gentle-pi 3.2.0 → 3.3.0

package/tests/shell-bar.test.ts

@@ -2,11 +2,13 @@ import assert from "node:assert/strict";
 import test from "node:test";
 import { visibleWidth } from "@earendil-works/pi-tui";
 import {
+	buildShellHeaderModel,
 	formatCost,
 	formatTokens,
 	gaugeTone,
 	renderGauge,
 	renderShellBar,
+	renderShellHeaderBar,
 	renderShellSidebarBar,
 	shellEnabled,
 	type ShellBarModel,
@@ -81,13 +83,13 @@ test("renderShellBar renders one line with the segments in order", () => {
 	assert.equal(rest.length, 0);
 	assert.equal(
 		line,
-		"✿ gentle-pi ⟡ ~/work/gentle-pi main ⟡ gpt-5.5 · medium ⟡ ctx ▰▰▰▰▱▱▱▱ 45% ⟡ $9.49 sub",
+		"✿ gentle shell ⟡ ~/work/gentle-pi main ⟡ gpt-5.5 · medium ⟡ ctx ▰▰▰▰▱▱▱▱ 45% ⟡ $9.49 sub",
 	);
 });
 
 test("renderShellBar colors the brand, model, effort, and gauge by role", () => {
 	const [line] = renderShellBar(model(), taggedTheme, 400);
-	assert.match(line, /<accent>✿ gentle-pi<\/accent>/);
+	assert.match(line, /<accent>✿ gentle shell<\/accent>/);
 	assert.match(line, /<text>gpt-5\.5<\/text>/);
 	assert.match(line, /<syntaxFunction>medium<\/syntaxFunction>/);
 	assert.match(line, /<accent>▰▰▰▰<\/accent><border>▱▱▱▱<\/border>/);
@@ -120,6 +122,36 @@ test("renderShellBar adds the subscription windows after the cost when usage is
 	assert.match(line, /\$9\.49 sub ⟡ codex 5h ▰▰▰▰▰▱▱▱ 62% · week 31%$/);
 });
 
+test("renderShellBar meters the model the session is using inside a multi-model provider", () => {
+	const usage = {
+		provider: "nan",
+		plan: undefined,
+		fetchedAt: 0,
+		limits: [
+			{ name: "deepseek-v4-flash", limitReached: false, windows: [{ label: "", usedPercent: 18, windowSeconds: 0, resetAt: null, used: 545_000_000, budget: 3_000_000_000 }] },
+			{ name: "glm5.3-flash", limitReached: false, windows: [{ label: "", usedPercent: 10, windowSeconds: 0, resetAt: null, used: 200_000_000, budget: 2_000_000_000 }] },
+		],
+	};
+	const [glm] = renderShellBar(model({ modelId: "glm5.3-flash", usage }), plainTheme, 200);
+	assert.match(glm, /glm5\.3-flash ▰▱▱▱▱▱▱▱ 10%$/);
+	assert.doesNotMatch(glm, /deepseek-v4-flash ▰/);
+	const [other] = renderShellBar(model({ modelId: "deepseek-v4-flash", usage }), plainTheme, 200);
+	assert.match(other, /deepseek-v4-flash ▰▱▱▱▱▱▱▱ 18%$/);
+});
+
+test("renderShellBar keeps its own zero-window contract independent of the sidebar", () => {
+	const usage = {
+		provider: "openai-codex",
+		plan: "pro",
+		fetchedAt: 0,
+		limits: [{ name: "codex", limitReached: false, windows: [
+			{ label: "5h", usedPercent: 0, windowSeconds: 18_000, resetAt: null },
+			{ label: "week", usedPercent: 0, windowSeconds: 604_800, resetAt: null },
+		] }],
+	};
+	assert.match(renderShellBar(model({ usage }), plainTheme, 200)[0], /codex 5h ▱▱▱▱▱▱▱▱ 0% · week 0%$/);
+});
+
 test("renderShellBar shows an unknown context as a question mark after compaction", () => {
 	const [line] = renderShellBar(model({ contextPercent: null }), plainTheme, 160);
 	assert.match(line, /ctx ▱▱▱▱▱▱▱▱ \?%/);
@@ -162,7 +194,7 @@ test("renderShellBar drops the session name, then trailing segments, before trun
 
 	const [atFifty] = renderShellBar(wide, plainTheme, 50);
 	assert.ok(visibleWidth(atFifty) <= 50, `line overflowed: ${visibleWidth(atFifty)}`);
-	assert.match(atFifty, /^✿ gentle-pi/);
+	assert.match(atFifty, /^✿ gentle shell/);
 });
 
 test("shellEnabled stays off inside a Gentle Agents child", () => {
@@ -176,13 +208,20 @@ test("shellEnabled honors GENTLE_PI_SHELL=0", () => {
 	assert.equal(shellEnabled({ GENTLE_PI_SHELL: "false" }), false);
 });
 
-test("sidebar unifies project, captured changes, usage and integrations in one frame", () => {
+test("renderShellSidebarBar paints the Status card frame with border and the title with accent", () => {
+	const lines = renderShellSidebarBar(model(), taggedTheme, 46);
+	assert.match(lines[0], /^<border>╭<\/border>/);
+	assert.match(lines[0], /<accent>✿ Status<\/accent>/);
+	assert.match(lines[lines.length - 1], /^<border>╰<\/border>/);
+});
+
+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 lines = renderShellSidebarBar(data, plainTheme, 46);
 	const text = lines.join("\n");
 	assert.equal(lines.filter((line) => line.startsWith("╭")).length, 1);
 	let previous = -1;
-	for (const heading of ["Status", "Project", "Changes", "Usage", "Integrations"]) {
+	for (const heading of ["Status", "Project", "Changes", "Integrations"]) {
 		const index = text.indexOf(heading);
 		assert.ok(index > previous, heading);
 		previous = index;
@@ -190,7 +229,7 @@ test("sidebar unifies project, captured changes, usage and integrations in one f
 	assert.match(text, /2 files.*\+7.*−3/);
 	assert.match(text, /capture warning/);
 	assert.match(text, /\/gentle:changes/);
-	assert.match(text, /gpt-5\.5/);
+	assert.match(text, /main/);
 	for (const width of [1, 8, 24, 46]) assert.ok(renderShellSidebarBar(data, plainTheme, width).every((line) => visibleWidth(line) <= width));
 	const empty = renderShellSidebarBar(model(), plainTheme, 46).join("\n");
 	assert.match(empty, /No captured changes/);
@@ -209,3 +248,182 @@ test("sidebar profile wraps long names without changing the compact bar", () =>
 	}
 	assert.deepEqual(renderShellBar(active, plainTheme, 120), renderShellBar(base, plainTheme, 120));
 });
+
+test("sidebar Status card drops Model, Effort, Context, Cost and Usage, keeping Project, Changes and Integrations", () => {
+	const usage = {
+		provider: "openai-codex",
+		plan: "pro",
+		fetchedAt: 0,
+		limits: [{ name: "codex", limitReached: false, windows: [{ label: "5h", usedPercent: 62, windowSeconds: 18_000, resetAt: null }] }],
+	};
+	const data = model({ profile: "team", sessionName: "session", usage, changes: { files: 1, added: 2, deleted: 1 }, statuses: ["MCP connected"] });
+	const text = renderShellSidebarBar(data, plainTheme, 60).join("\n");
+	assert.doesNotMatch(text, /Usage/);
+	assert.doesNotMatch(text, /Model/);
+	assert.doesNotMatch(text, /Effort/);
+	assert.doesNotMatch(text, /Context/);
+	assert.doesNotMatch(text, /Cost/);
+	assert.doesNotMatch(text, /\$9\.49/);
+	assert.doesNotMatch(text, /codex 5h/);
+	for (const heading of ["Status", "Project", "Changes", "Integrations"]) assert.match(text, new RegExp(heading));
+	assert.match(text, /Branch.*main/);
+	assert.match(text, /Session.*session/);
+	assert.match(text, /Profile.*team/);
+});
+
+// The live header row above the fullscreen rail: identity on the left (brand,
+// location, model · effort · profile), the per-frame counters right-aligned
+// (context gauge, cost). Never the working/thinking state or extension
+// statuses — those stay in the prompt and the Status card.
+
+test("buildShellHeaderModel keeps only the header's fields from the bar model", () => {
+	const header = buildShellHeaderModel(model({ profile: "team", statuses: ["MCP: 3 servers"] }));
+	assert.deepEqual(header, {
+		cwd: "~/work/gentle-pi",
+		branch: "main",
+		dirty: undefined,
+		modelId: "gpt-5.5",
+		effort: "medium",
+		profile: "team",
+		contextPercent: 45,
+		costTotal: 9.49,
+		subscription: true,
+		usage: undefined,
+	});
+	assert.ok(!("statuses" in header), "extension statuses never reach the header");
+});
+
+test("renderShellHeaderBar draws the brand, identity, and right-aligned counters (plus the standing usage segment) in one line", () => {
+	const header = buildShellHeaderModel(model({ profile: "team" }));
+	const { text: line } = renderShellHeaderBar(header, plainTheme, 120);
+	const left = "✿ Gentle Shell ⟡ ~/work/gentle-pi main ⟡ gpt-5.5 · medium · team";
+	const right = "ctx ▰▰▰▰▱▱▱▱ 45% ⟡ $9.49 sub ⟡ usage";
+	assert.equal(line, left + " ".repeat(120 - visibleWidth(left) - visibleWidth(right)) + right);
+	assert.equal(visibleWidth(line), 120);
+});
+
+test("renderShellHeaderBar never shows working state or extension statuses", () => {
+	const header = buildShellHeaderModel(model({ statuses: ["MCP: 3 servers", "working…"] }));
+	const { text: line } = renderShellHeaderBar(header, plainTheme, 120);
+	assert.doesNotMatch(line, /MCP: 3 servers/);
+	assert.doesNotMatch(line, /working/);
+});
+
+test("renderShellHeaderBar colors the brand bold and by role", () => {
+	const bolding = { fg: (color: string, text: string) => `<${color}>${text}</${color}>`, bold: (text: string) => `**${text}**` };
+	const header = buildShellHeaderModel(model());
+	const { text: line } = renderShellHeaderBar(header, bolding, 120);
+	assert.match(line, /<accent>\*\*✿ Gentle Shell\*\*<\/accent>/);
+});
+
+test("renderShellHeaderBar drops the profile, then the effort, then the whole location before the right group", () => {
+	const withProfile = buildShellHeaderModel(model({ profile: "team" }));
+	const { text: wide } = renderShellHeaderBar(withProfile, plainTheme, 120);
+	assert.match(wide, /gpt-5\.5 · medium · team/);
+	assert.match(wide, /~\/work\/gentle-pi main/);
+	assert.match(wide, /ctx ▰▰▰▰▱▱▱▱ 45% ⟡ \$9\.49 sub ⟡ usage$/);
+
+	// 100 cols: the profile no longer fits, but effort and location still do.
+	const { text: noProfile } = renderShellHeaderBar(withProfile, plainTheme, 100);
+	assert.doesNotMatch(noProfile, /team/);
+	assert.match(noProfile, /gpt-5\.5 · medium/);
+	assert.match(noProfile, /~\/work\/gentle-pi main/);
+	assert.equal(visibleWidth(noProfile), 100);
+
+	// 90 cols: effort goes too, only the bare model id remains next to location.
+	const { text: noEffort } = renderShellHeaderBar(withProfile, plainTheme, 90);
+	assert.doesNotMatch(noEffort, /medium/);
+	assert.doesNotMatch(noEffort, /team/);
+	assert.match(noEffort, /gpt-5\.5/);
+	assert.match(noEffort, /~\/work\/gentle-pi main/);
+	assert.equal(visibleWidth(noEffort), 90);
+
+	// 82 cols: the whole location segment goes; brand and model survive with the counters.
+	const { text: noLocation } = renderShellHeaderBar(withProfile, plainTheme, 82);
+	assert.doesNotMatch(noLocation, /~\/work\/gentle-pi/);
+	assert.match(noLocation, /gpt-5\.5/);
+	assert.match(noLocation, /✿ Gentle Shell/);
+	assert.match(noLocation, /ctx ▰▰▰▰▱▱▱▱ 45% ⟡ \$9\.49 sub ⟡ usage$/);
+	assert.equal(visibleWidth(noLocation), 82);
+
+	// 60 cols: even the standing usage segment is gone now; brand+model and ctx/cost survive.
+	const { text: noUsage } = renderShellHeaderBar(withProfile, plainTheme, 60);
+	assert.doesNotMatch(noUsage, /~\/work\/gentle-pi/);
+	assert.doesNotMatch(noUsage, /usage/);
+	assert.match(noUsage, /gpt-5\.5/);
+	assert.match(noUsage, /✿ Gentle Shell/);
+	assert.match(noUsage, /ctx ▰▰▰▰▱▱▱▱ 45% ⟡ \$9\.49 sub$/);
+	assert.equal(visibleWidth(noUsage), 60);
+});
+
+test("renderShellHeaderBar returns an empty string only once the brand itself cannot fit", () => {
+	assert.equal(renderShellHeaderBar(buildShellHeaderModel(model()), plainTheme, 3).text, "");
+	assert.match(renderShellHeaderBar(buildShellHeaderModel(model()), plainTheme, 40).text, /✿ Gentle Shell/);
+});
+
+// T8: the usage segment. It rides after cost in the right group, shows every
+// window of the active provider's main limit, and degrades (gauges, then
+// secondary windows, then the whole segment) before ctx/cost is ever touched.
+
+const USAGE_TWO_WINDOWS = {
+	provider: "openai-codex",
+	plan: "pro",
+	fetchedAt: 0,
+	limits: [{ name: "codex", limitReached: false, windows: [
+		{ label: "5h", usedPercent: 26, windowSeconds: 18_000, resetAt: null },
+		{ label: "week", usedPercent: 12, windowSeconds: 604_800, resetAt: null },
+	] }],
+};
+
+test("renderShellHeaderBar shows every usage window with its gauge and the shortcut hint, after cost", () => {
+	const header = buildShellHeaderModel(model({ usage: USAGE_TWO_WINDOWS }));
+	const { text, usageSpan } = renderShellHeaderBar(header, plainTheme, 140, "alt+u");
+	assert.match(text, /\$9\.49 sub ⟡ usage 5h ▰▰▱▱▱▱▱▱ 26% · week ▰▱▱▱▱▱▱▱ 12% · alt\+u$/);
+	assert.ok(usageSpan);
+	assert.equal(text.slice(usageSpan.start, usageSpan.end), "usage 5h ▰▰▱▱▱▱▱▱ 26% · week ▰▱▱▱▱▱▱▱ 12% · alt+u");
+});
+
+test("renderShellHeaderBar shows 'usage · <shortcut>' with no data, and drops the hint when the shortcut is disabled", () => {
+	const withHint = renderShellHeaderBar(buildShellHeaderModel(model({ usage: undefined })), plainTheme, 140, "alt+u");
+	assert.match(withHint.text, /usage · alt\+u$/);
+	const noHint = renderShellHeaderBar(buildShellHeaderModel(model({ usage: undefined })), plainTheme, 140, undefined);
+	assert.match(noHint.text, /usage$/);
+	assert.doesNotMatch(noHint.text, /alt\+u/);
+});
+
+test("renderShellHeaderBar degrades the usage segment (gauges, then secondary windows, then the whole segment) before touching ctx/cost", () => {
+	const header = buildShellHeaderModel(model({ usage: USAGE_TWO_WINDOWS }));
+	const full = renderShellHeaderBar(header, plainTheme, 140, "alt+u").text;
+	assert.match(full, /5h ▰▰▱▱▱▱▱▱ 26% · week ▰▱▱▱▱▱▱▱ 12%/);
+
+	// 100 cols: the gauges no longer fit, but both windows still show as text
+	// (a positive match on the bare "5h 26% · week 12%" run rules out any
+	// gauge glyph sneaking in between them; ctx's own gauge is unrelated).
+	const noGauges = renderShellHeaderBar(header, plainTheme, 100, "alt+u").text;
+	assert.match(noGauges, /usage 5h 26% · week 12% · alt\+u$/);
+	assert.match(noGauges, /ctx ▰▰▰▰▱▱▱▱ 45% ⟡ \$9\.49 sub/, "ctx/cost are untouched while usage still degrades");
+	assert.equal(visibleWidth(noGauges), 100);
+
+	// 80 cols: only the first window remains.
+	const primaryOnly = renderShellHeaderBar(header, plainTheme, 80, "alt+u").text;
+	assert.match(primaryOnly, /usage 5h 26% · alt\+u$/);
+	assert.doesNotMatch(primaryOnly, /week/);
+	assert.match(primaryOnly, /ctx ▰▰▰▰▱▱▱▱ 45% ⟡ \$9\.49 sub/);
+	assert.equal(visibleWidth(primaryOnly), 80);
+
+	// 70 cols: the whole usage segment is gone, ctx/cost remain intact.
+	const noUsage = renderShellHeaderBar(header, plainTheme, 70, "alt+u").text;
+	assert.doesNotMatch(noUsage, /usage/);
+	assert.match(noUsage, /ctx ▰▰▰▰▱▱▱▱ 45% ⟡ \$9\.49 sub$/);
+	assert.equal(visibleWidth(noUsage), 70);
+});
+
+test("renderShellHeaderBar's usage span always points at the usage text, not ctx/cost", () => {
+	const header = buildShellHeaderModel(model({ usage: USAGE_TWO_WINDOWS }));
+	for (const width of [140, 100, 90]) {
+		const { text, usageSpan } = renderShellHeaderBar(header, plainTheme, width, "alt+u");
+		if (!usageSpan) continue;
+		assert.match(text.slice(usageSpan.start, usageSpan.end), /^usage/);
+		assert.equal(usageSpan.end, visibleWidth(text), "the usage segment always ends at the right edge");
+	}
+});

package/tests/shell-card.test.ts

@@ -54,10 +54,12 @@ test("renderCard collapses to the frame and the first body line with an expand h
 });
 
 test("renderCard uses the card tone across the full frame while preserving content roles", () => {
+	// INFO paints the rose frame: the rounded border in the plain border role,
+	// the title in accent — the same look every sidebar card already used.
 	const info = renderCard(card(), taggedTheme, 80, { expanded: true });
-	assert.match(info[0], /^<customMessageLabel>╭<\/customMessageLabel><customMessageLabel>─ <\/customMessageLabel><customMessageLabel>✿ Gentle AI<\/customMessageLabel> <muted>·<\/muted> <muted>review preflight<\/muted><customMessageLabel> ─+<\/customMessageLabel><customMessageLabel>╮<\/customMessageLabel>$/);
-	assert.match(info[1], /^<customMessageLabel>│<\/customMessageLabel> <text>.*<customMessageLabel>│<\/customMessageLabel>$/);
-	assert.match(info[info.length - 1], /^<customMessageLabel>╰<\/customMessageLabel><customMessageLabel>─+╯<\/customMessageLabel>$/);
+	assert.match(info[0], /^<border>╭<\/border><border>─ <\/border><accent>✿ Gentle AI<\/accent> <muted>·<\/muted> <muted>review preflight<\/muted><border> ─+<\/border><border>╮<\/border>$/);
+	assert.match(info[1], /^<border>│<\/border> <text>.*<border>│<\/border>$/);
+	assert.match(info[info.length - 1], /^<border>╰<\/border><border>─+╯<\/border>$/);
 
 	const warning = renderCard(card({ tone: CARD_TONE.WARNING, subtitle: undefined }), taggedTheme, 80, { expanded: true });
 	assert.match(warning[0], /^<warning>╭<\/warning>/);

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

@@ -62,6 +62,30 @@ function mouseButton(type: TuiMouseEvent["type"], button: TuiMouseEvent["button"
 	return { type, button, x, y, screenX: x, screenY: y, width: 80, height, shift: false, alt: false, ctrl: false };
 }
 
+// H1 (odd/tasks/usage-click-and-changes-attribution.md): the same shared
+// hover role every other clickable surface uses, and it never overrides the
+// already-selected row's own role.
+test("WorktreeChangesView paints the shared hover role over an unselected row, never the selected one", async () => {
+	const trees = ["/main", "/linked"].map((root) => ({ root, branch: root === "/main" ? "main" : undefined, model: changesModel([file("same.ts", 1, 0)]) }));
+	const component = new WorktreeChangesView(trees, {
+		theme: taggedTheme, rows: 10,
+		loadDiff: async () => "",
+		onOpen: () => {},
+		onClose: () => {}, requestRender() {}, onRefresh() {},
+	});
+	component.render(80);
+	// Row y=1 is the selected group header (/main, index 0); row y=2 is /linked's header.
+	const hoverOther = component.handleMouse(mouseButton("move", "none", 3, 2, 10));
+	assert.deepEqual(hoverOther, { handled: true, render: true });
+	assert.match(component.render(80)[2]!, /<warning>[^<]*detached/, "hovering the unselected row paints the shared hover role");
+	assert.doesNotMatch(component.render(80)[1]!, /<warning>/, "the selected row keeps its own role");
+
+	const hoverSelected = component.handleMouse(mouseButton("move", "none", 3, 1, 10));
+	assert.deepEqual(hoverSelected, { handled: true, render: true });
+	assert.doesNotMatch(component.render(80)[1]!, /<warning>/, "hovering the selected row still never paints the hover role");
+	assert.doesNotMatch(component.render(80)[2]!, /<warning>/, "leaving the other row clears its hover");
+});
+
 test("worktree accordion keeps groups and nested files beside a framed lazy diff", async () => {
 	const trees = ["/main", "/linked"].map((root) => ({ root, branch: root === "/main" ? "main" : undefined, model: changesModel([file("same.ts", 1, 0)]) }));
 	const loaded: string[] = [];
@@ -503,6 +527,29 @@ test("ChangesView opens the selected file and closes on escape or q", async () =
 	assert.equal(events.filter((event) => event === "close").length, 2);
 });
 
+// H1 (odd/tasks/usage-click-and-changes-attribution.md): the same shared
+// hover role every other clickable surface uses, and it never overrides the
+// already-selected row's own role.
+test("ChangesView paints the shared hover role over an unselected file row, never the selected one", async () => {
+	const { view: component } = view({ theme: taggedTheme });
+	await settle();
+	component.render(80);
+	// Row y=1 is the selected file (lib/a.ts, index 0); row y=2 is lib/b.ts.
+	const hoverOther = component.handleMouse(mouseButton("move", "none", 3, 2, 12));
+	assert.deepEqual(hoverOther, { handled: true, render: true });
+	assert.match(component.render(80)[2]!, /<warning>[^<]*lib\/b\.ts/, "the hovered, unselected row paints the shared hover role");
+	assert.doesNotMatch(component.render(80)[1]!, /<warning>/, "the selected row keeps its own role instead");
+
+	const hoverSelected = component.handleMouse(mouseButton("move", "none", 3, 1, 12));
+	assert.deepEqual(hoverSelected, { handled: true, render: true });
+	assert.doesNotMatch(component.render(80)[1]!, /<warning>/, "hovering the selected row still never paints the hover role");
+	assert.doesNotMatch(component.render(80)[2]!, /<warning>/, "leaving lib/b.ts clears its hover paint");
+
+	const left = component.handleMouse(mouseButton("move", "none", 60, 1, 12)); // outside the list pane entirely
+	assert.deepEqual(left, { handled: true, render: true });
+	assert.doesNotMatch(component.render(80).join("\n"), /<warning>/, "moving off the list clears any hover");
+});
+
 test("ChangesView click selects a file without opening it", async () => {
 	const { view: component, events } = view();
 	await settle();

package/tests/shell-changes.test.ts

@@ -10,6 +10,9 @@ import {
 	CHANGE_STATUS,
 	ChangesTracker,
 	WorktreeChangesTracker,
+	RootBranchLabels,
+	UNKNOWN_BRANCH,
+	foreignRootBranch,
 	parseWorktrees,
 	changesSummary,
 	emptyChanges,
@@ -19,6 +22,7 @@ import {
 	changesModel,
 	snapshotChanges,
 	type ChangedFile,
+	type GitResult,
 } from "../lib/shell-changes.ts";
 
 // The changes view shows the working tree against HEAD, new files included,
@@ -72,6 +76,16 @@ test("parsePorcelain reads NUL-separated status entries including renames and un
 	);
 });
 
+test("parsePorcelain drops embedded-repository markers, never a real file", () => {
+	// Git reports a nested .git directory (an embedded/foreign repository, the
+	// live evidence's ~/work/NaN-builders inside ~/work) as one directory-shaped
+	// "?? path/" line, never expanded into files, even with --untracked-files=all.
+	// Treating that line as a changed file creates a phantom entry for whatever
+	// ancestor repository happens to contain the nested one.
+	const raw = ["?? NaN-builders/", "?? notes.md", " M lib/a.ts"].join("\0") + "\0";
+	assert.deepEqual([...parsePorcelain(raw).entries()], [["notes.md", CHANGE_STATUS.UNTRACKED], ["lib/a.ts", CHANGE_STATUS.MODIFIED]]);
+});
+
 test("snapshotChanges merges status with counts and keeps untracked files without counts", () => {
 	const files = snapshotChanges({
 		numstat: "4\t2\tlib/a.ts\n",
@@ -265,6 +279,114 @@ test("worktree porcelain preserves unusual directory names and detached fallback
 	assert.deepEqual(parseWorktrees("worktree /a\nbranch strange\0HEAD abc\0detached\0\0"), [{ root: "/a\nbranch strange" }]);
 });
 
+// A GitRunner that cannot even ask (root removed, git missing, the runner
+// itself rejecting) must reject foreignRootBranch too -- never resolve to the
+// same undefined a genuinely detached HEAD produces. Swallowing the two into
+// one shape is exactly the bug: the caller has no way left to tell "asked and
+// there is no branch" from "could not ask at all".
+test("foreignRootBranch propagates a GitRunner failure instead of reporting detached", async () => {
+	const failing = async (): Promise<GitResult> => { throw new Error("git unavailable"); };
+	await assert.rejects(() => foreignRootBranch(failing), /git unavailable/);
+});
+
+test("foreignRootBranch still reports a genuine detached HEAD as undefined, not a failure", async () => {
+	const detached = async (args: string[]): Promise<GitResult> => (args[0] === "symbolic-ref" ? { stdout: "", code: 1 } : { stdout: "deadbeef\n", code: 0 });
+	assert.equal(await foreignRootBranch(detached), undefined);
+});
+
+// C3 (odd/tasks/usage-click-and-changes-attribution.md): a root registered by
+// the session but absent from a single `git worktree list` scan -- because it
+// belongs to a different Git clone entirely, e.g. an inner repository nested
+// inside an outer one -- must not default to "detached". It must be asked
+// directly, and "no commits yet" must read differently from a real branch.
+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) {
+		await t.test(scenario.name, async () => {
+			const calls: string[][] = [];
+			const tracker = new WorktreeChangesTracker(
+				async () => ({ stdout: "", code: 0 }), // /foreign never appears in this clone's own worktree list
+				() => async (args) => {
+					calls.push(args);
+					if (args[0] === "status") return { stdout: "?? changed.ts\0", code: 0 };
+					if (args[0] === "symbolic-ref") return scenario.symbolic;
+					if (args[0] === "rev-parse") return scenario.verify;
+					return { stdout: "", code: 0 };
+				},
+				undefined,
+				() => ["/foreign"],
+			);
+			await tracker.start();
+			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");
+		});
+	}
+});
+
+// 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
+// UNKNOWN_BRANCH, distinct from "detached", and must never drop the
+// already-captured changes.
+test("a root missing from worktree list keeps its changes and reads UNKNOWN_BRANCH when the direct ask fails", async () => {
+	const tracker = new WorktreeChangesTracker(
+		async () => ({ stdout: "", code: 0 }),
+		() => async (args) => {
+			if (args[0] === "status") return { stdout: "?? changed.ts\0", code: 0 };
+			if (args[0] === "diff") return { stdout: "", code: 0 };
+			throw new Error("git unavailable"); // symbolic-ref / rev-parse: the direct branch ask
+		},
+		undefined,
+		() => ["/foreign"],
+	);
+	await tracker.start();
+	assert.deepEqual(tracker.worktrees.map((tree) => [tree.root, tree.branch]), [["/foreign", UNKNOWN_BRANCH]]);
+	assert.equal(tracker.worktrees[0]!.model.files.length, 1, "a failed branch lookup must not drop the root's real changes");
+});
+
+// A root already described by the same clone's own worktree list is trusted
+// as-is: a real "detached" marker there is already 100% accurate, so no
+// redundant per-root call is needed (and none happens).
+test("a root already described by worktree list is trusted without a redundant lookup", async () => {
+	const calls: string[][] = [];
+	const tracker = new WorktreeChangesTracker(
+		async () => ({ stdout: "worktree /known\0detached\0\0", code: 0 }),
+		() => async (args) => {
+			calls.push(args);
+			return { stdout: args[0] === "status" ? "?? changed.ts\0" : "", code: 0 };
+		},
+		undefined,
+		() => ["/known"],
+	);
+	await tracker.start();
+	assert.deepEqual(tracker.worktrees.map((tree) => [tree.root, tree.branch]), [["/known", undefined]]);
+	assert.ok(!calls.some((args) => args[0] === "symbolic-ref"), "a known worktree-list entry must not trigger a fallback call");
+});
+
+// The live evidence: an outer repo (~/work, no commits) whose ONLY change is
+// the embedded inner repository (~/work/NaN-builders) itself must never show
+// up as a phantom tree once the embedded-repo marker is filtered out of its
+// own file list -- it never had a real file to show in the first place.
+test("an outer ancestor whose only change is the embedded inner repository is never a phantom tree", async () => {
+	const tracker = new WorktreeChangesTracker(
+		async () => ({ stdout: "", code: 0 }), // neither root belongs to the other's clone
+		(root) => async (args) => {
+			if (args[0] !== "status") return { stdout: "", code: 0 };
+			// The outer root's only "change" is the nested repo directory marker;
+			// the inner root has a real file of its own.
+			return { stdout: root === "/outer" ? "?? NaN-builders/\0" : "?? jpg-png-converter.md\0", code: 0 };
+		},
+		undefined,
+		() => ["/outer", "/outer/NaN-builders"],
+	);
+	await tracker.start();
+	assert.deepEqual(tracker.worktrees.map((tree) => tree.root), ["/outer/NaN-builders"]);
+});
+
 test("registered roots remain scannable during metadata discovery failure", async () => {
 	let code = 128;
 	const tracker = new WorktreeChangesTracker(async () => ({ stdout: "worktree /repo\0\0", code }), () => async (args) => ({ stdout: args[0] === "status" ? "?? new.ts\0" : "", code: 0 }), undefined, () => ["/repo"]);
@@ -356,3 +478,58 @@ test("ChangesTracker counts the lines of untracked files, which git numstat leav
 	assert.equal(model.added, 3);
 	assert.deepEqual(counted, ["notes.md", "empty.md"]);
 });
+
+// The session-evidence tracker behind /gentle:changes knows roots, never
+// branches. The overlay decorates its trees with each root's own HEAD state,
+// resolved once per root and reported back so the view can repaint; until git
+// answers the tree shows no branch (the view's "detached" fallback), and a
+// genuinely detached HEAD stays that way.
+test("RootBranchLabels decorates session trees with each root's branch once git answers", async () => {
+	const calls = new Map<string, string[][]>();
+	const answers: Record<string, { symbolic: { stdout: string; code: number }; verify: { stdout: string; code: number } }> = {
+		"/repo": { symbolic: { stdout: "feature\n", code: 0 }, verify: { stdout: "deadbeef\n", code: 0 } },
+		"/fresh": { symbolic: { stdout: "main\n", code: 0 }, verify: { stdout: "", code: 1 } },
+		"/pinned": { symbolic: { stdout: "", code: 1 }, verify: { stdout: "deadbeef\n", code: 0 } },
+	};
+	let changed = 0;
+	const labels = new RootBranchLabels((root) => async (args) => {
+		calls.set(root, [...(calls.get(root) ?? []), args]);
+		await new Promise((resolve) => setImmediate(resolve));
+		return args[0] === "symbolic-ref" ? answers[root]!.symbolic : answers[root]!.verify;
+	}, () => changed++);
+	const trees = Object.keys(answers).map((root) => ({ root, model: changesModel([]) }));
+	const first = labels.decorate(trees);
+	assert.deepEqual(first.map((tree) => tree.branch), [undefined, undefined, undefined], "nothing is labelled before git answers");
+	await labels.settled();
+	assert.equal(changed, 3, "each resolved root asks the view to repaint once");
+	const second = labels.decorate(trees);
+	assert.deepEqual(second.map((tree) => tree.branch), ["feature", "no commits yet", undefined]);
+	labels.decorate(trees);
+	await labels.settled();
+	assert.deepEqual([...calls.values()].map((list) => list.length), [2, 2, 1], "one resolution per root, never per decorate call");
+	assert.equal(changed, 3);
+});
+
+// A root that could not even be asked (removed, git unavailable, the runner
+// itself rejecting) must read UNKNOWN_BRANCH -- never the same undefined a
+// genuine detached HEAD produces, and never silently stay unlabelled forever.
+test("RootBranchLabels labels a root UNKNOWN_BRANCH when it could not be asked, distinct from a real detached HEAD", async () => {
+	let changed = 0;
+	const labels = new RootBranchLabels((root) => async () => {
+		await new Promise((resolve) => setImmediate(resolve));
+		if (root === "/gone") throw new Error("root removed");
+		return { stdout: "", code: 1 };
+	}, () => changed++);
+	const trees = [
+		{ root: "/gone", model: changesModel([]) },
+		{ root: "/detached", model: changesModel([]) },
+	];
+	labels.decorate(trees);
+	await labels.settled();
+	assert.deepEqual(
+		labels.decorate(trees).map((tree) => tree.branch),
+		[UNKNOWN_BRANCH, undefined],
+		"a failed ask reads UNKNOWN_BRANCH; a real detached HEAD still reads undefined (the view's detached fallback)",
+	);
+	assert.equal(changed, 2, "a failed ask still resolves and asks the view to repaint, instead of hanging forever");
+});

package/tests/shell-hover.test.ts

@@ -0,0 +1,19 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { HOVER_ROLE, paintHoverable } from "../lib/shell-hover.ts";
+
+const theme = {
+	fg(role: string, text: string) {
+		return `<${role}>${text}</${role}>`;
+	},
+};
+
+test("paintHoverable paints the shared hover role only while hovered", () => {
+	assert.equal(paintHoverable(theme, "refresh", true), `<${HOVER_ROLE}>refresh</${HOVER_ROLE}>`);
+	assert.equal(paintHoverable(theme, "refresh", false), "refresh");
+});
+
+test("paintHoverable falls back to an idle role when given one", () => {
+	assert.equal(paintHoverable(theme, "refresh", false, "dim"), "<dim>refresh</dim>");
+	assert.equal(paintHoverable(theme, "refresh", true, "dim"), `<${HOVER_ROLE}>refresh</${HOVER_ROLE}>`, "hover always wins over the idle role");
+});

package/tests/shell-prompt.test.ts

@@ -128,6 +128,26 @@ test("framePromptLines keeps the editor scroll indicators inside the frame", ()
 	for (const line of lines) assert.equal(visibleWidth(line), width);
 });
 
+test("framePromptLines shows an explicit escHint on the bottom rule, overriding the editor's own scroll indicator", () => {
+	const width = 40;
+	const inner = width - 2;
+	const bottom = `─── ↓ 3 more ${"─".repeat(inner - 13)}`;
+	const lines = framePromptLines(
+		["─".repeat(inner), ` x${" ".repeat(inner - 2)}`, bottom],
+		width,
+		options({ fg: (_c, t) => t, escHint: "esc again to cancel" }),
+	);
+	assert.match(stripAnsi(lines[2]), /^╰─ esc again to cancel ─+╯$/);
+});
+
+test("framePromptLines falls back to the scroll indicator when no escHint is set", () => {
+	const width = 40;
+	const inner = width - 2;
+	const bottom = `─── ↓ 3 more ${"─".repeat(inner - 13)}`;
+	const lines = framePromptLines(["─".repeat(inner), ` x${" ".repeat(inner - 2)}`, bottom], width, options({ fg: (_c, t) => t }));
+	assert.match(stripAnsi(lines[2]), /^╰─ ↓ 3 more ─+╯$/);
+});
+
 test("withPromptHint places a dim hint after the cursor on an empty editor line", () => {
 	const inner = 38;
 	const line = ` ${CURSOR}${" ".repeat(inner - 2)}`;