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

package/extensions/worktree/guard.ts

@@ -12,11 +12,24 @@
  *   5. the un-re-rooted `powershell` tool, which has no guard of its own.
  */
 
-import { homedir } from "node:os";
-import { isAbsolute, join, resolve } from "node:path";
+import { isAbsolute, resolve } from "node:path";
 import { isInside, isInsideReal, realPathOfNearest } from "../../lib/path.ts";
-import { isShellEscapable } from "../../lib/shell.ts";
+import { WORKSPACE_READERS } from "../../lib/policy.ts";
 import type { WorktreeConfig } from "./config.ts";
+import {
+	COMMAND_WRAPPERS,
+	isAssignment,
+	isUnverifiable,
+	pathEscapes,
+	redirectionTargets,
+	splitSegments,
+	type ShellWord,
+	tokenize,
+} from "./shell.ts";
+
+// The reader's public names, so a caller keeps importing the guards from here.
+export { isUnverifiable };
+export type { Redirect, ShellWord } from "./shell.ts";
 
 export interface GuardBlock {
 	block: true;
@@ -33,14 +46,11 @@ export function resolveUnder(root: string, path: string | undefined): string {
 // File tools (check 1)
 // ---------------------------------------------------------------------------
 
+/** The file tools and the one argument that carries their path. */
 const PATH_FIELD: Record<string, string> = {
-	read: "path",
-	read_doc: "path",
+	...Object.fromEntries(WORKSPACE_READERS.map((name): [string, string] => [name, "path"])),
 	write: "path",
 	edit: "path",
-	grep: "path",
-	find: "path",
-	ls: "path",
 };
 
 const WRITE_TOOLS = new Set(["write", "edit"]);
@@ -82,281 +92,6 @@ export function guardFileTool(
 	return undefined;
 }
 
-// ---------------------------------------------------------------------------
-// Shell commands (checks 2-4)
-// ---------------------------------------------------------------------------
-
-/** One shell word, with whether it began inside a quote (a quoted literal). */
-interface ShellWord {
-	text: string;
-	leadingQuoted: boolean;
-}
-
-/** Split a command on unquoted `;`, `&`, `|`, and newlines, preserving quotes. */
-function splitSegments(command: string): string[] {
-	const segments: string[] = [];
-	let current = "";
-	let quote: string | null = null;
-	for (let i = 0; i < command.length; i++) {
-		const ch = command[i];
-		if (quote) {
-			current += ch;
-			if (ch === "\\" && quote === '"' && i + 1 < command.length) {
-				const next = command[i + 1];
-				if (isShellEscapable(next)) current += command[++i];
-			} else if (ch === quote) {
-				quote = null;
-			}
-			continue;
-		}
-		if (ch === "'" || ch === '"') {
-			quote = ch;
-			current += ch;
-		} else if (ch === ";" || ch === "\n") {
-			segments.push(current);
-			current = "";
-		} else if (ch === "&") {
-			const prev = command[i - 1];
-			const next = command[i + 1];
-			if (next === "&") {
-				// `&&` is a command separator.
-				segments.push(current);
-				current = "";
-				i++;
-			} else if (prev === ">" || prev === "<" || next === ">") {
-				// `>&`, `<&`, `&>`: redirection, not a separator.
-				current += ch;
-			} else {
-				// Background job `&`.
-				segments.push(current);
-				current = "";
-			}
-		} else if (ch === "|") {
-			if (command[i + 1] === "&") i++; // `|&` is still a pipe separator.
-			segments.push(current);
-			current = "";
-		} else {
-			current += ch;
-		}
-	}
-	segments.push(current);
-	return segments;
-}
-
-/** Tokenize a shell segment into words, removing quotes and tracking quoted leads. */
-function tokenize(segment: string): ShellWord[] {
-	const words: ShellWord[] = [];
-	let current = "";
-	let leadingQuoted = false;
-	let started = false;
-	let quote: string | null = null;
-	const push = () => {
-		if (started) words.push({ text: current, leadingQuoted });
-		current = "";
-		leadingQuoted = false;
-		started = false;
-	};
-	for (let i = 0; i < segment.length; i++) {
-		const ch = segment[i];
-		if (quote) {
-			if (ch === "\\" && quote === '"' && i + 1 < segment.length) {
-				const next = segment[i + 1];
-				if (isShellEscapable(next)) current += segment[++i];
-				else current += ch;
-			} else if (ch === quote) {
-				quote = null;
-			} else {
-				current += ch;
-			}
-			continue;
-		}
-		if (ch === "'" || ch === '"') {
-			if (!started) {
-				started = true;
-				leadingQuoted = true;
-			}
-			quote = ch;
-		} else if (ch === " " || ch === "\t") {
-			push();
-		} else if (ch === "\\" && i + 1 < segment.length) {
-			started = true;
-			const next = segment[i + 1];
-			if (isShellEscapable(next)) current += segment[++i];
-			else current += ch;
-		} else {
-			started = true;
-			current += ch;
-		}
-	}
-	push();
-	return words;
-}
-
-/**
- * Expand `~` and environment variables so a path that only leaves the worktree
- * after shell expansion is still caught. `unresolved` marks a value that cannot
- * be expanded statically (unknown variable, `$`, backtick, `~user`); callers
- * treat it as escaping, because guessing could allow a bypass.
- */
-function expandShellPath(raw: string): { path?: string; unresolved: boolean } {
-	let value = raw;
-	if (value === "~") value = homedir();
-	else if (value.startsWith("~/")) value = join(homedir(), value.slice(2));
-	else if (value.startsWith("~")) return { unresolved: true };
-
-	let unresolved = false;
-	value = value.replace(/\$\{([A-Za-z_][A-Za-z0-9_]*)\}|\$([A-Za-z_][A-Za-z0-9_]*)/g, (match, braced, plain) => {
-		const name = braced ?? plain;
-		const env = process.env[name];
-		if (env === undefined) {
-			unresolved = true;
-			return match;
-		}
-		return env;
-	});
-	if (value.includes("$") || value.includes("`")) unresolved = true;
-	return { path: value, unresolved };
-}
-
-/** Whether a shell path argument leaves the worktree once expanded. */
-function pathEscapes(root: string, raw: string): boolean {
-	const expanded = expandShellPath(raw);
-	if (expanded.unresolved || !expanded.path) return true;
-	return !isInside(root, resolve(root, expanded.path));
-}
-
-/**
- * Constructs whose text does not spell out the git command that runs. Exported
- * so the `tool_call` handler counts exactly the commands this check would have
- * refused, instead of guessing at a second list.
- */
-export function isUnverifiable(command: string): boolean {
-	return /\$\(|`|\$\{!|\beval\b|\b(?:sh|bash|zsh|dash|ksh)\s+-c\b/.test(command);
-}
-
-// ---------------------------------------------------------------------------
-// Shell redirections (check 1b)
-// ---------------------------------------------------------------------------
-
-interface Redirect {
-	target: string;
-	/** True for output/read-write redirections; false for input-only. */
-	write: boolean;
-}
-
-/** Read a shell word starting at `start`, skipping leading blanks, unquoting the result. */
-function readShellWord(text: string, start: number): { raw: string; end: number } {
-	let i = start;
-	while (i < text.length && (text[i] === " " || text[i] === "\t")) i++;
-	let raw = "";
-	let quote: string | null = null;
-	while (i < text.length) {
-		const ch = text[i];
-		if (quote) {
-			if (ch === "\\" && quote === '"' && i + 1 < text.length) {
-				const next = text[i + 1];
-				if (isShellEscapable(next)) {
-					raw += next;
-					i += 2;
-				} else {
-					raw += ch;
-					i += 1;
-				}
-				continue;
-			}
-			if (ch === quote) {
-				quote = null;
-				i++;
-				continue;
-			}
-			raw += ch;
-			i++;
-			continue;
-		}
-		if (ch === "'" || ch === '"') {
-			quote = ch;
-			i++;
-			continue;
-		}
-		if (ch === "\\" && i + 1 < text.length) {
-			const next = text[i + 1];
-			if (isShellEscapable(next)) {
-				raw += next;
-				i += 2;
-			} else {
-				raw += ch;
-				i += 1;
-			}
-			continue;
-		}
-		if (ch === " " || ch === "\t") break;
-		raw += ch;
-		i++;
-	}
-	return { raw, end: i };
-}
-
-/**
- * File redirection targets in one shell segment. File-descriptor duplications
- * (`2>&1`), heredocs (`<<EOF`), and here-strings (`<<<x`) are skipped because
- * their operand is not a path.
- */
-function redirectionTargets(segment: string): Redirect[] {
-	const redirects: Redirect[] = [];
-	let quote: string | null = null;
-	for (let i = 0; i < segment.length; i++) {
-		const ch = segment[i];
-		if (quote) {
-			if (ch === "\\" && quote === '"' && i + 1 < segment.length) {
-				i++;
-				continue;
-			}
-			if (ch === quote) quote = null;
-			continue;
-		}
-		if (ch === "'" || ch === '"') {
-			quote = ch;
-			continue;
-		}
-		if (ch === "\\") {
-			i++;
-			continue;
-		}
-		if (ch !== ">" && ch !== "<") continue;
-
-		const two = segment.slice(i, i + 2);
-		const three = segment.slice(i, i + 3);
-		if (three === "<<<") {
-			i += 2;
-			continue;
-		}
-		if (two === "<<") {
-			// Heredoc delimiter: not a path.
-			i += 1;
-			continue;
-		}
-		if (two === ">&" || two === "<&") {
-			// File-descriptor duplication (`2>&1`, `>&-`) is not a path, but bash
-			// treats `>&file` as `&>file` (stdout+stderr to a file).
-			const operand = readShellWord(segment, i + 2);
-			if (operand.raw === "" || /^\d+$/.test(operand.raw) || operand.raw === "-") {
-				i += 1;
-				continue;
-			}
-			redirects.push({ target: operand.raw, write: ch === ">" });
-			i = operand.end - 1;
-			continue;
-		}
-		// `>`, `>>`, `>|`, `<`, `<>`: the next word is a path.
-		const write = ch === ">" || two === "<>";
-		if (two === ">>" || two === ">|") i += 1;
-		const word = readShellWord(segment, i + 1);
-		if (word.raw) redirects.push({ target: word.raw, write });
-		i = word.end - 1;
-	}
-	return redirects;
-}
-
 /** Refuse an output/input redirection whose target leaves the worktree. */
 function redirectionEscapes(root: string, command: string, config: WorktreeConfig): string | undefined {
 	const checkWrites = config.guard.blockFileEscapes;
@@ -383,13 +118,6 @@ function isNullDevice(raw: string): boolean {
 	return raw.replace(/^(['"])(.*)\1$/, "$2") === "/dev/null";
 }
 
-/** Commands that wrap another command, so a following assignment is still a prefix. */
-const COMMAND_WRAPPERS = new Set(["sudo", "doas", "env", "command", "builtin", "exec", "nohup", "nice", "time"]);
-
-function isAssignment(word: string): boolean {
-	return /^[A-Za-z_][A-Za-z0-9_]*=/.test(word);
-}
-
 /** A leading `GIT_DIR=`/`GIT_WORK_TREE=` assignment that points outside. */
 function envGitRedirect(root: string, words: ShellWord[]): string | undefined {
 	for (let i = 0; i < words.length; i++) {

package/extensions/worktree/handoff.ts

@@ -20,7 +20,12 @@ export interface Handoff {
 	base: string | null;
 	/** Commits on the branch that the base does not contain. */
 	ahead: number;
-	/** Whether the base already contains every commit on the branch. */
+	/**
+	 * Commits the branch has made since the commit it was created at, when that was
+	 * recorded. Absent for a worktree this package did not create.
+	 */
+	commits?: number;
+	/** Whether the work landed: every commit is in the base, and there were commits. */
 	merged: boolean;
 }
 
@@ -43,7 +48,10 @@ export function handoffLines(handoff: Handoff): string[] {
 		];
 	}
 	if (handoff.merged || handoff.ahead === 0) {
-		const state = handoff.merged ? `is merged into ${handoff.base}` : `has no commits beyond ${handoff.base}`;
+		// "Merged" is a claim that work landed; a branch with no commits of its own never had
+		// any to land, and saying so is what stops an empty worktree reading as finished.
+		const landed = handoff.merged && handoff.commits !== 0;
+		const state = landed ? `is merged into ${handoff.base}` : `has no commits beyond ${handoff.base}`;
 		return [`Handoff: ${handoff.branch} ${state} — nothing to merge.`];
 	}
 

package/extensions/worktree/index.ts

@@ -34,6 +34,7 @@ import {
 	isWorktreeCancelled,
 	refusalMessage,
 	worktreeFacts,
+	enteredWorktree,
 	worktreeLabel,
 } from "./lifecycle.ts";
 import { registerCommands } from "./commands.ts";
@@ -160,7 +161,7 @@ export function registerWorktree(pi: ExtensionAPI, { entryPath, createBuiltin }:
 				const name = flag.trim() === "true" ? undefined : flag.trim();
 				try {
 					const { state } = await enterWorktree(pi, ctx, { name });
-					ctx.ui.notify(`Entered worktree ${worktreeLabel(state)}`, "info");
+					ctx.ui.notify(enteredWorktree(state), "info");
 				} catch (error) {
 					if (isWorktreeCancelled(error)) {
 						ctx.ui.notify(error instanceof Error ? error.message : String(error), "info");

package/extensions/worktree/lifecycle.ts

@@ -12,6 +12,8 @@ export { exitWorktree, type ExitOptions } from "./exit.ts";
 export { pruneWorktrees } from "./prune.ts";
 export { findInactiveOverrides } from "./root-tools.ts";
 export {
+	enteredWorktree,
+	exitedWorktree,
 	formatWorktreeStatus,
 	refusalMessage,
 	stateSummary,

package/extensions/worktree/registry.ts

@@ -6,8 +6,9 @@
  * is a disposable cache: a missing or corrupt file loads as empty, writes are
  * best-effort, and reads reconcile against `git worktree list`.
  *
- * `statusOf` is the single derived view used by status, prune, and (later)
- * switch/exit, so those do not each re-derive dirty/ahead/behind/merged state.
+ * `statusOf` is the single derived view the status listing reads, so the text and the
+ * screen do not each re-derive dirty/ahead/behind/merged state; exit reads the one fact it
+ * needs (`commitsAheadOf`) without it.
  */
 
 import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
@@ -15,14 +16,7 @@ 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 {
-	commitsAhead,
-	commitsBehind,
-	isBranchMerged,
-	isStaleLock,
-	type ManagedWorktree,
-	statusEntries,
-} from "./git.ts";
+import { commitsAhead, commitsBehind, isStaleLock, type ManagedWorktree, statusEntries } from "./git.ts";
 
 const REGISTRY_VERSION = 1;
 
@@ -53,8 +47,16 @@ export interface CheckoutStatus {
 	state: "clean" | "dirty" | "missing";
 	/** Number of changed files (porcelain entries). */
 	changed: number;
+	/**
+	 * Commits the branch has made since the commit it was created at.
+	 *
+	 * Absent when that commit was never recorded — a worktree the user pointed us at —
+	 * because git keeps no fork point of its own to ask.
+	 */
+	commits?: number;
 	ahead: number;
 	behind: number;
+	/** Whether the work landed: every commit is in the base, and there were commits. */
 	merged: boolean;
 	locked: boolean;
 	staleLock: boolean;
@@ -218,10 +220,17 @@ export async function statusOf(
 	const baseRef = options.baseRef;
 	base.state = dirty.length > 0 ? "dirty" : "clean";
 	base.changed = dirty.length;
+	// The commit the worktree was created at is the only fork point git can be asked about:
+	// once a branch is merged, it and a branch that never committed are both ancestors of
+	// the base, so `ahead` reports 0 for each and cannot tell them apart. This can.
+	const since = options.record?.base.commit;
+	if (since) base.commits = await commitsAhead(pi, path, since);
 	if (baseRef) {
 		base.ahead = await commitsAhead(pi, path, baseRef);
 		base.behind = await commitsBehind(pi, path, baseRef);
-		base.merged = base.ahead === 0 || (await isBranchMerged(pi, path, "HEAD", baseRef));
+		// `merged` claims the work landed, so it needs commits that could have landed: a
+		// branch with none is an empty checkout, not a finished one.
+		base.merged = base.ahead === 0 && base.commits !== 0;
 	}
 	return base;
 }

package/extensions/worktree/root-tools.ts

@@ -35,14 +35,24 @@ 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];
 
-type AnyToolDef = ToolDefinition<any, any, any>;
+/**
+ * A built-in tool definition, as the seven factories return it.
+ *
+ * Pi's own three defaults, spelled out rather than left implicit: `renderCall`'s arguments
+ * are contravariant in the parameter schema and its context in the detail type, so the
+ * seven concrete definitions do not widen to one `ToolDefinition<TSchema, unknown, ...>`
+ * — and neither does the test seam that replaces them with a stub. Erasing all three is
+ * the only alias that accepts both, which is what makes this line Pi's escape hatch
+ * rather than a missing type.
+ */
+type BuiltinToolDef = ToolDefinition<any, any, any>;
 
 export interface FactoryOptions {
 	read?: { autoResizeImages?: boolean };
 	bash?: { commandPrefix?: string; shellPath?: string };
 }
 
-function createBuiltin(name: RootToolName, cwd: string, options: FactoryOptions): AnyToolDef {
+function createBuiltin(name: RootToolName, cwd: string, options: FactoryOptions): BuiltinToolDef {
 	switch (name) {
 		case "read":
 			return createReadToolDefinition(cwd, options.read);
@@ -62,7 +72,7 @@ function createBuiltin(name: RootToolName, cwd: string, options: FactoryOptions)
 }
 
 /** Host built-in factory. Injectable so tests avoid `mock.module`. */
-export type BuiltinFactory = (name: RootToolName, cwd: string, options: FactoryOptions) => AnyToolDef;
+export type BuiltinFactory = (name: RootToolName, cwd: string, options: FactoryOptions) => BuiltinToolDef;
 
 export interface RootToolDeps {
 	/** Override the host built-in factories. Tests inject a stub definition. */

package/extensions/worktree/runtime.ts

@@ -21,8 +21,14 @@ export const ENV_BRANCH = "PI_WORKTREE_BRANCH";
 /** Main checkout a borrowed worktree forked from, so a child knows its `repoRoot`. */
 export const ENV_MAIN = "PI_WORKTREE_MAIN";
 
-/** Cross-extension notification channel. */
-export const WORKTREE_EVENT_CHANNEL = "worktree:changed";
+/**
+ * The channel `publishWorktree` announces on, for another extension that follows the active
+ * root without polling; `docs/extensions/worktree.md` names it as the contract.
+ *
+ * Not exported: the channel is an event name on `pi.events`, so what crosses the boundary
+ * is the string a listener subscribes to, and the constant is this module's own.
+ */
+const WORKTREE_EVENT_CHANNEL = "worktree:changed";
 
 let active: WorktreeState | null = null;
 /** Directory to use when not isolated (the session cwd at startup). */

package/extensions/worktree/screen.ts

@@ -4,8 +4,9 @@
  *
  * 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.
+ * from the same `worktreeSnapshot` the text status renders and their marks from the
+ * same `statusMarks`, 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
@@ -16,6 +17,7 @@
 import { basename } from "node:path";
 import type { Theme } from "@earendil-works/pi-coding-agent";
 import { messageOf } from "../../lib/errors.ts";
+import { planModeRefusal } from "../../lib/plan-entry.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";
@@ -75,11 +77,9 @@ function rowGlyph(status: CheckoutStatus | undefined): { char: string; role: Tui
 	return { char: GLYPHS.branch, role: "info" };
 }
 
-/** The row's right-hand text: its marks, or `clean` when it has none. */
+/** The row's right-hand text: its marks, worded once in `statusMarks`. */
 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("  ");
+	return (row.status ? statusMarks(row.status, row.current) : ["current"]).join("  ");
 }
 
 export interface WorktreeScreenOptions {
@@ -186,7 +186,13 @@ export class WorktreeListComponent extends DockListScreen<WorktreeRow> {
 			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");
+			// The row says it too, and for the same reason: a merged mark is a claim that work
+			// landed, which a worktree with no commits of its own cannot make.
+			if (status.commits === 0) bits.push("no commits");
+			else if (status.merged) {
+				if (status.commits !== undefined) bits.push(`${status.commits} commits`);
+				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"}`);
@@ -200,6 +206,7 @@ export class WorktreeListComponent extends DockListScreen<WorktreeRow> {
 						branch: row.branch,
 						base: this.view.baseBranch ?? null,
 						ahead: status.ahead,
+						commits: status.commits,
 						merged: status.merged,
 					}),
 				);
@@ -211,7 +218,7 @@ export class WorktreeListComponent extends DockListScreen<WorktreeRow> {
 	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.");
+			this.notify(planModeRefusal("changing worktrees"));
 			return;
 		}
 		if (key === "e") {