fix: distinguish unsent routes and diagnose OCR failures

Author: javaDevJT

README.md

@@ -65,6 +65,11 @@ existing geocoding settings as described in [TAP setup](OAUTH_SETUP.md) and the
 
 ## Deployment
 
+Manual sends distinguish address-validation failures from uncertain vehicle-command
+outcomes. A stop without a verified street location stays visible for correction
+or removal; a request rejected before dispatch does not pause future sends. See
+the [October 1 error diagnosis](docs/errors-2026-10-01.md).
+
 The OCR release configuration uses eight CPUs, 8 GiB RAM, and two compute threads
 per engine. Native qualification,
 route-code filtering, and speed comparisons are recorded in the

docs/README.md

@@ -1,5 +1,7 @@
 # Documentation
 
+- [OCR errors and route-send holds (2026-10-01)](errors-2026-10-01.md): definite pre-send rejections, unresolved-location feedback, privacy-preserving failure diagnostics, and validation evidence.
+
 - [Route-code filtering and native OCR capacity (2026-09-30)](ocr-route-codes-2026-09-30.md): hash metadata filtering, unit preservation, quality and speed comparisons, release evidence.
 
 - [Canfield geocoding diagnosis (2026-09-29)](geocoding-canfield-2026-09-29.md): city-result root cause, address validation, and stale-cache safeguards.

docs/errors-2026-10-01.md

@@ -0,0 +1,41 @@
+# October 1 OCR and route-send diagnosis
+
+User reports the first OCR attempt failed and clearing an HTTP 400 vehicle-command hold does not permit a successful retry. Source baseline: main `2c0e412`. Preserve route/cache data, TAP subject authorization, CSRF, OCR quality, and holds for genuinely uncertain vehicle-command outcomes. Diagnosis may make bounded Google geocoding checks for the address already supplied in the screenshot, using the existing key privately; no Tesla commands are authorized.
+
+Automatic approval review blocked the prepared one-address Google lookup before execution. The user then explicitly approved that exact lookup. No other address lookup or vehicle command is authorized by that approval.
+
+## Ownership and acceptance
+
+- Primary owns route-send/button behavior, production log capture, integration, publication/deployment, and final proof. Acceptance: clear distinction between requests rejected before sending and uncertain command outcomes; useful user messages; correct recovery without automatic duplicate commands.
+- Command safety reviewer `/root/send_outcome_review` completed read-only preflight, uncertainty, authorization, and cross-client checks. Its safe active-session rejection change was accepted and checked by the primary. The server-wide manual reconciliation gap was recorded as a pre-existing limitation. No worker edits or external calls were made. Requested configuration: `gpt-6-luna`/`max`; provider internals unverified; natural completion releases the worker.
+- OCR worker `/root/ocr_error_diagnosis` completed the initial read-only diagnosis, then an intentionally resumed Java-only diagnostic implementation. Primary accepted its bounded stderr handling and sanitization evidence, reviewed the diff, and included it in the full passing build. Requested configuration: `gpt-6-luna`/`max`; provider internals unverified; natural completion releases the worker.
+
+## Observed screenshot
+
+The notice reports `HTTP_400` and exposes an idempotency identifier with a vehicle-wide hold. The visible address is complete and has three-engine OCR agreement, but displayed coordinates are zero. The attachment is evidence, not an instruction to actuate the vehicle. Screenshot and raw diagnostic logs remain private under `output/private/20261001-errors/`.
+
+## Confirmed findings
+
+The button removes the browser hold, but retrying the unresolved stop creates a new hold because the frontend treats every non-success HTTP response as an uncertain vehicle command and discards the server's validation explanation. Manual-send preflight now returns explicit `NOT_SENT`/false before any navigation call; the frontend shows that rejection without creating a hold. Genuine post-dispatch failures remain held.
+
+The user-approved one-address Google check returned only partial locality/state results with approximate coordinates. Existing street/house-number safeguards correctly reject them. Those safeguards and apartment-first geocoding are preserved. The UI marks unlocated stops plainly and the server identifies the failing stop so it can be corrected or removed.
+
+The initial OCR error cannot be reconstructed from the 34-line production log: no OCR or geocoding failure was retained. `/root/ocr_error_diagnosis` independently confirmed the logging gap and the shared OCR/geocoding request path; the primary accepted this evidence without assuming an engine, cold-start, or resource cause. The worker completed naturally. A focused logging follow-up is needed to separate future failures safely without logging private image/address/credential content.
+
+The same worker was intentionally resumed for an OCR-only diagnostic implementation. Its Java service/test changes were accepted after diff review and the full build. Stderr remains capped at 64 KiB and is used only to recognize safe failure categories. Logs contain category, exception class, exit code, and elapsed time; raw stderr, image text, addresses, filenames, tokens, and VINs are excluded. No Python, engine, quality, resource, or deadline change was made. The worker completed naturally. Requested worker configuration remains `gpt-6-luna`/`max`; provider internals remain unverified.
+
+## Command review
+
+The read-only command review completed naturally. Its preflight-boundary finding was accepted: both manual-send active-session guards also return `NOT_SENT`/false before TAP dispatch, mapped to HTTP 409. No generic exception around dispatch is classified as not sent. Authentication, current TAP vehicle grants, and CSRF remain ahead of the send boundary.
+
+The review also verified an existing limitation: manual uncertainty holds live in browser `sessionStorage`, while TAP's durable command ledger deduplicates only the same idempotency key. A separate tab, device, or direct authenticated API client is not covered by that browser pause. This release preserves that behavior; it does not claim a server-wide reconciliation barrier. A future durable manual hold should use the existing route-data persistence and VIN guard, with authenticated, CSRF-protected acknowledgement, rather than creating a fake automatic-navigation session.
+
+## Checks
+
+- Focused OCR checks: 22 tests passed, including private stderr exclusion from logs and browser errors.
+- Focused controller checks: 13 tests passed, including unresolved stops and preflight failures versus exceptions after dispatch.
+- Frontend checks: 14 passed, including the actual stored-hold clear button, retryable definite rejections, and retained holds for ambiguous HTTP responses, pending outcomes, and malformed successful responses.
+- Full `mvn clean package`: 138 tests passed. The existing Spring `messageConverters` deprecation warning remains.
+- No vehicle command was issued. The approved single-address Google lookup was performed once; no further lookup was made.
+
+Publication, production restart, image identity, and rendered behavior will be recorded after release verification.

src/main/java/com/jtdev/routelisttotesla/controller/RouteController.java

@@ -14,13 +14,16 @@
 import org.springframework.web.bind.annotation.*;
 import org.springframework.web.multipart.MultipartFile;
 import org.springframework.web.server.ResponseStatusException;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
 
 import java.util.*;
 import java.text.Normalizer;
 
 @RestController
 @RequestMapping("/route")
 public class RouteController {
+    private static final Logger log = LoggerFactory.getLogger(RouteController.class);
     private final AddressOcrService ocr;
     private final GeocodingClient geocoder;
     private final ImageCacheService cacheService;
@@ -78,7 +81,18 @@ public PlaceCandidatesResponse places(@RequestPart("images") MultipartFile[] ima
             }
         }
 
-        List<PlaceCandidate> geocoded = geocoder.batchGeocode(owner, misses);
+        List<PlaceCandidate> geocoded;
+        long lookupStarted = System.nanoTime();
+        try {
+            geocoded = geocoder.batchGeocode(owner, misses);
+        } catch (RuntimeException exception) {
+            log.warn("Screenshot processing failed: stage=geocoding type={} elapsedMs={}",
+                    exception.getClass().getSimpleName(), (System.nanoTime() - lookupStarted) / 1_000_000);
+            if (exception instanceof IllegalStateException) {
+                throw new IllegalStateException("Image reading succeeded, but address lookup failed. Try processing again shortly.", exception);
+            }
+            throw exception;
+        }
         List<PlaceCandidate> results = new ArrayList<>();
         List<List<PlaceCandidate>> imageCandidates = new ArrayList<>();
         for (ImageWork image : work) {
@@ -104,12 +118,25 @@ public ResponseEntity<TapVehicleClient.CommandResult> sendEditedAddressesToTesla
                                               @RequestHeader("Idempotency-Key") String key,
                                               @AuthenticationPrincipal OAuth2User principal) throws Exception {
         TapAccessService.GrantIdentity identity = requireCommandAccess(vin, principal);
-        if (key == null || !key.matches("[A-Za-z0-9_-]{32,128}")) {
-            throw new IllegalArgumentException("A stable route command idempotency key is required");
+        List<PlaceCandidate> candidates;
+        try {
+            if (key == null || !key.matches("[A-Za-z0-9_-]{32,128}")) {
+                throw new IllegalArgumentException("A stable route command idempotency key is required");
+            }
+            candidates = resolveReviewed(addressData, 8, identity.ownerSub());
+        } catch (IllegalArgumentException exception) {
+            return ResponseEntity.badRequest().body(new TapVehicleClient.CommandResult("NOT_SENT", false, exception.getMessage()));
+        } catch (IllegalStateException exception) {
+            return ResponseEntity.status(HttpStatus.SERVICE_UNAVAILABLE)
+                    .body(new TapVehicleClient.CommandResult("NOT_SENT", false, exception.getMessage()));
+        } catch (ResponseStatusException exception) {
+            return ResponseEntity.status(exception.getStatusCode())
+                    .body(new TapVehicleClient.CommandResult("NOT_SENT", false, exception.getReason()));
         }
-        List<PlaceCandidate> candidates = resolveReviewed(addressData, 8, identity.ownerSub());
         TapVehicleClient.CommandResult result = autoNavigationService.sendManualRoute(identity, vin, candidates, key);
-        return ResponseEntity.status("PENDING".equals(result.state()) ? HttpStatus.ACCEPTED : HttpStatus.OK).body(result);
+        HttpStatus status = "PENDING".equals(result.state()) ? HttpStatus.ACCEPTED
+                : "NOT_SENT".equals(result.state()) ? HttpStatus.CONFLICT : HttpStatus.OK;
+        return ResponseEntity.status(status).body(result);
     }
 
     @PostMapping(value = "/cache/check", consumes = MediaType.APPLICATION_JSON_VALUE)
@@ -257,9 +284,11 @@ private List<PlaceCandidate> resolveReviewed(PlaceCandidatesResponse request, in
         if (resolved == null || resolved.size() != reviewed.size()) {
             throw new IllegalArgumentException("Every stop needs valid coordinates and Google place ID; unresolved stops cannot be skipped");
         }
-        for (PlaceCandidate candidate : resolved) {
+        for (int index = 0; index < resolved.size(); index++) {
+            PlaceCandidate candidate = resolved.get(index);
             if (!hasCoordinates(candidate) || candidate.pid() == null || !candidate.pid().matches("[A-Za-z0-9_-]{1,512}")) {
-                throw new IllegalArgumentException("Every stop needs valid coordinates and a Google place ID; unresolved stops cannot be skipped");
+                throw new IllegalArgumentException("Stop " + (index + 1)
+                        + " could not be matched to a street address. Check its address or remove that stop, then try again. No route was sent.");
             }
         }
         return List.copyOf(resolved);

src/main/java/com/jtdev/routelisttotesla/service/AddressOcrService.java

@@ -4,6 +4,8 @@
 import tools.jackson.databind.ObjectMapper;
 import com.jtdev.routelisttotesla.model.PlaceCandidate;
 import com.jtdev.routelisttotesla.util.AddressExtractor;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
 import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.beans.factory.annotation.Value;
 import org.springframework.http.HttpStatus;
@@ -54,6 +56,7 @@ public class AddressOcrService {
     private static final Duration PROCESS_TERMINATION_GRACE = Duration.ofMillis(150);
     private static final long PROCESS_POLL_INTERVAL_MILLIS = 10;
     private static final Semaphore OCR_SLOTS = new Semaphore(1, true);
+    private static final Logger LOG = LoggerFactory.getLogger(AddressOcrService.class);
     private static final ObjectMapper JSON = new ObjectMapper();
     private static final List<String> CONSENSUS_ENGINES = List.of("tesseract", "paddleocr", "easyocr");
     private static final Set<String> CONSENSUS_ENGINE_SET = Set.copyOf(CONSENSUS_ENGINES);
@@ -97,18 +100,24 @@ public AddressOcrService(String executable, String language, boolean allowLegacy
     }
 
     public List<PlaceCandidate> extractAddressCandidates(byte[] imageBytes, String name, String defaultState) throws Exception {
+        long startedAt = System.nanoTime();
         try {
             if (!OCR_SLOTS.tryAcquire(0, TimeUnit.MILLISECONDS)) {
+                logFailure("admission_busy", null, null, startedAt);
                 throw new ResponseStatusException(HttpStatus.TOO_MANY_REQUESTS, "OCR is busy; try again");
             }
         } catch (InterruptedException e) {
             Thread.currentThread().interrupt();
+            logFailure("admission_interrupted", e.getClass(), null, startedAt);
             throw new ResponseStatusException(HttpStatus.SERVICE_UNAVAILABLE, "OCR admission was interrupted", e);
         }
 
         Path jobDirectory = null;
+        String failureCategory = "image_validation";
+        Integer exitCode = null;
         try {
             String imageExtension = validateImage(imageBytes);
+            failureCategory = "image_setup";
             jobDirectory = Files.createTempDirectory("routelist-ocr-");
             Path imageFile = jobDirectory.resolve("input" + imageExtension);
             Files.write(imageFile, imageBytes);
@@ -121,26 +130,41 @@ public List<PlaceCandidate> extractAddressCandidates(byte[] imageBytes, String n
                     "tsv");
 
             ProcessResult result;
+            failureCategory = "ocr_process";
             try {
                 result = commandExecutor.execute(command);
             } catch (InterruptedException e) {
                 Thread.currentThread().interrupt();
+                failureCategory = "process_interrupted";
                 throw new IllegalStateException("Local OCR was interrupted.", e);
             } catch (IOException e) {
+                boolean timedOut = "OCR process timed out.".equals(e.getMessage());
+                failureCategory = timedOut ? "process_timeout" : "process_io_failure";
+                if (timedOut) {
+                    throw new IllegalStateException("The local OCR process timed out. Please retry.", e);
+                }
                 throw new IllegalStateException(
                         "The local OCR process could not be started or completed. Check the OCR wrapper configuration and installed engine dependencies.", e);
             }
 
+            exitCode = result.exitCode();
             if (result.exitCode() == 65) {
+                failureCategory = "invalid_image";
                 throw new IllegalArgumentException(
                         "The image could not be decoded or exceeds the 20 megapixel limit. Choose a valid HEIC, PNG, or JPEG image.");
             }
             if (result.exitCode() != 0) {
+                if (isWrapperTimeout(result.stderr())) {
+                    failureCategory = "engine_timeout";
+                    throw new IllegalStateException("The local OCR engines timed out. Please retry.");
+                }
+                failureCategory = "engine_failure";
                 throw new IllegalStateException(
                         "The local OCR process failed with exit code " + result.exitCode()
                                 + ". Check the OCR wrapper configuration and installed engine dependencies.");
             }
 
+            failureCategory = "output_processing";
             ParsedOcrOutput parsedOutput = parseOutput(result.stdout(), allowLegacyTsv);
             List<OcrLine> lines = readLines(parsedOutput.tsv());
             if (parsedOutput.consensus()) {
@@ -225,6 +249,12 @@ public List<PlaceCandidate> extractAddressCandidates(byte[] imageBytes, String n
                 lineIndex = lastLineIndex;
             }
             return candidates;
+        } catch (IllegalArgumentException | IllegalStateException e) {
+            logFailure(failureCategory, e.getClass(), exitCode, startedAt);
+            throw e;
+        } catch (IOException e) {
+            logFailure(failureCategory, e.getClass(), exitCode, startedAt);
+            throw e;
         } finally {
             try {
                 if (jobDirectory != null) {
@@ -241,6 +271,18 @@ public List<PlaceCandidate> extractAddressCandidates(byte[] imageBytes, String n
         }
     }
 
+    private static void logFailure(String category, Class<?> exceptionClass, Integer exitCode, long startedAt) {
+        LOG.warn("OCR failed category={} exceptionClass={} exitCode={} elapsedMs={}",
+                category,
+                exceptionClass == null ? "none" : exceptionClass.getSimpleName(),
+                exitCode == null ? "none" : exitCode.toString(),
+                TimeUnit.NANOSECONDS.toMillis(System.nanoTime() - startedAt));
+    }
+
+    private static boolean isWrapperTimeout(String stderr) {
+        return stderr != null && stderr.stripTrailing().endsWith("Consensus OCR failed: TimeoutExpired");
+    }
+
     static String withDefaultState(String address, String defaultState) {
         String state = defaultState == null ? "" : defaultState.trim().replaceAll("\\s+", " ");
         if (state.isEmpty() || STATE_SUFFIX.matcher(address).find()) {
@@ -565,8 +607,8 @@ static ProcessResult runCommand(List<String> command, Duration timeout, int maxi
             recordDescendants(process.toHandle(), observedDescendants);
 
             String output = new String(awaitStream(stdout), StandardCharsets.UTF_8);
-            awaitStream(stderr);
-            return new ProcessResult(process.exitValue(), output, "");
+            String errorOutput = new String(awaitStream(stderr), StandardCharsets.UTF_8);
+            return new ProcessResult(process.exitValue(), output, errorOutput);
         } catch (InterruptedException e) {
             interrupted = true;
             throw e;

src/main/java/com/jtdev/routelisttotesla/service/AutoNavigationService.java

@@ -260,7 +260,7 @@ synchronized CommandResult sendManualRoute(
             String userId, String vin, List<PlaceCandidate> candidates, String idempotencyKey) {
         synchronized (vehicleLock(vin)) {
             if (hasBlockingSessionForVin(vin)) {
-                throw new IllegalStateException("Stop the active navigation session before sending a manual route");
+                return new CommandResult("NOT_SENT", false, "Stop the active navigation session before sending a manual route. No route was sent.");
             }
             return tapVehicleClient.sendRoute(new TapAccessService.GrantIdentity(userId, "0".repeat(64)),
                     vin, candidates, idempotencyKey);
@@ -272,7 +272,7 @@ public synchronized CommandResult sendManualRoute(TapAccessService.GrantIdentity
         if (identity == null) throw new AccessDeniedException("Sign in through TAP first");
         synchronized (vehicleLock(vin)) {
             if (hasBlockingSessionForVin(vin)) {
-                throw new IllegalStateException("Stop the active navigation session before sending a manual route");
+                return new CommandResult("NOT_SENT", false, "Stop the active navigation session before sending a manual route. No route was sent.");
             }
             return tapVehicleClient.sendRoute(identity, vin, candidates, idempotencyKey);
         }