gentle-pi 2.5.0 → 2.6.0

package/tests/gentle-shell.test.ts

@@ -1,8 +1,14 @@
 import assert from "node:assert/strict";
+import { execFileSync, execFile } from "node:child_process";
+import { mkdirSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
 import test from "node:test";
 import { initTheme, type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-coding-agent";
-import gentleShell, { buildShellBarModel, changesShortcut, devBinaryCard, fetchCodexUsage, loadFileDiff, openInExternalEditor, type GentlePromptEditor } from "../extensions/gentle-shell.ts";
+import type { TUI } from "@earendil-works/pi-tui";
+import installGentleShell, { buildShellBarModel, changesShortcut, devBinaryCard, fetchCodexUsage, loadFileDiff, shellGitRunner, openInExternalEditor, type GentlePromptEditor } from "../extensions/gentle-shell.ts";
 import { CHANGE_STATUS } from "../lib/shell-changes.ts";
+import { sidebarState, type SidebarRail } from "../lib/shell-sidebar.ts";
 import type { ShellBarTheme } from "../lib/shell-bar.ts";
 import { stripAnsi } from "../lib/terminal-theme.ts";
 
@@ -11,6 +17,9 @@ import { stripAnsi } from "../lib/terminal-theme.ts";
 
 initTheme("dark");
 
+const resolveWorktree = (path: string) => ({ root: path.startsWith("/repo") || path === "." ? "/repo" : path, commonDir: "/clone/git" });
+const gentleShell: typeof installGentleShell = (pi, env, deps) => installGentleShell(pi, env, { resolveWorktree, gitRunner: (cwd) => async (args) => pi.exec("git", ["-C", cwd, ...args], { timeout: 5000 }), ...deps });
+
 const plainTheme = {
 	fg(_color: string, value: string) {
 		return value;
@@ -34,7 +43,7 @@ interface FakeUi {
 	workingVisible: boolean | undefined;
 	notices: string[];
 	overlay: unknown;
-	overlayView: { render(width: number): string[] } | undefined;
+	overlayView: { render(width: number): string[]; handleInput(data: string): void } | undefined;
 	closeOverlay: (() => void) | undefined;
 }
 
@@ -54,16 +63,25 @@ interface ShortcutRegistration {
 type MessageRenderer = (message: { customType: string; content: unknown }, options: { expanded: boolean }, theme: unknown) => { render(width: number): string[] };
 const renderers = new Map<string, MessageRenderer>();
 
-function fakePi(script: GitScript[] = [{ numstat: "", porcelain: "" }]): { pi: ExtensionAPI; handlers: Map<string, Array<(event: unknown, ctx: ExtensionContext) => unknown>>; git: string[][]; commands: Map<string, CommandRegistration>; shortcuts: Map<string, ShortcutRegistration> } {
+function fakePi(script: GitScript[] = [{ numstat: "", porcelain: "" }]) {
 	const handlers = new Map<string, Array<(event: unknown, ctx: ExtensionContext) => unknown>>();
 	const commands = new Map<string, CommandRegistration>();
 	const shortcuts = new Map<string, ShortcutRegistration>();
 	const git: string[][] = [];
+	let entries: unknown[] = [];
+	const tools = new Map<string, { renderShell?: string; execute(id: string, params: unknown, signal: undefined, update: undefined, ctx: ExtensionContext): Promise<unknown> }>();
+	const listeners = new Map<string, (data: unknown) => void>();
 	let round = 0;
 	const pi = {
 		on(event: string, handler: (event: unknown, ctx: ExtensionContext) => unknown) {
-			handlers.set(event, [...(handlers.get(event) ?? []), handler]);
+			handlers.set(event, [...(handlers.get(event) ?? []), (payload, ctx) => {
+				entries = ctx.sessionManager.getEntries();
+				return handler(payload, ctx);
+			}]);
 		},
+		appendEntry(customType: string, data: unknown) { entries.push({ type: "custom", customType, data }); },
+		events: { on(name: string, fn: (data: unknown) => void) { listeners.set(name, fn); return () => listeners.delete(name); }, emit(name: string, data: unknown) { listeners.get(name)?.(data); } },
+		registerTool(tool: { name: string }) { tools.set(tool.name, tool as never); },
 		registerCommand(name: string, registration: CommandRegistration) {
 			commands.set(name, registration);
 		},
@@ -78,20 +96,24 @@ function fakePi(script: GitScript[] = [{ numstat: "", porcelain: "" }]): { pi: E
 		},
 		async exec(_command: string, args: string[]) {
 			git.push(args);
+			if (args.includes("worktree")) return { stdout: "worktree /repo\0branch refs/heads/main\0\0", stderr: "", code: 0, killed: false };
 			const isNumstat = args.includes("diff");
 			const step = script[Math.min(isNumstat ? round : round++, script.length - 1)];
 			return { stdout: isNumstat ? step.numstat : step.porcelain, stderr: "", code: 0, killed: false };
 		},
 	} as unknown as ExtensionAPI;
-	return { pi, handlers, git, commands, shortcuts };
+	return { pi, handlers, git, commands, shortcuts, tools };
 }
 
 async function fire(handlers: Map<string, Array<(event: unknown, ctx: ExtensionContext) => unknown>>, event: string, ctx: ExtensionContext): Promise<void> {
 	for (const handler of handlers.get(event) ?? []) await handler({}, ctx);
 }
 
-function fakeContext(options: { hasUI?: boolean; entries?: unknown[]; oauth?: boolean; pending?: boolean; editorFactory?: unknown; token?: string } = {}): { ctx: ExtensionContext; ui: FakeUi } {
+function fakeContext(options: { hasUI?: boolean; entries?: unknown[]; oauth?: boolean; pending?: boolean; editorFactory?: unknown; token?: string } = {}): { ctx: ExtensionContext; ui: FakeUi; overlayReady: Promise<void> } {
 	const ui: FakeUi = { footerFactory: undefined, editorFactory: options.editorFactory, widgets: new Map(), widgetSets: 0, workingVisible: undefined, notices: [], overlay: undefined, overlayView: undefined, closeOverlay: undefined };
+	let resolveOverlay: () => void;
+	const overlayReady = new Promise<void>((resolve) => { resolveOverlay = resolve; });
+	const entries = options.entries ?? [];
 	const ctx = {
 		hasUI: options.hasUI ?? true,
 		hasPendingMessages: () => options.pending ?? false,
@@ -100,7 +122,8 @@ function fakeContext(options: { hasUI?: boolean; entries?: unknown[]; oauth?: bo
 		sessionManager: {
 			getCwd: () => "/repo",
 			getSessionName: () => "Release notes",
-			getEntries: () => options.entries ?? [],
+			getEntries: () => entries,
+			getSessionId: () => "shell-session",
 		},
 		modelRegistry: { isUsingOAuth: () => options.oauth ?? true, getApiKeyForProvider: async () => options.token },
 		getContextUsage: () => ({ tokens: 122_400, contextWindow: 272_000, percent: 45 }),
@@ -126,16 +149,17 @@ function fakeContext(options: { hasUI?: boolean; entries?: unknown[]; oauth?: bo
 			setWorkingVisible(visible: boolean) {
 				ui.workingVisible = visible;
 			},
-			custom(factory: (tui: unknown, theme: unknown, keybindings: unknown, done: (value: null) => void) => { render(width: number): string[] }) {
+			custom(factory: (tui: unknown, theme: unknown, keybindings: unknown, done: (value: null) => void) => { render(width: number): string[]; handleInput(data: string): void }) {
 				ui.overlay = factory;
 				return new Promise<null>((resolve) => {
 					ui.closeOverlay = () => resolve(null);
 					ui.overlayView = factory(fakeTui, plainTheme, fakeKeybindings, () => resolve(null));
+					resolveOverlay();
 				});
 			},
 		},
 	} as unknown as ExtensionContext;
-	return { ctx, ui };
+	return { ctx, ui, overlayReady };
 }
 
 function assistantEntry(usage: { input: number; output: number; cost: number }) {
@@ -206,6 +230,49 @@ test("gentleShell installs the footer on session_start when a UI exists", () =>
 	assert.match(lines[0], /main ⟡ gpt-5\.5 · medium/);
 });
 
+test("the fullscreen Status rail carries a live digest so a model switch refreshes it", async () => {
+	const { pi, handlers } = fakePi();
+	gentleShell(pi, { GENTLE_PI_SHELL_CHANGES_WATCH_MS: "off" });
+	const entries: unknown[] = [];
+	const { ctx, ui } = fakeContext({ entries });
+	await fire(handlers, "session_start", ctx);
+
+	const statuses = new Map<string, string>();
+	const liveFooterData = { getGitBranch: () => "main", getExtensionStatuses: () => statuses, getAvailableProviderCount: () => 1, onBranchChange: () => () => {} };
+	const tui = { terminal: { rows: 40, columns: 160 }, requestRender() {} };
+	const factory = ui.footerFactory as (tui: unknown, theme: ShellBarTheme, footerData: unknown) => { render(width: number): string[]; dispose(): void };
+	const component = factory(tui, plainTheme, liveFooterData);
+	try {
+		const rail = sidebarState(tui as unknown as TUI).parts.get("footer") as SidebarRail;
+		const live = () => rail.digest?.();
+		assert.equal(typeof rail.digest, "function", "the Status card paints live state and must declare a digest");
+		assert.match(rail.render(46).join("\n"), /gpt-5\.5/);
+
+		const beforeModel = live();
+		(ctx.model as { id: string }).id = "gpt-5.6";
+		assert.notEqual(live(), beforeModel, "/model must change the digest");
+		assert.match(rail.render(46).join("\n"), /gpt-5\.6/);
+
+		const beforeUsage = live();
+		(ctx as unknown as { getContextUsage: () => unknown }).getContextUsage = () => ({ tokens: 200_000, contextWindow: 272_000, percent: 74 });
+		assert.notEqual(live(), beforeUsage, "context usage must change the digest");
+		assert.match(rail.render(46).join("\n"), /74%/);
+
+		const beforeCost = live();
+		entries.push(assistantEntry({ input: 100, output: 20, cost: 0.42 }));
+		assert.notEqual(live(), beforeCost, "session cost must change the digest");
+		assert.match(rail.render(46).join("\n"), /\$0\.420/);
+
+		const beforeStatus = live();
+		statuses.set("mcp", "MCP: 3 servers enabled");
+		assert.notEqual(live(), beforeStatus, "extension statuses have no event and must change the digest");
+		assert.match(rail.render(46).join("\n"), /MCP: 3 servers enabled/);
+		assert.equal(live(), live(), "an unchanged digest still reuses the prepared rail");
+	} finally {
+		component.dispose();
+	}
+});
+
 test("gentleShell stays out of the way without a UI or when disabled", () => {
 	const disabled = fakePi();
 	gentleShell(disabled.pi, { GENTLE_PI_SHELL: "0" });
@@ -237,7 +304,7 @@ test("gentleShell frames the editor with the petal prompt and a hint while empty
 	editor.focused = true;
 	const lines = editor.render(60).map(stripAnsi);
 	assert.match(lines[0], /^╭─ ✿ ─+╮$/);
-	assert.ok(editor.render(60).every((line) => line.endsWith("\x1b[49m")), "prompt lines carry the panel background");
+	assert.doesNotMatch(editor.render(60).join("\n"), /\x1b\[44m/, "prompt must not paint passive backgrounds");
 	assert.match(lines[1], /^│.*type, or \/ for commands +│$/);
 	assert.match(lines[lines.length - 1], /^╰─+╯$/);
 	editor.setText("hola");
@@ -245,6 +312,24 @@ test("gentleShell frames the editor with the petal prompt and a hint while empty
 	editor.dispose();
 });
 
+test("registered prompt stays transparent while idle, working, and queued", () => {
+	const { pi, handlers, tools } = fakePi();
+	gentleShell(pi, {});
+	const { ctx, ui } = fakeContext();
+	ctx.ui.theme = { ...plainTheme, getBgAnsi: () => "\x1b[44m" } as typeof ctx.ui.theme;
+	const editor = installedPrompt(ctx, ui, handlers);
+	try {
+		for (const state of ["idle", "working", "queued"]) {
+			if (state === "working") for (const handler of handlers.get("agent_start") ?? []) handler({}, ctx);
+			(ctx as unknown as { hasPendingMessages(): boolean }).hasPendingMessages = () => state === "queued";
+			for (const width of [8, 40, 80]) assert.doesNotMatch(editor.render(width).join("\n"), /\x1b\[44m/, state);
+		}
+	} finally {
+		editor.dispose();
+	}
+	assert.equal(tools.get("session_worktree_register")?.renderShell, "self");
+});
+
 test("gentleShell shows working while the agent runs and queued when messages wait", () => {
 	const { pi, handlers } = fakePi();
 	gentleShell(pi, {});
@@ -322,6 +407,174 @@ test("gentleShell registers /gentle:changes and opens the overlay only when ther
 	await opened;
 });
 
+test("changes overlay follows registered linked roots on open, refresh and polling and scopes diff git cwd", async () => {
+	const { pi, handlers, commands, tools } = fakePi();
+	let roots = ["/repo"];
+	const diffs: string[][] = [];
+	pi.exec = (async (_command: string, args: string[]) => {
+		let stdout = "";
+		if (args.includes("worktree")) stdout = roots.map((root) => `worktree ${root}\0branch refs/heads/${root.slice(1)}\0\0`).join("");
+		else if (args.includes("status")) stdout = " M same.ts\0";
+		else if (args.includes("--numstat")) stdout = "1\t1\tsame.ts\n";
+		else { diffs.push(args); stdout = `+${args[1]}`; }
+		return { stdout, stderr: "", code: 0, killed: false };
+	}) as ExtensionAPI["exec"];
+	gentleShell(pi, { GENTLE_PI_SHELL_CHANGES_WATCH_MS: "off", GENTLE_PI_SHELL_CHANGES_POLL_MS: "5" });
+	const { ctx, ui } = fakeContext();
+	await fire(handlers, "session_start", ctx);
+	roots.push("/linked");
+	await tools.get("session_worktree_register")!.execute("register", { path: "/linked" }, undefined, undefined, ctx);
+	const open = commands.get("gentle:changes")!.handler("", ctx);
+	try {
+		await new Promise((resolve) => setTimeout(resolve, 20));
+		assert.match(ui.overlayView!.render(120).join("\n"), /linked · linked/);
+		assert.equal(diffs.length, 0);
+		ui.overlayView!.handleInput("j");
+		ui.overlayView!.handleInput("\r");
+		ui.overlayView!.handleInput("j");
+		await new Promise((resolve) => setTimeout(resolve, 0));
+		assert.deepEqual(diffs[0], ["-C", "/linked", "diff", "HEAD", "--", "same.ts"]);
+		ui.overlayView!.handleInput("\x1b[D");
+		roots.push("/new");
+		await tools.get("session_worktree_register")!.execute("register", { path: "/new" }, undefined, undefined, ctx);
+		ui.overlayView!.handleInput("r");
+		await new Promise((resolve) => setTimeout(resolve, 20));
+		assert.match(ui.overlayView!.render(120).join("\n"), /new · new/);
+		roots.push("/polled");
+		await tools.get("session_worktree_register")!.execute("register", { path: "/polled" }, undefined, undefined, ctx);
+		await new Promise((resolve) => setTimeout(resolve, 20));
+		assert.match(ui.overlayView!.render(120).join("\n"), /polled · polled/);
+	} finally {
+		ui.closeOverlay?.();
+		await open;
+		await fire(handlers, "session_shutdown", ctx);
+	}
+});
+
+test("successful direct tools register whole roots, failures and shell contents do not, and all UI counts agree", async () => {
+	const { pi, handlers, tools, commands } = fakePi();
+	const queried: string[] = [];
+	pi.exec = (async (_command: string, args: string[]) => {
+		const root = args[1];
+		if (args.includes("status")) queried.push(root);
+		const stdout = args.includes("worktree") ? ["/repo", "/used", "/failed", "/opaque", "/hidden"].map((path) => `worktree ${path}\0\0`).join("")
+			: args.includes("status") ? " M preexisting.ts\0?? new.ts\0"
+			: args.includes("--numstat") ? "2\t1\tpreexisting.ts\n" : "+diff";
+		return { stdout, stderr: "", code: 0, killed: false };
+	}) as ExtensionAPI["exec"];
+	gentleShell(pi, { GENTLE_PI_SHELL_CHANGES_WATCH_MS: "off" });
+	const { ctx, ui, overlayReady } = fakeContext();
+	await fire(handlers, "session_start", ctx);
+	const emit = async (name: string, event: unknown) => {
+		for (const handler of handlers.get(name) ?? []) await handler(event, ctx);
+	};
+	const complete = async (toolName: string, input: unknown, isError = false) => {
+		await emit("tool_execution_start", { toolCallId: "call", toolName, args: input });
+		await emit("tool_result", { toolCallId: "call", toolName, input, isError: false });
+		await emit("tool_execution_end", { toolCallId: "call", toolName, isError });
+	};
+	await complete("read", { path: "/failed" }, true);
+	await complete("bash", { command: "cd /opaque && edit stuff", path: "/opaque" });
+	assert.deepEqual(new Set(queried), new Set(["/repo"]));
+	await complete("read", { path: "/used" });
+	await complete("write", { path: "/used" });
+	assert.deepEqual(new Set(queried), new Set(["/repo", "/used"]));
+	assert.equal(ctx.sessionManager.getEntries().length, 2, "multiple completed tools dedupe");
+	assert.match(renderFooter(ui), /±4/);
+	const widget = ui.widgets.get("gentle-shell-changes") as (host: unknown, theme: unknown) => { render(width: number): string[] };
+	assert.match(widget(fakeTui, plainTheme).render(140)[0], /4 files/);
+	const open = commands.get("gentle:changes")!.handler("", ctx);
+	await overlayReady;
+	assert.doesNotMatch(ui.overlayView!.render(140).join("\n"), /hidden|opaque|failed/);
+	ui.closeOverlay?.();
+	await open;
+	await tools.get("session_worktree_register")!.execute("explicit", { path: "/opaque" }, undefined, undefined, ctx);
+	assert.match(renderFooter(ui), /±6/);
+	await fire(handlers, "session_shutdown", ctx);
+});
+
+test("session switching drops pending tool and foreign launch events while same-session entries restore", async () => {
+	const h = fakePi([{ numstat: "1\t0\ta.ts\n", porcelain: " M a.ts\0" }]);
+	gentleShell(h.pi, { GENTLE_PI_SHELL_CHANGES_WATCH_MS: "off" });
+	const first = fakeContext();
+	await fire(h.handlers, "session_start", first.ctx);
+	for (const handler of h.handlers.get("tool_execution_start") ?? []) await handler({ toolCallId: "old", toolName: "read", args: { path: "/foreign" } }, first.ctx);
+	const next = fakeContext({ entries: [...first.ctx.sessionManager.getEntries()] });
+	(next.ctx.sessionManager as unknown as { getSessionId(): string }).getSessionId = () => "new-session";
+	await fire(h.handlers, "session_start", next.ctx);
+	for (const handler of h.handlers.get("tool_result") ?? []) await handler({ toolCallId: "old", toolName: "read", input: { path: "/foreign" } }, next.ctx);
+	for (const handler of h.handlers.get("tool_execution_end") ?? []) await handler({ toolCallId: "old", toolName: "read", isError: false }, next.ctx);
+	const before = h.git.length;
+	h.pi.events.emit("gentle-pi:session-worktree-changed", { sessionId: "shell-session", root: "/foreign" });
+	assert.equal(h.git.length, before);
+	assert.match(renderFooter(next.ui), /±1/);
+	assert.ok(!h.git.some((args) => args[1] === "/foreign"));
+	await fire(h.handlers, "session_shutdown", next.ctx);
+});
+
+test("registered canonical root governs real Git discovery, status and diff despite inherited routing", async (t) => {
+	const fixture = realpathSync(mkdtempSync(join(tmpdir(), "shell-git-routing-")));
+	t.after(() => rmSync(fixture, { recursive: true, force: true }));
+	const selected = join(fixture, "selected");
+	const foreign = join(fixture, "foreign");
+	const empty = join(fixture, "empty");
+	mkdirSync(empty);
+	writeFileSync(join(empty, "config"), "");
+	const cleanEnv = Object.fromEntries(Object.entries(process.env).filter(([key]) => !key.startsWith("GIT_")));
+	Object.assign(cleanEnv, { GIT_CONFIG_GLOBAL: join(empty, "config"), GIT_CONFIG_NOSYSTEM: "1" });
+	const git = (cwd: string, args: string[]) => execFileSync("git", ["-C", cwd, "-c", `core.hooksPath=${empty}`, "-c", "commit.gpgsign=false", ...args], { env: cleanEnv, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });
+	for (const root of [selected, foreign]) {
+		git(fixture, ["init", "--initial-branch=main", `--template=${empty}`, root]);
+		writeFileSync(join(root, "tracked.txt"), "before\n");
+		git(root, ["add", "tracked.txt"]);
+		git(root, ["-c", "user.name=Fixture", "-c", "user.email=fixture@example.invalid", "commit", "-m", "Fixture"]);
+	}
+	writeFileSync(join(selected, "tracked.txt"), "selected change\n");
+	writeFileSync(join(selected, "selected-only.txt"), "selected untracked\n");
+	writeFileSync(join(foreign, "tracked.txt"), "foreign change\n");
+	writeFileSync(join(foreign, "foreign-only.txt"), "foreign untracked\n");
+	const poisoned = { ...cleanEnv, GIT_DIR: join(foreign, ".git"), GIT_WORK_TREE: foreign, GIT_INDEX_FILE: join(foreign, ".git", "index") };
+	const h = fakePi();
+	// Pi exec has no env option and inherits routing. Model that boundary with
+	// a child-only env, without changing this test process's environment.
+	h.pi.exec = ((command: string, args: string[], options: { timeout?: number } = {}) => new Promise((resolve) => {
+		execFile(command, args, { env: poisoned, encoding: "utf8", timeout: options.timeout, maxBuffer: Infinity }, (error, stdout, stderr) => resolve({ stdout, stderr, code: error ? typeof error.code === "number" ? error.code : 1 : 0, killed: Boolean(error?.killed) }));
+	})) as ExtensionAPI["exec"];
+	const { ctx, ui, overlayReady } = fakeContext();
+	(ctx as unknown as { cwd: string }).cwd = selected;
+	(ctx.sessionManager as unknown as { getCwd(): string }).getCwd = () => selected;
+	const run = shellGitRunner(selected, poisoned);
+	const discovery = await run(["worktree", "list", "--porcelain", "-z"]);
+	assert.match(discovery.stdout, new RegExp(`worktree ${selected}`));
+	assert.ok(!discovery.stdout.includes(foreign));
+	installGentleShell(h.pi, { GENTLE_PI_SHELL_CHANGES_WATCH_MS: "off" }, { devBinary: () => undefined, gitRunner: (cwd) => shellGitRunner(cwd, poisoned) });
+	await fire(h.handlers, "session_start", ctx);
+	t.after(() => fire(h.handlers, "session_shutdown", ctx));
+	const widget = ui.widgets.get("gentle-shell-changes") as (host: unknown, theme: unknown) => { render(width: number): string[] };
+	const rendered = widget(fakeTui, plainTheme).render(300).join("\n");
+	assert.match(rendered, /selected-only\.txt/);
+	assert.doesNotMatch(rendered, /foreign-only\.txt/);
+	const diff = await loadFileDiff(run, { path: "tracked.txt", added: 1, deleted: 1, status: CHANGE_STATUS.MODIFIED });
+	assert.match(diff, /\+selected change/);
+	assert.doesNotMatch(diff, /foreign change/);
+	const untracked = await loadFileDiff(run, { path: "selected-only.txt", added: 1, deleted: 0, status: CHANGE_STATUS.UNTRACKED });
+	assert.match(untracked, /\+selected untracked/);
+	assert.equal((await run(["rev-parse", "--verify", "missing-ref"])).code, 128, "Git failure codes stay intact");
+	assert.equal(poisoned.GIT_DIR, join(foreign, ".git"), "caller environment is not mutated");
+	assert.equal((await shellGitRunner(selected, { PATH: empty })(["status"])).code, 1, "spawn errors remain failed results rather than uncaught exceptions");
+	writeFileSync(join(selected, "tracked.txt"), "selected large line\n".repeat(70_000) + "selected final marker\n");
+	const largeDiff = await run(["diff", "HEAD", "--", "tracked.txt"]);
+	assert.equal(largeDiff.code, 0);
+	assert.ok(largeDiff.stdout.length > 1024 * 1024, "output must not inherit execFile's default one MiB cap");
+	assert.match(largeDiff.stdout, /\+selected final marker/);
+	const open = h.commands.get("gentle:changes")!.handler("", ctx);
+	await overlayReady;
+	ui.overlayView!.handleInput("\r");
+	ui.overlayView!.handleInput("j");
+	ui.closeOverlay?.();
+	await open;
+});
+
 test("loadFileDiff asks git for a HEAD diff, or a no-index diff for untracked files", async () => {
 	const calls: string[][] = [];
 	const git = async (args: string[]) => {
@@ -336,6 +589,24 @@ test("loadFileDiff asks git for a HEAD diff, or a no-index diff for untracked fi
 	]);
 });
 
+test("shell Git runner hides initial and repeated background polling children", async () => {
+	const calls: Array<{ command: string; args: readonly string[]; options: Record<string, unknown> }> = [];
+	const run = ((command: string, args: readonly string[], options: Record<string, unknown>, callback: (error: Error | null, stdout: string) => void) => {
+		calls.push({ command, args, options });
+		callback(null, "", "");
+	}) as typeof import("node:child_process").execFile;
+	const git = shellGitRunner("/repo with spaces & metacharacters", { PATH: process.env.PATH }, run);
+	await git(["status", "--porcelain=v1", "-z"]);
+	await git(["status", "--porcelain=v1", "-z"]);
+	assert.equal(calls.length, 2, "the same safe runner serves startup and repeated polling");
+	for (const call of calls) {
+		assert.equal(call.command, "git");
+		assert.deepEqual(call.args, ["-C", "/repo with spaces & metacharacters", "status", "--porcelain=v1", "-z"]);
+		assert.equal(call.options.shell, false);
+		assert.equal(call.options.windowsHide, true);
+	}
+});
+
 test("openInExternalEditor stops the TUI around the editor and honors $VISUAL over $EDITOR", () => {
 	const events: string[] = [];
 	const host = { stop: () => events.push("stop"), start: () => events.push("start"), requestRender: (force?: boolean) => events.push(`render:${force}`) };
@@ -348,6 +619,16 @@ test("openInExternalEditor stops the TUI around the editor and honors $VISUAL ov
 	assert.equal(openInExternalEditor(host, "lib/a.ts", {}, spawn), false);
 });
 
+test("external editor receives the selected worktree as process cwd", () => {
+	let cwd: string | undefined;
+	const spawn = ((_command: string, _args: string[], options: { cwd?: string }) => {
+		cwd = options.cwd;
+		return { status: 0 };
+	}) as typeof import("node:child_process").spawnSync;
+	openInExternalEditor({ stop() {}, start() {}, requestRender() {} }, "same.ts", { EDITOR: "vi" }, spawn, "/linked");
+	assert.equal(cwd, "/linked");
+});
+
 test("changesShortcut defaults to alt+g and can be overridden or disabled", () => {
 	assert.equal(changesShortcut({}), "alt+g");
 	assert.equal(changesShortcut({ GENTLE_PI_SHELL_CHANGES_KEY: "ctrl+shift+g" }), "ctrl+shift+g");
@@ -381,9 +662,10 @@ test("gentleShell keeps the open overlay in sync with git while it stays open",
 	await fire(handlers, "session_start", ctx);
 	const open = commands.get("gentle:changes")!.handler("", ctx);
 	await new Promise((resolve) => setTimeout(resolve, 40));
+	ui.overlayView!.handleInput("\r");
 	const plain = ui.overlayView!.render(100).map(stripAnsi);
-	assert.match(plain[0], /2 files · \+13 −1/);
-	assert.match(plain[2], /lib\/c\.ts/);
+	assert.match(plain[2], /2 files · \+13 −1/);
+	assert.match(plain[3], /lib\/c\.ts/);
 	assert.match(renderFooter(ui), /main ±2/);
 	ui.closeOverlay?.();
 	await open;
@@ -493,6 +775,10 @@ test("gentleShell draws the review preflight message as a Gentle card", () => {
 	const renderer = renderers.get("gentle-pi.review-preflight");
 	assert.ok(renderer, "renderer not registered");
 	const message = { customType: "gentle-pi.review-preflight", content: "Receipt-driven development is enabled.\n\nCall the gentle_review tool." };
+	const sentinelTheme = { ...plainTheme, bg: (_role: string, text: string) => `\x1b[44m${text}\x1b[49m` };
+	for (const expanded of [true, false]) {
+		assert.doesNotMatch(renderer(message, { expanded }, sentinelTheme).render(80).join("\n"), /\x1b\[44m/);
+	}
 	const expanded = renderer(message, { expanded: true }, plainTheme).render(80).map(stripAnsi);
 	assert.match(expanded[0], /^╭─ ✿ Gentle AI · review preflight ─+ .*collapse ╮$/);
 	assert.match(expanded[1], /^│ Receipt-driven development is enabled\. +│$/);
@@ -514,6 +800,11 @@ test("gentleShell keeps a dev-binary override visible above the editor for the w
 	assert.match(lines[1], /^│ \/Users\/me\/go\/bin\/gentle-ai · sha256:6e53bfc6305a3949 +│$/);
 	assert.match(lines[2], /^╰─+╯$/);
 	assert.equal(lines[3], "", "a blank line keeps the card off the prompt frame");
+	const painted = factory(fakeTui, { ...plainTheme, bg: (_role: string, text: string) => `\x1b[44m${text}\x1b[49m` }).render(100);
+	assert.equal(painted[0], lines[0], "top frame cells have no background");
+	assert.equal(painted[1], lines[1], "body interior remains transparent");
+	assert.equal(painted[2], lines[2], "bottom frame cells have no background");
+	assert.equal(painted[3], "", "external spacer has no background");
 	await fire(handlers, "agent_start", ctx);
 	assert.equal(ui.widgets.has("gentle-shell-dev-binary"), false, "the startup notice leaves with the first prompt");
 

package/tests/gentle-todo.test.ts

@@ -1,6 +1,7 @@
 import assert from "node:assert/strict";
 import test from "node:test";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { Component } from "@earendil-works/pi-tui";
 import gentleTodo, { todoCollapseKey, todoEnabled } from "../extensions/gentle-todo.ts";
 import { stripAnsi } from "../lib/terminal-theme.ts";
 
@@ -10,6 +11,7 @@ import { stripAnsi } from "../lib/terminal-theme.ts";
 type Handler = (event: unknown, ctx: ExtensionContext) => unknown;
 
 interface Registered {
+	renderShell?: string;
 	execute(toolCallId: string, params: unknown, signal: undefined, onUpdate: undefined, ctx: ExtensionContext): Promise<{ content: Array<{ type: string; text: string }>; details: Record<string, unknown> }>;
 	renderCall(args: unknown, theme: unknown): { render(width: number): string[] };
 	renderResult(result: unknown, options: { expanded: boolean }, theme: unknown): { render(width: number): string[] };
@@ -24,7 +26,6 @@ const plainTheme = {
 	},
 };
 const fakeTui = { requestRender() {} };
-
 function fakePi() {
 	const handlers = new Map<string, Handler[]>();
 	const tools = new Map<string, Registered>();
@@ -49,22 +50,23 @@ function fakePi() {
 }
 
 function fakeContext(branch: unknown[] = [], hasUI = true) {
-	const widgets = new Map<string, (tui: unknown, theme: unknown) => { render(width: number): string[] }>();
+	const widgets = new Map<string, (tui: unknown, theme: unknown) => Component>();
 	const ctx = {
 		hasUI,
 		sessionManager: { getSessionId: () => "s1", getBranch: () => branch },
 		ui: {
-			setWidget(key: string, content: ((tui: unknown, theme: unknown) => { render(width: number): string[] }) | undefined) {
+			setWidget(key: string, content: ((tui: unknown, theme: unknown) => Component) | undefined) {
 				if (content === undefined) widgets.delete(key);
 				else widgets.set(key, content);
 			},
 		},
 	} as unknown as ExtensionContext;
-	const widget = () => {
+	const widgetComponent = () => {
 		const factory = widgets.get("gentle-todo");
-		return factory ? factory(fakeTui, plainTheme).render(70).map(stripAnsi) : undefined;
+		return factory?.(fakeTui, plainTheme);
 	};
-	return { ctx, widgets, widget };
+	const widget = () => widgetComponent()?.render(70).map(stripAnsi);
+	return { ctx, widgets, widget, widgetComponent };
 }
 
 test("todoEnabled and todoCollapseKey read their environment flags", () => {
@@ -79,6 +81,12 @@ test("todoEnabled and todoCollapseKey read their environment flags", () => {
 	assert.equal(off.tools.size, 0);
 });
 
+test("todo registration owns its transparent transcript shell", () => {
+	const { pi, tools } = fakePi();
+	gentleTodo(pi, {});
+	assert.equal(tools.get("todo")?.renderShell, "self");
+});
+
 test("the todo tool writes the list, shows the card after the call, and carries the snapshot in details", async () => {
 	const { pi, tools, fire } = fakePi();
 	gentleTodo(pi, {});
@@ -92,7 +100,7 @@ test("the todo tool writes the list, shows the card after the call, and carries
 	assert.equal((result.details.gentleTodo as { tasks: unknown[] }).tasks.length, 2);
 	await fire("tool_execution_end", ctx, { toolName: "todo" });
 	const lines = widget()!;
-	assert.match(lines[0], /^╭─ ❀ Todos · 0 of 2 ─+╮$/);
+	assert.match(lines[0], /^╭─ ❀ Todos ▾ Collapse · 0 of 2 ─+ ctrl\+shift\+t collapse ╮$/);
 	assert.match(lines[1], /◐ Write the parser · parsing/);
 	assert.match(lines[2], /○ Add tests/);
 	assert.equal(lines[lines.length - 1], "", "a blank line keeps the card off the prompt");
@@ -104,6 +112,41 @@ test("the todo tool writes the list, shows the card after the call, and carries
 	assert.equal(tool.renderResult({ content: [{ type: "text", text: "a\nb" }] }, { expanded: false }, plainTheme).render(40).join("|").trimEnd(), "a");
 });
 
+test("the Todo header is a fullscreen left-click control while non-click pointer events stay inert", async () => {
+	const { pi, tools, fire } = fakePi();
+	gentleTodo(pi, {});
+	const { ctx, widgetComponent } = fakeContext();
+	await fire("session_start", ctx);
+	await tools.get("todo")!.execute("c1", { action: "write", tasks: [{ title: "A", status: "in_progress" }, { title: "B" }] }, undefined, undefined, ctx);
+	await fire("tool_execution_end", ctx, { toolName: "todo" });
+
+	const component = widgetComponent()!;
+	assert.match(stripAnsi(component.render(70)[0]!), /Todos ▾ Collapse/);
+	const event = (type: "press" | "click", button: "left" | "right", y = 0) => ({
+		type, button, x: 1, y, screenX: 1, screenY: y, width: 70, height: 5, shift: false, alt: false, ctrl: false,
+	});
+	assert.equal(component.handleMouse?.(event("press", "left")), undefined);
+	assert.equal(component.handleMouse?.(event("click", "right")), undefined);
+	assert.equal(component.handleMouse?.(event("click", "left", 1)), undefined);
+	assert.match(stripAnsi(component.render(70)[0]!), /Todos ▾ Collapse/, "only a left click on the header toggles");
+	assert.equal(component.handleMouse?.(event("click", "left"))?.handled, true);
+	assert.match(stripAnsi(component.render(70)[0]!), /Todos ▸ Expand/);
+});
+
+test("the Todo header remains a static visible control without hover handling", async () => {
+	const { pi, tools, fire } = fakePi();
+	gentleTodo(pi, {});
+	const { ctx, widgetComponent } = fakeContext();
+	await fire("session_start", ctx);
+	await tools.get("todo")!.execute("c1", { action: "write", tasks: [{ title: "A" }] }, undefined, undefined, ctx);
+	await fire("tool_execution_end", ctx, { toolName: "todo" });
+	const component = widgetComponent()!;
+	const move = { type: "move" as const, button: "none" as const, x: 1, y: 0, screenX: 1, screenY: 0, width: 70, height: 5, shift: false, alt: false, ctrl: false };
+	assert.match(stripAnsi(component.render(70)[0]!), /Todos ▾ Collapse/);
+	assert.equal(component.handleMouse?.(move), undefined);
+	assert.match(stripAnsi(component.render(70)[0]!), /Todos ▾ Collapse/);
+});
+
 test("every turn carries the open tasks in the system prompt and the card goes stale after two silent turns", async () => {
 	const { pi, tools, fire } = fakePi();
 	gentleTodo(pi, {});
@@ -120,7 +163,8 @@ test("every turn carries the open tasks in the system prompt and the card goes s
 
 	const stale = (await fire("before_agent_start", ctx, { systemPrompt: "base" })) as { systemPrompt: string };
 	assert.match(stale.systemPrompt, /stale: 2 turns without an update/);
-	assert.match(widget()![0], /stale · 2 turns/);
+	assert.match(widget()![0], /ctrl\+shift\+t collapse/);
+	assert.match(widget()![1], /stale · 2 turns/);
 
 	await tools.get("todo")!.execute("c2", { action: "update", id: 1, status: "in_progress", note: "on it" }, undefined, undefined, ctx);
 	await fire("tool_execution_end", ctx, { toolName: "todo" });
@@ -143,7 +187,7 @@ test("a finished list stays for its turn and clears at the next, and the collaps
 	await tools.get("todo")!.execute("c2", { action: "write", tasks: [{ id: 1, title: "A", status: "done" }, { id: 2, title: "B", status: "done" }] }, undefined, undefined, ctx);
 	await fire("tool_execution_end", ctx, { toolName: "todo" });
 	await fire("agent_end", ctx);
-	assert.match(widget()![0], /Todos · 2 of 2/, "the finished list is still visible at the end of its turn");
+	assert.match(widget()![0], /Todos ▾ Collapse · 2 of 2/, "the finished list is still visible at the end of its turn");
 	const next = await fire("before_agent_start", ctx, { systemPrompt: "base" });
 	assert.equal(next, undefined, "nothing open, nothing to add to the prompt");
 	assert.equal(widget(), undefined, "the card clears at the next turn");
@@ -160,7 +204,7 @@ test("session_start replays the list from the branch, rpiv-todo results included
 	const { ctx, widget } = fakeContext(branch);
 	await fire("session_start", ctx);
 	const lines = widget()!;
-	assert.match(lines[0], /Todos · 0 of 1/);
+	assert.match(lines[0], /Todos ▾ Collapse · 0 of 1/);
 	assert.match(lines[1], /◐ Old task · still going/);
 	const headless = fakeContext(branch, false);
 	await fire("session_start", headless.ctx);