pi-long-task 0.5.0 → 0.7.0

package/src/planner_progress.ts

@@ -0,0 +1,156 @@
+import type { PlannerBudget, PlannerComplexitySignal } from "./planner_config.ts";
+
+export type PlannerProgressState = "started" | "active" | "grace";
+
+/**
+ * One user-facing planner timing update. Millisecond fields remain available to
+ * integrations while `message` consistently uses friendly duration wording.
+ */
+export interface PlannerProgressEvent {
+  state: PlannerProgressState;
+  message: string;
+  budgetMs: number;
+  gracePeriodMs: number;
+  elapsedMs: number;
+  remainingMs: number;
+  graceRemainingMs?: number;
+  budget: Readonly<PlannerBudget>;
+}
+
+export type PlannerProgressHandler = (event: Readonly<PlannerProgressEvent>) => void;
+
+/** Formats a duration for people rather than exposing raw millisecond counts. */
+export function formatFriendlyDuration(durationMs: number): string {
+  const milliseconds = Math.max(0, Number.isFinite(durationMs) ? durationMs : 0);
+  if (milliseconds > 0 && milliseconds < 1_000) {
+    return "less than 1 second";
+  }
+
+  const totalSeconds = Math.round(milliseconds / 1_000);
+  if (totalSeconds < 60) {
+    return plural(totalSeconds, "second");
+  }
+
+  const totalMinutes = Math.floor(totalSeconds / 60);
+  const seconds = totalSeconds % 60;
+  if (totalMinutes < 60) {
+    return joinDurationParts(plural(totalMinutes, "minute"), seconds > 0 ? plural(seconds, "second") : undefined);
+  }
+
+  const totalHours = Math.floor(totalMinutes / 60);
+  const minutes = totalMinutes % 60;
+  if (totalHours < 24) {
+    return joinDurationParts(plural(totalHours, "hour"), minutes > 0 ? plural(minutes, "minute") : undefined);
+  }
+
+  const days = Math.floor(totalHours / 24);
+  const hours = totalHours % 24;
+  return joinDurationParts(plural(days, "day"), hours > 0 ? plural(hours, "hour") : undefined);
+}
+
+export function createPlannerStartedProgress(
+  budget: Readonly<PlannerBudget>,
+  gracePeriodMs: number,
+): PlannerProgressEvent {
+  const budgetText = formatFriendlyDuration(budget.timeoutMs);
+  const sourceText = budget.source === "explicit" ? " (explicitly configured)" : "";
+  const adaptiveText = adaptiveExtensionExplanation(budget);
+  const graceText =
+    gracePeriodMs > 0
+      ? ` A ${formatFriendlyDurationModifier(gracePeriodMs)} graceful-shutdown period is available afterward.`
+      : " No graceful-shutdown period is configured.";
+
+  return {
+    state: "started",
+    message: `Creating TODO plan. Effective planning budget: ${budgetText}${sourceText}.${adaptiveText}${graceText}`,
+    budgetMs: budget.timeoutMs,
+    gracePeriodMs,
+    elapsedMs: 0,
+    remainingMs: budget.timeoutMs,
+    budget,
+  };
+}
+
+export function createPlannerActiveProgress(
+  budget: Readonly<PlannerBudget>,
+  gracePeriodMs: number,
+  elapsedMs: number,
+): PlannerProgressEvent {
+  const elapsed = clamp(elapsedMs, 0, budget.timeoutMs);
+  const remaining = Math.max(0, budget.timeoutMs - elapsed);
+  return {
+    state: "active",
+    message: `Still planning: ${formatFriendlyDuration(elapsed)} elapsed; about ${formatFriendlyDuration(remaining)} remaining in the ${formatFriendlyDuration(budget.timeoutMs)} budget.`,
+    budgetMs: budget.timeoutMs,
+    gracePeriodMs,
+    elapsedMs: elapsed,
+    remainingMs: remaining,
+    budget,
+  };
+}
+
+export function createPlannerGraceProgress(
+  budget: Readonly<PlannerBudget>,
+  gracePeriodMs: number,
+): PlannerProgressEvent {
+  const grace = Math.max(0, gracePeriodMs);
+  return {
+    state: "grace",
+    message: `Planning budget reached after ${formatFriendlyDuration(budget.timeoutMs)}; entering a ${formatFriendlyDurationModifier(grace)} graceful-shutdown period to finish a valid plan.`,
+    budgetMs: budget.timeoutMs,
+    gracePeriodMs: grace,
+    elapsedMs: budget.timeoutMs,
+    remainingMs: 0,
+    graceRemainingMs: grace,
+    budget,
+  };
+}
+
+/** Three bounded checkpoints provide useful timing without per-second noise. */
+export function plannerProgressCheckpoints(budgetMs: number): number[] {
+  const budget = Math.max(0, Math.floor(budgetMs));
+  if (budget <= 1) {
+    return [];
+  }
+  return [...new Set([0.25, 0.5, 0.75].map((fraction) => Math.max(1, Math.floor(budget * fraction))))].filter(
+    (checkpoint) => checkpoint < budget,
+  );
+}
+
+function formatFriendlyDurationModifier(durationMs: number): string {
+  return formatFriendlyDuration(durationMs).replace(
+    /(\d[\d,]*) (seconds?|minutes?|hours?|days?)/g,
+    (_match, value: string, unit: string) => `${value}-${unit.replace(/s$/, "")}`,
+  );
+}
+
+function adaptiveExtensionExplanation(budget: Readonly<PlannerBudget>): string {
+  if (!budget.extensionApplied || budget.extensionMs <= 0 || !budget.trigger) {
+    return "";
+  }
+  return ` Adaptive extension: ${formatFriendlyDuration(budget.extensionMs)} because the request includes ${complexitySignalText(budget.trigger)}.`;
+}
+
+function complexitySignalText(signal: Readonly<PlannerComplexitySignal>): string {
+  switch (signal.kind) {
+    case "separately_planned_tasks":
+      return `${signal.itemCount} separately planned ${signal.itemCount === 1 ? "task" : "tasks"}`;
+    case "explicit_item_count":
+      return `an explicit count of ${signal.itemCount} ${signal.itemCount === 1 ? "deliverable" : "deliverables"}`;
+    case "enumerated_deliverables":
+      return `${signal.itemCount} enumerated ${signal.itemCount === 1 ? "deliverable" : "deliverables"}`;
+  }
+}
+
+function plural(value: number, unit: string): string {
+  return `${value.toLocaleString("en-US")} ${unit}${value === 1 ? "" : "s"}`;
+}
+
+function joinDurationParts(first: string, second: string | undefined): string {
+  return second ? `${first} ${second}` : first;
+}
+
+function clamp(value: number, minimum: number, maximum: number): number {
+  const finite = Number.isFinite(value) ? value : minimum;
+  return Math.min(maximum, Math.max(minimum, Math.round(finite)));
+}

package/src/render.ts

@@ -4,6 +4,7 @@ import { Text, type Component } from "@earendil-works/pi-tui";
 import type { GoalLoopState, GoalLoopStatus } from "./goal_loop.ts";
 import type { TaskProgressModel } from "./task_progress.ts";
 import type { CoordinatorCommitSummary, CoordinatorRemainingTask, CoordinatorStatus } from "./types.ts";
+import type { WorkerCapabilityWarning } from "./worker_capabilities.ts";
 
 export interface CoordinatorResultForRendering {
   status: CoordinatorStatus;
@@ -19,6 +20,7 @@ export interface CoordinatorResultForRendering {
   remainingTasks?: CoordinatorRemainingTask[];
   taskProgress?: TaskProgressModel;
   workerCostTotal?: number;
+  capabilityWarnings?: readonly WorkerCapabilityWarning[];
   goal?: string;
   error?: string;
 }
@@ -56,6 +58,10 @@ export function formatCoordinatorResultMessage(result: CoordinatorResultForRende
     lines.push(`Worker spend: ${formatCost(result.workerCostTotal)}`);
   }
 
+  if (result.capabilityWarnings?.length) {
+    lines.push("Worker capability warnings:", ...result.capabilityWarnings.map((warning) => `- ${warning.message}`));
+  }
+
   const commitLines = commits
     .filter((commit) => commit.hash || commit.error)
     .map((commit) => {
@@ -385,6 +391,9 @@ function renderLongTaskSummary(details: CoordinatorToolRenderDetails, expanded:
   }
 
   const lines = [summary.join(" — "), theme.fg("muted", details.summary)];
+  for (const warning of details.capabilityWarnings ?? []) {
+    lines.push(theme.fg("warning", `Warning: ${warning.message}`));
+  }
   lines.push(theme.fg("dim", `Result: ${details.resultPath ?? details.taskResultPath ?? "unknown"}`));
   lines.push(theme.fg("dim", `TODO: ${details.todoPath}`));
 
@@ -450,12 +459,16 @@ function progressSubtaskDetails(value: unknown): ProgressSubtaskRenderDetails[]
 
 function progressPhaseLabel(phase: string): string {
   switch (phase) {
+    case "capability_warning":
+      return "Warning";
     case "planning":
     case "planned":
       return "Thought";
     case "task_start":
     case "worker_tool":
       return "Build";
+    case "network_wait":
+      return "Network";
     case "task_done":
       return "Done";
     case "task_failed":
@@ -603,10 +616,35 @@ function longTaskDetails(details: Record<string, unknown> | undefined): Coordina
     remainingTasks: remainingTaskSummaries(details.remainingTasks),
     taskProgress: taskProgressModel(details.taskProgress),
     workerCostTotal: nonNegativeNumberValue(details.workerCostTotal),
+    capabilityWarnings: capabilityWarningDetails(details.capabilityWarnings),
     error: stringValue(details.error),
   };
 }
 
+function capabilityWarningDetails(value: unknown): WorkerCapabilityWarning[] {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+  return value.flatMap((item) => {
+    const record = recordOrUndefined(item);
+    const code = stringValue(record?.code);
+    const message = stringValue(record?.message);
+    const planningConstraint = stringValue(record?.planningConstraint);
+    if (code !== "unavailable_browser_capability" || !message || !planningConstraint) {
+      return [];
+    }
+    return [
+      {
+        code,
+        message,
+        planningConstraint,
+        requestedCapabilities: stringArray(record?.requestedCapabilities),
+        availableTools: stringArray(record?.availableTools),
+      },
+    ];
+  });
+}
+
 function commitSummaries(value: unknown): CoordinatorCommitSummary[] {
   if (!Array.isArray(value)) {
     return [];

package/src/session_guard.ts

@@ -15,14 +15,31 @@ export interface GuardedSessionPromptOptions {
   gracefulShutdownPrompt?: string;
   diagnostics?: string[];
   onEvent?: (event: unknown) => void;
+  /** Bounded elapsed-time checkpoints while the primary deadline is active. */
+  progressCheckpointsMs?: readonly number[];
+  onProgressCheckpoint?: (elapsedMs: number) => void;
+  /** Called exactly when a positive grace period begins. */
+  onGracePeriodStart?: (gracePeriodMs: number) => void;
   dispose?: boolean;
 }
 
 export interface GuardedSessionPromptResult {
   assistantText: string;
+  /** True when the primary prompt deadline elapsed, even if the prompt safely completed during grace. */
   timedOut: boolean;
+  /** True only when a timed-out prompt settled during the configured grace period. */
+  completedDuringGrace: boolean;
+  /** True when non-whitespace assistant output was observed before prompt termination. */
+  outputObserved: boolean;
+  /** True when the session had to be stopped because its grace period expired. */
+  graceExpired: boolean;
+  /** True when the session was stopped for any reason, including hard timeout. */
   aborted: boolean;
+  /** True only when the caller's AbortSignal cancelled the prompt. */
+  cancelled: boolean;
   error?: string;
+  /** Untouched prompt failure for coordinator-level provider/transport classification. */
+  failure?: unknown;
   diagnostics: string[];
   events: unknown[];
   sessionFile?: string;
@@ -37,13 +54,19 @@ export async function runGuardedSessionPrompt(
   const events: unknown[] = [];
   const timers = new Set<ReturnType<typeof setTimeout>>();
   let assistantText = "";
+  let currentAssistantText = "";
+  let outputObserved = false;
   let timedOut = false;
+  let graceExpired = false;
   let aborted = false;
+  let cancelled = false;
   let error: string | undefined;
+  let failure: unknown;
   let promptSettled = false;
   let finished = false;
   let unsubscribe: (() => void) | undefined;
   let complete: (() => void) | undefined;
+  const assistantTextAtStart = latestAssistantText(session, [], "");
 
   const completed = new Promise<void>((resolve) => {
     complete = resolve;
@@ -87,6 +110,14 @@ export async function runGuardedSessionPrompt(
     }
   };
 
+  const notifyTiming = (callback: (() => void) | undefined, label: string) => {
+    try {
+      callback?.();
+    } catch (exc) {
+      diagnostics.push(`${label} listener failed: ${errorMessage(exc)}`);
+    }
+  };
+
   const requestGracefulShutdown = () => {
     const message = options.gracefulShutdownPrompt?.trim();
     if (!message || finished || promptSettled || aborted) {
@@ -127,13 +158,18 @@ export async function runGuardedSessionPrompt(
     }
     timedOut = true;
     diagnostics.push(`session prompt timed out after ${formatMilliseconds(timeoutMs(options.timeoutMs))}`);
-    requestGracefulShutdown();
 
     const graceMs = nonNegativeMilliseconds(options.gracefulShutdownMs);
+    if (graceMs > 0) {
+      notifyTiming(() => options.onGracePeriodStart?.(graceMs), "grace-period progress");
+    }
+    requestGracefulShutdown();
+
     const hardAbort = () => {
       if (finished || promptSettled) {
         return;
       }
+      graceExpired = true;
       abortSession(`session prompt exceeded ${formatMilliseconds(timeoutMs(options.timeoutMs))} timeout`);
       resolveCompleted();
     };
@@ -149,20 +185,34 @@ export async function runGuardedSessionPrompt(
     if (finished || promptSettled) {
       return;
     }
-    abortSession(abortReason(options.abortSignal, "session prompt aborted by outer signal"));
+    cancelled = true;
+    abortSession(abortReason(options.abortSignal, "session prompt cancelled by outer signal"));
     resolveCompleted();
   };
 
   try {
     if (options.abortSignal?.aborted) {
       aborted = true;
-      error = abortReason(options.abortSignal, "session prompt aborted before start");
+      cancelled = true;
+      error = abortReason(options.abortSignal, "session prompt cancelled before start");
     } else {
       unsubscribe = session.subscribe((event: unknown) => {
         events.push(event);
-        const text = assistantTextFromEvent(event);
-        if (text) {
-          assistantText = text;
+        if (isAssistantMessageStart(event)) {
+          currentAssistantText = "";
+        }
+        const delta = assistantTextDeltaFromEvent(event);
+        if (delta !== undefined) {
+          currentAssistantText += delta;
+          assistantText = currentAssistantText || assistantText;
+          outputObserved ||= delta.trim().length > 0;
+        } else {
+          const text = assistantTextFromEvent(event);
+          if (text) {
+            currentAssistantText = text;
+            assistantText = text;
+            outputObserved ||= text.trim().length > 0;
+          }
         }
         try {
           options.onEvent?.(event);
@@ -180,6 +230,7 @@ export async function runGuardedSessionPrompt(
         },
         (exc: unknown) => {
           promptSettled = true;
+          failure ??= exc;
           error = error ?? errorMessage(exc);
           resolveCompleted();
         },
@@ -188,12 +239,20 @@ export async function runGuardedSessionPrompt(
 
       const limitMs = timeoutMs(options.timeoutMs);
       if (limitMs > 0) {
+        for (const checkpoint of normalizedProgressCheckpoints(options.progressCheckpointsMs, limitMs)) {
+          schedule(() => {
+            if (!finished && !promptSettled && !timedOut && !aborted) {
+              notifyTiming(() => options.onProgressCheckpoint?.(checkpoint), "timing progress");
+            }
+          }, checkpoint);
+        }
         schedule(triggerTimeout, limitMs);
       }
 
       await completed;
     }
   } catch (exc) {
+    failure ??= exc;
     error = error ?? errorMessage(exc);
   } finally {
     finished = true;
@@ -201,6 +260,7 @@ export async function runGuardedSessionPrompt(
     options.abortSignal?.removeEventListener("abort", abortListener);
     unsubscribe?.();
     assistantText = latestAssistantText(session, events, assistantText);
+    outputObserved ||= assistantText.trim().length > 0 && assistantText !== assistantTextAtStart;
     if (options.dispose !== false) {
       try {
         const disposeResult = (session.dispose as (() => unknown) | undefined)?.();
@@ -215,7 +275,20 @@ export async function runGuardedSessionPrompt(
     }
   }
 
-  return buildResult(session, events, assistantText, timedOut, aborted, error, diagnostics);
+  return buildResult(
+    session,
+    events,
+    assistantText,
+    timedOut,
+    timedOut && promptSettled && !graceExpired && !aborted && failure === undefined,
+    outputObserved,
+    graceExpired,
+    aborted,
+    cancelled,
+    error,
+    failure,
+    diagnostics,
+  );
 }
 
 function buildResult(
@@ -223,15 +296,25 @@ function buildResult(
   events: unknown[],
   assistantText: string,
   timedOut: boolean,
+  completedDuringGrace: boolean,
+  outputObserved: boolean,
+  graceExpired: boolean,
   aborted: boolean,
+  cancelled: boolean,
   error: string | undefined,
+  failure: unknown,
   diagnostics: string[],
 ): GuardedSessionPromptResult {
   return {
     assistantText: latestAssistantText(session, events, assistantText),
     timedOut,
+    completedDuringGrace,
+    outputObserved,
+    graceExpired,
     aborted,
+    cancelled,
     error,
+    ...(failure === undefined ? {} : { failure }),
     diagnostics: [...diagnostics],
     events: [...events],
     sessionFile: session.sessionFile,
@@ -259,6 +342,16 @@ function timeoutMs(value: number | undefined): number {
   return Math.max(0, value);
 }
 
+function normalizedProgressCheckpoints(values: readonly number[] | undefined, limitMs: number): number[] {
+  if (!values) {
+    return [];
+  }
+  return [...new Set(values)]
+    .filter((value) => Number.isFinite(value) && value > 0 && value < limitMs)
+    .map((value) => Math.floor(value))
+    .sort((left, right) => left - right);
+}
+
 function nonNegativeMilliseconds(value: number | undefined): number {
   if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) {
     return 0;
@@ -270,6 +363,26 @@ function formatMilliseconds(ms: number): string {
   return `${(ms / 1000).toFixed(3)}s`;
 }
 
+function isAssistantMessageStart(event: unknown): boolean {
+  return (
+    isRecord(event) && event.type === "message_start" && isRecord(event.message) && event.message.role === "assistant"
+  );
+}
+
+function assistantTextDeltaFromEvent(event: unknown): string | undefined {
+  if (!isRecord(event) || event.type !== "message_update" || !isRecord(event.assistantMessageEvent)) {
+    return undefined;
+  }
+  const assistantEvent = event.assistantMessageEvent;
+  return assistantEvent.type === "text_delta" && typeof assistantEvent.delta === "string"
+    ? assistantEvent.delta
+    : undefined;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
 function abortReason(signal: AbortSignal | undefined, fallback: string): string {
   const reason = signal?.reason;
   if (reason === undefined) {

package/src/todo_generator.ts

@@ -14,8 +14,8 @@ const NUMBERED_ITEM_RE = /^\s*\d+[.)]\s+(.+?)\s*$/;
 const FENCE_RE = /```(?:markdown|md)?\s*\n([\s\S]*?)\n```/gi;
 
 export class TodoGenerationError extends Error {
-  constructor(message: string) {
-    super(message);
+  constructor(message: string, options?: ErrorOptions) {
+    super(message, options);
     this.name = "TodoGenerationError";
   }
 }
@@ -133,7 +133,7 @@ export function applyGoalInstructionsToTodoMarkdown(markdown: string, goal?: str
     return markdown;
   }
 
-  let next = insertGlobalGoalInstructions(markdown, trimmedGoal);
+  let next = insertGlobalInstructions(markdown, goalInstructionLines(trimmedGoal));
   const coverageGoal = parseCoverageGoal(trimmedGoal);
   if (coverageGoal) {
     next = appendCoverageVerificationToTasks(next, coverageGoalVerifyBullet(coverageGoal));
@@ -142,14 +142,33 @@ export function applyGoalInstructionsToTodoMarkdown(markdown: string, goal?: str
   return next;
 }
 
-function insertGlobalGoalInstructions(markdown: string, goal: string): string {
+export function applyWorkerCapabilityConstraintsToTodoMarkdown(
+  markdown: string,
+  constraints: readonly string[],
+): string {
+  const additions = constraints
+    .map(oneLine)
+    .filter(Boolean)
+    .map((item) => `- ${item}`);
+  if (additions.length === 0) {
+    return markdown;
+  }
+  const next = insertGlobalInstructions(markdown, additions);
+  validateTodoMarkdown(next);
+  return next;
+}
+
+function goalInstructionLines(goal: string): string[] {
   const coverageGoal = parseCoverageGoal(goal);
   const additions = [`- Long task goal: ${goal}`];
   if (coverageGoal) {
     additions.push(`- Coverage goal: ${coverageGoalAction(coverageGoal)}`);
     additions.push(`- Coverage verification: ${coverageGoalVerification(coverageGoal)}`);
   }
+  return additions;
+}
 
+function insertGlobalInstructions(markdown: string, additions: readonly string[]): string {
   const lines = markdown.replace(/\r\n?/g, "\n").split("\n");
   const progressIndex = lines.findIndex((line) => /^##\s+Progress\s*$/i.test(line.trim()));
   if (progressIndex < 0) {
@@ -229,9 +248,43 @@ function oneLine(value: string): string {
   return value.replace(/\s+/g, " ").trim();
 }
 
-export function buildTodoCreationPrompt(rawInput: string, goal?: string): string {
+export function todoPlanningOnlyPromptBlock(capabilityConstraints: readonly string[] = []): string {
+  const capabilityBlock = capabilityConstraints.length
+    ? `\n\nWorker capability constraints (preserve these above ## Progress and in affected tasks):\n${capabilityConstraints
+        .map((constraint) => `- ${oneLine(constraint)}`)
+        .join("\n")}`
+    : "";
+  return `Planning-only boundary:
+- Produce only a concise executable plan for future workers.
+- Do not perform requested end work: do not implement or write code, execute research or report findings, create requested creative output (prose, stories, copy, designs, or assets), or produce any other final deliverable.
+- Use future-worker action language; do not claim work is complete or invent results.
+- Keep repeated task sections compact: use a one-sentence Goal and Done when, plus only the necessary Status and Verify bullets. Omit rationale, lengthy analysis, summaries, duplicated context, unrequested examples, and boilerplate.
+- Preserve every instruction, constraint, required deliverable, and acceptance condition from the source request and supplied planning context. Put shared constraints above ## Progress and task-specific requirements in the relevant task.${capabilityBlock}`;
+}
+
+export function buildTodoCreationPrompt(
+  rawInput: string,
+  goal?: string,
+  capabilityConstraints: readonly string[] = [],
+): string {
   const goalBlock = todoGoalPromptBlock(goal);
-  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${goalBlock}\nRaw input:\n\n${rawInput.trim()}\n`;
+  return `Convert the following raw project request into Pi Long Task-compatible TODO markdown.
+
+${todoPlanningOnlyPromptBlock(capabilityConstraints)}
+
+Required format:
+- Output only markdown, with no commentary and no code fence.
+- Start with exactly: # Pi Long Task TODO
+- Include a ## Progress section with one unchecked line per task: - [ ] TODO N — Title
+- Include a --- separator before task sections.
+- Create sequential sections named ## TODO N — Title.
+- Each task section must include **Goal:**, **Status:** with unchecked checkbox items, **Verify:** with concrete verification guidance, and **Done when:**.
+- Keep tasks focused and independently assignable to worker sessions.
+${goalBlock}
+Raw input:
+
+${rawInput.trim()}
+`;
 }
 
 export function buildTodoRepairPrompt(
@@ -239,9 +292,33 @@ export function buildTodoRepairPrompt(
   invalidOutput: string,
   validationError: string,
   goal?: string,
+  capabilityConstraints: readonly string[] = [],
 ): string {
   const goalBlock = todoGoalPromptBlock(goal);
-  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${goalBlock}\nOriginal raw input:\n\n${rawInput.trim()}\n\nPrevious invalid output:\n\n${invalidOutput.trim()}\n`;
+  return `Repair the previous response into valid Pi Long Task TODO markdown. Correct its plan and format only; do not continue or perform any attempted end work.
+
+${todoPlanningOnlyPromptBlock(capabilityConstraints)}
+
+Validation/extraction error:
+${validationError.trim() || "Unknown validation error."}
+
+Required format:
+- Output only corrected markdown, with no commentary and no code fence.
+- Start with exactly: # Pi Long Task TODO
+- Include a ## Progress section with one unchecked line per task: - [ ] TODO N — Title
+- Include a --- separator before task sections.
+- Create sequential sections named ## TODO N — Title.
+- Each task section must include **Goal:**, **Status:** with unchecked checkbox items, **Verify:** with concrete verification guidance, and **Done when:**.
+- Keep tasks focused and independently assignable to worker sessions.
+${goalBlock}
+Original raw input:
+
+${rawInput.trim()}
+
+Previous invalid output (repair its planning content; do not extend its end work):
+
+${invalidOutput.trim()}
+`;
 }
 
 function todoGoalPromptBlock(goal: string | undefined): string {