fix(#247): classify the claude Exec-format/broken-shim failure with retry guidance (ABCA-659)

When the agent image's claude CLI can't be exec'd (OSError Exec format error, or
the shim's own 'claude native binary not installed'), the classifier had no
matching pattern and fell through to the bare 'Unexpected error' with a generic
'report it' remedy — the exact no-guidance anti-pattern the error-feedback arc
(K5 buckets, remedy+retryable+errorClass) was built to eliminate. Live-caught on
ABCA-659's retry: the ❌ Linear comment just said 'Unexpected error', telling the
user nothing about whether to retry or escalate.

Add a COMPUTE + transient pattern so the failure reads honestly and actionably:
'Couldn't start the coding agent (environment issue) … not a problem with your
request … reply here to try again; if every attempt fails the same way, the
agent image needs a rebuild — contact your ABCA admin with the task id.' The
transient class also lets the platform's session-start auto-retry take a shot.
Matched before the AGENT/UNKNOWN fallthrough; two tests pin the copy + axis.

Author: isadeks

cdk/src/handlers/shared/error-classifier.ts

@@ -255,6 +255,30 @@ const PATTERNS: readonly ErrorPattern[] = [
       errorClass: ErrorClass.TRANSIENT,
     },
   },
+  {
+    // The `claude` CLI on the agent image couldn't be exec'd: either the OS
+    // refused the binary (`OSError: [Errno 8] Exec format error: 'claude'`) or
+    // the claude-code shim reports its platform-native binary was never placed
+    // ("claude native binary not installed" — its postinstall silently fell
+    // back at image-build time). Live-caught on ABCA-659's retry: all 3 ECS runs
+    // died at the run_agent step this way on a freshly rebuilt image, while the
+    // native binary was present but unwired. This is an IMAGE/infra fault, NOT a
+    // problem with the user's request — a fresh attempt usually lands on a host
+    // that materializes the image cleanly; a persistent one is a bad build an
+    // admin must rebuild. Without this bucket it fell through to a bare
+    // "Unexpected error" with no guidance (the anti-pattern the error-feedback
+    // work set out to kill). Matched before AGENT/UNKNOWN so the precise,
+    // retry-oriented copy wins.
+    pattern: /Exec format error.*claude|claude.*Exec format error|claude native binary not installed/i,
+    classification: {
+      category: ErrorCategory.COMPUTE,
+      title: 'Couldn\'t start the coding agent (environment issue)',
+      description: 'The agent runtime couldn\'t launch the `claude` CLI on the compute image — an infrastructure/image problem, not a problem with your request or code.',
+      remedy: 'This is usually a transient image/compute hiccup. Reply here to try again — a fresh attempt typically clears it. If every attempt fails the same way, the agent image needs a rebuild: contact your ABCA admin with the task id above.',
+      retryable: true,
+      errorClass: ErrorClass.TRANSIENT,
+    },
+  },
 
   // --- Agent ---
   {

cdk/test/handlers/shared/error-classifier.test.ts

@@ -157,6 +157,27 @@ describe('classifyError', () => {
       expect(result!.retryable).toBe(true);
     });
 
+    test('classifies claude Exec-format / broken-shim as a transient image issue (ABCA-659, not "Unexpected error")', () => {
+      // The raw run_agent failure the broken agent image produced.
+      const result = classifyError(
+        "Workflow run_agent step failed: OSError: [Errno 8] Exec format error: 'claude'",
+      );
+      expect(result!.category).toBe(ErrorCategory.COMPUTE);
+      expect(result!.title).toBe('Couldn\'t start the coding agent (environment issue)');
+      expect(result!.retryable).toBe(true);
+      // MUST be transient so retryGuidance tells the user to just reply-to-retry
+      // (and escalate to an admin only if it persists) — not the bare
+      // "Unexpected error" with no guidance it used to fall through to.
+      expect(result!.errorClass).toBe(ErrorClass.TRANSIENT);
+      expect(result!.remedy).toMatch(/try again|rebuild|admin/i);
+    });
+
+    test('classifies the claude shim self-report ("native binary not installed")', () => {
+      const result = classifyError('Error: claude native binary not installed.');
+      expect(result!.category).toBe(ErrorCategory.COMPUTE);
+      expect(result!.errorClass).toBe(ErrorClass.TRANSIENT);
+    });
+
     test('classifies ECS exit without terminal status', () => {
       const result = classifyError(
         'ECS task exited successfully but agent never wrote terminal status after 5 polls',