pi-long-task 0.4.0 → 0.6.0

package/src/coordinator.ts

@@ -10,7 +10,19 @@ import type {
 } from "./types.ts";
 import { commitAfterSession, gitDirtyPaths, shouldCommitOutcome, type CommitAfterSessionResult } from "./git.ts";
 import { formatCoordinatorResultMessage } from "./render.ts";
-import { extractResultSummary } from "./result_writer.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 {
   generatePlanRevision,
@@ -28,6 +40,16 @@ import {
 } from "./plan_store.ts";
 import type { SerializedSteeringQueue, SteeringMessage } from "./steering.ts";
 import { parseWorkerRuntimeConfig } from "./worker_config.ts";
+import {
+  classifyWorkerSessionRetry,
+  createWorkerSessionCompatibilityFingerprint,
+  decideWorkerSessionReuse,
+  DEFAULT_WORKER_SESSION_REUSE_CONTEXT_THRESHOLD_PERCENT,
+  DEFAULT_WORKER_SESSION_REUSE_ENABLED,
+  resolveWorkerSessionReuseConfig,
+  type WorkerSessionCompatibilityFingerprint,
+  type WorkerSessionHealth,
+} from "./worker_reuse_policy.ts";
 import { buildTaskProgressModel, type TaskProgressModel, type TaskProgressStatus } from "./task_progress.ts";
 import {
   applyGoalInstructionsToTodoMarkdown,
@@ -40,12 +62,21 @@ import {
 } from "./todo_generator.ts";
 import { parseTasks, todoGlobalInstructions, type Task } from "./todo_parser.ts";
 import {
+  buildWorkerSessionCreationFailureOutcome,
   createIsolatedWorkerSession,
+  createWorkerSessionResource,
+  DEFAULT_WORKER_TOOLS,
+  disposeWorkerSessionResource,
   runWorkerTask,
+  runWorkerTaskAssignment,
+  workerSessionContextUsagePercent,
   type RunWorkerTaskOptions,
   type SessionOutcome,
+  type WorkerSessionDiagnostic,
   type WorkerSessionFactory,
   type WorkerSessionLike,
+  type WorkerSessionResource,
+  type WorkerUsageTotals,
 } from "./worker_session.ts";
 
 export type { CoordinatorStatus } from "./types.ts";
@@ -58,6 +89,9 @@ export const DEFAULT_COORDINATOR_OPTIONS = {
   maxBashTimeoutMs: 300_000,
   taskThinking: "high",
   todoThinking: "xhigh",
+  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>;
@@ -65,7 +99,9 @@ export type CoordinatorProgressPhase =
   | "planning"
   | "planned"
   | "task_start"
+  | "worker_session"
   | "worker_tool"
+  | "network_wait"
   | "task_done"
   | "task_blocked"
   | "task_failed"
@@ -124,6 +160,16 @@ export interface CoordinatorProgressUpdate {
   plannerDiagnostics?: string[];
   plannerSessionFile?: string;
   plannerSessionId?: string;
+  workerSessionEvent?: WorkerSessionDiagnostic["event"];
+  workerSessionReason?: string;
+  workerSessionContextUsagePercent?: number;
+  workerSessionContextThresholdPercent?: number;
+  networkRecoveryEvent?: NetworkRecoveryEventType;
+  networkRetryCount?: number;
+  networkOutageElapsedMs?: number;
+  networkNextRetryAtMs?: number;
+  networkNextRetryInMs?: number;
+  networkFailureReason?: string;
 }
 
 export type CoordinatorProgressHandler = (update: CoordinatorProgressUpdate) => void;
@@ -146,12 +192,18 @@ export interface RunCoordinatorOptions extends PiLongTaskInput {
   maxBashTimeoutMs?: number;
   taskThinking?: string;
   todoThinking?: string;
+  /** Set false to retain the legacy one-session-per-task lifecycle. */
+  workerSessionReuse?: boolean;
+  /** Rotate before another assignment when context usage reaches this percentage. */
+  workerSessionReuseContextThresholdPercent?: number;
   now?: () => Date;
   onProgress?: CoordinatorProgressHandler;
   /** Run-scoped FIFO populated by the extension input handler during active execution. */
   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 {
@@ -170,6 +222,8 @@ export interface TodoPlannerOptions {
   plannerPrompt?: string;
   /** Structured revision context supplied alongside plannerPrompt. */
   planRevision?: Readonly<PlanRevisionRequest>;
+  /** Normalized coordinator recovery policy; network wait is excluded from operation timeouts. */
+  networkRecovery?: Readonly<NetworkRecoveryConfig>;
 }
 
 export interface TaskAttemptSummary {
@@ -190,6 +244,14 @@ export interface TaskAttemptSummary {
   resultText?: string;
 }
 
+export interface WorkerSessionMetrics {
+  starts: number;
+  reuses: number;
+  rotations: number;
+  retained: number;
+  rotationReasons: Record<string, number>;
+}
+
 export interface CoordinatorResult {
   status: CoordinatorStatus;
   summary: string;
@@ -210,6 +272,10 @@ export interface CoordinatorResult {
   attempts: TaskAttemptSummary[];
   taskProgress: TaskProgressModel;
   workerCostTotal: number;
+  /** Sum of task/attempt token deltas; omitted when statistics are unavailable. */
+  workerUsageTotal?: WorkerUsageTotals;
+  /** Additive lifecycle counters for adaptive worker-session reuse. */
+  workerSessionMetrics?: WorkerSessionMetrics;
   commit: boolean;
   goal?: string;
   error?: string;
@@ -236,9 +302,13 @@ interface RuntimeOptions {
   goal?: string;
   taskThinking: string;
   todoThinking: string;
+  workerSessionReuse: boolean;
+  workerSessionReuseContextThresholdPercent: number;
+  networkRecovery: NetworkRecoveryConfig;
   todoTimeoutMs: number;
   todoGracefulShutdownMs: number;
   workerRunner: WorkerRunner;
+  useRetainedWorkerLifecycle: boolean;
   todoPlanner: TodoPlanner;
   abortSignal?: AbortSignal;
   workerSessionFactory?: WorkerSessionFactory;
@@ -250,12 +320,636 @@ interface RuntimeOptions {
   workerTextByWorker: Map<string, string>;
   workerTextPublishedLengthByWorker: Map<string, number>;
   plannerDiagnostics: PlannerDiagnostic[];
+  workerSessionMetrics: WorkerSessionMetrics;
   steeringQueue?: SerializedSteeringQueue;
   onPlanRevisionAccepted?: (revision: GeneratedPlanRevision) => void | Promise<void>;
+  onNetworkRecovery?: (event: NetworkRecoveryEvent) => void;
+  lastProgress?: CoordinatorProgressUpdate;
+  progressClosed: boolean;
+  networkRecoverySequence: number;
+  activeNetworkRecoveries: Map<number, NetworkRecoveryEvent>;
+}
+
+type RetainedWorkerReuseScope = "sequential_task" | "partial_continuation";
+
+export interface WorkerAssignmentIdentity {
+  /** Unique invocation identity, even when a replacement reuses a task ID and attempt number. */
+  assignmentId: string;
+  /** Stable task identity or semantic fingerprint from the plan that launched this assignment. */
+  taskIdentity: string;
+  /** Accepted-steering generation at the assignment boundary. */
+  steeringGeneration: number;
+  /** Structural plan generation from which the assignment was selected. */
+  planAuthorityToken: string;
+}
+
+interface RetainedWorkerState {
+  resource: WorkerSessionResource;
+  compatibility: WorkerSessionCompatibilityFingerprint;
+  health: WorkerSessionHealth;
+  contextUsagePercent?: number;
+  previousTask: Pick<Task, "taskId" | "title">;
+  previousAttempt: number;
+  previousAssignmentIdentity: WorkerAssignmentIdentity;
+  reportDiagnostic: (diagnostic: WorkerSessionDiagnostic) => void;
+  reuseScope: RetainedWorkerReuseScope;
+}
+
+interface ActiveWorkerSessionAssignment {
+  identity: WorkerAssignmentIdentity;
+  controller: AbortController;
+  tainted: boolean;
+  rotationReported: boolean;
+  resource?: WorkerSessionResource;
+  reportDiagnostic?: (diagnostic: WorkerSessionDiagnostic) => void;
+  resolveCompletion: () => void;
+  completion: Promise<void>;
+}
+
+export interface CoordinatorWorkerSessionOwnerOptions {
+  runId: string;
+  cwd: string;
+  workerSessionReuse: boolean;
+  workerSessionReuseContextThresholdPercent: number;
+}
+
+/** Run-scoped owner for the single retained worker session and its assignment lock. */
+export class CoordinatorWorkerSessionOwner {
+  private retained: RetainedWorkerState | undefined;
+  private active: ActiveWorkerSessionAssignment | undefined;
+  private closed = false;
+  private disposePromise: Promise<void> | undefined;
+  private assignmentSequence = 0;
+  private readonly runtime: CoordinatorWorkerSessionOwnerOptions;
+
+  constructor(runtime: CoordinatorWorkerSessionOwnerOptions) {
+    this.runtime = runtime;
+  }
+
+  async run(options: RunWorkerTaskOptions, identity?: WorkerAssignmentIdentity): Promise<SessionOutcome> {
+    if (this.closed) {
+      throw new Error("retained worker session owner is closed");
+    }
+    const assignmentIdentity = identity ?? this.defaultIdentity(options);
+    if (this.active) {
+      throw new Error("retained worker session already has an active assignment");
+    }
+
+    let resolveCompletion: (() => void) | undefined;
+    const completion = new Promise<void>((resolve) => {
+      resolveCompletion = resolve;
+    });
+    const active: ActiveWorkerSessionAssignment = {
+      identity: assignmentIdentity,
+      controller: new AbortController(),
+      tainted: false,
+      rotationReported: false,
+      resolveCompletion: resolveCompletion as () => void,
+      completion,
+    };
+    this.active = active;
+    const assignmentOptions = {
+      ...options,
+      abortSignal: combineAbortSignals(options.abortSignal, active.controller.signal),
+    };
+    try {
+      return await this.runExclusive(assignmentOptions, assignmentIdentity, active);
+    } finally {
+      const activeResource = active.resource;
+      const retained = this.retained;
+      if (active.tainted && activeResource && retained?.resource === activeResource) {
+        retained.health = "cancelled";
+        await this.disposeRetainedResource(activeResource);
+      }
+      if (this.active === active) {
+        this.active = undefined;
+      }
+      active.resolveCompletion();
+    }
+  }
+
+  private async runExclusive(
+    options: RunWorkerTaskOptions,
+    identity: WorkerAssignmentIdentity,
+    active: ActiveWorkerSessionAssignment,
+  ): Promise<SessionOutcome> {
+    const compatibility = this.compatibilityFor(options);
+    const diagnostics: WorkerSessionDiagnostic[] = [];
+    const report = (diagnostic: WorkerSessionDiagnostic) => {
+      diagnostics.push(diagnostic);
+      options.onSessionDiagnostic?.(diagnostic);
+    };
+    active.reportDiagnostic = report;
+    const diagnosticContext = (retained: RetainedWorkerState) => ({
+      ...(retained.contextUsagePercent !== undefined ? { contextUsagePercent: retained.contextUsagePercent } : {}),
+      contextThresholdPercent: this.runtime.workerSessionReuseContextThresholdPercent,
+      previousTaskId: retained.previousTask.taskId,
+    });
+
+    let reusedFrom: Pick<Task, "taskId" | "title"> | undefined;
+    if (this.retained && !this.assignmentMatchesRetainedScope(options, this.retained)) {
+      // A partial-work session is continuity for exactly the next attempt of
+      // that task. It must never spill into unrelated work or a later retry.
+      report({
+        event: "session_rotated",
+        reasonCode: "partial_continuation_scope_mismatch",
+        ...diagnosticContext(this.retained),
+      });
+      await this.disposeRetained();
+    }
+    if (this.retained) {
+      const decision = decideWorkerSessionReuse({
+        config: {
+          enabled: this.runtime.workerSessionReuse,
+          contextThresholdPercent: this.runtime.workerSessionReuseContextThresholdPercent,
+        },
+        candidate: {
+          health: this.retained.health,
+          compatibility: this.retained.compatibility,
+          contextUsagePercent: this.retained.contextUsagePercent,
+          assignmentState: "idle",
+          disposed: this.retained.resource.disposed,
+        },
+        requestedCompatibility: compatibility,
+      });
+      if (decision.reusable) {
+        reusedFrom = this.retained.previousTask;
+        report({
+          event: "session_reused",
+          reasonCode: decision.reasonCode,
+          ...diagnosticContext(this.retained),
+        });
+      } else {
+        report({
+          event: "session_rotated",
+          reasonCode: decision.reasonCode,
+          ...diagnosticContext(this.retained),
+        });
+        await this.disposeRetained();
+      }
+    }
+
+    if (!this.retained) {
+      try {
+        this.retained = {
+          resource: await createWorkerSessionResource(options, options.sessionFactory ?? createIsolatedWorkerSession),
+          compatibility,
+          health: "healthy",
+          previousTask: options.task,
+          previousAttempt: options.attempt,
+          previousAssignmentIdentity: identity,
+          reportDiagnostic: report,
+          reuseScope: "sequential_task",
+        };
+        report({
+          event: "session_started",
+          reasonCode: diagnostics.some((item) => item.event === "session_rotated")
+            ? "rotation_completed"
+            : "fresh_session",
+          contextThresholdPercent: this.runtime.workerSessionReuseContextThresholdPercent,
+        });
+      } catch (error) {
+        const failed = buildWorkerSessionCreationFailureOutcome(options, error);
+        failed.sessionDiagnostics = diagnostics;
+        return failed;
+      }
+    }
+
+    active.resource = this.retained.resource;
+    let outcome: SessionOutcome;
+    try {
+      outcome = await runWorkerTaskAssignment(
+        options,
+        this.retained.resource,
+        reusedFrom ? { previousTask: reusedFrom } : undefined,
+      );
+    } catch (error) {
+      this.retained.health = active.tainted ? "cancelled" : "unrecoverable_error";
+      if (!active.rotationReported) {
+        active.rotationReported = true;
+        report({
+          event: "session_rotated",
+          reasonCode: "health_unrecoverable_error",
+          ...diagnosticContext(this.retained),
+        });
+      }
+      await this.disposeRetained();
+      throw error;
+    }
+
+    if (this.retained) {
+      const cancelled = Boolean(options.abortSignal?.aborted);
+      this.retained.health = workerSessionHealthForOutcome(outcome, cancelled);
+      this.retained.contextUsagePercent = await workerSessionContextUsagePercent(this.retained.resource.session);
+      this.retained.previousTask = options.task;
+      this.retained.previousAttempt = options.attempt;
+      this.retained.previousAssignmentIdentity = identity;
+      this.retained.reportDiagnostic = report;
+
+      if (active.tainted) {
+        if (!active.rotationReported) {
+          this.reportTaintedRotation(active, "assignment_cancelled");
+        }
+        await this.disposeRetainedResource(this.retained.resource);
+        outcome.sessionDiagnostics = [...(outcome.sessionDiagnostics ?? []), ...diagnostics];
+        return outcome;
+      }
+
+      const retry = classifyWorkerSessionRetry({
+        done: outcome.done,
+        reportedStatus: outcome.reportedStatus,
+        completeTaskResult: hasCompleteTaskResult(outcome.assistantText),
+        timedOut: outcome.timedOut,
+        aborted: outcome.aborted,
+        cancelled,
+        error: outcome.error,
+      });
+      this.retained.reuseScope = retry.mayContinueInSession ? "partial_continuation" : "sequential_task";
+
+      const postAssignmentDecision = decideWorkerSessionReuse({
+        config: {
+          enabled: this.runtime.workerSessionReuse,
+          contextThresholdPercent: this.runtime.workerSessionReuseContextThresholdPercent,
+        },
+        candidate: {
+          health: this.retained.health,
+          compatibility: this.retained.compatibility,
+          contextUsagePercent: this.retained.contextUsagePercent,
+          assignmentState: "idle",
+          disposed: this.retained.resource.disposed,
+        },
+        requestedCompatibility: compatibility,
+      });
+      // Completed tasks may flow into the next sequential TODO. A retry may
+      // remain only when it is an explicitly safe partial continuation and all
+      // normal health/compatibility/context checks still pass.
+      const rotateForRetry = !outcome.done && !retry.mayContinueInSession;
+      if (!postAssignmentDecision.reusable || rotateForRetry) {
+        if (!active.rotationReported) {
+          active.rotationReported = true;
+          report({
+            event: "session_rotated",
+            reasonCode: postAssignmentDecision.reusable ? retry.reasonCode : postAssignmentDecision.reasonCode,
+            ...diagnosticContext(this.retained),
+          });
+        }
+        await this.disposeRetained();
+      } else {
+        report({
+          event: "session_retained",
+          reasonCode: postAssignmentDecision.reasonCode,
+          ...diagnosticContext(this.retained),
+        });
+      }
+    }
+    outcome.sessionDiagnostics = [...(outcome.sessionDiagnostics ?? []), ...diagnostics];
+    return outcome;
+  }
+
+  /**
+   * Taint and abort only the matching obsolete assignment. Late cancellation
+   * from an older steering generation cannot affect a replacement assignment.
+   */
+  async invalidateAssignment(identity: WorkerAssignmentIdentity): Promise<boolean> {
+    const active = this.active;
+    if (active && sameWorkerAssignment(active.identity, identity)) {
+      this.taintActiveAssignment(active, "steering_revision_obsolete");
+      if (!active.controller.signal.aborted) {
+        active.controller.abort(new Error(`worker assignment ${identity.assignmentId} became obsolete`));
+      }
+      return true;
+    }
+
+    if (this.retained && sameWorkerAssignment(this.retained.previousAssignmentIdentity, identity)) {
+      const retained = this.retained;
+      retained.health = "cancelled";
+      retained.reportDiagnostic({
+        event: "session_rotated",
+        reasonCode: "steering_revision_obsolete",
+        ...this.diagnosticContext(retained),
+      });
+      await this.disposeRetained();
+      return true;
+    }
+    return false;
+  }
+
+  /** Abort active work, wait for its ownership path, then dispose retained state once. */
+  dispose(): Promise<void> {
+    if (!this.disposePromise) {
+      this.closed = true;
+      this.disposePromise = this.disposeAfterActiveAssignment();
+    }
+    return this.disposePromise;
+  }
+
+  private async disposeAfterActiveAssignment(): Promise<void> {
+    const active = this.active;
+    if (active) {
+      this.taintActiveAssignment(active, "coordinator_shutdown");
+      if (!active.controller.signal.aborted) {
+        active.controller.abort(new Error("worker session owner disposed"));
+      }
+      await active.completion;
+    }
+    await this.disposeRetained();
+  }
+
+  private assignmentMatchesRetainedScope(options: RunWorkerTaskOptions, retained: RetainedWorkerState): boolean {
+    if (retained.reuseScope === "sequential_task") {
+      return true;
+    }
+    return (
+      options.task.taskId === retained.previousTask.taskId &&
+      options.task.title === retained.previousTask.title &&
+      options.attempt === retained.previousAttempt + 1
+    );
+  }
+
+  private taintActiveAssignment(active: ActiveWorkerSessionAssignment, reasonCode: string): void {
+    active.tainted = true;
+    const retained = this.retained;
+    if (retained && retained.resource === active.resource) {
+      retained.health = "cancelled";
+    }
+    this.reportTaintedRotation(active, reasonCode);
+  }
+
+  private reportTaintedRotation(active: ActiveWorkerSessionAssignment, reasonCode: string): void {
+    if (active.rotationReported) return;
+    active.rotationReported = true;
+    const retained = this.retained;
+    active.reportDiagnostic?.({
+      event: "session_rotated",
+      reasonCode,
+      ...(retained ? this.diagnosticContext(retained) : {}),
+    });
+  }
+
+  private diagnosticContext(retained: RetainedWorkerState): {
+    contextUsagePercent?: number;
+    contextThresholdPercent: number;
+    previousTaskId: string;
+  } {
+    return {
+      ...(retained.contextUsagePercent !== undefined ? { contextUsagePercent: retained.contextUsagePercent } : {}),
+      contextThresholdPercent: this.runtime.workerSessionReuseContextThresholdPercent,
+      previousTaskId: retained.previousTask.taskId,
+    };
+  }
+
+  private defaultIdentity(options: RunWorkerTaskOptions): WorkerAssignmentIdentity {
+    const sequence = ++this.assignmentSequence;
+    return {
+      assignmentId: `${options.task.taskId}:${options.attempt}:${sequence}`,
+      taskIdentity: `${options.task.taskId}:${options.task.title}`,
+      steeringGeneration: 0,
+      planAuthorityToken: "direct-owner",
+    };
+  }
+
+  private compatibilityFor(options: RunWorkerTaskOptions): WorkerSessionCompatibilityFingerprint {
+    return createWorkerSessionCompatibilityFingerprint({
+      coordinatorRunId: this.runtime.runId,
+      repositoryRoot: this.runtime.cwd,
+      worktreeRoot: options.cwd,
+      modelName: options.modelName,
+      model: options.model,
+      tools: options.tools ?? DEFAULT_WORKER_TOOLS,
+      thinkingLevel: options.thinkingLevel,
+      agentDir: options.agentDir,
+      modelRuntime: options.modelRuntime,
+      authStorage: options.authStorage,
+      modelRegistry: options.modelRegistry,
+      settingsManager: options.settingsManager,
+      resourceLoader: options.resourceLoader,
+      sessionFactory: options.sessionFactory ?? createIsolatedWorkerSession,
+    });
+  }
+
+  private async disposeRetained(): Promise<void> {
+    const retained = this.retained;
+    if (!retained) {
+      return;
+    }
+    await this.disposeRetainedResource(retained.resource);
+  }
+
+  private async disposeRetainedResource(resource: WorkerSessionResource): Promise<void> {
+    if (this.retained?.resource === resource) {
+      this.retained = undefined;
+    }
+    try {
+      await disposeWorkerSessionResource(resource);
+    } catch {
+      // Session disposal is best effort; resource ownership is still closed exactly once.
+    }
+  }
+}
+
+function sameWorkerAssignment(left: WorkerAssignmentIdentity, right: WorkerAssignmentIdentity): boolean {
+  return (
+    left.assignmentId === right.assignmentId &&
+    left.taskIdentity === right.taskIdentity &&
+    left.steeringGeneration === right.steeringGeneration &&
+    left.planAuthorityToken === right.planAuthorityToken
+  );
+}
+
+function combineAbortSignals(...signals: Array<AbortSignal | undefined>): AbortSignal | undefined {
+  const available = signals.filter((signal): signal is AbortSignal => Boolean(signal));
+  if (available.length === 0) return undefined;
+  if (available.length === 1) return available[0];
+  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,
+): WorkerSessionHealth {
+  if (outcome.timedOut) return "timed_out";
+  if (cancelled) return "cancelled";
+  if (outcome.aborted) return "aborted";
+  if (outcome.error) return "unrecoverable_error";
+  if (!hasCompleteTaskResult(outcome.assistantText)) return "invalid_state";
+  return "healthy";
 }
 
 export async function runCoordinator(options: RunCoordinatorOptions): Promise<CoordinatorResult> {
   const runtime = buildRuntimeOptions(options);
+  const workerSessionOwner = runtime.useRetainedWorkerLifecycle
+    ? new CoordinatorWorkerSessionOwner(runtime)
+    : undefined;
   const inputText = coordinatorInputText(options);
   const attempts: TaskAttemptSummary[] = [];
   const outcomes: SessionOutcome[] = [];
@@ -269,6 +963,12 @@ export async function runCoordinator(options: RunCoordinatorOptions): Promise<Co
   let activeTask: Task | undefined;
   let activeTaskReference: PlanTaskReference | undefined;
   let activeAttempt: number | undefined;
+  let activeWorkerAssignment:
+    | { identity: WorkerAssignmentIdentity; controller: AbortController; obsolete: boolean }
+    | undefined;
+  let steeringGeneration = 0;
+  let workerExecutionSequence = 0;
+  let removeSteeringProcessor: (() => void) | undefined;
   const protectedDirtyPathsByTask = new Map<string, Set<string>>();
 
   try {
@@ -287,7 +987,7 @@ export async function runCoordinator(options: RunCoordinatorOptions): Promise<Co
     });
 
     let failure: string | undefined;
-    runtime.steeringQueue?.setProcessor(async (message) => {
+    removeSteeringProcessor = runtime.steeringQueue?.setProcessor(async (message) => {
       const baseAtRequest = planStore.snapshot();
       const activeTaskAtRequest = activeTaskReference
         ? resolvePlanTaskReference(
@@ -320,6 +1020,25 @@ export async function runCoordinator(options: RunCoordinatorOptions): Promise<Co
         // boundary, so this accepted revision continues the same run.
         latestTodoMarkdown = appliedRevision.todoMarkdown;
         latestTasks = appliedRevision.reconciliation.activeTasks.map((item) => item.task);
+        steeringGeneration += 1;
+
+        // Once replacement/removal is authoritative, make the exact old
+        // invocation obsolete before aborting it. Event callbacks consult this
+        // identity, so a late old result cannot repaint replacement progress.
+        const assignmentAtAcceptance = activeWorkerAssignment;
+        const activeStillValid = activeTaskReference
+          ? Boolean(resolvePlanTaskReference(latestTasks, activeTaskReference, planStore.snapshot().authorityToken))
+          : true;
+        if (assignmentAtAcceptance && !activeStillValid) {
+          assignmentAtAcceptance.obsolete = true;
+          if (!assignmentAtAcceptance.controller.signal.aborted) {
+            assignmentAtAcceptance.controller.abort(
+              new Error(`steering revision ${message.sequence} replaced the active assignment`),
+            );
+          }
+          await workerSessionOwner?.invalidateAssignment(assignmentAtAcceptance.identity);
+        }
+
         emitProgress(
           runtime,
           `Accepted steering revision ${message.sequence} with ${appliedRevision.reconciliation.activeTasks.length} task(s).`,
@@ -365,6 +1084,23 @@ export async function runCoordinator(options: RunCoordinatorOptions): Promise<Co
       const initialActivity =
         nextTask.statusItems.find((item) => !item.done)?.text ?? `Starting TODO ${nextTask.taskId}`;
       const worker = workerKey(nextTask.taskId, attempt);
+      // Task IDs and attempt numbers may be reused after an in-flight task is
+      // replaced by steering. Accounting needs an invocation identity so the
+      // obsolete attempt's finalized spend cannot be overwritten.
+      const accountingWorker = `${worker}#${++workerExecutionSequence}`;
+      const assignmentIdentity: WorkerAssignmentIdentity = {
+        assignmentId: accountingWorker,
+        taskIdentity: nextTask.stableId ?? taskSemanticFingerprint(nextTask),
+        steeringGeneration,
+        planAuthorityToken: schedulingSnapshot.authorityToken,
+      };
+      const assignmentController = new AbortController();
+      const assignmentState = { identity: assignmentIdentity, controller: assignmentController, obsolete: false };
+      const taskPlanReference = planTaskReference(nextTask, schedulingSnapshot.authorityToken);
+      activeWorkerAssignment = assignmentState;
+      activeTask = nextTask;
+      activeAttempt = attempt;
+      activeTaskReference = taskPlanReference;
       runtime.workerActivityByWorker.set(worker, initialActivity);
       runtime.workerTextByWorker.delete(worker);
       runtime.workerTextPublishedLengthByWorker.delete(worker);
@@ -393,11 +1129,7 @@ export async function runCoordinator(options: RunCoordinatorOptions): Promise<Co
           : new Set<string>();
         protectedDirtyPathsByTask.set(executionIdentity, preExistingDirtyPaths);
       }
-      activeTask = nextTask;
-      activeAttempt = attempt;
-      const taskPlanReference = planTaskReference(nextTask, schedulingSnapshot.authorityToken);
-      activeTaskReference = taskPlanReference;
-      const outcome = await runtime.workerRunner({
+      const workerOptions: RunWorkerTaskOptions = {
         cwd: runtime.cwd,
         todoPath: runtime.todoPath,
         task: nextTask,
@@ -415,12 +1147,62 @@ export async function runCoordinator(options: RunCoordinatorOptions): Promise<Co
         model: runtime.workerModel,
         modelName: runtime.workerModelName,
         thinkingLevel: runtime.taskThinking,
-        abortSignal: runtime.abortSignal,
+        abortSignal: combineAbortSignals(runtime.abortSignal, assignmentController.signal),
         sessionFactory: runtime.workerSessionFactory,
+        networkRecovery: runtime.networkRecovery,
         now: runtime.now,
-        onEvent: (event) => emitWorkerEventProgress(runtime, tasksBeforeAttempt, nextTask, attempts, attempt, event),
-      });
-      finalizeWorkerCost(runtime.workerCostState, outcome);
+        onEvent: (event) => {
+          if (activeWorkerAssignment === assignmentState && !assignmentState.obsolete) {
+            emitWorkerEventProgress(runtime, tasksBeforeAttempt, nextTask, attempts, attempt, event, accountingWorker);
+          }
+        },
+        onSessionDiagnostic: (diagnostic) => {
+          if (activeWorkerAssignment === assignmentState && !assignmentState.obsolete) {
+            emitWorkerSessionProgress(runtime, tasksBeforeAttempt, nextTask, attempts, attempt, diagnostic);
+          } else {
+            // Lifecycle accounting remains accurate, but obsolete diagnostics
+            // must not mutate the replacement task's visible progress.
+            recordWorkerSessionMetric(runtime.workerSessionMetrics, diagnostic);
+          }
+        },
+      };
+      let outcome: SessionOutcome;
+      const networkInterruptedOutcomes: SessionOutcome[] = [];
+      try {
+        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 = mergeWorkerRecoveryOutcomes(
+          networkInterruptedOutcomes,
+          buildWorkerSessionCreationFailureOutcome(workerOptions, error),
+        );
+        outcome.aborted = true;
+      }
+      finalizeWorkerCost(runtime.workerCostState, accountingWorker, outcome);
 
       // A revision may have been accepted while the worker was running. Let all
       // already-received guidance settle, then resolve this exact task identity
@@ -465,6 +1247,9 @@ export async function runCoordinator(options: RunCoordinatorOptions): Promise<Co
       activeTask = undefined;
       activeTaskReference = undefined;
       activeAttempt = undefined;
+      if (activeWorkerAssignment === assignmentState) {
+        activeWorkerAssignment = undefined;
+      }
 
       let taskCommitHash: string | undefined;
       let taskCommitError: string | undefined;
@@ -587,6 +1372,8 @@ export async function runCoordinator(options: RunCoordinatorOptions): Promise<Co
       attempts,
       taskProgress,
       workerCostTotal: runtime.workerCostState.total,
+      workerUsageTotal: aggregateWorkerUsage(outcomes),
+      workerSessionMetrics: snapshotWorkerSessionMetrics(runtime.workerSessionMetrics),
       commit: options.commit,
       goal: runtime.goal,
       error: failure,
@@ -668,6 +1455,8 @@ export async function runCoordinator(options: RunCoordinatorOptions): Promise<Co
       attempts,
       taskProgress,
       workerCostTotal: runtime.workerCostState.total,
+      workerUsageTotal: aggregateWorkerUsage(outcomes),
+      workerSessionMetrics: snapshotWorkerSessionMetrics(runtime.workerSessionMetrics),
       commit: options.commit,
       goal: runtime.goal,
       error: resultError,
@@ -680,6 +1469,11 @@ export async function runCoordinator(options: RunCoordinatorOptions): Promise<Co
       taskProgress,
     });
     return result;
+  } finally {
+    runtime.progressClosed = true;
+    runtime.activeNetworkRecoveries.clear();
+    removeSteeringProcessor?.();
+    await workerSessionOwner?.dispose();
   }
 }
 
@@ -749,19 +1543,59 @@ 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,
+      sessionFactory: runtime.todoSessionFactory,
+      networkRecovery: runtime.networkRecovery,
+      onDiagnostic: (diagnostic) => recordPlannerDiagnostic(runtime, diagnostic),
+      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 planner timeout;
+ * backoff remains governed solely by the separate outage deadline.
+ */
+async function runPlannerOperationWithNetworkRecovery(
+  plannerOptions: TodoPlannerOptions,
+  runtime: RuntimeOptions,
+): Promise<string> {
+  const run = (recoverySignal?: AbortSignal) =>
+    runtime.todoPlanner({
+      ...plannerOptions,
+      abortSignal: combineAbortSignals(plannerOptions.abortSignal, recoverySignal),
+    });
+
+  try {
+    return await run();
+  } catch (initialFailure) {
+    const classification = classifyNetworkFailure(initialFailure);
+    if (!runtime.networkRecovery.enabled || !classification.recoverable) {
+      throw initialFailure;
+    }
+    const recovered = await recoverNetworkOperation({
+      initialFailure,
+      config: runtime.networkRecovery,
+      signal: plannerOptions.abortSignal,
+      onEvent: createNetworkRecoveryProgressHandler(runtime),
+      retry: ({ signal }) => run(signal),
+    });
+    return recovered.value;
+  }
 }
 
 async function generateSteeringPlanRevision(options: {
@@ -794,21 +1628,25 @@ 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,
+          sessionFactory: options.runtime.todoSessionFactory,
+          networkRecovery: options.runtime.networkRecovery,
+          onDiagnostic: (diagnostic) => recordPlannerDiagnostic(options.runtime, diagnostic),
+          goal: options.runtime.goal,
+        },
+        options.runtime,
+      ),
   });
 }
 
@@ -1031,7 +1869,10 @@ async function runTodoPlannerPrompt(options: {
   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.";
@@ -1077,6 +1918,15 @@ function buildRuntimeOptions(options: RunCoordinatorOptions): RuntimeOptions {
   const workerModelName = options.workerModelName ?? parsedWorkerConfig.modelName;
   const workerModel = workerModelName ? undefined : options.workerModel;
   const goal = normalizeOptionalText(options.goal);
+  const workerSessionReuseConfig = resolveWorkerSessionReuseConfig({
+    enabled: options.workerSessionReuse ?? parsedWorkerConfig.workerSessionReuseEnabled,
+    contextThresholdPercent:
+      options.workerSessionReuseContextThresholdPercent ?? parsedWorkerConfig.workerSessionReuseContextThresholdPercent,
+  });
+  const networkRecovery = resolveNetworkRecoveryConfig({
+    ...parsedWorkerConfig.networkRecovery,
+    ...options.networkRecovery,
+  });
 
   return {
     cwd,
@@ -1098,7 +1948,11 @@ function buildRuntimeOptions(options: RunCoordinatorOptions): RuntimeOptions {
     goal,
     taskThinking: options.taskThinking ?? DEFAULT_COORDINATOR_OPTIONS.taskThinking,
     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,
     abortSignal: options.abortSignal,
     workerSessionFactory: options.workerSessionFactory,
@@ -1110,8 +1964,13 @@ function buildRuntimeOptions(options: RunCoordinatorOptions): RuntimeOptions {
     workerTextByWorker: new Map(),
     workerTextPublishedLengthByWorker: new Map(),
     plannerDiagnostics: [],
+    workerSessionMetrics: createWorkerSessionMetrics(),
     steeringQueue: options.steeringQueue,
     onPlanRevisionAccepted: options.onPlanRevisionAccepted,
+    onNetworkRecovery: options.onNetworkRecovery,
+    progressClosed: false,
+    networkRecoverySequence: 0,
+    activeNetworkRecoveries: new Map(),
   };
 }
 
@@ -1120,7 +1979,8 @@ function emitProgress(
   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,
@@ -1128,9 +1988,107 @@ function emitProgress(
     workerCostTotal: runtime.workerCostState.total,
     ...update,
     goal: runtime.goal,
+  };
+  runtime.lastProgress = progress;
+  const activeRecovery = latestNetworkRecovery(runtime.activeNetworkRecoveries);
+  if (activeRecovery) {
+    publishNetworkRecoveryProgress(runtime, activeRecovery);
+  } 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): (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);
+        } else if (runtime.lastProgress) {
+          runtime.onProgress?.({ ...runtime.lastProgress, workerCostTotal: runtime.workerCostState.total });
+        }
+      }
+      return;
+    }
+
+    runtime.activeNetworkRecoveries.set(operationId, event);
+    if (operationId === latestNetworkRecoveryId(runtime.activeNetworkRecoveries)) {
+      publishNetworkRecoveryProgress(runtime, event);
+    }
+  };
+}
+
+function publishNetworkRecoveryProgress(runtime: RuntimeOptions, event: NetworkRecoveryEvent): void {
+  if (runtime.progressClosed) return;
+  const stable = runtime.lastProgress;
+  const nowMs = event.state.outageStartedAtMs + event.state.elapsedMs;
+  const message = formatNetworkRecoveryStatus(event);
+  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,
   });
 }
 
+function latestNetworkRecovery(
+  recoveries: ReadonlyMap<number, NetworkRecoveryEvent>,
+): NetworkRecoveryEvent | undefined {
+  const id = latestNetworkRecoveryId(recoveries);
+  return id === undefined ? undefined : recoveries.get(id);
+}
+
+function latestNetworkRecoveryId(recoveries: ReadonlyMap<number, NetworkRecoveryEvent>): 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 recordPlannerDiagnostic(runtime: RuntimeOptions, diagnostic: PlannerDiagnostic): void {
   const normalized: PlannerDiagnostic = {
     kind: diagnostic.kind,
@@ -1156,6 +2114,41 @@ function recordPlannerDiagnostic(runtime: RuntimeOptions, diagnostic: PlannerDia
   });
 }
 
+function aggregateWorkerUsage(outcomes: readonly SessionOutcome[]): WorkerUsageTotals | undefined {
+  const usage = outcomes.flatMap((outcome) => (outcome.workerUsage ? [outcome.workerUsage] : []));
+  if (usage.length === 0) {
+    return undefined;
+  }
+  return usage.reduce<WorkerUsageTotals>(
+    (total, item) => ({
+      input: total.input + item.input,
+      output: total.output + item.output,
+      cacheRead: total.cacheRead + item.cacheRead,
+      cacheWrite: total.cacheWrite + item.cacheWrite,
+      total: total.total + item.total,
+    }),
+    { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+  );
+}
+
+function createWorkerSessionMetrics(): WorkerSessionMetrics {
+  return { starts: 0, reuses: 0, rotations: 0, retained: 0, rotationReasons: {} };
+}
+
+function snapshotWorkerSessionMetrics(metrics: WorkerSessionMetrics): WorkerSessionMetrics {
+  return { ...metrics, rotationReasons: { ...metrics.rotationReasons } };
+}
+
+function recordWorkerSessionMetric(metrics: WorkerSessionMetrics, diagnostic: WorkerSessionDiagnostic): void {
+  if (diagnostic.event === "session_started") metrics.starts += 1;
+  if (diagnostic.event === "session_reused") metrics.reuses += 1;
+  if (diagnostic.event === "session_retained") metrics.retained += 1;
+  if (diagnostic.event === "session_rotated") {
+    metrics.rotations += 1;
+    metrics.rotationReasons[diagnostic.reasonCode] = (metrics.rotationReasons[diagnostic.reasonCode] ?? 0) + 1;
+  }
+}
+
 function createWorkerCostState(): WorkerCostState {
   return {
     total: 0,
@@ -1192,9 +2185,9 @@ function recordLiveWorkerCost(
 
 function finalizeWorkerCost(
   state: WorkerCostState,
-  outcome: Pick<SessionOutcome, "task" | "attempt" | "workerCostTotal">,
+  worker: string,
+  outcome: Pick<SessionOutcome, "workerCostTotal">,
 ): void {
-  const worker = workerKey(outcome.task.taskId, outcome.attempt);
   state.finalizedByWorker.set(worker, finiteNonNegativeNumber(outcome.workerCostTotal) ?? 0);
   state.liveByWorker.delete(worker);
   for (const messageKey of state.liveByMessage.keys()) {
@@ -1263,6 +2256,43 @@ function subtaskProgress(
   });
 }
 
+function emitWorkerSessionProgress(
+  runtime: RuntimeOptions,
+  tasks: readonly Task[],
+  task: Pick<Task, "taskId" | "title" | "statusItems">,
+  attempts: readonly TaskAttemptSummary[],
+  attempt: number,
+  diagnostic: WorkerSessionDiagnostic,
+): void {
+  recordWorkerSessionMetric(runtime.workerSessionMetrics, diagnostic);
+  const contextText =
+    diagnostic.contextUsagePercent === undefined
+      ? ""
+      : ` at ${diagnostic.contextUsagePercent.toFixed(1)}% context usage`;
+  const action =
+    diagnostic.event === "session_started"
+      ? "started"
+      : diagnostic.event === "session_reused"
+        ? "reused"
+        : diagnostic.event === "session_rotated"
+          ? "rotated"
+          : "retained";
+  emitProgress(runtime, `Worker session ${action}${contextText} (${diagnostic.reasonCode}).`, {
+    phase: "worker_session",
+    taskId: task.taskId,
+    title: task.title,
+    attempt,
+    status: "in_progress",
+    activeStatus: `Worker session ${action}`,
+    workerSessionEvent: diagnostic.event,
+    workerSessionReason: diagnostic.reasonCode,
+    workerSessionContextUsagePercent: diagnostic.contextUsagePercent,
+    workerSessionContextThresholdPercent: diagnostic.contextThresholdPercent,
+    ...currentTaskProgress(task, "in_progress"),
+    taskProgress: buildTaskProgressModel({ tasks, attempts, currentTaskId: task.taskId }),
+  });
+}
+
 function emitWorkerEventProgress(
   runtime: RuntimeOptions,
   tasks: readonly Task[],
@@ -1278,6 +2308,7 @@ function emitWorkerEventProgress(
     usageCostTotal?: number;
     usageCostKey?: string;
   },
+  accountingWorker = workerKey(task.taskId, attempt),
 ): void {
   const worker = workerKey(task.taskId, attempt);
   let activeStatus = runtime.workerActivityByWorker.get(worker);
@@ -1318,7 +2349,7 @@ function emitWorkerEventProgress(
   }
 
   const costChanged =
-    event.usageCostTotal !== undefined && recordLiveWorkerCost(runtime.workerCostState, worker, event);
+    event.usageCostTotal !== undefined && recordLiveWorkerCost(runtime.workerCostState, accountingWorker, event);
 
   if (event.type === "message_end" && event.activity) {
     emitProgress(runtime, event.activity, {
@@ -1390,7 +2421,7 @@ function emitWorkerEventProgress(
 }
 
 function stripToolOutcomePrefix(activity: string): string {
-  return activity.replace(/^(?:(?:Finished|Failed):\s*)+/i, "");
+  return activity.trim().replace(/^(?:(?:Finished|Failed):\s*)+/i, "");
 }
 
 function activeStatusFromWorkerText(text: string): string {
@@ -1591,6 +2622,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,
@@ -1629,6 +2697,25 @@ async function appendTaskResult(
   if (outcome.contextObservations.length > 0) {
     lines.push("", "Context observations:", ...outcome.contextObservations.map((item) => `- ${item}`));
   }
+  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}`,
+    );
+  }
+  if (outcome.sessionDiagnostics?.length) {
+    lines.push(
+      "",
+      "Worker session diagnostics:",
+      ...outcome.sessionDiagnostics.map((item) => {
+        const context =
+          item.contextUsagePercent === undefined ? "" : ` context=${item.contextUsagePercent.toFixed(1)}%`;
+        return `- event=${item.event} reason=${item.reasonCode}${context}`;
+      }),
+    );
+  }
   if (outcome.compactionEvents.length > 0) {
     lines.push("", "Compaction events:", ...outcome.compactionEvents.map((item) => `- ${item}`));
   }