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

package/extensions/rewind/snapshot.ts

@@ -8,7 +8,15 @@
  * touched: all staging happens in a temporary index.
  */
 
-import { commitTree, currentBranch, revParse, treeFromWorkingTree, updateRef, GitError, type RunGit } from "./git.ts";
+import {
+	commitTree,
+	currentBranch,
+	treeFromWorkingTree,
+	updateRef,
+	GitError,
+	revParseMany,
+	type RunGit,
+} from "./git.ts";
 import { encodeMessage, refFor, META_VERSION, type SnapshotMeta } from "./store.ts";
 import type { Snapshot, SnapshotReason } from "./types.ts";
 
@@ -44,11 +52,12 @@ function defaultId(now: number): string {
 /** Point a ref at the current working tree and return the recorded snapshot. */
 export async function createSnapshot(deps: SnapshotDeps, input: SnapshotInput): Promise<Snapshot> {
 	const { runGit } = deps;
-	const head = await revParse(runGit, input.root, "HEAD");
-	if (!head) throw new GitError("the repository has no commits to snapshot.", 1);
+	// One `rev-parse` for both ids: the snapshot needs HEAD to parent the commit
+	// and HEAD's tree to know whether the working tree is clean.
+	const [head, headTree] = await revParseMany(runGit, input.root, ["HEAD", "HEAD^{tree}"]);
+	if (!head || !headTree) throw new GitError("the repository has no commits to snapshot.", 1);
 
 	const tree = await treeFromWorkingTree(runGit, input.root, input.indexFile, input.includeUntracked);
-	const headTree = await revParse(runGit, input.root, "HEAD^{tree}");
 	const clean = tree === headTree;
 
 	const now = deps.now?.() ?? Date.now();

package/extensions/subagent/background-tui.ts

@@ -161,7 +161,7 @@ export class AgentsBoardComponent extends DockListScreen<BackgroundRun> {
 	}
 
 	protected listHints(): ScreenHint[] {
-		const focused = this.focused;
+		const focused = this.focusedRow;
 		const hints: ScreenHint[] = ["Esc close", { text: "Enter detail", color: "accent" }];
 		if (focused && canCollect(focused)) hints.push({ text: "c collect", color: "accent" });
 		if (focused?.status === "running") hints.push({ text: "x cancel", color: "warning" });

package/extensions/subagent/background.ts

@@ -9,7 +9,7 @@
  */
 
 import { resolve } from "node:path";
-import { formatDuration, sanitizeLine, stripControlChars } from "../../lib/format.ts";
+import { sanitizeLine, stripControlChars } from "../../lib/format.ts";
 import type { AgentConfig } from "./agents.ts";
 import { formatUsageStats } from "./format.ts";
 import type { RunOptions } from "./run.ts";
@@ -458,12 +458,6 @@ export function createBackgroundRuntime(deps: BackgroundDeps): BackgroundRuntime
 	return { start, list, collect, cancel, shutdown, reset, subscribe };
 }
 
-/** A human duration for a run; kept here so the board and collect agree. */
-export function backgroundDuration(run: BackgroundRun, now = Date.now()): string {
-	const end = run.finishedAt ?? now;
-	return formatDuration(Math.max(0, end - run.startedAt));
-}
-
 /** Whether a run can be collected. */
 export function canCollect(run: BackgroundRun): boolean {
 	return run.status !== "running" && run.status !== "interrupted";

package/extensions/todo/tools.ts

@@ -12,12 +12,11 @@
 
 import type { JsonValue } from "@earendil-works/pi-ai";
 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 { callLine, detailsOrLine, rejectionLine } from "../../lib/tui/tool.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";
@@ -98,24 +97,21 @@ export function registerTools(pi: ExtensionAPI, runtime: TodoRuntime): void {
 		},
 
 		renderCall(args, theme, context) {
-			const text = reuseCallText(context.lastComponent);
-			text.setText(
-				toolCallTitle(theme, `${TOOL_NAME} `) +
-					paint(theme, "meta", formatCallText(args.todos as Todo[] | undefined, context.argsComplete)),
-			);
-			return text;
+			const body = formatCallText(args.todos as Todo[] | undefined, context.argsComplete);
+			return callLine(theme, context.lastComponent, TOOL_NAME, body);
 		},
 
 		renderResult(result, { expanded }, theme, context) {
 			const text = reuseText(context.lastComponent);
-			const details = toolDetails<TodoDetails>(result.details);
-			if (details?.error) {
-				text.setText(paint(theme, "bad", `Error: ${sanitizeLine(details.error)}`));
+			const outcome = detailsOrLine(theme, result, expanded, toolDetails<TodoDetails>(result.details));
+			if ("line" in outcome) {
+				text.setText(outcome.line);
 				return text;
 			}
-			// A call rejected before `execute` (argument validation or a permission
-			// block) carries `details: {}` with no list, so fall back to its message.
-			if (!details || !Array.isArray(details.todos)) {
+			const details = outcome.details;
+			// A details block can still arrive without the list: the host rejected the
+			// arguments, so its message is the whole result.
+			if (!Array.isArray(details.todos)) {
 				text.setText(rejectionLine(theme, result, expanded));
 				return text;
 			}

package/extensions/watch/README.md

@@ -236,8 +236,8 @@ outlive the session.
 
 ## Testing
 
-Pure-module tests cover `config`, `schema`, `format`, and `tui`; `runtime.test.ts`
-drives the tailer with a fake clock and fake children; `tools.test.ts`,
-`commands.test.ts`, and `extension.test.ts` exercise the tool, command, and
-lifecycle through the shared `createFakePi`/`fakeCtx` doubles. The test harness
-is `test/helpers/fixtures/watch.ts`.
+`runtime.test.ts` covers config, schema, the child supervisor, and the tailer
+with a fake clock and fake children; `tools.test.ts` covers the tool and command;
+`ui.test.ts` covers registration, formatting, the status chips, and the screen
+through the shared `createFakePi`/`fakeCtx` doubles. The test harness is
+`test/helpers/fixtures/watch.ts`.

package/extensions/watch/commands.ts

@@ -8,7 +8,7 @@
  */
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { withRailsSuppressed } from "../../lib/rails.ts";
+import { withPolledScreen } from "../../lib/screen-session.ts";
 import { formatWatchList, shortLabel } from "./format.ts";
 import type { WatchRuntime } from "./runtime.ts";
 import { WatchListComponent } from "./tui.ts";
@@ -92,54 +92,40 @@ export function registerCommands(pi: ExtensionAPI, runtime: WatchRuntime): void
 				return;
 			}
 
-			let timer: ReturnType<typeof setInterval> | undefined;
-			const stopTimer = (): void => {
-				if (timer) clearInterval(timer);
-				timer = undefined;
-			};
-
-			// The dock screen owns the editor slot; hide the rails for its lifetime.
-			try {
-				await withRailsSuppressed(pi, () =>
-					ctx.ui.custom<void>((tui, theme, _keybindings, done) => {
-						const component = new WatchListComponent(
-							() => runtime.list(),
-							theme,
-							{
-								lines: (watchId) => runtime.matches(watchId, 500),
-								stop: (watchId) => {
-									runtime.stop(watchId);
-								},
-								clear: () => {
-									const result = runtime.clear(undefined, false);
-									if (result.cleared > 0) {
-										ctx.ui.notify(`Cleared ${result.cleared} watcher${result.cleared === 1 ? "" : "s"}.`, "info");
-									}
-								},
+			await withPolledScreen(
+				pi,
+				ctx,
+				(screen) =>
+					new WatchListComponent(
+						() => runtime.list(),
+						screen.theme,
+						{
+							lines: (watchId) => runtime.matches(watchId, 500),
+							stop: (watchId) => {
+								runtime.stop(watchId);
 							},
-							() => {
-								stopTimer();
-								done();
+							clear: () => {
+								const result = runtime.clear(undefined, false);
+								if (result.cleared > 0) {
+									ctx.ui.notify(`Cleared ${result.cleared} watcher${result.cleared === 1 ? "" : "s"}.`, "info");
+								}
 							},
-							() => tui.requestRender(),
-							() => tui.terminal?.rows,
-						);
-
-						// The runtime's own clock owns file polling; this only refreshes
-						// what the screen shows, so opening it cannot change the poll cadence.
-						timer = setInterval(() => {
-							const open = component.currentLineId();
-							if (open) component.refreshLines(open);
-							tui.requestRender();
-						}, REFRESH_MS);
-						timer.unref?.();
-
-						return component;
-					}),
-				);
-			} finally {
-				stopTimer();
-			}
+						},
+						screen.close,
+						screen.requestRender,
+						screen.viewportRows,
+					),
+				{
+					pollMs: REFRESH_MS,
+					// The runtime's own clock owns file polling; this only refreshes what
+					// the screen shows, so opening it cannot change the poll cadence.
+					poll: (component, handles) => {
+						const open = component.currentLineId();
+						if (open) component.refreshLines(open);
+						handles.requestRender();
+					},
+				},
+			);
 		},
 	});
 }

package/extensions/watch/runtime.ts

@@ -17,6 +17,7 @@ import type { KillTreeFn, SpawnFn, SpawnedProcess } from "../../lib/spawn.ts";
 import { createChildSupervisor } from "./child.ts";
 import { DEFAULT_CONFIG, loadConfig, type WatchConfig } from "./config.ts";
 import { sanitizeUntrustedLine } from "../../lib/format.ts";
+import { defaultInterval } from "../../lib/timer.ts";
 import { compileRegex, sourceLabel } from "./format.ts";
 import { createUiController, type UiController } from "./ui.ts";
 import type { PendingMatch, WatchMatch, WatchRecord, WatchSource } from "./types.ts";
@@ -118,7 +119,7 @@ export function createWatchRuntime(options: WatchRuntimeOptions = {}): WatchRunt
 	const watches = new Map<string, Internal>();
 	let counter = 0;
 	let disposed = false;
-	let clock: ReturnType<typeof setInterval> | undefined;
+	let clock: (() => void) | undefined;
 	let onMatchHandler: ((matches: PendingMatch[]) => void) | undefined;
 
 	const record = (w: Internal): WatchRecord => ({
@@ -163,16 +164,13 @@ export function createWatchRuntime(options: WatchRuntimeOptions = {}): WatchRunt
 	});
 
 	const stopClock = (): void => {
-		if (clock) {
-			clearInterval(clock);
-			clock = undefined;
-		}
+		clock?.();
+		clock = undefined;
 	};
 
 	const ensureClock = (): void => {
 		if (disposed || !autoClock || clock) return;
-		clock = setInterval(() => tick(), config.pollMs);
-		clock.unref?.();
+		clock = defaultInterval(config.pollMs, () => tick());
 	};
 
 	const pendingMatches = (): PendingMatch[] => {

package/extensions/watch/tools.ts

@@ -11,7 +11,7 @@ import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-a
 import { sanitizeLine } from "../../lib/format.ts";
 import { errorResult } from "../../lib/tool-result.ts";
 import { reuseText, toolDetails } from "../../lib/tui/chrome.ts";
-import { rejectionLine, reuseCallText, toolCallTitle } from "../../lib/tui/tool.ts";
+import { callLine, detailsOrLine, rejectionLine } from "../../lib/tui/tool.ts";
 import { SEPARATORS } from "../../lib/tui/glyphs.ts";
 import { paint } from "../../lib/tui/tokens.ts";
 import {
@@ -182,29 +182,18 @@ export function registerTools(pi: ExtensionAPI, runtime: WatchRuntime): void {
 
 		renderCall(args, theme, context) {
 			const action = typeof args.action === "string" ? args.action : "watch";
-			const text = reuseCallText(context.lastComponent, "", "middle");
-			text.setText(
-				toolCallTitle(theme, `${TOOL_NAME} `) +
-					paint(
-						theme,
-						"meta",
-						sanitizeLine(formatCallText(action, args as Record<string, unknown>, context.argsComplete)),
-					),
-			);
-			return text;
+			const subject = formatCallText(action, args as Record<string, unknown>, context.argsComplete);
+			return callLine(theme, context.lastComponent, TOOL_NAME, subject, "middle");
 		},
 
 		renderResult(result, options, theme, context) {
 			const text = reuseText(context.lastComponent);
-			const details = toolDetails<WatchDetails>(result.details);
-			if (!details) {
-				text.setText(rejectionLine(theme, result, options.expanded));
-				return text;
-			}
-			if (details.error) {
-				text.setText(paint(theme, "bad", `Error: ${sanitizeLine(details.error)}`));
+			const outcome = detailsOrLine(theme, result, options.expanded, toolDetails<WatchDetails>(result.details));
+			if ("line" in outcome) {
+				text.setText(outcome.line);
 				return text;
 			}
+			const details = outcome.details;
 
 			if (details.action === "list" && details.watches) {
 				if (details.watches.length === 0) {

package/extensions/web-access/README.md

@@ -378,9 +378,9 @@ the content type and size.
 
 ## Testing
 
-`extensions/web-access/` mirrors the halves (`search/`, `fetch/`) plus top-level
-`config.test.ts` and `index.test.ts`. It covers the shared runner (via injected
-`fetch`), the provider registry and resolution, each provider's URL builder and
+`extensions/web-access/` mirrors the halves (`search/`, `fetch/`) plus the
+`http.test.ts` suite for the shared runner, charset, config, and registration.
+It covers the injected `fetch` runner, the provider registry and resolution, each provider's URL builder and
 parser (DuckDuckGo, SearXNG, Brave), the orchestration pipeline and throttle,
 charset decoding (declared, `<meta>`, and BOM precedence), a streamed body over
 the byte cap, redirect re-validation (per-hop SSRF with literal IPs),

package/extensions/web-access/search/search.ts

@@ -8,6 +8,7 @@
  */
 
 import { messageOf } from "../../../lib/errors.ts";
+import { abortableSleep } from "../../../lib/timer.ts";
 import { createFetchRunner, type HttpRunner } from "../http.ts";
 import { resolveSearchApiKey, type WebSearchConfig } from "./config.ts";
 import { resolveProvider } from "./registry.ts";
@@ -40,24 +41,14 @@ export interface SearchDeps {
 /** A sleeper, injectable so throttle scheduling is testable without wall time. */
 type ThrottleSleep = (ms: number, signal?: AbortSignal) => Promise<void>;
 
-function delay(ms: number, signal: AbortSignal | undefined): Promise<void> {
-	return new Promise((resolve, reject) => {
-		const finish = () => {
-			clearTimeout(timer);
-			signal?.removeEventListener("abort", onAbort);
-		};
-		const onAbort = () => {
-			finish();
-			reject(new WebSearchError("Search aborted."));
-		};
-		const timer = setTimeout(() => {
-			finish();
-			resolve();
-		}, ms);
-		if (signal?.aborted) return onAbort();
-		signal?.addEventListener("abort", onAbort, { once: true });
-	});
-}
+/** The shared abortable sleep, mapped to the one error this extension throws. */
+const delay: ThrottleSleep = async (ms, signal) => {
+	try {
+		await abortableSleep(ms, signal);
+	} catch {
+		throw new WebSearchError("Search aborted.");
+	}
+};
 
 /**
  * A stateful throttle that spaces requests by `minIntervalMs`. `now` and `sleep`

package/extensions/wechat/timer.ts

@@ -3,20 +3,18 @@
  *
  * The bridge and the channel need a cancellable one-shot timer that a test can
  * drive without waiting (the delayed acknowledgement, the typing keep-alive, the
- * prompt timeout); login needs an abortable sleep between polls. The defaults use
- * a real `setTimeout`, `unref`'d for the one-shot so a pending timer never holds
- * the process open.
+ * prompt timeout), and login needs an abortable sleep between polls; both seams
+ * and their production defaults are in [`lib/timer.ts`](../../lib/timer.ts),
+ * because job, watch, file-browse, plan, and web-access arm the same two. This
+ * module adds the per-key map those timers are held in.
  */
 
-/** Arm a one-shot timer; the returned function cancels it. */
-export type ArmTimer = (ms: number, fn: () => void) => () => void;
+import { abortableSleep, type ArmTimer } from "../../lib/timer.ts";
 
-/** The production timer: `setTimeout`, detached from the event loop. */
-export const defaultTimer: ArmTimer = (ms, fn) => {
-	const timer = setTimeout(fn, ms);
-	(timer as { unref?: () => void }).unref?.();
-	return () => clearTimeout(timer);
-};
+export { type ArmTimer, defaultTimer } from "../../lib/timer.ts";
+
+/** The shared abortable sleep, under the name the bridge and login already use. */
+export const defaultSleep = abortableSleep;
 
 /**
  * A set of one-shot timers keyed by a caller's id (a peer, a watcher).
@@ -74,22 +72,3 @@ export function createTimerMap(arm: ArmTimer): TimerMap {
 	};
 	return map;
 }
-
-/** An abortable sleep: resolves after `ms`, rejects when `signal` aborts. */
-export function defaultSleep(ms: number, signal?: AbortSignal): Promise<void> {
-	return new Promise((resolve, reject) => {
-		if (signal?.aborted) {
-			reject(new Error("aborted"));
-			return;
-		}
-		const timer = setTimeout(() => {
-			signal?.removeEventListener("abort", onAbort);
-			resolve();
-		}, ms);
-		const onAbort = () => {
-			clearTimeout(timer);
-			reject(new Error("aborted"));
-		};
-		signal?.addEventListener("abort", onAbort, { once: true });
-	});
-}

package/extensions/wechat/tools.ts

@@ -10,9 +10,8 @@
 import type { JsonValue } from "@earendil-works/pi-ai";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type, type Static } from "typebox";
-import { sanitizeLine } from "../../lib/format.ts";
 import { reuseText, toolDetails } from "../../lib/tui/chrome.ts";
-import { rejectionLine, reuseCallText, toolCallTitle } from "../../lib/tui/tool.ts";
+import { callLine, errorLine, rejectionLine } from "../../lib/tui/tool.ts";
 import { paint } from "../../lib/tui/tokens.ts";
 import type { Bridge } from "./bridge.ts";
 
@@ -82,11 +81,9 @@ export function registerTools(pi: ExtensionAPI, deps: ToolDeps): void {
 		},
 
 		renderCall(args, theme, context) {
-			const text = reuseCallText(context.lastComponent);
 			const body = (args as { text?: unknown }).text;
-			const label = context.argsComplete && typeof body === "string" ? sanitizeLine(body) : "…";
-			text.setText(toolCallTitle(theme, `${TOOL_NAME} `) + paint(theme, "meta", label));
-			return text;
+			const label = context.argsComplete && typeof body === "string" ? body : "…";
+			return callLine(theme, context.lastComponent, TOOL_NAME, label);
 		},
 
 		renderResult(result, options, theme, context) {
@@ -97,7 +94,7 @@ export function registerTools(pi: ExtensionAPI, deps: ToolDeps): void {
 				return text;
 			}
 			if (details?.error) {
-				text.setText(paint(theme, "bad", `Error: ${sanitizeLine(details.error)}`));
+				text.setText(errorLine(theme, details.error));
 				return text;
 			}
 			// Pi's rejection result carries `{}`; show its sanitized message.

package/extensions/worktree/status.ts

@@ -6,9 +6,10 @@
 import { basename } from "node:path";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { realPathOfNearest } from "../../lib/path.ts";
+import { mapConcurrent } from "../../lib/pool.ts";
 import { loadConfig } from "./config.ts";
 import { gapLines, isolationGaps } from "./gaps.ts";
-import { type CheckoutCheck, defaultBranch, listManagedWorktrees, repoRoot } from "./git.ts";
+import { type CheckoutCheck, 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";
@@ -115,15 +116,19 @@ export async function worktreeStatus(pi: ExtensionAPI, ctx: ExtensionContext): P
 		const { registry } = reconcileRegistry(root, config, managed, { persist: false });
 		const baseBranch = await defaultBranch(pi, root);
 		const baseRef = baseBranch ? `origin/${baseBranch}` : undefined;
-		lines.push("", `Managed worktrees (${managed.length}):`);
-		for (const entry of managed) {
-			const record = registry.worktrees.find((candidate) => candidate.path === realPathOfNearest(entry.path));
-			const status = await statusOf(pi, entry, { baseRef, record });
+		// Keyed by the canonical path the registry stores, so a row's record is one
+		// lookup instead of a scan of every record.
+		const records = new Map(registry.worktrees.map((record) => [record.path, record]));
+		const row = async (entry: ManagedWorktree): Promise<string> => {
+			const path = realPathOfNearest(entry.path);
+			const status = await statusOf(pi, entry, { baseRef, record: records.get(path) });
 			const marks = statusMarks(status, current?.path === entry.path);
-			lines.push(
-				`  ${entry.path}  ${entry.branch ?? ""}${marks.length > 0 ? `  [${marks.join(", ")}]` : ""}`.trimEnd(),
-			);
-		}
+			return `  ${entry.path}  ${entry.branch ?? ""}${marks.length > 0 ? `  [${marks.join(", ")}]` : ""}`.trimEnd();
+		};
+		// Each row is up to four git reads; four at a time keeps the list in the order
+		// git reports while overlapping the waits. `statusOf` passes no `env`, which is
+		// what makes concurrent git calls safe here (see `RunGitOptions.env`).
+		lines.push("", `Managed worktrees (${managed.length}):`, ...(await mapConcurrent(managed, 4, row)));
 	}
 	return lines.join("\n");
 }

package/lib/README.md

@@ -20,25 +20,28 @@ belongs in that extension instead — see `extensions/web-access/http.ts` and
 | [`browser.ts`](./browser.ts) | Cross-platform default-browser opener shared by `file-browse` and `plan`: pure `browserCommand(url, platform)` plus best-effort `openInBrowser(url, { platform, spawn })` with an injectable spawn. |
 | [`config.ts`](./config.ts) | Config loading, two ways: `loadConfigFile` for a whole file, and the shared `bytefly.json` (`SHARED_CONFIG_FILE`) via `configSection` / `configValueAt` / `loadConfigSection` (global, then project), plus the atomic `writeConfigFile` / `writeConfigSection` / `writeConfigValue` / `writeConfigValueAt` / `writeConfigValuesAt` / `unsetConfigValueAt` (the leaf writers preserve siblings and metadata, `writeConfigValuesAt` applies several leaves in one document pass, and the last removes one and prunes what it emptied). Includes `clampInteger` / `clampNumber` / `cleanString` / `optionalString` / `asBoolean` / `stringList` / `asRecord` / `readJson` / `readJsonResult`. |
 | [`env.ts`](./env.ts) | Env-var contracts shared across extensions: the worktree environment (`ENV_ROOT`, `worktreeRoot`, `resolveEffectiveCwd`) used by worktree, file-browse, job, and rewind, plus `isExtensionEnabled` / `ENV_DISABLED_EXTENSIONS` for the package-wide disable list. |
-| [`escape.ts`](./escape.ts) | `escapeHtml`: the single HTML text/attribute escape used by the browse page renderers and the Markdown and syntax highlighters. |
+| [`escape.ts`](./escape.ts) | `escapeHtml`: the single HTML text/attribute escape used by the browse page renderers and the Markdown and syntax highlighters, plus `decodeCodePoint`, the other half of the same boundary — one numeric character reference as text, with a surrogate or out-of-range value decoded to U+FFFD. |
 | [`events.ts`](./events.ts) | Inter-extension `pi.events` channels and payloads: `JOB_FINISHED_CHANNEL` / `JobFinishedEvent` (published by `job`, consumed by bytefly's notify capability), `SUBAGENT_FINISHED_CHANNEL` / `SubagentFinishedEvent` (published by `subagent`, consumed by bytefly's footer roll-up), and `WEB_SEARCH_PROVIDER_CHANNEL` / `WebSearchProviderEvent` (published by `web-access` at session start, consumed by bytefly's doctor so it can report the resolved provider without importing the extension — the key itself is never in the payload). |
 | [`notice.ts`](./notice.ts) | The shared transcript notice: `NOTICE_TYPE`, the `NoticeDetails` / `NoticeItem` shape, `noticeMessage` (the `display: true` message both send paths accept), `isNotice`, and `pruneStaleNotices` — posted by `job` and `watch`, rendered by bytefly. |
 | [`report.ts`](./report.ts) | The pending-report coordinator: `createPendingReporter` with `wake` / `pending` / `markReported` / `buildNotice` / `source` / `onWoke`, returning the lifecycle handlers that report at the next turn, raise at most one triggered turn per wake window, and prune only their own notices. Shared by `job` and `watch`. |
 | [`errors.ts`](./errors.ts) | `messageOf`: the one boundary that turns an unknown thrown value into a user-facing line (an `Error` yields its message, anything else is stringified). |
 | [`format.ts`](./format.ts) | Pure text/number formatting shared by renderers: `formatTokens`, `formatCount`, `formatDuration` (`450ms`, `3.2s`, `1m05s`, `2h03m`), `boundedTail` (the end of a joined tail with a `truncated` flag), `stripControlChars`, `sanitize`, `sanitizeLine` — the boundary for untrusted, single-line text — `lineOf` (a value read as one sanitized line), `sanitizeUntrustedLine` / `sanitizeUntrustedText` with `MAX_OUTPUT_LINE` for **program output** (OSC/CSI escapes removed whole, `\r` progress resolved, clipped), and `shortenPath`. |
+| [`timer.ts`](./timer.ts) | The three timer seams and their production defaults, each cancellable and each built so a pending timer never holds the process open: `ArmTimer` / `defaultTimer` (one shot), `RepeatTimer` / `defaultInterval` (repeating), and `abortableSleep` (resolve after a delay, reject `Error("aborted")` when a signal wins). Shared by `wechat`'s bridge and prompt channel, plan's review page, `job`'s and `watch`'s repaint clocks, `bytefly`'s working tick, the browse live channel, and the search throttle — so a test drives a deadline instead of waiting on one. |
 | [`lines.ts`](./lines.ts) | `LineSplitter`, the byte-safe splitter for a stream of program output: buffers bytes and decodes only at a newline, so a UTF-8 character split across two reads survives, and caps an over-long line instead of dropping it. Shared by `job`, `watch`, `check`, and `subagent`. |
+| [`pool.ts`](./pool.ts) | `mapConcurrent`: one async read per entry with at most `limit` calls in flight and results in input order, so a directory listing or a status sweep fans out without an unbounded burst or a per-entry round trip. Shared by `file-browse` and `worktree`. |
 | [`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`), and `remoteChannel` / `isRemoteTurn` / `supportsCustomUI` / `askHuman` (with an optional file, fallback text, and digest preface) 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`, `hasCommits`, `currentBranch`); [`git/index.ts`](./git/index.ts) is the barrel. |
+| [`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` and `plan`: [`http/headers.ts`](./http/headers.ts) (the page policy `PAGE_CSP` and the `pageHeaders` / `scriptHeaders` / `jsonHeaders` sets), [`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/server.ts`](./http/server.ts) (`bindLoopback` on `127.0.0.1` with the accept-error listener, `respond` for HEAD / streamed file / body, and the idempotent `createCloser`), 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) (`screenHint`, `dockListFrame` (the docked-list frame) with `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`, `statusRow`, `checkbox`, `chip`, `keyValueRow`, `emptyState`, `byRunningFirst` for a live list's order), [`tui/columns.ts`](./tui/columns.ts) (`splitRow`, `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`, 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). |
+| [`http/`](./http/) | The loopback HTTP layer shared by `file-browse` and `plan`: [`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/server.ts`](./http/server.ts) (`bindLoopback` on `127.0.0.1` with the accept-error listener, `respond` for HEAD / streamed file / body, `openEventStream` for the head and reconnect hint of an SSE response, and the idempotent `createCloser`), 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) (`screenHint`, `dockListFrame` (the docked-list frame) with `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 `document`: `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. |
+| [`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. |
 | [`pi-invocation.ts`](./pi-invocation.ts) | `getPiInvocation`: how to launch a nested `pi` process, shared by `subagent` and bytefly's doctor surface. |
 | [`policy.ts`](./policy.ts) | `createReadOnlyPolicy`: default-deny tool classification from `readOnlyHint` + explicit allow/deny. |
 | [`plan-state.ts`](./plan-state.ts) | The plan-mode flag replayed from the session branch: `PLAN_MODE_ENTRY_TYPE` and `isPlanModeEnabled(entries)`, so `rewind` can refuse a write while planning without importing the plan extension. |
 | [`plan-entry.ts`](./plan-entry.ts) | Plan-mode entry shared by the extension that owns the mode and the one that offers it: `READ_ONLY_SUMMARY` and `PLAN_CONSENT` (one wording for the read-only guarantee), the `PLAN_ENTER_REQUEST` channel with its `PlanEnterRequest` payload, and `requestPlanMode(pi, ctx)` — a request/response over `pi.events` that resolves `false` instead of hanging when `plan` is not loaded, so a command context (which has no `executeTool`) can still enter the mode after asking the user once. |
 | [`rails.ts`](./rails.ts) | Above-editor widget ordering (`goal` → `todo`) and dock-screen suppression, carried on `pi.events`. |
+| [`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. |
 | [`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`. |
@@ -61,9 +64,10 @@ belongs in that extension instead — see `extensions/web-access/http.ts` and
   one extension probes on another — live in `tool-names.ts`.
 - **A helper that exists here must be imported, not redefined.**
   `test/shared-helpers.test.ts` fails a top-level extension declaration whose
-  name is also exported by `lib/`, and a body copied from `lib/` or from another
-  extension. A deliberate wrapper goes on that test's reasoned exception list; a
-  copy belongs here with one co-located test.
+  name is also exported by `lib/`, and a body copied from `lib/` or from any
+  other file — a second extension, a sibling module, or `lib/` itself. A
+  deliberate wrapper goes on that test's reasoned exception list; a copy belongs
+  here with its declared capability suite.
 - **A color is a role, not a token.** The rules and the primitives are in
   [`tui/README.md`](./tui/README.md#color-is-a-role): draw through
   [`tui/tokens.ts`](./tui/tokens.ts) (`paint(theme, role, text)`) so a theme swap

package/lib/escape.ts

@@ -1,11 +1,14 @@
 /**
- * HTML text escaping for the browse pages.
+ * HTML text escaping, and the inverse for one character reference.
  *
  * The single escape used by every page renderer and by the Markdown renderer:
  * model- and file-authored text becomes safe text nodes and double-quoted
  * attributes. Keeping it here (rather than in `html.ts`) lets `markdown.ts`
  * escape without importing the page renderer, so the module graph stays
- * acyclic.
+ * acyclic. `decodeCodePoint` is the other half of the same boundary and lives
+ * beside it for the same reason: the Markdown inline scan and the raw-HTML
+ * attribute decoder both resolve `&#N;` and `&#xN;` references, and one copy
+ * cannot drift from the other.
  */
 
 /** Escape text for an HTML text node or double-quoted attribute. */
@@ -25,3 +28,13 @@ export function escapeHtml(value: string): string {
 		}
 	});
 }
+
+/**
+ * One numeric character reference as text: U+FFFD when it is a surrogate, zero,
+ * or out of range, so an entity cannot inject an unpaired half of a pair.
+ */
+export function decodeCodePoint(value: number): string {
+	if (!Number.isFinite(value) || value <= 0 || value > 0x10ffff || (value >= 0xd800 && value <= 0xdfff))
+		return "\uFFFD";
+	return String.fromCodePoint(value);
+}

package/lib/git/read.ts

@@ -70,6 +70,26 @@ export async function revParse(runGit: RunGit, cwd: string, rev: string): Promis
 	return id || undefined;
 }
 
+/**
+ * Resolve several revisions in one `git rev-parse`, in the order given.
+ *
+ * A snapshot needs `HEAD` and its tree, and two calls pay two spawns for one
+ * answer; `rev-parse` prints one line per argument, so one call is enough. A
+ * revision that does not resolve is not a shorter list — it is no answer, since
+ * the caller's indices would shift — so the result is `[]` unless every one
+ * resolved.
+ */
+export async function revParseMany(runGit: RunGit, cwd: string, revs: readonly string[]): Promise<string[]> {
+	if (revs.length === 0) return [];
+	const result = await runGit(["rev-parse", ...revs], { cwd });
+	if (result.code !== 0) return [];
+	const ids = result.stdout
+		.split("\n")
+		.map((line) => line.trim())
+		.filter((line) => line !== "");
+	return ids.length === revs.length ? ids : [];
+}
+
 /** Whether the repository has at least one commit. */
 export async function hasCommits(runGit: RunGit, cwd: string): Promise<boolean> {
 	return (await revParse(runGit, cwd, "HEAD")) !== undefined;