gentle-pi 3.2.1 → 3.3.0

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)}`;

package/tests/shell-sidebar-fullscreen.test.ts

@@ -0,0 +1,59 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { Container, Spacer, TuiAltScreen, type Component } from "@earendil-works/pi-tui";
+import { createChatViewport } from "../node_modules/@earendil-works/pi-coding-agent/dist/modes/interactive/chat-viewport.js";
+import { installSidebar } from "../lib/shell-sidebar-layout.ts";
+import { sidebarHeader, sidebarPart } from "../lib/shell-sidebar.ts";
+
+// End-to-end through pi-tui's real alt-screen renderer and Pi's real chat
+// viewport: the unit fixtures elsewhere hand-build layout nodes, which is how
+// two earlier attempts at this row passed their tests and still failed live.
+const theme = { fg: (_color: string, text: string) => text, bold: (text: string) => text };
+const strip = (text: string) => text.replace(/\x1b\[[0-9;?]*[A-Za-z]/g, "").replace(/\x1b\][^\x07]*\x07/g, "").replace(/\s+$/, "");
+const lines = (rows: string[]): Component => ({ render: () => rows, invalidate() {} });
+
+async function renderViewport(columns: number, rows: number, sidebar: boolean): Promise<string[]> {
+	const terminal = {
+		start() {}, stop() {}, async drainInput() {}, write() {},
+		get columns() { return columns; }, get rows() { return rows; },
+		moveBy() {}, hideCursor() {}, showCursor() {}, clearLine() {}, clearFromCursor() {}, clearScreen() {}, setTitle() {}, setProgress() {},
+		kittyProtocolActive: false, getBufferedInput() { return ""; }, hasPendingInput() { return false; },
+	} as never;
+	const above = new Container();
+	above.addChild(new Spacer(1)); // Pi adds a spacer above the editor when no widget is shown
+	const footer = new Container();
+	const viewport = createChatViewport({
+		document: lines(Array.from({ length: 12 }, (_, i) => `transcript ${i + 1}`)),
+		pendingMessages: new Container(), status: new Container(), widgetsAbove: above,
+		editor: lines(["╭─ editor ─╮", "│ prompt   │", "╰──────────╯"]),
+		widgetsBelow: new Container(), footer, scrollbar: "auto",
+	});
+	const tui = new TuiAltScreen(terminal, false);
+	tui.setLayoutRoot(viewport.root);
+	if (sidebar) {
+		footer.addChild(sidebarPart(tui, "footer", lines(["BOTTOM BAR"]), { render: () => ["Status card"], invalidate() {} }));
+		sidebarHeader(tui, { render: (width: number) => [`HEADER ${width}`], invalidate() {} });
+		installSidebar(tui, theme);
+	} else {
+		footer.addChild(lines(["BOTTOM BAR"]));
+	}
+	tui.start();
+	tui.requestRender(true);
+	await new Promise((resolve) => setTimeout(resolve, 20));
+	tui.stop();
+	return ((tui as unknown as { previousScreen: string[] }).previousScreen ?? []).map(strip);
+}
+
+test("fullscreen with the sidebar leaves no blank row between the editor and the terminal edge", async () => {
+	const screen = await renderViewport(140, 24, true);
+	assert.equal(screen[0], "HEADER 138", "the header owns the first row");
+	assert.match(screen[screen.length - 1] ?? "", /^╰/, `the editor's bottom border sits on the last row, got ${JSON.stringify(screen.slice(-3))}`);
+	assert.ok(screen.some((row) => row.startsWith("╭─ editor")), "the editor is still painted");
+	assert.ok(screen.some((row) => row.includes("Status card")), "the rail is still painted");
+});
+
+test("fullscreen without the sidebar keeps Pi's bottom bar on the last row", async () => {
+	const screen = await renderViewport(140, 24, false);
+	assert.equal(screen[screen.length - 1], "BOTTOM BAR");
+	assert.match(screen[screen.length - 2] ?? "", /^╰/);
+});

package/tests/shell-sidebar-layout.test.ts

@@ -1,9 +1,9 @@
 import assert from "node:assert/strict";
 import test from "node:test";
-import { CURSOR_MARKER, ScrollView, VStack, visibleWidth, type TUI, type TuiMouseEvent } from "@earendil-works/pi-tui";
+import { CURSOR_MARKER, ScrollView, VStack, visibleWidth, type Component, type TUI, type TuiMouseEvent } from "@earendil-works/pi-tui";
 import { getScrollViewsAt, renderLayoutFrame, type LayoutBox } from "@earendil-works/pi-tui/dist/layout.js";
 import { installSidebar, invalidateSidebar } from "../lib/shell-sidebar-layout.ts";
-import { sidebarPart, sidebarState } from "../lib/shell-sidebar.ts";
+import { sidebarHeader, sidebarPart, sidebarState } from "../lib/shell-sidebar.ts";
 import { renderShellSidebarBar } from "../lib/shell-bar.ts";
 import { renderTodoCard, type TodoState } from "../lib/shell-todo.ts";
 
@@ -23,6 +23,20 @@ function rail(f: ReturnType<typeof fixture>): ScrollView {
 	assert.equal(node.type, "hstack");
 	return node.entries[1].component;
 }
+type HstackNode = { type: string; gap: number; align: string; entries: { component: unknown; basis: number; grow: number; shrink: number; minSize: number }[] };
+// Finds the [left, scroll] hstack regardless of whether it is returned
+// directly (no active header) or nested one level under the header vstack.
+function hstackOf(f: ReturnType<typeof fixture>): HstackNode {
+	const node = f.root[NODE]() as unknown as { type: string; entries: { component: { [NODE]?(): HstackNode } }[] };
+	if (node.type === "hstack") return node as unknown as HstackNode;
+	assert.equal(node.type, "vstack");
+	const nested = node.entries[1]?.component[NODE]?.();
+	assert.ok(nested, "the vstack's second entry must expose the hstack via NODE");
+	return nested!;
+}
+function railWithHeader(f: ReturnType<typeof fixture>): ScrollView {
+	return hstackOf(f).entries[1].component as ScrollView;
+}
 
 test("grouped Status preserves structured fields and opaque integration text", () => {
 	const lines = renderShellSidebarBar({
@@ -32,13 +46,14 @@ test("grouped Status preserves structured fields and opaque integration text", (
 	}, theme, 46);
 	const text = lines.join("\n");
 	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;
 	}
 	assert.match(text, /opaque integration/);
 	assert.match(text, /Branch.*main/);
+	assert.doesNotMatch(text, /Usage/);
 });
 
 test("scrollable TODO keeps every task while bottom and collapsed cards stay bounded", () => {
@@ -265,14 +280,17 @@ test("real layout frames reuse unchanged sidebar output and invalidate at state
 	assert.deepEqual(f.bottom.render(80), ["Status"]);
 	f.host.terminal.columns = 140;
 	renderLayoutFrame(f.root, 140, 20, () => {});
-	assert.deepEqual(counts, { footer: 3, changes: 0, agents: 3, todo: 3 });
+	// Dipping below the breakpoint and back nulls the whole-rail `prepared`
+	// memo, but the per-section cache survives underneath it: the revision
+	// never moved, so no section actually needed to re-render.
+	assert.deepEqual(counts, { footer: 2, changes: 0, agents: 2, todo: 2 });
 
 	f.host.mode = "regular";
 	renderLayoutFrame(f.root, 140, 20, () => {});
 	assert.deepEqual(f.bottom.render(80), ["Status"]);
 	f.host.mode = "fullscreen";
 	renderLayoutFrame(f.root, 140, 20, () => {});
-	assert.deepEqual(counts, { footer: 4, changes: 0, agents: 4, todo: 4 });
+	assert.deepEqual(counts, { footer: 2, changes: 0, agents: 2, todo: 2 });
 
 	let replacementRenders = 0;
 	sidebarPart(f.tui, "todo", {
@@ -469,3 +487,223 @@ test("native transcript and sidebar keep separate scroll routing across resize,
 		assert.equal(result.frame.root.children.some(box => box.component === rail), mode === "fullscreen" && width >= 140);
 	}
 });
+
+// T3: per-section render memo. Each rail section caches its rendered lines by
+// its own digest, so a section whose digest did not change is never re-run
+// when a sibling section's digest ticks — only the whole rail's assembled
+// `lines`/`hits` are rebuilt from the (possibly cached) per-section lines.
+
+test("a footer digest change does not re-render Agents or TODO", (t) => {
+	const f = fixture();
+	let footerLabel = "one";
+	const counts = { footer: 0, agents: 0, todo: 0 };
+	sidebarPart(f.tui, "footer", { render: () => ["Status"], invalidate() {} }, {
+		digest: () => footerLabel,
+		render: () => { counts.footer++; return [`Footer ${footerLabel}`]; },
+		invalidate() {},
+	});
+	for (const key of ["agents", "todo"] as const) {
+		sidebarPart(f.tui, key, { render: () => [key], invalidate() {} }, {
+			render: () => { counts[key]++; return [key]; },
+			invalidate() {},
+		});
+	}
+	t.after(installSidebar(f.tui, theme));
+
+	assert.match(rail(f).render(50).join("\n"), /Footer one/);
+	assert.deepEqual(counts, { footer: 1, agents: 1, todo: 1 });
+
+	// Re-render with nothing changed at all: the outer unchanged fast path
+	// must not call any section's render either.
+	assert.match(rail(f).render(50).join("\n"), /Footer one/);
+	assert.deepEqual(counts, { footer: 1, agents: 1, todo: 1 });
+
+	footerLabel = "two";
+	assert.match(rail(f).render(50).join("\n"), /Footer two/);
+	assert.deepEqual(counts, { footer: 2, agents: 1, todo: 1 }, "only the section whose digest changed re-renders");
+
+	// invalidateSidebar bumps the global revision, which is only what a
+	// no-digest section keys its cache on: footer's own unchanged digest
+	// still protects it from re-rendering.
+	invalidateSidebar(f.tui);
+	assert.match(rail(f).render(50).join("\n"), /Footer two/);
+	assert.deepEqual(counts, { footer: 2, agents: 2, todo: 2 }, "revision invalidation reaches only the sections with no digest of their own");
+});
+
+test("a throwing digest still degrades to invalidation-only under the per-section memo", (t) => {
+	const f = fixture();
+	let todoRenders = 0;
+	sidebarPart(f.tui, "todo", { render: () => ["Todo"], invalidate() {} }, {
+		digest: () => { throw new Error("broken digest"); },
+		render: () => { todoRenders++; return ["Todo card"]; },
+		invalidate() {},
+	});
+	t.after(installSidebar(f.tui, theme));
+
+	assert.match(rail(f).render(50).join("\n"), /Todo card/);
+	assert.equal(todoRenders, 1);
+	assert.match(rail(f).render(50).join("\n"), /Todo card/);
+	assert.equal(todoRenders, 1, "an unchanged frame reuses the cached section even without a digest");
+
+	invalidateSidebar(f.tui);
+	assert.match(rail(f).render(50).join("\n"), /Todo card/);
+	assert.equal(todoRenders, 2, "explicit invalidation still reaches a rail without a digest");
+});
+
+test("a part replaced under the same key never reuses the previous part's cached lines", (t) => {
+	const f = fixture();
+	let firstRenders = 0;
+	sidebarPart(f.tui, "todo", { render: () => ["Todo"], invalidate() {} }, {
+		render: () => { firstRenders++; return ["first"]; },
+		invalidate() {},
+	});
+	t.after(installSidebar(f.tui, theme));
+	assert.match(rail(f).render(50).join("\n"), /first/);
+	assert.equal(firstRenders, 1);
+
+	let secondRenders = 0;
+	sidebarPart(f.tui, "todo", { render: () => ["Todo"], invalidate() {} }, {
+		render: () => { secondRenders++; return ["second"]; },
+		invalidate() {},
+	});
+	const text = rail(f).render(50).join("\n");
+	assert.match(text, /second/);
+	assert.doesNotMatch(text, /first/);
+	assert.equal(secondRenders, 1);
+});
+
+// T2: the live header row. A registered "header" part wraps the existing
+// [left, scroll] hstack in a one-row-taller vstack and takes over the brand
+// the banner used to carry inside the rail. Hosts that never register a
+// header (every fixture above) keep the exact old hstack-direct shape.
+
+test("an active header wraps the hstack in a vstack and removes the banner from the rail", (t) => {
+	const f = fixture();
+	sidebarHeader(f.tui, { render: (width: number) => [`HEADER ${width}`], invalidate() {} });
+	t.after(installSidebar(f.tui, theme));
+
+	const node = f.root[NODE]() as unknown as HstackNode;
+	assert.equal(node.type, "vstack");
+	assert.equal(node.gap, 0);
+	assert.equal(node.align, "stretch");
+	assert.deepEqual(node.entries.map(({ basis, grow, shrink, minSize }) => ({ basis, grow, shrink, minSize })), [
+		{ basis: 1, grow: 0, shrink: 0, minSize: 1 },
+		{ basis: 0, grow: 1, shrink: 1, minSize: 1 },
+	]);
+	const header = node.entries[0].component as { render(width: number): string[] };
+	// The rail card ends two columns before the terminal edge (its padding plus
+	// the scrollbar column); the header stops there too so its right group
+	// lines up with the card border instead of touching the edge.
+	assert.deepEqual(header.render(0), ["HEADER 138"], "the header renders at the terminal width minus the rail's right inset, not the rail width");
+
+	const hstack = hstackOf(f);
+	assert.equal(hstack.type, "hstack");
+	const scroll = railWithHeader(f);
+	const rail = scroll.render(50);
+	assert.doesNotMatch(rail.join("\n"), /✿ Gentle Shell ✿/, "the header carries the brand now, not the banner");
+	// The banner used to hold the first card away from the top; with the
+	// header in its place the rail keeps one blank row so the first card does
+	// not sit flush against the header.
+	assert.equal(rail[0]?.trim(), "", "the rail opens with a blank row under the header");
+	assert.notEqual(rail[1]?.trim(), "", "the first card starts on the second row");
+});
+
+test("without a registered header the rail keeps the banner and the plain hstack", (t) => {
+	const f = fixture();
+	t.after(installSidebar(f.tui, theme));
+	const node = f.root[NODE]() as unknown as { type: string };
+	assert.equal(node.type, "hstack");
+	const scroll = rail(f);
+	assert.match(scroll.render(50).join("\n"), /✿ Gentle Shell ✿/);
+});
+
+test("a header too narrow to show anything falls back to the plain hstack and the banner", (t) => {
+	const f = fixture();
+	sidebarHeader(f.tui, { render: () => [""], invalidate() {} });
+	t.after(installSidebar(f.tui, theme));
+	const node = f.root[NODE]() as unknown as { type: string };
+	assert.equal(node.type, "hstack", "a blank header line does not earn its own row");
+	const scroll = rail(f);
+	assert.match(scroll.render(50).join("\n"), /✿ Gentle Shell ✿/);
+});
+
+test("header content changes reach the header row while an unrelated part is untouched", (t) => {
+	const f = fixture();
+	let label = "one";
+	sidebarHeader(f.tui, { digest: () => label, render: () => [`HEADER ${label}`], invalidate() {} });
+	t.after(installSidebar(f.tui, theme));
+
+	const headerLines = () => (f.root[NODE]() as unknown as HstackNode).entries[0].component as { render(width: number): string[] };
+	assert.deepEqual(headerLines().render(0), ["HEADER one"]);
+	label = "two";
+	assert.deepEqual(headerLines().render(0), ["HEADER two"]);
+});
+
+test("rail mouse dispatch still maps clicks correctly with the header row above it", (t) => {
+	const f = fixture();
+	let clicks = 0;
+	const todo = {
+		render: () => ["Todo header", "Todo body"],
+		invalidate() {},
+		handleMouse(event: TuiMouseEvent) {
+			if (event.type !== "click" || event.button !== "left" || event.y !== 0) return undefined;
+			clicks++;
+			return { handled: true, render: true };
+		},
+	};
+	sidebarPart(f.tui, "todo", todo);
+	sidebarHeader(f.tui, { render: () => ["HEADER"], invalidate() {} });
+	const dispose = installSidebar(f.tui, theme);
+	t.after(dispose);
+	const scroll = railWithHeader(f);
+	const content = scroll.render(50);
+	scroll.updateLayout(content.length, 5, () => {});
+	const headerY = content.findIndex((line) => line.includes("Todo header"));
+	assert.ok(headerY >= 0);
+	// The mouse event carries coordinates local to the scroll component itself
+	// (pi-tui's layout tree translates screen coordinates before dispatch), so
+	// nesting the hstack one level deeper under the header row does not shift
+	// what the rail receives.
+	const hit = scroll.handleMouse({ type: "click", button: "left", x: 2, y: headerY, screenX: 92, screenY: 31 + headerY, width: 50, height: 5, shift: false, alt: false, ctrl: false });
+	assert.equal(hit?.handled, true);
+	assert.equal(clicks, 1);
+});
+
+// T8(c): the header row is a leaf in the layout tree, not inside the rail's
+// ScrollView, so pi-tui's mouse dispatch (tui-alt-screen.js) finds and calls
+// its own handleMouse directly — it never goes through dispatchPartMouse.
+test("the header component's handleMouse delegates to the registered header part", (t) => {
+	const f = fixture();
+	const received: TuiMouseEvent[] = [];
+	let result: { handled: boolean; render?: boolean } | undefined = { handled: true, render: true };
+	sidebarHeader(f.tui, {
+		render: () => ["HEADER"],
+		invalidate() {},
+		handleMouse(event: TuiMouseEvent) {
+			received.push(event);
+			return result;
+		},
+	});
+	t.after(installSidebar(f.tui, theme));
+
+	const node = f.root[NODE]() as unknown as { type: string; entries: { component: Component }[] };
+	assert.equal(node.type, "vstack", "an active header wraps the hstack in a vstack");
+	const header = node.entries[0]!.component as { handleMouse(event: TuiMouseEvent): { handled: boolean; render?: boolean } | undefined };
+
+	const event = { type: "click", button: "left", x: 5, y: 0, screenX: 5, screenY: 0, width: 140, height: 1, shift: false, alt: false, ctrl: false } as TuiMouseEvent;
+	assert.deepEqual(header.handleMouse(event), { handled: true, render: true });
+	assert.equal(received.length, 1);
+	assert.equal(received[0], event, "the event reaches the registered part unmodified");
+
+	result = undefined;
+	assert.equal(header.handleMouse(event), undefined, "an ignored click returns undefined, same as any other component");
+});
+
+test("the header component's handleMouse is a harmless no-op when no header part is registered", (t) => {
+	const f = fixture();
+	t.after(installSidebar(f.tui, theme));
+	const node = f.root[NODE]() as unknown as { type: string; entries?: { component: Component }[] };
+	// No header registered: the active node stays the plain hstack (T2's
+	// backward-compatible fallback), so there is no header leaf to click at all.
+	assert.equal(node.type, "hstack");
+});

package/tests/shell-sidebar.test.ts

@@ -1,7 +1,7 @@
 import assert from "node:assert/strict";
 import test from "node:test";
 import type { TUI } from "@earendil-works/pi-tui";
-import { sidebarPart, sidebarState } from "../lib/shell-sidebar.ts";
+import { sidebarHeader, sidebarPart, sidebarState } from "../lib/shell-sidebar.ts";
 
 const host = (terminal?: object) => ({ terminal }) as TUI;
 const component = () => ({ render: (_width = 80) => ["bottom"], invalidate() {} });
@@ -48,3 +48,27 @@ test("disposing an old part preserves its replacement and releases its bottom",
 	(second as typeof second & { dispose?(): void }).dispose?.();
 	assert.equal(sidebarState(tui).parts.size, 0);
 });
+
+test("sidebarHeader registers the header part under its own key and disposes it without a bottom widget", () => {
+	const tui = host({});
+	const rail = { render: () => ["header line"], invalidate() {}, digest: () => "d" };
+	const dispose = sidebarHeader(tui, rail);
+	assert.equal(sidebarState(tui).parts.get("header"), rail);
+	dispose();
+	assert.equal(sidebarState(tui).parts.get("header"), undefined);
+});
+
+test("sidebarHeader on an unsupported host is a harmless no-op", () => {
+	const dispose = sidebarHeader(host(), { render: () => [], invalidate() {} });
+	assert.doesNotThrow(dispose);
+});
+
+test("sidebarHeader dispose does not remove a replacement rail registered after it", () => {
+	const tui = host({});
+	const first = { render: () => ["first"], invalidate() {} };
+	const dispose = sidebarHeader(tui, first);
+	const second = { render: () => ["second"], invalidate() {} };
+	sidebarHeader(tui, second);
+	dispose();
+	assert.equal(sidebarState(tui).parts.get("header"), second);
+});