pi-long-task 0.5.0 → 0.7.0

package/src/coordinator.ts

@@ -10,6 +10,18 @@ import type {
 } from "./types.ts";
 import { commitAfterSession, gitDirtyPaths, shouldCommitOutcome, type CommitAfterSessionResult } from "./git.ts";
 import { formatCoordinatorResultMessage } from "./render.ts";
+import { classifyNetworkFailure } from "./network_failure.ts";
+import {
+  formatNetworkRecoveryStatus,
+  recoverNetworkOperation,
+  type NetworkRecoveryEvent,
+  type NetworkRecoveryEventType,
+} from "./network_recovery.ts";
+import {
+  DEFAULT_NETWORK_RECOVERY_CONFIG,
+  resolveNetworkRecoveryConfig,
+  type NetworkRecoveryConfig,
+} from "./network_recovery_config.ts";
 import { extractResultSummary, hasCompleteTaskResult } from "./result_writer.ts";
 import { runGuardedSessionPrompt } from "./session_guard.ts";
 import {
@@ -20,6 +32,24 @@ import {
   type PlanRevisionRelevantResult,
 } from "./plan_revision_generation.ts";
 import { taskSemanticFingerprint, type PlanTaskState } from "./plan_revision.ts";
+import {
+  DEFAULT_PLANNER_THINKING_LEVEL,
+  DEFAULT_PLANNER_TIMEOUT_MS,
+  resolvePlannerBudget,
+  resolvePlannerGracefulShutdownMs,
+  resolvePlannerTimeoutMs,
+  type PlannerBudget,
+} from "./planner_config.ts";
+import {
+  createPlannerActiveProgress,
+  createPlannerGraceProgress,
+  createPlannerStartedProgress,
+  formatFriendlyDuration,
+  plannerProgressCheckpoints,
+  type PlannerProgressEvent,
+  type PlannerProgressHandler,
+  type PlannerProgressState,
+} from "./planner_progress.ts";
 import {
   PersistentTodoPlanStore,
   planTaskReference,
@@ -41,6 +71,7 @@ import {
 import { buildTaskProgressModel, type TaskProgressModel, type TaskProgressStatus } from "./task_progress.ts";
 import {
   applyGoalInstructionsToTodoMarkdown,
+  applyWorkerCapabilityConstraintsToTodoMarkdown,
   buildTodoCreationPrompt,
   buildTodoRepairPrompt,
   extractAndValidateTodoMarkdown,
@@ -49,6 +80,7 @@ import {
   validateTodoMarkdown,
 } from "./todo_generator.ts";
 import { parseTasks, todoGlobalInstructions, type Task } from "./todo_parser.ts";
+import { detectUnavailableWorkerCapabilities, type WorkerCapabilityWarning } from "./worker_capabilities.ts";
 import {
   buildWorkerSessionCreationFailureOutcome,
   createIsolatedWorkerSession,
@@ -72,36 +104,55 @@ export type { CoordinatorStatus } from "./types.ts";
 export const DEFAULT_COORDINATOR_OPTIONS = {
   maxAttemptsPerTask: 3,
   taskTimeoutMs: 900_000,
-  todoTimeoutMs: 300_000,
+  todoTimeoutMs: DEFAULT_PLANNER_TIMEOUT_MS,
   todoGracefulShutdownMs: 15_000,
   maxBashTimeoutMs: 300_000,
   taskThinking: "high",
-  todoThinking: "xhigh",
+  todoThinking: DEFAULT_PLANNER_THINKING_LEVEL,
   workerSessionReuse: DEFAULT_WORKER_SESSION_REUSE_ENABLED,
   workerSessionReuseContextThresholdPercent: DEFAULT_WORKER_SESSION_REUSE_CONTEXT_THRESHOLD_PERCENT,
+  networkRecovery: DEFAULT_NETWORK_RECOVERY_CONFIG,
 } as const;
 
 export type WorkerRunner = (options: RunWorkerTaskOptions) => Promise<SessionOutcome>;
 export type CoordinatorProgressPhase =
+  | "capability_warning"
   | "planning"
   | "planned"
   | "task_start"
   | "worker_session"
   | "worker_tool"
+  | "network_wait"
   | "task_done"
   | "task_blocked"
   | "task_failed"
   | "task_obsolete"
   | "complete";
 
-export type PlannerDiagnosticKind = "timeout" | "abort" | "invalid_output" | "repair_attempt" | "failure";
+export type PlannerDiagnosticKind =
+  | "timeout"
+  | "cancelled"
+  /** @deprecated Planner cancellation is now reported as `cancelled`. */
+  | "abort"
+  | "network_recovery"
+  | "network_failure"
+  | "invalid_output"
+  | "repair_attempt"
+  | "failure";
 
 export interface PlannerDiagnostic {
   kind: PlannerDiagnosticKind;
   message: string;
+  /** Present whenever output presence is known; partial content itself is deliberately omitted. */
+  partialOutputObserved?: boolean;
   diagnostics?: string[];
   sessionFile?: string;
   sessionId?: string;
+  /** Network lifecycle data is separate from timeout/cancellation classification. */
+  networkRecoveryEvent?: NetworkRecoveryEventType;
+  networkFailureReason?: string;
+  networkRetryCount?: number;
+  networkOutageElapsedMs?: number;
 }
 
 export type PlannerDiagnosticHandler = (diagnostic: PlannerDiagnostic) => void;
@@ -144,12 +195,32 @@ export interface CoordinatorProgressUpdate {
   taskProgress?: TaskProgressModel;
   plannerDiagnostic?: PlannerDiagnosticKind;
   plannerDiagnostics?: string[];
+  plannerPartialOutputObserved?: boolean;
   plannerSessionFile?: string;
   plannerSessionId?: string;
+  /** Deterministic deadline selection used by planner calls in this run. */
+  plannerBudget?: Readonly<PlannerBudget>;
+  /** Human-facing state with exact millisecond values retained for integrations. */
+  plannerProgressState?: PlannerProgressState;
+  plannerElapsedMs?: number;
+  plannerRemainingMs?: number;
+  plannerGracePeriodMs?: number;
+  plannerGraceRemainingMs?: number;
+  capabilityWarning?: Readonly<WorkerCapabilityWarning>;
   workerSessionEvent?: WorkerSessionDiagnostic["event"];
   workerSessionReason?: string;
   workerSessionContextUsagePercent?: number;
   workerSessionContextThresholdPercent?: number;
+  networkRecoveryEvent?: NetworkRecoveryEventType;
+  networkRetryCount?: number;
+  networkOutageElapsedMs?: number;
+  networkNextRetryAtMs?: number;
+  networkNextRetryInMs?: number;
+  networkFailureReason?: string;
+  /** Identifies whether recovery belongs to planning or worker execution. */
+  networkOperation?: "planner" | "worker";
+  /** Planner recovery never mutates the configured per-attempt deadline. */
+  plannerDeadlinePolicy?: "per_attempt_excludes_network_wait";
 }
 
 export type CoordinatorProgressHandler = (update: CoordinatorProgressUpdate) => void;
@@ -182,24 +253,39 @@ export interface RunCoordinatorOptions extends PiLongTaskInput {
   steeringQueue?: SerializedSteeringQueue;
   /** Runs after rebase/validation and immediately before the revision is atomically persisted. */
   onPlanRevisionAccepted?: (revision: GeneratedPlanRevision) => void | Promise<void>;
+  /** Receives coordinator-level outage lifecycle events for parent orchestrators and status integrations. */
+  onNetworkRecovery?: (event: NetworkRecoveryEvent) => void;
 }
 
 export interface TodoPlannerOptions {
   inputText: string;
   cwd: string;
   runDir: string;
-  thinkingLevel: string;
+  /** Defaults to the planner-only balanced level; explicit values are forwarded unchanged. */
+  thinkingLevel?: string;
   model?: unknown;
   abortSignal?: AbortSignal;
   timeoutMs?: number;
   gracefulShutdownMs?: number;
+  /** Structured record of explicit/default/adaptive deadline selection. */
+  plannerBudget?: Readonly<PlannerBudget>;
   sessionFactory?: WorkerSessionFactory;
   onDiagnostic?: PlannerDiagnosticHandler;
+  /** Shared human-readable timing events for CLI, TUI, and headless integrations. */
+  onProgress?: PlannerProgressHandler;
   goal?: string;
   /** Exact prompt for revision planners; bypasses the initial TODO-creation wrapper. */
   plannerPrompt?: string;
   /** Structured revision context supplied alongside plannerPrompt. */
   planRevision?: Readonly<PlanRevisionRequest>;
+  /**
+   * Normalized coordinator recovery policy. Recovery wait is accounted on its
+   * own outage clock; every replay receives the same configured per-attempt
+   * planner deadline, so recovery settings never replace that deadline.
+   */
+  networkRecovery?: Readonly<NetworkRecoveryConfig>;
+  /** Run-level constraints derived from capabilities unavailable to isolated workers. */
+  capabilityConstraints?: readonly string[];
 }
 
 export interface TaskAttemptSummary {
@@ -252,6 +338,10 @@ export interface CoordinatorResult {
   workerUsageTotal?: WorkerUsageTotals;
   /** Additive lifecycle counters for adaptive worker-session reuse. */
   workerSessionMetrics?: WorkerSessionMetrics;
+  /** Deterministic deadline selection used by planner calls in this run. */
+  plannerBudget?: Readonly<PlannerBudget>;
+  /** Explicit, non-fatal warnings for requested capabilities unavailable to isolated workers. */
+  capabilityWarnings?: readonly WorkerCapabilityWarning[];
   commit: boolean;
   goal?: string;
   error?: string;
@@ -280,8 +370,10 @@ interface RuntimeOptions {
   todoThinking: string;
   workerSessionReuse: boolean;
   workerSessionReuseContextThresholdPercent: number;
+  networkRecovery: NetworkRecoveryConfig;
   todoTimeoutMs: number;
   todoGracefulShutdownMs: number;
+  plannerBudget: PlannerBudget;
   workerRunner: WorkerRunner;
   useRetainedWorkerLifecycle: boolean;
   todoPlanner: TodoPlanner;
@@ -295,9 +387,20 @@ interface RuntimeOptions {
   workerTextByWorker: Map<string, string>;
   workerTextPublishedLengthByWorker: Map<string, number>;
   plannerDiagnostics: PlannerDiagnostic[];
+  capabilityWarnings: WorkerCapabilityWarning[];
   workerSessionMetrics: WorkerSessionMetrics;
   steeringQueue?: SerializedSteeringQueue;
   onPlanRevisionAccepted?: (revision: GeneratedPlanRevision) => void | Promise<void>;
+  onNetworkRecovery?: (event: NetworkRecoveryEvent) => void;
+  lastProgress?: CoordinatorProgressUpdate;
+  progressClosed: boolean;
+  networkRecoverySequence: number;
+  activeNetworkRecoveries: Map<number, ActiveNetworkRecovery>;
+}
+
+interface ActiveNetworkRecovery {
+  event: NetworkRecoveryEvent;
+  operation: "planner" | "worker";
 }
 
 type RetainedWorkerReuseScope = "sequential_task" | "partial_continuation";
@@ -733,6 +836,176 @@ function combineAbortSignals(...signals: Array<AbortSignal | undefined>): AbortS
   return AbortSignal.any(available);
 }
 
+/** Retains the full worker result while exposing its provider error to the shared classifier. */
+class WorkerNetworkFailure extends Error {
+  readonly outcome: SessionOutcome;
+
+  constructor(outcome: SessionOutcome) {
+    const message = outcome.error ?? "worker network operation failed";
+    super(message, { cause: workerFailureValue(outcome) });
+    this.name = "WorkerNetworkFailure";
+    this.outcome = outcome;
+  }
+}
+
+interface WorkerRecoveryExecutionOptions {
+  workerOptions: RunWorkerTaskOptions;
+  run: (options: RunWorkerTaskOptions) => Promise<SessionOutcome>;
+  taskResultPath: string;
+  networkRecovery: Readonly<NetworkRecoveryConfig>;
+  signal?: AbortSignal;
+  onInterruption?: (outcome: SessionOutcome) => void;
+  onNetworkRecovery?: (event: NetworkRecoveryEvent) => void;
+}
+
+/**
+ * Run one ordinary worker attempt, replacing only transport-failed sessions.
+ * Pi owns bounded request retries inside session.prompt(); therefore an outcome
+ * reaches this boundary only after those retries have settled. Coordinator
+ * probes retain the same task/attempt and always receive a recovery prompt.
+ */
+async function runWorkerAttemptWithNetworkRecovery(options: WorkerRecoveryExecutionOptions): Promise<SessionOutcome> {
+  const interrupted: SessionOutcome[] = [];
+  const thrownErrors = new Map<SessionOutcome, unknown>();
+  const execute = async (workerOptions: RunWorkerTaskOptions): Promise<SessionOutcome> => {
+    try {
+      return await options.run(workerOptions);
+    } catch (error) {
+      const outcome = buildWorkerSessionCreationFailureOutcome(workerOptions, error);
+      thrownErrors.set(outcome, error);
+      return outcome;
+    }
+  };
+  const recordRecoverableInterruption = async (outcome: SessionOutcome): Promise<void> => {
+    await appendNetworkInterruptionEvidence(options.taskResultPath, outcome, interrupted.length + 1);
+    interrupted.push(outcome);
+    options.onInterruption?.(outcome);
+  };
+
+  const initial = await execute(options.workerOptions);
+  const initialFailure = workerFailureValue(initial);
+  const initialClassification = initialFailure === undefined ? undefined : classifyNetworkFailure(initialFailure);
+  if (initialClassification && isFailFastWorkerFailure(initialClassification.reason)) {
+    throw new WorkerNetworkFailure(initial);
+  }
+  if (!options.networkRecovery.enabled || !initialClassification?.recoverable) {
+    if (thrownErrors.has(initial)) throw thrownErrors.get(initial);
+    return initial;
+  }
+  await recordRecoverableInterruption(initial);
+
+  try {
+    const recovered = await recoverNetworkOperation({
+      initialFailure: new WorkerNetworkFailure(initial),
+      config: options.networkRecovery,
+      signal: options.signal,
+      onEvent: options.onNetworkRecovery,
+      retry: async ({ retryCount, signal }) => {
+        const previous = interrupted.at(-1)!;
+        const resumed = await execute({
+          ...options.workerOptions,
+          // The recovery signal includes both run cancellation and the outage
+          // deadline without replacing the assignment/steering cancellation.
+          abortSignal: combineAbortSignals(options.workerOptions.abortSignal, signal),
+          networkRecoveryContext: {
+            retryCount,
+            durableEvidencePath: options.taskResultPath,
+            priorSessionId: previous.sessionId,
+            failure: previous.error ?? "transient provider or transport failure",
+          },
+        });
+        const resumedFailure = workerFailureValue(resumed);
+        const classification = resumedFailure === undefined ? undefined : classifyNetworkFailure(resumedFailure);
+        if (classification?.recoverable) {
+          await recordRecoverableInterruption(resumed);
+        }
+        if (resumed.error) {
+          if (
+            thrownErrors.has(resumed) &&
+            !classification?.recoverable &&
+            !isFailFastWorkerFailure(classification!.reason)
+          ) {
+            throw thrownErrors.get(resumed);
+          }
+          throw new WorkerNetworkFailure(resumed);
+        }
+        return resumed;
+      },
+    });
+    return mergeWorkerRecoveryOutcomes(interrupted, recovered.value);
+  } catch (error) {
+    // If connectivity recovered but the fresh session failed deterministically,
+    // hand its outcome back to the ordinary worker failure path immediately.
+    if (error instanceof WorkerNetworkFailure) {
+      const merged = mergeWorkerRecoveryOutcomes(interrupted, error.outcome);
+      const mergedFailure = workerFailureValue(merged);
+      const classification = mergedFailure === undefined ? undefined : classifyNetworkFailure(mergedFailure);
+      if (classification && isFailFastWorkerFailure(classification.reason)) {
+        throw new WorkerNetworkFailure(merged);
+      }
+      return merged;
+    }
+    throw error;
+  }
+}
+
+function workerFailureValue(outcome: SessionOutcome): unknown {
+  return outcome.failure ?? outcome.error;
+}
+
+function isFailFastWorkerFailure(reason: ReturnType<typeof classifyNetworkFailure>["reason"]): boolean {
+  return [
+    "authentication",
+    "authorization",
+    "billing",
+    "quota_exhausted",
+    "invalid_model",
+    "invalid_request",
+    "http_client_error",
+    "non_retryable_server_error",
+  ].includes(reason);
+}
+
+function mergeWorkerRecoveryOutcomes(interrupted: readonly SessionOutcome[], final: SessionOutcome): SessionOutcome {
+  if (interrupted.length === 0) return final;
+  const usage = addWorkerUsage([...interrupted.map((item) => item.workerUsage), final.workerUsage]);
+  return {
+    ...final,
+    startedAt: interrupted[0].startedAt,
+    contextObservations: [
+      ...interrupted.flatMap((item, index) => [
+        `network interruption ${index + 1}: ${item.error ?? "transient provider or transport failure"}`,
+        ...item.contextObservations,
+      ]),
+      ...final.contextObservations,
+    ],
+    compactionEvents: [...interrupted.flatMap((item) => item.compactionEvents), ...final.compactionEvents],
+    events: [...interrupted.flatMap((item) => item.events), ...final.events],
+    workerCostTotal: [...interrupted, final].reduce((total, item) => total + item.workerCostTotal, 0),
+    workerCostSource: "network_recovery_aggregate",
+    workerUsage: usage,
+    sessionDiagnostics: [
+      ...interrupted.flatMap((item) => item.sessionDiagnostics ?? []),
+      ...(final.sessionDiagnostics ?? []),
+    ],
+  };
+}
+
+function addWorkerUsage(values: Array<WorkerUsageTotals | undefined>): WorkerUsageTotals | undefined {
+  const available = values.filter((value): value is WorkerUsageTotals => Boolean(value));
+  if (available.length === 0) return undefined;
+  return available.reduce<WorkerUsageTotals>(
+    (total, value) => ({
+      input: total.input + value.input,
+      output: total.output + value.output,
+      cacheRead: total.cacheRead + value.cacheRead,
+      cacheWrite: total.cacheWrite + value.cacheWrite,
+      total: total.total + value.total,
+    }),
+    { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+  );
+}
+
 export function workerSessionHealthForOutcome(
   outcome: Pick<SessionOutcome, "timedOut" | "aborted" | "error" | "assistantText">,
   cancelled = false,
@@ -756,7 +1029,7 @@ export async function runCoordinator(options: RunCoordinatorOptions): Promise<Co
   const commits: CoordinatorCommitSummary[] = [];
 
   await mkdir(runtime.runDir, { recursive: true });
-  await writeFile(runtime.taskResultPath, initialTaskResultMarkdown(runtime.runId), "utf8");
+  await writeFile(runtime.taskResultPath, initialTaskResultMarkdown(runtime.runId, runtime.capabilityWarnings), "utf8");
   let planningComplete = false;
   let latestTodoMarkdown: string | undefined;
   let latestTasks: Task[] = [];
@@ -772,7 +1045,14 @@ export async function runCoordinator(options: RunCoordinatorOptions): Promise<Co
   const protectedDirtyPathsByTask = new Map<string, Set<string>>();
 
   try {
-    emitProgress(runtime, "Creating TODO plan...", { phase: "planning" });
+    for (const warning of runtime.capabilityWarnings) {
+      emitProgress(runtime, warning.message, {
+        phase: "capability_warning",
+        status: "warning",
+        capabilityWarning: warning,
+      });
+    }
+    emitPlannerProgress(runtime, createPlannerStartedProgress(runtime.plannerBudget, runtime.todoGracefulShutdownMs));
     let todoMarkdown = await generateOrNormalizeTodoMarkdown(inputText, runtime);
     validateTodoMarkdown(todoMarkdown);
     planningComplete = true;
@@ -949,6 +1229,7 @@ export async function runCoordinator(options: RunCoordinatorOptions): Promise<Co
         thinkingLevel: runtime.taskThinking,
         abortSignal: combineAbortSignals(runtime.abortSignal, assignmentController.signal),
         sessionFactory: runtime.workerSessionFactory,
+        networkRecovery: runtime.networkRecovery,
         now: runtime.now,
         onEvent: (event) => {
           if (activeWorkerAssignment === assignmentState && !assignmentState.obsolete) {
@@ -966,18 +1247,39 @@ export async function runCoordinator(options: RunCoordinatorOptions): Promise<Co
         },
       };
       let outcome: SessionOutcome;
+      const networkInterruptedOutcomes: SessionOutcome[] = [];
       try {
-        outcome = workerSessionOwner
-          ? await workerSessionOwner.run(workerOptions, assignmentIdentity)
-          : await runtime.workerRunner(workerOptions);
+        outcome = await runWorkerAttemptWithNetworkRecovery({
+          workerOptions,
+          run: (resumedOptions) =>
+            workerSessionOwner
+              ? workerSessionOwner.run(resumedOptions, assignmentIdentity)
+              : runtime.workerRunner(resumedOptions),
+          taskResultPath: runtime.taskResultPath,
+          networkRecovery: runtime.networkRecovery,
+          signal: workerOptions.abortSignal,
+          onInterruption: (interrupted) => networkInterruptedOutcomes.push(interrupted),
+          onNetworkRecovery: createNetworkRecoveryProgressHandler(runtime),
+        });
       } catch (error) {
         if (!assignmentState.obsolete) {
+          const terminalOutcome = error instanceof WorkerNetworkFailure ? error.outcome : undefined;
+          if (terminalOutcome || networkInterruptedOutcomes.length > 0) {
+            finalizeWorkerCost(runtime.workerCostState, accountingWorker, {
+              workerCostTotal:
+                terminalOutcome?.workerCostTotal ??
+                networkInterruptedOutcomes.reduce((total, interrupted) => total + interrupted.workerCostTotal, 0),
+            });
+          }
           throw error;
         }
         // A cancellation-aware custom runner may reject instead of returning
         // an aborted outcome. Preserve historical evidence, but never let that
         // obsolete rejection terminate or update the replacement assignment.
-        outcome = buildWorkerSessionCreationFailureOutcome(workerOptions, error);
+        outcome = mergeWorkerRecoveryOutcomes(
+          networkInterruptedOutcomes,
+          buildWorkerSessionCreationFailureOutcome(workerOptions, error),
+        );
         outcome.aborted = true;
       }
       finalizeWorkerCost(runtime.workerCostState, accountingWorker, outcome);
@@ -1152,6 +1454,8 @@ export async function runCoordinator(options: RunCoordinatorOptions): Promise<Co
       workerCostTotal: runtime.workerCostState.total,
       workerUsageTotal: aggregateWorkerUsage(outcomes),
       workerSessionMetrics: snapshotWorkerSessionMetrics(runtime.workerSessionMetrics),
+      plannerBudget: runtime.plannerBudget,
+      capabilityWarnings: runtime.capabilityWarnings,
       commit: options.commit,
       goal: runtime.goal,
       error: failure,
@@ -1166,10 +1470,12 @@ export async function runCoordinator(options: RunCoordinatorOptions): Promise<Co
     return result;
   } catch (error) {
     const message = errorMessage(error);
-    if (!planningComplete) {
+    if (!planningComplete && !hasTerminalPlannerDiagnostic(runtime.plannerDiagnostics)) {
       recordPlannerDiagnostic(runtime, {
-        kind: "failure",
-        message: `TODO planning failed: ${message}`,
+        kind: runtime.abortSignal?.aborted ? "cancelled" : "failure",
+        message: runtime.abortSignal?.aborted
+          ? `TODO planning cancelled: ${abortSignalReason(runtime.abortSignal)}`
+          : `TODO planning failed: ${message}`,
       });
     }
     const resultError = !planningComplete
@@ -1235,6 +1541,8 @@ export async function runCoordinator(options: RunCoordinatorOptions): Promise<Co
       workerCostTotal: runtime.workerCostState.total,
       workerUsageTotal: aggregateWorkerUsage(outcomes),
       workerSessionMetrics: snapshotWorkerSessionMetrics(runtime.workerSessionMetrics),
+      plannerBudget: runtime.plannerBudget,
+      capabilityWarnings: runtime.capabilityWarnings,
       commit: options.commit,
       goal: runtime.goal,
       error: resultError,
@@ -1248,15 +1556,18 @@ export async function runCoordinator(options: RunCoordinatorOptions): Promise<Co
     });
     return result;
   } finally {
+    runtime.progressClosed = true;
+    runtime.activeNetworkRecoveries.clear();
     removeSteeringProcessor?.();
     await workerSessionOwner?.dispose();
   }
 }
 
 async function generateOrNormalizeTodoMarkdown(inputText: string, runtime: RuntimeOptions): Promise<string> {
+  const capabilityConstraints = runtime.capabilityWarnings.map((warning) => warning.planningConstraint);
   const local = todoMarkdownFromString(inputText, runtime.goal);
   if (local) {
-    return local;
+    return applyWorkerCapabilityConstraintsToTodoMarkdown(local, capabilityConstraints);
   }
 
   const plannerText = await requestTodoPlan(inputText, runtime);
@@ -1265,6 +1576,7 @@ async function generateOrNormalizeTodoMarkdown(inputText: string, runtime: Runti
     plannerText,
     (repairPrompt) => requestTodoPlan(repairPrompt, runtime),
     runtime.goal,
+    capabilityConstraints,
     {
       onInvalidOutput: (validationError) =>
         recordPlannerDiagnostic(runtime, {
@@ -1283,7 +1595,8 @@ async function generateOrNormalizeTodoMarkdown(inputText: string, runtime: Runti
         }),
     },
   );
-  return applyGoalInstructionsToTodoMarkdown(planned, runtime.goal);
+  const withGoal = applyGoalInstructionsToTodoMarkdown(planned, runtime.goal);
+  return applyWorkerCapabilityConstraintsToTodoMarkdown(withGoal, capabilityConstraints);
 }
 
 interface TodoExtractionRepairHooks {
@@ -1297,6 +1610,7 @@ async function extractTodoMarkdownWithOneRepair(
   plannerText: string,
   requestRepair: (repairPrompt: string) => Promise<string>,
   goal?: string,
+  capabilityConstraints: readonly string[] = [],
   hooks: TodoExtractionRepairHooks = {},
 ): Promise<string> {
   try {
@@ -1305,7 +1619,9 @@ async function extractTodoMarkdownWithOneRepair(
     const validationError = errorMessage(error);
     hooks.onInvalidOutput?.(validationError);
     hooks.onRepairAttempt?.(validationError);
-    const repairText = await requestRepair(buildTodoRepairPrompt(inputText, plannerText, validationError, goal));
+    const repairText = await requestRepair(
+      buildTodoRepairPrompt(inputText, plannerText, validationError, goal, capabilityConstraints),
+    );
     try {
       return extractAndValidateTodoMarkdown(repairText);
     } catch (repairError) {
@@ -1319,19 +1635,126 @@ async function extractTodoMarkdownWithOneRepair(
 }
 
 async function requestTodoPlan(inputText: string, runtime: RuntimeOptions): Promise<string> {
-  return runtime.todoPlanner({
-    inputText,
-    cwd: runtime.cwd,
-    runDir: runtime.runDir,
-    thinkingLevel: runtime.todoThinking,
-    model: runtime.workerModel,
-    abortSignal: runtime.abortSignal,
-    timeoutMs: runtime.todoTimeoutMs,
-    gracefulShutdownMs: runtime.todoGracefulShutdownMs,
-    sessionFactory: runtime.todoSessionFactory,
-    onDiagnostic: (diagnostic) => recordPlannerDiagnostic(runtime, diagnostic),
-    goal: runtime.goal,
-  });
+  return runPlannerOperationWithNetworkRecovery(
+    {
+      inputText,
+      cwd: runtime.cwd,
+      runDir: runtime.runDir,
+      thinkingLevel: runtime.todoThinking,
+      model: runtime.workerModel,
+      abortSignal: runtime.abortSignal,
+      timeoutMs: runtime.todoTimeoutMs,
+      gracefulShutdownMs: runtime.todoGracefulShutdownMs,
+      plannerBudget: runtime.plannerBudget,
+      sessionFactory: runtime.todoSessionFactory,
+      networkRecovery: runtime.networkRecovery,
+      capabilityConstraints: runtime.capabilityWarnings.map((warning) => warning.planningConstraint),
+      onDiagnostic: (diagnostic) => recordPlannerDiagnostic(runtime, diagnostic),
+      onProgress: (event) => {
+        if (event.state !== "started") {
+          emitPlannerProgress(runtime, event);
+        }
+      },
+      goal: runtime.goal,
+    },
+    runtime,
+  );
+}
+
+/**
+ * Retry a side-effect-free planner request only after its provider boundary has
+ * failed. The default planner disables tools and disposes every session before
+ * rejecting, so each retry rotates unsafe conversation state while replaying
+ * only the complete immutable planning context. Recovery owns no planner
+ * repair/attempt counter, and each fresh call retains the exact configured
+ * per-attempt planner timeout. Network wait is intentionally excluded and is
+ * governed solely by the separate outage deadline; recovery cannot reset,
+ * extend, or replace the timeout attached to any individual planner call.
+ */
+async function runPlannerOperationWithNetworkRecovery(
+  plannerOptions: TodoPlannerOptions,
+  runtime: RuntimeOptions,
+): Promise<string> {
+  const run = (recoverySignal?: AbortSignal) =>
+    runtime.todoPlanner({
+      ...plannerOptions,
+      // The recovery signal carries cancellation/outage expiry only. It does
+      // not alter timeoutMs, which remains authoritative for every replay.
+      abortSignal: combineAbortSignals(plannerOptions.abortSignal, recoverySignal),
+    });
+
+  try {
+    return await run();
+  } catch (initialFailure) {
+    const classification = classifyNetworkFailure(initialFailure);
+    if (plannerOptions.abortSignal?.aborted || classification.reason === "cancelled") {
+      recordPlannerCancellation(runtime, plannerOptions.abortSignal, initialFailure);
+      throw plannerCancellationError(plannerOptions.abortSignal, initialFailure);
+    }
+    if (!runtime.networkRecovery.enabled || !classification.recoverable) {
+      throw initialFailure;
+    }
+
+    const publishRecovery = createNetworkRecoveryProgressHandler(runtime, "planner");
+    let recoveryStarted = false;
+    let lastRecoveryEvent: NetworkRecoveryEvent | undefined;
+    const onRecoveryEvent = (event: NetworkRecoveryEvent) => {
+      if (event.type !== "cleanup") lastRecoveryEvent = event;
+      if (event.type === "outage_started" && !recoveryStarted) {
+        recoveryStarted = true;
+        recordPlannerDiagnostic(
+          runtime,
+          plannerNetworkDiagnostic(
+            event,
+            plannerOptions.timeoutMs,
+            latestPlannerPartialOutput(runtime.plannerDiagnostics),
+          ),
+        );
+      }
+      publishRecovery(event);
+      if (event.type === "recovered") {
+        recordPlannerDiagnostic(
+          runtime,
+          plannerNetworkDiagnostic(
+            event,
+            plannerOptions.timeoutMs,
+            latestPlannerPartialOutput(runtime.plannerDiagnostics),
+          ),
+        );
+      }
+    };
+
+    try {
+      const recovered = await recoverNetworkOperation({
+        initialFailure,
+        config: runtime.networkRecovery,
+        signal: plannerOptions.abortSignal,
+        onEvent: onRecoveryEvent,
+        retry: ({ signal }) => run(signal),
+      });
+      return recovered.value;
+    } catch (recoveryFailure) {
+      if (plannerOptions.abortSignal?.aborted) {
+        recordPlannerCancellation(runtime, plannerOptions.abortSignal, recoveryFailure);
+        throw plannerCancellationError(plannerOptions.abortSignal, recoveryFailure);
+      } else if (!hasTerminalPlannerDiagnosticAfterLatestRecovery(runtime.plannerDiagnostics)) {
+        const finalClassification = classifyNetworkFailure(recoveryFailure);
+        recordPlannerDiagnostic(runtime, {
+          kind: "network_failure",
+          message: `TODO planner network recovery ended before planning completed: ${errorMessage(recoveryFailure)}`,
+          partialOutputObserved: latestPlannerPartialOutput(runtime.plannerDiagnostics),
+          networkRecoveryEvent:
+            lastRecoveryEvent?.type === "outage_expired" || lastRecoveryEvent?.type === "failed"
+              ? lastRecoveryEvent.type
+              : "failed",
+          networkFailureReason: lastRecoveryEvent?.state.lastFailure.reason ?? finalClassification.reason,
+          networkRetryCount: lastRecoveryEvent?.state.retryCount,
+          networkOutageElapsedMs: lastRecoveryEvent?.state.elapsedMs,
+        });
+      }
+      throw recoveryFailure;
+    }
+  }
 }
 
 async function generateSteeringPlanRevision(options: {
@@ -1364,21 +1787,28 @@ async function generateSteeringPlanRevision(options: {
         }
       : undefined,
     planner: ({ prompt, request }) =>
-      options.runtime.todoPlanner({
-        inputText: prompt,
-        plannerPrompt: prompt,
-        planRevision: request,
-        cwd: options.runtime.cwd,
-        runDir: options.runtime.runDir,
-        thinkingLevel: options.runtime.todoThinking,
-        model: options.runtime.workerModel,
-        abortSignal: options.runtime.abortSignal,
-        timeoutMs: options.runtime.todoTimeoutMs,
-        gracefulShutdownMs: options.runtime.todoGracefulShutdownMs,
-        sessionFactory: options.runtime.todoSessionFactory,
-        onDiagnostic: (diagnostic) => recordPlannerDiagnostic(options.runtime, diagnostic),
-        goal: options.runtime.goal,
-      }),
+      runPlannerOperationWithNetworkRecovery(
+        {
+          inputText: prompt,
+          plannerPrompt: prompt,
+          planRevision: request,
+          cwd: options.runtime.cwd,
+          runDir: options.runtime.runDir,
+          thinkingLevel: options.runtime.todoThinking,
+          model: options.runtime.workerModel,
+          abortSignal: options.runtime.abortSignal,
+          timeoutMs: options.runtime.todoTimeoutMs,
+          gracefulShutdownMs: options.runtime.todoGracefulShutdownMs,
+          plannerBudget: options.runtime.plannerBudget,
+          sessionFactory: options.runtime.todoSessionFactory,
+          networkRecovery: options.runtime.networkRecovery,
+          capabilityConstraints: options.runtime.capabilityWarnings.map((warning) => warning.planningConstraint),
+          onDiagnostic: (diagnostic) => recordPlannerDiagnostic(options.runtime, diagnostic),
+          onProgress: (event) => emitPlannerProgress(options.runtime, event),
+          goal: options.runtime.goal,
+        },
+        options.runtime,
+      ),
   });
 }
 
@@ -1483,16 +1913,41 @@ function relevantPlanRevisionResults(
 // Planner/worker lifecycle differences are audited in docs/planner-worker-lifecycle-audit.md;
 // keep this function's public contract stable while moving shared prompt guarding into a helper.
 export async function runTodoPlanner(options: TodoPlannerOptions): Promise<string> {
+  const capabilityConstraints =
+    options.capabilityConstraints ??
+    capabilityWarningsForRequest(options.inputText, options.goal).map((warning) => warning.planningConstraint);
+  const plannerBudget =
+    options.plannerBudget ??
+    resolvePlannerBudget({
+      inputText: options.inputText,
+      explicitTimeoutMs: options.timeoutMs,
+      defaultTimeoutMs: DEFAULT_COORDINATOR_OPTIONS.todoTimeoutMs,
+    });
+  const timeoutMs = resolvePlannerTimeoutMs(options.timeoutMs, plannerBudget.timeoutMs);
+  const gracefulShutdownMs = resolvePlannerGracefulShutdownMs(
+    options.gracefulShutdownMs,
+    DEFAULT_COORDINATOR_OPTIONS.todoGracefulShutdownMs,
+  );
+  const effectivePlannerBudget: PlannerBudget =
+    timeoutMs === plannerBudget.timeoutMs
+      ? plannerBudget
+      : {
+          ...plannerBudget,
+          timeoutMs,
+          extensionApplied: false,
+          extensionMs: 0,
+          source: "explicit",
+          trigger: undefined,
+        };
+  notifyPlannerProgress(options.onProgress, createPlannerStartedProgress(effectivePlannerBudget, gracefulShutdownMs));
   const sessionFactory = options.sessionFactory ?? createIsolatedWorkerSession;
   const result = await sessionFactory({
     cwd: options.cwd,
     tools: [],
     model: options.model,
-    thinkingLevel: options.thinkingLevel,
+    thinkingLevel: options.thinkingLevel ?? DEFAULT_PLANNER_THINKING_LEVEL,
   });
   const session = result.session;
-  const timeoutMs = positiveMilliseconds(options.timeoutMs, DEFAULT_COORDINATOR_OPTIONS.todoTimeoutMs);
-  const gracefulShutdownMs = options.gracefulShutdownMs ?? DEFAULT_COORDINATOR_OPTIONS.todoGracefulShutdownMs;
 
   let plannerMarkdown: string | undefined;
   let plannerError: unknown;
@@ -1500,12 +1955,14 @@ export async function runTodoPlanner(options: TodoPlannerOptions): Promise<strin
   try {
     const plannerText = await runTodoPlannerPrompt({
       session,
-      prompt: options.plannerPrompt ?? buildTodoCreationPrompt(options.inputText, options.goal),
+      prompt: options.plannerPrompt ?? buildTodoCreationPrompt(options.inputText, options.goal, capabilityConstraints),
       abortSignal: options.abortSignal,
       timeoutMs,
       gracefulShutdownMs,
       diagnostics: result.diagnostics,
       onDiagnostic: options.onDiagnostic,
+      plannerBudget: effectivePlannerBudget,
+      onProgress: options.onProgress,
     });
 
     plannerMarkdown = await extractTodoMarkdownWithOneRepair(
@@ -1520,8 +1977,11 @@ export async function runTodoPlanner(options: TodoPlannerOptions): Promise<strin
           gracefulShutdownMs,
           diagnostics: result.diagnostics,
           onDiagnostic: options.onDiagnostic,
+          plannerBudget: effectivePlannerBudget,
+          onProgress: options.onProgress,
         }),
       options.goal,
+      capabilityConstraints,
       {
         onInvalidOutput: (validationError) =>
           options.onDiagnostic?.({
@@ -1565,7 +2025,8 @@ export async function runTodoPlanner(options: TodoPlannerOptions): Promise<strin
   if (!plannerMarkdown) {
     throw new TodoGenerationError("TODO planner did not return valid TODO markdown.");
   }
-  return applyGoalInstructionsToTodoMarkdown(plannerMarkdown, options.goal);
+  const withGoal = applyGoalInstructionsToTodoMarkdown(plannerMarkdown, options.goal);
+  return applyWorkerCapabilityConstraintsToTodoMarkdown(withGoal, capabilityConstraints);
 }
 
 async function runTodoPlannerPrompt(options: {
@@ -1576,6 +2037,8 @@ async function runTodoPlannerPrompt(options: {
   gracefulShutdownMs: number;
   diagnostics?: string[];
   onDiagnostic?: PlannerDiagnosticHandler;
+  plannerBudget: Readonly<PlannerBudget>;
+  onProgress?: PlannerProgressHandler;
 }): Promise<string> {
   const promptResult = await runGuardedSessionPrompt({
     session: options.session,
@@ -1585,23 +2048,56 @@ async function runTodoPlannerPrompt(options: {
     gracefulShutdownMs: options.gracefulShutdownMs,
     gracefulShutdownPrompt: buildTodoPlanningShutdownMessage(),
     diagnostics: options.diagnostics,
+    progressCheckpointsMs: plannerProgressCheckpoints(options.timeoutMs),
+    onProgressCheckpoint: (elapsedMs) =>
+      notifyPlannerProgress(
+        options.onProgress,
+        createPlannerActiveProgress(options.plannerBudget, options.gracefulShutdownMs, elapsedMs),
+      ),
+    onGracePeriodStart: (gracePeriodMs) =>
+      notifyPlannerProgress(options.onProgress, createPlannerGraceProgress(options.plannerBudget, gracePeriodMs)),
     dispose: false,
   });
 
+  // Caller cancellation wins even when it arrives during grace. A hard abort
+  // caused by grace expiry has cancelled=false and remains a timeout.
+  if (promptResult.cancelled) {
+    const outputState = promptResult.outputObserved
+      ? "partial output observed; content omitted"
+      : "no planner output observed";
+    const message = `TODO planner cancelled (${outputState}): ${promptResult.error ?? "caller cancellation"}`;
+    options.onDiagnostic?.(plannerPromptDiagnostic("cancelled", message, promptResult));
+    throw new TodoGenerationError(message);
+  }
   if (promptResult.timedOut) {
-    const message = `TODO planner timed out: ${promptResult.error ?? "time budget exceeded"}`;
+    if (
+      promptResult.completedDuringGrace &&
+      promptResult.outputObserved &&
+      !promptResult.error &&
+      isSafeCompletedTodoPlannerOutput(promptResult.assistantText)
+    ) {
+      return promptResult.assistantText;
+    }
+
+    const outputState = promptResult.outputObserved
+      ? "partial output observed; content omitted"
+      : "no planner output observed";
+    const message = `TODO planner timed out (${outputState}): ${promptResult.error ?? "time budget exceeded"}`;
     options.onDiagnostic?.(plannerPromptDiagnostic("timeout", message, promptResult));
     throw new TodoGenerationError(message);
   }
   if (promptResult.aborted) {
-    const message = `TODO planner aborted: ${promptResult.error ?? "outer abort signal"}`;
-    options.onDiagnostic?.(plannerPromptDiagnostic("abort", message, promptResult));
+    const message = `TODO planner stopped: ${promptResult.error ?? "session abort"}`;
+    options.onDiagnostic?.(plannerPromptDiagnostic("failure", message, promptResult));
     throw new TodoGenerationError(message);
   }
   if (promptResult.error) {
     const message = `TODO planner failed: ${promptResult.error}`;
     options.onDiagnostic?.(plannerPromptDiagnostic("failure", message, promptResult));
-    throw new TodoGenerationError(message);
+    throw new TodoGenerationError(
+      message,
+      promptResult.failure === undefined ? undefined : { cause: promptResult.failure },
+    );
   }
   if (!promptResult.assistantText) {
     const message = "TODO planner did not return assistant text.";
@@ -1612,9 +2108,10 @@ async function runTodoPlannerPrompt(options: {
 }
 
 function plannerPromptDiagnostic(
-  kind: Extract<PlannerDiagnosticKind, "timeout" | "abort" | "failure">,
+  kind: Extract<PlannerDiagnosticKind, "timeout" | "cancelled" | "abort" | "failure">,
   message: string,
   promptResult: {
+    outputObserved: boolean;
     diagnostics: string[];
     sessionFile?: string;
     sessionId?: string;
@@ -1623,12 +2120,25 @@ function plannerPromptDiagnostic(
   return {
     kind,
     message,
+    partialOutputObserved: promptResult.outputObserved,
     diagnostics: promptResult.diagnostics,
     sessionFile: promptResult.sessionFile,
     sessionId: promptResult.sessionId,
   };
 }
 
+function isSafeCompletedTodoPlannerOutput(text: string): boolean {
+  if (!text.trim()) {
+    return false;
+  }
+  try {
+    extractAndValidateTodoMarkdown(text);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 function buildTodoPlanningShutdownMessage(): string {
   return `Pi Long Task notice: TODO planning has reached its time budget.
 Return the best valid Pi Long Task TODO markdown you can produce now, or stop if that is not possible.`;
@@ -1641,8 +2151,13 @@ function buildRuntimeOptions(options: RunCoordinatorOptions): RuntimeOptions {
   const parsedWorkerConfig = parseWorkerRuntimeConfig(options.inputText ?? "");
   const configuredAttempts = options.maxAttemptsPerTask ?? parsedWorkerConfig.maxAttemptsPerTask;
   const configuredTaskTimeoutMs = options.taskTimeoutMs ?? parsedWorkerConfig.taskTimeoutMs;
-  const configuredTodoTimeoutMs = options.todoTimeoutMs;
-  const configuredTodoGracefulShutdownMs = options.todoGracefulShutdownMs;
+  const configuredTodoTimeoutMs = options.todoTimeoutMs ?? parsedWorkerConfig.todoTimeoutMs;
+  const configuredTodoGracefulShutdownMs = options.todoGracefulShutdownMs ?? parsedWorkerConfig.todoGracefulShutdownMs;
+  const plannerBudget = resolvePlannerBudget({
+    inputText: coordinatorInputText(options),
+    explicitTimeoutMs: configuredTodoTimeoutMs,
+    defaultTimeoutMs: DEFAULT_COORDINATOR_OPTIONS.todoTimeoutMs,
+  });
   const configuredMaxBashTimeoutMs = options.maxBashTimeoutMs ?? parsedWorkerConfig.maxBashTimeoutMs;
   const workerModelName = options.workerModelName ?? parsedWorkerConfig.modelName;
   const workerModel = workerModelName ? undefined : options.workerModel;
@@ -1652,6 +2167,11 @@ function buildRuntimeOptions(options: RunCoordinatorOptions): RuntimeOptions {
     contextThresholdPercent:
       options.workerSessionReuseContextThresholdPercent ?? parsedWorkerConfig.workerSessionReuseContextThresholdPercent,
   });
+  const networkRecovery = resolveNetworkRecoveryConfig({
+    ...parsedWorkerConfig.networkRecovery,
+    ...options.networkRecovery,
+  });
+  const capabilityWarnings = capabilityWarningsForRequest(options.inputText, options.goal);
 
   return {
     cwd,
@@ -1661,11 +2181,12 @@ function buildRuntimeOptions(options: RunCoordinatorOptions): RuntimeOptions {
     taskResultPath: path.join(runDir, "TASK_RESULT.md"),
     maxAttemptsPerTask: positiveInteger(configuredAttempts, DEFAULT_COORDINATOR_OPTIONS.maxAttemptsPerTask),
     taskTimeoutSeconds: positiveMilliseconds(configuredTaskTimeoutMs, DEFAULT_COORDINATOR_OPTIONS.taskTimeoutMs) / 1000,
-    todoTimeoutMs: positiveMilliseconds(configuredTodoTimeoutMs, DEFAULT_COORDINATOR_OPTIONS.todoTimeoutMs),
-    todoGracefulShutdownMs: positiveMilliseconds(
+    todoTimeoutMs: plannerBudget.timeoutMs,
+    todoGracefulShutdownMs: resolvePlannerGracefulShutdownMs(
       configuredTodoGracefulShutdownMs,
       DEFAULT_COORDINATOR_OPTIONS.todoGracefulShutdownMs,
     ),
+    plannerBudget,
     maxBashTimeoutSeconds:
       positiveMilliseconds(configuredMaxBashTimeoutMs, DEFAULT_COORDINATOR_OPTIONS.maxBashTimeoutMs) / 1000,
     workerModel,
@@ -1675,6 +2196,7 @@ function buildRuntimeOptions(options: RunCoordinatorOptions): RuntimeOptions {
     todoThinking: options.todoThinking ?? DEFAULT_COORDINATOR_OPTIONS.todoThinking,
     workerSessionReuse: workerSessionReuseConfig.enabled,
     workerSessionReuseContextThresholdPercent: workerSessionReuseConfig.contextThresholdPercent,
+    networkRecovery,
     workerRunner: options.workerRunner ?? runWorkerTask,
     useRetainedWorkerLifecycle: options.workerRunner === undefined,
     todoPlanner: options.todoPlanner ?? runTodoPlanner,
@@ -1688,18 +2210,41 @@ function buildRuntimeOptions(options: RunCoordinatorOptions): RuntimeOptions {
     workerTextByWorker: new Map(),
     workerTextPublishedLengthByWorker: new Map(),
     plannerDiagnostics: [],
+    capabilityWarnings,
     workerSessionMetrics: createWorkerSessionMetrics(),
     steeringQueue: options.steeringQueue,
     onPlanRevisionAccepted: options.onPlanRevisionAccepted,
+    onNetworkRecovery: options.onNetworkRecovery,
+    progressClosed: false,
+    networkRecoverySequence: 0,
+    activeNetworkRecoveries: new Map(),
   };
 }
 
+function emitPlannerProgress(runtime: RuntimeOptions, event: Readonly<PlannerProgressEvent>): void {
+  emitProgress(runtime, event.message, {
+    phase: "planning",
+    activeStatus: event.message,
+    plannerBudget: event.budget,
+    plannerProgressState: event.state,
+    plannerElapsedMs: event.elapsedMs,
+    plannerRemainingMs: event.remainingMs,
+    plannerGracePeriodMs: event.gracePeriodMs,
+    ...(event.graceRemainingMs === undefined ? {} : { plannerGraceRemainingMs: event.graceRemainingMs }),
+  });
+}
+
+function notifyPlannerProgress(handler: PlannerProgressHandler | undefined, event: PlannerProgressEvent): void {
+  handler?.(event);
+}
+
 function emitProgress(
   runtime: RuntimeOptions,
   message: string,
   update: Omit<CoordinatorProgressUpdate, "message" | "runId" | "todoPath" | "resultPath" | "workerCostTotal">,
 ): void {
-  runtime.onProgress?.({
+  if (runtime.progressClosed) return;
+  const progress: CoordinatorProgressUpdate = {
     message,
     runId: runtime.runId,
     todoPath: runtime.todoPath,
@@ -1707,16 +2252,193 @@ function emitProgress(
     workerCostTotal: runtime.workerCostState.total,
     ...update,
     goal: runtime.goal,
+  };
+  runtime.lastProgress = progress;
+  const activeRecovery = latestNetworkRecovery(runtime.activeNetworkRecoveries);
+  if (activeRecovery) {
+    publishNetworkRecoveryProgress(runtime, activeRecovery.event, activeRecovery.operation);
+  } else {
+    runtime.onProgress?.(progress);
+  }
+}
+
+/**
+ * Bridge one recovery lifecycle into coordinator progress without replacing the
+ * last stable task/phase update. A recovered operation restores whichever
+ * ordinary status is current; terminal failures are left for the normal final
+ * status path. Operation IDs prevent an older concurrent recovery from
+ * repainting a newer outage or completion.
+ */
+function createNetworkRecoveryProgressHandler(
+  runtime: RuntimeOptions,
+  operation: "planner" | "worker" = "worker",
+): (event: NetworkRecoveryEvent) => void {
+  const operationId = ++runtime.networkRecoverySequence;
+  let cleaned = false;
+
+  return (event) => {
+    runtime.onNetworkRecovery?.(event);
+    if (cleaned || runtime.progressClosed) return;
+
+    if (event.type === "cleanup") {
+      cleaned = true;
+      runtime.activeNetworkRecoveries.delete(operationId);
+      return;
+    }
+
+    if (isTerminalNetworkRecoveryEvent(event.type)) {
+      runtime.activeNetworkRecoveries.delete(operationId);
+      if (event.type === "recovered") {
+        const active = latestNetworkRecovery(runtime.activeNetworkRecoveries);
+        if (active) {
+          publishNetworkRecoveryProgress(runtime, active.event, active.operation);
+        } else if (runtime.lastProgress) {
+          runtime.onProgress?.({ ...runtime.lastProgress, workerCostTotal: runtime.workerCostState.total });
+        }
+      }
+      return;
+    }
+
+    runtime.activeNetworkRecoveries.set(operationId, { event, operation });
+    if (operationId === latestNetworkRecoveryId(runtime.activeNetworkRecoveries)) {
+      publishNetworkRecoveryProgress(runtime, event, operation);
+    }
+  };
+}
+
+function publishNetworkRecoveryProgress(
+  runtime: RuntimeOptions,
+  event: NetworkRecoveryEvent,
+  operation: "planner" | "worker" = "worker",
+): void {
+  if (runtime.progressClosed) return;
+  const stable = runtime.lastProgress;
+  const nowMs = event.state.outageStartedAtMs + event.state.elapsedMs;
+  const recoveryStatus = formatNetworkRecoveryStatus(event);
+  const message =
+    operation === "planner"
+      ? `TODO planner network recovery: ${recoveryStatus} The ${formatFriendlyDuration(runtime.todoTimeoutMs)} planning deadline remains unchanged for each provider attempt.`
+      : recoveryStatus;
+  runtime.onProgress?.({
+    message,
+    phase: "network_wait",
+    runId: runtime.runId,
+    todoPath: runtime.todoPath,
+    resultPath: runtime.taskResultPath,
+    workerCostTotal: runtime.workerCostState.total,
+    goal: runtime.goal,
+    taskId: stable?.taskId,
+    title: stable?.title,
+    attempt: stable?.attempt,
+    totalTasks: stable?.totalTasks,
+    currentTask: stable?.currentTask,
+    subtasks: stable?.subtasks,
+    taskProgress: stable?.taskProgress,
+    activeStatus: message,
+    networkRecoveryEvent: event.type,
+    networkRetryCount: event.state.retryCount,
+    networkOutageElapsedMs: event.state.elapsedMs,
+    networkNextRetryAtMs: event.state.nextRetryAtMs,
+    networkNextRetryInMs:
+      event.state.nextRetryAtMs === undefined ? undefined : Math.max(0, event.state.nextRetryAtMs - nowMs),
+    networkFailureReason: event.state.lastFailure.reason,
+    networkOperation: operation,
+    ...(operation === "planner" ? { plannerDeadlinePolicy: "per_attempt_excludes_network_wait" as const } : {}),
   });
 }
 
+function latestNetworkRecovery(
+  recoveries: ReadonlyMap<number, ActiveNetworkRecovery>,
+): ActiveNetworkRecovery | undefined {
+  const id = latestNetworkRecoveryId(recoveries);
+  return id === undefined ? undefined : recoveries.get(id);
+}
+
+function latestNetworkRecoveryId(recoveries: ReadonlyMap<number, ActiveNetworkRecovery>): number | undefined {
+  let latest: number | undefined;
+  for (const id of recoveries.keys()) {
+    if (latest === undefined || id > latest) latest = id;
+  }
+  return latest;
+}
+
+function isTerminalNetworkRecoveryEvent(type: NetworkRecoveryEventType): boolean {
+  return type === "recovered" || type === "failed" || type === "cancelled" || type === "outage_expired";
+}
+
+function plannerNetworkDiagnostic(
+  event: NetworkRecoveryEvent,
+  timeoutMs: number | undefined,
+  partialOutputObserved: boolean | undefined,
+): PlannerDiagnostic {
+  const recovered = event.type === "recovered";
+  const budget = formatFriendlyDuration(timeoutMs ?? DEFAULT_COORDINATOR_OPTIONS.todoTimeoutMs);
+  return {
+    kind: "network_recovery",
+    message: recovered
+      ? `TODO planner network recovery succeeded after ${formatFriendlyDuration(event.state.elapsedMs)}; planning continues with its unchanged ${budget} per-attempt deadline.`
+      : `TODO planner network recovery started (${event.state.lastFailure.reason}); its outage clock is separate and the ${budget} per-attempt planning deadline remains unchanged.`,
+    partialOutputObserved,
+    networkRecoveryEvent: event.type,
+    networkFailureReason: event.state.lastFailure.reason,
+    networkRetryCount: event.state.retryCount,
+    networkOutageElapsedMs: event.state.elapsedMs,
+  };
+}
+
+function latestPlannerPartialOutput(diagnostics: readonly PlannerDiagnostic[]): boolean | undefined {
+  return [...diagnostics].reverse().find((diagnostic) => diagnostic.partialOutputObserved !== undefined)
+    ?.partialOutputObserved;
+}
+
+function hasTerminalPlannerDiagnostic(diagnostics: readonly PlannerDiagnostic[]): boolean {
+  const kind = diagnostics.at(-1)?.kind;
+  return kind !== undefined && ["timeout", "cancelled", "abort", "network_failure", "failure"].includes(kind);
+}
+
+function hasTerminalPlannerDiagnosticAfterLatestRecovery(diagnostics: readonly PlannerDiagnostic[]): boolean {
+  let recoveryIndex = -1;
+  for (let index = diagnostics.length - 1; index >= 0; index -= 1) {
+    if (diagnostics[index]?.kind === "network_recovery") {
+      recoveryIndex = index;
+      break;
+    }
+  }
+  return diagnostics
+    .slice(recoveryIndex + 1)
+    .some((diagnostic) => ["timeout", "cancelled", "abort", "network_failure"].includes(diagnostic.kind));
+}
+
+function recordPlannerCancellation(runtime: RuntimeOptions, signal: AbortSignal | undefined, cause: unknown): void {
+  if (runtime.plannerDiagnostics.some((diagnostic) => diagnostic.kind === "cancelled")) return;
+  recordPlannerDiagnostic(runtime, {
+    kind: "cancelled",
+    message: `TODO planning cancelled: ${signal?.aborted ? abortSignalReason(signal) : errorMessage(cause)}`,
+    partialOutputObserved: latestPlannerPartialOutput(runtime.plannerDiagnostics),
+  });
+}
+
+function abortSignalReason(signal: AbortSignal): string {
+  return signal.reason === undefined ? "cancelled by caller" : errorMessage(signal.reason);
+}
+
+function plannerCancellationError(signal: AbortSignal | undefined, cause: unknown): TodoGenerationError {
+  const reason = signal?.aborted ? abortSignalReason(signal) : errorMessage(cause);
+  return new TodoGenerationError(`TODO planning cancelled: ${reason}`, { cause });
+}
+
 function recordPlannerDiagnostic(runtime: RuntimeOptions, diagnostic: PlannerDiagnostic): void {
   const normalized: PlannerDiagnostic = {
     kind: diagnostic.kind,
     message: diagnostic.message,
+    partialOutputObserved: diagnostic.partialOutputObserved,
     diagnostics: diagnostic.diagnostics?.filter(Boolean),
     sessionFile: diagnostic.sessionFile,
     sessionId: diagnostic.sessionId,
+    networkRecoveryEvent: diagnostic.networkRecoveryEvent,
+    networkFailureReason: diagnostic.networkFailureReason,
+    networkRetryCount: diagnostic.networkRetryCount,
+    networkOutageElapsedMs: diagnostic.networkOutageElapsedMs,
   };
   const last = runtime.plannerDiagnostics.at(-1);
   if (last?.kind === normalized.kind && last.message === normalized.message) {
@@ -1726,11 +2448,22 @@ function recordPlannerDiagnostic(runtime: RuntimeOptions, diagnostic: PlannerDia
   emitProgress(runtime, normalized.message, {
     phase: "planning",
     status: normalized.kind,
-    isError: normalized.kind !== "repair_attempt",
+    isError: !["repair_attempt", "network_recovery"].includes(normalized.kind),
     plannerDiagnostic: normalized.kind,
     plannerDiagnostics: normalized.diagnostics,
+    plannerPartialOutputObserved: normalized.partialOutputObserved,
     plannerSessionFile: normalized.sessionFile,
     plannerSessionId: normalized.sessionId,
+    networkRecoveryEvent: normalized.networkRecoveryEvent,
+    networkRetryCount: normalized.networkRetryCount,
+    networkOutageElapsedMs: normalized.networkOutageElapsedMs,
+    networkFailureReason: normalized.networkFailureReason,
+    networkOperation:
+      normalized.kind === "network_recovery" || normalized.kind === "network_failure" ? "planner" : undefined,
+    plannerDeadlinePolicy:
+      normalized.kind === "network_recovery" || normalized.kind === "network_failure"
+        ? "per_attempt_excludes_network_wait"
+        : undefined,
     taskProgress: buildTaskProgressModel({ tasks: [] }),
   });
 }
@@ -2203,8 +2936,11 @@ function outcomeProgressItemStatus(
   return "failed";
 }
 
-function initialTaskResultMarkdown(runId: string): string {
-  return `# Pi Long Task TASK_RESULT\n\nRun: ${runId}\n`;
+function initialTaskResultMarkdown(runId: string, capabilityWarnings: readonly WorkerCapabilityWarning[] = []): string {
+  const warningBlock = capabilityWarnings.length
+    ? `\n\n## Worker capability warnings\n\n${capabilityWarnings.map((warning) => `- ${warning.message}`).join("\n")}`
+    : "";
+  return `# Pi Long Task TASK_RESULT\n\nRun: ${runId}${warningBlock}\n`;
 }
 
 async function appendFailureNote(
@@ -2217,6 +2953,21 @@ async function appendFailureNote(
     lines.push("", "### Planner diagnostics");
     for (const diagnostic of plannerDiagnostics) {
       lines.push("", `- ${diagnostic.kind}: ${diagnostic.message}`);
+      if (diagnostic.partialOutputObserved !== undefined) {
+        lines.push(`  - Partial output observed: ${diagnostic.partialOutputObserved ? "yes" : "no"}`);
+      }
+      if (diagnostic.networkRecoveryEvent) {
+        lines.push(`  - Network recovery event: ${diagnostic.networkRecoveryEvent}`);
+      }
+      if (diagnostic.networkFailureReason) {
+        lines.push(`  - Network failure reason: ${diagnostic.networkFailureReason}`);
+      }
+      if (diagnostic.networkRetryCount !== undefined) {
+        lines.push(`  - Network retry count: ${diagnostic.networkRetryCount}`);
+      }
+      if (diagnostic.networkOutageElapsedMs !== undefined) {
+        lines.push(`  - Network outage elapsed: ${formatFriendlyDuration(diagnostic.networkOutageElapsedMs)}`);
+      }
       if (diagnostic.sessionId) {
         lines.push(`  - Session ID: ${diagnostic.sessionId}`);
       }
@@ -2243,6 +2994,43 @@ async function appendCommitNote(pathname: string, result: CommitAfterSessionResu
   await appendFile(pathname, `${lines.join("\n")}\n`, "utf8");
 }
 
+async function appendNetworkInterruptionEvidence(
+  pathname: string,
+  outcome: SessionOutcome,
+  networkRetry: number,
+): Promise<void> {
+  const summary = extractResultSummary(outcome.assistantText || "").trim() || "TASK_RESULT:\nstatus: unknown";
+  const lines = [
+    "",
+    `## TODO ${outcome.task.taskId} — ${outcome.task.title} (ordinary attempt ${outcome.attempt}, network interruption ${networkRetry})`,
+    "",
+    "Disposition: transient provider/transport failure; this is durable evidence, not an ordinary task attempt.",
+    `Started: ${outcome.startedAt}`,
+    `Ended: ${outcome.endedAt}`,
+    `Worker error: ${outcome.error ?? "transient provider or transport failure"}`,
+  ];
+  if (outcome.sessionId) lines.push(`Session ID: ${outcome.sessionId}`);
+  if (outcome.sessionFile) lines.push(`Session file: ${outcome.sessionFile}`);
+  if (outcome.workerCostSource || outcome.workerCostTotal > 0) {
+    lines.push(`Worker cost: ${outcome.workerCostTotal} (${outcome.workerCostSource ?? "unavailable"})`);
+  }
+  if (outcome.workerUsage) {
+    lines.push(
+      `Worker token usage: input=${outcome.workerUsage.input}, output=${outcome.workerUsage.output}, cacheRead=${outcome.workerUsage.cacheRead}, cacheWrite=${outcome.workerUsage.cacheWrite}, total=${outcome.workerUsage.total}`,
+    );
+  }
+  lines.push(
+    "",
+    "Safety: the replacement session must inspect the working tree and this evidence before continuing; completed side effects must not be blindly replayed.",
+    "",
+    "```text",
+    summary,
+    "```",
+    "",
+  );
+  await appendFile(pathname, `${lines.join("\n")}\n`, "utf8");
+}
+
 async function appendTaskResult(
   pathname: string,
   task: Task,
@@ -2378,6 +3166,17 @@ function coordinatorInputText(options: RunCoordinatorOptions): string {
   return normalizeOptionalText(options.inputText) ?? normalizeOptionalText(options.goal) ?? "";
 }
 
+function capabilityWarningsForRequest(inputText?: string, goal?: string): WorkerCapabilityWarning[] {
+  const requestText = [normalizeOptionalText(inputText), normalizeOptionalText(goal)]
+    .filter((item): item is string => Boolean(item))
+    .filter((item, index, all) => all.indexOf(item) === index)
+    .join("\n");
+  return detectUnavailableWorkerCapabilities(requestText, {
+    tools: DEFAULT_WORKER_TOOLS,
+    extensionsEnabled: false,
+  });
+}
+
 function positiveInteger(value: number | undefined, fallback: number): number {
   if (typeof value === "number" && Number.isFinite(value) && value > 0) {
     return Math.floor(value);