@gavin-hu/my-pi-agent 0.19.0 → 0.20.0

package/extensions/worktree/shell.ts

@@ -0,0 +1,303 @@
+/**
+ * Reading a shell command line: its words, its segments, and its redirection targets.
+ *
+ * The isolation guards in `guard.ts` ask questions about a command through this module and
+ * never re-lex it themselves: one reader, so "where does this command go" has one answer.
+ * A quoted word keeps whether it began inside quotes, and anything that cannot be expanded
+ * statically is reported as unresolved rather than guessed at.
+ */
+
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import { isInside } from "../../lib/path.ts";
+import { isShellEscapable } from "../../lib/shell.ts";
+
+// ---------------------------------------------------------------------------
+// Shell commands (checks 2-4)
+// ---------------------------------------------------------------------------
+
+/** One shell word, with whether it began inside a quote (a quoted literal). */
+export interface ShellWord {
+	text: string;
+	leadingQuoted: boolean;
+}
+
+/** Split a command on unquoted `;`, `&`, `|`, and newlines, preserving quotes. */
+export function splitSegments(command: string): string[] {
+	const segments: string[] = [];
+	let current = "";
+	let quote: string | null = null;
+	for (let i = 0; i < command.length; i++) {
+		const ch = command[i];
+		if (quote) {
+			current += ch;
+			if (ch === "\\" && quote === '"' && i + 1 < command.length) {
+				const next = command[i + 1];
+				if (isShellEscapable(next)) current += command[++i];
+			} else if (ch === quote) {
+				quote = null;
+			}
+			continue;
+		}
+		if (ch === "'" || ch === '"') {
+			quote = ch;
+			current += ch;
+		} else if (ch === ";" || ch === "\n") {
+			segments.push(current);
+			current = "";
+		} else if (ch === "&") {
+			const prev = command[i - 1];
+			const next = command[i + 1];
+			if (next === "&") {
+				// `&&` is a command separator.
+				segments.push(current);
+				current = "";
+				i++;
+			} else if (prev === ">" || prev === "<" || next === ">") {
+				// `>&`, `<&`, `&>`: redirection, not a separator.
+				current += ch;
+			} else {
+				// Background job `&`.
+				segments.push(current);
+				current = "";
+			}
+		} else if (ch === "|") {
+			if (command[i + 1] === "&") i++; // `|&` is still a pipe separator.
+			segments.push(current);
+			current = "";
+		} else {
+			current += ch;
+		}
+	}
+	segments.push(current);
+	return segments;
+}
+
+/** Tokenize a shell segment into words, removing quotes and tracking quoted leads. */
+export function tokenize(segment: string): ShellWord[] {
+	const words: ShellWord[] = [];
+	let current = "";
+	let leadingQuoted = false;
+	let started = false;
+	let quote: string | null = null;
+	const push = () => {
+		if (started) words.push({ text: current, leadingQuoted });
+		current = "";
+		leadingQuoted = false;
+		started = false;
+	};
+	for (let i = 0; i < segment.length; i++) {
+		const ch = segment[i];
+		if (quote) {
+			if (ch === "\\" && quote === '"' && i + 1 < segment.length) {
+				const next = segment[i + 1];
+				if (isShellEscapable(next)) current += segment[++i];
+				else current += ch;
+			} else if (ch === quote) {
+				quote = null;
+			} else {
+				current += ch;
+			}
+			continue;
+		}
+		if (ch === "'" || ch === '"') {
+			if (!started) {
+				started = true;
+				leadingQuoted = true;
+			}
+			quote = ch;
+		} else if (ch === " " || ch === "\t") {
+			push();
+		} else if (ch === "\\" && i + 1 < segment.length) {
+			started = true;
+			const next = segment[i + 1];
+			if (isShellEscapable(next)) current += segment[++i];
+			else current += ch;
+		} else {
+			started = true;
+			current += ch;
+		}
+	}
+	push();
+	return words;
+}
+
+/**
+ * Expand `~` and environment variables so a path that only leaves the worktree
+ * after shell expansion is still caught. `unresolved` marks a value that cannot
+ * be expanded statically (unknown variable, `$`, backtick, `~user`); callers
+ * treat it as escaping, because guessing could allow a bypass.
+ */
+export function expandShellPath(raw: string): { path?: string; unresolved: boolean } {
+	let value = raw;
+	if (value === "~") value = homedir();
+	else if (value.startsWith("~/")) value = join(homedir(), value.slice(2));
+	else if (value.startsWith("~")) return { unresolved: true };
+
+	let unresolved = false;
+	value = value.replace(/\$\{([A-Za-z_][A-Za-z0-9_]*)\}|\$([A-Za-z_][A-Za-z0-9_]*)/g, (match, braced, plain) => {
+		const name = braced ?? plain;
+		const env = process.env[name];
+		if (env === undefined) {
+			unresolved = true;
+			return match;
+		}
+		return env;
+	});
+	if (value.includes("$") || value.includes("`")) unresolved = true;
+	return { path: value, unresolved };
+}
+
+/** Whether a shell path argument leaves the worktree once expanded. */
+export function pathEscapes(root: string, raw: string): boolean {
+	const expanded = expandShellPath(raw);
+	if (expanded.unresolved || !expanded.path) return true;
+	return !isInside(root, resolve(root, expanded.path));
+}
+
+/**
+ * Constructs whose text does not spell out the git command that runs. Exported
+ * so the `tool_call` handler counts exactly the commands this check would have
+ * refused, instead of guessing at a second list.
+ */
+export function isUnverifiable(command: string): boolean {
+	return /\$\(|`|\$\{!|\beval\b|\b(?:sh|bash|zsh|dash|ksh)\s+-c\b/.test(command);
+}
+
+/**
+ * Redirection targets: the paths a command writes to or reads from.
+ *
+ * The output and input operators name a path; descriptor duplication, a heredoc delimiter,
+ * and a here-string do not, so those are skipped rather than reported as an escape.
+ */
+
+// ---------------------------------------------------------------------------
+// Shell redirections (check 1b)
+// ---------------------------------------------------------------------------
+
+export interface Redirect {
+	target: string;
+	/** True for output/read-write redirections; false for input-only. */
+	write: boolean;
+}
+
+/** Read a shell word starting at `start`, skipping leading blanks, unquoting the result. */
+export function readShellWord(text: string, start: number): { raw: string; end: number } {
+	let i = start;
+	while (i < text.length && (text[i] === " " || text[i] === "\t")) i++;
+	let raw = "";
+	let quote: string | null = null;
+	while (i < text.length) {
+		const ch = text[i];
+		if (quote) {
+			if (ch === "\\" && quote === '"' && i + 1 < text.length) {
+				const next = text[i + 1];
+				if (isShellEscapable(next)) {
+					raw += next;
+					i += 2;
+				} else {
+					raw += ch;
+					i += 1;
+				}
+				continue;
+			}
+			if (ch === quote) {
+				quote = null;
+				i++;
+				continue;
+			}
+			raw += ch;
+			i++;
+			continue;
+		}
+		if (ch === "'" || ch === '"') {
+			quote = ch;
+			i++;
+			continue;
+		}
+		if (ch === "\\" && i + 1 < text.length) {
+			const next = text[i + 1];
+			if (isShellEscapable(next)) {
+				raw += next;
+				i += 2;
+			} else {
+				raw += ch;
+				i += 1;
+			}
+			continue;
+		}
+		if (ch === " " || ch === "\t") break;
+		raw += ch;
+		i++;
+	}
+	return { raw, end: i };
+}
+
+/**
+ * File redirection targets in one shell segment. File-descriptor duplications
+ * (`2>&1`), heredocs (`<<EOF`), and here-strings (`<<<x`) are skipped because
+ * their operand is not a path.
+ */
+export function redirectionTargets(segment: string): Redirect[] {
+	const redirects: Redirect[] = [];
+	let quote: string | null = null;
+	for (let i = 0; i < segment.length; i++) {
+		const ch = segment[i];
+		if (quote) {
+			if (ch === "\\" && quote === '"' && i + 1 < segment.length) {
+				i++;
+				continue;
+			}
+			if (ch === quote) quote = null;
+			continue;
+		}
+		if (ch === "'" || ch === '"') {
+			quote = ch;
+			continue;
+		}
+		if (ch === "\\") {
+			i++;
+			continue;
+		}
+		if (ch !== ">" && ch !== "<") continue;
+
+		const two = segment.slice(i, i + 2);
+		const three = segment.slice(i, i + 3);
+		if (three === "<<<") {
+			i += 2;
+			continue;
+		}
+		if (two === "<<") {
+			// Heredoc delimiter: not a path.
+			i += 1;
+			continue;
+		}
+		if (two === ">&" || two === "<&") {
+			// File-descriptor duplication (`2>&1`, `>&-`) is not a path, but bash
+			// treats `>&file` as `&>file` (stdout+stderr to a file).
+			const operand = readShellWord(segment, i + 2);
+			if (operand.raw === "" || /^\d+$/.test(operand.raw) || operand.raw === "-") {
+				i += 1;
+				continue;
+			}
+			redirects.push({ target: operand.raw, write: ch === ">" });
+			i = operand.end - 1;
+			continue;
+		}
+		// `>`, `>>`, `>|`, `<`, `<>`: the next word is a path.
+		const write = ch === ">" || two === "<>";
+		if (two === ">>" || two === ">|") i += 1;
+		const word = readShellWord(segment, i + 1);
+		if (word.raw) redirects.push({ target: word.raw, write });
+		i = word.end - 1;
+	}
+	return redirects;
+}
+
+/** The wrappers and assignment shapes a policy reads through. */
+/** Commands that wrap another command, so a following assignment is still a prefix. */
+export const COMMAND_WRAPPERS = new Set(["sudo", "doas", "env", "command", "builtin", "exec", "nohup", "nice", "time"]);
+
+export function isAssignment(word: string): boolean {
+	return /^[A-Za-z_][A-Za-z0-9_]*=/.test(word);
+}

package/extensions/worktree/state.ts

@@ -12,7 +12,7 @@ const STATE_ENTRY = "worktree";
 
 export interface WorktreeState {
 	active: boolean;
-	/** Name of a managed worktree ("feature-auth"). Absent for foreign paths. */
+	/** Name of a managed worktree ("feature-auth"). Absent on an inherited checkout. */
 	name?: string;
 	/** Absolute path of the worktree. */
 	path: string;

package/extensions/worktree/status.ts

@@ -4,8 +4,8 @@
  *
  * One snapshot feeds both surfaces: `formatWorktreeStatus` renders it as the text
  * a tool result or a headless command prints, and `screen.ts` renders the same
- * rows as the `/worktree` list screen. They read the same git calls, so they
- * cannot disagree about a worktree.
+ * rows as the `/worktree` list screen. They read the same git calls and word a row
+ * through the same `statusMarks`, so the two cannot disagree about a worktree.
  */
 
 import { basename } from "node:path";
@@ -13,7 +13,7 @@ import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-a
 import { mapConcurrent } from "../../lib/pool.ts";
 import { loadConfig } from "./config.ts";
 import { gapLines, type IsolationGap, isolationGaps } from "./gaps.ts";
-import { type CheckoutCheck, defaultBranch, listManagedWorktrees, type ManagedWorktree, repoRoot } from "./git.ts";
+import { type CheckoutRefusal, defaultBranch, listManagedWorktrees, type ManagedWorktree, repoRoot } from "./git.ts";
 import { reconcileRegistry, statusOf, type CheckoutStatus } from "./registry.ts";
 import { configFor, getActive, getInactiveOverrides, getUnverifiableCommands } from "./runtime.ts";
 import type { WorktreeState } from "./state.ts";
@@ -22,6 +22,22 @@ export function worktreeLabel(state: WorktreeState): string {
 	return state.name ?? basename(state.path);
 }
 
+/**
+ * What entering a worktree is reported as, on every surface that reports it.
+ *
+ * The tool, the `/worktree` command, and the startup flag say the same sentence through
+ * this one function; the command adds the path on a line of its own, because a command's
+ * answer is read without a tool result beside it.
+ */
+export function enteredWorktree(state: WorktreeState): string {
+	return `Entered worktree ${worktreeLabel(state)}`;
+}
+
+/** What leaving one is reported as, for the same reason. */
+export function exitedWorktree(state: WorktreeState): string {
+	return `Exited worktree ${worktreeLabel(state)}`;
+}
+
 /**
  * The worktree/path/branch/main fact block shared by the status summary and
  * the injected prompt section. `pathLabel` and `column` preserve each
@@ -47,9 +63,14 @@ export function stateSummary(state: WorktreeState): string {
 	return `Worktree: ${worktreeLabel(state)}\n${worktreeFacts(state, "path", 8, [base])}`;
 }
 
-/** Actionable message for a worktree the session refuses to restore. */
-export function refusalMessage(check: CheckoutCheck, path: string, cwd: string): string {
-	if (check.ok) return "";
+/**
+ * Actionable message for a worktree the session refuses to restore.
+ *
+ * The parameter is the refusal half of `CheckoutCheck`, so "there is a message" is the
+ * type's claim rather than a guard's: its only caller is the branch that already knows the
+ * check failed.
+ */
+export function refusalMessage(check: CheckoutRefusal, path: string, cwd: string): string {
 	if (check.reason === "gone") {
 		return `Worktree ${path} no longer exists; its binding was cleared and the session continues in ${cwd}.`;
 	}
@@ -65,17 +86,29 @@ export function refusalMessage(check: CheckoutCheck, path: string, cwd: string):
 	);
 }
 
-/** Compact marks for one managed worktree in the status list. */
+/**
+ * Compact marks for one managed worktree, as both surfaces print them.
+ *
+ * A worktree with nothing to report says `clean` rather than nothing: a blank column reads
+ * as "not read yet", and the screen had to invent the word for itself before this owned it.
+ */
 export function statusMarks(status: CheckoutStatus, isCurrent: boolean): string[] {
 	const marks: string[] = [];
-	if (isCurrent) marks.push("current");
 	if (status.state === "missing") marks.push("missing");
 	if (status.locked) marks.push(status.staleLock ? "locked (stale)" : "locked");
 	if (status.state === "dirty") marks.push(`dirty (${status.changed})`);
 	if (status.ahead > 0) marks.push(`ahead ${status.ahead}`);
 	if (status.behind > 0) marks.push(`behind ${status.behind}`);
-	if (status.merged) marks.push("merged");
+	// A merged mark claims the work landed; with no commits of its own the worktree is an
+	// empty checkout, and saying so is the difference between "nothing here yet" and "done".
+	// How many commits landed is the number that mark is about, so it goes beside it.
+	if (status.commits === 0) marks.push("no commits");
+	else if (status.merged) marks.push(...(status.commits === undefined ? [] : [`commits ${status.commits}`]), "merged");
 	if (status.lastUsedAt) marks.push(`used ${relativeDay(status.lastUsedAt)}`);
+	// `clean` answers "what is wrong with this checkout", so it does not stand in for the
+	// session's own mark: a worktree this session is in and has not touched is both.
+	if (marks.length === 0) marks.push("clean");
+	if (isCurrent) marks.unshift("current");
 	return marks;
 }
 

package/extensions/worktree/tools.ts

@@ -4,12 +4,14 @@
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
+import { messageOf } from "../../lib/errors.ts";
 import {
 	enterWorktree,
 	exitWorktree,
 	isWorktreeCancelled,
 	pruneWorktrees,
-	worktreeLabel,
+	enteredWorktree,
+	exitedWorktree,
 	worktreeStatus,
 } from "./lifecycle.ts";
 import { getActive, getInactiveOverrides } from "./runtime.ts";
@@ -26,6 +28,18 @@ export const WORKTREE_TOOLS = {
 	list: "list_worktrees",
 } as const;
 
+/**
+ * The result a lifecycle tool answers when the user declined.
+ *
+ * Entering and exiting ask the same question and are refused the same way: the message is
+ * the refusal the user just chose, and `cancelled` is what tells a caller it was a choice
+ * rather than a failure. A cancelled call still throws — every other error is a real one.
+ */
+function cancelledResult(error: unknown): { content: [{ type: "text"; text: string }]; details: { cancelled: true } } {
+	if (!isWorktreeCancelled(error)) throw error;
+	return { content: [{ type: "text", text: messageOf(error) }], details: { cancelled: true } };
+}
+
 export function registerTools(pi: ExtensionAPI): void {
 	pi.registerTool({
 		name: WORKTREE_TOOLS.enter,
@@ -55,17 +69,13 @@ export function registerTools(pi: ExtensionAPI): void {
 		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
 			try {
 				const { state, summary } = await enterWorktree(pi, ctx, { name: params.name, path: params.path });
-				ctx.ui.notify(`Entered worktree ${worktreeLabel(state)}`, "info");
+				ctx.ui.notify(enteredWorktree(state), "info");
 				return {
 					content: [{ type: "text", text: summary }],
 					details: { state },
 				};
 			} catch (error) {
-				if (isWorktreeCancelled(error)) {
-					const message = error instanceof Error ? error.message : String(error);
-					return { content: [{ type: "text", text: message }], details: { cancelled: true } };
-				}
-				throw error;
+				return cancelledResult(error);
 			}
 		},
 	});
@@ -91,17 +101,13 @@ export function registerTools(pi: ExtensionAPI): void {
 		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
 			try {
 				const result = await exitWorktree(pi, ctx, { remove: params.remove, keepBranch: params.keepBranch });
-				ctx.ui.notify(`Exited worktree ${worktreeLabel(result.state)}`, "info");
+				ctx.ui.notify(exitedWorktree(result.state), "info");
 				return {
 					content: [{ type: "text", text: result.output }],
 					details: { state: result.state, removed: result.removed, handoff: result.handoff },
 				};
 			} catch (error) {
-				if (isWorktreeCancelled(error)) {
-					const message = error instanceof Error ? error.message : String(error);
-					return { content: [{ type: "text", text: message }], details: { cancelled: true } };
-				}
-				throw error;
+				return cancelledResult(error);
 			}
 		},
 	});

package/lib/README.md

@@ -33,7 +33,7 @@ belongs in that extension instead — see `extensions/web-access/http.ts` and
 | [`interaction.ts`](./interaction.ts) | Turn-affinity prompt contract: the channel a remote transport marks on the UI context it owns (`INTERACTION_TURN_KEY`), the `InteractionChannel` interface (`request` / `post` / `postFile`, plus an optional `setPromptTimeout` scope for a dialog the human must read something before answering), and `remoteChannel` / `isRemoteTurn` / `supportsCustomUI` / `askHuman` (with an optional file, fallback text, digest preface, and prompt `timeoutMs`) plus the shared “Other” label. |
 | [`git/`](./git/) | Shared git plumbing. [`git/runner.ts`](./git/runner.ts) is the `RunGit` seam (`createExecRunner` with timeout/env handling, `runGitOrThrow`, `GitError`); [`git/read.ts`](./git/read.ts) holds the read helpers (`repoRoot`, `repoRootFor`, `gitDir`, `gitCommonDir`, `revParse`, `revParseMany` for several revisions in one call, `hasCommits`, `currentBranch`); [`git/index.ts`](./git/index.ts) is the barrel. |
 | [`highlight.ts`](./highlight.ts) | First-party, escape-first syntax tokenizer (`detectLanguage`, `fenceLanguage`, `highlightLines`, `HighlightLanguage`, `TokenClass`) for js/ts, json, css, html, shell, python, java, yaml, and sql; shared by `file-browse` and plan's code blocks. |
-| [`http/`](./http/) | The loopback HTTP layer shared by `file-browse`, `plan`, and `board`: [`http/serve.ts`](./http/serve.ts) (the one server entry, `serveLoopback` — bind with a port retry, the capped request body, `HEAD` of a stream, the SSE head, idle grace, and the idempotent close — so an extension supplies a handler and no extension builds a `node:http` server), [`http/sink.ts`](./http/sink.ts) (`EventSink`, the one thing a route writes, which owns liveness — a write after the end is a no-op — plus the open-stream registry and the idle grace armed when the last one goes), [`http/headers.ts`](./http/headers.ts) (the page policy `PAGE_CSP` and the `pageHeaders` / `scriptHeaders` / `jsonHeaders` sets, plus `eventHeaders` for the one long-lived stream), [`http/response.ts`](./http/response.ts) (`ServeResponse` — a buffered body, a `filePath` stream, or an SSE `stream` — plus `htmlResponse` / `jsonResponse` / `jsonError` / `textResponse`), [`http/router.ts`](./http/router.ts) (`parseRequestUrl`, and `isLocalHostHeader` with the `required` mode each server chooses), [`http/guard.ts`](./http/guard.ts) (the request guards a served page shares: `postOnly`, `checkOrigin`, `requireJsonBody`, and `envelopeRefusal` — the method allowlist, then the fail-closed `Host` rule, then the origin check on every state-changing method), [`http/token.ts`](./http/token.ts) (`mintToken`, 128 random bits as hex, and `tokenMatches`, the constant-time comparison a route trusts), [`http/server.ts`](./http/server.ts) (the socket primitives `serveLoopback` is built from — `bindHost` with the accept-error listener, `respond` for HEAD / streamed file / body, `openEventStream`, and the idempotent `createCloser` — layer-internal, so the barrel does not export them), and the [`http/index.ts`](./http/index.ts) barrel. |
+| [`http/`](./http/) | The loopback HTTP layer shared by `file-browse`, `plan`, and `board`: [`http/serve.ts`](./http/serve.ts) (the one server entry, `serveLoopback` — bind with a port retry, the capped request body, `HEAD` of a stream, the SSE head, idle grace, and the idempotent close — so an extension supplies a handler and no extension builds a `node:http` server), [`http/sink.ts`](./http/sink.ts) (`EventSink`, the one thing a route writes, which owns liveness — a write after the end is a no-op — plus the open-stream registry and the idle grace — armed when the last one goes, and, for a server that asks, from the bind so a page no tab ever opened cannot hold its port), [`http/headers.ts`](./http/headers.ts) (the page policy `PAGE_CSP` and the `pageHeaders` / `scriptHeaders` / `jsonHeaders` sets, plus `eventHeaders` for the one long-lived stream), [`http/response.ts`](./http/response.ts) (`ServeResponse` — a buffered body, a `filePath` stream, or an SSE `stream` — plus `htmlResponse` / `jsonResponse` / `jsonError` / `textResponse`), [`http/router.ts`](./http/router.ts) (`parseRequestUrl`, and `isLocalHostHeader` with the `required` mode each server chooses), [`http/guard.ts`](./http/guard.ts) (the request guards a served page shares: `postOnly`, `checkOrigin`, `requireJsonBody`, and `envelopeRefusal` — the method allowlist, then the fail-closed `Host` rule, then the origin check on every state-changing method), [`http/token.ts`](./http/token.ts) (`mintToken`, 128 random bits as hex, and `tokenMatches`, the constant-time comparison a route trusts), [`http/server.ts`](./http/server.ts) (the socket primitives `serveLoopback` is built from — `bindHost` with the accept-error listener, `respond` for HEAD / streamed file / body, `openEventStream`, and the idempotent `createCloser` — layer-internal, so the barrel does not export them), and the [`http/index.ts`](./http/index.ts) barrel. |
 | [`tui/`](./tui/) | The Bytefly terminal design system shared by every interactive surface, whose conventions are its own doc, [`tui/README.md`](./tui/README.md). Modules: [`tui/tokens.ts`](./tui/tokens.ts) (semantic role -> theme color, `paint`), [`tui/glyphs.ts`](./tui/glyphs.ts) (`GLYPHS`, `SEPARATORS`, `STATUS_KEYS`, `EXPAND_KEYBINDING` with `expandKey` / `expandHint`, `GLYPH_GAP` — the vocabulary both sides of a status must agree on), [`tui/chrome.ts`](./tui/chrome.ts) (the docked-list frame `dockListFrame`, the `screenFooter` that closes a screen's own rows, `screenHint`, `detailBlockRows` (the rows its detail block costs), `viewportRows`, `FULL_SCREEN_OVERLAY`, `reuseText`, `editorTheme`), [`tui/rules.ts`](./tui/rules.ts) (the rule glyph `RULE_GLYPH`, and `plainRule` / `titleRule` / `centeredRule`), [`tui/indent.ts`](./tui/indent.ts) (the transcript block indent: `BODY_INDENT`, an optional rail prefix that a wrapped call line is kept out of, and `bodyLines` / `indentBlockLines` / `indentedLines`), [`tui/rows.ts`](./tui/rows.ts) (`listRow` with its `align` option for a value held beside its label, `statusRow`, `checkbox`, `chip`, `keyValueRow`, `emptyState`, `byRunningFirst` for a live list's order), [`tui/columns.ts`](./tui/columns.ts) (`splitRow` for two cells at the two edges, `inlineRow` for two cells held together, `fitCells`, `flowCells`, `padTo`, `clip`, `clipMiddle`, `labelLine` / `clipLabel` with `LABEL_WIDTH`), [`tui/gauge.ts`](./tui/gauge.ts) (`computeGauge`, `gaugeRole`, `gaugeBar`), [`tui/line-pane.ts`](./tui/line-pane.ts) (`LinePane`, the scrollable log/match pane), [`tui/status-controller.ts`](./tui/status-controller.ts) (`createStatusController`, the footer chips `job`, `watch`, and `subagent` share, with the attached-context `notify` and a `detach` that clears its keys), [`tui/dock-screen.ts`](./tui/dock-screen.ts) (`DockListScreen`, the two-mode docked list + detail-pane screen with navigation, wheel, range, and confirm), [`tui/confirm.ts`](./tui/confirm.ts) (`ConfirmState`, the y/N layer behind every destructive screen action), [`tui/tool.ts`](./tui/tool.ts) (`toolCallTitle`, the width-safe `ToolCallText` / `reuseCallText`, `callLine` — the one headline every renderer draws — `detailsOrLine` (a result's details, or the one `errorLine` / `rejectionLine` a failure shows), sanitized `errorLine` / `rejectionLine`, `moreHint` / `overflowHint` / `earlierHint`, the `TailResult` transcript block, `syncElapsedTimer`, `elapsedSuffix` — the tool-transcript kit), [`tui/render-cache.ts`](./tui/render-cache.ts) (`RenderCache`: the per-instance line memo a component that derives its lines from another component's output renders through, so a repeat frame is one comparison), and [`tui/cursor.ts`](./tui/cursor.ts) (scroll and navigation: `fitRows`, `keepVisible`, `clampScroll`, `navIntent`, `navigateList`, `navigateScroll`, `wheelDelta`, `scrollList`, `isCloseKey`, `selectionMarker`, `formatRange`, and the `ListCursor` (by index) and `IdCursor` (by stable id) state). |
 | [`path.ts`](./path.ts) | `isInside` (string containment) plus `realPathOfNearest` / `isInsideReal` (symlink-aware): the containment predicates the file-browse, worktree, doc, and plan guards share, and the canonical-path helper the worktree registry keys records by. |
 | [`pdf.ts`](./pdf.ts) | The optional `unpdf` seam shared by `web-access` and `file-read`: `pdfGuidance`, `PdfUnavailableError`, `pdfTextFromResult`, and the lazy `loadPdfExtractor` / `extractPdfText` (an injected extractor wins), so a missing package and a merged-pages result read the same way through either surface. |
@@ -44,19 +44,20 @@ belongs in that extension instead — see `extensions/web-access/http.ts` and
 | [`rails.ts`](./rails.ts) | Above-editor widget ordering (`goal` → `todo`) and dock-screen suppression, carried on `pi.events`. |
 | [`repo-key.ts`](./repo-key.ts) | The per-repository storage key that outlives one checkout: `repoKeyOf(value)` hashes an identity to `REPO_KEY_LENGTH` hex characters, and `repoKeyFor(pi, cwd)` returns `{ root, key, fromGit }` from the repository's *common* git directory, so every worktree of one repository files state under the same key, while a directory outside git keys on itself. Shared by `session-bus` (sessions, mail, claims) and `plan` (plans). |
 | [`screen-session.ts`](./screen-session.ts) | `withPolledScreen`: mount one `ctx.ui.custom` dock screen — rails suppressed for its lifetime, an optional repaint tick through an injected `RepeatTimer`, and one teardown — handing the mount the host's `tui`, `theme`, `requestRender`, `close`, and `viewportRows`. Shared by `/jobs`, `/watch`, and `/memory`, whose rails window and timer window were the same one. |
-| [`board/`](./board/) | The shared feature board. [`board/card.ts`](./board/card.ts) is the record: `CARD_VERSION`, `Card` / `CardStatus` / `CardOwner` / `CardNote`, the field caps `MAX_TITLE` / `MAX_PATHS` / `MAX_PLAN` / `MAX_NOTE` / `MAX_NOTES`, the `normalize*` boundary the model's arguments pass (`normalizeTitle`, `normalizePathHints` — repo-relative hints, never claims —, `normalizeNote`, `normalizePlanPath`, `normalizeCardId`, `normalizePriority`), the priority (`PRIORITIES`, `priorityOf`, `priorityRank`) and the links (`dependsOf`), `matchesQuery` — the rule `list`'s `query` applies, which the page's filter box answers in its own script — `cardRef`, `signatureOf`, and `isCard`, the one gate a file read passes. [`board/rules.ts`](./board/rules.ts) is the lifecycle: `Actor`, `CardOp` (including `edit`, whose fields are each optional because an omitted one must be left alone), `createCard`, the pure `applyOp` over the card *and* the board index (every transition, its owner rule, the dependency gates a claim, a move, and a drop pass, and the sentence a refusal carries, with a no-op reported as `changed: false`), and `holds`. [`board/links.ts`](./board/links.ts) is the dependency graph that index answers: `BoardIndex` / `indexOf`, `blockersOf` (what is unfinished), `dependentsOf` / `dependedOn` (what a drop would strand), `wouldCycle`, and `normalizeDepends` — one edge stored once, as an id in the waiting card's file. [`board/session.ts`](./board/session.ts) is the session a call works as (`BoardSession`, `openBoardSession` — one store per working directory, and the id/label pair a card records, shared by `board` and `team`). [`board/store.ts`](./board/store.ts) is the backend: `BoardStore` over `<agentDir>/board/<repo-key>/cards/*.json`, with `createStore(dir)` and the one construction point `openBoard(pi, cwd)` — `create` allocates the id by hard-linking a temp file onto the name (so two adds cannot share one), `mutate` re-reads the board and re-checks an operation whose card changed underneath instead of overwriting it, `list` orders a lane by priority before age, and nothing prunes. [`board/round.ts`](./board/round.ts) is the lead's rollup (`buildRound`, `IDLE_MS` — owners, unassigned, unplanned, blocked, idle, done, read from the cards alone so it works with the bus disabled), and [`board/round-text.ts`](./board/round-text.ts) is that rollup as the sentences a reader gets (`formatRound`, `plural`), so the tool's result and `team`'s `/team` cannot describe one board two ways. [`board/view.ts`](./board/view.ts) is the page's snapshot (`buildView` → lanes, counts, rollup, bytes, signature, where, and the session reading it), the one shape a client is allowed to know. [`board/page-pointer.ts`](./board/page-pointer.ts) is how a second session finds a page already serving (`PAGE_FILE`, `PagePointer`, `readPointer`, the exclusive `createPointer`, `clearPointer` for its own note only, `probePage` — the file is believed only while it answers, and it carries a view token, never the write one — and `settlePointer`, the ladder a starting page runs: write, attach to a winner that answers, take over a note proved dead, and name the file rather than blame a session when it cannot be read). |
-| [`session-roster.ts`](./session-roster.ts) | Who is on this repository's bus, read as data: `readRoster(dir)` returns `RosterSession` (`id`, `label`, `mode`, `lastSeen`, `mail`, and `watching` when the record says) or `undefined` when the bus has never been used here, `rosterStateOf` applies the liveness rule, and `BUS_DIR_NAME` / `SESSIONS_DIR_NAME` / `INBOX_DIR_NAME` / `SESSION_TTL_MS` are the one copy of the layout, imported by `session-bus` and read by `board`'s page so the Team tab can list teammates without the board depending on the bus extension. |
+| [`board/`](./board/) | The shared feature board. [`board/card.ts`](./board/card.ts) is the record: `CARD_VERSION`, `Card` / `CardStatus` / `CardOwner` / `CardNote`, the field caps `MAX_TITLE` / `MAX_PATHS` / `MAX_PLAN` / `MAX_NOTE` / `MAX_NOTES`, the `normalize*` boundary the model's arguments pass (`normalizeTitle`, `normalizePathHints` — repo-relative hints, never claims —, `normalizeNote`, `normalizePlanPath`, `normalizeCardId`, `normalizePriority`), the priority (`PRIORITIES`, `priorityOf`, `priorityRank`), the lane clock (`CardTransition`, `MAX_LOG`, and `laneSince` — when the card entered the lane it is in, or nothing when its history does not say) and the links (`dependsOf`), `matchesQuery` — the rule `list`'s `query` and the page's filter box both answer, spliced into the bundle as `MATCHES_QUERY_JS` so it cannot become two rules — `cardRef`, `signatureOf`, and `isCard`, the one gate a file read passes. [`board/rules.ts`](./board/rules.ts) is the lifecycle: `Actor`, `CardOp` (including `edit`, whose fields are each optional because an omitted one must be left alone), `createCard`, the pure `applyOp` over the card *and* the board index (every transition, its owner rule, the dependency gates a claim, a move, and a drop pass, `archive` — the one op that moves no field, because the pile a finished card's file lies in is the whole of it — and the sentence a refusal carries, with a no-op reported as `changed: false`), and `holds`. [`board/links.ts`](./board/links.ts) is the dependency graph that index answers: `BoardIndex` / `indexOf`, `blockersOf` (what is unfinished) and `blockersText` (the same list as `#2 (doing)`, one wording for a refusal and for the page), `dependentsOf` / `dependedOn` (what a drop would strand), `wouldCycle`, and `normalizeDepends` — one edge stored once, as an id in the waiting card's file. [`board/session.ts`](./board/session.ts) is the session a call works as (`BoardSession`, `openBoardSession` — one store per working directory, and the id/label pair a card records, shared by `board` and `team`). [`board/store.ts`](./board/store.ts) is the backend: `BoardStore` over `<agentDir>/board/<repo-key>/cards/*.json`, with `createStore(dir)` and the one construction point `openBoard(pi, cwd)` — `create` allocates the id by hard-linking a temp file onto the name (so two adds cannot share one), `mutate` re-reads the board and re-checks an operation whose card changed underneath instead of overwriting it, `list` orders a lane by priority before age, `archive` renames a finished card's file into `archive/` beside the cards without rewriting it — so `read` finds a card in either pile and writes it back to that one, and `list` still reads the board alone —, `archived()` / `archivedCount()` are the pile on request and its count, `nextCardId` spends an archived number as well as an ended one, and neither pile is pruned by a janitor: `archive` and `drop` are the two ways a card leaves the board. [`board/round.ts`](./board/round.ts) is the lead's rollup (`buildRound`, `IDLE_MS` — owners, unassigned, unplanned, blocked, idle, done, read from the cards alone so it works with the bus disabled), and [`board/round-text.ts`](./board/round-text.ts) is that rollup as the sentences a reader gets (`formatRound`, `plural`), so the tool's result and `team`'s `/team` cannot describe one board two ways. [`board/view.ts`](./board/view.ts) is the page's snapshot (`buildView` → lanes, counts, rollup, bytes, signature, where, and the session reading it), the one shape a client is allowed to know: each card arrives as a `ViewCard` carrying the priority it acts on, the moment it entered its lane (`since`), and, when something unfinished blocks it, `waits` — so the browser renders an answer instead of re-deciding one. [`board/page-pointer.ts`](./board/page-pointer.ts) is how a second session finds a page already serving (`PAGE_FILE`, `PagePointer`, `readPointer`, the exclusive `createPointer`, `clearPointer` for its own note only, `probePage` — the file is believed only while it answers, and it carries the page's one token, which reads and nothing else — and `settlePointer`, the ladder a starting page runs: write, attach to a winner that answers, take over a note proved dead, and name the file rather than blame a session when it cannot be read). |
+| [`session-roster.ts`](./session-roster.ts) | Who is on this repository's bus, read as data: `readRoster(dir)` returns `RosterSession` (`id`, `label`, `mode`, `lastSeen`, `mail`, `pid` and `startToken` when the record names them, and `watching` when it says) or `undefined` when the bus has never been used here, `rosterStateOf` answers `live` / `quiet` / `gone` — a dead pid outranks a fresh heartbeat, and the start token settles a reused pid — and `BUS_DIR_NAME` / `SESSIONS_DIR_NAME` / `INBOX_DIR_NAME` / `SESSION_TTL_MS` are the one copy of the layout, imported by `session-bus` and read by `board`'s page so the Team tab can list teammates without the board depending on the bus extension. |
 | [`session-tool.ts`](./session-tool.ts) | The `session` tool as the other extensions call it: `join(ctx, {label?, wake?, listen?})`, `peers(ctx)`, and `send(ctx, {kind, to, text})`, each a typed result that never throws (`{ ok, error }` or `undefined` for a read the bus cannot answer), plus `MAX_MESSAGE_TEXT`, the send cap `session-bus` re-exports as `MAX_TEXT`. One copy, because the alternative is two extensions knowing the tool's details shape. |
 | [`session-label.ts`](./session-label.ts) | The label rules a session is addressed by and a card records: `MAX_LABEL`, `normalizeLabel` (one line, capped, with a fallback), `shortId`, and `defaultLabel` (the Pi session name, else the working directory's basename, else the id). Shared by `session-bus` (which settles the unique one) and `board` (which records it on a claimed card), so a card's owner names a target the bus answers to. |
 | [`requirements.ts`](./requirements.ts) | Per-extension runtime prerequisite table plus a pure `probeExtension(seams)` over injected seams (exec, config reads, optional imports, the published search provider, env, and a refresh-only reachability probe): bytefly's doctor surface reports on it and the extensions that own a dependency format their errors from it. A check kind is either a prerequisite (`binary`, `module`, `state`, `invocation`, `notify`, `provider`) or a `safety` switch whose off value trades a protection away, read from `bytefly.json` global-then-project. |
 | [`shell.ts`](./shell.ts) | Shell escape rule shared by the worktree isolation guard and plan mode's read-only git guard: `SHELL_ESCAPABLE`, `isShellEscapable`, `hasShellEscape`. |
-| [`spawn.ts`](./spawn.ts) | The process seam for extensions that run a shell command: `SpawnedProcess`, `SpawnFn`, `KillTreeFn`, the pure `spawnOptions` / `killPlan`, `applyKillPlan` over injected seams, `isPidAlive`, and the `defaultSpawn` / `defaultKillTree` that execute them (process group on POSIX, `taskkill /T` on Windows). Shared by `job`, `watch`, `check`, `worktree`, and `wechat`. |
+| [`spawn.ts`](./spawn.ts) | The process seam for extensions that run a shell command: `SpawnedProcess`, `SpawnFn`, `KillTreeFn`, the pure `spawnOptions` / `killPlan`, `applyKillPlan` over injected seams, the liveness pair `isPidAlive` / `startTokenOf` (the second settles a pid reused by another process), and the `defaultSpawn` / `defaultKillTree` that execute them (process group on POSIX, `taskkill /T` on Windows). Shared by `job`, `watch`, `check`, `worktree`, `wechat`, and the session roster. |
 | [`goal-state.ts`](./goal-state.ts) | The published `goal` state replayed from the session branch: `PublishedGoal`, `PublishedGoalStatus` (`planning` / `active` / `achieved`), `GOAL_ENTRY_TYPE`, `MAX_GOAL_OBJECTIVE`, `isPursuedGoal(goal)` and `lastGoal(entries)` (the last valid goal, skipping a rejected call and honouring an explicit clear), so `plan` can restate a pursued goal while planning, promote a `planning` one at approval, and offer to record one when a plan is approved with none, and `goal` itself reads the branch through the same replay — with no extension importing another's modules. |
 | [`todo-state.ts`](./todo-state.ts) | The todo item contract, its parser, and the published state replayed from the session branch: `TODO_STATUSES` / `TodoStatus`, `ExistingTodo`, `MAX_TODOS` / `MAX_CONTENT`, `normalizeTodos`, and `lastTodos(entries)` (the last write that fully validates, skipping a rejected call; a malformed write leaves the previous list). `plan` merges steps into that list, `goal` counts the items still open, and `todo` itself replays through it — so one rule decides which writes are state writes, with no extension importing another's modules. |
+| [`stray-fields.ts`](./stray-fields.ts) | The refusal for a tool call that carries a field its action does not act on: `ActionFields` is the per-action table the tool itself keeps, and `strayField(action, args, fields)` is the one sentence — `add does not act on dependsOn: \`edit\` takes it.` — that names every stray field and the action that does take it. Shared by `board` and `team`, whose flat parameter objects both used to drop such a field in silence. |
 | [`tool-names.ts`](./tool-names.ts) | Tool names and one parameter name that more than one extension must agree on, so an orchestrating `ctx.executeTool()` call or schema probe breaks the build on a rename. |
 | [`tool-result.ts`](./tool-result.ts) | The tool-result envelope: `textResult` builds the one text block, the caller's `details`, and the optional `structuredContent` mirror; `failedResult` is the same shape marked `isError`, keeping the previous state for a retry; `toolError` builds the rejected-call content plus the caller's details, and `errorResult` is the action-and-message form `job` and `watch` share. |
 | [`usage.ts`](./usage.ts) | The usage counters an accumulator is measured in: `USAGE_COUNTERS`, `UsageCounter`, `UsageCounts`, and `zeroUsage` — shared by bytefly's session and `↳` roll-up accounting and by `subagent`'s fold of a child's `message_end` events, so two extensions cannot drift on which numbers a run is made of. `turns` and the context size are not counters and stay with each owner. |
-| [`web/`](./web/) | The Bytefly web brand system shared by the browser surfaces, whose conventions are its own doc, [`web/README.md`](./web/README.md). Modules: [`web/tokens.ts`](./web/tokens.ts) (palette derived from the Bytefly terminal themes, scales, the `tok-*` map, and the derived `--on-accent` / `--scrim` / `--shadow` overlays), [`web/base.ts`](./web/base.ts) (reset, one focus ring, the print and forced-colours layers), [`web/components.ts`](./web/components.ts) (the `bf-*` kit, including the dialog, shortcut-sheet, and `bf-kbd` rules), [`web/layout.ts`](./web/layout.ts) (the app shell and its one breakpoint), [`web/runtime.ts`](./web/runtime.ts) (theme storage and bootstrap, `THEME_JS_PATH`, `THEME_TOGGLE_JS`, `dialogScript`, and `keysDialogScript`), [`web/markup.ts`](./web/markup.ts) (the HTML atoms, including `keysSheet` and its `KeyHint` rows), and the [`web/index.ts`](./web/index.ts) barrel. |
+| [`web/`](./web/) | The Bytefly web brand system shared by the browser surfaces, whose conventions are its own doc, [`web/README.md`](./web/README.md). Modules: [`web/tokens.ts`](./web/tokens.ts) (palette derived from the Bytefly terminal themes, scales, the `tok-*` map, and the derived `--on-accent` / `--scrim` / `--shadow` overlays), [`web/base.ts`](./web/base.ts) (reset, one focus ring, the print and forced-colours layers), [`web/components.ts`](./web/components.ts) (the `bf-*` kit, including the dialog, shortcut-sheet, and `bf-kbd` rules), [`web/layout.ts`](./web/layout.ts) (the app shell and its one breakpoint), [`web/client-runtime.ts`](./web/client-runtime.ts) (the browser runtime every page bundle splices in: `el`, `typing`, `paintStatus`, `postJson`, `ClientNode` — the node shape those answer — and `CLIENT_RUNTIME_JS`), [`web/runtime.ts`](./web/runtime.ts) (theme storage and bootstrap, `THEME_JS_PATH`, `THEME_TOGGLE_JS`, `dialogScript`, and `keysDialogScript`), [`web/markup.ts`](./web/markup.ts) (the HTML atoms, including `keysSheet` and its `KeyHint` rows, the mark's one geometry, which `brandLockup` draws and `markIcon` links as the tab icon, and `tabTitle`, the one shape the served pages' tab titles take), [`web/names.ts`](./web/names.ts) (a page's class names as one table: `ClassNames`, the `KEBAB` / `IDENTIFIER` shape a name must have to survive being spliced into a bundle, and `namesScript`), and the [`web/index.ts`](./web/index.ts) barrel. |
 
 ## Conventions