feat(subagent): mark recoverable failures continuable in wait output

Author: TheGreatAxios

src/inference-error-message.ts

@@ -68,6 +68,31 @@ export function classifyInferenceErrorCategory(
     : error.category;
 }
 
+/**
+ * Whether a normalized provider-failure category is transient enough that a
+ * parent may spawn one successor with the same brief (CL-8978). Allowlist:
+ * retryable/timeout — including 429 overload, which normalizes to retryable.
+ * Fatal categories win explicitly: credential, quota, and context-overflow
+ * failures must never read as continuable.
+ */
+const FATAL_PROVIDER_FAILURE_CATEGORIES: ReadonlySet<string> = new Set([
+  "credential_failure",
+  "quota_exhausted",
+  "context_overflow",
+]);
+
+const RECOVERABLE_PROVIDER_FAILURE_CATEGORIES: ReadonlySet<string> = new Set([
+  "retryable",
+  "timeout",
+]);
+
+export function isRecoverableProviderFailureCategory(
+  category: string,
+): boolean {
+  if (FATAL_PROVIDER_FAILURE_CATEGORIES.has(category)) return false;
+  return RECOVERABLE_PROVIDER_FAILURE_CATEGORIES.has(category);
+}
+
 function codexUsageLimitLine(error: InferenceErrorLike): string | undefined {
   // Match normalizeCodexUsageLimitError: never brand a known non-Codex source.
   if (

src/subagent/agent-fleet.ts

@@ -107,7 +107,10 @@ import {
 } from "./authority.js";
 
 import { formatSubAgentSpawnAuthFailureMessage } from "./inference-auth-failure.js";
-import { isResolvedProviderFailureError } from "../inference-error-message.js";
+import {
+  isRecoverableProviderFailureCategory,
+  isResolvedProviderFailureError,
+} from "../inference-error-message.js";
 import { errorMessage } from "../agent/error-message.js";
 import { isSubAgentCancelError } from "./dispose.js";
 import {
@@ -125,6 +128,8 @@ interface FleetRecord {
   error?: string;
   stopReason?: string;
   providerFailure?: true;
+  /** CL-8978: transient provider failure — the parent may spawn one successor. */
+  recoverableFailure?: true;
   /** Set once a wait_agents caller has been handed this result. */
   collected?: boolean;
   /** Set once a waiter or occupancy take handed report/error. */
@@ -158,6 +163,8 @@ interface FleetOverlay {
   tombstoned?: boolean;
   hint?: string;
   providerFailure?: true;
+  /** CL-8978: transient provider failure — the parent may spawn one successor. */
+  recoverableFailure?: true;
 }
 
 const RECOVERY_HINT =
@@ -265,6 +272,17 @@ class FleetMailbox {
     existing.providerFailure = true;
   }
 
+  /**
+   * CL-8978: stamp a transient (retryable/timeout/overload) provider failure
+   * alongside sessions.fail. Survives session eviction like providerFailure —
+   * snapshot projects it even once the payload is tombstoned.
+   */
+  markRecoverable(id: string): void {
+    const existing = this.records.get(id);
+    if (existing === undefined) return;
+    existing.recoverableFailure = true;
+  }
+
   markQueued(id: string): void {
     const existing = this.records.get(id);
     if (existing === undefined || existing.collected === true) return;
@@ -462,6 +480,9 @@ class FleetMailbox {
         : {}),
       ...(stopReason !== undefined ? { stopReason } : {}),
       ...(overlay.providerFailure === true ? { providerFailure: true } : {}),
+      ...(overlay.recoverableFailure === true
+        ? { recoverableFailure: true }
+        : {}),
       ...(ask !== undefined
         ? { question: ask.question, questionId: ask.questionId }
         : {}),
@@ -600,7 +621,10 @@ export const waitAgentsToolDefinition: ToolDefinition = {
     `slot), "running", and "awaiting_director". interrupt_agent unblocks this wait immediately with ` +
     `status "interrupted" (a parent-initiated pause — resume_agent, do not spawn_agent a successor against the still-live worker). ` +
     `close_agent also unblocks with status "interrupted" but is permanent. Terminal JSON includes stop_reason when the session recorded one ` +
-    `(interrupted, cancelled, incomplete-report, and similar). awaiting_director is not terminal: re-wait while still pending re-delivers the same question. ` +
+    `(interrupted, cancelled, incomplete-report, and similar). A "failed" entry with "continuable": true is a recoverable transient ` +
+    `provider failure (retryable/timeout/overload) — terminal, not a timeout and not a stall: do not re-wait it, and you may spawn at most ` +
+    `one successor with the same brief. "failed" without the marker (auth, quota, context-overflow, or other errors) is not continuable — ` +
+    `do not respawn it. awaiting_director is not terminal: re-wait while still pending re-delivers the same question. ` +
     `Answer with send_input (soft). Do not call this in a tight zero-progress loop: a timeout means the targets are still ` +
     `queued, running, or awaiting a director answer, not "try again right away" — do other work, reply to the operator, or change the brief. Calling again with the ` +
     `same targets is a real timed wait, not a spin, but wastes turns if nothing has changed. ` +
@@ -1530,6 +1554,17 @@ export function createSpawnAgentTool(deps: AgentFleetDeps): AgentTool {
               if (isProviderFailure || providerFailureObserved) {
                 deps.fleetRecords.markProviderFailure(session.id);
               }
+              // CL-8978: a classified transient failure stays wait-terminal
+              // failed, but carries a continuable marker so the parent can
+              // spawn one successor instead of stalling on the failure.
+              // Fatal categories (credential/quota/context-overflow) and
+              // unclassified throws never mark — no auto-retry is added here.
+              if (
+                isResolvedProviderFailureError(err) &&
+                isRecoverableProviderFailureCategory(err.category)
+              ) {
+                deps.fleetRecords.markRecoverable(session.id);
+              }
               deps.sessions.fail(session.id, failReason);
             })
             .finally(() => {

src/subagent/fleet-dry-drive.ts

@@ -34,6 +34,8 @@ export interface FleetDryMailboxRecord {
   readonly description?: string;
   readonly hint?: string;
   readonly providerFailure?: true;
+  /** CL-8978: transient provider failure — the parent may spawn one successor. */
+  readonly recoverableFailure?: true;
   readonly stopReason?: string;
 }
 
@@ -58,9 +60,25 @@ export interface CollectedWorkerReport {
   error?: string;
   hint?: string;
   provider_failure?: true;
+  /**
+   * CL-8978: failed entries from a transient provider failure carry this
+   * marker plus single-successor guidance in continue_with. Capped affordance:
+   * at most one respawn with the same brief, never a retry loop.
+   */
+  continuable?: true;
+  continue_with?: string;
   stop_reason?: string;
 }
 
+/**
+ * Single-successor guidance for a failed+continuable entry. The marker is
+ * advisory only — no runtime auto-retry backs it.
+ */
+export const RECOVERABLE_FAILURE_CONTINUE_GUIDANCE =
+  "This worker failed with a transient provider error (retryable/timeout/overload) " +
+  "and is terminal — do not re-wait it. You may spawn at most one successor with " +
+  "the same brief; do not retry in a loop.";
+
 export function shouldDriveOpenTasks(input: {
   previousRunning?: number | undefined;
   running?: number | undefined;
@@ -169,6 +187,12 @@ export function projectMailboxRecord(
     ...(error !== undefined ? { error } : {}),
     ...(taken.hint !== undefined ? { hint: taken.hint } : {}),
     ...(taken.providerFailure === true ? { provider_failure: true } : {}),
+    ...(taken.status === "failed" && taken.recoverableFailure === true
+      ? {
+          continuable: true as const,
+          continue_with: RECOVERABLE_FAILURE_CONTINUE_GUIDANCE,
+        }
+      : {}),
     ...(taken.stopReason !== undefined
       ? { stop_reason: taken.stopReason }
       : {}),

src/subagent/run-recoverable-failure.test.ts

@@ -161,7 +161,11 @@ describe("CL-8978 recoverable subagent failure", () => {
     // The parent handle still works: spawn and wait a successor.
     const deps2 = makeDeps(async () => ({ report: "successor done" }));
     // Share the fleet so the successor is a true sibling lane.
-    const spawn2 = createSpawnAgentTool({ ...deps2, sessions: deps.sessions, fleetRecords: deps.fleetRecords });
+    const spawn2 = createSpawnAgentTool({
+      ...deps2,
+      sessions: deps.sessions,
+      fleetRecords: deps.fleetRecords,
+    });
     const wait2 = createWaitAgentsTool({
       sessions: deps.sessions,
       fleetRecords: deps.fleetRecords,
@@ -255,6 +259,53 @@ describe("CL-8978 recoverable subagent failure", () => {
     expect(await drive()).toBe(true);
     expect(prompts).toHaveLength(2);
     expect(deps.fleetRecords.peek(id)?.collected).toBe(true);
+    // The mailbox path carries the same continuable marker as wait_agents.
+    expect(prompts[1]).toContain('"continuable":true');
+  });
+
+  test("in-flight work stays live until settled: a timeout is liveness, not failure", async () => {
+    let resolveRun!: (v: RunSubAgentResult) => void;
+    const gate = new Promise<RunSubAgentResult>((res) => {
+      resolveRun = res;
+    });
+    const deps = makeDeps(() => gate);
+    const spawn = createSpawnAgentTool(deps);
+    const wait = createWaitAgentsTool({
+      sessions: deps.sessions,
+      fleetRecords: deps.fleetRecords,
+    });
+
+    const spawned = await callTool(spawn, {
+      description: "slow job",
+      prompt: "do it",
+      intent: "explore",
+    });
+    const id = spawned.agent_id as string;
+
+    // Unsettled work (including an in-flight provider retry) projects live.
+    const snap = deps.fleetRecords.peek(id);
+    expect(snap?.status).toBe("running");
+    expect(isLiveWaitStatus(snap?.status ?? "failed")).toBe(true);
+
+    const waited = await callTool(wait, {
+      targets: [id],
+      timeout_ms: 50,
+      mode: "all",
+    });
+    expect(waited.timed_out).toBe(true);
+    const results = waited.results as Record<string, unknown>[];
+    expect(results[0]?.status).toBe("running");
+    expect(results[0]?.continuable).toBeUndefined();
+
+    resolveRun({ report: "slow done" });
+    const waited2 = await callTool(wait, {
+      targets: [id],
+      timeout_ms: 5000,
+      mode: "all",
+    });
+    expect(waited2.timed_out).toBe(false);
+    const results2 = waited2.results as Record<string, unknown>[];
+    expect(results2[0]?.status).toBe("done");
   });
 
   test("wait_agents documents the continuable failed marker", () => {