pi-long-task 0.5.0 → 0.7.0

package/src/types.ts

@@ -1,9 +1,41 @@
 import type { Static } from "typebox";
 import { Type } from "typebox";
 
+import { MAX_PLANNER_DURATION_MS, type PlannerBudget } from "./planner_config.ts";
 import type { TaskProgressModel } from "./task_progress.ts";
+import type { WorkerCapabilityWarning } from "./worker_capabilities.ts";
 import type { SessionOutcome } from "./worker_session.ts";
 
+const NetworkRecoveryParams = Type.Object(
+  {
+    enabled: Type.Optional(
+      Type.Boolean({
+        description:
+          "Enable coordinator-level recovery after Pi's bounded provider retries are exhausted. Defaults to false for backward compatibility.",
+      }),
+    ),
+    baseDelayMs: Type.Optional(
+      Type.Integer({
+        minimum: 1,
+        description: "Initial network-recovery delay in milliseconds. Defaults to 1000.",
+      }),
+    ),
+    maxDelayMs: Type.Optional(
+      Type.Integer({
+        minimum: 1,
+        description: "Maximum network-recovery backoff delay in milliseconds. Defaults to 30000.",
+      }),
+    ),
+    maxOutageMs: Type.Optional(
+      Type.Union([Type.Integer({ minimum: 1 }), Type.Null()], {
+        description:
+          "Maximum continuous outage duration in milliseconds. Defaults to 300000; use null to wait indefinitely until cancelled.",
+      }),
+    ),
+  },
+  { additionalProperties: false },
+);
+
 export const PiLongTaskParams = Type.Object(
   {
     inputText: Type.Optional(
@@ -21,6 +53,23 @@ export const PiLongTaskParams = Type.Object(
         description: "Optional high-level goal or desired outcome for the long-task run.",
       }),
     ),
+    todoTimeoutMs: Type.Optional(
+      Type.Integer({
+        minimum: 1,
+        maximum: MAX_PLANNER_DURATION_MS,
+        description:
+          "Explicit TODO-planner timeout in milliseconds. When omitted, the 5-minute default adapts deterministically for explicit item counts, enumerated deliverables, and separately planned tasks, up to 15 minutes.",
+      }),
+    ),
+    todoGracefulShutdownMs: Type.Optional(
+      Type.Integer({
+        minimum: 0,
+        maximum: MAX_PLANNER_DURATION_MS,
+        description:
+          "Grace period in milliseconds after the TODO-planner timeout. Defaults to 15000 (15 seconds); use 0 to disable the grace period.",
+      }),
+    ),
+    networkRecovery: Type.Optional(NetworkRecoveryParams),
   },
   { additionalProperties: false },
 );
@@ -82,6 +131,23 @@ export const PiGoalTaskParams = Type.Object(
         description: "Maximum bash command timeout in milliseconds allowed in worker sessions.",
       }),
     ),
+    todoTimeoutMs: Type.Optional(
+      Type.Integer({
+        minimum: 1,
+        maximum: MAX_PLANNER_DURATION_MS,
+        description:
+          "Explicit TODO-planner timeout in milliseconds for child long-task planning and plan revisions. When omitted, the 5-minute default adapts deterministically for explicit item counts, enumerated deliverables, and separately planned tasks, up to 15 minutes.",
+      }),
+    ),
+    todoGracefulShutdownMs: Type.Optional(
+      Type.Integer({
+        minimum: 0,
+        maximum: MAX_PLANNER_DURATION_MS,
+        description:
+          "Grace period in milliseconds after a child TODO-planner timeout. Defaults to 15000 (15 seconds); use 0 to disable the grace period.",
+      }),
+    ),
+    networkRecovery: Type.Optional(NetworkRecoveryParams),
   },
   { additionalProperties: false },
 );
@@ -133,6 +199,8 @@ export interface PiLongTaskResult {
   }>;
   taskProgress: TaskProgressModel;
   workerCostTotal: number;
+  plannerBudget?: Readonly<PlannerBudget>;
+  capabilityWarnings?: readonly WorkerCapabilityWarning[];
   commit: boolean;
   goal?: string;
   error?: string;

package/src/worker_capabilities.ts

@@ -0,0 +1,103 @@
+export interface IsolatedWorkerCapabilities {
+  /** Tool names exposed directly to the worker session. */
+  tools: readonly string[];
+  /** Pi Long Task isolated sessions deliberately disable extension runtimes. */
+  extensionsEnabled: boolean;
+}
+
+export type WorkerCapabilityWarningCode = "unavailable_browser_capability";
+
+export interface WorkerCapabilityWarning {
+  code: WorkerCapabilityWarningCode;
+  requestedCapabilities: readonly string[];
+  availableTools: readonly string[];
+  message: string;
+  planningConstraint: string;
+}
+
+const BROWSER_EXTENSION_REQUIREMENT_RE =
+  /\b(?:must(?:\s+use)?|need(?:s|ed)?(?:\s+to\s+use)?|require(?:s|d)?|rely(?:ing)?\s+on|use|using|via|through|with)\s+(?:the\s+|an?\s+)?(?:google\s+)?(?:chrome|chromium|firefox|edge|browser)(?:\s+(?:browser|devtools?))?\s+(?:extension|mcp|connector)\b/i;
+const REQUIRED_NAMED_BROWSER_EXTENSION_RE =
+  /\b(?:chrome\s+devtools\s+(?:mcp|extension|tool)|(?:chrome|browser)\s+(?:mcp|extension(?:\s+tool)?|tool\s+extension))\s+(?:is\s+(?:required|needed)|must\s+be\s+used)\b/i;
+const IMPERATIVE_CHROME_RE =
+  /\b(?:open|launch|control|drive|browse\s+with|inspect\s+(?:with|using)|scrape\s+(?:with|using)|fetch\s+(?:with|using)|test\s+(?:with|using))\s+(?:google\s+)?chrome\b/i;
+const EXPLICIT_BROWSER_TOOL_RE =
+  /\b(?:must(?:\s+use)?|need(?:s|ed)?(?:\s+to\s+use)?|require(?:s|d)?|use|using|via|through|with)\s+(?:the\s+)?(browser|chrome|web[_-]?fetch|playwright|puppeteer)\s+tool\b/i;
+const EXPLICIT_CHROME_RUNTIME_RE =
+  /(?:\b(?:must\s+use|need(?:s|ed)?\s+to\s+use|use|using)\s+(?:google\s+)?chrome(?:\s+devtools?)?(?=\s+(?:to|for)\b|\s*[.,;:]|\s*$)|\b(?:via|through)\s+(?:google\s+)?chrome\b|\b(?:google\s+)?chrome(?:\s+devtools?)?\s+(?:is\s+required|must\s+be\s+used)\b)/i;
+const NEGATED_CAPABILITY_RE =
+  /\b(?:do\s+not|don't|dont|never|avoid|without)\s+(?:use|using|rely(?:ing)?\s+on|requiring?)?\s*(?:the\s+|an?\s+)?(?:google\s+)?(?:chrome(?:\s+(?:browser|devtools?))?|chromium|firefox|edge|browser|web[_-]?fetch|playwright|puppeteer)(?:\s+(?:extension|mcp|tool(?:ing)?|connector))?/gi;
+
+/**
+ * Detect only explicit requests to invoke a browser capability. Merely asking
+ * workers to build or support a browser extension is implementation work and
+ * does not imply that the extension must be loaded during the run.
+ */
+export function detectUnavailableWorkerCapabilities(
+  requestText: string,
+  capabilities: Readonly<IsolatedWorkerCapabilities>,
+): WorkerCapabilityWarning[] {
+  const text = requestText.replace(NEGATED_CAPABILITY_RE, " ");
+  const extensionRequested =
+    BROWSER_EXTENSION_REQUIREMENT_RE.test(text) ||
+    REQUIRED_NAMED_BROWSER_EXTENSION_RE.test(text) ||
+    IMPERATIVE_CHROME_RE.test(text);
+  const browserToolMatch = EXPLICIT_BROWSER_TOOL_RE.exec(text);
+  const requestedDirectTools = [
+    browserToolMatch?.[1],
+    EXPLICIT_CHROME_RUNTIME_RE.test(text) ? "chrome" : undefined,
+  ].filter((item, index, all): item is string => Boolean(item) && all.indexOf(item) === index);
+  const unavailableDirectTools = requestedDirectTools.filter(
+    (requested) =>
+      !capabilities.tools.some((available) => canonicalToolName(available) === canonicalToolName(requested)),
+  );
+
+  if ((!extensionRequested || capabilities.extensionsEnabled) && unavailableDirectTools.length === 0) {
+    return [];
+  }
+
+  const requestedCapabilities = [
+    extensionRequested && !capabilities.extensionsEnabled ? "Chrome/browser extension runtime" : undefined,
+    unavailableDirectTools.length > 0 ? `${unavailableDirectTools.join("/")} direct tool` : undefined,
+  ].filter((item): item is string => Boolean(item));
+  const availableTools = [...capabilities.tools];
+  const toolList = availableTools.length > 0 ? availableTools.join(", ") : "none";
+  const alternatives = availableWorkerAlternatives(capabilities);
+  const alternativeText = alternatives.join(", or ");
+
+  return [
+    {
+      code: "unavailable_browser_capability",
+      requestedCapabilities,
+      availableTools,
+      message:
+        `Worker capability warning: isolated Pi Long Task workers disable extensions and expose only these direct tools: ${toolList}. ` +
+        `They cannot silently use the requested ${requestedCapabilities.join(" or ")}. The run will continue, but it must use an available safe alternative when that satisfies the request: ${alternativeText}. ` +
+        "If the exact extension or browser tool is mandatory, the affected task must report blocked instead of claiming it used that capability.",
+      planningConstraint:
+        `Isolated-worker capability constraint: extensions are disabled and workers have only these direct tools: ${toolList}. ` +
+        `Do not create or execute tasks that assume the requested ${requestedCapabilities.join(" or ")} is available, and never claim it was used. ` +
+        `When equivalent, ${alternativeText}. If the exact unavailable capability is mandatory, make the affected task report blocked with the required user action.`,
+    },
+  ];
+}
+
+function canonicalToolName(tool: string): string {
+  return tool.toLowerCase().replace(/[-_]/g, "");
+}
+
+function availableWorkerAlternatives(capabilities: Readonly<IsolatedWorkerCapabilities>): string[] {
+  const alternatives: string[] = [];
+  if (capabilities.tools.includes("bash")) {
+    alternatives.push(
+      "fetch public content through a supported command-line mechanism via bash or run project-provided browser automation via bash when available",
+    );
+  }
+  if (capabilities.tools.includes("read")) {
+    alternatives.push("supply the page or source content to the run so workers can read it locally");
+  }
+  if (alternatives.length === 0) {
+    alternatives.push("supply the needed source content to the run");
+  }
+  return alternatives;
+}

package/src/worker_config.ts

@@ -1,10 +1,20 @@
+import {
+  NetworkRecoveryConfigError,
+  resolveNetworkRecoveryConfig,
+  type NetworkRecoveryConfigInput,
+} from "./network_recovery_config.ts";
+import { MAX_PLANNER_DURATION_MS, PlannerDurationConfigError } from "./planner_config.ts";
+
 export interface ParsedWorkerRuntimeConfig {
   modelName?: string;
   maxAttemptsPerTask?: number;
   taskTimeoutMs?: number;
+  todoTimeoutMs?: number;
+  todoGracefulShutdownMs?: number;
   maxBashTimeoutMs?: number;
   workerSessionReuseEnabled?: boolean;
   workerSessionReuseContextThresholdPercent?: number;
+  networkRecovery?: NetworkRecoveryConfigInput;
 }
 
 type MutableWorkerRuntimeConfig = ParsedWorkerRuntimeConfig & { provider?: string; model?: string };
@@ -36,12 +46,17 @@ export function parseWorkerRuntimeConfig(text: string): ParsedWorkerRuntimeConfi
 
   parseLineDirectives(text, state);
   parseNaturalLanguageDirectives(text, state);
+  if (state.networkRecovery) {
+    resolveNetworkRecoveryConfig(state.networkRecovery);
+  }
 
   const modelName = combineProviderAndModel(state.provider, state.model);
   return {
     ...(modelName ? { modelName } : {}),
     ...(state.maxAttemptsPerTask !== undefined ? { maxAttemptsPerTask: state.maxAttemptsPerTask } : {}),
     ...(state.taskTimeoutMs !== undefined ? { taskTimeoutMs: state.taskTimeoutMs } : {}),
+    ...(state.todoTimeoutMs !== undefined ? { todoTimeoutMs: state.todoTimeoutMs } : {}),
+    ...(state.todoGracefulShutdownMs !== undefined ? { todoGracefulShutdownMs: state.todoGracefulShutdownMs } : {}),
     ...(state.maxBashTimeoutMs !== undefined ? { maxBashTimeoutMs: state.maxBashTimeoutMs } : {}),
     ...(state.workerSessionReuseEnabled !== undefined
       ? { workerSessionReuseEnabled: state.workerSessionReuseEnabled }
@@ -49,6 +64,7 @@ export function parseWorkerRuntimeConfig(text: string): ParsedWorkerRuntimeConfi
     ...(state.workerSessionReuseContextThresholdPercent !== undefined
       ? { workerSessionReuseContextThresholdPercent: state.workerSessionReuseContextThresholdPercent }
       : {}),
+    ...(state.networkRecovery ? { networkRecovery: { ...state.networkRecovery } } : {}),
   };
 }
 
@@ -124,14 +140,36 @@ function parseNaturalLanguageDirectives(text: string, state: MutableWorkerRuntim
 
   captureDurations(
     text,
-    /\b(?<!bash\s)(?<!max\s)(?:worker\s+|task\s+)?timeout\s*(?:is|=|:|to|of)?\s*(\d+(?:\.\d+)?\s*(?:milliseconds?|msecs?|ms|seconds?|secs?|s|minutes?|mins?|m|hours?|hrs?|h)?)/gi,
+    /\b(?:todo\s+)?(?:planner|planning)\s+timeout\s*(?:is|=|:|to|of)?\s*(\d+(?:\.\d+)?\s*(?:milliseconds?|msecs?|ms|seconds?|secs?|s|minutes?|mins?|m|hours?|hrs?|h)?)/gi,
+    (value) => {
+      state.todoTimeoutMs = value;
+    },
+  );
+  captureDurations(
+    text,
+    /\b(\d+(?:\.\d+)?\s*(?:milliseconds?|msecs?|ms|seconds?|secs?|s|minutes?|mins?|m|hours?|hrs?|h))\s+(?:todo\s+)?(?:planner|planning)\s+timeout\b/gi,
+    (value) => {
+      state.todoTimeoutMs = value;
+    },
+  );
+  captureDurations(
+    text,
+    /\b(?:todo\s+)?(?:planner|planning)\s+(?:grace(?:ful)?(?:\s+shutdown|\s+period)?|shutdown\s+grace(?:\s+period)?)\s*(?:duration\s*)?(?:is|=|:|to|of)?\s*(\d+(?:\.\d+)?\s*(?:milliseconds?|msecs?|ms|seconds?|secs?|s|minutes?|mins?|m|hours?|hrs?|h)?)/gi,
+    (value) => {
+      state.todoGracefulShutdownMs = value;
+    },
+    { allowZero: true },
+  );
+  captureDurations(
+    text,
+    /\b(?<!bash\s)(?<!max\s)(?<!planner\s)(?<!planning\s)(?:worker\s+|task\s+)?timeout\s*(?:is|=|:|to|of)?\s*(\d+(?:\.\d+)?\s*(?:milliseconds?|msecs?|ms|seconds?|secs?|s|minutes?|mins?|m|hours?|hrs?|h)?)/gi,
     (value) => {
       state.taskTimeoutMs = value;
     },
   );
   captureDurations(
     text,
-    /\b(\d+(?:\.\d+)?\s*(?:milliseconds?|msecs?|ms|seconds?|secs?|s|minutes?|mins?|m|hours?|hrs?|h))\s+(?:worker\s+|task\s+)?timeout\b/gi,
+    /\b(\d+(?:\.\d+)?\s*(?:milliseconds?|msecs?|ms|seconds?|secs?|s|minutes?|mins?|m|hours?|hrs?|h))[ \t]+(?:worker[ \t]+|task[ \t]+)?timeout\b/gi,
     (value) => {
       state.taskTimeoutMs = value;
     },
@@ -159,6 +197,11 @@ function parseNaturalLanguageDirectives(text: string, state: MutableWorkerRuntim
 }
 
 function applyDirective(key: string, value: string, state: MutableWorkerRuntimeConfig): void {
+  if (/\bnetwork\b/.test(key) && /\brecover(?:y|ies)?\b/.test(key)) {
+    applyNetworkRecoveryDirective(key, value, state);
+    return;
+  }
+
   if (/\breuse\b/.test(key) && /\b(?:threshold|context)\b/.test(key)) {
     const threshold = percentageFromText(value);
     if (threshold !== undefined) {
@@ -199,6 +242,16 @@ function applyDirective(key: string, value: string, state: MutableWorkerRuntimeC
     return;
   }
 
+  if (/\b(?:planner|planning)\b/.test(key) && /\b(?:grace|graceful|shutdown)\b/.test(key)) {
+    state.todoGracefulShutdownMs = requiredPlannerDuration("graceful-shutdown duration", value, true);
+    return;
+  }
+
+  if (/\b(?:planner|planning)\b/.test(key) && /\btimeout\b/.test(key)) {
+    state.todoTimeoutMs = requiredPlannerDuration("timeout", value, false);
+    return;
+  }
+
   if (/\bbash\b/.test(key) && /\btimeout\b/.test(key)) {
     const timeout = durationMsFromText(value, { allowBareSeconds: true });
     if (timeout !== undefined) {
@@ -215,6 +268,81 @@ function applyDirective(key: string, value: string, state: MutableWorkerRuntimeC
   }
 }
 
+function applyNetworkRecoveryDirective(key: string, value: string, state: MutableWorkerRuntimeConfig): void {
+  const recovery = (state.networkRecovery ??= {});
+
+  if (/\bbase\b/.test(key) && /\bdelay\b/.test(key)) {
+    recovery.baseDelayMs = requiredNetworkRecoveryDuration("base delay", value);
+    return;
+  }
+  if (/\bmax(?:imum)?\b/.test(key) && /\bdelay\b/.test(key)) {
+    recovery.maxDelayMs = requiredNetworkRecoveryDuration("maximum delay", value);
+    return;
+  }
+  if (/\b(?:outage|duration|wait)\b/.test(key)) {
+    const normalized = trimDirectiveValue(value)
+      .toLowerCase()
+      .replace(/[.!]+$/g, "")
+      .trim();
+    if (/^(?:unlimited|indefinite|indefinitely|until cancelled|until canceled)$/.test(normalized)) {
+      recovery.maxOutageMs = null;
+      return;
+    }
+    recovery.maxOutageMs = requiredNetworkRecoveryDuration("maximum outage", value);
+    return;
+  }
+  if (/\b(?:enabled?|enablement)\b/.test(key) || /\bnetwork recovery\b/.test(key)) {
+    const enabled = booleanSetting(value);
+    if (enabled === undefined) {
+      throw new NetworkRecoveryConfigError(
+        "Network recovery must be configured as enabled/disabled, on/off, true/false, or yes/no.",
+      );
+    }
+    recovery.enabled = enabled;
+    return;
+  }
+
+  throw new NetworkRecoveryConfigError(`Unknown network recovery configuration directive: ${key}.`);
+}
+
+function requiredPlannerDuration(label: string, value: string, allowZero: boolean): number {
+  const trimmed = trimDirectiveValue(value)
+    .replace(/[.!]+$/g, "")
+    .trim();
+  const match = /^(\d+(?:\.\d+)?)\s*(milliseconds?|msecs?|ms|seconds?|secs?|s|minutes?|mins?|m|hours?|hrs?|h)?$/i.exec(
+    trimmed,
+  );
+  const milliseconds = match ? durationMsFromText(trimmed, { allowBareSeconds: true, allowZero }) : undefined;
+  if (milliseconds === undefined || milliseconds > MAX_PLANNER_DURATION_MS) {
+    const minimum = allowZero ? "non-negative" : "positive";
+    throw new PlannerDurationConfigError(
+      `TODO planner ${label} must be a ${minimum} finite duration no greater than about 24.9 days (${MAX_PLANNER_DURATION_MS} milliseconds), for example 30s or 5m.`,
+    );
+  }
+  return milliseconds;
+}
+
+function requiredNetworkRecoveryDuration(label: string, value: string): number {
+  const trimmed = trimDirectiveValue(value)
+    .replace(/[.!]+$/g, "")
+    .trim();
+  const match = /^(\d+(?:\.\d+)?)\s*(milliseconds?|msecs?|ms|seconds?|secs?|s|minutes?|mins?|m|hours?|hrs?|h)?$/i.exec(
+    trimmed,
+  );
+  if (!match) {
+    throw new NetworkRecoveryConfigError(
+      `Network recovery ${label} must be a positive finite duration (for example 1000ms, 30s, or 5m).`,
+    );
+  }
+  const milliseconds = durationMsFromText(trimmed, { allowBareSeconds: true });
+  if (milliseconds === undefined) {
+    throw new NetworkRecoveryConfigError(
+      `Network recovery ${label} must be a positive finite duration (for example 1000ms, 30s, or 5m).`,
+    );
+  }
+  return milliseconds;
+}
+
 function captureTokens(text: string, pattern: RegExp, apply: (token: string) => void): void {
   for (const match of text.matchAll(pattern)) {
     const token = modelToken(match[1] ?? "");
@@ -233,9 +361,17 @@ function captureNumbers(text: string, pattern: RegExp, apply: (value: number) =>
   }
 }
 
-function captureDurations(text: string, pattern: RegExp, apply: (value: number) => void): void {
+function captureDurations(
+  text: string,
+  pattern: RegExp,
+  apply: (value: number) => void,
+  options: { allowZero?: boolean } = {},
+): void {
   for (const match of text.matchAll(pattern)) {
-    const value = durationMsFromText(match[1] ?? "", { allowBareSeconds: true });
+    const value = durationMsFromText(match[1] ?? "", {
+      allowBareSeconds: true,
+      allowZero: options.allowZero,
+    });
     if (value !== undefined) {
       apply(value);
     }
@@ -299,7 +435,10 @@ function booleanSetting(value: string): boolean | undefined {
   return undefined;
 }
 
-function durationMsFromText(value: string, options: { allowBareSeconds: boolean }): number | undefined {
+function durationMsFromText(
+  value: string,
+  options: { allowBareSeconds: boolean; allowZero?: boolean },
+): number | undefined {
   const match = /(\d+(?:\.\d+)?)\s*(milliseconds?|msecs?|ms|seconds?|secs?|s|minutes?|mins?|m|hours?|hrs?|h)?\b/i.exec(
     value,
   );
@@ -308,7 +447,7 @@ function durationMsFromText(value: string, options: { allowBareSeconds: boolean
   }
 
   const amount = Number.parseFloat(match[1] ?? "");
-  if (!Number.isFinite(amount) || amount <= 0) {
+  if (!Number.isFinite(amount) || amount < 0 || (!options.allowZero && amount === 0)) {
     return undefined;
   }
 
@@ -319,7 +458,9 @@ function durationMsFromText(value: string, options: { allowBareSeconds: boolean
 
   const multiplier = durationMultiplier(unit || "seconds");
   const milliseconds = Math.round(amount * multiplier);
-  return Number.isSafeInteger(milliseconds) && milliseconds > 0 ? milliseconds : undefined;
+  return Number.isSafeInteger(milliseconds) && (options.allowZero ? milliseconds >= 0 : milliseconds > 0)
+    ? milliseconds
+    : undefined;
 }
 
 function durationMultiplier(unit: string): number {

package/src/worker_session.ts

@@ -8,14 +8,25 @@ import {
   parseCompleteTaskResult,
   parseReportedStatus,
 } from "./result_writer.ts";
+import type { NetworkRecoveryConfig } from "./network_recovery_config.ts";
 import type { Task } from "./todo_parser.ts";
 
+export interface WorkerNetworkRecoveryContext {
+  /** One-based coordinator network retry count; this is not a task attempt. */
+  retryCount: number;
+  durableEvidencePath: string;
+  priorSessionId?: string;
+  failure: string;
+}
+
 export interface WorkerTaskPromptOptions {
   todoPath: string;
   task: Pick<Task, "taskId" | "title" | "section">;
   attempt: number;
   commitRequested: boolean;
   previousAttempts?: string;
+  /** Continuity supplied only when a failed transport session is replaced. */
+  networkRecoveryContext?: WorkerNetworkRecoveryContext;
   globalInstructions?: string;
   goal?: string;
   maxBashTimeoutSeconds: number;
@@ -43,6 +54,18 @@ Previous attempts for this same assigned task are below. Use them only as contin
 \`\`\`text
 ${previousAttempts}
 \`\`\`
+`
+    : "";
+
+  const recovery = options.networkRecoveryContext;
+  const recoveryText = recovery
+    ? `
+Network recovery continuation (network retry ${recovery.retryCount}, still ordinary task attempt ${options.attempt}):
+- The prior worker session ended only after Pi's bounded provider-request retries were exhausted: ${recovery.failure}
+- Durable interruption evidence was recorded in \`${recovery.durableEvidencePath}\`${recovery.priorSessionId ? ` for session \`${recovery.priorSessionId}\`` : ""}.
+- The prior session may already have completed tool calls and changed the working tree. Inspect the durable evidence and current files before acting.
+- Continue this same TODO from its current state. Never blindly replay prior edits, commands, commits, external writes, or other side effects.
+- Report one final TASK_RESULT for the assignment only after verifying what remains.
 `
     : "";
 
@@ -93,7 +116,7 @@ Rules:
 - Do not run bash commands with timeout greater than ${options.maxBashTimeoutSeconds.toFixed(0)} seconds. For long full-suite checks, run once with a bounded timeout and report any timeout/failure in TASK_RESULT instead of continuing indefinitely.
 - If TODO-file global instructions restrict scope, obey them strictly. If the task appears to require out-of-scope code changes, stop and report \`status: blocked\` instead of changing those files.
 
-${globalText}Assigned task content only:
+${globalText}${recoveryText}Assigned task content only:
 
 \`\`\`markdown
 ${options.task.section.trimEnd()}
@@ -289,6 +312,8 @@ export type WorkerSessionFactory = (options: CreateWorkerSessionOptions) => Prom
 export interface RunWorkerTaskOptions extends WorkerTaskPromptOptions, CreateWorkerSessionOptions {
   taskTimeoutSeconds?: number;
   gracefulShutdownSeconds?: number;
+  /** Normalized coordinator policy for resuming this operation after transient transport failure. */
+  networkRecovery?: Readonly<NetworkRecoveryConfig>;
   abortSignal?: AbortSignal;
   sessionFactory?: WorkerSessionFactory;
   onEvent?: (event: CapturedWorkerEvent) => void;
@@ -353,6 +378,8 @@ export interface SessionOutcome {
   timedOut: boolean;
   aborted: boolean;
   error?: string;
+  /** Original provider/transport failure retained for coordinator classification. */
+  failure?: unknown;
 }
 
 export function buildMissingTaskResultMessage(): string {
@@ -512,6 +539,7 @@ export async function runWorkerTaskAssignment(
   let timedOut = false;
   let aborted = false;
   let error: string | undefined;
+  let failure: unknown;
   let finished = false;
   let turnCount = 0;
   let messageUsageCostTotal = 0;
@@ -637,6 +665,7 @@ export async function runWorkerTaskAssignment(
       },
       (exc: unknown) => {
         settled = true;
+        failure ??= exc;
         error = error ?? errorMessage(exc);
         resolvePromptWait?.();
         resolvePromptWait = undefined;
@@ -773,6 +802,7 @@ export async function runWorkerTaskAssignment(
       assistantText = latestInvocationAssistantText(session, assistantText, invocationMessageStart, !reusedAssignment);
     }
   } catch (exc) {
+    failure ??= exc;
     error = error ?? errorMessage(exc);
   } finally {
     finished = true;
@@ -823,6 +853,7 @@ export async function runWorkerTaskAssignment(
     timedOut,
     aborted: aborted || cancelled,
     error,
+    ...(failure === undefined ? {} : { failure }),
   };
 }
 
@@ -872,6 +903,7 @@ export function buildWorkerSessionCreationFailureOutcome(
     timedOut: false,
     aborted: Boolean(options.abortSignal?.aborted),
     error: message,
+    failure: error,
   };
 }