gentle-pi 2.5.0 → 2.6.0

package/tests/shell-changes.test.ts

@@ -1,9 +1,16 @@
 import assert from "node:assert/strict";
 import test from "node:test";
+import { execFile } from "node:child_process";
+import { mkdir, mkdtemp, realpath, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { promisify } from "node:util";
 import { visibleWidth } from "@earendil-works/pi-tui";
 import {
 	CHANGE_STATUS,
 	ChangesTracker,
+	WorktreeChangesTracker,
+	parseWorktrees,
 	changesSummary,
 	emptyChanges,
 	parseNumstat,
@@ -167,6 +174,167 @@ test("ChangesTracker coalesces overlapping refreshes into at most one extra roun
 	assert.equal(rounds, 3);
 });
 
+test("registered roots hide clean and missing worktrees while metadata never admits bare or prunable siblings", async () => {
+	let roots = "worktree /main\0branch refs/heads/main\0\0worktree /linked space\0detached\0\0worktree /clean\0\0worktree /gone\0\0worktree /pruned\0prunable missing\0\0worktree /bare\0bare\0\0";
+	const calls: string[] = [];
+	let registered = ["/main", "/linked space", "/clean", "/gone"];
+	const tracker = new WorktreeChangesTracker(async () => ({ stdout: roots, code: 0 }), (root) => async (args) => {
+		calls.push(root);
+		if (root === "/gone") throw new Error("missing directory");
+		return { stdout: args[0] === "status" && root !== "/clean" ? "?? same.ts\0" : "", code: 0 };
+	}, (root) => async () => root === "/main" ? 2 : 3, () => registered);
+	await tracker.start();
+	assert.deepEqual(tracker.worktrees.map((tree) => [tree.root, tree.branch, tree.model.added]), [["/main", "main", 2], ["/linked space", undefined, 3]]);
+	assert.equal(tracker.model.files.length, 2, "identical filenames in different roots remain distinct");
+	assert.equal(new Set(tracker.model.files.map((file) => file.path)).size, 2);
+	assert.ok(!calls.includes("/pruned") && !calls.includes("/bare"));
+	roots += "worktree /new\0branch refs/heads/new\0\0";
+	registered.push("/new");
+	await tracker.refresh();
+	assert.equal(tracker.worktrees.length, 3);
+	roots = "worktree /clean\0\0";
+	registered = ["/clean"];
+	await tracker.refresh();
+	assert.deepEqual(tracker.worktrees, []);
+	assert.deepEqual(tracker.model, emptyChanges());
+});
+
+test("only registered worktrees are scanned, with whole preexisting and untracked contents", async () => {
+	const queried: string[] = [];
+	const roots = ["/used"];
+	const tracker = new WorktreeChangesTracker(async () => ({ code: 0, stdout: "worktree /used\0\0worktree /hidden\0\0" }), (root) => async (args) => {
+		queried.push(root);
+		return { code: 0, stdout: args[0] === "status" ? " M old.ts\0?? new.ts\0" : "4\t2\told.ts\n" };
+	}, () => async () => 3, () => roots);
+	await tracker.start();
+	assert.deepEqual(new Set(queried), new Set(["/used"]));
+	assert.equal(tracker.model.files.length, 2);
+	assert.equal(tracker.model.added, 7);
+	roots.push("/hidden");
+	await tracker.refresh();
+	assert.equal(tracker.model.files.length, 4);
+});
+
+test("worktree refresh shares one scan so polling faster than discovery cannot prolong it", async () => {
+	let release: (() => void) | undefined;
+	let scans = 0;
+	const tracker = new WorktreeChangesTracker(async () => {
+		scans++;
+		if (scans === 2) await new Promise<void>((resolve) => { release = resolve; });
+		return { stdout: "", code: 0 };
+	}, () => async () => ({ stdout: "", code: 0 }));
+	await tracker.start();
+	const first = tracker.refresh();
+	const overlapping = tracker.refresh();
+	release!();
+	await Promise.all([first, overlapping]);
+	assert.equal(scans, 2, "overlapping poll must not extend an already slow scan");
+	await tracker.refresh();
+	assert.equal(scans, 3, "next refresh still rediscovers roots");
+});
+
+test("registration during an in-flight status scan is included before refresh resolves", async () => {
+	const roots = ["/used"];
+	let release: () => void;
+	let entered: () => void;
+	const scanning = new Promise<void>((resolve) => { entered = resolve; });
+	const gate = new Promise<void>((resolve) => { release = resolve; });
+	let paused = false;
+	const tracker = new WorktreeChangesTracker(async () => ({ code: 0, stdout: "" }), (root) => async (args) => {
+		if (root === "/used" && args[0] === "status" && !paused) { paused = true; entered(); await gate; }
+		return { code: 0, stdout: args[0] === "status" ? " M file.ts\0" : "1\t0\tfile.ts\n" };
+	}, undefined, () => roots);
+	const scan = tracker.refresh();
+	await scanning;
+	roots.push("/newly-used");
+	const concurrent = tracker.refresh();
+	release();
+	await Promise.all([scan, concurrent]);
+	assert.equal(tracker.model.files.length, 2);
+});
+
+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" }]);
+});
+
+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"]);
+	await tracker.start();
+	assert.equal(tracker.worktrees.length, 1);
+	code = 0;
+	await tracker.refresh();
+	assert.equal(tracker.worktrees.length, 1);
+});
+
+test("isolated Git worktrees include preexisting dirty files only after root registration", async (t) => {
+	const temporary = await mkdtemp(join(tmpdir(), "gentle-shell-worktrees-"));
+	// Every repository, linked root and Git configuration belongs to this fixture.
+	t.after(() => rm(temporary, { recursive: true, force: true }));
+	const fixture = await realpath(temporary);
+	const main = join(fixture, "main");
+	const linked = join(fixture, "linked space");
+	const clean = join(fixture, "clean");
+	const untracked = join(fixture, "untracked");
+	const empty = join(fixture, "empty");
+	const config = join(fixture, "gitconfig");
+	await mkdir(empty);
+	await writeFile(config, "");
+	const env = { ...process.env };
+	for (const key of Object.keys(env)) {
+		if (key.startsWith("GIT_")) delete env[key];
+	}
+	env.GIT_CONFIG_GLOBAL = config;
+	env.GIT_CONFIG_NOSYSTEM = "1";
+	env.GIT_ATTR_NOSYSTEM = "1";
+	const exec = promisify(execFile);
+	const gitAt = (root: string) => async (args: string[]) => {
+		const { stdout } = await exec("git", [
+			"--no-optional-locks", "-C", root,
+			"-c", `core.hooksPath=${empty}`,
+			"-c", "commit.gpgsign=false", "-c", "tag.gpgsign=false",
+			...args,
+		], { env });
+		return { stdout, code: 0 };
+	};
+	await gitAt(fixture)(["init", "--initial-branch=main", `--template=${empty}`, main]);
+	await gitAt(main)(["config", "user.name", "Shell Test"]);
+	await gitAt(main)(["config", "user.email", "shell-test@example.invalid"]);
+	await writeFile(join(main, "same.ts"), "export const value = 1;\n");
+	await gitAt(main)(["add", "same.ts"]);
+	await gitAt(main)(["commit", "-m", "Initial fixture"]);
+	await gitAt(main)(["worktree", "add", "-b", "linked", linked]);
+	await gitAt(main)(["worktree", "add", "-b", "clean", clean]);
+
+	// Discovery starts from a linked root, not the clone's primary worktree.
+	const registered = [main, linked, clean];
+	const tracker = new WorktreeChangesTracker(gitAt(linked), gitAt, undefined, () => registered);
+	await tracker.start();
+	assert.deepEqual(tracker.worktrees, [], "all clean roots are hidden");
+	await writeFile(join(main, "same.ts"), "export const value = 2;\n");
+	await writeFile(join(linked, "same.ts"), "export const value = 3;\n");
+	await tracker.refresh();
+	assert.deepEqual(new Set(tracker.worktrees.map((tree) => tree.root)), new Set([main, linked]));
+	assert.deepEqual(tracker.worktrees.map((tree) => tree.model.files[0].path), ["same.ts", "same.ts"]);
+	assert.equal(new Set(tracker.model.files.map((file) => file.path)).size, 2, "aggregate paths distinguish the two roots");
+
+	await gitAt(main)(["worktree", "add", "-b", "untracked", untracked]);
+	await writeFile(join(untracked, "notes.md"), "New worktree content\n");
+	await tracker.refresh();
+	assert.equal(tracker.worktrees.length, 2, "a new dirty sibling stays hidden until registered");
+	registered.push(untracked);
+	await tracker.refresh();
+	assert.deepEqual(new Set(tracker.worktrees.map((tree) => tree.root)), new Set([main, linked, untracked]));
+	assert.deepEqual(tracker.worktrees.find((tree) => tree.root === untracked)?.model.files, [file("notes.md", 0, 0, CHANGE_STATUS.UNTRACKED)]);
+	assert.ok(!tracker.worktrees.some((tree) => tree.root === clean), "unchanged linked root remains hidden");
+});
+
+test("untracked-only unborn roots remain visible without a HEAD diff", async () => {
+	const tracker = new ChangesTracker(async (args) => ({ stdout: args[0] === "status" ? "?? first.ts\0" : "", code: args[0] === "status" ? 0 : 128 }), async () => 2);
+	await tracker.start();
+	assert.deepEqual(tracker.model.files, [file("first.ts", 2, 0, CHANGE_STATUS.UNTRACKED)]);
+});
+
 test("ChangesTracker counts the lines of untracked files, which git numstat leaves out", async () => {
 	const { git } = fakeGit(["", ""], ["", "?? notes.md\0?? empty.md\0"]);
 	const counted: string[] = [];

package/tests/shell-prompt.test.ts

@@ -4,7 +4,6 @@ import { visibleWidth } from "@earendil-works/pi-tui";
 import { stripAnsi } from "../lib/terminal-theme.ts";
 import {
 	framePromptLines,
-	panelPainter,
 	PROMPT_STATE,
 	petalGlyph,
 	petalTone,
@@ -110,9 +109,32 @@ test("withPromptHint leaves the line alone when the hint does not fit", () => {
 	assert.equal(hinted, line);
 });
 
-test("panelPainter keeps the background running after pi's cursor reset", () => {
-	const paint = panelPainter("<bg>");
-	assert.equal(paint("a\x1b[0mb"), "<bg>a\x1b[0m<bg>b\x1b[49m");
-	const lines = framePromptLines(editorLines(40), 40, options({ fg: (_c, t) => t, paint }));
-	assert.ok(lines.every((line) => line.startsWith("<bg>") && line.endsWith("\x1b[49m")));
+test("working prompt stays transparent at narrow and normal widths", () => {
+	for (const width of [0, 1, 2, 3, 8, 40]) {
+		const lines = framePromptLines(["──", ` ${CURSOR}界`, "──"], width, options({
+			state: PROMPT_STATE.WORKING, fg: (_c, t) => t,
+		}));
+		for (const [row, line] of lines.entries()) {
+			assert.ok(visibleWidth(line) <= width);
+			let bg = false, cell = 0;
+			for (const token of line.match(/\x1b\[[\d;]*m|[^\x1b]/gu) ?? []) {
+				if (token.startsWith("\x1b")) {
+					for (const code of token.slice(2, -1).split(";").map(Number)) {
+						if (code === 0 || code === 49) bg = false;
+						if (code === 44) bg = true;
+					}
+				} else {
+					assert.equal(bg, false, `row ${row}, cell ${cell} must remain transparent`);
+					cell += visibleWidth(token);
+				}
+			}
+			assert.equal(bg, false);
+		}
+	}
+});
+
+test("transparent prompt preserves pi's cursor reset", () => {
+	const lines = framePromptLines(editorLines(40), 40, options({ fg: (_c, t) => t }));
+	assert.ok(lines[1].includes(CURSOR));
+	assert.doesNotMatch(lines.join("\n"), /\x1b\[44m/);
 });

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

@@ -0,0 +1,23 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { visibleWidth } from "@earendil-works/pi-tui";
+import { renderSidebarBanner } from "../lib/shell-sidebar-banner.ts";
+
+const plain = { fg: (_role: string, text: string) => text, bold: (text: string) => text };
+test("sidebar heading is only the centered literal product label", () => {
+	const label = "✿ Gentle-Pi ✿";
+	for (const width of [0, 1, 8, 11, 20, 21, 30, 45, 46, 80]) {
+		const lines = renderSidebarBanner(plain, width);
+		const space = width - visibleWidth(label);
+		assert.deepEqual(lines, space >= 0 ? [" ".repeat(Math.floor(space / 2)) + label + " ".repeat(Math.ceil(space / 2))] : []);
+		assert.ok(lines.every((line) => visibleWidth(line) === width));
+	}
+});
+
+test("heading uses the current theme on every render", () => {
+	let palette = "dark";
+	const theme = { ...plain, fg: (role: string, text: string) => `<${palette}:${role}>${text}` };
+	assert.equal(renderSidebarBanner(theme, 46)[0].trim(), "<dark:accent>✿ <dark:text>Gentle-Pi <dark:accent>✿");
+	palette = "light";
+	assert.equal(renderSidebarBanner(theme, 46)[0].trim(), "<light:accent>✿ <light:text>Gentle-Pi <light:accent>✿");
+});

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

@@ -0,0 +1,387 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { ScrollView, visibleWidth, type TUI, type TuiMouseEvent } from "@earendil-works/pi-tui";
+import { renderLayoutFrame } 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 { renderShellSidebarBar } from "../lib/shell-bar.ts";
+import { renderTodoCard, type TodoState } from "../lib/shell-todo.ts";
+
+const NODE = Symbol.for("@earendil-works/pi-tui/layout-node");
+const theme = { fg: (_color: string, text: string) => text, bold: (text: string) => text };
+function fixture(mode = "fullscreen", columns = 140) {
+	const original = () => ({ type: "vstack", entries: [] });
+	const root = { render: () => ["transcript"], invalidate() {}, [NODE]: original };
+	let renders = 0;
+	const host = { mode, terminal: { columns }, layoutRoot: root, requestRender() { renders++; } };
+	const tui = host as unknown as TUI;
+	const bottom = sidebarPart(tui, "footer", { render: (_width: number) => ["Status"], invalidate() {} });
+	return { host, tui, root, original, bottom, renders: () => renders };
+}
+function rail(f: ReturnType<typeof fixture>): ScrollView {
+	const node = f.root[NODE]() as unknown as { type: string; entries: { component: ScrollView }[] };
+	assert.equal(node.type, "hstack");
+	return node.entries[1].component;
+}
+
+test("grouped Status preserves structured fields and opaque integration text", () => {
+	const lines = renderShellSidebarBar({
+		cwd: "/project", branch: "main", dirty: 2, sessionName: "session",
+		modelId: "model", effort: "high", contextPercent: 45, contextWindow: 1000,
+		costTotal: 1, subscription: false, statuses: ["opaque integration"],
+	}, theme, 46);
+	const text = lines.join("\n");
+	let previous = -1;
+	for (const heading of ["Status", "Project", "Model", "Context", "Usage", "Integrations"]) {
+		const index = text.indexOf(heading);
+		assert.ok(index > previous, heading);
+		previous = index;
+	}
+	assert.match(text, /opaque integration/);
+	assert.match(text, /Branch.*main/);
+});
+
+test("scrollable TODO keeps every task while bottom and collapsed cards stay bounded", () => {
+	const state: TodoState = { tasks: Array.from({ length: 20 }, (_, i) => ({ id: i + 1, title: `Task-${i + 1}!`, status: "pending" })), nextId: 21, updatedTurn: 0 };
+	const todoTheme = { ...theme, strikethrough: (text: string) => text };
+	const render = (scrollable: boolean, collapsed = false) => renderTodoCard(state, todoTheme, 46, { scrollable, collapsed, staleTurns: 0 }).join("\n");
+	for (const task of state.tasks) assert.ok(render(true).includes(task.title));
+	assert.ok(!render(false).includes("Task-20!"));
+	assert.ok(!render(true, true).includes("Task-20!"));
+});
+
+test("installation on a missing-terminal host is a harmless no-op", () => {
+	const dispose = installSidebar({} as TUI, theme);
+	assert.doesNotThrow(dispose);
+});
+
+test("only fullscreen at 140 columns activates; shrinking restores bottom paint", (t) => {
+	for (const [mode, width, active] of [["regular", 140, false], ["fullscreen", 139, false], ["fullscreen", 140, true]] as const) {
+		const f = fixture(mode, width);
+		t.after(installSidebar(f.tui, theme));
+		assert.equal(f.root[NODE]().type, active ? "hstack" : "vstack");
+		assert.deepEqual(f.bottom.render(80), active ? [] : ["Status"]);
+		f.host.terminal.columns = 139;
+		assert.equal(f.root[NODE]().type, "vstack");
+		assert.deepEqual(f.bottom.render(80), ["Status"]);
+	}
+});
+
+test("rail orders Status, changes, agents, TODO independent of registration order", (t) => {
+	const f = fixture();
+	for (const key of ["todo", "agents", "changes"]) {
+		sidebarPart(f.tui, key, { render: () => [key, ""], invalidate() {} });
+	}
+	t.after(installSidebar(f.tui, theme));
+	assert.deepEqual(rail(f).render(50).map((line) => line.trim()), ["✿ Gentle-Pi ✿", "", "Status", "", "changes", "", "agents", "", "todo"]);
+});
+
+test("branding belongs to scroll content before Status, never transcript or narrow bottom", (t) => {
+	const f = fixture();
+	t.after(installSidebar(f.tui, theme));
+	const scroll = rail(f);
+	const lines = scroll.render(50);
+	const brandIndex = lines.findIndex((line) => line.includes("✿ Gentle-Pi ✿"));
+	assert.ok(brandIndex >= 0 && brandIndex < lines.findIndex((line) => line.includes("Status")));
+	assert.doesNotMatch(lines.join("\n"), /[\u2800-\u28ff]/);
+	const heading = lines[brandIndex];
+	const usableWidth = scroll.getContentWidth(50) - 2;
+	const spare = usableWidth - visibleWidth("✿ Gentle-Pi ✿");
+	const scrollbarWidth = 50 - scroll.getContentWidth(50);
+	assert.equal(heading, " ".repeat(1 + Math.floor(spare / 2)) + "✿ Gentle-Pi ✿" + " ".repeat(1 + Math.ceil(spare / 2) + scrollbarWidth));
+	assert.deepEqual(f.root.render(), ["transcript"]);
+	scroll.updateLayout(lines.length, 2, () => {});
+	scroll.scrollBy(9);
+	assert.ok(scroll.scrollTop > 0);
+	f.host.terminal.columns = 80;
+	assert.equal(f.root[NODE]().type, "vstack");
+	assert.deepEqual(f.bottom.render(80), ["Status"]);
+});
+
+test("wheel scrolls the rail and is consumed at both boundaries and blank space", (t) => {
+	const f = fixture();
+	t.after(installSidebar(f.tui, theme));
+	const scroll = rail(f);
+	scroll.updateLayout(20, 5, () => {});
+	for (const [delta, expected] of [[-1, 0], [3, 3], [100, 15], [1, 15], [-100, 0]]) {
+		const result = scroll.handleMouse({ type: "wheel", wheelDelta: delta, x: 3, y: 4, screenX: 93, screenY: 6, width: 50, height: 5 } as Parameters<typeof scroll.handleMouse>[0]);
+		assert.equal(result?.handled, true);
+		assert.equal(scroll.scrollTop, expected);
+		assert.equal(result?.target?.component, scroll);
+	}
+	f.host.terminal.columns = 139;
+	assert.equal(f.root[NODE]().type, "vstack");
+	assert.deepEqual(f.bottom.render(80), ["Status"]);
+	f.host.terminal.columns = 160;
+	const restored = rail(f);
+	assert.deepEqual(f.bottom.render(80), []);
+	const layout = f.root[NODE]() as unknown as { gap: number; entries: { basis: number; grow: number; shrink: number; minSize: number }[] };
+	assert.equal(layout.gap, 3);
+	assert.deepEqual(layout.entries.map(({ basis, grow, shrink, minSize }) => ({ basis, grow, shrink, minSize })), [
+		{ basis: 0, grow: 1, shrink: 1, minSize: 1 },
+		{ basis: 50, grow: 0, shrink: 0, minSize: 50 },
+	]);
+	const restoredLines = restored.render(50);
+	// Native ScrollView.render only appends the scrollbar gutter; short rows need not fill the layout allocation.
+	for (const line of restoredLines) assert.ok(visibleWidth(line) <= 50);
+	assert.ok(restoredLines.some((line) => line.startsWith(" Status ")));
+	assert.deepEqual(f.root.render(), ["transcript"]);
+	restored.updateLayout(20, 5, () => {});
+	const before = restored.scrollTop;
+	const result = restored.handleMouse({ type: "wheel", wheelDelta: 2, x: 3, y: 4, screenX: 113, screenY: 6, width: 50, height: 5 } as Parameters<typeof restored.handleMouse>[0]);
+	assert.equal(result?.handled, true);
+	assert.equal(result?.target?.component, restored);
+	assert.equal(restored.scrollTop, Math.min(15, before + 2));
+	for (const line of restored.render(50)) assert.ok(visibleWidth(line) <= 50);
+	assert.deepEqual(f.root.render(), ["transcript"]);
+	scroll.updateLayout(1, 5, () => {});
+	assert.equal(scroll.handleMouse({ type: "wheel", wheelDelta: 1 } as Parameters<typeof scroll.handleMouse>[0])?.handled, true);
+	assert.equal(scroll.scrollTop, 0);
+});
+
+test("rail dispatches a clipped, scroll-translated left click to only the matching sidebar part", (t) => {
+	const f = fixture();
+	let clicks = 0;
+	const received: TuiMouseEvent[] = [];
+	const todo = {
+		render: () => ["Todo header", "Todo body"],
+		invalidate() {},
+		handleMouse(event: TuiMouseEvent) {
+			received.push(event);
+			if (event.type !== "click" || event.button !== "left" || event.y !== 0) return undefined;
+			clicks++;
+			return { handled: true, render: true };
+		},
+	};
+	sidebarPart(f.tui, "todo", todo);
+	const dispose = installSidebar(f.tui, theme);
+	t.after(dispose);
+	const scroll = rail(f);
+	const content = scroll.render(50);
+	scroll.updateLayout(content.length, 5, () => {});
+	scroll.scrollBy(1);
+	const headerY = content.findIndex((line) => line.includes("Todo header")) - scroll.scrollTop;
+	assert.ok(headerY >= 0);
+	const mouse = (type: TuiMouseEvent["type"], button: TuiMouseEvent["button"], y: number): TuiMouseEvent => ({
+		type, button, x: 2, y, screenX: 92, screenY: 30 + y, width: 50, height: 5, shift: false, alt: false, ctrl: false,
+	});
+
+	assert.equal(scroll.handleMouse(mouse("press", "left", headerY)), undefined);
+	assert.equal(scroll.handleMouse(mouse("click", "right", headerY)), undefined);
+	assert.equal(scroll.handleMouse(mouse("click", "left", headerY + 1)), undefined);
+	assert.equal(clicks, 0);
+	const hit = scroll.handleMouse(mouse("click", "left", headerY));
+	assert.equal(hit?.handled, true);
+	assert.equal(clicks, 1);
+	assert.deepEqual(received.at(-1) && { x: received.at(-1)!.x, y: received.at(-1)!.y, width: received.at(-1)!.width, height: received.at(-1)!.height }, { x: 1, y: 0, width: 47, height: 2 });
+
+	const gapY = headerY - 1;
+	assert.equal(scroll.handleMouse(mouse("click", "left", gapY)), undefined, "section gaps do not hit a neighbor");
+	assert.equal(scroll.handleMouse({ ...mouse("click", "left", headerY), x: 48 }), undefined, "padding outside the clipped part is inert");
+	invalidateSidebar(f.tui);
+	assert.equal(scroll.handleMouse(mouse("click", "left", headerY)), undefined, "stale geometry is inert");
+	f.host.terminal.columns = 139;
+	assert.equal(scroll.handleMouse(mouse("click", "left", headerY)), undefined, "resized-away rails are inert");
+	dispose();
+	assert.equal(scroll.handleMouse(mouse("click", "left", headerY)), undefined, "disposed rails are inert");
+});
+
+test("rail rejects removed or replaced parts before cached geometry is prepared again", (t) => {
+	const f = fixture();
+	let originalClicks = 0;
+	let replacementClicks = 0;
+	const original = {
+		render: () => ["Todo header"],
+		invalidate() {},
+		handleMouse(event: TuiMouseEvent) {
+			if (event.type !== "click" || event.button !== "left") return undefined;
+			originalClicks++;
+			return { handled: true };
+		},
+	};
+	const mounted = sidebarPart(f.tui, "todo", { render: () => ["Todo bottom"], invalidate() {} }, original);
+	const dispose = installSidebar(f.tui, theme);
+	t.after(dispose);
+	const scroll = rail(f);
+	const content = scroll.render(50);
+	scroll.updateLayout(content.length, 5, () => {});
+	const headerY = content.findIndex((line) => line.includes("Todo header"));
+	const click = (): TuiMouseEvent => ({ type: "click", button: "left", x: 2, y: headerY, screenX: 92, screenY: 30 + headerY, width: 50, height: 5, shift: false, alt: false, ctrl: false });
+	assert.equal(scroll.handleMouse(click())?.handled, true, "healthy cached geometry still dispatches");
+	assert.equal(originalClicks, 1);
+
+	mounted.dispose();
+	assert.equal(scroll.handleMouse(click()), undefined, "removed parts are inert before the next prepare");
+	assert.equal(originalClicks, 1);
+
+	const replacement = {
+		render: () => ["Todo replacement"],
+		invalidate() {},
+		handleMouse(event: TuiMouseEvent) {
+			if (event.type !== "click" || event.button !== "left") return undefined;
+			replacementClicks++;
+			return { handled: true };
+		},
+	};
+	sidebarPart(f.tui, "todo", { render: () => ["Todo bottom"], invalidate() {} }, replacement);
+	assert.equal(scroll.handleMouse(click()), undefined, "a replacement cannot receive stale cached geometry");
+	assert.equal(originalClicks, 1);
+	assert.equal(replacementClicks, 0);
+
+	rail(f);
+	assert.equal(scroll.handleMouse(click())?.handled, true, "prepared replacement dispatches normally");
+	assert.equal(replacementClicks, 1);
+});
+
+test("real layout frames reuse unchanged sidebar output and invalidate at state and breakpoint boundaries", (t) => {
+	const f = fixture();
+	const counts = { footer: 0, changes: 0, agents: 0, todo: 0 };
+	let todo = "Todo one";
+	for (const key of Object.keys(counts) as Array<keyof typeof counts>) {
+		sidebarPart(f.tui, key, {
+			render: () => {
+				counts[key]++;
+				return [`${key === "todo" ? todo : key}`];
+			},
+			invalidate() {},
+		});
+	}
+	t.after(installSidebar(f.tui, theme));
+
+	const first = renderLayoutFrame(f.root, 140, 20, () => {});
+	assert.deepEqual(counts, { footer: 1, changes: 1, agents: 1, todo: 1 });
+	const sidebarRail = first.root.children[1]?.component as ScrollView;
+	renderLayoutFrame(f.root, 140, 20, () => {});
+	assert.deepEqual(counts, { footer: 1, changes: 1, agents: 1, todo: 1 });
+
+	todo = "Todo two";
+	sidebarRail.invalidate();
+	const changed = renderLayoutFrame(f.root, 140, 20, () => {});
+	assert.match(changed.lines.join("\n"), /Todo two/);
+	assert.deepEqual(counts, { footer: 2, changes: 2, agents: 2, todo: 2 });
+
+	f.host.terminal.columns = 139;
+	renderLayoutFrame(f.root, 139, 20, () => {});
+	assert.deepEqual(f.bottom.render(80), ["Status"]);
+	f.host.terminal.columns = 140;
+	renderLayoutFrame(f.root, 140, 20, () => {});
+	assert.deepEqual(counts, { footer: 3, changes: 3, agents: 3, todo: 3 });
+
+	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: 4, agents: 4, todo: 4 });
+
+	let replacementRenders = 0;
+	sidebarPart(f.tui, "todo", {
+		render: () => {
+			replacementRenders++;
+			return ["Todo replacement"];
+		},
+		invalidate() {},
+	});
+	const replaced = renderLayoutFrame(f.root, 140, 20, () => {});
+	assert.match(replaced.lines.join("\n"), /Todo replacement/);
+	assert.equal(replacementRenders, 1);
+});
+
+test("a rail digest refreshes live state that no invalidation announces", (t) => {
+	const f = fixture();
+	let model = "model-a";
+	let renders = 0;
+	// The digest is the only signal: no part is re-registered and invalidateSidebar
+	// is never called here, which is exactly the /model case in fullscreen.
+	sidebarPart(f.tui, "footer", { render: () => ["Status"], invalidate() {} }, {
+		digest: () => model,
+		render: () => {
+			renders++;
+			return [`Model ${model}`];
+		},
+		invalidate() {},
+	});
+	t.after(installSidebar(f.tui, theme));
+
+	assert.match(renderLayoutFrame(f.root, 140, 20, () => {}).lines.join("\n"), /Model model-a/);
+	assert.equal(renders, 1);
+	renderLayoutFrame(f.root, 140, 20, () => {});
+	assert.equal(renders, 1, "an unchanged digest still reuses the prepared rail");
+
+	model = "model-b";
+	assert.match(renderLayoutFrame(f.root, 140, 20, () => {}).lines.join("\n"), /Model model-b/);
+	assert.equal(renders, 2);
+
+	// Rail digests run inside the layout frame, so a broken one must not disable
+	// the sidebar for the parts that still work.
+	let todoRenders = 0;
+	sidebarPart(f.tui, "todo", { render: () => ["Todo bottom"], invalidate() {} }, {
+		digest: () => { throw new Error("broken digest"); },
+		render: () => {
+			todoRenders++;
+			return ["Todo card"];
+		},
+		invalidate() {},
+	});
+	model = "model-c";
+	assert.match(renderLayoutFrame(f.root, 140, 20, () => {}).lines.join("\n"), /Model model-c/);
+	assert.equal(todoRenders, 1);
+	assert.match(renderLayoutFrame(f.root, 140, 20, () => {}).lines.join("\n"), /Todo card/);
+	assert.equal(todoRenders, 1, "a throwing digest degrades to invalidation-only");
+	invalidateSidebar(f.tui);
+	renderLayoutFrame(f.root, 140, 20, () => {});
+	assert.equal(todoRenders, 2, "explicit invalidation still reaches a rail without a digest");
+});
+
+test("reuses final sidebar presentation until a relevant invalidation", (t) => {
+	const f = fixture();
+	sidebarPart(f.tui, "todo", { render: () => Array.from({ length: 10 }, (_, index) => `Todo ${index}`), invalidate() {} });
+	t.after(installSidebar(f.tui, theme));
+
+	const first = f.root[NODE]();
+	assert.equal(f.root[NODE](), first);
+	const scroll = (first as { entries: { component: ScrollView }[] }).entries[1].component;
+	scroll.updateLayout(scroll.render(50).length, 1, () => {});
+	scroll.scrollBy(1);
+	const scrolled = f.root[NODE]();
+	assert.notEqual(scrolled, first);
+	assert.equal(f.root[NODE](), scrolled);
+
+	scroll.invalidate();
+	const invalidated = f.root[NODE]();
+	assert.notEqual(invalidated, scrolled);
+	assert.equal(f.root[NODE](), invalidated);
+
+	f.host.terminal.columns = 141;
+	const resized = f.root[NODE]();
+	assert.notEqual(resized, invalidated);
+	assert.equal(f.root[NODE](), resized);
+	f.host.mode = "regular";
+	assert.equal(f.root[NODE]().type, "vstack");
+	assert.deepEqual(f.bottom.render(80), ["Status"]);
+});
+
+test("cleanup restores the native layout and bottom paint without disposing widgets", () => {
+	const f = fixture();
+	const dispose = installSidebar(f.tui, theme);
+	rail(f);
+	dispose();
+	assert.equal(f.root[NODE], f.original);
+	assert.deepEqual(f.bottom.render(80), ["Status"]);
+	assert.equal(sidebarState(f.tui).parts.size, 1);
+	assert.ok(f.renders() >= 2);
+});
+
+test("unsupported roots, empty rails and overflowing parts leave native layout intact", (t) => {
+	for (const lines of [[], ["x".repeat(100)]]) {
+		const f = fixture();
+		sidebarPart(f.tui, "footer", { render: () => lines, invalidate() {} });
+		t.after(installSidebar(f.tui, theme));
+		assert.equal(f.root[NODE]().type, "vstack");
+		assert.equal(sidebarState(f.tui).active, false);
+	}
+	const f = fixture();
+	Reflect.deleteProperty(f.root, NODE);
+	t.after(installSidebar(f.tui, theme));
+	assert.deepEqual(f.bottom.render(80), ["Status"]);
+});