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

package/lib/report.ts

@@ -0,0 +1,99 @@
+/**
+ * The pending-report coordinator: how a live feature tells the model what
+ * happened without interrupting it.
+ *
+ * A watcher match and a finished job follow one rule — report at the next turn,
+ * and raise at most one triggered turn when the work opted into `wake`. The two
+ * traps are subtle enough to have been re-derived once per extension:
+ *
+ * - a wake is only safe while the agent is idle, so an outcome that arrives
+ *   mid-turn must be queued rather than sent;
+ * - between the triggered send and the `agent_start` it causes, the agent still
+ *   looks idle, so a second outcome in that window must not trigger a second
+ *   turn. `waking` closes that window.
+ *
+ * Delivery is one shared transcript notice per burst, and a burst is marked
+ * reported only after the send succeeded, so a throw leaves it for the next
+ * turn. Value-only: every flag lives in the returned closure, never in a module
+ * variable, because each extension gets its own module instance.
+ */
+
+import type { AgentMessage } from "@earendil-works/pi-agent-core";
+import { pruneStaleNotices, type NoticeMessage } from "./notice.ts";
+
+export interface PendingReporterOptions<T> {
+	/** Send a notice and ask the host to start one turn for it. */
+	wake(notice: NoticeMessage): void;
+	/** The outcomes not yet reported, oldest first. Does not mark them. */
+	pending(): T[];
+	/** Mark outcomes as reported, once the send has succeeded. */
+	markReported(items: T[]): void;
+	/** Build the notice for one burst: model text plus renderer details. */
+	buildNotice(items: T[]): NoticeMessage;
+	/** The notice's source, so only its own stale entries are pruned. */
+	source: string;
+	/** Runs after a wake turn was successfully requested, for an extra announcement. */
+	onWoke?(items: T[]): void;
+}
+
+/** The handlers an extension wires into its lifecycle hooks. */
+export interface PendingReporter {
+	/** An outcome arrived: wake a turn if the agent is idle, else leave it queued. */
+	report(): void;
+	/** A new session starts idle. */
+	sessionStart(): void;
+	/** A turn began: outcomes queue up, and none of them triggers a turn. */
+	agentStart(): void;
+	/** The turn settled: a later outcome may wake again. */
+	agentSettled(): void;
+	/** Report what is queued at the start of a turn, without triggering one. */
+	beforeAgentStart(): { message: NoticeMessage } | undefined;
+	/** Drop this source's older notices from the outgoing context. */
+	filterContext(messages: readonly AgentMessage[]): { messages: AgentMessage[] } | undefined;
+}
+
+export function createPendingReporter<T>(options: PendingReporterOptions<T>): PendingReporter {
+	const { wake, pending, markReported, buildNotice, source, onWoke } = options;
+	let busy = false;
+	let waking = false;
+
+	return {
+		report: () => {
+			if (busy || waking) return;
+			const items = pending();
+			if (items.length === 0) return;
+			try {
+				wake(buildNotice(items));
+			} catch {
+				// Reporting is best-effort; the next turn reports the same items.
+				return;
+			}
+			// Mark only after the send succeeded, so a throw changes nothing.
+			markReported(items);
+			waking = true;
+			onWoke?.(items);
+		},
+		sessionStart: () => {
+			busy = false;
+			waking = false;
+		},
+		agentStart: () => {
+			busy = true;
+		},
+		agentSettled: () => {
+			busy = false;
+			waking = false;
+		},
+		beforeAgentStart: () => {
+			const items = pending();
+			if (items.length === 0) return undefined;
+			const notice = buildNotice(items);
+			markReported(items);
+			return { message: notice };
+		},
+		filterContext: (messages) => {
+			const pruned = pruneStaleNotices(messages, source);
+			return pruned ? { messages: pruned } : undefined;
+		},
+	};
+}

package/lib/requirements.ts

@@ -17,6 +17,7 @@
 import { join } from "node:path";
 import { configSection, configValueAt, type JsonReadResult, SHARED_CONFIG_FILE } from "./config.ts";
 import type { WebSearchProviderEvent } from "./events.ts";
+import { pdfGuidance } from "./pdf.ts";
 import { getPiInvocation, type PiInvocation } from "./pi-invocation.ts";
 
 /** How a check came out. Only `missing` is worth interrupting a session for. */
@@ -167,19 +168,6 @@ export interface ExtensionReport {
 	findings: Finding[];
 }
 
-// --- Install guidance -------------------------------------------------------
-//
-// Moved here from the extensions that raise it, so `doctor` and the tool error
-// say the same thing. Formatting only: no extension-specific logic.
-
-/** Install command for the optional PDF extractor package. */
-const UNPDF_INSTALL = "npm i unpdf";
-
-/** Model-facing guidance when the optional `unpdf` package is absent. */
-export function pdfGuidance(): string {
-	return `PDF extraction requires the optional 'unpdf' package (${UNPDF_INSTALL}).`;
-}
-
 // --- The table --------------------------------------------------------------
 
 /**
@@ -224,6 +212,9 @@ export const REQUIREMENTS: Readonly<Record<string, ExtensionRequirements>> = {
 	},
 	todo: {},
 	goal: {},
+	check: {
+		notes: ["Runs the project's detected command through a shell; a stack with no detector needs `check.command`."],
+	},
 	plan: {
 		optional: [gitCheck("project-local `.pi/plans` (otherwise plans land in the agent directory)")],
 		notes: ["Needs an interactive UI to enter plan mode."],
@@ -769,19 +760,34 @@ export async function probeExtension(extension: string, seams: ProbeSeams): Prom
 	return { extension, enabled, findings };
 }
 
+/** Probes in flight at once: enough to hide spawn latency, not a burst. */
+export const PROBE_CONCURRENCY = 4;
+
 /**
- * Probe every declared extension, or just `names`, in declaration order.
+ * Probe every declared extension, or just `names`, keeping declaration order.
  *
- * Sequential on purpose: the caller runs this on a session-start budget, and a
- * burst of parallel probes would trade a few milliseconds for a burst of child
- * processes.
+ * The caller is a user-facing report (`run_doctor`) or the panel's refresh, so
+ * the probes run a few at a time: a serial pass pays the sum of every spawn and
+ * read, while one `Promise.all` over the whole table starts a burst of child
+ * processes. The startup check does not come through here; it probes only the
+ * hard requirements, all at once (see `probeRequired`).
  */
 export async function probeAll(
 	seams: ProbeSeams,
 	names: readonly string[] = Object.keys(REQUIREMENTS),
 ): Promise<ExtensionReport[]> {
-	const reports: ExtensionReport[] = [];
-	for (const name of names) reports.push(await probeExtension(name, seams));
+	const reports = new Array<ExtensionReport>(names.length);
+	let cursor = 0;
+	/** Take the next name until the queue is empty; each worker keeps its slot. */
+	const drain = async (): Promise<void> => {
+		while (cursor < names.length) {
+			const index = cursor;
+			cursor += 1;
+			reports[index] = await probeExtension(names[index], seams);
+		}
+	};
+	const workers = Array.from({ length: Math.min(PROBE_CONCURRENCY, names.length) }, () => drain());
+	await Promise.all(workers);
 	return reports;
 }
 

package/lib/spawn.ts

@@ -0,0 +1,170 @@
+/**
+ * The process seam shared by the extensions that run a shell command.
+ *
+ * `job`, `watch`, and `check` all start a command in its own process group,
+ * stream or discard its output, and kill the whole tree — a signal to the POSIX
+ * group, or `taskkill /T` on Windows. Only the policy on top differs (durable
+ * jobs, a tailed watcher, a bounded check), so the seam lives here.
+ *
+ * IO is split from the decision: {@link spawnOptions} and {@link killPlan} are
+ * pure and testable on every platform, while {@link defaultSpawn} and
+ * {@link defaultKillTree} execute them. Value-only, like every `lib/` module:
+ * no module state, and each caller keeps its own children.
+ */
+
+import { spawn as nodeSpawn, spawnSync } from "node:child_process";
+import type { Readable } from "node:stream";
+
+/**
+ * The writable end of a child's stdin pipe.
+ *
+ * Only the operations a caller needs, so tests can hand the runtime a recording
+ * double instead of a real socket.
+ */
+export interface StdinSink {
+	write(chunk: string): boolean;
+	end(): void;
+	destroy?(): void;
+	on(event: "error" | "close", listener: (error?: Error) => void): unknown;
+}
+
+/** The subset of a spawned child the extensions use. */
+export interface SpawnedProcess {
+	pid?: number;
+	stdout: Readable | null;
+	stderr: Readable | null;
+	/** Present only when the child was spawned with `stdin: true`. */
+	stdin?: StdinSink | null;
+	on(event: "close", listener: (code: number | null, signal: NodeJS.Signals | null) => void): unknown;
+	on(event: "error", listener: (error: Error) => void): unknown;
+	kill(signal?: NodeJS.Signals): boolean;
+	/** Detach from the parent's event loop, so a child cannot hold Pi open. */
+	unref?(): void;
+}
+
+export interface SpawnOptions {
+	cwd: string;
+	env?: NodeJS.ProcessEnv;
+	/** Give the child a stdin pipe instead of a closed stdin (no immediate EOF). */
+	stdin?: boolean;
+	/** The command writes its own output to a log; keep no parent pipe. */
+	detachOutput?: boolean;
+}
+
+export type SpawnFn = (command: string, options: SpawnOptions) => SpawnedProcess;
+
+/** Send `signal` to a pid's process tree, escalating to SIGKILL when `force`. */
+export type KillTreeFn = (pid: number, signal: NodeJS.Signals, force?: boolean) => void;
+
+/** The `stdio` triple a spawn needs: stdin, stdout, stderr. */
+export type SpawnStdio = ["pipe" | "ignore", "pipe" | "ignore", "pipe" | "ignore"];
+
+/** The `child_process.spawn` options this seam produces. */
+export interface NodeSpawnOptions {
+	cwd: string;
+	shell: boolean;
+	detached: boolean;
+	stdio: SpawnStdio;
+	env?: NodeJS.ProcessEnv;
+}
+
+/**
+ * The spawn options for one command: a shell in its own process group, so a
+ * signal can reach the shell and its descendants together.
+ *
+ * Stdin stays closed unless asked for, because a closed stdin gives the child
+ * EOF — a `read` exits instead of blocking forever. `detachOutput` keeps no
+ * parent pipe, for a child that writes its own log file.
+ */
+export function spawnOptions(options: SpawnOptions, platform: NodeJS.Platform = process.platform): NodeSpawnOptions {
+	return {
+		cwd: options.cwd,
+		shell: true,
+		detached: platform !== "win32",
+		stdio: [
+			options.stdin ? "pipe" : "ignore",
+			options.detachOutput ? "ignore" : "pipe",
+			options.detachOutput ? "ignore" : "pipe",
+		],
+		env: options.env,
+	};
+}
+
+/** What killing a pid's tree means on this platform. */
+export interface KillPlan {
+	/** A program to run instead of signalling (Windows has no process group). */
+	command?: { file: string; args: string[] };
+	/**
+	 * Pids to signal in order: the process group first, then the pid itself for a
+	 * child that is not a group leader (a reattached pid, for example).
+	 */
+	targets: number[];
+}
+
+/** The kill plan for `pid`: `taskkill /T` on Windows, group-then-pid otherwise. */
+export function killPlan(pid: number, force: boolean, platform: NodeJS.Platform = process.platform): KillPlan {
+	if (platform === "win32") {
+		const args = ["/pid", String(pid), "/T", ...(force ? ["/F"] : [])];
+		return { command: { file: "taskkill", args }, targets: [] };
+	}
+	return { targets: [-pid, pid] };
+}
+
+/** A signal-0 probe; injectable so the EPERM branch is testable. */
+export type KillProbe = (pid: number, signal: number) => unknown;
+
+/** Whether a pid is alive on this host. EPERM means it exists but is not ours. */
+export function isPidAlive(pid: number, probe: KillProbe = process.kill): boolean {
+	if (!Number.isFinite(pid) || pid <= 0) return false;
+	try {
+		probe(pid, 0);
+		return true;
+	} catch (error) {
+		return (error as NodeJS.ErrnoException).code === "EPERM";
+	}
+}
+
+/** The host seams {@link applyKillPlan} runs through. */
+export interface KillSeams {
+	/** Signal one pid; throws when the pid is gone or not ours. */
+	kill(pid: number, signal: NodeJS.Signals): unknown;
+	/** Run a program (the Windows `taskkill`). */
+	run(file: string, args: string[]): unknown;
+}
+
+/**
+ * Execute a {@link KillPlan}: run the command, or signal each target in order.
+ *
+ * The group attempt may answer `ESRCH` for a pid that is not a group leader, and
+ * the final attempt is the fallback, so its failure means "already gone" — a
+ * kill of a dead process is not an error a caller can act on.
+ */
+export function applyKillPlan(plan: KillPlan, signal: NodeJS.Signals, seams: KillSeams): void {
+	if (plan.command) {
+		seams.run(plan.command.file, plan.command.args);
+		return;
+	}
+	for (const [index, target] of plan.targets.entries()) {
+		const isFallback = index === plan.targets.length - 1;
+		try {
+			seams.kill(target, signal);
+			return;
+		} catch (error) {
+			if (!isFallback && (error as NodeJS.ErrnoException).code !== "ESRCH") throw error;
+		}
+	}
+}
+
+/** The real seams, so a caller needs no adapter. */
+const processSeams: KillSeams = {
+	kill: (pid, signal) => process.kill(pid, signal),
+	run: (file, args) => spawnSync(file, args, { stdio: "ignore" }),
+};
+
+/** Default spawn: a shell command in its own process group, output piped. */
+export const defaultSpawn: SpawnFn = (command, options) => nodeSpawn(command, spawnOptions(options));
+
+/** Default tree kill: process group on POSIX, `taskkill /T` on Windows. */
+export const defaultKillTree: KillTreeFn = (pid, signal, force = false) => {
+	applyKillPlan(killPlan(pid, force), signal, processSeams);
+};

package/lib/todo-state.ts

@@ -1,19 +1,43 @@
 /**
- * The published `todo` state, read back from the session branch (pure).
+ * The todo item contract, its parser, and the published state replayed from the
+ * session branch.
  *
- * The todo list is a whole-list replacement stored in each `todo` tool result's
- * `details`, so replaying the branch is how another extension reads it without
- * importing the todo extension. `plan` merges an approved plan's steps into the
- * last list, and `goal` mentions the items still open when a goal is marked
- * achieved.
+ * The list is a whole-list replacement stored in each `todo` tool result's
+ * `details`, so replaying the branch is how an extension reads it without
+ * importing the todo extension. `todo` reads the branch through the same
+ * {@link lastTodos} replay, so the tool, `plan`, and `goal` cannot disagree
+ * about which write is a state write: a write that fails validation is ignored
+ * and the last valid list stays, exactly as the tool itself keeps the previous
+ * list on a rejected call.
+ *
+ * Stored values are re-validated and re-sanitized here. Branch data can be
+ * tampered with, migrated, or written by an older version, and a reader must not
+ * pass escapes or unbounded text onward; anything that fails validation is
+ * ignored rather than partially applied.
+ *
+ * Value-only: no module state, no host access.
  */
 
+import { sanitizeLine } from "./format.ts";
 import { TODO_TOOL } from "./tool-names.ts";
 
-/** One item in a `todo` list, as the todo tool stores it. */
+/** Statuses a todo item may carry. */
+export const TODO_STATUSES = ["pending", "in_progress", "completed"] as const;
+
+/** One item's status. */
+export type TodoStatus = (typeof TODO_STATUSES)[number];
+
+/** 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;
+
+/** One item in a `todo` list, as the tool stores it. */
 export interface ExistingTodo {
+	/** Imperative description of the task. */
 	content: string;
-	status: "pending" | "in_progress" | "completed";
+	/** Where the item sits in the list. */
+	status: TodoStatus;
 	/** Present-continuous label the todo tool requires for an in-progress item. */
 	activeForm?: string;
 }
@@ -28,14 +52,82 @@ interface BranchEntryLike {
 	};
 }
 
-function isStatus(value: unknown): value is ExistingTodo["status"] {
-	return value === "pending" || value === "in_progress" || value === "completed";
+const STATUS_SET: ReadonlySet<string> = new Set(TODO_STATUSES);
+
+function normalizeTodoStatus(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;
 }
 
 /**
- * The last valid todo list written on the branch, or an empty list. A rejected
- * call carries the unchanged list and is not a state write, so it is skipped;
- * an entry that does not re-validate is ignored rather than wiping a good list.
+ * Validate and normalize a todo 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 = {}): ExistingTodo[] {
+	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: ExistingTodo[] = [];
+	const seen = new Set<string>();
+	let inProgress = 0;
+
+	for (let i = 0; i < raw.length; i++) {
+		const item = (raw[i] ?? {}) as Partial<ExistingTodo>;
+		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 = normalizeTodoStatus(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;
+}
+
+/**
+ * The last valid todo list written on the branch, or an empty list.
+ *
+ * A rejected call carries the unchanged list and is not a state write, so it is
+ * skipped. A write that fails validation is ignored whole, so a corrupt or
+ * tampered entry cannot wipe or partially replace a valid list.
  */
 export function lastTodos(entries: Iterable<unknown>): ExistingTodo[] {
 	let todos: ExistingTodo[] = [];
@@ -47,16 +139,11 @@ export function lastTodos(entries: Iterable<unknown>): ExistingTodo[] {
 		const details = message.details as { todos?: unknown; error?: unknown } | undefined;
 		if (!details || details.error) continue;
 		if (!Array.isArray(details.todos)) continue;
-		todos = details.todos.flatMap((item): ExistingTodo[] => {
-			if (typeof item !== "object" || item === null) return [];
-			const value = item as { content?: unknown; status?: unknown; activeForm?: unknown };
-			if (typeof value.content !== "string" || !isStatus(value.status)) return [];
-			const content = value.content.trim();
-			if (!content) return [];
-			const activeForm =
-				typeof value.activeForm === "string" && value.activeForm.trim() ? value.activeForm.trim() : undefined;
-			return [activeForm ? { content, status: value.status, activeForm } : { content, status: value.status }];
-		});
+		try {
+			todos = normalizeTodos(details.todos, { requireActiveForm: false });
+		} catch {
+			// Keep the previous list.
+		}
 	}
 	return todos;
 }

package/lib/tool-names.ts

@@ -15,6 +15,13 @@ export const TODO_TOOL = "todo";
 /** The `goal` tool, allowlisted as a reader by plan and rewind. */
 export const GOAL_TOOL = "goal";
 
+/**
+ * The `enter_plan_mode` tool. `plan` registers it, and `goal` offers the same
+ * phase to the user, so the name is shared: the request channel and the
+ * registration probe both look it up.
+ */
+export const PLAN_ENTER_TOOL = "enter_plan_mode";
+
 /** The `subagent` tool, which plan mode pins to read-only delegation. */
 export const SUBAGENT_TOOL = "subagent";
 

package/lib/tool-result.ts

@@ -0,0 +1,33 @@
+/**
+ * The shared shape of a rejected tool call.
+ *
+ * Extension tools return an `isError: true` result carrying their own `details`
+ * type. `toolError` builds the content and the flag so the extensions that
+ * reject a call (`job` and `watch`, plus any future tool) agree on the shape.
+ */
+
+/** One text block in a tool result. */
+export interface ToolErrorContent {
+	type: "text";
+	text: string;
+}
+
+/** A rejected tool call: the message as content, the extension's details, and the error flag. */
+export function toolError<Details extends { action: string; error: string }>(
+	message: string,
+	details: Details,
+): { content: ToolErrorContent[]; details: Details; isError: true } {
+	return {
+		content: [{ type: "text", text: `Error: ${message}` }],
+		details,
+		isError: true,
+	};
+}
+
+/** A rejected tool call whose details are only the action and the message. */
+export function errorResult<Action extends string>(
+	action: Action,
+	message: string,
+): { content: ToolErrorContent[]; details: { action: Action; error: string }; isError: true } {
+	return toolError(message, { action, error: message });
+}

package/lib/tui/README.md

@@ -30,9 +30,61 @@ build a second terminal renderer.
 ## Primitives
 
 Reach for a `lib/tui/` primitive before composing your own: `plainRule` /
-`titleRule` for a heading, `listRow` / `checkbox` for a list, `gaugeBar` for a
-meter, `emptyState` for an empty screen, `splitRow` / `fitCells` for two columns,
-`LinePane` for a scrollable log, and `ListCursor` / `IdCursor` for selection.
+`titleRule` for a heading, `listRow` / `statusRow` / `checkbox` for a list,
+`gaugeBar` for a meter, `emptyState` for an empty screen, `splitRow` /
+`fitCells` for two columns, `LinePane` for a scrollable log, `ListCursor` /
+`IdCursor` for selection, `byRunningFirst` for a live list's order,
+`DockListScreen` for a list that opens a pane, `TailResult` for a tool result
+that lists rows or tails output, and `ConfirmState` before a destructive action.
+
+## Docked list screens
+
+Every list screen is `dockListFrame`: the header rule, an optional summary and
+its blank line, the body, an optional range row, an optional detail block, and
+the blank-padded hint. The frame owns that spacing, so a screen never hand-rolls
+it — including the blank line above the detail block, which keeps a footnote
+from reading as one more row. A screen that sizes its body through `fitRows`
+counts the block with `detailBlockRows`, or the hint row is pushed off the
+bottom of a short terminal.
+
+A list that **opens a pane over one row** — `/jobs`, `/watch`, `/agents`,
+`/check` — subclasses [`dock-screen.ts`](./dock-screen.ts) instead of
+re-assembling the frame. `DockListScreen` owns the two modes, the `IdCursor` and
+`LinePane`, the navigation and wheel keys, the y/N confirmation, the one-line
+feedback notice, and the range rows; the subclass supplies `rows`, `idOf`,
+`rowLine`, `detailBlock`, `summaryCells`, `listHints(rows)`, `detailHints(row)`,
+`detailFor`, and `handleVerb`. Keep the ordering in `rows()` (the base re-reads
+it every render) and return it by stable id, so a live re-sort cannot move the
+cursor or swap the open pane out from under the reader.
+
+Four optional members cover what a richer screen needs, and each defaults to
+what a plain list wants — do not hand-roll the frame to get one of them:
+
+- `DetailContents.facts(width)` — rows *above* the scrollable body that depend on
+  the width (key/value facts, a legend). The body's lines are built once at open,
+  so anything width-dependent belongs here, and the base counts the rows against
+  the pane's height.
+- `liveDetail()` — set it when the pane's source changes between frames on its
+  own (a child's output) rather than on a poll. The base then re-reads
+  `detailById` while rendering, without asking for another frame, and closes the
+  pane if the row is gone.
+- `detailById(id)` — the poll source job and watch read every 500 ms; omit it
+  when nothing polls the pane.
+- `handleDetailVerb(key, row)` — a verb that also works while reading the pane
+  (`c` collect, `x` cancel). Return `true` for the keys it claimed; everything
+  else falls through to the pane's scroll keys.
+
+A destructive action asks through [`confirm.ts`](./confirm.ts):
+`ConfirmState.ask(prompt, accept)` holds the question, `resolve(data)` accepts on
+`y`/`Y`/Enter, dismisses on `n`/`N`/Esc/`q`, and returns `undefined` for any
+other key so a stray arrow cannot cancel the question. The prompt ends in
+`? y/N`.
+
+The block carries footnotes about the focused row: what the row does not already
+say. Never repeat its label, verdict, or duration — the row is one line above,
+and a second copy is noise the reader has to compare. Prose that the hint row
+already says with keys does not belong there either; a sentence that long is
+clipped mid-word at the widths the screen runs at.
 
 ## Color is a role
 
@@ -42,6 +94,13 @@ token named inline; a theme swap must re-skin every surface. Use the shared
 `selectionMarker`, `GLYPHS`, `SEPARATORS`, and `STATUS_KEYS` instead of retyping
 their literals, and `screenHint` / Pi's `keyHint` for the hint row.
 
+A list accents the focused row's label (`labelRole: selected ? "accent" :
+"label"`); the `❯` marker alone is not enough to tell which row is live. The
+hint row colors by role, not by taste: `accent` for the screen's primary action,
+`warning` for one that discards state (a revert, a kill, a stop, a clear, a
+forget), and `error` for one that ends the session. Keys that navigate, scroll,
+or select stay dim, so a colored key is one worth a second thought.
+
 ## Width is columns
 
 Width is terminal columns, not string length. Use `visibleWidth`,
@@ -59,6 +118,12 @@ widget or the terminal: it neutralizes control characters and then collapses the
 text to one line. `stripControlChars` alone is for multi-line text that must keep
 its newlines.
 
+Program output — a log file, a child's stdout, a tailed file — goes through
+`sanitizeUntrustedLine` instead. It removes OSC, CSI, and single-character
+escapes whole (so the printable tail of an escape never reaches the terminal),
+then resolves `\r` the way a terminal would, squeezes whitespace, and clips.
+`sanitizeLine` would leave `[31m` behind, because it turns ESC into a space.
+
 ## Keyboard first
 
 Use `matchesKey` / `Key`, give every mouse interaction a keyboard path, and keep