pi-long-task 0.3.7 → 0.3.9

package/README.md

@@ -18,11 +18,11 @@ Use it when a coding request is bigger than one focused interaction. Pi Long Tas
 When you ask Pi to run a long task, Pi Long Task:
 
 1. Recognizes natural-language requests like "run a long task with commits" and routes them to `pi_long_task`.
-2. Creates or cleans up a TODO plan from your request.
+2. Creates or cleans up a TODO plan from your request. Natural-language planning uses a bounded planner session; if generated TODO markdown is invalid, Pi Long Task asks the planner to repair it once before failing the run.
 3. Works through each unfinished TODO task in order using isolated worker sessions.
 4. Registers a Pi TUI sidebar/widget when UI support is available and updates it with the current task, inferred subtask progress, and full task timeline while the run is active.
 5. Retries unfinished tasks up to the configured attempt limit.
-6. Records progress, task artifacts, and final results under `tmp/pi-long-task/<run-id>/`.
+6. Records progress, planner diagnostics, task artifacts, and final results under `tmp/pi-long-task/<run-id>/`.
 7. Returns a summary with completed, failed, blocked, and remaining task counts, plus worker spend when available.
 8. Optionally commits completed work after each task.
 
@@ -230,6 +230,8 @@ That smoke test creates disposable git repos and verifies both `commit: false` a
 ## Limitations and expectations
 
 - Tasks run sequentially, one TODO at a time; Pi Long Task prioritizes isolation, progress tracking, and safe handoff over parallel execution.
+- Natural-language TODO planning has a bounded time budget (five minutes by default, with a short graceful-shutdown request). If planning times out or is aborted before a valid plan exists, the run fails before worker tasks start and records planner diagnostics in `TASK_RESULT.md`.
+- If the planner returns invalid TODO markdown, Pi Long Task makes one repair attempt. A second invalid response fails planning with diagnostics instead of guessing at a plan.
 - Real runs require usable Pi model credentials, such as a working Pi login or API key for the selected model.
 - Worker spend is added to the main Pi `$ spent` total as cost-only usage. Token counts are not merged into the main thread because worker sessions have separate context windows, and merging their token usage would corrupt the main conversation's context statistics.
 - Run artifacts are written under `tmp/pi-long-task/<run-id>/`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-long-task",
-  "version": "0.3.7",
+  "version": "0.3.9",
   "type": "module",
   "description": "Pi extension for breaking down and running long coding tasks safely.",
   "keywords": [

package/src/coordinator.ts

@@ -11,17 +11,20 @@ import type {
 import { commitAfterSession, gitDirtyPaths, shouldCommitOutcome, type CommitAfterSessionResult } from "./git.ts";
 import { formatCoordinatorResultMessage } from "./render.ts";
 import { extractResultSummary } from "./result_writer.ts";
+import { runGuardedSessionPrompt } from "./session_guard.ts";
+import { parseWorkerRuntimeConfig } from "./worker_config.ts";
 import { buildTaskProgressModel, type TaskProgressModel, type TaskProgressStatus } from "./task_progress.ts";
 import {
   buildTodoCreationPrompt,
-  extractTodoMarkdown,
+  buildTodoRepairPrompt,
+  extractAndValidateTodoMarkdown,
+  TodoGenerationError,
   todoMarkdownFromString,
   validateTodoMarkdown,
 } from "./todo_generator.ts";
 import { markTaskDone, parseTasks, todoGlobalInstructions, type Task } from "./todo_parser.ts";
 import {
   createIsolatedWorkerSession,
-  lastAssistantTextFromMessages,
   runWorkerTask,
   type RunWorkerTaskOptions,
   type SessionOutcome,
@@ -34,6 +37,8 @@ export type { CoordinatorStatus } from "./types.ts";
 export const DEFAULT_COORDINATOR_OPTIONS = {
   maxAttemptsPerTask: 3,
   taskTimeoutMs: 900_000,
+  todoTimeoutMs: 300_000,
+  todoGracefulShutdownMs: 15_000,
   maxBashTimeoutMs: 300_000,
   taskThinking: "high",
   todoThinking: "xhigh",
@@ -50,6 +55,18 @@ export type CoordinatorProgressPhase =
   | "task_failed"
   | "complete";
 
+export type PlannerDiagnosticKind = "timeout" | "abort" | "invalid_output" | "repair_attempt" | "failure";
+
+export interface PlannerDiagnostic {
+  kind: PlannerDiagnosticKind;
+  message: string;
+  diagnostics?: string[];
+  sessionFile?: string;
+  sessionId?: string;
+}
+
+export type PlannerDiagnosticHandler = (diagnostic: PlannerDiagnostic) => void;
+
 export type CoordinatorProgressItemStatus = "empty" | "in_progress" | "done" | "failed" | "blocked";
 
 export interface CoordinatorProgressTask {
@@ -84,6 +101,10 @@ export interface CoordinatorProgressUpdate {
   currentTask?: CoordinatorProgressTask;
   subtasks?: CoordinatorProgressSubtask[];
   taskProgress?: TaskProgressModel;
+  plannerDiagnostic?: PlannerDiagnosticKind;
+  plannerDiagnostics?: string[];
+  plannerSessionFile?: string;
+  plannerSessionId?: string;
 }
 
 export type CoordinatorProgressHandler = (update: CoordinatorProgressUpdate) => void;
@@ -97,8 +118,12 @@ export interface RunCoordinatorOptions extends PiLongTaskInput {
   todoPlanner?: TodoPlanner;
   workerSessionFactory?: WorkerSessionFactory;
   todoSessionFactory?: WorkerSessionFactory;
+  workerModel?: unknown;
+  workerModelName?: string;
   maxAttemptsPerTask?: number;
   taskTimeoutMs?: number;
+  todoTimeoutMs?: number;
+  todoGracefulShutdownMs?: number;
   maxBashTimeoutMs?: number;
   taskThinking?: string;
   todoThinking?: string;
@@ -111,8 +136,12 @@ export interface TodoPlannerOptions {
   cwd: string;
   runDir: string;
   thinkingLevel: string;
+  model?: unknown;
   abortSignal?: AbortSignal;
+  timeoutMs?: number;
+  gracefulShutdownMs?: number;
   sessionFactory?: WorkerSessionFactory;
+  onDiagnostic?: PlannerDiagnosticHandler;
 }
 
 export interface TaskAttemptSummary {
@@ -167,8 +196,12 @@ interface RuntimeOptions {
   maxAttemptsPerTask: number;
   taskTimeoutSeconds: number;
   maxBashTimeoutSeconds: number;
+  workerModel?: unknown;
+  workerModelName?: string;
   taskThinking: string;
   todoThinking: string;
+  todoTimeoutMs: number;
+  todoGracefulShutdownMs: number;
   workerRunner: WorkerRunner;
   todoPlanner: TodoPlanner;
   abortSignal?: AbortSignal;
@@ -177,6 +210,7 @@ interface RuntimeOptions {
   now: () => Date;
   onProgress?: CoordinatorProgressHandler;
   workerCostState: WorkerCostState;
+  plannerDiagnostics: PlannerDiagnostic[];
 }
 
 export async function runCoordinator(options: RunCoordinatorOptions): Promise<CoordinatorResult> {
@@ -187,11 +221,13 @@ export async function runCoordinator(options: RunCoordinatorOptions): Promise<Co
 
   await mkdir(runtime.runDir, { recursive: true });
   await writeFile(runtime.taskResultPath, initialTaskResultMarkdown(runtime.runId), "utf8");
+  let planningComplete = false;
 
   try {
     emitProgress(runtime, "Creating TODO plan...", { phase: "planning" });
     let todoMarkdown = await generateOrNormalizeTodoMarkdown(options.inputText, runtime);
     validateTodoMarkdown(todoMarkdown);
+    planningComplete = true;
     await writeFile(runtime.todoPath, todoMarkdown, "utf8");
     const initialTasks = parseTasks(todoMarkdown);
     emitProgress(runtime, `Created TODO plan with ${initialTasks.length} task(s).`, {
@@ -240,6 +276,8 @@ export async function runCoordinator(options: RunCoordinatorOptions): Promise<Co
         globalInstructions: todoGlobalInstructions(todoMarkdown),
         maxBashTimeoutSeconds: runtime.maxBashTimeoutSeconds,
         taskTimeoutSeconds: runtime.taskTimeoutSeconds,
+        model: runtime.workerModel,
+        modelName: runtime.workerModelName,
         thinkingLevel: runtime.taskThinking,
         abortSignal: runtime.abortSignal,
         sessionFactory: runtime.workerSessionFactory,
@@ -371,9 +409,18 @@ export async function runCoordinator(options: RunCoordinatorOptions): Promise<Co
     return result;
   } catch (error) {
     const message = errorMessage(error);
-    const summary = `Pi Long Task failed: ${message}`;
+    if (!planningComplete) {
+      recordPlannerDiagnostic(runtime, {
+        kind: "failure",
+        message: `TODO planning failed: ${message}`,
+      });
+    }
+    const resultError = !planningComplete
+      ? `${message} See ${runtime.taskResultPath} for planner diagnostics.`
+      : message;
+    const summary = `Pi Long Task failed: ${resultError}`;
     try {
-      await appendFile(runtime.taskResultPath, `\n## Pi Long Task failure\n\n${message}\n`, "utf8");
+      await appendFailureNote(runtime.taskResultPath, message, !planningComplete ? runtime.plannerDiagnostics : []);
     } catch {
       // Best effort only; the original error is returned below.
     }
@@ -399,7 +446,7 @@ export async function runCoordinator(options: RunCoordinatorOptions): Promise<Co
       taskProgress: buildTaskProgressModel({ tasks: [], attempts }),
       workerCostTotal: runtime.workerCostState.total,
       commit: options.commit,
-      error: message,
+      error: resultError,
     };
     result.message = formatCoordinatorResultMessage(result);
     emitProgress(runtime, "Pi Long Task failed.", {
@@ -417,49 +464,242 @@ async function generateOrNormalizeTodoMarkdown(inputText: string, runtime: Runti
     return local;
   }
 
-  const plannerText = await runtime.todoPlanner({
+  const plannerText = await requestTodoPlan(inputText, runtime);
+  return extractTodoMarkdownWithOneRepair(
+    inputText,
+    plannerText,
+    (repairPrompt) => requestTodoPlan(repairPrompt, runtime),
+    {
+      onInvalidOutput: (validationError) =>
+        recordPlannerDiagnostic(runtime, {
+          kind: "invalid_output",
+          message: `TODO planner returned invalid output: ${validationError}`,
+        }),
+      onRepairAttempt: (validationError) =>
+        recordPlannerDiagnostic(runtime, {
+          kind: "repair_attempt",
+          message: `Asking TODO planner to repair invalid output: ${validationError}`,
+        }),
+      onFailure: (validationError) =>
+        recordPlannerDiagnostic(runtime, {
+          kind: "failure",
+          message: `TODO planner repair failed: ${validationError}`,
+        }),
+    },
+  );
+}
+
+interface TodoExtractionRepairHooks {
+  onInvalidOutput?: (validationError: string) => void;
+  onRepairAttempt?: (validationError: string) => void;
+  onFailure?: (validationError: string) => void;
+}
+
+async function extractTodoMarkdownWithOneRepair(
+  inputText: string,
+  plannerText: string,
+  requestRepair: (repairPrompt: string) => Promise<string>,
+  hooks: TodoExtractionRepairHooks = {},
+): Promise<string> {
+  try {
+    return extractAndValidateTodoMarkdown(plannerText);
+  } catch (error) {
+    const validationError = errorMessage(error);
+    hooks.onInvalidOutput?.(validationError);
+    hooks.onRepairAttempt?.(validationError);
+    const repairText = await requestRepair(buildTodoRepairPrompt(inputText, plannerText, validationError));
+    try {
+      return extractAndValidateTodoMarkdown(repairText);
+    } catch (repairError) {
+      const repairMessage = errorMessage(repairError);
+      hooks.onFailure?.(repairMessage);
+      throw new TodoGenerationError(
+        `TODO planner returned invalid TODO markdown after one repair attempt: ${repairMessage}`,
+      );
+    }
+  }
+}
+
+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),
   });
-  return extractTodoMarkdown(plannerText);
 }
 
+// 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> {
-  let session: WorkerSessionLike | undefined;
+  const sessionFactory = options.sessionFactory ?? createIsolatedWorkerSession;
+  const result = await sessionFactory({
+    cwd: options.cwd,
+    tools: [],
+    model: options.model,
+    thinkingLevel: options.thinkingLevel,
+  });
+  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;
+
   try {
-    const sessionFactory = options.sessionFactory ?? createIsolatedWorkerSession;
-    const result = await sessionFactory({
-      cwd: options.cwd,
-      tools: [],
-      thinkingLevel: options.thinkingLevel,
+    const plannerText = await runTodoPlannerPrompt({
+      session,
+      prompt: buildTodoCreationPrompt(options.inputText),
+      abortSignal: options.abortSignal,
+      timeoutMs,
+      gracefulShutdownMs,
+      diagnostics: result.diagnostics,
+      onDiagnostic: options.onDiagnostic,
     });
-    session = result.session;
 
-    if (options.abortSignal?.aborted) {
-      throw new Error("TODO planner aborted before start");
-    }
+    plannerMarkdown = await extractTodoMarkdownWithOneRepair(
+      options.inputText,
+      plannerText,
+      (repairPrompt) =>
+        runTodoPlannerPrompt({
+          session,
+          prompt: repairPrompt,
+          abortSignal: options.abortSignal,
+          timeoutMs,
+          gracefulShutdownMs,
+          diagnostics: result.diagnostics,
+          onDiagnostic: options.onDiagnostic,
+        }),
+      {
+        onInvalidOutput: (validationError) =>
+          options.onDiagnostic?.({
+            kind: "invalid_output",
+            message: `TODO planner returned invalid output: ${validationError}`,
+            diagnostics: result.diagnostics,
+            sessionFile: session.sessionFile,
+            sessionId: session.sessionId,
+          }),
+        onRepairAttempt: (validationError) =>
+          options.onDiagnostic?.({
+            kind: "repair_attempt",
+            message: `Asking TODO planner to repair invalid output: ${validationError}`,
+            diagnostics: result.diagnostics,
+            sessionFile: session.sessionFile,
+            sessionId: session.sessionId,
+          }),
+        onFailure: (validationError) =>
+          options.onDiagnostic?.({
+            kind: "failure",
+            message: `TODO planner repair failed: ${validationError}`,
+            diagnostics: result.diagnostics,
+            sessionFile: session.sessionFile,
+            sessionId: session.sessionId,
+          }),
+      },
+    );
+  } catch (error) {
+    plannerError = error;
+  }
 
-    await session.prompt(buildTodoCreationPrompt(options.inputText));
-    const direct = session.getLastAssistantText?.();
-    const fromMessages = lastAssistantTextFromMessages(session.messages);
-    const text = direct || fromMessages;
-    if (!text) {
-      throw new Error("TODO planner did not return assistant text.");
-    }
-    return text;
-  } finally {
-    session?.dispose?.();
+  try {
+    await Promise.resolve(session.dispose?.());
+  } catch (error) {
+    plannerError = plannerError ?? new TodoGenerationError(`TODO planner dispose failed: ${errorMessage(error)}`);
+  }
+
+  if (plannerError) {
+    throw plannerError;
   }
+  if (!plannerMarkdown) {
+    throw new TodoGenerationError("TODO planner did not return valid TODO markdown.");
+  }
+  return plannerMarkdown;
+}
+
+async function runTodoPlannerPrompt(options: {
+  session: WorkerSessionLike;
+  prompt: string;
+  abortSignal?: AbortSignal;
+  timeoutMs: number;
+  gracefulShutdownMs: number;
+  diagnostics?: string[];
+  onDiagnostic?: PlannerDiagnosticHandler;
+}): Promise<string> {
+  const promptResult = await runGuardedSessionPrompt({
+    session: options.session,
+    prompt: options.prompt,
+    abortSignal: options.abortSignal,
+    timeoutMs: options.timeoutMs,
+    gracefulShutdownMs: options.gracefulShutdownMs,
+    gracefulShutdownPrompt: buildTodoPlanningShutdownMessage(),
+    diagnostics: options.diagnostics,
+    dispose: false,
+  });
+
+  if (promptResult.timedOut) {
+    const message = `TODO planner timed out: ${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));
+    throw new TodoGenerationError(message);
+  }
+  if (promptResult.error) {
+    const message = `TODO planner failed: ${promptResult.error}`;
+    options.onDiagnostic?.(plannerPromptDiagnostic("failure", message, promptResult));
+    throw new TodoGenerationError(message);
+  }
+  if (!promptResult.assistantText) {
+    const message = "TODO planner did not return assistant text.";
+    options.onDiagnostic?.(plannerPromptDiagnostic("failure", message, promptResult));
+    throw new TodoGenerationError(message);
+  }
+  return promptResult.assistantText;
+}
+
+function plannerPromptDiagnostic(
+  kind: Extract<PlannerDiagnosticKind, "timeout" | "abort" | "failure">,
+  message: string,
+  promptResult: {
+    diagnostics: string[];
+    sessionFile?: string;
+    sessionId?: string;
+  },
+): PlannerDiagnostic {
+  return {
+    kind,
+    message,
+    diagnostics: promptResult.diagnostics,
+    sessionFile: promptResult.sessionFile,
+    sessionId: promptResult.sessionId,
+  };
+}
+
+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.`;
 }
 
 function buildRuntimeOptions(options: RunCoordinatorOptions): RuntimeOptions {
   const cwd = path.resolve(options.cwd ?? process.cwd());
   const runId = sanitizeRunId(options.runId ?? defaultRunId(options.now?.() ?? new Date()));
   const runDir = path.join(cwd, "tmp", "pi-long-task", runId);
+  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 configuredMaxBashTimeoutMs = options.maxBashTimeoutMs ?? parsedWorkerConfig.maxBashTimeoutMs;
+  const workerModelName = options.workerModelName ?? parsedWorkerConfig.modelName;
+  const workerModel = workerModelName ? undefined : options.workerModel;
 
   return {
     cwd,
@@ -467,10 +707,17 @@ function buildRuntimeOptions(options: RunCoordinatorOptions): RuntimeOptions {
     runDir,
     todoPath: path.join(runDir, "TODO.md"),
     taskResultPath: path.join(runDir, "TASK_RESULT.md"),
-    maxAttemptsPerTask: positiveInteger(options.maxAttemptsPerTask, DEFAULT_COORDINATOR_OPTIONS.maxAttemptsPerTask),
-    taskTimeoutSeconds: positiveMilliseconds(options.taskTimeoutMs, DEFAULT_COORDINATOR_OPTIONS.taskTimeoutMs) / 1000,
+    maxAttemptsPerTask: positiveInteger(configuredAttempts, DEFAULT_COORDINATOR_OPTIONS.maxAttemptsPerTask),
+    taskTimeoutSeconds: positiveMilliseconds(configuredTaskTimeoutMs, DEFAULT_COORDINATOR_OPTIONS.taskTimeoutMs) / 1000,
+    todoTimeoutMs: positiveMilliseconds(configuredTodoTimeoutMs, DEFAULT_COORDINATOR_OPTIONS.todoTimeoutMs),
+    todoGracefulShutdownMs: positiveMilliseconds(
+      configuredTodoGracefulShutdownMs,
+      DEFAULT_COORDINATOR_OPTIONS.todoGracefulShutdownMs,
+    ),
     maxBashTimeoutSeconds:
-      positiveMilliseconds(options.maxBashTimeoutMs, DEFAULT_COORDINATOR_OPTIONS.maxBashTimeoutMs) / 1000,
+      positiveMilliseconds(configuredMaxBashTimeoutMs, DEFAULT_COORDINATOR_OPTIONS.maxBashTimeoutMs) / 1000,
+    workerModel,
+    workerModelName,
     taskThinking: options.taskThinking ?? DEFAULT_COORDINATOR_OPTIONS.taskThinking,
     todoThinking: options.todoThinking ?? DEFAULT_COORDINATOR_OPTIONS.todoThinking,
     workerRunner: options.workerRunner ?? runWorkerTask,
@@ -481,6 +728,7 @@ function buildRuntimeOptions(options: RunCoordinatorOptions): RuntimeOptions {
     now: options.now ?? (() => new Date()),
     onProgress: options.onProgress,
     workerCostState: createWorkerCostState(),
+    plannerDiagnostics: [],
   };
 }
 
@@ -499,6 +747,31 @@ function emitProgress(
   });
 }
 
+function recordPlannerDiagnostic(runtime: RuntimeOptions, diagnostic: PlannerDiagnostic): void {
+  const normalized: PlannerDiagnostic = {
+    kind: diagnostic.kind,
+    message: diagnostic.message,
+    diagnostics: diagnostic.diagnostics?.filter(Boolean),
+    sessionFile: diagnostic.sessionFile,
+    sessionId: diagnostic.sessionId,
+  };
+  const last = runtime.plannerDiagnostics.at(-1);
+  if (last?.kind === normalized.kind && last.message === normalized.message) {
+    return;
+  }
+  runtime.plannerDiagnostics.push(normalized);
+  emitProgress(runtime, normalized.message, {
+    phase: "planning",
+    status: normalized.kind,
+    isError: normalized.kind !== "repair_attempt",
+    plannerDiagnostic: normalized.kind,
+    plannerDiagnostics: normalized.diagnostics,
+    plannerSessionFile: normalized.sessionFile,
+    plannerSessionId: normalized.sessionId,
+    taskProgress: buildTaskProgressModel({ tasks: [] }),
+  });
+}
+
 function createWorkerCostState(): WorkerCostState {
   return {
     total: 0,
@@ -753,6 +1026,30 @@ function initialTaskResultMarkdown(runId: string): string {
   return `# Pi Long Task TASK_RESULT\n\nRun: ${runId}\n`;
 }
 
+async function appendFailureNote(
+  pathname: string,
+  message: string,
+  plannerDiagnostics: readonly PlannerDiagnostic[],
+): Promise<void> {
+  const lines = ["", "## Pi Long Task failure", "", message];
+  if (plannerDiagnostics.length > 0) {
+    lines.push("", "### Planner diagnostics");
+    for (const diagnostic of plannerDiagnostics) {
+      lines.push("", `- ${diagnostic.kind}: ${diagnostic.message}`);
+      if (diagnostic.sessionId) {
+        lines.push(`  - Session ID: ${diagnostic.sessionId}`);
+      }
+      if (diagnostic.sessionFile) {
+        lines.push(`  - Session file: ${diagnostic.sessionFile}`);
+      }
+      for (const item of diagnostic.diagnostics ?? []) {
+        lines.push(`  - Diagnostic: ${item}`);
+      }
+    }
+  }
+  await appendFile(pathname, `${lines.join("\n")}\n`, "utf8");
+}
+
 async function appendCommitNote(pathname: string, result: CommitAfterSessionResult): Promise<void> {
   const lines = ["", "### Commit note", ""];
   if (result.hash) {

package/src/index.ts

@@ -1,6 +1,6 @@
 import type { ExtensionAPI, ExtensionContext, Theme } from "@earendil-works/pi-coding-agent";
 import type { AssistantMessage } from "@earendil-works/pi-ai";
-import { truncateToWidth, type Component, type TUI } from "@earendil-works/pi-tui";
+import { truncateToWidth, type Component, type OverlayHandle, type TUI } from "@earendil-works/pi-tui";
 
 import { runCoordinator, type CoordinatorProgressUpdate, type CoordinatorResult } from "./coordinator.ts";
 import { longTaskInputTransform } from "./input_router.ts";
@@ -72,6 +72,7 @@ function toolDetails(result: CoordinatorResult) {
     taskProgress: result.taskProgress,
     workerCostTotal: result.workerCostTotal,
     summary: result.summary,
+    error: result.error,
   };
 }
 
@@ -118,20 +119,24 @@ export function createLongTaskSidebarController(ctx: UiContext | undefined): Lon
   }
 
   let latestUpdate: CoordinatorProgressUpdate | undefined;
-  let sidebarComponent: PiLongTaskSidebarComponent | undefined;
-  let sidebarTui: TUI | undefined;
+  let widgetComponent: PiLongTaskSidebarComponent | undefined;
+  let widgetTui: TUI | undefined;
+  let overlayComponent: PiLongTaskSidebarComponent | undefined;
+  let overlayTui: TUI | undefined;
+  let overlayDone: ((result: undefined) => void) | undefined;
+  let overlayHandle: OverlayHandle | undefined;
   let closed = false;
 
   if (supportsTuiWidget(ctx)) {
     ctx.ui.setWidget(
       LONG_TASK_WIDGET_KEY,
       (tui, theme) => {
-        sidebarTui = tui;
-        sidebarComponent = new PiLongTaskSidebarComponent(theme, () => sidebarWidgetLineLimit(tui));
+        widgetTui = tui;
+        widgetComponent = new PiLongTaskSidebarComponent(theme, () => sidebarWidgetLineLimit(tui));
         if (latestUpdate) {
-          sidebarComponent.setUpdate(latestUpdate);
+          widgetComponent.setUpdate(latestUpdate);
         }
-        return sidebarComponent;
+        return widgetComponent;
       },
       { placement: "aboveEditor" },
     );
@@ -139,15 +144,59 @@ export function createLongTaskSidebarController(ctx: UiContext | undefined): Lon
     ctx.ui.setWidget(LONG_TASK_WIDGET_KEY, ["Pi Long Task: preparing sidebar..."], { placement: "aboveEditor" });
   }
 
+  if (supportsTuiOverlay(ctx)) {
+    try {
+      const overlayPromise = ctx.ui.custom<undefined>(
+        (tui, theme, _keybindings, done) => {
+          overlayTui = tui;
+          overlayDone = done;
+          overlayComponent = new PiLongTaskSidebarComponent(theme);
+          if (latestUpdate) {
+            overlayComponent.setUpdate(latestUpdate);
+          }
+          if (closed) {
+            done(undefined);
+          }
+          return overlayComponent;
+        },
+        {
+          overlay: true,
+          overlayOptions: {
+            anchor: "right-center",
+            width: "34%",
+            minWidth: 32,
+            maxHeight: "85%",
+            margin: 1,
+            nonCapturing: true,
+            visible: (termWidth, termHeight) => termWidth >= 96 && termHeight >= 16,
+          },
+          onHandle: (handle) => {
+            overlayHandle = handle;
+            handle.unfocus();
+          },
+        },
+      );
+      void overlayPromise.catch(() => {
+        // The widget fallback remains active if overlay registration is unavailable.
+      });
+    } catch {
+      // The widget fallback remains active if overlay registration is unavailable.
+    }
+  }
+
   return {
     update(update: CoordinatorProgressUpdate): void {
       if (closed) {
         return;
       }
       latestUpdate = update;
-      sidebarComponent?.setUpdate(update);
-      sidebarTui?.requestRender();
-      if (!sidebarComponent) {
+      widgetComponent?.setUpdate(update);
+      overlayComponent?.setUpdate(update);
+      widgetTui?.requestRender();
+      if (overlayTui && overlayTui !== widgetTui) {
+        overlayTui.requestRender();
+      }
+      if (!widgetComponent) {
         ctx.ui.setWidget(LONG_TASK_WIDGET_KEY, renderSidebarWidgetLines(update), { placement: "aboveEditor" });
       }
     },
@@ -157,8 +206,17 @@ export function createLongTaskSidebarController(ctx: UiContext | undefined): Lon
       }
       closed = true;
       ctx.ui.setWidget(LONG_TASK_WIDGET_KEY, undefined);
-      sidebarComponent = undefined;
-      sidebarTui = undefined;
+      if (overlayHandle) {
+        overlayHandle.hide();
+      } else {
+        overlayDone?.(undefined);
+      }
+      widgetComponent = undefined;
+      widgetTui = undefined;
+      overlayComponent = undefined;
+      overlayTui = undefined;
+      overlayDone = undefined;
+      overlayHandle = undefined;
     },
   };
 }
@@ -168,6 +226,11 @@ function supportsTuiWidget(ctx: UiContext): boolean {
   return mode === "tui" || mode === undefined;
 }
 
+function supportsTuiOverlay(ctx: UiContext): boolean {
+  const mode = (ctx as UiContext & { mode?: string }).mode;
+  return mode === "tui" || mode === undefined;
+}
+
 function sidebarWidgetLineLimit(tui: TUI): number {
   const terminalRows = tui.terminal.rows;
   const rows = Number.isFinite(terminalRows) ? Math.max(0, Math.floor(terminalRows)) : 24;
@@ -679,6 +742,7 @@ export default function registerPiLongTaskExtension(pi: ExtensionAPI) {
         const result = await runCoordinator({
           ...params,
           cwd: ctx?.cwd,
+          workerModel: ctx?.model,
           abortSignal: signal,
           onProgress: publishProgress,
         });

package/src/session_guard.ts

@@ -0,0 +1,287 @@
+import {
+  assistantTextFromEvent,
+  lastAssistantTextFromEvents,
+  lastAssistantTextFromMessages,
+  type WorkerSessionLike,
+} from "./worker_session.ts";
+
+export interface GuardedSessionPromptOptions {
+  session: WorkerSessionLike;
+  prompt: string;
+  promptOptions?: Record<string, unknown>;
+  abortSignal?: AbortSignal;
+  timeoutMs?: number;
+  gracefulShutdownMs?: number;
+  gracefulShutdownPrompt?: string;
+  diagnostics?: string[];
+  onEvent?: (event: unknown) => void;
+  dispose?: boolean;
+}
+
+export interface GuardedSessionPromptResult {
+  assistantText: string;
+  timedOut: boolean;
+  aborted: boolean;
+  error?: string;
+  diagnostics: string[];
+  events: unknown[];
+  sessionFile?: string;
+  sessionId?: string;
+}
+
+export async function runGuardedSessionPrompt(
+  options: GuardedSessionPromptOptions,
+): Promise<GuardedSessionPromptResult> {
+  const session = options.session;
+  const diagnostics = [...(options.diagnostics ?? [])];
+  const events: unknown[] = [];
+  const timers = new Set<ReturnType<typeof setTimeout>>();
+  let assistantText = "";
+  let timedOut = false;
+  let aborted = false;
+  let error: string | undefined;
+  let promptSettled = false;
+  let finished = false;
+  let unsubscribe: (() => void) | undefined;
+  let complete: (() => void) | undefined;
+
+  const completed = new Promise<void>((resolve) => {
+    complete = resolve;
+  });
+
+  const resolveCompleted = () => {
+    complete?.();
+    complete = undefined;
+  };
+
+  const clearTimers = () => {
+    for (const timer of timers) {
+      clearTimeout(timer);
+    }
+    timers.clear();
+  };
+
+  const schedule = (fn: () => void, ms: number) => {
+    const timer = setTimeout(() => {
+      timers.delete(timer);
+      fn();
+    }, ms);
+    timers.add(timer);
+  };
+
+  const abortSession = (reason: string) => {
+    if (finished || aborted) {
+      return;
+    }
+    aborted = true;
+    error = error ?? reason;
+    try {
+      const abortResult = session.abort?.();
+      if (isPromiseLike(abortResult)) {
+        void abortResult.catch((exc: unknown) => {
+          diagnostics.push(`session abort failed: ${errorMessage(exc)}`);
+        });
+      }
+    } catch (exc) {
+      diagnostics.push(`session abort failed: ${errorMessage(exc)}`);
+    }
+  };
+
+  const requestGracefulShutdown = () => {
+    const message = options.gracefulShutdownPrompt?.trim();
+    if (!message || finished || promptSettled || aborted) {
+      return;
+    }
+
+    try {
+      if (session.isBashRunning && session.abortBash) {
+        session.abortBash();
+        diagnostics.push("aborted running bash before graceful shutdown request");
+      }
+
+      let request: Promise<unknown> | undefined;
+      if ((session.isStreaming || session.isBashRunning) && session.steer) {
+        request = session.steer(message);
+      } else if (session.followUp) {
+        request = session.followUp(message);
+      } else if (session.steer) {
+        request = session.steer(message);
+      }
+
+      if (!request) {
+        diagnostics.push("graceful shutdown request skipped: session does not support steer/followUp");
+        return;
+      }
+
+      void request.catch((exc: unknown) => {
+        diagnostics.push(`graceful shutdown request failed: ${errorMessage(exc)}`);
+      });
+    } catch (exc) {
+      diagnostics.push(`graceful shutdown request failed: ${errorMessage(exc)}`);
+    }
+  };
+
+  const triggerTimeout = () => {
+    if (finished || promptSettled || timedOut) {
+      return;
+    }
+    timedOut = true;
+    diagnostics.push(`session prompt timed out after ${formatMilliseconds(timeoutMs(options.timeoutMs))}`);
+    requestGracefulShutdown();
+
+    const graceMs = nonNegativeMilliseconds(options.gracefulShutdownMs);
+    const hardAbort = () => {
+      if (finished || promptSettled) {
+        return;
+      }
+      abortSession(`session prompt exceeded ${formatMilliseconds(timeoutMs(options.timeoutMs))} timeout`);
+      resolveCompleted();
+    };
+
+    if (graceMs > 0) {
+      schedule(hardAbort, graceMs);
+    } else {
+      hardAbort();
+    }
+  };
+
+  const abortListener = () => {
+    if (finished || promptSettled) {
+      return;
+    }
+    abortSession(abortReason(options.abortSignal, "session prompt aborted by outer signal"));
+    resolveCompleted();
+  };
+
+  try {
+    if (options.abortSignal?.aborted) {
+      aborted = true;
+      error = abortReason(options.abortSignal, "session prompt aborted before start");
+    } else {
+      unsubscribe = session.subscribe((event: unknown) => {
+        events.push(event);
+        const text = assistantTextFromEvent(event);
+        if (text) {
+          assistantText = text;
+        }
+        try {
+          options.onEvent?.(event);
+        } catch (exc) {
+          diagnostics.push(`event listener failed: ${errorMessage(exc)}`);
+        }
+      });
+
+      options.abortSignal?.addEventListener("abort", abortListener, { once: true });
+
+      const promptPromise = session.prompt(options.prompt, options.promptOptions).then(
+        () => {
+          promptSettled = true;
+          resolveCompleted();
+        },
+        (exc: unknown) => {
+          promptSettled = true;
+          error = error ?? errorMessage(exc);
+          resolveCompleted();
+        },
+      );
+      void promptPromise;
+
+      const limitMs = timeoutMs(options.timeoutMs);
+      if (limitMs > 0) {
+        schedule(triggerTimeout, limitMs);
+      }
+
+      await completed;
+    }
+  } catch (exc) {
+    error = error ?? errorMessage(exc);
+  } finally {
+    finished = true;
+    clearTimers();
+    options.abortSignal?.removeEventListener("abort", abortListener);
+    unsubscribe?.();
+    assistantText = latestAssistantText(session, events, assistantText);
+    if (options.dispose !== false) {
+      try {
+        const disposeResult = (session.dispose as (() => unknown) | undefined)?.();
+        if (isPromiseLike(disposeResult)) {
+          await disposeResult;
+        }
+      } catch (exc) {
+        const message = `session dispose failed: ${errorMessage(exc)}`;
+        diagnostics.push(message);
+        error = error ?? message;
+      }
+    }
+  }
+
+  return buildResult(session, events, assistantText, timedOut, aborted, error, diagnostics);
+}
+
+function buildResult(
+  session: WorkerSessionLike,
+  events: unknown[],
+  assistantText: string,
+  timedOut: boolean,
+  aborted: boolean,
+  error: string | undefined,
+  diagnostics: string[],
+): GuardedSessionPromptResult {
+  return {
+    assistantText: latestAssistantText(session, events, assistantText),
+    timedOut,
+    aborted,
+    error,
+    diagnostics: [...diagnostics],
+    events: [...events],
+    sessionFile: session.sessionFile,
+    sessionId: session.sessionId,
+  };
+}
+
+function latestAssistantText(session: WorkerSessionLike, events: unknown[], fallback: string): string {
+  const direct = session.getLastAssistantText?.();
+  if (direct) {
+    return direct;
+  }
+  const fromMessages = lastAssistantTextFromMessages(session.messages);
+  if (fromMessages) {
+    return fromMessages;
+  }
+  const fromEvents = lastAssistantTextFromEvents(events);
+  return fromEvents || fallback;
+}
+
+function timeoutMs(value: number | undefined): number {
+  if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) {
+    return 0;
+  }
+  return Math.max(0, value);
+}
+
+function nonNegativeMilliseconds(value: number | undefined): number {
+  if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) {
+    return 0;
+  }
+  return Math.max(0, value);
+}
+
+function formatMilliseconds(ms: number): string {
+  return `${(ms / 1000).toFixed(3)}s`;
+}
+
+function abortReason(signal: AbortSignal | undefined, fallback: string): string {
+  const reason = signal?.reason;
+  if (reason === undefined) {
+    return fallback;
+  }
+  return errorMessage(reason);
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function isPromiseLike(value: unknown): value is PromiseLike<unknown> {
+  return typeof value === "object" && value !== null && "then" in value && typeof value.then === "function";
+}

package/src/todo_generator.ts

@@ -120,6 +120,16 @@ export function buildTodoCreationPrompt(rawInput: string): string {
   return `Convert the following raw project request into Pi Long Task-compatible TODO markdown.\n\nRequirements:\n- Output only markdown, with no commentary and no code fence.\n- Start with exactly: # Pi Long Task TODO\n- Include a ## Progress section with one unchecked line per task: - [ ] TODO N — Title\n- Include a --- separator before task sections.\n- Create sequential sections named ## TODO N — Title.\n- Each task section must include **Goal:**, **Status:** with unchecked checkbox items, **Verify:** with concrete verification guidance, and **Done when:**.\n- Preserve any global instructions or constraints that apply to all tasks above ## Progress.\n- Keep tasks focused and independently assignable to worker sessions.\n\nRaw input:\n\n${rawInput.trim()}\n`;
 }
 
+export function buildTodoRepairPrompt(rawInput: string, invalidOutput: string, validationError: string): string {
+  return `Your previous response was not valid Pi Long Task TODO markdown. Correct it now.\n\nValidation/extraction error:\n${validationError.trim() || "Unknown validation error."}\n\nRequirements:\n- Output only corrected markdown, with no commentary and no code fence.\n- Start with exactly: # Pi Long Task TODO\n- Include a ## Progress section with one unchecked line per task: - [ ] TODO N — Title\n- Include a --- separator before task sections.\n- Create sequential sections named ## TODO N — Title.\n- Each task section must include **Goal:**, **Status:** with unchecked checkbox items, **Verify:** with concrete verification guidance, and **Done when:**.\n- Preserve any global instructions or constraints that apply to all tasks above ## Progress.\n- Keep tasks focused and independently assignable to worker sessions.\n\nOriginal raw input:\n\n${rawInput.trim()}\n\nPrevious invalid output:\n\n${invalidOutput.trim()}\n`;
+}
+
+export function extractAndValidateTodoMarkdown(assistantText: string): string {
+  const markdown = extractTodoMarkdown(assistantText);
+  validateTodoMarkdown(markdown);
+  return markdown;
+}
+
 export function extractTodoMarkdown(assistantText: string): string {
   for (const block of fencedMarkdownBlocks(assistantText)) {
     const candidate = normalizeCandidate(block);

package/src/worker_config.ts

@@ -0,0 +1,291 @@
+export interface ParsedWorkerRuntimeConfig {
+  modelName?: string;
+  maxAttemptsPerTask?: number;
+  taskTimeoutMs?: number;
+  maxBashTimeoutMs?: number;
+}
+
+const MODEL_TOKEN_RE = /[A-Za-z0-9][A-Za-z0-9._~:+/@-]*/;
+const STOP_WORDS = new Set([
+  "and",
+  "as",
+  "for",
+  "from",
+  "in",
+  "is",
+  "of",
+  "on",
+  "per",
+  "please",
+  "task",
+  "tasks",
+  "the",
+  "to",
+  "use",
+  "with",
+  "worker",
+  "workers",
+]);
+
+export function parseWorkerRuntimeConfig(text: string): ParsedWorkerRuntimeConfig {
+  const state: ParsedWorkerRuntimeConfig & { provider?: string; model?: string } = {};
+
+  parseLineDirectives(text, state);
+  parseNaturalLanguageDirectives(text, state);
+
+  const modelName = combineProviderAndModel(state.provider, state.model);
+  return {
+    ...(modelName ? { modelName } : {}),
+    ...(state.maxAttemptsPerTask !== undefined ? { maxAttemptsPerTask: state.maxAttemptsPerTask } : {}),
+    ...(state.taskTimeoutMs !== undefined ? { taskTimeoutMs: state.taskTimeoutMs } : {}),
+    ...(state.maxBashTimeoutMs !== undefined ? { maxBashTimeoutMs: state.maxBashTimeoutMs } : {}),
+  };
+}
+
+function parseLineDirectives(
+  text: string,
+  state: ParsedWorkerRuntimeConfig & { provider?: string; model?: string },
+): void {
+  for (const rawLine of text.split(/\r?\n/)) {
+    const line = rawLine.replace(/^\s{0,3}>+\s?/, "").trim();
+    const match = line.match(
+      /^(?:[-*+]\s*)?(?:(pi\s+long\s+task|long\s+task|worker|workers?|task)\s+)?([a-z][a-z\s-]{0,40})\s*(?::|=)\s*(.+)$/i,
+    );
+    if (!match) {
+      continue;
+    }
+
+    const prefix = normalizeWords(match[1] ?? "");
+    const key = normalizeWords(match[2] ?? "");
+    const fullKey = normalizeWords(`${prefix} ${key}`);
+    const value = match[3] ?? "";
+
+    applyDirective(fullKey, value, state);
+  }
+}
+
+function parseNaturalLanguageDirectives(
+  text: string,
+  state: ParsedWorkerRuntimeConfig & { provider?: string; model?: string },
+): void {
+  captureTokens(
+    text,
+    /\bworker\s+(?:model|provider\/model)\s*(?:is|=|:|to|as)?\s*[`'"]?([A-Za-z0-9][A-Za-z0-9._~:+/@-]*)/gi,
+    (token) => {
+      state.model = token;
+    },
+  );
+  captureTokens(
+    text,
+    /\b(?:use|using|with|set|run(?:ning)?)\s+(?:the\s+)?(?:worker\s+)?model\s*(?:to|as|is|=|:)?\s*[`'"]?([A-Za-z0-9][A-Za-z0-9._~:+/@-]*)/gi,
+    (token) => {
+      state.model = token;
+    },
+  );
+  captureTokens(text, /\bmodel\s*(?:=|:)\s*[`'"]?([A-Za-z0-9][A-Za-z0-9._~:+/@-]*)/gi, (token) => {
+    state.model = token;
+  });
+
+  captureTokens(
+    text,
+    /\bworker\s+provider\s*(?:is|=|:|to|as)?\s*[`'"]?([A-Za-z0-9][A-Za-z0-9._~:+/@-]*)/gi,
+    (token) => {
+      state.provider = token;
+    },
+  );
+  captureTokens(text, /\bprovider\s*(?:=|:)\s*[`'"]?([A-Za-z0-9][A-Za-z0-9._~:+/@-]*)/gi, (token) => {
+    state.provider = token;
+  });
+  captureTokens(
+    text,
+    /\b(?:use|using|with|set)\s+(?:the\s+)?(?:worker\s+)?provider\s*(?:to|as|is|=|:)?\s*[`'"]?([A-Za-z0-9][A-Za-z0-9._~:+/@-]*)/gi,
+    (token) => {
+      state.provider = token;
+    },
+  );
+
+  captureNumbers(
+    text,
+    /\b(?:max(?:imum)?\s+)?(?:worker\s+|task\s+)?attempts?\s*(?:per\s+task)?\s*(?:is|=|:|to|at)?\s*(\d+)/gi,
+    (value) => {
+      state.maxAttemptsPerTask = value;
+    },
+  );
+  captureNumbers(text, /\b(\d+)\s+(?:worker\s+|task\s+)?attempts?\b/gi, (value) => {
+    state.maxAttemptsPerTask = value;
+  });
+  captureNumbers(text, /\btry\s+(?:each\s+task\s+)?(?:up\s+to\s+)?(\d+)\s+times\b/gi, (value) => {
+    state.maxAttemptsPerTask = value;
+  });
+
+  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,
+    (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,
+    (value) => {
+      state.taskTimeoutMs = value;
+    },
+  );
+  captureDurations(
+    text,
+    /\b(?:max\s+)?bash\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.maxBashTimeoutMs = value;
+    },
+  );
+}
+
+function applyDirective(
+  key: string,
+  value: string,
+  state: ParsedWorkerRuntimeConfig & { provider?: string; model?: string },
+): void {
+  if (/\bprovider\b/.test(key)) {
+    const token = modelToken(value);
+    if (token) {
+      state.provider = token;
+    }
+    return;
+  }
+
+  if (/\bmodel\b/.test(key)) {
+    const token = modelToken(value);
+    if (token) {
+      state.model = token;
+    }
+    return;
+  }
+
+  if (/\b(?:attempt|attempts|retry|retries)\b/.test(key)) {
+    const attempts = positiveIntegerFromText(value);
+    if (attempts !== undefined) {
+      state.maxAttemptsPerTask = attempts;
+    }
+    return;
+  }
+
+  if (/\bbash\b/.test(key) && /\btimeout\b/.test(key)) {
+    const timeout = durationMsFromText(value, { allowBareSeconds: true });
+    if (timeout !== undefined) {
+      state.maxBashTimeoutMs = timeout;
+    }
+    return;
+  }
+
+  if (/\btimeout\b/.test(key)) {
+    const timeout = durationMsFromText(value, { allowBareSeconds: true });
+    if (timeout !== undefined) {
+      state.taskTimeoutMs = timeout;
+    }
+  }
+}
+
+function captureTokens(text: string, pattern: RegExp, apply: (token: string) => void): void {
+  for (const match of text.matchAll(pattern)) {
+    const token = modelToken(match[1] ?? "");
+    if (token) {
+      apply(token);
+    }
+  }
+}
+
+function captureNumbers(text: string, pattern: RegExp, apply: (value: number) => void): void {
+  for (const match of text.matchAll(pattern)) {
+    const value = positiveIntegerFromText(match[1] ?? "");
+    if (value !== undefined) {
+      apply(value);
+    }
+  }
+}
+
+function captureDurations(text: string, pattern: RegExp, apply: (value: number) => void): void {
+  for (const match of text.matchAll(pattern)) {
+    const value = durationMsFromText(match[1] ?? "", { allowBareSeconds: true });
+    if (value !== undefined) {
+      apply(value);
+    }
+  }
+}
+
+function combineProviderAndModel(provider: string | undefined, model: string | undefined): string | undefined {
+  if (!model) {
+    return undefined;
+  }
+  if (model.includes("/") || !provider) {
+    return model;
+  }
+  return `${provider}/${model}`;
+}
+
+function modelToken(value: string): string | undefined {
+  const trimmed = trimDirectiveValue(value);
+  const match = MODEL_TOKEN_RE.exec(trimmed);
+  if (!match) {
+    return undefined;
+  }
+  const token = match[0].replace(/[.,;:]+$/g, "");
+  return token && !STOP_WORDS.has(token.toLowerCase()) ? token : undefined;
+}
+
+function trimDirectiveValue(value: string): string {
+  return value
+    .trim()
+    .replace(/^['"`]+/, "")
+    .replace(/['"`]+$/, "")
+    .trim();
+}
+
+function positiveIntegerFromText(value: string): number | undefined {
+  const match = /\d+/.exec(value);
+  if (!match) {
+    return undefined;
+  }
+  const parsed = Number.parseInt(match[0], 10);
+  return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : undefined;
+}
+
+function durationMsFromText(value: string, options: { allowBareSeconds: boolean }): number | undefined {
+  const match = /(\d+(?:\.\d+)?)\s*(milliseconds?|msecs?|ms|seconds?|secs?|s|minutes?|mins?|m|hours?|hrs?|h)?\b/i.exec(
+    value,
+  );
+  if (!match) {
+    return undefined;
+  }
+
+  const amount = Number.parseFloat(match[1] ?? "");
+  if (!Number.isFinite(amount) || amount <= 0) {
+    return undefined;
+  }
+
+  const unit = (match[2] ?? "").toLowerCase();
+  if (!unit && !options.allowBareSeconds) {
+    return undefined;
+  }
+
+  const multiplier = durationMultiplier(unit || "seconds");
+  const milliseconds = Math.round(amount * multiplier);
+  return Number.isSafeInteger(milliseconds) && milliseconds > 0 ? milliseconds : undefined;
+}
+
+function durationMultiplier(unit: string): number {
+  if (unit === "ms" || unit.startsWith("millisecond") || unit.startsWith("msec")) {
+    return 1;
+  }
+  if (unit === "h" || unit.startsWith("hour") || unit.startsWith("hr")) {
+    return 60 * 60 * 1000;
+  }
+  if (unit === "m" || unit.startsWith("minute") || unit.startsWith("min")) {
+    return 60 * 1000;
+  }
+  return 1000;
+}
+
+function normalizeWords(value: string): string {
+  return value.toLowerCase().replace(/[-_]+/g, " ").replace(/\s+/g, " ").trim();
+}

package/src/worker_session.ts

@@ -186,7 +186,6 @@ export const extractAssistantTextFromEvent = assistantTextFromEvent;
 export const extractLastAssistantTextFromEvents = lastAssistantTextFromEvents;
 
 export const DEFAULT_WORKER_TOOLS = ["read", "bash", "edit", "write", "grep", "find", "ls"] as const;
-export const DEFAULT_WORKER_MODEL = "openai-codex/gpt-5.5";
 export const DEFAULT_WORKER_THINKING_LEVEL = "high";
 export const DEFAULT_TASK_TIMEOUT_SECONDS = 60 * 60;
 export const DEFAULT_GRACEFUL_SHUTDOWN_SECONDS = 60;
@@ -309,7 +308,8 @@ export async function createIsolatedWorkerSession(
   const resourceLoader = disableExtensionsForWorker(discoveredResourceLoader, () => pi.createExtensionRuntime());
   await resourceLoader.reload();
 
-  const model = options.model ?? (await resolveWorkerModel(modelRegistry, options.modelName ?? DEFAULT_WORKER_MODEL));
+  const model =
+    options.model ?? (options.modelName ? await resolveWorkerModel(modelRegistry, options.modelName) : undefined);
   const createOptions: Record<string, unknown> = {
     cwd,
     agentDir,