pi-long-task 0.6.0 → 0.7.0

package/src/goal_orchestrator.ts

@@ -30,6 +30,7 @@ import {
   type NetworkRecoveryConfig,
   type NetworkRecoveryConfigInput,
 } from "./network_recovery_config.ts";
+import { validatePlannerGracefulShutdownMs, validatePlannerTimeoutMs } from "./planner_config.ts";
 import { runGoalReviewSession, type GoalReviewResult, type GoalReviewerRunner } from "./goal_review.ts";
 import {
   runGoalTodoExecutionLongTask,
@@ -109,6 +110,8 @@ export interface RunGoalLoopOptions extends GoalLoopLimitInput {
   thinkingLevel?: string;
   maxBashTimeoutMs?: number;
   maxAttemptsPerTask?: number;
+  todoTimeoutMs?: number;
+  todoGracefulShutdownMs?: number;
   networkRecovery?: NetworkRecoveryConfigInput;
   commit?: boolean;
   now?: () => Date;
@@ -140,6 +143,8 @@ export class GoalLoopOrchestratorError extends Error {
 export async function runGoalLoop(options: RunGoalLoopOptions): Promise<GoalLoopRunResult> {
   const now = options.now ?? (() => new Date());
   const networkRecovery = resolveNetworkRecoveryConfig(options.networkRecovery);
+  const todoTimeoutMs = validatePlannerTimeoutMs(options.todoTimeoutMs);
+  const todoGracefulShutdownMs = validatePlannerGracefulShutdownMs(options.todoGracefulShutdownMs);
   let state =
     options.initialState ??
     createGoalLoopState({
@@ -282,6 +287,8 @@ export async function runGoalLoop(options: RunGoalLoopOptions): Promise<GoalLoop
           modelName: options.modelName,
           thinkingLevel: options.thinkingLevel,
           maxBashTimeoutMs: options.maxBashTimeoutMs,
+          todoTimeoutMs,
+          todoGracefulShutdownMs,
           networkRecovery,
           now,
           goalSpecification,
@@ -313,6 +320,8 @@ export async function runGoalLoop(options: RunGoalLoopOptions): Promise<GoalLoop
           modelName: options.modelName,
           thinkingLevel: options.thinkingLevel,
           maxBashTimeoutMs: options.maxBashTimeoutMs,
+          todoTimeoutMs,
+          todoGracefulShutdownMs,
           networkRecovery,
           now,
           goalSpecification,
@@ -346,6 +355,8 @@ export async function runGoalLoop(options: RunGoalLoopOptions): Promise<GoalLoop
             thinkingLevel: options.thinkingLevel,
             maxBashTimeoutMs: options.maxBashTimeoutMs,
             maxAttemptsPerTask: options.maxAttemptsPerTask,
+            todoTimeoutMs,
+            todoGracefulShutdownMs,
             networkRecovery,
             commit: options.commit,
             now,

package/src/goal_todo_execution.ts

@@ -33,6 +33,8 @@ export interface GoalTodoExecutionOptions {
   thinkingLevel?: string;
   maxBashTimeoutMs?: number;
   maxAttemptsPerTask?: number;
+  todoTimeoutMs?: number;
+  todoGracefulShutdownMs?: number;
   networkRecovery?: Readonly<NetworkRecoveryConfig>;
   commit?: boolean;
   now?: () => Date;
@@ -154,6 +156,8 @@ export async function runGoalTodoExecutionLongTask(
       taskTimeoutMs: childTimeoutMs,
       maxBashTimeoutMs: options.maxBashTimeoutMs,
       maxAttemptsPerTask: options.maxAttemptsPerTask,
+      todoTimeoutMs: options.todoTimeoutMs,
+      todoGracefulShutdownMs: options.todoGracefulShutdownMs,
       networkRecovery: options.networkRecovery,
       onProgress: (update) => {
         progressEvents.push(update);

package/src/goal_todo_generation.ts

@@ -19,6 +19,7 @@ import { parseTasks } from "./todo_parser.ts";
 import {
   applyGoalInstructionsToTodoMarkdown,
   extractAndValidateTodoMarkdown,
+  todoPlanningOnlyPromptBlock,
   validateTodoMarkdown,
 } from "./todo_generator.ts";
 
@@ -38,6 +39,8 @@ export interface GoalTodoGenerationOptions {
   modelName?: string;
   thinkingLevel?: string;
   maxBashTimeoutMs?: number;
+  todoTimeoutMs?: number;
+  todoGracefulShutdownMs?: number;
   networkRecovery?: Readonly<NetworkRecoveryConfig>;
   now?: () => Date;
   additionalContext?: string;
@@ -122,6 +125,8 @@ export async function runGoalTodoGenerationLongTask(
     taskThinking: options.thinkingLevel,
     taskTimeoutMs: childTimeoutMs,
     maxBashTimeoutMs: options.maxBashTimeoutMs,
+    todoTimeoutMs: options.todoTimeoutMs,
+    todoGracefulShutdownMs: options.todoGracefulShutdownMs,
     networkRecovery: options.networkRecovery,
     onNetworkRecovery: captureOutage,
   };
@@ -225,16 +230,17 @@ export function buildGoalTodoGenerationTaskPayload(options: {
 
 - Long task goal: ${oneLine(options.state.goal)}
 - This is goal-loop TODO generation iteration ${options.iteration} for goal run ${options.state.goalRunId}.
-- Only generate TODO markdown for future workers; do not implement, edit, test, refactor, or otherwise perform the goal work in this generation run.
 - Write the generated Pi Long Task-compatible TODO markdown to \`${options.outputPath}\`.
 - Do not wrap the generated file in a code fence and do not include commentary outside the TODO markdown in that file.
 - Keep generated tasks focused, independently assignable, and safe for separate worker sessions.
 ${iterationPolicy}
 ${
   options.goalSpecification
-    ? "- A persisted goal specification is available; derive implementation TODOs from that specification rather than only the original vague goal.\n- Ensure generated tasks explicitly cover relevant requirement IDs, milestones, acceptance criteria, verification gates, constraints, and definition-of-done items from the specification.\n- Include spec IDs (for example REQ-*, MS-*, AC-*, VG-*) in generated task goals/status/verification/done-when guidance wherever applicable.\n"
+    ? "- A persisted goal specification is available; derive implementation TODOs from it rather than only the original vague goal.\n- Preserve its requirement IDs, milestones, acceptance criteria, verification gates, constraints, and definition of done in the relevant tasks. Reference each applicable spec ID (for example REQ-*, MS-*, AC-*, VG-*) where it is most useful instead of duplicating it in every task field.\n"
     : ""
 }
+${todoPlanningOnlyPromptBlock()}
+
 ## Progress
 
 - [ ] TODO 1 — Generate Pi Long Task TODO markdown
@@ -246,16 +252,12 @@ ${
 **Goal:** Convert the high-level goal into a valid Pi Long Task TODO plan for the next implementation long task.
 
 **Status:**
-- [ ] Analyze the high-level goal and any iteration context.
-- [ ] Create TODO markdown that starts with \`# Pi Long Task TODO\`.
-- [ ] Include a \`## Progress\` section with one unchecked \`- [ ] TODO N — Title\` line per generated task.
-- [ ] Include a \`---\` separator before generated task sections.
-- [ ] Include sequential \`## TODO N — Title\` sections with \`**Goal:**\`, \`**Status:**\`, \`**Verify:**\`, and \`**Done when:**\` guidance.
-- [ ] Write only the generated TODO markdown to \`${options.outputPath}\`.
+- [ ] Derive focused future-worker tasks from the goal, constraints, and iteration context without performing that work.
+- [ ] Render the required Progress list and sequential task sections with Goal, Status, Verify, and Done when fields.
+- [ ] Write only the concise generated TODO markdown to \`${options.outputPath}\`.
 
 **Verify:**
-- Confirm the file at \`${options.outputPath}\` exists.
-- Confirm it starts with \`# Pi Long Task TODO\`, has a \`## Progress\` section, a \`---\` separator, sequential TODO sections, unchecked status checkboxes, and concrete verification instructions.
+- Confirm \`${options.outputPath}\` contains valid TODO markdown with preserved constraints, compact task sections, unchecked statuses, and concrete checks.
 
 **Done when:**
 - \`${options.outputPath}\` contains valid Pi Long Task-compatible TODO markdown for achieving the high-level goal.

package/src/index.ts

@@ -80,6 +80,8 @@ function toolDetails(result: CoordinatorResult) {
     remainingTasks: result.remainingTasks,
     taskProgress: result.taskProgress,
     workerCostTotal: result.workerCostTotal,
+    plannerBudget: result.plannerBudget,
+    capabilityWarnings: result.capabilityWarnings,
     summary: result.summary,
     goal: result.goal,
     error: result.error,
@@ -349,7 +351,15 @@ function renderSidebarRows(update: CoordinatorProgressUpdate | undefined, theme:
   rows.push(renderSidebarStateLine(update, theme));
 
   if (!progress || progress.tasks.length === 0) {
-    rows.push("", sidebarHeading("Context", theme), theme.fg("muted", "Waiting for TODO plan"));
+    const planningStatus =
+      update.phase === "planning" ? normalizeActiveStatus(update.activeStatus ?? update.message) : undefined;
+    rows.push(
+      "",
+      sidebarHeading(planningStatus ? "Planning timing" : "Context", theme),
+      ...(planningStatus
+        ? wrapPlainText(planningStatus, width, 8).map((line) => theme.fg("accent", line))
+        : [theme.fg("muted", "Waiting for TODO plan")]),
+    );
     if (update.workerCostTotal > 0) {
       rows.push(theme.fg("muted", `${formatCost(update.workerCostTotal)} spent`));
     }
@@ -566,6 +576,8 @@ function sidebarUpdateStateDetails(update: CoordinatorProgressUpdate): {
   }
 
   switch (update.phase) {
+    case "capability_warning":
+      return { icon: "!", label: "Capability warning", color: "warning" };
     case "planning":
       return { icon: "+", label: "Planning", color: "warning" };
     case "planned":

package/src/network_recovery.ts

@@ -91,9 +91,9 @@ export function formatNetworkRecoveryStatus(event: NetworkRecoveryEvent): string
 
 function formatRecoveryDuration(milliseconds: number): string {
   const safeMs = Math.max(0, Math.round(milliseconds));
-  if (safeMs < 1_000) return `${safeMs}ms`;
+  if (safeMs > 0 && safeMs < 1_000) return "less than 1 second";
   const seconds = safeMs / 1_000;
-  return `${Number.isInteger(seconds) ? seconds : seconds.toFixed(1)}s`;
+  return `${Number.isInteger(seconds) ? seconds : seconds.toFixed(1)} seconds`;
 }
 
 export class NetworkOutageExpiredError extends Error {

package/src/planner_config.ts

@@ -0,0 +1,214 @@
+export const MAX_PLANNER_DURATION_MS = 2_147_483_647;
+
+/** Thinking levels accepted by the supported Pi SDK, in increasing reasoning-budget order. */
+export const SUPPORTED_PLANNER_THINKING_LEVELS = ["minimal", "low", "medium", "high", "xhigh", "max"] as const;
+export type PlannerThinkingLevel = (typeof SUPPORTED_PLANNER_THINKING_LEVELS)[number];
+/**
+ * Planner-only quality/latency balance. `high` retains enough reasoning budget
+ * for dependency-aware complex plans without imposing `xhigh` latency on every
+ * ordinary request. Explicit caller values remain authoritative.
+ */
+export const DEFAULT_PLANNER_THINKING_LEVEL: PlannerThinkingLevel = "high";
+
+/** Normal planning budget used for requests that do not contain a scale signal. */
+export const DEFAULT_PLANNER_TIMEOUT_MS = 300_000;
+/** Adaptive planning never reduces the normal five-minute budget. */
+export const MIN_ADAPTIVE_PLANNER_TIMEOUT_MS = DEFAULT_PLANNER_TIMEOUT_MS;
+/** Adaptive planning is capped at fifteen minutes, even for very large requests. */
+export const MAX_ADAPTIVE_PLANNER_TIMEOUT_MS = 900_000;
+/** The normal budget includes up to four requested deliverables. */
+export const PLANNER_ITEMS_INCLUDED_IN_BASE_BUDGET = 4;
+/** Every additional detected deliverable adds thirty seconds until the cap. */
+export const PLANNER_TIMEOUT_PER_ADDITIONAL_ITEM_MS = 30_000;
+
+export type PlannerComplexitySignalKind =
+  | "explicit_item_count"
+  | "enumerated_deliverables"
+  | "separately_planned_tasks";
+
+export interface PlannerComplexitySignal {
+  kind: PlannerComplexitySignalKind;
+  itemCount: number;
+}
+
+export type PlannerBudgetSource = "explicit" | "default" | "adaptive";
+
+/**
+ * Complete, machine-readable record of how a planner deadline was selected.
+ * `trigger` is present only when a deterministic complexity signal actually
+ * extended the normal budget.
+ */
+export interface PlannerBudget {
+  timeoutMs: number;
+  baseTimeoutMs: number;
+  minimumTimeoutMs: number;
+  maximumTimeoutMs: number;
+  extensionApplied: boolean;
+  extensionMs: number;
+  source: PlannerBudgetSource;
+  signals: readonly PlannerComplexitySignal[];
+  trigger?: PlannerComplexitySignal;
+}
+
+export interface ResolvePlannerBudgetOptions {
+  inputText: string;
+  /** Structured or natural-language timeout configuration. It always wins exactly. */
+  explicitTimeoutMs?: number;
+  defaultTimeoutMs?: number;
+}
+
+const EXPLICIT_ITEM_COUNT_RE =
+  /\b(\d{1,6})\s+(?:(?:separate(?:ly)?|individual(?:ly)?|distinct|independent(?:ly)?)\s+(?:planned\s+)?)?(?:(?:user|job|work)\s+)?(?:stories|tasks|todos?|deliverables?|items?|work\s+items?|features?|components?|pages?|endpoints?|tests?|scenarios?|requirements?)\b/gi;
+const ENUMERATED_DELIVERABLE_RE = /^\s*(?:[-*+]\s+(?:\[[ xX]\]\s+)?|\d{1,6}[.)]\s+)\S.*$/gm;
+const SEPARATE_PLANNING_RE =
+  /\b(?:separately|individually|independently)\s+(?:plan(?:ned)?|scope(?:d)?|specif(?:y|ied)|assign(?:ed)?)\b|\b(?:plan|scope|specify)\s+(?:each|every)\b|\b(?:separate|individual|independent)\s+(?:plans?|tasks?|todos?|work\s+items?)\b/i;
+
+/**
+ * Detects only reproducible textual scale signals:
+ *
+ * 1. an integer directly attached to a deliverable noun (for example,
+ *    "24 stories"),
+ * 2. line-start bullet or numbered deliverables, and
+ * 3. explicit language requiring those items to be planned separately.
+ *
+ * The detector intentionally does not estimate semantic difficulty or ask the
+ * model to grade complexity. Signals are returned in stable priority order.
+ */
+export function detectPlannerComplexitySignals(inputText: string): PlannerComplexitySignal[] {
+  const normalized = inputText.replace(/\r\n?/g, "\n");
+  const explicitItemCount = maximumMatchedInteger(normalized, EXPLICIT_ITEM_COUNT_RE);
+  const enumeratedItemCount = [...normalized.matchAll(ENUMERATED_DELIVERABLE_RE)].length;
+  const signals: PlannerComplexitySignal[] = [];
+
+  if (SEPARATE_PLANNING_RE.test(normalized)) {
+    const separatelyPlannedCount = Math.max(explicitItemCount ?? 0, enumeratedItemCount);
+    if (separatelyPlannedCount > 0) {
+      signals.push({ kind: "separately_planned_tasks", itemCount: separatelyPlannedCount });
+    }
+  }
+  if (explicitItemCount !== undefined) {
+    signals.push({ kind: "explicit_item_count", itemCount: explicitItemCount });
+  }
+  if (enumeratedItemCount > 0) {
+    signals.push({ kind: "enumerated_deliverables", itemCount: enumeratedItemCount });
+  }
+
+  return signals;
+}
+
+/**
+ * Selects a deterministic planner deadline. The normal five-minute budget
+ * covers four items; each additional item adds thirty seconds, capped at
+ * fifteen minutes. Explicit timeout configuration bypasses both detection and
+ * adaptive bounds and is returned unchanged after public duration validation.
+ */
+export function resolvePlannerBudget(options: ResolvePlannerBudgetOptions): PlannerBudget {
+  const baseTimeoutMs = resolvePlannerTimeoutMs(options.defaultTimeoutMs, DEFAULT_PLANNER_TIMEOUT_MS);
+
+  if (options.explicitTimeoutMs !== undefined) {
+    const timeoutMs = resolvePlannerTimeoutMs(options.explicitTimeoutMs, baseTimeoutMs);
+    return {
+      timeoutMs,
+      baseTimeoutMs,
+      minimumTimeoutMs: MIN_ADAPTIVE_PLANNER_TIMEOUT_MS,
+      maximumTimeoutMs: MAX_ADAPTIVE_PLANNER_TIMEOUT_MS,
+      extensionApplied: false,
+      extensionMs: 0,
+      source: "explicit",
+      signals: [],
+    };
+  }
+
+  const signals = detectPlannerComplexitySignals(options.inputText);
+  const trigger = strongestComplexitySignal(signals);
+  const additionalItems = Math.max(0, (trigger?.itemCount ?? 0) - PLANNER_ITEMS_INCLUDED_IN_BASE_BUDGET);
+  const requestedTimeoutMs = baseTimeoutMs + additionalItems * PLANNER_TIMEOUT_PER_ADDITIONAL_ITEM_MS;
+  const timeoutMs = Math.min(
+    MAX_ADAPTIVE_PLANNER_TIMEOUT_MS,
+    Math.max(MIN_ADAPTIVE_PLANNER_TIMEOUT_MS, requestedTimeoutMs),
+  );
+  const extensionMs = Math.max(0, timeoutMs - baseTimeoutMs);
+  const extensionApplied = extensionMs > 0;
+
+  return {
+    timeoutMs,
+    baseTimeoutMs,
+    minimumTimeoutMs: MIN_ADAPTIVE_PLANNER_TIMEOUT_MS,
+    maximumTimeoutMs: MAX_ADAPTIVE_PLANNER_TIMEOUT_MS,
+    extensionApplied,
+    extensionMs,
+    source: extensionApplied ? "adaptive" : "default",
+    signals,
+    ...(extensionApplied && trigger ? { trigger } : {}),
+  };
+}
+
+export class PlannerDurationConfigError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "PlannerDurationConfigError";
+  }
+}
+
+export function resolvePlannerTimeoutMs(value: number | undefined, fallback: number): number {
+  return resolvePlannerDurationMs(value, fallback, "TODO planner timeout", false);
+}
+
+export function resolvePlannerGracefulShutdownMs(value: number | undefined, fallback: number): number {
+  return resolvePlannerDurationMs(value, fallback, "TODO planner graceful-shutdown duration", true);
+}
+
+export function validatePlannerTimeoutMs(value: number | undefined): number | undefined {
+  return value === undefined ? undefined : resolvePlannerTimeoutMs(value, value);
+}
+
+export function validatePlannerGracefulShutdownMs(value: number | undefined): number | undefined {
+  return value === undefined ? undefined : resolvePlannerGracefulShutdownMs(value, value);
+}
+
+function maximumMatchedInteger(value: string, expression: RegExp): number | undefined {
+  expression.lastIndex = 0;
+  let maximum: number | undefined;
+  for (const match of value.matchAll(expression)) {
+    const count = Number.parseInt(match[1], 10);
+    if (Number.isSafeInteger(count) && count > 0) {
+      maximum = Math.max(maximum ?? 0, count);
+    }
+  }
+  return maximum;
+}
+
+function strongestComplexitySignal(signals: readonly PlannerComplexitySignal[]): PlannerComplexitySignal | undefined {
+  // Stable input order is also the tie-break priority: separate planning,
+  // explicit counts, then plain enumeration.
+  return signals.reduce<PlannerComplexitySignal | undefined>(
+    (strongest, signal) => (!strongest || signal.itemCount > strongest.itemCount ? signal : strongest),
+    undefined,
+  );
+}
+
+function resolvePlannerDurationMs(
+  value: number | undefined,
+  fallback: number,
+  label: string,
+  allowZero: boolean,
+): number {
+  if (value === undefined) {
+    return fallback;
+  }
+
+  const minimumDescription = allowZero ? "a non-negative" : "a positive";
+  if (
+    typeof value !== "number" ||
+    !Number.isSafeInteger(value) ||
+    (!allowZero && value <= 0) ||
+    (allowZero && value < 0) ||
+    value > MAX_PLANNER_DURATION_MS
+  ) {
+    throw new PlannerDurationConfigError(
+      `${label} must be ${minimumDescription} whole-millisecond duration no greater than about 24.9 days (${MAX_PLANNER_DURATION_MS} milliseconds); received ${String(value)}.`,
+    );
+  }
+
+  return value;
+}

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,6 +459,8 @@ function progressSubtaskDetails(value: unknown): ProgressSubtaskRenderDetails[]
 
 function progressPhaseLabel(phase: string): string {
   switch (phase) {
+    case "capability_warning":
+      return "Warning";
     case "planning":
     case "planned":
       return "Thought";
@@ -605,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 [];