feat(errors): 3-way transient/service/user classification + auto-retry-once on transient session-start

Error handling couldn't distinguish a transient hiccup from a real service error
— the retryable boolean conflated 'self-heals on retry' with 'you must change
something first', so a customer couldn't tell whether to retry or call their admin.

- error-classifier.ts: new ErrorClass axis (transient / service / user) on every
  classification. transient = infra/service hiccup a retry clears (ECS deploy-race,
  ENI/capacity delay, network blip, Bedrock throttle, concurrency cap); service =
  real platform/config fault an admin owns (bad token/scopes, model-not-enabled,
  blueprint misconfig); user = the request/code is the thing to change (build/test
  failed, guardrail, wrong PR, max-turns). retryGuidance() keys on errorClass and
  takes an autoRetried flag. New isTransientError() helper.
- orchestrate-task.ts: AUTO-RETRY-ONCE at session-start for transient failures —
  the one place a retry is idempotent by construction (no clone/commits/PR yet).
  Emits session_start_retry; stamps '[auto-retried]' so the surface says 'I tried
  again, still failed'. Mid-run crashes are NOT retried.

Backport note: the failure-reply.ts consumer hunk from the origin commit is
omitted — that module is part of the not-yet-merged #247 orchestration UX and
does not exist on main. The classifier axis + auto-retry stand alone.

(cherry picked from commit 63a12dc)

Author: isadeks

cdk/src/handlers/orchestrate-task.ts

@@ -20,6 +20,7 @@
 import { withDurableExecution, type DurableExecutionHandler } from '@aws/durable-execution-sdk-js';
 import { TaskStatus, TERMINAL_STATUSES } from '../constructs/task-status';
 import { resolveComputeStrategy } from './shared/compute-strategy';
+import { classifyError, isTransientError } from './shared/error-classifier';
 import { reportIssueFailure as reportJiraIssueFailure } from './shared/jira-feedback';
 import { reportIssueFailure } from './shared/linear-feedback';
 import { logger } from './shared/logger';
@@ -159,14 +160,42 @@ const durableHandler: DurableExecutionHandler<OrchestrateTaskEvent, void> = asyn
   // Step 4: Start agent session — resolve compute strategy, invoke runtime, transition to RUNNING
   // Returns the full SessionHandle (serializable) so ECS polling can use it in step 5.
   const sessionHandle = await context.step('start-session', async () => {
+    let autoRetried = false;
     try {
       const strategy = resolveComputeStrategy(blueprintConfig);
-      const handle = await strategy.startSession({
+      const startInput = {
         taskId,
         userId: task.user_id,
         payload,
         blueprintConfig,
-      });
+      };
+      // Transient-error AUTO-RETRY (once). session-start is the ONE place a retry
+      // is idempotent by construction — no repo clone, no commits, no PR have
+      // happened yet, so re-invoking RunTask/InvokeAgentRuntime can't double-run
+      // work. A transient hiccup here (ECS deploy-race "TaskDefinition is inactive",
+      // ENI/capacity delay, a Bedrock/agentcore throttle) usually clears on a second
+      // attempt — so we swallow the first transient failure and try once more before
+      // surfacing anything to the user. A NON-transient failure (bad config, missing
+      // ECS substrate) throws immediately — retrying it just wastes ~a minute. Mid-run
+      // crashes are NOT retried here (step 5); the agent may have pushed commits.
+      let handle;
+      try {
+        handle = await strategy.startSession(startInput);
+      } catch (firstErr) {
+        const classification = classifyError(`Session start failed: ${String(firstErr)}`);
+        if (!isTransientError(classification)) {
+          throw firstErr; // service/user error — a retry won't help; surface now.
+        }
+        autoRetried = true;
+        logger.warn('Session start hit a transient error — auto-retrying once', {
+          task_id: taskId,
+          error: firstErr instanceof Error ? firstErr.message : String(firstErr),
+        });
+        await emitTaskEvent(taskId, 'session_start_retry', {
+          reason: classification?.title ?? 'transient',
+        });
+        handle = await strategy.startSession(startInput);
+      }
 
       // Build compute metadata for the task record so cancel-task can stop the right backend
       const computeMetadata: Record<string, string> = handle.strategyType === 'ecs'
@@ -192,7 +221,12 @@ const durableHandler: DurableExecutionHandler<OrchestrateTaskEvent, void> = asyn
 
       return handle;
     } catch (err) {
-      await failTask(taskId, TaskStatus.HYDRATING, `Session start failed: ${String(err)}`, task.user_id, true, task.repo);
+      // Carry the auto-retry fact into error_message so the channel surface can say
+      // "I already tried again" (a bare marker the classifier ignores but
+      // renderFailureReply detects — see AUTO_RETRIED_MARKER). Only stamped when the
+      // single transient retry above also failed.
+      const retriedNote = autoRetried ? ' [auto-retried]' : '';
+      await failTask(taskId, TaskStatus.HYDRATING, `Session start failed: ${String(err)}${retriedNote}`, task.user_id, true, task.repo);
       throw err;
     }
   });