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

package/extensions/worktree/screen.ts

@@ -0,0 +1,263 @@
+/**
+ * The `/worktree` list screen: one row per managed worktree, the active one
+ * marked, with a detail pane and three verbs.
+ *
+ * The frame, navigation, y/N confirmation, and pane come from the shared
+ * `DockListScreen`, so this module owns only the worktree vocabulary. Rows come
+ * from the same `worktreeSnapshot` the text status renders, so the screen and the
+ * `list_worktrees` tool cannot disagree about a worktree.
+ *
+ * Every verb but `p` closes the screen and hands the action back to the command:
+ * entering and exiting change the session binding and `exitWorktree` asks through
+ * `ctx.ui.select`, which cannot nest inside a mount. `p` never prompts, so it
+ * runs in place and refreshes the rows.
+ */
+
+import { basename } from "node:path";
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { messageOf } from "../../lib/errors.ts";
+import type { ScreenHint, ViewportRowsSource } from "../../lib/tui/chrome.ts";
+import { DockListScreen, type DetailContents } from "../../lib/tui/dock-screen.ts";
+import { GLYPHS } from "../../lib/tui/glyphs.ts";
+import { statusRow } from "../../lib/tui/rows.ts";
+import { paint, type TuiRole } from "../../lib/tui/tokens.ts";
+import { gapLines } from "./gaps.ts";
+import { handoffLines } from "./handoff.ts";
+import type { CheckoutStatus } from "./registry.ts";
+import { relativeDay, statusMarks, type WorktreeSnapshot, worktreeLabel } from "./status.ts";
+
+/** What a verb asks the command to do once the screen is gone. */
+export type WorktreeAction = { kind: "enter"; name: string } | { kind: "exit" };
+
+/** One row: a managed worktree, or the active one when this session does not manage it. */
+export interface WorktreeRow {
+	/** Canonical path, and the row's stable id. */
+	path: string;
+	/** Basename of the path: the name `enter` takes back. */
+	name: string;
+	branch: string | undefined;
+	/** Whether this row is the session's active worktree. */
+	current: boolean;
+	/** What git says about it; absent for a worktree entered by path. */
+	status: CheckoutStatus | undefined;
+}
+
+/** The rows for a snapshot, in git's order, with the active worktree always present. */
+export function worktreeRows(snapshot: WorktreeSnapshot): WorktreeRow[] {
+	const rows: WorktreeRow[] = snapshot.managed.map((item) => ({
+		path: item.entry.path,
+		name: basename(item.entry.path),
+		branch: item.entry.branch,
+		current: snapshot.active?.path === item.entry.path,
+		status: item.status,
+	}));
+	const active = snapshot.active;
+	// A worktree entered by path is not in the managed list, but a reader looking
+	// for "where am I" must still see it.
+	if (active && !rows.some((row) => row.path === active.path)) {
+		rows.unshift({
+			path: active.path,
+			name: worktreeLabel(active),
+			branch: active.branch,
+			current: true,
+			status: undefined,
+		});
+	}
+	return rows;
+}
+
+/** The glyph and its role: a missing checkout is the error, dirty work the warning. */
+function rowGlyph(status: CheckoutStatus | undefined): { char: string; role: TuiRole } {
+	if (!status) return { char: GLYPHS.worktree, role: "info" };
+	if (status.state === "missing") return { char: GLYPHS.cross, role: "bad" };
+	if (status.state === "dirty") return { char: GLYPHS.warn, role: "warn" };
+	if (status.merged) return { char: GLYPHS.check, role: "ok" };
+	return { char: GLYPHS.branch, role: "info" };
+}
+
+/** The row's right-hand text: its marks, or `clean` when it has none. */
+function rowMarks(row: WorktreeRow): string {
+	const marks = row.status ? statusMarks(row.status, row.current) : ["current"];
+	if (marks.length === 0) marks.push("clean");
+	return marks.join("  ");
+}
+
+export interface WorktreeScreenOptions {
+	/** The rows to open with; the command has already read them. */
+	snapshot: WorktreeSnapshot;
+	theme: Theme;
+	requestRender(): void;
+	/** Close the screen; `undefined` when the user only closed it. */
+	onDone(action: WorktreeAction | undefined): void;
+	/** Read the rows again after a verb changed them. */
+	reload(): Promise<WorktreeSnapshot>;
+	/** Run a prune in place and return its report. */
+	prune(): Promise<string>;
+	/** Plan mode: the screen still shows the list, but no verb may change it. */
+	readOnly: boolean;
+	viewportRowsSource?: ViewportRowsSource;
+}
+
+/** The `/worktree` screen. */
+export class WorktreeListComponent extends DockListScreen<WorktreeRow> {
+	private view: WorktreeSnapshot;
+	private pruning = false;
+
+	constructor(private readonly deps: WorktreeScreenOptions) {
+		super({
+			theme: deps.theme,
+			title: "Worktrees",
+			detailTitle: "Worktree",
+			emptyList: "No managed worktrees. /worktree enter <name> creates one.",
+			emptyDetail: "Nothing recorded for this worktree.",
+			requestRender: deps.requestRender,
+			onClose: () => deps.onDone(undefined),
+			viewportRowsSource: deps.viewportRowsSource,
+		});
+		this.view = deps.snapshot;
+	}
+
+	protected rows(): readonly WorktreeRow[] {
+		return worktreeRows(this.view);
+	}
+
+	protected idOf(row: WorktreeRow): string {
+		return row.path;
+	}
+
+	protected rowLine(row: WorktreeRow, width: number, selected: boolean): string {
+		const glyph = rowGlyph(row.status);
+		return statusRow(this.theme, width, {
+			selected,
+			glyph: glyph.char,
+			glyphRole: glyph.role,
+			label: row.name,
+			labelRole: selected ? "accent" : "label",
+			trailing: rowMarks(row),
+			trailingRole: row.current ? "accent" : "faint",
+		});
+	}
+
+	protected detailBlock(row: WorktreeRow): string[] {
+		const lines = [`${row.path}  ${row.branch ?? "(detached)"}`];
+		const active = this.view.active;
+		// The gaps are the same rules `/worktree` status and `doctor` report: a gap
+		// the user cannot see is a gap they cannot weigh.
+		if (row.current && active) {
+			lines.push(`base: ${active.baseRef} (${active.baseRefMode})    main: ${active.repoRoot}`);
+			if (this.view.gaps.length > 0) lines.push("Not isolated:", ...gapLines(this.view.gaps));
+		}
+		return lines;
+	}
+
+	protected summaryCells(rows: readonly WorktreeRow[]): string[] {
+		const cells = [paint(this.theme, "meta", `${rows.length} worktree${rows.length === 1 ? "" : "s"}`)];
+		const dirty = rows.filter((row) => row.status?.state === "dirty").length;
+		if (dirty > 0) cells.push(paint(this.theme, "warn", `${dirty} dirty`));
+		const ahead = rows.filter((row) => (row.status?.ahead ?? 0) > 0).length;
+		if (ahead > 0) cells.push(paint(this.theme, "accent", `${ahead} ahead`));
+		const inactive = this.view.inactiveOverrides;
+		if (inactive.length > 0) cells.push(paint(this.theme, "warn", `not isolated: ${inactive.join(", ")}`));
+		return cells;
+	}
+
+	protected listHints(): ScreenHint[] {
+		return [
+			"Esc close",
+			"↑/↓ or j/k select",
+			{ text: "Enter or l detail", color: "accent" },
+			{ text: "e enter", color: "accent" },
+			{ text: "x exit", color: "warning" },
+			{ text: "p prune", color: "warning" },
+		];
+	}
+
+	protected detailHints(): ScreenHint[] {
+		return ["Esc back", "↑/↓ scroll", "g/G ends"];
+	}
+
+	protected detailFor(row: WorktreeRow): DetailContents {
+		const lines = [`path    ${row.path}`, `branch  ${row.branch ?? "(detached)"}`];
+		const status = row.status;
+		if (!status) {
+			lines.push("state   entered by path; this session does not manage it");
+		} else {
+			if (status.head) lines.push(`head    ${status.head.slice(0, 7)}`);
+			const bits = [status.state === "dirty" ? `dirty (${status.changed} changed)` : "clean"];
+			if (status.ahead > 0) bits.push(`${status.ahead} ahead`);
+			if (status.behind > 0) bits.push(`${status.behind} behind`);
+			if (status.merged) bits.push("merged");
+			lines.push(`state   ${bits.join(", ")}`);
+			if (status.locked) {
+				lines.push(`lock    ${status.staleLock ? "stale (owner is gone)" : "held by a live session"}`);
+			}
+			if (status.lastUsedAt) lines.push(`used    ${relativeDay(status.lastUsedAt)}`);
+			// The handoff is read, not performed: a merge lands in the main checkout.
+			if (status.ahead > 0 && row.branch) {
+				lines.push(
+					"",
+					...handoffLines({
+						branch: row.branch,
+						base: this.view.baseBranch ?? null,
+						ahead: status.ahead,
+						merged: status.merged,
+					}),
+				);
+			}
+		}
+		return { title: row.name, lines, subtitle: row.branch ?? row.path };
+	}
+
+	protected handleVerb(key: string, row: WorktreeRow | undefined): void {
+		if (key !== "e" && key !== "x" && key !== "p") return;
+		if (this.deps.readOnly) {
+			this.notify("Plan mode is read-only. Approve the plan before changing worktrees.");
+			return;
+		}
+		if (key === "e") {
+			if (!row) {
+				this.notify("No worktree to enter.");
+				return;
+			}
+			if (row.current) {
+				this.notify(`${row.name} is already the current worktree.`);
+				return;
+			}
+			if (this.view.active) {
+				this.notify(`Still in ${worktreeLabel(this.view.active)}; press x to exit first.`);
+				return;
+			}
+			this.deps.onDone({ kind: "enter", name: row.name });
+			return;
+		}
+		if (key === "x") {
+			if (!this.view.active) {
+				this.notify("Not in a worktree.");
+				return;
+			}
+			this.deps.onDone({ kind: "exit" });
+			return;
+		}
+		if (this.pruning) {
+			this.notify("A prune is already running.");
+			return;
+		}
+		this.pruning = true;
+		this.notify("Pruning…");
+		void this.pruneInPlace();
+	}
+
+	/** Prune is the one verb that never prompts, so it runs without closing the screen. */
+	private async pruneInPlace(): Promise<void> {
+		try {
+			const report = await this.deps.prune();
+			this.view = await this.deps.reload();
+			this.resort();
+			this.notify(report.split("\n")[0] ?? "Pruned.");
+		} catch (error) {
+			this.notify(`Prune failed: ${messageOf(error)}`);
+		} finally {
+			this.pruning = false;
+		}
+	}
+}

package/extensions/worktree/status.ts

@@ -1,14 +1,18 @@
 /**
  * Worktree status and reporting: labels, summaries, refusal messages, and the
  * override/`list_worktrees` view.
+ *
+ * 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.
  */
 
 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 { gapLines, type IsolationGap, isolationGaps } from "./gaps.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";
@@ -62,7 +66,7 @@ export function refusalMessage(check: CheckoutCheck, path: string, cwd: string):
 }
 
 /** Compact marks for one managed worktree in the status list. */
-function statusMarks(status: CheckoutStatus, isCurrent: boolean): string[] {
+export function statusMarks(status: CheckoutStatus, isCurrent: boolean): string[] {
 	const marks: string[] = [];
 	if (isCurrent) marks.push("current");
 	if (status.state === "missing") marks.push("missing");
@@ -75,60 +79,100 @@ function statusMarks(status: CheckoutStatus, isCurrent: boolean): string[] {
 	return marks;
 }
 
-function relativeDay(at: number): string {
+export function relativeDay(at: number): string {
 	const days = Math.floor((Date.now() - at) / 86_400_000);
 	if (days <= 0) return "today";
 	if (days === 1) return "1d ago";
 	return `${days}d ago`;
 }
 
-/** Human-readable status: current worktree, override conflicts, gaps, managed worktrees. */
-export async function worktreeStatus(pi: ExtensionAPI, ctx: ExtensionContext): Promise<string> {
-	const current = getActive();
-	const lines: string[] = [];
-	if (current) {
-		lines.push(stateSummary(current));
-		if (current.borrowed) lines.push("  (inherited from the parent session)");
-	} else {
-		lines.push("Not in a worktree.");
-	}
-	const inactive = getInactiveOverrides();
-	if (inactive.length > 0) {
-		lines.push("", `Isolation not active for: ${inactive.join(", ")} (their default implementation is in use).`);
-	}
-	if (current) {
-		// What isolation does not cover, from the same rules `doctor` reports: a gap
-		// the user cannot see is a gap they cannot weigh.
-		const gaps = isolationGaps({
-			platform: process.platform,
-			activeTools: pi.getActiveTools(),
-			config: configFor(current.repoRoot),
-			unverifiableCommands: getUnverifiableCommands(),
-		});
-		const gapBlock = gapLines(gaps);
-		if (gapBlock.length > 0) lines.push("", "Not isolated:", ...gapBlock);
-	}
+/** One managed worktree and what git says about it. */
+export interface ManagedRow {
+	entry: ManagedWorktree;
+	status: CheckoutStatus;
+}
+
+/** Everything both status surfaces report, read once. */
+export interface WorktreeSnapshot {
+	active: WorktreeState | null;
+	/** What isolation does not cover, from the same rules `doctor` reports. */
+	gaps: IsolationGap[];
+	/** Built-in tools with an inactive override. */
+	inactiveOverrides: string[];
+	/** Managed worktrees with their checkout status, in git's order. */
+	managed: ManagedRow[];
+	/** The merge-target branch name, when the repository has a remote. */
+	baseBranch: string | undefined;
+}
 
-	const root = current?.repoRoot ?? (await repoRoot(pi, ctx.cwd));
+/** Read the session's worktree status once, for either surface to render. */
+export async function worktreeSnapshot(pi: ExtensionAPI, ctx: ExtensionContext): Promise<WorktreeSnapshot> {
+	const active = getActive();
+	// A gap the user cannot see is a gap they cannot weigh, so they are computed for
+	// every read rather than cached from session start.
+	const gaps = active
+		? isolationGaps({
+				platform: process.platform,
+				activeTools: pi.getActiveTools(),
+				config: configFor(active.repoRoot),
+				unverifiableCommands: getUnverifiableCommands(),
+			})
+		: [];
+
+	const managed: ManagedRow[] = [];
+	let baseBranch: string | undefined;
+	const root = active?.repoRoot ?? (await repoRoot(pi, ctx.cwd));
 	if (root) {
 		const config = loadConfig(root);
-		const managed = await listManagedWorktrees(pi, root, config);
-		const { registry } = reconcileRegistry(root, config, managed, { persist: false });
-		const baseBranch = await defaultBranch(pi, root);
+		const entries = await listManagedWorktrees(pi, root, config);
+		const { registry } = reconcileRegistry(root, config, entries, { persist: false });
+		baseBranch = await defaultBranch(pi, root);
 		const baseRef = baseBranch ? `origin/${baseBranch}` : undefined;
 		// 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);
-			return `  ${entry.path}  ${entry.branch ?? ""}${marks.length > 0 ? `  [${marks.join(", ")}]` : ""}`.trimEnd();
+		const row = async (entry: ManagedWorktree): Promise<ManagedRow> => {
+			return { entry, status: await statusOf(pi, entry, { baseRef, record: records.get(entry.path) }) };
 		};
 		// 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)));
+		managed.push(...(await mapConcurrent(entries, 4, row)));
+	}
+
+	return { active, gaps, inactiveOverrides: getInactiveOverrides(), managed, baseBranch };
+}
+
+/** Human-readable status: current worktree, override conflicts, gaps, managed worktrees. */
+export function formatWorktreeStatus(snapshot: WorktreeSnapshot): string {
+	const { active, gaps, inactiveOverrides, managed } = snapshot;
+	const lines: string[] = [];
+	if (active) {
+		lines.push(stateSummary(active));
+		if (active.borrowed) lines.push("  (inherited from the parent session)");
+	} else {
+		lines.push("Not in a worktree.");
+	}
+	if (inactiveOverrides.length > 0) {
+		lines.push(
+			"",
+			`Isolation not active for: ${inactiveOverrides.join(", ")} (their default implementation is in use).`,
+		);
+	}
+	const gapBlock = gapLines(gaps);
+	if (gapBlock.length > 0) lines.push("", "Not isolated:", ...gapBlock);
+
+	if (managed.length > 0) {
+		const row = (item: ManagedRow): string => {
+			const marks = statusMarks(item.status, active?.path === item.entry.path);
+			return `  ${item.entry.path}  ${item.entry.branch ?? ""}${marks.length > 0 ? `  [${marks.join(", ")}]` : ""}`.trimEnd();
+		};
+		lines.push("", `Managed worktrees (${managed.length}):`, ...managed.map(row));
 	}
 	return lines.join("\n");
 }
+
+/** Read the status and render it: what the `list_worktrees` tool and a headless `/worktree` print. */
+export async function worktreeStatus(pi: ExtensionAPI, ctx: ExtensionContext): Promise<string> {
+	return formatWorktreeStatus(await worktreeSnapshot(pi, ctx));
+}

package/lib/README.md

@@ -18,29 +18,33 @@ belongs in that extension instead — see `extensions/web-access/http.ts` and
 | Module | Responsibility |
 |---|---|
 | [`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`. |
+| [`claims/`](./claims/) | Claim overlap, shared by the two things that ask "do these paths collide?" so approval and claiming cannot disagree: [`claims/overlap.ts`](./claims/overlap.ts) holds `normalizeClaimPath` (repository-relative, posix, no trailing slash — a Windows spelling reads as the same path), `claimsConflict` (a claim covers everything below it, in either direction) and `findClaimOverlap` (the first colliding pair). Used by `session-bus` when a session claims, and by plan approval when a split names its units. |
+| [`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` / `asNumber` (the untrusted-JSON narrowing pair) / `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, 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`. |
+| [`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`, `watch`, and `session-bus`, rendered by bytefly — plus `burstText`, the one assembly of the model-facing text for a burst of pending outcomes (marker, counted headline, rows, an optional `… N more`, an optional hint). |
+| [`report.ts`](./report.ts) | The pending-report channel: `createPendingReporter` with `wake` / `pending` / `markReported` / `buildNotice` / `wakeRequested` / `source` / `onWoke`, returning the handlers that report at the next turn, raise at most one triggered turn per wake window, retry a wake the running turn suppressed once `agent_settled` reports an unaborted settle, and prune only their own notices; and `registerPendingChannel`, which binds those handlers to `session_start` / `session_tree` / `agent_start` / `agent_settled` / `before_agent_start` / `context` / `session_shutdown` around a `load` / `setStatus?` / `shutdown` runtime, so the order a session starts and shuts down is written once. A `load` that resolves a repository may return a promise, which is awaited before the trigger is armed; a runtime that publishes no chip omits `setStatus`. `job`, `watch`, and `session-bus` supply only their own arming in `onSessionStart` / `onSessionShutdown` and their own `wakeRequested`. |
 | [`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. |
+| [`qr.ts`](./qr.ts) | The QR seam shared by `wechat`'s login and `plan`'s shared review link: `qrMatrix` (the module matrix), `qrLines` (Unicode half-block terminal lines of a fixed width), and `qrSvg` (inline markup a page can paste); the `qrcode` package is imported on first use, never at registration. |
+| [`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` 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). |
+| [`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. |
 | [`pi-invocation.ts`](./pi-invocation.ts) | `getPiInvocation`: how to launch a nested `pi` process, shared by `subagent` and bytefly's doctor surface. |
+| [`plans/`](./plans/) | The plan document's shared shape, for plan mode and for whatever reads a plan without importing it: [`plans/sections.ts`](./plans/sections.ts) is the one fence-aware scan (`extractSections`, `replaceSection`, `teamSectionBody`, and the `HEADING` / `FENCE` / `normalizeHeadingText` vocabulary), [`plans/team.ts`](./plans/team.ts) parses and renders the `## Team` section (`PlanUnit`, `PlanTeam`, `renderTeam`, `parseTeam`, `readTeam`, `writeTeam`), [`plans/split.ts`](./plans/split.ts) decides whether a proposed split is one (`checkSplit`, its refusals by name, `SHARED_FILES`, `MAX_OWNERS`, `mergeOrder`), and [`plans/store.ts`](./plans/store.ts) holds the one directory rule (`plansDir`) the store writes to and the bus reads from. The switch lives apart in [`plans/setting.ts`](./plans/setting.ts): `SPLIT_SECTION` / `SPLIT_KEY` / `SPLIT_DEFAULT`, the `SPLIT_SETTING_ID` / `SPLIT_SETTING_LABEL` the settings row shows, `splitEnabled(cwd)` and `SPLIT_OFF_NOTE`, so the panel row, approval, and the bus read one key. |
 | [`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`. |
+| [`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. |
 | [`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`. |
@@ -48,8 +52,9 @@ belongs in that extension instead — see `extensions/web-access/http.ts` and
 | [`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. |
 | [`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 rejected-tool-call shape: `toolError` builds the `isError: true` content plus the caller's `details`, and `errorResult` is the action-and-message form `job` and `watch` share. |
-| [`web/`](./web/) | The Bytefly web brand system shared by the browser surfaces: [`web/tokens.ts`](./web/tokens.ts) (palette derived from the Bytefly terminal themes, scales, and the `tok-*` map), [`web/base.ts`](./web/base.ts), [`web/components.ts`](./web/components.ts) (the `bf-*` kit, including the dialog, shortcut-sheet, and `bf-kbd` rules), [`web/layout.ts`](./web/layout.ts), [`web/runtime.ts`](./web/runtime.ts) (`WEB_THEME_STORAGE_KEY`, `THEME_JS`, `THEME_TOGGLE_JS`, and `keysDialogScript(triggerId)` — the shared shortcut-sheet wiring, whose contract is `window.bfKeys`), [`web/markup.ts`](./web/markup.ts) (the HTML atoms, including `keysSheet` and its `KeyHint` rows), and the [`web/index.ts`](./web/index.ts) barrel. |
+| [`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. |
 
 ## Conventions
 

package/lib/claims/overlap.ts

@@ -0,0 +1,43 @@
+/**
+ * Claim overlap (pure).
+ *
+ * Two things in this package need the same answer to "do these paths collide?":
+ * `session-bus` when a session claims a path, and plan approval when a proposed
+ * split names its units. They must agree, because a split that passes validation
+ * and then conflicts at claim time — or the reverse — teaches the user that a
+ * claim is arbitrary. So the predicate lives here once and both call it.
+ *
+ * A claim on a directory covers every file below it, in either direction, and a
+ * claim is always a repository-relative, posix-separated path: the caller
+ * normalizes first, because a Windows spelling (`a\b`) and a posix one (`a/b`)
+ * naming the same file must not read as two claims.
+ */
+
+/** A repository-relative path with one separator and no trailing slash. */
+export function normalizeClaimPath(raw: string): string {
+	const posix = raw.trim().replace(/\\/g, "/");
+	const trimmed = posix
+		.replace(/^\.\//, "")
+		.replace(/\/{2,}/g, "/")
+		.replace(/\/+$/, "");
+	return trimmed === "." ? "" : trimmed;
+}
+
+/** Whether one claim covers the other path in either direction. */
+export function claimsConflict(a: string, b: string): boolean {
+	const left = normalizeClaimPath(a);
+	const right = normalizeClaimPath(b);
+	// The root claim (an empty path, or ".") covers everything below it.
+	if (left === "" || right === "") return true;
+	return left === right || left.startsWith(`${right}/`) || right.startsWith(`${left}/`);
+}
+
+/** The first two prefixes in `paths` that collide, if any. */
+export function findClaimOverlap(paths: readonly string[]): [string, string] | undefined {
+	for (let i = 0; i < paths.length; i++) {
+		for (let j = i + 1; j < paths.length; j++) {
+			if (claimsConflict(paths[i], paths[j])) return [paths[i], paths[j]];
+		}
+	}
+	return undefined;
+}

package/lib/config.ts

@@ -85,6 +85,18 @@ export function asRecord(value: unknown): Record<string, unknown> | undefined {
 	return value as Record<string, unknown>;
 }
 
+/**
+ * A finite number from an untrusted JSON field, or `undefined`.
+ *
+ * The numeric companion to {@link asRecord}: a field a wire format, a child
+ * process, or a config file claims is a number is only a number when it is one —
+ * a string, `NaN`, or `null` reads as "not reported" so a caller can fall back
+ * instead of summing garbage into a total.
+ */
+export function asNumber(value: unknown): number | undefined {
+	return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+
 /** Parse a JSON object from disk, ignoring missing/malformed/non-object files. */
 export function readJson(path: string): Record<string, unknown> | undefined {
 	const result = readJsonResult(path);

package/lib/format.ts

@@ -7,12 +7,16 @@
 
 import { homedir } from "node:os";
 
-/** Compact token count: `999`, `1.0k`, `12k`, `1.5M`, `12M`. `?` when not a number. */
+/**
+ * Compact token count: `999`, `1.0k`, `12k`, `1.5M`, `12M`. `?` when not a
+ * number. The `k` → `M` switch sits below a million so a count that would round
+ * to `1000k` prints as `1.0M` instead.
+ */
 export function formatTokens(count: number): string {
 	if (!Number.isFinite(count)) return "?";
 	if (count < 1000) return count.toString();
 	if (count < 10000) return `${(count / 1000).toFixed(1)}k`;
-	if (count < 1000000) return `${Math.round(count / 1000)}k`;
+	if (count < 999500) return `${Math.round(count / 1000)}k`;
 	if (count < 10000000) return `${(count / 1000000).toFixed(1)}M`;
 	return `${Math.round(count / 1000000)}M`;
 }