@gavin-hu/my-pi-agent 0.14.0 → 0.15.0

package/extensions/subagent/index.ts

@@ -25,6 +25,9 @@ import {
 	formatAgentList,
 	formatAgentNames,
 } from "./agents.ts";
+import { createBackgroundRuntime } from "./background.ts";
+import { registerAgentsCommand } from "./commands.ts";
+import { createSubagentUi } from "./ui.ts";
 import { loadSubagentConfig, type SubagentConfig } from "./config.ts";
 import { runChainMode, runParallelMode, runSingleMode, type ModeContext } from "./orchestrate.ts";
 import { renderSubagentCall, renderSubagentResult } from "./render.ts";
@@ -48,6 +51,7 @@ const DESCRIPTION = [
 	"Delegate tasks to specialized subagents with isolated context windows.",
 	"Modes: single (`agent` + `task`), parallel (`tasks`), chain (sequential, `{previous}` placeholder).",
 	"Each runs in its own process, inheriting the current model and thinking level.",
+	"A single run can start in the background (`background: true`) and is managed with `/agents`.",
 	`Built-in agents: ${AGENT_NAMES}.`,
 ].join(" ");
 
@@ -55,6 +59,7 @@ const GUIDELINES = [
 	"Use `subagent` for broad codebase exploration, parallel research, or isolated implementation work that would bloat the main context.",
 	"Prefer `explorer` first when another agent would otherwise re-read many files, then pass its output to `planner` or `worker`.",
 	"Run independent tasks with `tasks` (max 8, up to 4 at once); use `chain` only when each step needs the previous step's output.",
+	"Use `background: true` only for one long task you will collect from `/agents`.",
 	"Project-local agents are repository-controlled and load only when `agentScope` includes them; an untrusted project requires confirmation.",
 ];
 
@@ -73,6 +78,7 @@ export default function subagent(pi: ExtensionAPI, deps: SubagentDeps = {}): voi
 	// Read once per session; a call that arrives before `session_start` reads the
 	// same files lazily, so the two paths cannot disagree.
 	let settings: SubagentConfig | undefined;
+	let activeCtx: ExtensionContext | undefined;
 
 	const startSession = async (ctx: ExtensionContext): Promise<void> => {
 		settings = loadSubagentConfig(ctx.cwd);
@@ -84,8 +90,6 @@ export default function subagent(pi: ExtensionAPI, deps: SubagentDeps = {}): voi
 		}
 	};
 
-	pi.on("session_start", (_event, ctx) => startSession(ctx));
-
 	/**
 	 * Account for each finished child, then hand the result on unchanged.
 	 *
@@ -106,6 +110,29 @@ export default function subagent(pi: ExtensionAPI, deps: SubagentDeps = {}): voi
 		return result;
 	};
 
+	const background = createBackgroundRuntime({
+		appendEntry: (customType, data) => pi.appendEntry(customType, data),
+		onFinish: (run) => ui.notifyFinished(run),
+	});
+	const ui = createSubagentUi({
+		runs: () => background.list(activeCtx?.sessionManager.getBranch() ?? []),
+	});
+
+	pi.on("session_start", async (_event, ctx) => {
+		background.reset();
+		activeCtx = ctx;
+		ui.attach(ctx);
+		background.subscribe(() => ui.paint());
+		ui.paint();
+		await startSession(ctx);
+	});
+	pi.on("session_shutdown", () => {
+		background.shutdown();
+		ui.detach();
+		activeCtx = undefined;
+	});
+	registerAgentsCommand(pi, background);
+
 	pi.registerTool({
 		name: TOOL_NAME,
 		label: "Subagent",
@@ -195,6 +222,68 @@ export default function subagent(pi: ExtensionAPI, deps: SubagentDeps = {}): voi
 				}
 			}
 
+			if (args.background) {
+				if (mode !== "single") {
+					return {
+						content: [{ type: "text" as const, text: "`background` supports single mode only." }],
+						details: makeDetails([]),
+					};
+				}
+				if (!agents.some((candidate) => candidate.name === args.agent)) {
+					return {
+						content: [
+							{
+								type: "text" as const,
+								text: `Unknown agent: "${args.agent ?? ""}". Available agents: ${formatAgentList(agents)}`,
+							},
+						],
+						details: makeDetails([]),
+					};
+				}
+				const started = background.start(
+					{
+						agent: args.agent ?? "",
+						task: args.task ?? "",
+						cwd: args.cwd,
+						readOnly: args.readOnly,
+					},
+					ctx.sessionManager.getBranch(),
+					{
+						run,
+						agents,
+						defaults,
+						defaultCwd: root,
+						timeoutMs: config.timeoutMs,
+						transcripts,
+						backgroundMax: config.backgroundMax,
+					},
+				);
+				if (!started.ok) {
+					return {
+						content: [{ type: "text" as const, text: started.error }],
+						details: makeDetails([]),
+					};
+				}
+				return {
+					content: [
+						{
+							type: "text" as const,
+							text: `Started ${started.run.agent} as ${started.run.id} in the background. Use /agents to inspect, collect, or cancel it.`,
+						},
+					],
+					details: {
+						...makeDetails([]),
+						background: {
+							runId: started.run.id,
+							agent: started.run.agent,
+							task: started.run.task,
+							cwd: started.run.cwd,
+							startedAt: started.run.startedAt,
+						},
+					} satisfies SubagentDetails,
+				};
+			}
+
 			const context: ModeContext = {
 				run,
 				args,

package/extensions/subagent/render.ts

@@ -488,6 +488,19 @@ export function renderSubagentResult(
 ): Component {
 	const now = options.now ?? Date.now();
 	const details = toolDetails<SubagentDetails>(result.details);
+	if (details?.background) {
+		syncElapsedTimer(false, context);
+		const text = reuseText(context?.lastComponent);
+		const background = details.background;
+		text.setText(
+			paint(
+				theme,
+				"meta",
+				`Started ${sanitizeLine(background.agent)} as ${sanitizeLine(background.runId)} in the background. Use /agents to collect or cancel it.`,
+			),
+		);
+		return text;
+	}
 	if (!details || details.results.length === 0) {
 		syncElapsedTimer(false, context);
 		const text = reuseText(context?.lastComponent);

package/extensions/subagent/run.ts

@@ -13,6 +13,7 @@ import * as os from "node:os";
 import * as path from "node:path";
 import { withFileMutationQueue } from "@earendil-works/pi-coding-agent";
 import { formatDuration } from "../../lib/format.ts";
+import { LineSplitter } from "../../lib/lines.ts";
 import { BUILTIN_AGENTS, formatAgentList, type AgentConfig } from "./agents.ts";
 import type { TranscriptMode } from "./config.ts";
 import { buildAgentArgs, getPiInvocation, READ_ONLY_NOTE } from "./invocation.ts";
@@ -44,6 +45,8 @@ export interface RunOptions {
 	spawn?: SpawnFn;
 	/** Per-run wall-clock limit in ms; `0` or absent disables it. */
 	timeoutMs?: number;
+	/** Return an aborted result instead of throwing (used by background runs). */
+	abortAsResult?: boolean;
 	/** Where and when a finished run writes a transcript. */
 	transcripts?: { dir: string; mode: Exclude<TranscriptMode, "off"> };
 }
@@ -88,7 +91,7 @@ function spawnAndCollect(context: SpawnContext): Promise<SpawnOutcome> {
 	const { command, args, cwd, timeoutMs, signal, result, onEvent, transcript, spawn } = context;
 	return new Promise<SpawnOutcome>((resolve) => {
 		const proc = spawn(command, args, { cwd, shell: false, stdio: ["ignore", "pipe", "pipe"] });
-		let buffer = "";
+		const splitter = new LineSplitter();
 		let settled = false;
 		let abortRequested = false;
 		let timedOut = false;
@@ -117,10 +120,8 @@ function spawnAndCollect(context: SpawnContext): Promise<SpawnOutcome> {
 			if (signal) signal.removeEventListener("abort", onAbort);
 			if (killTimer) clearTimeout(killTimer);
 			if (timeoutTimer) clearTimeout(timeoutTimer);
-			if (buffer.trim()) {
-				transcript?.line(buffer);
-				const event = parseJsonLine(buffer);
-				if (event && applyEvent(result, event)) onEvent();
+			for (const line of splitter.flush()) {
+				if (line.trim()) processLine(line);
 			}
 			resolve({ exitCode, aborted: abortRequested, timedOut });
 		};
@@ -132,15 +133,8 @@ function spawnAndCollect(context: SpawnContext): Promise<SpawnOutcome> {
 		};
 
 		proc.stdout?.on("data", (chunk) => {
-			const text = chunk.toString();
-			buffer += text;
-			// Keep the final partial line in the buffer for the close handler.
-			let newline = buffer.indexOf("\n");
-			while (newline !== -1) {
-				processLine(buffer.slice(0, newline));
-				buffer = buffer.slice(newline + 1);
-				newline = buffer.indexOf("\n");
-			}
+			// The splitter holds the final partial line for the close handler.
+			for (const line of splitter.push(chunk)) processLine(line);
 		});
 
 		proc.stderr?.on("data", (chunk) => {
@@ -236,12 +230,19 @@ export async function runSingleAgent(options: RunOptions): Promise<SingleResult>
 			spawn,
 		});
 
-		result.exitCode = outcome.timedOut ? 1 : outcome.exitCode;
+		result.exitCode = outcome.timedOut || outcome.aborted ? 1 : outcome.exitCode;
 		result.finishedAt = Date.now();
 		// A deadline fails the run rather than rejecting it: a chain then stops at
 		// this step and reports why, instead of discarding the steps already done.
 		if (outcome.timedOut) result.errorMessage = `Timed out after ${formatDuration(timeoutMs)}`;
-		if (outcome.aborted) throw new Error("Subagent was aborted");
+		if (outcome.aborted) {
+			if (options.abortAsResult) {
+				result.stopReason = "aborted";
+				result.errorMessage = "Aborted";
+				return result;
+			}
+			throw new Error("Subagent was aborted");
+		}
 		return result;
 	} finally {
 		// Flushed here, not after the call: the abort path throws past every caller.

package/extensions/subagent/schema.ts

@@ -66,6 +66,11 @@ export const SubagentParams = Type.Object({
 			description: "Force a read-only tool set (readers only). Plan mode sets this.",
 		}),
 	),
+	background: Type.Optional(
+		Type.Boolean({
+			description: "Start a single run and return immediately; inspect and collect it with /agents.",
+		}),
+	),
 });
 
 export type SubagentArgs = Static<typeof SubagentParams>;
@@ -85,6 +90,13 @@ export function resolveMode(params: SubagentArgs): ModeResolution {
 	const hasTasks = taskCount > 0;
 	const hasSingle = Boolean(params.agent && params.task);
 
+	if (params.background === true && (hasChain || hasTasks)) {
+		return { error: "`background` supports single mode only; provide `agent` and `task`." };
+	}
+	if (params.background === true && !hasSingle) {
+		return { error: "`background` requires `agent` and `task`." };
+	}
+
 	if (hasChain && hasTasks) return { error: "Provide either `chain` or `tasks`, not both." };
 	if (hasChain && hasSingle) return { error: "Provide either `chain` or `agent`+`task`, not both." };
 	if (hasTasks && hasSingle) return { error: "Provide either `tasks` or `agent`+`task`, not both." };

package/extensions/subagent/types.ts

@@ -64,6 +64,15 @@ export interface SingleResult {
 	artifactError?: string;
 }
 
+/** A background run the tool just started. */
+export interface BackgroundStart {
+	runId: string;
+	agent: string;
+	task: string;
+	cwd: string;
+	startedAt: number;
+}
+
 /** Structured result carried on the `subagent` tool result for rendering. */
 export interface SubagentDetails {
 	mode: SubagentMode;
@@ -74,6 +83,8 @@ export interface SubagentDetails {
 	projectAgentsDir?: string | null;
 	/** Whether the run forced a read-only tool set (plan mode). */
 	readOnly?: boolean;
+	/** Present when the tool started a background run instead of waiting. */
+	background?: BackgroundStart;
 	/**
 	 * Total steps/tasks requested, which can exceed `results.length` when a chain
 	 * stops early. Defaults to `results.length` when absent.

package/extensions/subagent/ui.ts

@@ -0,0 +1,50 @@
+/**
+ * Footer status and finish notices for background subagent runs.
+ *
+ * The runtime owns lifecycle and results; this owns the running-count chip and
+ * the notice that points back at `/agents`. A cancelled run stays silent because
+ * the user initiated it.
+ */
+
+import { sanitizeLine } from "../../lib/format.ts";
+import { GLYPHS, STATUS_KEYS } from "../../lib/tui/glyphs.ts";
+import { createStatusController, type StatusController } from "../../lib/tui/status-controller.ts";
+import type { BackgroundRun } from "./background.ts";
+
+export interface SubagentUiOptions {
+	/** The current runs, read fresh on every paint. */
+	runs(): readonly BackgroundRun[];
+}
+
+export interface SubagentUiController extends StatusController {
+	notifyFinished(run: BackgroundRun): void;
+}
+
+/** A status word a notice can read without exposing the type's spelling. */
+function statusText(status: BackgroundRun["status"]): string {
+	return status === "timedout" ? "timed out" : status;
+}
+
+export function createSubagentUi(options: SubagentUiOptions): SubagentUiController {
+	const controller = createStatusController({
+		keys: [STATUS_KEYS.agents],
+		enabled: () => true,
+		chips: () => {
+			const running = options.runs().filter((run) => run.status === "running").length;
+			return [{ key: STATUS_KEYS.agents, glyph: GLYPHS.delegation, count: running, role: "accent" }];
+		},
+	});
+
+	const notifyFinished = (run: BackgroundRun): void => {
+		// A cancelled run stays silent because the user initiated it.
+		if (run.status === "cancelled") return;
+		const failed = run.status === "failed" || run.status === "timedout";
+		const action = run.status === "finished" ? "collect" : "inspect";
+		controller.notify(
+			`Background subagent ${run.id} (${sanitizeLine(run.agent)}) ${statusText(run.status)}. Use /agents to ${action} it.`,
+			failed ? "error" : "info",
+		);
+	};
+
+	return { ...controller, notifyFinished };
+}

package/extensions/todo/README.md

@@ -174,13 +174,17 @@ depends on config.
 - **Whole-list replacement, not mutations.** Every call is a snapshot, so
   `todos: []` is the natural clear and there is no "forgot to toggle" failure
   mode. No ids or per-item update actions exist.
-- **State in tool-result `details`.** `reconstructTodos` replays the active
-  branch and takes the last `todo` result, so `/resume` and `/tree` reproduce
-  the list for that point in history. `pi.appendEntry()` was rejected because a
-  side-channel list would not branch; error results are skipped as non-writes.
-- **Validation is pure and fail-safe.** `normalizeTodos` throws a
-  model-readable message, and the tool turns that into an `isError` result that
-  carries the *previous* list. A rejected call never half-applies.
+- **State in tool-result `details`.** `lib/todo-state.ts`'s `lastTodos` replays
+  the active branch and takes the last write that fully validates, so `/resume`
+  and `/tree` reproduce the list for that point in history. The same replay is
+  what `plan` and `goal` read, so there is one rule for which write is a state
+  write. `pi.appendEntry()` was rejected because a side-channel list would not
+  branch; error results are skipped as non-writes.
+- **Validation is pure and fail-safe.** The parser (`normalizeTodos` in
+  `lib/todo-state.ts`) throws a model-readable message, and the tool turns that
+  into an `isError` result that carries the *previous* list. A rejected call
+  never half-applies, and branch replay follows the same rule: a stored write
+  that fails validation is ignored whole rather than partially applied.
 - **One `in_progress` item, with a label.** The rule is validated, not silently
   coerced, so the model learns it from the error. The item must carry a
   non-blank `activeForm`; branch replay passes `{ requireActiveForm: false }`
@@ -210,10 +214,10 @@ depends on config.
   answer and never reopens that path. `nudged` caps it at one per user turn,
   `setTodos` clears the counters, and `context` drops the hidden message on the
   next user turn so it never accumulates.
-- **Content is sanitized at the boundary.** `normalizeTodos` replaces control
-  characters and collapses whitespace before the length and duplicate checks,
-  keeping `format.ts` free of terminal concerns and every surface to one row
-  per item.
+- **Content is sanitized at the boundary.** `normalizeTodos` in
+  `lib/todo-state.ts` replaces control characters and collapses whitespace
+  before the length and duplicate checks, keeping `format.ts` free of terminal
+  concerns and every surface to one row per item.
 - **The widget summarizes; full views keep the model's order.** The persistent
   widget is a single line (`currentTodo` picks the `in_progress` item, else the
   first pending); `/todos` keeps the submitted order, and the transcript result
@@ -234,8 +238,9 @@ depends on config.
 |---|---|
 | `index.ts` | Factory: wire the runtime, tool, command, reminder events, and session events. |
 | `types.ts` | `Todo`, `TodoStatus`, `TodoDetails`. |
-| `schema.ts` | TypeBox parameters and pure validation/normalization. |
-| `state.ts` | Branch reconstruction and status queries (pure). |
+| `types.ts` | `Todo` and `TodoDetails`; re-exports `TodoStatus` / `TODO_STATUSES` from `lib/todo-state.ts`. |
+| `schema.ts` | TypeBox parameters; the parser and limits live in `lib/todo-state.ts`. |
+| `state.ts` | Status queries over the replayed list (pure). |
 | `nudge.ts` | Lag detection: mutating and file-write classification, due check, reminder text (pure). |
 | `format.ts` | Model-facing and transcript text (pure). |
 | `tui.ts` | Widget and scrollable `/todos` components, drawn from the `lib/tui/` kit (`titleRule`, `dockListFrame`, `listRow`, `emptyState`). |

package/extensions/todo/format.ts

@@ -4,7 +4,8 @@
 
 import type { Theme } from "@earendil-works/pi-coding-agent";
 import { truncateToWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
-import { expandHint, GLYPH_GAP, GLYPHS } from "../../lib/tui/glyphs.ts";
+import { GLYPH_GAP, GLYPHS } from "../../lib/tui/glyphs.ts";
+import { overflowHint } from "../../lib/tui/tool.ts";
 import { paint, type TuiRole } from "../../lib/tui/tokens.ts";
 import { completedCount, currentTodo } from "./state.ts";
 import type { Todo, TodoStatus } from "./types.ts";
@@ -149,7 +150,7 @@ export function todoRailLines(input: TodoRailInput, theme: Theme, width: number)
 		});
 	}
 	if (input.more && input.more > 0) {
-		lines.push(`${continuation}${paint(theme, "faint", `… ${input.more} more`)} ${expandHint(theme)}`);
+		lines.push(`${continuation}${overflowHint(theme, input.more)}`);
 	}
 	return lines.map((line) => truncateToWidth(line, w, "…"));
 }

package/extensions/todo/runtime.ts

@@ -12,9 +12,10 @@
 
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { onRailsSuppressed, onUpperRailChanged } from "../../lib/rails.ts";
+import { lastTodos } from "../../lib/todo-state.ts";
 import { DEFAULT_TODO_CONFIG, type TodoConfig } from "./config.ts";
 import { shouldNudge } from "./nudge.ts";
-import { hasOpenTodos, reconstructTodos } from "./state.ts";
+import { hasOpenTodos } from "./state.ts";
 import { TodoWidget, WIDGET_KEY } from "./tui.ts";
 import type { Todo } from "./types.ts";
 
@@ -115,7 +116,7 @@ export function createTodoRuntime(pi?: Pick<ExtensionAPI, "events">): TodoRuntim
 			notify();
 		},
 		reconstruct: (ctx) => {
-			todos = reconstructTodos(ctx.sessionManager.getBranch());
+			todos = lastTodos(ctx.sessionManager.getBranch());
 			mutations = 0;
 			writes = 0;
 			touched = false;

package/extensions/todo/schema.ts

@@ -1,28 +1,22 @@
 /**
- * Parameter schema and validation for the `todo` tool.
+ * Parameter schema for the `todo` tool.
  *
- * Everything here is pure: no host APIs, no terminal. Invalid input throws a
- * model-readable `Error` before any state changes, so the model can retry with
- * a corrected list instead of silently corrupting the list.
+ * The schema is the host-facing shape; the semantic validation and the branch
+ * replay live together in `lib/todo-state.ts`, so the tool, `plan`, and `goal`
+ * read the same rules. Invalid input still throws a model-readable `Error`
+ * before any state changes.
  */
 
 import { StringEnum } from "@earendil-works/pi-ai";
 import { Type, type Static } from "typebox";
-import { sanitizeLine } from "../../lib/format.ts";
-import { TODO_STATUSES, type Todo, type TodoStatus } from "./types.ts";
-
-/** Maximum number of items in one list. */
-export const MAX_TODOS = 50;
-/** Maximum length of a single item's text. */
-export const MAX_CONTENT = 500;
+import { MAX_TODOS, TODO_STATUSES } from "../../lib/todo-state.ts";
 
 /**
  * One item in the tool's input and output schemas.
  *
  * The input schema (`TodoParams`) enforces `maxItems` and the status enum
- * before `execute` runs. `normalizeTodos` re-enforces both for branch replay
- * and direct unit use, and owns the semantic rules the schema cannot express
- * (one `in_progress`, unique non-empty content, content length).
+ * before `execute` runs; `normalizeTodos` in `lib/todo-state.ts` re-enforces
+ * both and owns the semantic rules the schema cannot express.
  */
 export const TodoItem = Type.Object({
 	content: Type.String({ description: "Imperative description of the task" }),
@@ -53,73 +47,3 @@ export const TodoResult = Type.Object({
 });
 
 export type TodoArgs = Static<typeof TodoParams>;
-
-const STATUS_SET: ReadonlySet<string> = new Set(TODO_STATUSES);
-
-function normalizeStatus(raw: unknown, index: number): TodoStatus {
-	const value = typeof raw === "string" ? raw.trim().toLowerCase() : "";
-	if (STATUS_SET.has(value)) return value as TodoStatus;
-	throw new Error(`Todo ${index + 1}: status must be one of ${TODO_STATUSES.join(", ")}.`);
-}
-
-/** Options for {@link normalizeTodos}. */
-export interface NormalizeOptions {
-	/**
-	 * Require a non-blank `activeForm` on `in_progress` items. Live tool input
-	 * enforces this (the default); branch replay passes `false` so lists written
-	 * before the rule was added still load.
-	 */
-	requireActiveForm?: boolean;
-}
-
-/**
- * Validate and normalize the model's list.
- *
- * Content and `activeForm` are sanitized to a single safe line (see
- * `sanitizeLine`). Rejects an empty description, an unknown status, duplicate
- * content, an over-long field, more than one `in_progress` item, and — unless
- * `options.requireActiveForm` is `false` — an `in_progress` item without a
- * non-blank `activeForm`. `activeForm` is dropped when blank.
- */
-export function normalizeTodos(raw: unknown, options: NormalizeOptions = {}): Todo[] {
-	const requireActiveForm = options.requireActiveForm ?? true;
-	if (raw === undefined || raw === null) return [];
-	if (!Array.isArray(raw)) throw new Error("todos must be an array.");
-	if (raw.length > MAX_TODOS) throw new Error(`At most ${MAX_TODOS} todos are allowed.`);
-
-	const todos: Todo[] = [];
-	const seen = new Set<string>();
-	let inProgress = 0;
-
-	for (let i = 0; i < raw.length; i++) {
-		const item = (raw[i] ?? {}) as Partial<Todo>;
-		const content = typeof item.content === "string" ? sanitizeLine(item.content) : "";
-		if (!content) throw new Error(`Todo ${i + 1}: content is required.`);
-		if (content.length > MAX_CONTENT) {
-			throw new Error(`Todo ${i + 1}: content is longer than ${MAX_CONTENT} characters.`);
-		}
-
-		const key = content.toLowerCase();
-		if (seen.has(key)) throw new Error(`Todo ${i + 1}: duplicate content "${content}".`);
-		seen.add(key);
-
-		const status = normalizeStatus(item.status, i);
-		if (status === "in_progress") inProgress++;
-
-		const activeForm = typeof item.activeForm === "string" ? sanitizeLine(item.activeForm) : "";
-		if (activeForm.length > MAX_CONTENT) {
-			throw new Error(`Todo ${i + 1}: activeForm is longer than ${MAX_CONTENT} characters.`);
-		}
-		if (status === "in_progress" && requireActiveForm && !activeForm) {
-			throw new Error(
-				`Todo ${i + 1}: activeForm is required for an in_progress item (present-continuous, e.g. "Running tests").`,
-			);
-		}
-		todos.push(activeForm ? { content, status, activeForm } : { content, status });
-	}
-
-	if (inProgress > 1) {
-		throw new Error("At most one todo may be in_progress; mark the rest pending or completed.");
-	}
-	return todos;
-}

package/extensions/todo/state.ts

@@ -1,53 +1,12 @@
 /**
- * Branch-aware state for the todo extension (pure).
+ * Status queries over the list the branch published (pure).
  *
- * The list lives in each `todo` tool result's `details`, so navigating or
- * branching the session reproduces the list that was correct at that point.
- * `reconstructTodos` replays a branch and returns the last valid list; stored
- * values are re-validated and re-sanitized so corrupt or tampered branch data
- * cannot inject escapes, crash reconstruction, or wipe a valid list.
+ * The list itself — the item contract, its validation, and the single strict
+ * replay — lives in `lib/todo-state.ts`, shared with `plan` and `goal`. These
+ * are the derived facts the widget and the transcript ask of it.
  */
 
-import { TODO_TOOL } from "../../lib/tool-names.ts";
-import { normalizeTodos } from "./schema.ts";
-import type { Todo, TodoDetails } from "./types.ts";
-
-/** Minimal shape of a session entry, used for runtime narrowing. */
-interface BranchEntryLike {
-	type?: string;
-	message?: {
-		role?: string;
-		toolName?: string;
-		details?: unknown;
-	};
-}
-
-/** The last valid list written on the branch, or an empty list. */
-export function reconstructTodos(entries: Iterable<unknown>): Todo[] {
-	let todos: Todo[] = [];
-	for (const raw of entries) {
-		const entry = raw as BranchEntryLike;
-		if (entry?.type !== "message") continue;
-		const message = entry.message;
-		if (message?.role !== "toolResult" || message.toolName !== TODO_TOOL) continue;
-		const details = message.details as TodoDetails | undefined;
-		if (!details || details.todos === undefined) continue;
-		// A rejected call carries the unchanged list for the model to read; it is
-		// not a state write and must not be replayed as one.
-		if (details.error) continue;
-		// Anything that does not re-validate as a todo list is ignored, so a
-		// malformed entry cannot wipe a valid one. Replay is lenient about
-		// `activeForm`: a list written before that field was required still loads
-		// instead of being dropped.
-		if (!Array.isArray(details.todos)) continue;
-		try {
-			todos = normalizeTodos(details.todos, { requireActiveForm: false });
-		} catch {
-			// Keep the previous list.
-		}
-	}
-	return todos;
-}
+import type { Todo } from "./types.ts";
 
 /** Number of completed items. */
 export function completedCount(todos: Todo[]): number {

package/extensions/todo/tools.ts

@@ -15,12 +15,13 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { sanitizeLine } from "../../lib/format.ts";
 import { TODO_TOOL } from "../../lib/tool-names.ts";
 import { GLYPHS } from "../../lib/tui/glyphs.ts";
+import { normalizeTodos } from "../../lib/todo-state.ts";
 import { reuseText, toolDetails } from "../../lib/tui/chrome.ts";
 import { rejectionLine, reuseCallText, toolCallTitle } from "../../lib/tui/tool.ts";
 import { paint } from "../../lib/tui/tokens.ts";
 import { compareByActivity, formatCallText, formatTodoText, type TodoRailInput } from "./format.ts";
 import type { TodoRuntime } from "./runtime.ts";
-import { normalizeTodos, TodoParams, TodoResult, type TodoArgs } from "./schema.ts";
+import { TodoParams, TodoResult, type TodoArgs } from "./schema.ts";
 import { TodoResult as TodoResultView } from "./tui.ts";
 import type { Todo, TodoDetails } from "./types.ts";
 

package/extensions/todo/types.ts

@@ -1,26 +1,17 @@
 /**
  * Shared types for the todo extension.
  *
- * The todo list is a whole-list replacement, the way Claude Code's `TodoWrite`
- * works: the model always sends the complete list, so there is no "add" or
- * "toggle" operation and no id bookkeeping.
+ * The item contract itself lives in `lib/todo-state.ts`, which owns the parser
+ * and the branch replay shared with `plan` and `goal`; this module re-exports it
+ * under the name the extension uses and adds the tool-result shape.
  */
 
-export const TODO_STATUSES = ["pending", "in_progress", "completed"] as const;
+import type { ExistingTodo } from "../../lib/todo-state.ts";
 
-export type TodoStatus = (typeof TODO_STATUSES)[number];
+export { TODO_STATUSES, type TodoStatus } from "../../lib/todo-state.ts";
 
 /** One item in the list. */
-export type Todo = {
-	/** Imperative description of the task, e.g. "Write the parser tests". */
-	content: string;
-	status: TodoStatus;
-	/**
-	 * Present-continuous label shown while the item is in progress, e.g.
-	 * "Writing the parser tests". Falls back to `content` when absent.
-	 */
-	activeForm?: string;
-};
+export type Todo = ExistingTodo;
 
 /** Structured result carried in the tool's `details` and used for reconstruction. */
 export interface TodoDetails {