pi-long-task 0.3.8 → 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.8",
+  "version": "0.3.9",
   "type": "module",
   "description": "Pi extension for breaking down and running long coding tasks safely.",
   "keywords": [

package/src/coordinator.ts

@@ -11,18 +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,
@@ -35,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",
@@ -51,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 {
@@ -85,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;
@@ -102,6 +122,8 @@ export interface RunCoordinatorOptions extends PiLongTaskInput {
   workerModelName?: string;
   maxAttemptsPerTask?: number;
   taskTimeoutMs?: number;
+  todoTimeoutMs?: number;
+  todoGracefulShutdownMs?: number;
   maxBashTimeoutMs?: number;
   taskThinking?: string;
   todoThinking?: string;
@@ -116,7 +138,10 @@ export interface TodoPlannerOptions {
   thinkingLevel: string;
   model?: unknown;
   abortSignal?: AbortSignal;
+  timeoutMs?: number;
+  gracefulShutdownMs?: number;
   sessionFactory?: WorkerSessionFactory;
+  onDiagnostic?: PlannerDiagnosticHandler;
 }
 
 export interface TaskAttemptSummary {
@@ -175,6 +200,8 @@ interface RuntimeOptions {
   workerModelName?: string;
   taskThinking: string;
   todoThinking: string;
+  todoTimeoutMs: number;
+  todoGracefulShutdownMs: number;
   workerRunner: WorkerRunner;
   todoPlanner: TodoPlanner;
   abortSignal?: AbortSignal;
@@ -183,6 +210,7 @@ interface RuntimeOptions {
   now: () => Date;
   onProgress?: CoordinatorProgressHandler;
   workerCostState: WorkerCostState;
+  plannerDiagnostics: PlannerDiagnostic[];
 }
 
 export async function runCoordinator(options: RunCoordinatorOptions): Promise<CoordinatorResult> {
@@ -193,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).`, {
@@ -379,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.
     }
@@ -407,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.", {
@@ -425,45 +464,228 @@ 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: [],
-      model: options.model,
-      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 {
@@ -473,6 +695,8 @@ 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 configuredMaxBashTimeoutMs = options.maxBashTimeoutMs ?? parsedWorkerConfig.maxBashTimeoutMs;
   const workerModelName = options.workerModelName ?? parsedWorkerConfig.modelName;
   const workerModel = workerModelName ? undefined : options.workerModel;
@@ -485,6 +709,11 @@ 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(
+      configuredTodoGracefulShutdownMs,
+      DEFAULT_COORDINATOR_OPTIONS.todoGracefulShutdownMs,
+    ),
     maxBashTimeoutSeconds:
       positiveMilliseconds(configuredMaxBashTimeoutMs, DEFAULT_COORDINATOR_OPTIONS.maxBashTimeoutMs) / 1000,
     workerModel,
@@ -499,6 +728,7 @@ function buildRuntimeOptions(options: RunCoordinatorOptions): RuntimeOptions {
     now: options.now ?? (() => new Date()),
     onProgress: options.onProgress,
     workerCostState: createWorkerCostState(),
+    plannerDiagnostics: [],
   };
 }
 
@@ -517,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,
@@ -771,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

@@ -72,6 +72,7 @@ function toolDetails(result: CoordinatorResult) {
     taskProgress: result.taskProgress,
     workerCostTotal: result.workerCostTotal,
     summary: result.summary,
+    error: result.error,
   };
 }
 

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);