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

package/extensions/worktree/config.ts

@@ -7,7 +7,7 @@
  */
 
 import { CONFIG_DIR_NAME, getAgentDir } from "@earendil-works/pi-coding-agent";
-import { cleanString, clampInteger, loadConfigSection } from "../../lib/config.ts";
+import { asBoolean, cleanString, clampInteger, loadConfigSection, stringList } from "../../lib/config.ts";
 
 export interface WorktreeGuardConfig {
 	/** Block write/edit whose resolved path leaves the active worktree. Default: true */
@@ -70,28 +70,16 @@ export const DEFAULT_CONFIG: WorktreeConfig = {
 	},
 };
 
-function booleanOr(value: unknown, fallback: boolean): boolean {
-	return typeof value === "boolean" ? value : fallback;
-}
-
-/** Keep only trimmed, non-empty strings from an untrusted array. */
-function stringList(value: unknown, fallback: string[]): string[] {
-	if (!Array.isArray(value)) return fallback;
-	return value
-		.filter((item): item is string => typeof item === "string" && item.trim().length > 0)
-		.map((item) => item.trim());
-}
-
 function normalizeGuard(raw: unknown, base: WorktreeGuardConfig): WorktreeGuardConfig {
 	if (!raw || typeof raw !== "object" || Array.isArray(raw)) return base;
 	const value = raw as Record<string, unknown>;
 	return {
-		blockFileEscapes: booleanOr(value.blockFileEscapes, base.blockFileEscapes),
-		blockReadEscapes: booleanOr(value.blockReadEscapes, base.blockReadEscapes),
-		blockGitRedirects: booleanOr(value.blockGitRedirects, base.blockGitRedirects),
-		blockSymlinkEscapes: booleanOr(value.blockSymlinkEscapes, base.blockSymlinkEscapes),
-		blockUnparsableCommands: booleanOr(value.blockUnparsableCommands, base.blockUnparsableCommands),
-		blockPowershell: booleanOr(value.blockPowershell, base.blockPowershell),
+		blockFileEscapes: asBoolean(value.blockFileEscapes, base.blockFileEscapes),
+		blockReadEscapes: asBoolean(value.blockReadEscapes, base.blockReadEscapes),
+		blockGitRedirects: asBoolean(value.blockGitRedirects, base.blockGitRedirects),
+		blockSymlinkEscapes: asBoolean(value.blockSymlinkEscapes, base.blockSymlinkEscapes),
+		blockUnparsableCommands: asBoolean(value.blockUnparsableCommands, base.blockUnparsableCommands),
+		blockPowershell: asBoolean(value.blockPowershell, base.blockPowershell),
 	};
 }
 
@@ -102,7 +90,7 @@ export function normalizeConfig(raw: Record<string, unknown> | undefined, base:
 		dir: cleanString(raw.dir, base.dir),
 		baseRef: raw.baseRef === "head" || raw.baseRef === "fresh" ? raw.baseRef : base.baseRef,
 		branchPrefix: cleanString(raw.branchPrefix, base.branchPrefix),
-		fetchRemote: booleanOr(raw.fetchRemote, base.fetchRemote),
+		fetchRemote: asBoolean(raw.fetchRemote, base.fetchRemote),
 		fetchTimeoutMs: clampInteger(raw.fetchTimeoutMs, base.fetchTimeoutMs, 0, 600_000),
 		onExit: raw.onExit === "ask" || raw.onExit === "keep" || raw.onExit === "remove" ? raw.onExit : base.onExit,
 		pruneAfterDays: clampInteger(raw.pruneAfterDays, base.pruneAfterDays, 0, 3650),

package/extensions/worktree/enter.ts

@@ -6,13 +6,13 @@
 import { appendFileSync, existsSync, readFileSync } from "node:fs";
 import { basename, join, resolve } from "node:path";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { isInside } from "../../lib/path.ts";
+import { createExecRunner, revParse } from "../../lib/git/index.ts";
+import { isInside, realPathOfNearest } from "../../lib/path.ts";
 import { GLYPHS } from "../../lib/tui/glyphs.ts";
 import { loadConfig, type WorktreeConfig } from "./config.ts";
 import { WorktreeCancelledError } from "./errors.ts";
 import {
 	branchExists,
-	canonicalize,
 	commitsAhead,
 	currentBranch,
 	fetchPrRef,
@@ -95,12 +95,7 @@ export interface EnterOptions {
 }
 
 async function resolveCommit(pi: ExtensionAPI, dir: string, ref: string): Promise<string | undefined> {
-	try {
-		const result = await pi.exec("git", ["rev-parse", ref], { cwd: dir });
-		return result.code === 0 ? result.stdout.trim() : undefined;
-	} catch {
-		return undefined;
-	}
+	return revParse(createExecRunner(pi), dir, ref);
 }
 
 /** Create or enter a worktree and rebind the session's effective root. */
@@ -139,11 +134,11 @@ export async function enterWorktree(
 	let createdByUs = true;
 
 	if (pathArg) {
-		target = canonicalize(resolve(ctx.cwd, pathArg));
-		if (target === canonicalize(root)) {
+		target = realPathOfNearest(resolve(ctx.cwd, pathArg));
+		if (target === realPathOfNearest(root)) {
 			throw new Error("The main checkout is not a worktree; enter a separate worktree path.");
 		}
-		const managedRoot = canonicalize(resolve(root, config.dir));
+		const managedRoot = realPathOfNearest(resolve(root, config.dir));
 		if (!isInside(managedRoot, target)) {
 			if (!ctx.hasUI) throw new Error(`Refusing to enter ${target} outside ${managedRoot} without confirmation.`);
 			const ok = await ctx.ui.confirm(
@@ -163,7 +158,7 @@ export async function enterWorktree(
 		target = worktreePath(root, config, name);
 		// `name` becomes both a directory and a branch, so an absolute name or one
 		// with `..` can otherwise place the worktree outside the managed root.
-		const managedRoot = canonicalize(resolve(root, config.dir));
+		const managedRoot = realPathOfNearest(resolve(root, config.dir));
 		if (!isInside(managedRoot, target)) {
 			throw new Error(
 				`Refusing to create a worktree outside ${managedRoot}: ${target}. ` +

package/extensions/worktree/git.ts

@@ -5,19 +5,26 @@
  * configuration (and abort/timeout handling) as the rest of Pi.
  */
 
-import { existsSync, realpathSync, statSync } from "node:fs";
-import { basename, dirname, join, resolve } from "node:path";
+import { existsSync, statSync } from "node:fs";
+import { resolve } from "node:path";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import {
 	createExecRunner,
 	currentBranch as sharedCurrentBranch,
+	gitCommonDir,
 	hasCommits as sharedHasCommits,
 	repoRootFor,
+	revParse,
+	type RunGitOptions,
 } from "../../lib/git/index.ts";
+import { isInside, realPathOfNearest } from "../../lib/path.ts";
+import { isPidAlive } from "../../lib/spawn.ts";
 import type { WorktreeConfig } from "./config.ts";
 
-async function git(pi: ExtensionAPI, args: string[], cwd: string, timeout?: number) {
-	return createExecRunner(pi)(args, { cwd, ...(timeout ? { timeoutMs: timeout } : {}) });
+type GitCallOptions = Omit<RunGitOptions, "cwd">;
+
+async function git(pi: ExtensionAPI, args: string[], cwd: string, options: GitCallOptions = {}) {
+	return createExecRunner(pi)(args, { cwd, ...options });
 }
 
 type GitOutcome = { ok: true; stdout: string } | { ok: false; code: number; error: string };
@@ -30,46 +37,15 @@ async function gitOutcome(pi: ExtensionAPI, args: string[], cwd: string): Promis
 }
 
 /**
- * Run a network git operation with terminal prompting disabled, so a fetch that
- * would ask for credentials fails fast instead of hanging until its timeout.
- * The environment is restored afterwards.
+ * A network fetch: terminal prompting is disabled through the runner's env seam,
+ * so a credentials prompt fails fast instead of hanging until its timeout.
  */
-export async function withGitNoPrompt<T>(fn: () => Promise<T>): Promise<T> {
-	const previous = process.env.GIT_TERMINAL_PROMPT;
-	process.env.GIT_TERMINAL_PROMPT = "0";
-	try {
-		return await fn();
-	} finally {
-		if (previous === undefined) delete process.env.GIT_TERMINAL_PROMPT;
-		else process.env.GIT_TERMINAL_PROMPT = previous;
-	}
-}
-
-/**
- * Canonicalize a path, resolving symlinks. Handles paths that do not exist yet
- * by canonicalizing the nearest existing ancestor, so `/tmp/x` and
- * `/private/tmp/x` compare equal on macOS.
- */
-export function canonicalize(path: string): string {
-	const absolute = resolve(path);
-	try {
-		// `.native` resolves Windows 8.3 short names (e.g. HSPCAD~1) to their
-		// long form, so a temp path from os.tmpdir() compares equal to git's
-		// expanded output. It is equivalent to realpathSync on other platforms.
-		return realpathSync.native(absolute);
-	} catch {
-		try {
-			return join(realpathSync.native(dirname(absolute)), basename(absolute));
-		} catch {
-			return absolute;
-		}
-	}
-}
+const NO_TERMINAL_PROMPT: GitCallOptions = { env: { GIT_TERMINAL_PROMPT: "0" } };
 
 /** Absolute path of the repository root containing `cwd`, or undefined when not a git repo. */
 export async function repoRoot(pi: ExtensionAPI, cwd: string): Promise<string | undefined> {
 	const root = await repoRootFor(pi, cwd);
-	return root ? canonicalize(root) : undefined;
+	return root ? realPathOfNearest(root) : undefined;
 }
 
 /** Whether the repository has at least one commit (a worktree needs a commit to branch from). */
@@ -101,11 +77,13 @@ export async function resolveBaseRef(
 	if (branch) {
 		if (config.fetchRemote && (await fetchStale(pi, repoRoot))) {
 			// Never block on credentials: treat an error or timeout as "keep using the cache".
-			await withGitNoPrompt(() => git(pi, ["fetch", "--no-tags", "origin", branch], repoRoot, config.fetchTimeoutMs));
+			await git(pi, ["fetch", "--no-tags", "origin", branch], repoRoot, {
+				...NO_TERMINAL_PROMPT,
+				timeoutMs: config.fetchTimeoutMs,
+			});
 		}
 		const remoteRef = `origin/${branch}`;
-		const exists = await git(pi, ["rev-parse", "--verify", "--quiet", remoteRef], repoRoot);
-		if (exists.code === 0 && exists.stdout.trim()) return { ref: remoteRef, mode: "fresh" };
+		if (await refExists(pi, repoRoot, remoteRef)) return { ref: remoteRef, mode: "fresh" };
 	}
 	return { ref: "HEAD", mode: "head" };
 }
@@ -121,9 +99,9 @@ const FETCH_MAX_AGE_MS = 24 * 60 * 60 * 1000;
 
 /** Whether the repository has not been fetched in the last 24 hours. */
 export async function fetchStale(pi: ExtensionAPI, repoRoot: string, maxAgeMs = FETCH_MAX_AGE_MS): Promise<boolean> {
-	const common = await git(pi, ["rev-parse", "--path-format=absolute", "--git-common-dir"], repoRoot);
-	if (common.code !== 0) return true;
-	const fetchHead = resolve(common.stdout.trim(), "FETCH_HEAD");
+	const common = await gitCommonDir(createExecRunner(pi), repoRoot);
+	if (common === undefined) return true;
+	const fetchHead = resolve(common, "FETCH_HEAD");
 	try {
 		return Date.now() - statSync(fetchHead).mtimeMs > maxAgeMs;
 	} catch {
@@ -170,7 +148,10 @@ export async function fetchPrRef(
 			? [`merge-requests/${pr.number}/head`]
 			: [`pull/${pr.number}/head`, `merge-requests/${pr.number}/head`];
 	for (const spec of specs) {
-		const result = await withGitNoPrompt(() => git(pi, ["fetch", "--no-tags", "origin", spec], repoRoot, timeoutMs));
+		const result = await git(pi, ["fetch", "--no-tags", "origin", spec], repoRoot, {
+			...NO_TERMINAL_PROMPT,
+			timeoutMs,
+		});
 		if (result.code === 0) return { ok: true };
 	}
 	return { ok: false, error: `Failed to fetch PR/MR #${pr.number}` };
@@ -178,16 +159,16 @@ export async function fetchPrRef(
 
 /** Path of a managed worktree directory from its name. */
 export function worktreePath(repoRoot: string, config: WorktreeConfig, name: string): string {
-	return canonicalize(resolve(repoRoot, config.dir, name));
+	return realPathOfNearest(resolve(repoRoot, config.dir, name));
 }
 
 export async function worktreeExists(pi: ExtensionAPI, dir: string): Promise<boolean> {
-	const want = canonicalize(dir);
+	const want = realPathOfNearest(dir);
 	const result = await git(pi, ["worktree", "list", "--porcelain"], dir);
 	if (result.code !== 0) return false;
 	return result.stdout
 		.split("\n")
-		.some((line) => line.startsWith("worktree ") && canonicalize(line.slice("worktree ".length).trim()) === want);
+		.some((line) => line.startsWith("worktree ") && realPathOfNearest(line.slice("worktree ".length).trim()) === want);
 }
 
 /** Whether a local branch exists. */
@@ -206,8 +187,7 @@ export async function commitsAheadOf(pi: ExtensionAPI, dir: string, branch: stri
 
 /** Whether `ref` resolves here: a branch, a remote-tracking ref, or a tag. */
 export async function refExists(pi: ExtensionAPI, dir: string, ref: string): Promise<boolean> {
-	const result = await git(pi, ["rev-parse", "--verify", "--quiet", ref], dir);
-	return result.code === 0 && result.stdout.trim() !== "";
+	return (await revParse(createExecRunner(pi), dir, ref)) !== undefined;
 }
 
 export async function branchExists(pi: ExtensionAPI, repoRoot: string, branch: string): Promise<boolean> {
@@ -317,15 +297,15 @@ export async function checkCheckout(pi: ExtensionAPI, dir: string, mainRoot: str
 	if (!top) {
 		return { ok: false, reason: "unsafe", detail: `${dir} is not a git worktree.` };
 	}
-	if (canonicalize(top) === canonicalize(mainRoot)) {
+	if (realPathOfNearest(top) === realPathOfNearest(mainRoot)) {
 		return {
 			ok: false,
 			reason: "unsafe",
 			detail: `${dir} resolves its working tree to the main checkout ${mainRoot}.`,
 		};
 	}
-	const commonDir = await git(pi, ["rev-parse", "--path-format=absolute", "--git-common-dir"], dir);
-	if (commonDir.code !== 0) {
+	const commonDir = await gitCommonDir(createExecRunner(pi), dir);
+	if (commonDir === undefined) {
 		return { ok: false, reason: "unverified", detail: `Could not read git metadata for ${dir}.` };
 	}
 	return { ok: true };
@@ -390,13 +370,13 @@ export async function listManagedWorktrees(
 ): Promise<ManagedWorktree[]> {
 	const result = await git(pi, ["worktree", "list", "--porcelain"], repoRoot);
 	if (result.code !== 0) return [];
-	const managedRoot = canonicalize(resolve(repoRoot, config.dir));
+	const managedRoot = realPathOfNearest(resolve(repoRoot, config.dir));
 	const entries: ManagedWorktree[] = [];
 	let current: ManagedWorktree = { path: "" };
 	const flush = () => {
 		if (!current.path) return;
-		const path = canonicalize(current.path);
-		if (path === managedRoot || path.startsWith(`${managedRoot}/`) || path.startsWith(`${managedRoot}\\`)) {
+		const path = realPathOfNearest(current.path);
+		if (isInside(managedRoot, path)) {
 			entries.push({ ...current, path });
 		}
 		current = { path: "" };
@@ -433,17 +413,6 @@ export async function unlockWorktree(pi: ExtensionAPI, repoRoot: string, dir: st
 	await git(pi, ["worktree", "unlock", dir], repoRoot);
 }
 
-/** Whether a process id is alive on this host. */
-export function isProcessAlive(pid: number): boolean {
-	if (!Number.isFinite(pid) || pid <= 0) return false;
-	try {
-		process.kill(pid, 0);
-		return true;
-	} catch (error) {
-		return (error as NodeJS.ErrnoException).code === "EPERM";
-	}
-}
-
 /** Owning pid from a `pi:<pid>:<session>` lock reason, when present. */
 export function lockOwnerPid(reason: string): number | undefined {
 	const match = reason.match(/^pi:(\d+):/);
@@ -453,5 +422,5 @@ export function lockOwnerPid(reason: string): number | undefined {
 /** Whether a lock reason names a `pi` process that is no longer alive. */
 export function isStaleLock(reason: string): boolean {
 	const pid = lockOwnerPid(reason);
-	return pid !== undefined && !isProcessAlive(pid);
+	return pid !== undefined && !isPidAlive(pid);
 }

package/extensions/worktree/index.ts

@@ -24,8 +24,9 @@ import { existsSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { isExtensionEnabled } from "../../lib/env.ts";
+import { realPathOfNearest } from "../../lib/path.ts";
 import { GLYPHS } from "../../lib/tui/glyphs.ts";
-import { canonicalize, checkCheckout, repoRoot, unlockWorktree } from "./git.ts";
+import { checkCheckout, repoRoot, unlockWorktree } from "./git.ts";
 import { analyzeBashCommand, guardFileTool, guardPowershellTool, isUnverifiable } from "./guard.ts";
 import {
 	enterWorktree,
@@ -100,9 +101,9 @@ export function registerWorktree(pi: ExtensionAPI, { entryPath, createBuiltin }:
 		// factory inside the parent, which must restore its own recorded state.
 		const envRoot = event.reason === "startup" ? process.env[ENV_ROOT] : undefined;
 		if (envRoot) {
-			const borrowedPath = canonicalize(envRoot);
+			const borrowedPath = realPathOfNearest(envRoot);
 			if (existsSync(borrowedPath) && (await repoRoot(pi, borrowedPath))) {
-				const borrowedMain = process.env[ENV_MAIN] ? canonicalize(process.env[ENV_MAIN]) : borrowedPath;
+				const borrowedMain = process.env[ENV_MAIN] ? realPathOfNearest(process.env[ENV_MAIN]) : borrowedPath;
 				const borrowed: WorktreeState = {
 					active: true,
 					borrowed: true,
@@ -229,5 +230,5 @@ export function registerWorktree(pi: ExtensionAPI, { entryPath, createBuiltin }:
 /** Pi extension entrypoint. */
 export default function worktreeExtension(pi: ExtensionAPI): void {
 	if (!isExtensionEnabled("worktree")) return;
-	registerWorktree(pi, { entryPath: canonicalize(fileURLToPath(import.meta.url)) });
+	registerWorktree(pi, { entryPath: realPathOfNearest(fileURLToPath(import.meta.url)) });
 }

package/extensions/worktree/registry.ts

@@ -13,9 +13,9 @@
 import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { realPathOfNearest } from "../../lib/path.ts";
 import type { WorktreeConfig } from "./config.ts";
 import {
-	canonicalize,
 	commitsAhead,
 	commitsBehind,
 	isBranchMerged,
@@ -102,7 +102,7 @@ function saveRegistry(repoRoot: string, config: WorktreeConfig, registry: Worktr
 /** Insert or replace a record, preserving an existing `createdAt`. */
 export function upsertRecord(repoRoot: string, config: WorktreeConfig, record: WorktreeRecord): void {
 	const registry = loadRegistry(repoRoot, config);
-	const path = canonicalize(record.path);
+	const path = realPathOfNearest(record.path);
 	const existing = registry.worktrees.find((candidate) => candidate.path === path);
 	const next: WorktreeRecord = existing
 		? { ...record, path, createdAt: existing.createdAt || record.createdAt }
@@ -116,7 +116,7 @@ export function upsertRecord(repoRoot: string, config: WorktreeConfig, record: W
 /** Mark a worktree as just used. No-op when it is not registered. */
 export function touchRecord(repoRoot: string, config: WorktreeConfig, path: string, at = Date.now()): void {
 	const registry = loadRegistry(repoRoot, config);
-	const wanted = canonicalize(path);
+	const wanted = realPathOfNearest(path);
 	const record = registry.worktrees.find((candidate) => candidate.path === wanted);
 	if (!record) return;
 	record.lastUsedAt = at;
@@ -125,7 +125,7 @@ export function touchRecord(repoRoot: string, config: WorktreeConfig, path: stri
 
 export function removeRecord(repoRoot: string, config: WorktreeConfig, path: string): void {
 	const registry = loadRegistry(repoRoot, config);
-	const wanted = canonicalize(path);
+	const wanted = realPathOfNearest(path);
 	const next = registry.worktrees.filter((candidate) => candidate.path !== wanted);
 	if (next.length === registry.worktrees.length) return;
 	registry.worktrees = next;
@@ -145,7 +145,7 @@ export function reconcileRegistry(
 	options: { persist?: boolean } = {},
 ): { registry: WorktreeRegistry; changed: boolean } {
 	const registry = loadRegistry(repoRoot, config);
-	const live = new Set(managed.map((entry) => canonicalize(entry.path)));
+	const live = new Set(managed.map((entry) => realPathOfNearest(entry.path)));
 	const byPath = new Map(registry.worktrees.map((record) => [record.path, record] as const));
 
 	let changed = false;
@@ -158,7 +158,7 @@ export function reconcileRegistry(
 		}
 	}
 	for (const entry of managed) {
-		const path = canonicalize(entry.path);
+		const path = realPathOfNearest(entry.path);
 		if (byPath.has(path)) continue;
 		next.push({
 			path,
@@ -189,7 +189,7 @@ export async function statusOf(
 	entry: ManagedWorktree,
 	options: StatusOptions = {},
 ): Promise<CheckoutStatus> {
-	const path = canonicalize(entry.path);
+	const path = realPathOfNearest(entry.path);
 	const locked = entry.locked !== undefined;
 	const staleLock = locked && entry.locked ? isStaleLock(entry.locked) : false;
 	const base: CheckoutStatus = {

package/extensions/worktree/root-tools.ts

@@ -30,7 +30,7 @@ import {
 	createReadToolDefinition,
 	createWriteToolDefinition,
 } from "@earendil-works/pi-coding-agent";
-import { canonicalize } from "./git.ts";
+import { realPathOfNearest } from "../../lib/path.ts";
 
 export const ROOT_TOOL_NAMES = ["read", "write", "edit", "bash", "grep", "find", "ls"] as const;
 export type RootToolName = (typeof ROOT_TOOL_NAMES)[number];
@@ -155,7 +155,7 @@ export function findInactiveOverrides(pi: ExtensionAPI, self: string | undefined
 		const info = pi.getAllTools().find((entry) => entry.name === name);
 		if (!info) continue;
 		const path = info.sourceInfo?.path;
-		const isOurs = path && !path.startsWith("builtin:") && (!self || canonicalize(path) === self);
+		const isOurs = path && !path.startsWith("builtin:") && (!self || realPathOfNearest(path) === self);
 		if (!isOurs) inactive.push(name);
 	}
 	return inactive;

package/extensions/worktree/status.ts

@@ -5,9 +5,10 @@
 
 import { basename } from "node:path";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { realPathOfNearest } from "../../lib/path.ts";
 import { loadConfig } from "./config.ts";
 import { gapLines, isolationGaps } from "./gaps.ts";
-import { canonicalize, type CheckoutCheck, defaultBranch, listManagedWorktrees, repoRoot } from "./git.ts";
+import { type CheckoutCheck, defaultBranch, listManagedWorktrees, 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";
@@ -116,7 +117,7 @@ export async function worktreeStatus(pi: ExtensionAPI, ctx: ExtensionContext): P
 		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 === canonicalize(entry.path));
+			const record = registry.worktrees.find((candidate) => candidate.path === realPathOfNearest(entry.path));
 			const status = await statusOf(pi, entry, { baseRef, record });
 			const marks = statusMarks(status, current?.path === entry.path);
 			lines.push(

package/lib/README.md

@@ -18,26 +18,35 @@ 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` (the last two edit one leaf, flat or nested, preserving siblings and metadata). Includes `clampInteger` / `clampNumber` / `cleanString` / `asRecord` / `readJson` / `readJsonResult`. |
+| [`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. |
 | [`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. |
-| [`format.ts`](./format.ts) | Pure text/number formatting shared by renderers: `formatTokens`, `formatCount`, `formatDuration` (`450ms`, `3.2s`, `1m05s`, `2h03m`), `stripControlChars`, `sanitize`, `sanitizeLine` — the boundary for untrusted, single-line text — and `shortenPath`. |
+| [`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`. |
+| [`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`. |
 | [`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`, `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`, `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. |
-| [`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), `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`, `checkbox`, `chip`, `keyValueRow`, `emptyState`), [`tui/columns.ts`](./tui/columns.ts) (`splitRow`, `fitCells`, `flowCells`, `padTo`, `clip`, `clipMiddle`), [`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` and `watch` share), [`tui/tool.ts`](./tui/tool.ts) (`toolCallTitle`, the width-safe `ToolCallText` / `reuseCallText`, sanitized `errorLine` / `rejectionLine`, `moreHint`, `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, and doc guards share. |
+| [`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). |
+| [`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. |
 | [`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`. |
 | [`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`. |
-| [`goal-state.ts`](./goal-state.ts) | The published `goal` state replayed from the session branch: `PublishedGoal`, `GOAL_ENTRY_TYPE`, `MAX_GOAL_OBJECTIVE`, and `lastGoal(entries)` (the last valid goal, skipping a rejected call and honouring an explicit clear), so `plan` can restate an active goal while planning and offer to record one on approval — with no extension importing another's modules. |
-| [`todo-state.ts`](./todo-state.ts) | The published `todo` state replayed from the session branch: `ExistingTodo` and `lastTodos(entries)` (the last valid list, skipping a rejected call), so `plan` can merge an approved plan's steps into it and `goal` can name the items still open when a goal is marked achieved — with no extension importing another's modules. |
+| [`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`. |
+| [`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. |
-| [`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), [`web/layout.ts`](./web/layout.ts), [`web/runtime.ts`](./web/runtime.ts) (`WEB_THEME_STORAGE_KEY`, `THEME_JS`, `THEME_TOGGLE_JS`), [`web/markup.ts`](./web/markup.ts), and the [`web/index.ts`](./web/index.ts) barrel. |
+| [`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. |
 
 ## Conventions
 
@@ -50,6 +59,11 @@ belongs in that extension instead — see `extensions/web-access/http.ts` and
   glyph and the `setStatus` key are one contract, not two literals. Tool names
   shared by an orchestrating tool and the tool it calls — and parameter names
   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.
 - **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