pi-long-task 0.5.0 → 0.6.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 {
@@ -79,6 +91,7 @@ export const DEFAULT_COORDINATOR_OPTIONS = {
   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>;
@@ -88,6 +101,7 @@ export type CoordinatorProgressPhase =
   | "task_start"
   | "worker_session"
   | "worker_tool"
+  | "network_wait"
   | "task_done"
   | "task_blocked"
   | "task_failed"
@@ -150,6 +164,12 @@ export interface CoordinatorProgressUpdate {
   workerSessionReason?: string;
   workerSessionContextUsagePercent?: number;
   workerSessionContextThresholdPercent?: number;
+  networkRecoveryEvent?: NetworkRecoveryEventType;
+  networkRetryCount?: number;
+  networkOutageElapsedMs?: number;
+  networkNextRetryAtMs?: number;
+  networkNextRetryInMs?: number;
+  networkFailureReason?: string;
 }
 
 export type CoordinatorProgressHandler = (update: CoordinatorProgressUpdate) => void;
@@ -182,6 +202,8 @@ 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 {
@@ -200,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 {
@@ -280,6 +304,7 @@ interface RuntimeOptions {
   todoThinking: string;
   workerSessionReuse: boolean;
   workerSessionReuseContextThresholdPercent: number;
+  networkRecovery: NetworkRecoveryConfig;
   todoTimeoutMs: number;
   todoGracefulShutdownMs: number;
   workerRunner: WorkerRunner;
@@ -298,6 +323,11 @@ interface RuntimeOptions {
   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";
@@ -733,6 +763,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,
@@ -949,6 +1149,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 +1167,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);
@@ -1248,6 +1470,8 @@ export async function runCoordinator(options: RunCoordinatorOptions): Promise<Co
     });
     return result;
   } finally {
+    runtime.progressClosed = true;
+    runtime.activeNetworkRecoveries.clear();
     removeSteeringProcessor?.();
     await workerSessionOwner?.dispose();
   }
@@ -1319,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: {
@@ -1364,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,
+      ),
   });
 }
 
@@ -1601,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.";
@@ -1652,6 +1923,10 @@ function buildRuntimeOptions(options: RunCoordinatorOptions): RuntimeOptions {
     contextThresholdPercent:
       options.workerSessionReuseContextThresholdPercent ?? parsedWorkerConfig.workerSessionReuseContextThresholdPercent,
   });
+  const networkRecovery = resolveNetworkRecoveryConfig({
+    ...parsedWorkerConfig.networkRecovery,
+    ...options.networkRecovery,
+  });
 
   return {
     cwd,
@@ -1675,6 +1950,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,
@@ -1691,6 +1967,10 @@ function buildRuntimeOptions(options: RunCoordinatorOptions): RuntimeOptions {
     workerSessionMetrics: createWorkerSessionMetrics(),
     steeringQueue: options.steeringQueue,
     onPlanRevisionAccepted: options.onPlanRevisionAccepted,
+    onNetworkRecovery: options.onNetworkRecovery,
+    progressClosed: false,
+    networkRecoverySequence: 0,
+    activeNetworkRecoveries: new Map(),
   };
 }
 
@@ -1699,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,
@@ -1707,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,
@@ -2243,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,

package/src/goal_discovery.ts

@@ -13,6 +13,7 @@ import {
 } from "./goal_spec.ts";
 import type { GoalLoopState } from "./goal_loop.ts";
 import type { GoalStateStore } from "./goal_state.ts";
+import type { NetworkRecoveryConfig } from "./network_recovery_config.ts";
 
 export type GoalDiscoveryEntrypoint = "pi_goal_task" | "pi_long_task";
 export type GoalDiscoveryRoute = "discovery" | "direct";
@@ -41,6 +42,7 @@ export interface GoalDiscoveryRunnerOptions {
   model?: unknown;
   modelName?: string;
   thinkingLevel?: string;
+  networkRecovery?: Readonly<NetworkRecoveryConfig>;
   now: () => Date;
 }