pi-long-task 0.6.0 → 0.7.0

package/src/coordinator.ts

@@ -32,6 +32,24 @@ import {
   type PlanRevisionRelevantResult,
 } from "./plan_revision_generation.ts";
 import { taskSemanticFingerprint, type PlanTaskState } from "./plan_revision.ts";
+import {
+  DEFAULT_PLANNER_THINKING_LEVEL,
+  DEFAULT_PLANNER_TIMEOUT_MS,
+  resolvePlannerBudget,
+  resolvePlannerGracefulShutdownMs,
+  resolvePlannerTimeoutMs,
+  type PlannerBudget,
+} from "./planner_config.ts";
+import {
+  createPlannerActiveProgress,
+  createPlannerGraceProgress,
+  createPlannerStartedProgress,
+  formatFriendlyDuration,
+  plannerProgressCheckpoints,
+  type PlannerProgressEvent,
+  type PlannerProgressHandler,
+  type PlannerProgressState,
+} from "./planner_progress.ts";
 import {
   PersistentTodoPlanStore,
   planTaskReference,
@@ -53,6 +71,7 @@ import {
 import { buildTaskProgressModel, type TaskProgressModel, type TaskProgressStatus } from "./task_progress.ts";
 import {
   applyGoalInstructionsToTodoMarkdown,
+  applyWorkerCapabilityConstraintsToTodoMarkdown,
   buildTodoCreationPrompt,
   buildTodoRepairPrompt,
   extractAndValidateTodoMarkdown,
@@ -61,6 +80,7 @@ import {
   validateTodoMarkdown,
 } from "./todo_generator.ts";
 import { parseTasks, todoGlobalInstructions, type Task } from "./todo_parser.ts";
+import { detectUnavailableWorkerCapabilities, type WorkerCapabilityWarning } from "./worker_capabilities.ts";
 import {
   buildWorkerSessionCreationFailureOutcome,
   createIsolatedWorkerSession,
@@ -84,11 +104,11 @@ export type { CoordinatorStatus } from "./types.ts";
 export const DEFAULT_COORDINATOR_OPTIONS = {
   maxAttemptsPerTask: 3,
   taskTimeoutMs: 900_000,
-  todoTimeoutMs: 300_000,
+  todoTimeoutMs: DEFAULT_PLANNER_TIMEOUT_MS,
   todoGracefulShutdownMs: 15_000,
   maxBashTimeoutMs: 300_000,
   taskThinking: "high",
-  todoThinking: "xhigh",
+  todoThinking: DEFAULT_PLANNER_THINKING_LEVEL,
   workerSessionReuse: DEFAULT_WORKER_SESSION_REUSE_ENABLED,
   workerSessionReuseContextThresholdPercent: DEFAULT_WORKER_SESSION_REUSE_CONTEXT_THRESHOLD_PERCENT,
   networkRecovery: DEFAULT_NETWORK_RECOVERY_CONFIG,
@@ -96,6 +116,7 @@ export const DEFAULT_COORDINATOR_OPTIONS = {
 
 export type WorkerRunner = (options: RunWorkerTaskOptions) => Promise<SessionOutcome>;
 export type CoordinatorProgressPhase =
+  | "capability_warning"
   | "planning"
   | "planned"
   | "task_start"
@@ -108,14 +129,30 @@ export type CoordinatorProgressPhase =
   | "task_obsolete"
   | "complete";
 
-export type PlannerDiagnosticKind = "timeout" | "abort" | "invalid_output" | "repair_attempt" | "failure";
+export type PlannerDiagnosticKind =
+  | "timeout"
+  | "cancelled"
+  /** @deprecated Planner cancellation is now reported as `cancelled`. */
+  | "abort"
+  | "network_recovery"
+  | "network_failure"
+  | "invalid_output"
+  | "repair_attempt"
+  | "failure";
 
 export interface PlannerDiagnostic {
   kind: PlannerDiagnosticKind;
   message: string;
+  /** Present whenever output presence is known; partial content itself is deliberately omitted. */
+  partialOutputObserved?: boolean;
   diagnostics?: string[];
   sessionFile?: string;
   sessionId?: string;
+  /** Network lifecycle data is separate from timeout/cancellation classification. */
+  networkRecoveryEvent?: NetworkRecoveryEventType;
+  networkFailureReason?: string;
+  networkRetryCount?: number;
+  networkOutageElapsedMs?: number;
 }
 
 export type PlannerDiagnosticHandler = (diagnostic: PlannerDiagnostic) => void;
@@ -158,8 +195,18 @@ export interface CoordinatorProgressUpdate {
   taskProgress?: TaskProgressModel;
   plannerDiagnostic?: PlannerDiagnosticKind;
   plannerDiagnostics?: string[];
+  plannerPartialOutputObserved?: boolean;
   plannerSessionFile?: string;
   plannerSessionId?: string;
+  /** Deterministic deadline selection used by planner calls in this run. */
+  plannerBudget?: Readonly<PlannerBudget>;
+  /** Human-facing state with exact millisecond values retained for integrations. */
+  plannerProgressState?: PlannerProgressState;
+  plannerElapsedMs?: number;
+  plannerRemainingMs?: number;
+  plannerGracePeriodMs?: number;
+  plannerGraceRemainingMs?: number;
+  capabilityWarning?: Readonly<WorkerCapabilityWarning>;
   workerSessionEvent?: WorkerSessionDiagnostic["event"];
   workerSessionReason?: string;
   workerSessionContextUsagePercent?: number;
@@ -170,6 +217,10 @@ export interface CoordinatorProgressUpdate {
   networkNextRetryAtMs?: number;
   networkNextRetryInMs?: number;
   networkFailureReason?: string;
+  /** Identifies whether recovery belongs to planning or worker execution. */
+  networkOperation?: "planner" | "worker";
+  /** Planner recovery never mutates the configured per-attempt deadline. */
+  plannerDeadlinePolicy?: "per_attempt_excludes_network_wait";
 }
 
 export type CoordinatorProgressHandler = (update: CoordinatorProgressUpdate) => void;
@@ -210,20 +261,31 @@ export interface TodoPlannerOptions {
   inputText: string;
   cwd: string;
   runDir: string;
-  thinkingLevel: string;
+  /** Defaults to the planner-only balanced level; explicit values are forwarded unchanged. */
+  thinkingLevel?: string;
   model?: unknown;
   abortSignal?: AbortSignal;
   timeoutMs?: number;
   gracefulShutdownMs?: number;
+  /** Structured record of explicit/default/adaptive deadline selection. */
+  plannerBudget?: Readonly<PlannerBudget>;
   sessionFactory?: WorkerSessionFactory;
   onDiagnostic?: PlannerDiagnosticHandler;
+  /** Shared human-readable timing events for CLI, TUI, and headless integrations. */
+  onProgress?: PlannerProgressHandler;
   goal?: string;
   /** Exact prompt for revision planners; bypasses the initial TODO-creation wrapper. */
   plannerPrompt?: string;
   /** Structured revision context supplied alongside plannerPrompt. */
   planRevision?: Readonly<PlanRevisionRequest>;
-  /** Normalized coordinator recovery policy; network wait is excluded from operation timeouts. */
+  /**
+   * Normalized coordinator recovery policy. Recovery wait is accounted on its
+   * own outage clock; every replay receives the same configured per-attempt
+   * planner deadline, so recovery settings never replace that deadline.
+   */
   networkRecovery?: Readonly<NetworkRecoveryConfig>;
+  /** Run-level constraints derived from capabilities unavailable to isolated workers. */
+  capabilityConstraints?: readonly string[];
 }
 
 export interface TaskAttemptSummary {
@@ -276,6 +338,10 @@ export interface CoordinatorResult {
   workerUsageTotal?: WorkerUsageTotals;
   /** Additive lifecycle counters for adaptive worker-session reuse. */
   workerSessionMetrics?: WorkerSessionMetrics;
+  /** Deterministic deadline selection used by planner calls in this run. */
+  plannerBudget?: Readonly<PlannerBudget>;
+  /** Explicit, non-fatal warnings for requested capabilities unavailable to isolated workers. */
+  capabilityWarnings?: readonly WorkerCapabilityWarning[];
   commit: boolean;
   goal?: string;
   error?: string;
@@ -307,6 +373,7 @@ interface RuntimeOptions {
   networkRecovery: NetworkRecoveryConfig;
   todoTimeoutMs: number;
   todoGracefulShutdownMs: number;
+  plannerBudget: PlannerBudget;
   workerRunner: WorkerRunner;
   useRetainedWorkerLifecycle: boolean;
   todoPlanner: TodoPlanner;
@@ -320,6 +387,7 @@ interface RuntimeOptions {
   workerTextByWorker: Map<string, string>;
   workerTextPublishedLengthByWorker: Map<string, number>;
   plannerDiagnostics: PlannerDiagnostic[];
+  capabilityWarnings: WorkerCapabilityWarning[];
   workerSessionMetrics: WorkerSessionMetrics;
   steeringQueue?: SerializedSteeringQueue;
   onPlanRevisionAccepted?: (revision: GeneratedPlanRevision) => void | Promise<void>;
@@ -327,7 +395,12 @@ interface RuntimeOptions {
   lastProgress?: CoordinatorProgressUpdate;
   progressClosed: boolean;
   networkRecoverySequence: number;
-  activeNetworkRecoveries: Map<number, NetworkRecoveryEvent>;
+  activeNetworkRecoveries: Map<number, ActiveNetworkRecovery>;
+}
+
+interface ActiveNetworkRecovery {
+  event: NetworkRecoveryEvent;
+  operation: "planner" | "worker";
 }
 
 type RetainedWorkerReuseScope = "sequential_task" | "partial_continuation";
@@ -956,7 +1029,7 @@ export async function runCoordinator(options: RunCoordinatorOptions): Promise<Co
   const commits: CoordinatorCommitSummary[] = [];
 
   await mkdir(runtime.runDir, { recursive: true });
-  await writeFile(runtime.taskResultPath, initialTaskResultMarkdown(runtime.runId), "utf8");
+  await writeFile(runtime.taskResultPath, initialTaskResultMarkdown(runtime.runId, runtime.capabilityWarnings), "utf8");
   let planningComplete = false;
   let latestTodoMarkdown: string | undefined;
   let latestTasks: Task[] = [];
@@ -972,7 +1045,14 @@ export async function runCoordinator(options: RunCoordinatorOptions): Promise<Co
   const protectedDirtyPathsByTask = new Map<string, Set<string>>();
 
   try {
-    emitProgress(runtime, "Creating TODO plan...", { phase: "planning" });
+    for (const warning of runtime.capabilityWarnings) {
+      emitProgress(runtime, warning.message, {
+        phase: "capability_warning",
+        status: "warning",
+        capabilityWarning: warning,
+      });
+    }
+    emitPlannerProgress(runtime, createPlannerStartedProgress(runtime.plannerBudget, runtime.todoGracefulShutdownMs));
     let todoMarkdown = await generateOrNormalizeTodoMarkdown(inputText, runtime);
     validateTodoMarkdown(todoMarkdown);
     planningComplete = true;
@@ -1374,6 +1454,8 @@ export async function runCoordinator(options: RunCoordinatorOptions): Promise<Co
       workerCostTotal: runtime.workerCostState.total,
       workerUsageTotal: aggregateWorkerUsage(outcomes),
       workerSessionMetrics: snapshotWorkerSessionMetrics(runtime.workerSessionMetrics),
+      plannerBudget: runtime.plannerBudget,
+      capabilityWarnings: runtime.capabilityWarnings,
       commit: options.commit,
       goal: runtime.goal,
       error: failure,
@@ -1388,10 +1470,12 @@ export async function runCoordinator(options: RunCoordinatorOptions): Promise<Co
     return result;
   } catch (error) {
     const message = errorMessage(error);
-    if (!planningComplete) {
+    if (!planningComplete && !hasTerminalPlannerDiagnostic(runtime.plannerDiagnostics)) {
       recordPlannerDiagnostic(runtime, {
-        kind: "failure",
-        message: `TODO planning failed: ${message}`,
+        kind: runtime.abortSignal?.aborted ? "cancelled" : "failure",
+        message: runtime.abortSignal?.aborted
+          ? `TODO planning cancelled: ${abortSignalReason(runtime.abortSignal)}`
+          : `TODO planning failed: ${message}`,
       });
     }
     const resultError = !planningComplete
@@ -1457,6 +1541,8 @@ export async function runCoordinator(options: RunCoordinatorOptions): Promise<Co
       workerCostTotal: runtime.workerCostState.total,
       workerUsageTotal: aggregateWorkerUsage(outcomes),
       workerSessionMetrics: snapshotWorkerSessionMetrics(runtime.workerSessionMetrics),
+      plannerBudget: runtime.plannerBudget,
+      capabilityWarnings: runtime.capabilityWarnings,
       commit: options.commit,
       goal: runtime.goal,
       error: resultError,
@@ -1478,9 +1564,10 @@ export async function runCoordinator(options: RunCoordinatorOptions): Promise<Co
 }
 
 async function generateOrNormalizeTodoMarkdown(inputText: string, runtime: RuntimeOptions): Promise<string> {
+  const capabilityConstraints = runtime.capabilityWarnings.map((warning) => warning.planningConstraint);
   const local = todoMarkdownFromString(inputText, runtime.goal);
   if (local) {
-    return local;
+    return applyWorkerCapabilityConstraintsToTodoMarkdown(local, capabilityConstraints);
   }
 
   const plannerText = await requestTodoPlan(inputText, runtime);
@@ -1489,6 +1576,7 @@ async function generateOrNormalizeTodoMarkdown(inputText: string, runtime: Runti
     plannerText,
     (repairPrompt) => requestTodoPlan(repairPrompt, runtime),
     runtime.goal,
+    capabilityConstraints,
     {
       onInvalidOutput: (validationError) =>
         recordPlannerDiagnostic(runtime, {
@@ -1507,7 +1595,8 @@ async function generateOrNormalizeTodoMarkdown(inputText: string, runtime: Runti
         }),
     },
   );
-  return applyGoalInstructionsToTodoMarkdown(planned, runtime.goal);
+  const withGoal = applyGoalInstructionsToTodoMarkdown(planned, runtime.goal);
+  return applyWorkerCapabilityConstraintsToTodoMarkdown(withGoal, capabilityConstraints);
 }
 
 interface TodoExtractionRepairHooks {
@@ -1521,6 +1610,7 @@ async function extractTodoMarkdownWithOneRepair(
   plannerText: string,
   requestRepair: (repairPrompt: string) => Promise<string>,
   goal?: string,
+  capabilityConstraints: readonly string[] = [],
   hooks: TodoExtractionRepairHooks = {},
 ): Promise<string> {
   try {
@@ -1529,7 +1619,9 @@ async function extractTodoMarkdownWithOneRepair(
     const validationError = errorMessage(error);
     hooks.onInvalidOutput?.(validationError);
     hooks.onRepairAttempt?.(validationError);
-    const repairText = await requestRepair(buildTodoRepairPrompt(inputText, plannerText, validationError, goal));
+    const repairText = await requestRepair(
+      buildTodoRepairPrompt(inputText, plannerText, validationError, goal, capabilityConstraints),
+    );
     try {
       return extractAndValidateTodoMarkdown(repairText);
     } catch (repairError) {
@@ -1553,9 +1645,16 @@ async function requestTodoPlan(inputText: string, runtime: RuntimeOptions): Prom
       abortSignal: runtime.abortSignal,
       timeoutMs: runtime.todoTimeoutMs,
       gracefulShutdownMs: runtime.todoGracefulShutdownMs,
+      plannerBudget: runtime.plannerBudget,
       sessionFactory: runtime.todoSessionFactory,
       networkRecovery: runtime.networkRecovery,
+      capabilityConstraints: runtime.capabilityWarnings.map((warning) => warning.planningConstraint),
       onDiagnostic: (diagnostic) => recordPlannerDiagnostic(runtime, diagnostic),
+      onProgress: (event) => {
+        if (event.state !== "started") {
+          emitPlannerProgress(runtime, event);
+        }
+      },
       goal: runtime.goal,
     },
     runtime,
@@ -1567,8 +1666,10 @@ async function requestTodoPlan(inputText: string, runtime: RuntimeOptions): Prom
  * 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.
+ * repair/attempt counter, and each fresh call retains the exact configured
+ * per-attempt planner timeout. Network wait is intentionally excluded and is
+ * governed solely by the separate outage deadline; recovery cannot reset,
+ * extend, or replace the timeout attached to any individual planner call.
  */
 async function runPlannerOperationWithNetworkRecovery(
   plannerOptions: TodoPlannerOptions,
@@ -1577,6 +1678,8 @@ async function runPlannerOperationWithNetworkRecovery(
   const run = (recoverySignal?: AbortSignal) =>
     runtime.todoPlanner({
       ...plannerOptions,
+      // The recovery signal carries cancellation/outage expiry only. It does
+      // not alter timeoutMs, which remains authoritative for every replay.
       abortSignal: combineAbortSignals(plannerOptions.abortSignal, recoverySignal),
     });
 
@@ -1584,17 +1687,73 @@ async function runPlannerOperationWithNetworkRecovery(
     return await run();
   } catch (initialFailure) {
     const classification = classifyNetworkFailure(initialFailure);
+    if (plannerOptions.abortSignal?.aborted || classification.reason === "cancelled") {
+      recordPlannerCancellation(runtime, plannerOptions.abortSignal, initialFailure);
+      throw plannerCancellationError(plannerOptions.abortSignal, initialFailure);
+    }
     if (!runtime.networkRecovery.enabled || !classification.recoverable) {
       throw initialFailure;
     }
-    const recovered = await recoverNetworkOperation({
-      initialFailure,
-      config: runtime.networkRecovery,
-      signal: plannerOptions.abortSignal,
-      onEvent: createNetworkRecoveryProgressHandler(runtime),
-      retry: ({ signal }) => run(signal),
-    });
-    return recovered.value;
+
+    const publishRecovery = createNetworkRecoveryProgressHandler(runtime, "planner");
+    let recoveryStarted = false;
+    let lastRecoveryEvent: NetworkRecoveryEvent | undefined;
+    const onRecoveryEvent = (event: NetworkRecoveryEvent) => {
+      if (event.type !== "cleanup") lastRecoveryEvent = event;
+      if (event.type === "outage_started" && !recoveryStarted) {
+        recoveryStarted = true;
+        recordPlannerDiagnostic(
+          runtime,
+          plannerNetworkDiagnostic(
+            event,
+            plannerOptions.timeoutMs,
+            latestPlannerPartialOutput(runtime.plannerDiagnostics),
+          ),
+        );
+      }
+      publishRecovery(event);
+      if (event.type === "recovered") {
+        recordPlannerDiagnostic(
+          runtime,
+          plannerNetworkDiagnostic(
+            event,
+            plannerOptions.timeoutMs,
+            latestPlannerPartialOutput(runtime.plannerDiagnostics),
+          ),
+        );
+      }
+    };
+
+    try {
+      const recovered = await recoverNetworkOperation({
+        initialFailure,
+        config: runtime.networkRecovery,
+        signal: plannerOptions.abortSignal,
+        onEvent: onRecoveryEvent,
+        retry: ({ signal }) => run(signal),
+      });
+      return recovered.value;
+    } catch (recoveryFailure) {
+      if (plannerOptions.abortSignal?.aborted) {
+        recordPlannerCancellation(runtime, plannerOptions.abortSignal, recoveryFailure);
+        throw plannerCancellationError(plannerOptions.abortSignal, recoveryFailure);
+      } else if (!hasTerminalPlannerDiagnosticAfterLatestRecovery(runtime.plannerDiagnostics)) {
+        const finalClassification = classifyNetworkFailure(recoveryFailure);
+        recordPlannerDiagnostic(runtime, {
+          kind: "network_failure",
+          message: `TODO planner network recovery ended before planning completed: ${errorMessage(recoveryFailure)}`,
+          partialOutputObserved: latestPlannerPartialOutput(runtime.plannerDiagnostics),
+          networkRecoveryEvent:
+            lastRecoveryEvent?.type === "outage_expired" || lastRecoveryEvent?.type === "failed"
+              ? lastRecoveryEvent.type
+              : "failed",
+          networkFailureReason: lastRecoveryEvent?.state.lastFailure.reason ?? finalClassification.reason,
+          networkRetryCount: lastRecoveryEvent?.state.retryCount,
+          networkOutageElapsedMs: lastRecoveryEvent?.state.elapsedMs,
+        });
+      }
+      throw recoveryFailure;
+    }
   }
 }
 
@@ -1640,9 +1799,12 @@ async function generateSteeringPlanRevision(options: {
           abortSignal: options.runtime.abortSignal,
           timeoutMs: options.runtime.todoTimeoutMs,
           gracefulShutdownMs: options.runtime.todoGracefulShutdownMs,
+          plannerBudget: options.runtime.plannerBudget,
           sessionFactory: options.runtime.todoSessionFactory,
           networkRecovery: options.runtime.networkRecovery,
+          capabilityConstraints: options.runtime.capabilityWarnings.map((warning) => warning.planningConstraint),
           onDiagnostic: (diagnostic) => recordPlannerDiagnostic(options.runtime, diagnostic),
+          onProgress: (event) => emitPlannerProgress(options.runtime, event),
           goal: options.runtime.goal,
         },
         options.runtime,
@@ -1751,16 +1913,41 @@ function relevantPlanRevisionResults(
 // Planner/worker lifecycle differences are audited in docs/planner-worker-lifecycle-audit.md;
 // keep this function's public contract stable while moving shared prompt guarding into a helper.
 export async function runTodoPlanner(options: TodoPlannerOptions): Promise<string> {
+  const capabilityConstraints =
+    options.capabilityConstraints ??
+    capabilityWarningsForRequest(options.inputText, options.goal).map((warning) => warning.planningConstraint);
+  const plannerBudget =
+    options.plannerBudget ??
+    resolvePlannerBudget({
+      inputText: options.inputText,
+      explicitTimeoutMs: options.timeoutMs,
+      defaultTimeoutMs: DEFAULT_COORDINATOR_OPTIONS.todoTimeoutMs,
+    });
+  const timeoutMs = resolvePlannerTimeoutMs(options.timeoutMs, plannerBudget.timeoutMs);
+  const gracefulShutdownMs = resolvePlannerGracefulShutdownMs(
+    options.gracefulShutdownMs,
+    DEFAULT_COORDINATOR_OPTIONS.todoGracefulShutdownMs,
+  );
+  const effectivePlannerBudget: PlannerBudget =
+    timeoutMs === plannerBudget.timeoutMs
+      ? plannerBudget
+      : {
+          ...plannerBudget,
+          timeoutMs,
+          extensionApplied: false,
+          extensionMs: 0,
+          source: "explicit",
+          trigger: undefined,
+        };
+  notifyPlannerProgress(options.onProgress, createPlannerStartedProgress(effectivePlannerBudget, gracefulShutdownMs));
   const sessionFactory = options.sessionFactory ?? createIsolatedWorkerSession;
   const result = await sessionFactory({
     cwd: options.cwd,
     tools: [],
     model: options.model,
-    thinkingLevel: options.thinkingLevel,
+    thinkingLevel: options.thinkingLevel ?? DEFAULT_PLANNER_THINKING_LEVEL,
   });
   const session = result.session;
-  const timeoutMs = positiveMilliseconds(options.timeoutMs, DEFAULT_COORDINATOR_OPTIONS.todoTimeoutMs);
-  const gracefulShutdownMs = options.gracefulShutdownMs ?? DEFAULT_COORDINATOR_OPTIONS.todoGracefulShutdownMs;
 
   let plannerMarkdown: string | undefined;
   let plannerError: unknown;
@@ -1768,12 +1955,14 @@ export async function runTodoPlanner(options: TodoPlannerOptions): Promise<strin
   try {
     const plannerText = await runTodoPlannerPrompt({
       session,
-      prompt: options.plannerPrompt ?? buildTodoCreationPrompt(options.inputText, options.goal),
+      prompt: options.plannerPrompt ?? buildTodoCreationPrompt(options.inputText, options.goal, capabilityConstraints),
       abortSignal: options.abortSignal,
       timeoutMs,
       gracefulShutdownMs,
       diagnostics: result.diagnostics,
       onDiagnostic: options.onDiagnostic,
+      plannerBudget: effectivePlannerBudget,
+      onProgress: options.onProgress,
     });
 
     plannerMarkdown = await extractTodoMarkdownWithOneRepair(
@@ -1788,8 +1977,11 @@ export async function runTodoPlanner(options: TodoPlannerOptions): Promise<strin
           gracefulShutdownMs,
           diagnostics: result.diagnostics,
           onDiagnostic: options.onDiagnostic,
+          plannerBudget: effectivePlannerBudget,
+          onProgress: options.onProgress,
         }),
       options.goal,
+      capabilityConstraints,
       {
         onInvalidOutput: (validationError) =>
           options.onDiagnostic?.({
@@ -1833,7 +2025,8 @@ export async function runTodoPlanner(options: TodoPlannerOptions): Promise<strin
   if (!plannerMarkdown) {
     throw new TodoGenerationError("TODO planner did not return valid TODO markdown.");
   }
-  return applyGoalInstructionsToTodoMarkdown(plannerMarkdown, options.goal);
+  const withGoal = applyGoalInstructionsToTodoMarkdown(plannerMarkdown, options.goal);
+  return applyWorkerCapabilityConstraintsToTodoMarkdown(withGoal, capabilityConstraints);
 }
 
 async function runTodoPlannerPrompt(options: {
@@ -1844,6 +2037,8 @@ async function runTodoPlannerPrompt(options: {
   gracefulShutdownMs: number;
   diagnostics?: string[];
   onDiagnostic?: PlannerDiagnosticHandler;
+  plannerBudget: Readonly<PlannerBudget>;
+  onProgress?: PlannerProgressHandler;
 }): Promise<string> {
   const promptResult = await runGuardedSessionPrompt({
     session: options.session,
@@ -1853,17 +2048,47 @@ async function runTodoPlannerPrompt(options: {
     gracefulShutdownMs: options.gracefulShutdownMs,
     gracefulShutdownPrompt: buildTodoPlanningShutdownMessage(),
     diagnostics: options.diagnostics,
+    progressCheckpointsMs: plannerProgressCheckpoints(options.timeoutMs),
+    onProgressCheckpoint: (elapsedMs) =>
+      notifyPlannerProgress(
+        options.onProgress,
+        createPlannerActiveProgress(options.plannerBudget, options.gracefulShutdownMs, elapsedMs),
+      ),
+    onGracePeriodStart: (gracePeriodMs) =>
+      notifyPlannerProgress(options.onProgress, createPlannerGraceProgress(options.plannerBudget, gracePeriodMs)),
     dispose: false,
   });
 
+  // Caller cancellation wins even when it arrives during grace. A hard abort
+  // caused by grace expiry has cancelled=false and remains a timeout.
+  if (promptResult.cancelled) {
+    const outputState = promptResult.outputObserved
+      ? "partial output observed; content omitted"
+      : "no planner output observed";
+    const message = `TODO planner cancelled (${outputState}): ${promptResult.error ?? "caller cancellation"}`;
+    options.onDiagnostic?.(plannerPromptDiagnostic("cancelled", message, promptResult));
+    throw new TodoGenerationError(message);
+  }
   if (promptResult.timedOut) {
-    const message = `TODO planner timed out: ${promptResult.error ?? "time budget exceeded"}`;
+    if (
+      promptResult.completedDuringGrace &&
+      promptResult.outputObserved &&
+      !promptResult.error &&
+      isSafeCompletedTodoPlannerOutput(promptResult.assistantText)
+    ) {
+      return promptResult.assistantText;
+    }
+
+    const outputState = promptResult.outputObserved
+      ? "partial output observed; content omitted"
+      : "no planner output observed";
+    const message = `TODO planner timed out (${outputState}): ${promptResult.error ?? "time budget exceeded"}`;
     options.onDiagnostic?.(plannerPromptDiagnostic("timeout", message, promptResult));
     throw new TodoGenerationError(message);
   }
   if (promptResult.aborted) {
-    const message = `TODO planner aborted: ${promptResult.error ?? "outer abort signal"}`;
-    options.onDiagnostic?.(plannerPromptDiagnostic("abort", message, promptResult));
+    const message = `TODO planner stopped: ${promptResult.error ?? "session abort"}`;
+    options.onDiagnostic?.(plannerPromptDiagnostic("failure", message, promptResult));
     throw new TodoGenerationError(message);
   }
   if (promptResult.error) {
@@ -1883,9 +2108,10 @@ async function runTodoPlannerPrompt(options: {
 }
 
 function plannerPromptDiagnostic(
-  kind: Extract<PlannerDiagnosticKind, "timeout" | "abort" | "failure">,
+  kind: Extract<PlannerDiagnosticKind, "timeout" | "cancelled" | "abort" | "failure">,
   message: string,
   promptResult: {
+    outputObserved: boolean;
     diagnostics: string[];
     sessionFile?: string;
     sessionId?: string;
@@ -1894,12 +2120,25 @@ function plannerPromptDiagnostic(
   return {
     kind,
     message,
+    partialOutputObserved: promptResult.outputObserved,
     diagnostics: promptResult.diagnostics,
     sessionFile: promptResult.sessionFile,
     sessionId: promptResult.sessionId,
   };
 }
 
+function isSafeCompletedTodoPlannerOutput(text: string): boolean {
+  if (!text.trim()) {
+    return false;
+  }
+  try {
+    extractAndValidateTodoMarkdown(text);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 function buildTodoPlanningShutdownMessage(): string {
   return `Pi Long Task notice: TODO planning has reached its time budget.
 Return the best valid Pi Long Task TODO markdown you can produce now, or stop if that is not possible.`;
@@ -1912,8 +2151,13 @@ function buildRuntimeOptions(options: RunCoordinatorOptions): RuntimeOptions {
   const parsedWorkerConfig = parseWorkerRuntimeConfig(options.inputText ?? "");
   const configuredAttempts = options.maxAttemptsPerTask ?? parsedWorkerConfig.maxAttemptsPerTask;
   const configuredTaskTimeoutMs = options.taskTimeoutMs ?? parsedWorkerConfig.taskTimeoutMs;
-  const configuredTodoTimeoutMs = options.todoTimeoutMs;
-  const configuredTodoGracefulShutdownMs = options.todoGracefulShutdownMs;
+  const configuredTodoTimeoutMs = options.todoTimeoutMs ?? parsedWorkerConfig.todoTimeoutMs;
+  const configuredTodoGracefulShutdownMs = options.todoGracefulShutdownMs ?? parsedWorkerConfig.todoGracefulShutdownMs;
+  const plannerBudget = resolvePlannerBudget({
+    inputText: coordinatorInputText(options),
+    explicitTimeoutMs: configuredTodoTimeoutMs,
+    defaultTimeoutMs: DEFAULT_COORDINATOR_OPTIONS.todoTimeoutMs,
+  });
   const configuredMaxBashTimeoutMs = options.maxBashTimeoutMs ?? parsedWorkerConfig.maxBashTimeoutMs;
   const workerModelName = options.workerModelName ?? parsedWorkerConfig.modelName;
   const workerModel = workerModelName ? undefined : options.workerModel;
@@ -1927,6 +2171,7 @@ function buildRuntimeOptions(options: RunCoordinatorOptions): RuntimeOptions {
     ...parsedWorkerConfig.networkRecovery,
     ...options.networkRecovery,
   });
+  const capabilityWarnings = capabilityWarningsForRequest(options.inputText, options.goal);
 
   return {
     cwd,
@@ -1936,11 +2181,12 @@ function buildRuntimeOptions(options: RunCoordinatorOptions): RuntimeOptions {
     taskResultPath: path.join(runDir, "TASK_RESULT.md"),
     maxAttemptsPerTask: positiveInteger(configuredAttempts, DEFAULT_COORDINATOR_OPTIONS.maxAttemptsPerTask),
     taskTimeoutSeconds: positiveMilliseconds(configuredTaskTimeoutMs, DEFAULT_COORDINATOR_OPTIONS.taskTimeoutMs) / 1000,
-    todoTimeoutMs: positiveMilliseconds(configuredTodoTimeoutMs, DEFAULT_COORDINATOR_OPTIONS.todoTimeoutMs),
-    todoGracefulShutdownMs: positiveMilliseconds(
+    todoTimeoutMs: plannerBudget.timeoutMs,
+    todoGracefulShutdownMs: resolvePlannerGracefulShutdownMs(
       configuredTodoGracefulShutdownMs,
       DEFAULT_COORDINATOR_OPTIONS.todoGracefulShutdownMs,
     ),
+    plannerBudget,
     maxBashTimeoutSeconds:
       positiveMilliseconds(configuredMaxBashTimeoutMs, DEFAULT_COORDINATOR_OPTIONS.maxBashTimeoutMs) / 1000,
     workerModel,
@@ -1964,6 +2210,7 @@ function buildRuntimeOptions(options: RunCoordinatorOptions): RuntimeOptions {
     workerTextByWorker: new Map(),
     workerTextPublishedLengthByWorker: new Map(),
     plannerDiagnostics: [],
+    capabilityWarnings,
     workerSessionMetrics: createWorkerSessionMetrics(),
     steeringQueue: options.steeringQueue,
     onPlanRevisionAccepted: options.onPlanRevisionAccepted,
@@ -1974,6 +2221,23 @@ function buildRuntimeOptions(options: RunCoordinatorOptions): RuntimeOptions {
   };
 }
 
+function emitPlannerProgress(runtime: RuntimeOptions, event: Readonly<PlannerProgressEvent>): void {
+  emitProgress(runtime, event.message, {
+    phase: "planning",
+    activeStatus: event.message,
+    plannerBudget: event.budget,
+    plannerProgressState: event.state,
+    plannerElapsedMs: event.elapsedMs,
+    plannerRemainingMs: event.remainingMs,
+    plannerGracePeriodMs: event.gracePeriodMs,
+    ...(event.graceRemainingMs === undefined ? {} : { plannerGraceRemainingMs: event.graceRemainingMs }),
+  });
+}
+
+function notifyPlannerProgress(handler: PlannerProgressHandler | undefined, event: PlannerProgressEvent): void {
+  handler?.(event);
+}
+
 function emitProgress(
   runtime: RuntimeOptions,
   message: string,
@@ -1992,7 +2256,7 @@ function emitProgress(
   runtime.lastProgress = progress;
   const activeRecovery = latestNetworkRecovery(runtime.activeNetworkRecoveries);
   if (activeRecovery) {
-    publishNetworkRecoveryProgress(runtime, activeRecovery);
+    publishNetworkRecoveryProgress(runtime, activeRecovery.event, activeRecovery.operation);
   } else {
     runtime.onProgress?.(progress);
   }
@@ -2005,7 +2269,10 @@ function emitProgress(
  * status path. Operation IDs prevent an older concurrent recovery from
  * repainting a newer outage or completion.
  */
-function createNetworkRecoveryProgressHandler(runtime: RuntimeOptions): (event: NetworkRecoveryEvent) => void {
+function createNetworkRecoveryProgressHandler(
+  runtime: RuntimeOptions,
+  operation: "planner" | "worker" = "worker",
+): (event: NetworkRecoveryEvent) => void {
   const operationId = ++runtime.networkRecoverySequence;
   let cleaned = false;
 
@@ -2024,7 +2291,7 @@ function createNetworkRecoveryProgressHandler(runtime: RuntimeOptions): (event:
       if (event.type === "recovered") {
         const active = latestNetworkRecovery(runtime.activeNetworkRecoveries);
         if (active) {
-          publishNetworkRecoveryProgress(runtime, active);
+          publishNetworkRecoveryProgress(runtime, active.event, active.operation);
         } else if (runtime.lastProgress) {
           runtime.onProgress?.({ ...runtime.lastProgress, workerCostTotal: runtime.workerCostState.total });
         }
@@ -2032,18 +2299,26 @@ function createNetworkRecoveryProgressHandler(runtime: RuntimeOptions): (event:
       return;
     }
 
-    runtime.activeNetworkRecoveries.set(operationId, event);
+    runtime.activeNetworkRecoveries.set(operationId, { event, operation });
     if (operationId === latestNetworkRecoveryId(runtime.activeNetworkRecoveries)) {
-      publishNetworkRecoveryProgress(runtime, event);
+      publishNetworkRecoveryProgress(runtime, event, operation);
     }
   };
 }
 
-function publishNetworkRecoveryProgress(runtime: RuntimeOptions, event: NetworkRecoveryEvent): void {
+function publishNetworkRecoveryProgress(
+  runtime: RuntimeOptions,
+  event: NetworkRecoveryEvent,
+  operation: "planner" | "worker" = "worker",
+): void {
   if (runtime.progressClosed) return;
   const stable = runtime.lastProgress;
   const nowMs = event.state.outageStartedAtMs + event.state.elapsedMs;
-  const message = formatNetworkRecoveryStatus(event);
+  const recoveryStatus = formatNetworkRecoveryStatus(event);
+  const message =
+    operation === "planner"
+      ? `TODO planner network recovery: ${recoveryStatus} The ${formatFriendlyDuration(runtime.todoTimeoutMs)} planning deadline remains unchanged for each provider attempt.`
+      : recoveryStatus;
   runtime.onProgress?.({
     message,
     phase: "network_wait",
@@ -2067,17 +2342,19 @@ function publishNetworkRecoveryProgress(runtime: RuntimeOptions, event: NetworkR
     networkNextRetryInMs:
       event.state.nextRetryAtMs === undefined ? undefined : Math.max(0, event.state.nextRetryAtMs - nowMs),
     networkFailureReason: event.state.lastFailure.reason,
+    networkOperation: operation,
+    ...(operation === "planner" ? { plannerDeadlinePolicy: "per_attempt_excludes_network_wait" as const } : {}),
   });
 }
 
 function latestNetworkRecovery(
-  recoveries: ReadonlyMap<number, NetworkRecoveryEvent>,
-): NetworkRecoveryEvent | undefined {
+  recoveries: ReadonlyMap<number, ActiveNetworkRecovery>,
+): ActiveNetworkRecovery | undefined {
   const id = latestNetworkRecoveryId(recoveries);
   return id === undefined ? undefined : recoveries.get(id);
 }
 
-function latestNetworkRecoveryId(recoveries: ReadonlyMap<number, NetworkRecoveryEvent>): number | undefined {
+function latestNetworkRecoveryId(recoveries: ReadonlyMap<number, ActiveNetworkRecovery>): number | undefined {
   let latest: number | undefined;
   for (const id of recoveries.keys()) {
     if (latest === undefined || id > latest) latest = id;
@@ -2089,13 +2366,79 @@ function isTerminalNetworkRecoveryEvent(type: NetworkRecoveryEventType): boolean
   return type === "recovered" || type === "failed" || type === "cancelled" || type === "outage_expired";
 }
 
+function plannerNetworkDiagnostic(
+  event: NetworkRecoveryEvent,
+  timeoutMs: number | undefined,
+  partialOutputObserved: boolean | undefined,
+): PlannerDiagnostic {
+  const recovered = event.type === "recovered";
+  const budget = formatFriendlyDuration(timeoutMs ?? DEFAULT_COORDINATOR_OPTIONS.todoTimeoutMs);
+  return {
+    kind: "network_recovery",
+    message: recovered
+      ? `TODO planner network recovery succeeded after ${formatFriendlyDuration(event.state.elapsedMs)}; planning continues with its unchanged ${budget} per-attempt deadline.`
+      : `TODO planner network recovery started (${event.state.lastFailure.reason}); its outage clock is separate and the ${budget} per-attempt planning deadline remains unchanged.`,
+    partialOutputObserved,
+    networkRecoveryEvent: event.type,
+    networkFailureReason: event.state.lastFailure.reason,
+    networkRetryCount: event.state.retryCount,
+    networkOutageElapsedMs: event.state.elapsedMs,
+  };
+}
+
+function latestPlannerPartialOutput(diagnostics: readonly PlannerDiagnostic[]): boolean | undefined {
+  return [...diagnostics].reverse().find((diagnostic) => diagnostic.partialOutputObserved !== undefined)
+    ?.partialOutputObserved;
+}
+
+function hasTerminalPlannerDiagnostic(diagnostics: readonly PlannerDiagnostic[]): boolean {
+  const kind = diagnostics.at(-1)?.kind;
+  return kind !== undefined && ["timeout", "cancelled", "abort", "network_failure", "failure"].includes(kind);
+}
+
+function hasTerminalPlannerDiagnosticAfterLatestRecovery(diagnostics: readonly PlannerDiagnostic[]): boolean {
+  let recoveryIndex = -1;
+  for (let index = diagnostics.length - 1; index >= 0; index -= 1) {
+    if (diagnostics[index]?.kind === "network_recovery") {
+      recoveryIndex = index;
+      break;
+    }
+  }
+  return diagnostics
+    .slice(recoveryIndex + 1)
+    .some((diagnostic) => ["timeout", "cancelled", "abort", "network_failure"].includes(diagnostic.kind));
+}
+
+function recordPlannerCancellation(runtime: RuntimeOptions, signal: AbortSignal | undefined, cause: unknown): void {
+  if (runtime.plannerDiagnostics.some((diagnostic) => diagnostic.kind === "cancelled")) return;
+  recordPlannerDiagnostic(runtime, {
+    kind: "cancelled",
+    message: `TODO planning cancelled: ${signal?.aborted ? abortSignalReason(signal) : errorMessage(cause)}`,
+    partialOutputObserved: latestPlannerPartialOutput(runtime.plannerDiagnostics),
+  });
+}
+
+function abortSignalReason(signal: AbortSignal): string {
+  return signal.reason === undefined ? "cancelled by caller" : errorMessage(signal.reason);
+}
+
+function plannerCancellationError(signal: AbortSignal | undefined, cause: unknown): TodoGenerationError {
+  const reason = signal?.aborted ? abortSignalReason(signal) : errorMessage(cause);
+  return new TodoGenerationError(`TODO planning cancelled: ${reason}`, { cause });
+}
+
 function recordPlannerDiagnostic(runtime: RuntimeOptions, diagnostic: PlannerDiagnostic): void {
   const normalized: PlannerDiagnostic = {
     kind: diagnostic.kind,
     message: diagnostic.message,
+    partialOutputObserved: diagnostic.partialOutputObserved,
     diagnostics: diagnostic.diagnostics?.filter(Boolean),
     sessionFile: diagnostic.sessionFile,
     sessionId: diagnostic.sessionId,
+    networkRecoveryEvent: diagnostic.networkRecoveryEvent,
+    networkFailureReason: diagnostic.networkFailureReason,
+    networkRetryCount: diagnostic.networkRetryCount,
+    networkOutageElapsedMs: diagnostic.networkOutageElapsedMs,
   };
   const last = runtime.plannerDiagnostics.at(-1);
   if (last?.kind === normalized.kind && last.message === normalized.message) {
@@ -2105,11 +2448,22 @@ function recordPlannerDiagnostic(runtime: RuntimeOptions, diagnostic: PlannerDia
   emitProgress(runtime, normalized.message, {
     phase: "planning",
     status: normalized.kind,
-    isError: normalized.kind !== "repair_attempt",
+    isError: !["repair_attempt", "network_recovery"].includes(normalized.kind),
     plannerDiagnostic: normalized.kind,
     plannerDiagnostics: normalized.diagnostics,
+    plannerPartialOutputObserved: normalized.partialOutputObserved,
     plannerSessionFile: normalized.sessionFile,
     plannerSessionId: normalized.sessionId,
+    networkRecoveryEvent: normalized.networkRecoveryEvent,
+    networkRetryCount: normalized.networkRetryCount,
+    networkOutageElapsedMs: normalized.networkOutageElapsedMs,
+    networkFailureReason: normalized.networkFailureReason,
+    networkOperation:
+      normalized.kind === "network_recovery" || normalized.kind === "network_failure" ? "planner" : undefined,
+    plannerDeadlinePolicy:
+      normalized.kind === "network_recovery" || normalized.kind === "network_failure"
+        ? "per_attempt_excludes_network_wait"
+        : undefined,
     taskProgress: buildTaskProgressModel({ tasks: [] }),
   });
 }
@@ -2582,8 +2936,11 @@ function outcomeProgressItemStatus(
   return "failed";
 }
 
-function initialTaskResultMarkdown(runId: string): string {
-  return `# Pi Long Task TASK_RESULT\n\nRun: ${runId}\n`;
+function initialTaskResultMarkdown(runId: string, capabilityWarnings: readonly WorkerCapabilityWarning[] = []): string {
+  const warningBlock = capabilityWarnings.length
+    ? `\n\n## Worker capability warnings\n\n${capabilityWarnings.map((warning) => `- ${warning.message}`).join("\n")}`
+    : "";
+  return `# Pi Long Task TASK_RESULT\n\nRun: ${runId}${warningBlock}\n`;
 }
 
 async function appendFailureNote(
@@ -2596,6 +2953,21 @@ async function appendFailureNote(
     lines.push("", "### Planner diagnostics");
     for (const diagnostic of plannerDiagnostics) {
       lines.push("", `- ${diagnostic.kind}: ${diagnostic.message}`);
+      if (diagnostic.partialOutputObserved !== undefined) {
+        lines.push(`  - Partial output observed: ${diagnostic.partialOutputObserved ? "yes" : "no"}`);
+      }
+      if (diagnostic.networkRecoveryEvent) {
+        lines.push(`  - Network recovery event: ${diagnostic.networkRecoveryEvent}`);
+      }
+      if (diagnostic.networkFailureReason) {
+        lines.push(`  - Network failure reason: ${diagnostic.networkFailureReason}`);
+      }
+      if (diagnostic.networkRetryCount !== undefined) {
+        lines.push(`  - Network retry count: ${diagnostic.networkRetryCount}`);
+      }
+      if (diagnostic.networkOutageElapsedMs !== undefined) {
+        lines.push(`  - Network outage elapsed: ${formatFriendlyDuration(diagnostic.networkOutageElapsedMs)}`);
+      }
       if (diagnostic.sessionId) {
         lines.push(`  - Session ID: ${diagnostic.sessionId}`);
       }
@@ -2794,6 +3166,17 @@ function coordinatorInputText(options: RunCoordinatorOptions): string {
   return normalizeOptionalText(options.inputText) ?? normalizeOptionalText(options.goal) ?? "";
 }
 
+function capabilityWarningsForRequest(inputText?: string, goal?: string): WorkerCapabilityWarning[] {
+  const requestText = [normalizeOptionalText(inputText), normalizeOptionalText(goal)]
+    .filter((item): item is string => Boolean(item))
+    .filter((item, index, all) => all.indexOf(item) === index)
+    .join("\n");
+  return detectUnavailableWorkerCapabilities(requestText, {
+    tools: DEFAULT_WORKER_TOOLS,
+    extensionsEnabled: false,
+  });
+}
+
 function positiveInteger(value: number | undefined, fallback: number): number {
   if (typeof value === "number" && Number.isFinite(value) && value > 0) {
     return Math.floor(value);