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

package/extensions/subagent/transcripts.ts

@@ -0,0 +1,202 @@
+/**
+ * Opt-in per-run transcripts.
+ *
+ * The dispatching process writes these; a child never learns that one exists, so
+ * the read-only tool set and the project-agent trust gate stay exactly as strict
+ * as they are. Lines are buffered in memory up to {@link MAX_TRANSCRIPT_BYTES}
+ * and flushed once at the end of the run, which keeps the store ordered without a
+ * stream to close and still writes on the abort path.
+ *
+ * Every failure is reported, never thrown: an unwritable checkout must not fail a
+ * delegation that already did its work.
+ */
+
+import { randomBytes } from "node:crypto";
+import { mkdirSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { CONFIG_DIR_NAME, getAgentDir, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { repoRootFor } from "../../lib/git/index.ts";
+import type { SingleResult } from "./types.ts";
+
+/** Ceiling for one run's buffered transcript, stdout and stderr together. */
+export const MAX_TRANSCRIPT_BYTES = 32 * 1024 * 1024;
+
+/** `YYYYMMDD-HHMMSS-abcdef`; a name sort is chronological, so pruning never parses one. */
+const RUN_ID_PATTERN = /^\d{8}-\d{6}-[0-9a-f]{6}$/;
+
+const EVENTS_FILE = "events.jsonl";
+const STDERR_FILE = "stderr.log";
+const META_FILE = "meta.json";
+
+/** What a transcript needs from the run that produced it. */
+export interface TranscriptContext {
+	/** Working directory the child ran in. */
+	cwd: string;
+	/** Whether the run forced a reader-only tool set. */
+	readOnly: boolean;
+}
+
+/** The outcome of writing one run directory. */
+export interface TranscriptWritten {
+	/** Directory written, absent when the write failed. */
+	path?: string;
+	/** Bytes buffered for this run. */
+	bytes: number;
+	/** Whether the size cap cut the transcript short. */
+	truncated: boolean;
+	/** Why the write failed, when it did. */
+	error?: string;
+}
+
+/** A run's buffered transcript, written once the run has finished. */
+export interface Transcript {
+	/** Append one raw stdout line. */
+	line(raw: string): void;
+	/** Append stderr text, which may arrive in partial chunks. */
+	stderr(text: string): void;
+	/** Write the run directory under `dir`. Never throws. */
+	write(dir: string, result: SingleResult, context: TranscriptContext): TranscriptWritten;
+}
+
+/** The directory holding every transcript for `cwd`'s repository. */
+export async function transcriptsDirFor(pi: Pick<ExtensionAPI, "exec">, cwd: string): Promise<string> {
+	const root = await repoRootFor(pi, cwd, 5_000);
+	return root ? join(root, CONFIG_DIR_NAME, "subagents") : join(getAgentDir(), "subagents");
+}
+
+/** A run id for `at` (epoch ms, rendered in UTC) with a six-hex suffix. */
+export function runIdFor(at: number, suffix: string): string {
+	const date = new Date(at);
+	const pad = (value: number, width = 2) => String(value).padStart(width, "0");
+	const day = `${date.getUTCFullYear()}${pad(date.getUTCMonth() + 1)}${pad(date.getUTCDate())}`;
+	const time = `${pad(date.getUTCHours())}${pad(date.getUTCMinutes())}${pad(date.getUTCSeconds())}`;
+	return `${day}-${time}-${suffix}`;
+}
+
+/** The metadata written beside a run's stream; enough to audit it without one. */
+function metaFor(runId: string, result: SingleResult, context: TranscriptContext, truncated: boolean) {
+	return {
+		version: 1,
+		runId,
+		agent: result.agent,
+		agentSource: result.agentSource,
+		task: result.task,
+		step: result.step,
+		cwd: context.cwd,
+		readOnly: context.readOnly,
+		provider: result.provider,
+		model: result.model,
+		startedAt: result.startedAt,
+		finishedAt: result.finishedAt,
+		exitCode: result.exitCode,
+		timedOut: result.timedOut === true,
+		stopReason: result.stopReason,
+		errorMessage: result.errorMessage,
+		toolErrors: result.toolErrors ?? 0,
+		usage: result.usage,
+		transcript: { truncated },
+	};
+}
+
+/** Buffer one run's stream until it finishes. */
+export function createTranscript(options: { maxBytes?: number } = {}): Transcript {
+	const maxBytes = options.maxBytes ?? MAX_TRANSCRIPT_BYTES;
+	const lines: string[] = [];
+	let stderr = "";
+	let bytes = 0;
+	let truncated = false;
+
+	const append = (text: string, kind: "line" | "stderr"): void => {
+		if (truncated || !text) return;
+		const size = Buffer.byteLength(text);
+		if (bytes + size > maxBytes) {
+			// Stop growing; the marker is added on write so the file stays parseable.
+			truncated = true;
+			return;
+		}
+		bytes += size;
+		if (kind === "line") lines.push(text);
+		else stderr += text;
+	};
+
+	return {
+		line: (raw) => append(raw, "line"),
+		stderr: (text) => append(text, "stderr"),
+
+		write(dir, result, context) {
+			const runId = runIdFor(result.startedAt ?? Date.now(), randomBytes(3).toString("hex"));
+			const runDir = join(dir, runId);
+			try {
+				mkdirSync(runDir, { recursive: true });
+				const body = truncated ? [...lines, JSON.stringify({ type: "transcript-truncated", bytes })] : lines;
+				if (body.length > 0) writeFileSync(join(runDir, EVENTS_FILE), `${body.join("\n")}\n`, { mode: 0o600 });
+				if (stderr) writeFileSync(join(runDir, STDERR_FILE), stderr, { mode: 0o600 });
+				// Written last: a directory without metadata is an interrupted write.
+				const meta = `${JSON.stringify(metaFor(runId, result, context, truncated), null, 2)}\n`;
+				writeFileSync(join(runDir, META_FILE), meta, { mode: 0o600 });
+				return { path: runDir, bytes, truncated };
+			} catch (error) {
+				return {
+					bytes,
+					truncated,
+					error: error instanceof Error ? error.message : String(error),
+				};
+			}
+		},
+	};
+}
+
+/** Which run directories a prune keeps and which it removes. */
+export interface PruneOutcome {
+	removed: string[];
+	/** Runs still on disk after the prune. */
+	kept: number;
+}
+
+/**
+ * Remove aged and surplus run directories. Only names matching a run id are
+ * candidates, so an unrelated directory under the store is never touched.
+ */
+export function pruneTranscripts(
+	dir: string,
+	options: { retentionDays: number; maxRuns: number; now?: number },
+): PruneOutcome {
+	const now = options.now ?? Date.now();
+	let names: string[];
+	try {
+		names = readdirSync(dir, { withFileTypes: true })
+			.filter((entry) => entry.isDirectory() && RUN_ID_PATTERN.test(entry.name))
+			.map((entry) => entry.name)
+			.sort();
+	} catch {
+		return { removed: [], kept: 0 };
+	}
+
+	const kept: string[] = [];
+	const stale: string[] = [];
+	for (const name of names) {
+		let modified: number;
+		try {
+			modified = statSync(join(dir, name)).mtimeMs;
+		} catch {
+			continue;
+		}
+		if (now - modified > options.retentionDays * 86_400_000) stale.push(name);
+		else kept.push(name);
+	}
+	while (kept.length > options.maxRuns) {
+		const oldest = kept.shift();
+		if (oldest) stale.push(oldest);
+	}
+
+	const removed: string[] = [];
+	for (const name of stale) {
+		try {
+			rmSync(join(dir, name), { recursive: true, force: true });
+			removed.push(name);
+		} catch {
+			// Best-effort: a locked directory is retried at the next session start.
+		}
+	}
+	return { removed, kept: kept.length };
+}

package/extensions/subagent/types.ts

@@ -50,6 +50,27 @@ export interface SingleResult {
 	startedAt?: number;
 	/** Epoch ms when the subprocess finished. */
 	finishedAt?: number;
+	/** Whether the run hit its wall-clock limit, which fails the run without aborting it. */
+	timedOut?: boolean;
+	/** The limit that applied to this run in ms; absent when it had none. */
+	timeoutMs?: number;
+	/** Directory of the run's transcript, when one was written. */
+	artifactPath?: string;
+	/** Bytes buffered for the transcript. */
+	artifactBytes?: number;
+	/** Whether the transcript stopped at the size cap. */
+	artifactTruncated?: boolean;
+	/** Why the transcript could not be written, when it could not. */
+	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. */
@@ -62,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 {

package/extensions/watch/README.md

@@ -103,6 +103,8 @@ render the tail of the sanitized lines, with the hidden count noted above and
 
 ### Command: /watch
 
+<img src="../../assets/watch.png" alt="The /watch screen: a Watch title rule, a `2 watchers · 1 running · 3 matches` summary, a selected file watcher and a finished command watcher, the focused watcher's path and pattern with its line and match counts, and the key hints" width="100%">
+
 A bare `/watch` opens a dock screen listing watchers. `j`/`k` (and the wheel)
 move, `Enter`/`l` opens a watcher's matches, `x`/`K` stops a running watcher
 behind a `y/N` confirm, `d` clears stopped ones behind a `y/N` confirm, `Esc`
@@ -195,6 +197,14 @@ other.
 
 ## Design notes
 
+The shared seams are `lib/`'s: `lib/spawn.ts` (spawn, tree-kill), `lib/lines.ts`
+(the byte-safe splitter), `lib/format.ts` (`sanitizeUntrustedLine`),
+`lib/report.ts` (pending matches → notice → one wake turn),
+`lib/tui/status-controller.ts` (chips and the alert), and
+`lib/tui/dock-screen.ts` (the `/watch` frame, navigation, and confirm layer).
+What stays here is the watcher policy: the tailer, the matcher, the source
+model, the command-child lifecycle in `child.ts`, and the watcher vocabulary.
+
 The file tailer polls and exposes `tick()` publicly; the interval is a thin
 wrapper over `tick()`, so tests drive matching deterministically with no real
 timer. A command tailer is event-driven and feeds both output streams through
@@ -212,15 +222,15 @@ outlive the session.
 
 | Module | Responsibility |
 |---|---|
-| `index.ts` | Extension factory: registers the tool and command, wires the lifecycle and the shared notices. |
+| `index.ts` | Extension factory: registers the tool and command, wires the lifecycle, the shared `lib/report.ts` match reporter, and the shared notices. |
 | `tools.ts` | The `watch` tool definition, execution, and transcript rendering. |
 | `schema.ts` | TypeBox parameters and pure `normalizeCall` validation. |
 | `types.ts` | `WatchAction`/`WatchStatus`, `WatchRecord`, `WatchDetails`, `PendingMatch`. |
-| `runtime.ts` | The session-scoped watcher table, matcher, poll tick, and shutdown. |
-| `process.ts` | Injectable spawn and process-tree kill. |
-| `format.ts` | Pure sanitization and text formatting. |
-| `ui.ts` | Status chips and the match alert, over the shared `lib/tui/status-controller.ts`. |
-| `tui.ts` | `WatchResult` transcript block and the `/watch` dock screen, drawn from the `lib/tui/` kit (`titleRule`, `listRow`, `emptyState`, `IdCursor`, `LinePane`). |
+| `runtime.ts` | The session-scoped watcher table, matcher, poll tick, and shutdown; spawning and tree-kill come from `child.ts`, line splitting from `lib/lines.ts`. |
+| `child.ts` | A command watcher's process lifecycle: spawn, the SIGTERM → SIGKILL grace, and the shutdown drain, over the injected `SpawnFn`/`KillTreeFn` seams. |
+| `format.ts` | Pure text formatting; sanitization is `lib/format.ts`'s `sanitizeUntrustedLine`. |
+| `ui.ts` | Status chips and the match alert, over the shared `lib/tui/status-controller.ts` (chips, attached context, `notify`). |
+| `tui.ts` | The `WatchResult` transcript block over the shared `TailResult`, and the `/watch` screen as a `DockListScreen` subclass: watcher rows, focus block, counts, verbs. |
 | `commands.ts` | The `/watch` command and its completions. |
 | `config.ts` | The `watch` config section load and normalization. |