gentle-pi 4.2.0 → 4.4.0

package/tests/session-subject-routing-contract.test.ts

@@ -8,7 +8,8 @@ const source = readFileSync(join(root, "extensions/gentle-agents.ts"), "utf8");
 const match = source.match(/name: "orchestrator_session_id",\s*label: "[^"]+",\s*description: ("(?:[^"\\]|\\.)*")/);
 assert.ok(match, "Registered session tool must expose a public description");
 const description: string = JSON.parse(match[1]);
-const detail = readFileSync(join(root, "assets/orchestrator-delegation.md"), "utf8")
+// S11 T2: the session subject rules moved from the delegation card to its reference.
+const detail = readFileSync(join(root, "assets/orchestrator-delegation-reference.md"), "utf8")
 	.split("## Session subject and display identity\n")[1].split("### Publish and find classified work")[0];
 const docs = readFileSync(join(root, "docs/gentle-agents-activity.md"), "utf8")
 	.split("### Declare a recognizable subject\n")[1].split("### Publish curated state")[0];

package/tests/session-worktree-registry.test.ts

@@ -6,7 +6,7 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import test from "node:test";
 import { SessionManager } from "@earendil-works/pi-coding-agent";
-import { SessionWorktreeRegistry, clearSessionWorktreeMemo, memoizeWorktreeResolver, resolveSessionWorktree, resolveSessionWorktreeWithGit, SESSION_WORKTREE_ENTRY, toolWorktreePath, worktreeGitEnvironment } from "../lib/session-worktree-registry.ts";
+import { SessionWorktreeRegistry, clearSessionWorktreeMemo, memoizeWorktreeResolver, resolveSessionWorktree, resolveSessionWorktreeWithGit, SESSION_WORKTREE_ENTRY, nativeRootSpelling, toolWorktreePath, worktreeGitEnvironment } from "../lib/session-worktree-registry.ts";
 import { sessionRepositoryAuthority } from "../lib/bounded-writer-admission.ts";
 
 // All Git and session writes belong to unique fixtures, never the live clone.
@@ -306,3 +306,15 @@ test("memoized identity still observes removal, nested repositories and expiry",
 	counted(join(f.dir, "empty"), f.dir);
 	assert.equal(calls, 4, "a missing repository is never memoized, so bootstrap is observed at once");
 });
+
+test("Windows root spelling accepts forward slashes as the native separator only (gentle-shell#2314)", () => {
+	// Git prints C:/repo while realpath returns C:\\repo; both name the same root.
+	assert.equal(nativeRootSpelling("C:/path/to/sibling-repo", "win32"), "C:\\path\\to\\sibling-repo");
+	assert.equal(nativeRootSpelling("C:\\path\\to\\sibling-repo", "win32"), "C:\\path\\to\\sibling-repo");
+	// Only separators change: dot segments and trailing separators stay non-canonical.
+	assert.equal(nativeRootSpelling("C:/repo/.", "win32"), "C:\\repo\\.");
+	assert.equal(nativeRootSpelling("C:/repo/", "win32"), "C:\\repo\\");
+	// POSIX spelling is untouched; a backslash is an ordinary filename character there.
+	assert.equal(nativeRootSpelling("/srv/repo", "linux"), "/srv/repo");
+	assert.equal(nativeRootSpelling("/srv/re\\po", "darwin"), "/srv/re\\po");
+});

package/tests/shell-bar.test.ts

@@ -219,6 +219,13 @@ test("renderShellBar renders one line with the segments in order", () => {
 	);
 });
 
+test("renderShellBar paints the context gauge with the given gauge roles", () => {
+	const [line] = renderShellBar(model(), taggedTheme, 400, undefined, { ok: "gaugeOk", empty: "gaugeEmpty" });
+	assert.match(line, /<gaugeOk>▰▰▰▰<\/gaugeOk><gaugeEmpty>▱▱▱▱<\/gaugeEmpty>/);
+	const [fallback] = renderShellBar(model(), taggedTheme, 400);
+	assert.match(fallback, /<accent>▰▰▰▰<\/accent><border>▱▱▱▱<\/border>/);
+});
+
 test("renderShellBar colors the brand, model, effort, and gauge by role", () => {
 	const [line] = renderShellBar(model(), taggedTheme, 400);
 	assert.match(line, /<accent>✿ gentle shell<\/accent>/);
@@ -348,7 +355,7 @@ test("renderShellSidebarBar paints the Status card frame with border and the tit
 });
 
 test("sidebar unifies project, captured changes and integrations in one frame", () => {
-	const data = model({ changes: { files: 2, added: 7, deleted: 3, notice: "capture warning" }, statuses: ["MCP connected"] });
+	const data = model({ changes: { files: 2, added: 7, deleted: 3 }, statuses: ["MCP connected"] });
 	const lines = renderShellSidebarBar(data, plainTheme, 46);
 	const text = lines.join("\n");
 	assert.equal(lines.filter((line) => line.startsWith("╭")).length, 1);
@@ -359,7 +366,6 @@ test("sidebar unifies project, captured changes and integrations in one frame",
 		previous = index;
 	}
 	assert.match(text, /2 files.*\+7.*−3/);
-	assert.match(text, /capture warning/);
 	assert.match(text, /\/gentle:changes/);
 	assert.match(text, /main/);
 	for (const width of [1, 8, 24, 46]) assert.ok(renderShellSidebarBar(data, plainTheme, width).every((line) => visibleWidth(line) <= width));
@@ -849,6 +855,19 @@ test("unified below-input float includes optional Changes and sanitized statuses
 	assert.equal(renderShellBelowInputFloat(model(), theme, 140, "alt+u", presentation, changes), undefined);
 });
 
+// The idle Changes row exists only when files are actually tracked; an empty
+// capture — including an unborn-only root, which the tracker never scans — is
+// silence (explained by /gentle:changes on demand), never an instruction row.
+test("the below-input float shows no Changes row without tracked files", (t) => {
+	useCardStyle(t, CARD_STYLE.FLOAT);
+	const theme = withBackground(plainTheme);
+	const presentation = { ...DEFAULT_VISUAL_SETTINGS, headerPlacement: "below-input" as const };
+	const empty = { files: [], added: 0, deleted: 0 };
+	const chrome = renderShellBelowInputFloat(model(), theme, 140, "alt+u", presentation, empty)!;
+	assert.equal(chrome.headerRow, 2, "an empty capture is silence, not a Changes row");
+	assert.doesNotMatch(stripAnsi(chrome.rows.join("\n")), /make a commit to start tracking/);
+});
+
 test("the narrow-layout bottom-only bar stays unchanged in the float style", (t) => {
 	const theme = withBackground(taggedTheme);
 	const data = model({ usage: USAGE_TWO_WINDOWS, statuses: ["mcp ok"] });

package/tests/shell-changes-view.test.ts

@@ -4,6 +4,7 @@ import { TuiAltScreen, visibleWidth, type Terminal, type TuiMouseEvent } from "@
 import { CHANGE_STATUS, DIFF_TOO_LARGE, changesModel, type ChangedFile } from "../lib/shell-changes.ts";
 import { WorktreeChangesView, ChangesView, colorDiff, type ChangesViewDeps } from "../lib/shell-changes-view.ts";
 import { stripAnsi } from "../lib/terminal-theme.ts";
+import { createNativeFullscreenInteraction } from "../lib/native-fullscreen-interaction.ts";
 
 // The changes overlay: files on the left, the selected file's diff on the
 // right, keys at the bottom. Rendering is pure; git access is injected.
@@ -458,7 +459,7 @@ const statusCases = [
 	[CHANGE_STATUS.ADDED, "A", 3, 0],
 	[CHANGE_STATUS.DELETED, "D", 0, 4],
 	[CHANGE_STATUS.RENAMED, "R", 0, 0],
-	[CHANGE_STATUS.UNTRACKED, "??", 5, 0],
+	[CHANGE_STATUS.UNTRACKED, "U", 5, 0],
 ] as const;
 
 for (const [status, code, added, deleted] of statusCases) {
@@ -757,3 +758,138 @@ test("ChangesView.update keeps the selected file, reloads moved diffs, and survi
 	component.handleInput("j");
 	component.handleInput("o");
 });
+
+// Diff-only mode (F): the file column and its separator leave so the diff
+// spans the whole inner width; j/k still walk files, esc returns first.
+function diffOnlyView(overrides: { rows?: number; loadDiff?: (root: string, target: ChangedFile) => Promise<string> } = {}) {
+	const trees = [
+		{ root: "/main", branch: "main", model: changesModel([file("a.ts", 1, 0), file("b.ts", 1, 0)]) },
+		{ root: "/linked", branch: "agent", model: changesModel([file("c.ts", 1, 0)]) },
+	];
+	const events: string[] = [];
+	const component = new WorktreeChangesView(trees, {
+		theme: plainTheme, rows: overrides.rows ?? 10,
+		loadDiff: overrides.loadDiff ?? (async (root, target) => `+${root}:${target.path} ${"x".repeat(80)}`),
+		onOpen: (root, target) => { events.push(`open:${root}:${target.path}`); },
+		onClose: () => { events.push("close"); },
+		onRefresh: () => { events.push("refresh"); },
+		requestRender() {},
+	});
+	return { component, events };
+}
+
+test("F hides the file list and its separator so the diff spans the full inner width", async () => {
+	const { component } = diffOnlyView();
+	component.handleInput("\r");
+	component.handleInput("j");
+	await settle();
+	const normal = component.render(100);
+	assert.match(normal[1]!, /^│ +▾ main · main +│ M a\.ts +│$/, "the normal view keeps the two-pane layout");
+	assert.match(stripAnsi(normal[2]!), /^│ ▸   M a\.ts .*│ \+\/main:a\.ts x+…│$/, "the narrow diff pane clips a long line");
+	assert.match(normal[8]!, /F diff only/);
+	component.handleInput("F");
+	await settle();
+	const wide = component.render(100);
+	assert.equal(wide.length, 10);
+	for (const line of wide) assert.equal(visibleWidth(line), 100);
+	assert.match(wide[1]!, /^│ M a\.ts +│$/, "the path header starts at the frame edge");
+	assert.equal(wide[2]!, `│ ${`+/main:a.ts ${"x".repeat(80)}`.padEnd(96)} │`, "the diff uses the full inner width");
+	assert.doesNotMatch(wide.slice(1, 8).join("\n"), /main · main|│.*│.*│/, "no list column and no separator remain");
+	assert.match(wide[8]!, /F files/);
+	component.handleInput("F");
+	assert.match(component.render(100)[1]!, /▾ main · main/, "F toggles back to the file list");
+});
+
+test("j/k in diff-only mode walk files across worktrees and the path header follows", async () => {
+	const { component } = diffOnlyView();
+	component.handleInput("F");
+	await settle();
+	assert.match(component.render(100)[1]!, /^│ M a\.ts +│$/, "entering on a group header jumps to its first file");
+	component.handleInput("j");
+	await settle();
+	assert.match(component.render(100)[1]!, /^│ M b\.ts +│$/);
+	component.handleInput("j");
+	await settle();
+	assert.match(component.render(100)[1]!, /^│ M c\.ts +│$/, "j crosses into the next worktree's files");
+	assert.match(component.render(100)[2]!, /\+\/linked:c\.ts/);
+	component.handleInput("j");
+	assert.match(component.render(100)[1]!, /^│ M c\.ts +│$/, "the last file stays selected");
+	component.handleInput("k");
+	await settle();
+	assert.match(component.render(100)[1]!, /^│ M b\.ts +│$/);
+	component.handleInput("j");
+	component.handleInput("\x1b");
+	assert.match(component.render(100).join("\n"), /▸   M c\.ts/, "the files view shows the file chosen in diff-only mode");
+});
+
+test("esc leaves diff-only mode before closing; q, o and r keep working there", async () => {
+	const { component, events } = diffOnlyView();
+	component.handleInput("F");
+	component.handleInput("\x1b");
+	assert.deepEqual(events, [], "the first esc only returns to the file list");
+	assert.match(component.render(100)[1]!, /main · main/);
+	component.handleInput("\x1b");
+	assert.deepEqual(events, ["close"]);
+	component.handleInput("F");
+	component.handleInput("o");
+	component.handleInput("r");
+	component.handleInput("q");
+	assert.deepEqual(events, ["close", "open:/main:a.ts", "refresh", "close"]);
+});
+
+test("diff-only mode has no list mouse zone; the wheel scrolls the widened diff", async () => {
+	const long = Array.from({ length: 30 }, (_, index) => `+line ${index}`).join("\n");
+	const { component } = diffOnlyView({ rows: 8, loadDiff: async () => `@@ -0,0 +1,30 @@\n${long}` });
+	component.handleInput("F");
+	await settle();
+	component.render(80);
+	assert.equal(component.handleMouse(mouseButton("move", "none", 3, 2, 8)), undefined, "no hover target");
+	assert.equal(component.handleMouse(mouseButton("click", "left", 3, 2, 8)), undefined, "no click target");
+	assert.match(component.render(80)[1]!, /^│ M a\.ts +│$/, "a click where the list was does not select");
+	assert.deepEqual(component.handleMouse(mouse("wheel", 3, 2, 3, 8)), { handled: true, render: true });
+	assert.doesNotMatch(component.render(80)[2]!, /@@/, "the left edge now scrolls the diff");
+	component.handleInput("\x1b");
+	component.render(80);
+	assert.deepEqual(component.handleMouse(mouse("click", 3, 3, undefined, 8)), { handled: true, render: true }, "leaving diff-only restores the list zone");
+	assert.match(component.render(80)[3]!, /▸   M b\.ts/);
+});
+
+test("the native fullscreen wrapper keeps keyboard, hover, click and wheel on the changes view", async () => {
+	let onInput: ((data: string) => void) | undefined;
+	const terminal: Terminal = {
+		start(input: Parameters<Terminal["start"]>[0]) { onInput = input; }, stop() {}, async drainInput() {}, write() {}, get columns() { return 80; }, get rows() { return 8; }, get kittyProtocolActive() { return false; }, moveBy() {}, hideCursor() {}, showCursor() {}, clearLine() {}, clearFromCursor() {}, clearScreen() {}, setTitle() {}, setProgress() {}, setProgramStatus() {},
+	};
+	const long = Array.from({ length: 30 }, (_, index) => `+line ${index}`).join("\n");
+	let renders = 0;
+	const trees = [{ root: "/main", branch: "main", model: changesModel([file("a.ts", 1, 0), file("b.ts", 1, 0)]) }];
+	const component = new WorktreeChangesView(trees, {
+		theme: { fg: (color: string, text: string) => color === "warning" ? `\x1b[33m${text}\x1b[39m` : text }, rows: 8, loadDiff: async () => `@@ -0,0 +1,30 @@\n${long}`,
+		onOpen() {}, onClose() {}, onRefresh() {}, requestRender() {},
+	});
+	const interaction = createNativeFullscreenInteraction({ keyboardTarget: component, requestRender: () => { renders++; } });
+	interaction.addChild(component);
+	const tui = new TuiAltScreen(terminal, false, undefined, { mouse: true });
+	tui.setLayoutRoot(interaction);
+	tui.start();
+	interaction.handleInput("\r");
+	assert.ok(renders > 0, "keys reach the view and request a render");
+	tui.renderNow(true);
+	try {
+		onInput?.("\x1b[<35;4;4M");
+		assert.match(interaction.render(80)[3]!, /\x1b\[33mM b\.ts/, "hover paints the row under the pointer");
+		onInput?.("\x1b[<0;4;4M");
+		onInput?.("\x1b[<0;4;4m");
+		assert.match(stripAnsi(interaction.render(80)[3]!), /▸   M b\.ts/, "a click selects the file");
+		await settle();
+		tui.renderNow(true);
+		onInput?.("\x1b[<65;60;3M");
+		assert.doesNotMatch(stripAnsi(interaction.render(80)[2]!), /@@/, "the wheel scrolls the diff");
+		interaction.handleInput("F");
+		tui.renderNow(true);
+		onInput?.("\x1b[<0;4;3M");
+		onInput?.("\x1b[<0;4;3m");
+		assert.match(stripAnsi(interaction.render(80)[1]!), /^│ M b\.ts +│$/, "diff-only mode ignores clicks where the list was");
+	} finally {
+		tui.stop();
+	}
+});

package/tests/shell-changes.test.ts

@@ -15,6 +15,7 @@ import {
 	foreignRootBranch,
 	parseWorktrees,
 	changesSummary,
+	changesDigest,
 	emptyChanges,
 	parseNumstat,
 	parsePorcelain,
@@ -101,6 +102,36 @@ test("changesModel sorts files by path and totals the counts", () => {
 	assert.equal(model.deleted, 2);
 });
 
+// The footer Status memo reads the changes digest on every keystroke, so the
+// model stores it once per build and reading it never walks the file list.
+// The digest hashes every per-file tuple the renderer consumes (path, status,
+// counts, diffRevision, countsUnavailable); a 64-bit collision could only
+// skip one refresh until the next change moves it again -- never render a
+// wrong picture.
+test("the changes digest is stored on the model and stays equal while nothing moves", () => {
+	const files = [file("lib/a.ts", 4, 2), file("lib/b.ts", 10, 0, CHANGE_STATUS.ADDED)];
+	const model = changesModel([...files]);
+	assert.equal(Object.hasOwn(model, "digest"), true, "the digest is a stored field, not recomputed per read");
+	assert.equal(model.digest, changesDigest(model), "the stored digest matches an independently computed one");
+	assert.equal(changesModel([...files]).digest, model.digest, "an unchanged model rebuilds to the same digest");
+	assert.equal(emptyChanges().digest, emptyChanges().digest, "the empty model carries a stable digest");
+});
+
+test("the changes digest moves with every per-file detail the renderer consumes", () => {
+	const base = changesModel([file("lib/a.ts", 4, 2)]).digest;
+	const digestFor = (files: ChangedFile[]) => changesModel(files).digest!;
+	assert.notEqual(digestFor([file("lib/a.ts", 4, 2, CHANGE_STATUS.RENAMED)]), base, "a status change moves the digest even at equal counts");
+	assert.notEqual(digestFor([file("lib/a.ts", 5, 2)]), base, "an added-count change moves the digest");
+	assert.notEqual(digestFor([file("lib/a.ts", 4, 3)]), base, "a deleted-count change moves the digest");
+	assert.notEqual(digestFor([file("lib/b.ts", 4, 2)]), base, "a path change moves the digest");
+	const revised = file("lib/a.ts", 4, 2);
+	revised.diffRevision = "abc123";
+	assert.notEqual(digestFor([revised]), base, "a diffRevision change moves the digest");
+	const partial = file("lib/a.ts", 4, 2);
+	partial.countsUnavailable = "timeout";
+	assert.notEqual(digestFor([partial]), base, "countsUnavailable moves the digest");
+});
+
 test("changesSummary and the widget describe the session at a glance", () => {
 	const model = changesModel([file("extensions/gentle-shell.ts", 31, 0, CHANGE_STATUS.ADDED), file("lib/shell-bar.ts", 9, 7), file("tests/x.test.ts", 2, 0)]);
 	assert.equal(changesSummary(model), "3 files · +42 −7");
@@ -121,6 +152,14 @@ test("renderChangesWidget colors counts by direction and yields nothing when cle
 	assert.deepEqual(renderChangesWidget(emptyChanges(), plainTheme, 120), []);
 });
 
+// The unborn state (no commits yet) is silence in the idle bar: the widget
+// renders only tracked files, and /gentle:changes explains the state on demand.
+test("renderChangesWidget stays silent when nothing is tracked", () => {
+	assert.deepEqual(renderChangesWidget(emptyChanges(), plainTheme, 120), []);
+	assert.deepEqual(renderChangesWidget(emptyChanges(), taggedTheme, 400), []);
+	assert.deepEqual(renderChangesWidget(emptyChanges(), plainTheme, 12), []);
+});
+
 test("renderChangesWidget drops the file list before truncating on narrow terminals", () => {
 	const model = changesModel([file("a/very/long/path/one.ts", 1, 0), file("a/very/long/path/two.ts", 1, 0)]);
 	const [line] = renderChangesWidget(model, plainTheme, 40);
@@ -132,6 +171,67 @@ test("renderChangesWidget drops the file list before truncating on narrow termin
 	assert.match(tiny, /^✎ 2 files/);
 });
 
+// Repeated frames hit the widget from two surfaces (the sidebar part and the
+// below-input header row), but its paint depends only on what the model digest
+// already covers plus the width and the theme. A counting theme is the seam: a
+// cache hit paints nothing, so theme.fg stays silent instead of walking files.
+function countingTheme() {
+	let calls = 0;
+	return {
+		get fgCalls() {
+			return calls;
+		},
+		fg(_color: string, text: string) {
+			calls += 1;
+			return text;
+		},
+	};
+}
+
+test("renderChangesWidget memoizes a frame per digest, width and theme so an unchanged model repaints nothing", () => {
+	const model = changesModel([file("lib/a.ts", 4, 2), file("lib/b.ts", 10, 0, CHANGE_STATUS.ADDED)]);
+	const theme = countingTheme();
+	const first = renderChangesWidget(model, theme, 120);
+	assert.ok(theme.fgCalls > 0, "the first render paints");
+	const afterFirst = theme.fgCalls;
+	const second = renderChangesWidget(model, theme, 120);
+	assert.deepEqual(second, first, "an unchanged model, width and theme return the same rows");
+	assert.equal(theme.fgCalls, afterFirst, "a memo hit repaints nothing: no per-file iteration");
+});
+
+test("renderChangesWidget re-renders when the digest moves", () => {
+	const theme = countingTheme();
+	const before = changesModel([file("lib/a.ts", 4, 2)]);
+	renderChangesWidget(before, theme, 120);
+	const afterFirst = theme.fgCalls;
+	const moved = changesModel([file("lib/a.ts", 5, 2)]);
+	assert.notEqual(moved.digest, before.digest, "a count change moves the digest");
+	const lines = renderChangesWidget(moved, theme, 120);
+	assert.ok(theme.fgCalls > afterFirst, "a digest change re-renders");
+	assert.match(lines.join("\n"), /\+5/, "the re-render shows the new totals");
+});
+
+test("renderChangesWidget re-renders when the width or the theme changes", () => {
+	const model = changesModel([file("lib/a.ts", 4, 2)]);
+	const theme = countingTheme();
+	const wide = renderChangesWidget(model, theme, 400);
+	const afterWide = theme.fgCalls;
+	renderChangesWidget(model, theme, 40);
+	assert.ok(theme.fgCalls > afterWide, "a width change re-renders");
+	const otherTheme = countingTheme();
+	assert.deepEqual(renderChangesWidget(model, otherTheme, 400), wide, "a new theme object repaints the same wide frame");
+	assert.ok(otherTheme.fgCalls > 0, "the new theme did the painting");
+});
+
+test("renderChangesWidget never caches a digest-less model", () => {
+	const model = { files: [file("lib/a.ts", 4, 2)], added: 4, deleted: 2 };
+	const theme = countingTheme();
+	renderChangesWidget(model, theme, 120);
+	const afterFirst = theme.fgCalls;
+	renderChangesWidget(model, theme, 120);
+	assert.ok(theme.fgCalls > afterFirst, "a hand-built model without a digest re-renders every call");
+});
+
 function fakeGit(numstats: string[], porcelains: string[], code = 0) {
 	const calls: string[][] = [];
 	let round = 0;
@@ -336,7 +436,6 @@ test("foreignRootBranch still reports a genuine detached HEAD as undefined, not
 test("a root missing from worktree list resolves its own branch instead of defaulting to detached", async (t) => {
 	const scenarios: Array<{ name: string; symbolic: { stdout: string; code: number }; verify: { stdout: string; code: number }; expected: string | undefined }> = [
 		{ name: "a normal branch on a foreign clone", symbolic: { stdout: "feature\n", code: 0 }, verify: { stdout: "deadbeef\n", code: 0 }, expected: "feature" },
-		{ name: "an unborn branch (no commits yet)", symbolic: { stdout: "main\n", code: 0 }, verify: { stdout: "", code: 1 }, expected: "no commits yet" },
 		{ name: "a genuinely detached HEAD", symbolic: { stdout: "", code: 1 }, verify: { stdout: "deadbeef\n", code: 0 }, expected: undefined },
 	];
 	for (const scenario of scenarios) {
@@ -358,9 +457,57 @@ test("a root missing from worktree list resolves its own branch instead of defau
 			assert.deepEqual(tracker.worktrees.map((tree) => [tree.root, tree.branch]), [["/foreign", scenario.expected]]);
 			assert.ok(calls.some((args) => args[0] === "symbolic-ref"), "a root absent from worktree list must be asked directly");
 		});
+		// An unborn foreign root is a holder before it is a branch question: with
+		// no commits there is no baseline to diff against, so it is skipped --
+		// neither dirty nor failed -- before any branch lookup happens.
+		await t.test("an unborn foreign root is skipped as a holder before the branch ask", async () => {
+			const calls: string[][] = [];
+			const tracker = new WorktreeChangesTracker(
+				async () => ({ stdout: "", code: 0 }),
+				() => async (args) => {
+					calls.push(args);
+					if (args[0] === "rev-parse") return { stdout: "", code: 1 };
+					return { stdout: "", code: 0 };
+				},
+				undefined,
+				() => ["/foreign"],
+			);
+			await tracker.start();
+			assert.deepEqual(tracker.worktrees, []);
+			assert.deepEqual(tracker.unbornRoots, ["/foreign"]);
+			assert.deepEqual(tracker.failedRoots, []);
+			assert.ok(!calls.some((args) => args[0] === "symbolic-ref"), "a skipped holder is never asked for a branch");
+		});
 	}
 });
 
+// A worktree-holder repository (no commits, only linked worktrees inside) has
+// no baseline: `git diff HEAD` is meaningless and every file reports
+// untracked, so scanning it floods Changes with thousands of phantom files.
+// It is skipped as neither dirty nor failed, and its first commit starts
+// tracking it on the next scan.
+test("a root with no commits is skipped as a holder, neither dirty nor failed, and recovers on its first commit", async () => {
+	let holderHasCommits = false;
+	const tracker = new WorktreeChangesTracker(
+		async () => ({ stdout: "worktree /real\0branch refs/heads/main\0\0", code: 0 }),
+		(root) => async (args) => {
+			if (args[0] === "rev-parse") return { stdout: "", code: root === "/holder" && !holderHasCommits ? 1 : 0 };
+			return { stdout: args[0] === "status" && (root === "/real" || (root === "/holder" && holderHasCommits)) ? "?? a.ts\0" : "", code: 0 };
+		},
+		undefined,
+		() => ["/holder", "/real"],
+	);
+	await tracker.start();
+	assert.deepEqual(tracker.worktrees.map((tree) => tree.root), ["/real"], "an unborn root is skipped, not scanned");
+	assert.deepEqual(tracker.unbornRoots, ["/holder"]);
+	assert.deepEqual(tracker.failedRoots, [], "no commits is not a Git failure");
+	assert.equal(tracker.scannedRootCount, 2);
+	holderHasCommits = true;
+	await tracker.refresh();
+	assert.deepEqual(tracker.worktrees.map((tree) => tree.root), ["/holder", "/real"], "the first commit starts tracking");
+	assert.deepEqual(tracker.unbornRoots, []);
+});
+
 // The direct per-root ask (for a root missing from worktree list) can fail on
 // its own -- root gone, git unavailable -- independently of the change scan
 // that already found real files. That failure must label the root

package/tests/shell-gauge.test.ts

@@ -0,0 +1,42 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { paintGauge, renderGauge, type GaugePaint } from "../lib/shell-gauge.ts";
+
+// Issue #2222: gauge-specific theme roles fall back to today's roles when a
+// theme does not define them, so existing themes render byte-identically.
+// (Fixtures here are unit-scoped stubs; Pi's theme schema is validated
+// separately by the loader and was checked directly against ThemeJsonSchema.)
+
+const taggedTheme = {
+	fg(color: string, text: string) {
+		return `<${color}>${text}</${color}>`;
+	},
+};
+
+test("paintGauge falls back to today's roles when no gauge roles are given", () => {
+	assert.equal(paintGauge(45, taggedTheme), `<accent>▰▰▰▰</accent><border>▱▱▱▱</border>`);
+	assert.equal(paintGauge(85, taggedTheme), `<warning>▰▰▰▰▰▰▰</warning><border>▱</border>`);
+	assert.equal(paintGauge(96, taggedTheme), `<error>▰▰▰▰▰▰▰▰</error><border></border>`);
+	assert.equal(paintGauge(null, taggedTheme), `<dim></dim><border>▱▱▱▱▱▱▱▱</border>`);
+});
+
+test("paintGauge uses the gauge-specific roles when the theme defines them", () => {
+	const roles: GaugePaint = { ok: "gaugeOk", warning: "gaugeWarning", error: "gaugeError", empty: "gaugeEmpty" };
+	assert.equal(paintGauge(45, taggedTheme, 8, roles), `<gaugeOk>▰▰▰▰</gaugeOk><gaugeEmpty>▱▱▱▱</gaugeEmpty>`);
+	assert.equal(paintGauge(85, taggedTheme, 8, roles), `<gaugeWarning>▰▰▰▰▰▰▰</gaugeWarning><gaugeEmpty>▱</gaugeEmpty>`);
+	assert.equal(paintGauge(96, taggedTheme, 8, roles), `<gaugeError>▰▰▰▰▰▰▰▰</gaugeError><gaugeEmpty></gaugeEmpty>`);
+	// A null percentage stays dim: there is nothing to gauge yet.
+	assert.equal(paintGauge(null, taggedTheme, 8, roles), `<dim></dim><gaugeEmpty>▱▱▱▱▱▱▱▱</gaugeEmpty>`);
+});
+
+test("paintGauge falls back per role, not per block", () => {
+	// A theme that defines only gaugeWarning keeps accent for the ok range.
+	assert.equal(paintGauge(45, taggedTheme, 8, { warning: "gaugeWarning" }), `<accent>▰▰▰▰</accent><border>▱▱▱▱</border>`);
+	assert.equal(paintGauge(85, taggedTheme, 8, { warning: "gaugeWarning" }), `<gaugeWarning>▰▰▰▰▰▰▰</gaugeWarning><border>▱</border>`);
+});
+
+test("renderGauge uses theme-defined glyphs when given, defaults otherwise", () => {
+	assert.equal(renderGauge(50, 4, { filled: "█", empty: "░" }), "██░░");
+	assert.equal(renderGauge(50, 4), "▰▰▱▱");
+	assert.equal(renderGauge(50, 4, { filled: "█" }), "██▱▱");
+});

package/tests/shell-prompt.test.ts

@@ -8,15 +8,15 @@ import {
 	PROMPT_STATE,
 	petalGlyph,
 	petalTone,
-	SHELL_PULSE_MS,
+	SHELL_PULSE_WATCHDOG_MS,
 	SHELL_SCANNER_STEPS,
 	withPromptHint,
 	type PromptFrameOptions,
 } from "../lib/shell-prompt.ts";
 
-test("scanner reflects a symmetric light wave across working text at Pi's original cadence", () => {
+test("scanner reflects a symmetric light wave across working text at the watchdog cadence", () => {
 	const fg = (role: string, char: string) => `<${role}>${char}</${role}>`;
-	assert.equal(SHELL_PULSE_MS, 80);
+	assert.equal(SHELL_PULSE_WATCHDOG_MS, 1000);
 	assert.equal(SHELL_SCANNER_STEPS, 15);
 	for (const word of ["working…", "Thinking…"]) {
 		for (let tick = 0; tick < SHELL_SCANNER_STEPS; tick++) {

package/tests/shell-render-cache.test.ts

@@ -1,7 +1,11 @@
 import assert from "node:assert/strict";
 import test from "node:test";
 import { initTheme, type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { buildShellBarModel, type ShellFooterData } from "../extensions/gentle-shell.ts";
+import { buildShellBarModel, createFooterStatusMemo, type ShellFooterData } from "../extensions/gentle-shell.ts";
+import { CHANGE_STATUS } from "../lib/shell-changes.ts";
+import type { RunningJobDisplay } from "../lib/jobs-sidebar-state.ts";
+import type { ReviewSidebarSnapshot } from "../lib/review-sidebar-state.ts";
+import type { ProviderUsage } from "../lib/shell-usage.ts";
 import { createQuietToolRenderer } from "../extensions/quiet-tools.ts";
 import { CARD_STYLE, cardStyle, setCardStyle } from "../lib/shell-card.ts";
 
@@ -127,3 +131,132 @@ test("image renderers keep their live geometry instead of caching opaque compone
 		{ expanded: true, isPartial: false }, theme as never, {} as never);
 	assert.notDeepEqual(card.render(80), card.render(80));
 });
+
+function footerMemoFixture() {
+	let reads = 0;
+	let projections = 0;
+	let leaf = "leaf-1";
+	const entries = [{ type: "message", message: { role: "assistant", usage: { cost: { total: 1 } } } }];
+	// One stable model object, replaced only by setModelId: real hosts keep the
+	// model identity stable, and sessionStatsKey compares it by identity.
+	let model: { id: string; contextWindow: number } = { id: "model", contextWindow: 1000 };
+	const ctx = {
+		get model() { return model; },
+		getContextUsage() { projections++; return { percent: 10, contextWindow: 1000 }; },
+		modelRegistry: { isUsingOAuth: () => false },
+		sessionManager: {
+			getEntries() { reads++; return [...entries]; },
+			getEntryCount: () => entries.length,
+			getSessionId: () => "session-1",
+			getLeafId: () => leaf,
+			getCwd: () => "/repo",
+			getSessionName: () => "session",
+		},
+	};
+	let branch: string | null = "main";
+	let statuses = new Map<string, string>();
+	let usage: ProviderUsage | undefined;
+	let added = 0;
+	let deleted = 0;
+	let unbornRoots = 0;
+	let review: ReviewSidebarSnapshot | undefined;
+	let jobs: RunningJobDisplay[] | undefined;
+	let settings: unknown = { statusPlacement: "auto" };
+	let style: unknown = "comfortable";
+	const footerData = { getGitBranch: () => branch, getExtensionStatuses: () => statuses } as unknown as ShellFooterData;
+	let profile: string | undefined = "team";
+	const memo = createFooterStatusMemo({
+		pi, ctx: ctx as unknown as ExtensionContext, footerData,
+		usage: () => usage,
+		profile: () => profile,
+		jobs: () => jobs,
+		review: () => review,
+		tracker: () => ({ model: { files: [{ path: "a.ts", status: CHANGE_STATUS.MODIFIED, added, deleted }], added, deleted }, unbornRoots: Array.from({ length: unbornRoots }, () => "root") }),
+		visualSettings: () => settings,
+		cardStyle: () => style,
+	});
+	return {
+		ctx: ctx as unknown as ExtensionContext & { sessionManager: { getLeafId?: () => string } },
+		memo,
+		counts: () => [reads, projections],
+		setLeaf: (value: string) => { leaf = value; },
+		spend: () => { entries[0]!.message.usage.cost.total += 1; },
+		setModelId: (value: string) => { model = { ...model, id: value }; },
+		setProfile: (value: string | undefined) => { profile = value; },
+		setBranch: (value: string | null) => { branch = value; },
+		setStatuses: (value: Map<string, string>) => { statuses = value; },
+		setUsage: (value: ProviderUsage | undefined) => { usage = value; },
+		setChangeCounts: (nextAdded: number, nextDeleted: number) => { added = nextAdded; deleted = nextDeleted; },
+		setUnbornRoots: (value: number) => { unbornRoots = value; },
+		setReview: (value: ReviewSidebarSnapshot | undefined) => { review = value; },
+		setJobs: (value: RunningJobDisplay[] | undefined) => { jobs = value; },
+		setSettings: (value: unknown) => { settings = value; },
+		setStyle: (value: unknown) => { style = value; },
+	};
+}
+
+test("the footer status memo reuses one model while live inputs hold still", () => {
+	const f = footerMemoFixture();
+	const first = f.memo.model();
+	assert.equal(first.costTotal, 1);
+	assert.deepEqual(first.changes, { files: 1, added: 0, deleted: 0 });
+	for (let frame = 0; frame < 10; frame++) assert.equal(f.memo.model(), first, "stable inputs reuse the built model");
+	assert.deepEqual(f.counts(), [1, 1], "warm frames never rescan the session");
+});
+
+test("the footer status digest key notices every live input the model reads", () => {
+	const f = footerMemoFixture();
+	const before = f.memo.key();
+	assert.equal(f.memo.key(), before, "the key is deterministic while nothing moves");
+	const mutations: Array<[string, () => void]> = [
+		["branch", () => f.setBranch("feature")],
+		["profile", () => f.setProfile("other (local)")],
+		["statuses", () => f.setStatuses(new Map([["jobs", "1 running"]]))],
+		["usage", () => f.setUsage({ provider: "p", plan: undefined, limits: [], fetchedAt: 1 })],
+		["change counts", () => f.setChangeCounts(2, 1)],
+		["unborn roots", () => f.setUnbornRoots(1)],
+		["review", () => f.setReview({ state: "open", scope: undefined } as unknown as ReviewSidebarSnapshot)],
+		["jobs", () => f.setJobs([{ id: "j", label: "l", startedAt: 0 }])],
+		["visual settings", () => f.setSettings({ statusPlacement: "bottom" })],
+		["card style", () => f.setStyle("compact")],
+		["model", () => f.setModelId("new-model")],
+		["cwd", () => (f.ctx.sessionManager as { getCwd(): string }).getCwd = () => "/other"],
+		["session name", () => (f.ctx.sessionManager as { getSessionName(): string }).getSessionName = () => "renamed"],
+		["leaf", () => f.setLeaf("leaf-2")],
+	];
+	let previous = before;
+	for (const [name, mutate] of mutations) {
+		mutate();
+		const current = f.memo.key();
+		assert.notEqual(current, previous, `a moved ${name} changes the digest key`);
+		previous = current;
+	}
+	// A branch or profile move rebuilds the model without rescanning statistics:
+	// the model object identity stays stable across those rebuilds.
+	const settled = f.memo.model();
+	const [reads, projections] = f.counts();
+	f.setBranch("release");
+	assert.notEqual(f.memo.model(), settled);
+	assert.deepEqual(f.counts(), [reads, projections]);
+});
+
+test("a moved leaf rebuilds the footer model with fresh statistics", () => {
+	const f = footerMemoFixture();
+	const first = f.memo.model();
+	f.setLeaf("leaf-2");
+	const second = f.memo.model();
+	assert.notEqual(second, first);
+	assert.deepEqual(f.counts(), [2, 2]);
+	assert.equal(f.memo.model(), second, "the fresh model is memoized again");
+});
+
+test("hosts without leaf identity stay honest through the digest key's values", () => {
+	const f = footerMemoFixture();
+	assert.equal(f.memo.key(), f.memo.key(), "the key stays deterministic on uncached hosts");
+	Reflect.deleteProperty(f.ctx.sessionManager, "getLeafId");
+	const first = f.memo.model();
+	f.spend();
+	const second = f.memo.model();
+	assert.notEqual(second, first, "a changed cost value rebuilds the model without leaf identity");
+	assert.equal(second.costTotal, 2);
+});