gentle-pi 3.2.0 → 3.3.0

package/lib/shell-changes-view.ts

@@ -2,6 +2,7 @@ import { Key, matchesKey, truncateToWidth, visibleWidth, type TuiMouseEvent, typ
 import { sanitizeTerminalText } from "./terminal-theme.ts";
 import { basename } from "node:path";
 import { CHANGE_STATUS, changesSummary, type ChangedFile, type ChangesModel, type WorktreeChanges } from "./shell-changes.ts";
+import { paintHoverable } from "./shell-hover.ts";
 
 // Gentle Shell changes overlay: a framed two-pane view with the working
 // tree's changed files on the left and the selected file's diff on the right.
@@ -78,8 +79,8 @@ function fileCounts(file: ChangedFile, theme: ChangesViewTheme): string {
 	return `${theme.fg(ROLE.ADDED, `+${file.added}`)} ${theme.fg(ROLE.REMOVED, `-${file.deleted}`)}`;
 }
 
-function fileLabel(file: ChangedFile, theme: ChangesViewTheme, role: string): string {
-	return `${theme.fg(role, `${FILE_STATUS[file.status]} ${displayText(file.path)}`)}  ${fileCounts(file, theme)}`;
+function fileLabel(file: ChangedFile, theme: ChangesViewTheme, hovered: boolean, idleRole: string): string {
+	return `${paintHoverable(theme, `${FILE_STATUS[file.status]} ${displayText(file.path)}`, hovered, idleRole)}  ${fileCounts(file, theme)}`;
 }
 
 function fit(text: string, width: number): string {
@@ -158,6 +159,7 @@ export class WorktreeChangesView {
 	private pointerLayout: PointerLayout | undefined;
 	private disposed = false;
 	private leftPressActive = false;
+	private hoveredIndex: number | undefined;
 	private readonly expanded = new Set<string>();
 	private readonly previews = new Map<string, { fingerprint: string; view: ChangesView }>();
 
@@ -172,6 +174,7 @@ export class WorktreeChangesView {
 
 	update(trees: WorktreeChanges[]): void {
 		this.leftPressActive = false;
+		this.hoveredIndex = undefined;
 		if (this.disposed) return;
 		this.pointerLayout = undefined;
 		const before = this.visibleRows()[this.selected];
@@ -239,6 +242,7 @@ export class WorktreeChangesView {
 			}
 			return undefined;
 		}
+		if (event.type === "move" && event.button === "none") return this.hoverRow(inFiles ? this.listOffset + event.y - 1 : undefined);
 		if (!inFiles) return undefined;
 		if (event.type === "press") {
 			if (event.button !== "left") return undefined;
@@ -255,6 +259,15 @@ export class WorktreeChangesView {
 		return { handled: true, render: changed };
 	}
 
+	// Row hover: the shared hover role paints an unselected row while the
+	// pointer is over it, never overriding the already-selected row's role.
+	private hoverRow(index: number | undefined): TuiMouseEventResult | undefined {
+		const next = index !== undefined && index >= 0 && index < this.visibleRows().length ? index : undefined;
+		if (next === this.hoveredIndex) return next === undefined ? undefined : { handled: true };
+		this.hoveredIndex = next;
+		return { handled: true, render: true };
+	}
+
 	render(width: number): string[] {
 		const theme = this.deps.theme;
 		const rows = this.visibleRows();
@@ -266,8 +279,14 @@ export class WorktreeChangesView {
 			const row = rows[index + this.listOffset];
 			if (!row) return "";
 			const active = index + this.listOffset === this.selected;
+			// Selection always outranks hover; the shared hover painter only
+			// applies once selection is ruled out.
+			const hovered = !active && index + this.listOffset === this.hoveredIndex;
+			const idleRole = active ? ROLE.SELECTED : ROLE.PATH_IDLE;
 			const marker = active ? theme.fg(ROLE.SELECTED, "▸") : " ";
-			const text = row.file ? `  ${fileLabel(row.file, theme, active ? ROLE.SELECTED : ROLE.PATH_IDLE)}` : theme.fg(active ? ROLE.SELECTED : ROLE.PATH_IDLE, `${this.expanded.has(row.tree.root) ? "▾" : "▸"} ${displayText(row.tree.branch ?? "detached")} · ${displayText(basename(row.tree.root))}`);
+			const text = row.file
+				? `  ${fileLabel(row.file, theme, hovered, idleRole)}`
+				: paintHoverable(theme, `${this.expanded.has(row.tree.root) ? "▾" : "▸"} ${displayText(row.tree.branch ?? "detached")} · ${displayText(basename(row.tree.root))}`, hovered, idleRole);
 			return `${marker} ${text}`;
 		};
 		const keys = theme.fg(ROLE.KEY_TEXT, "j/k select   enter toggle/open   ← parent/fold   ctrl+j/k scroll   r refresh   esc close");
@@ -277,6 +296,7 @@ export class WorktreeChangesView {
 
 	invalidate(): void {
 		this.leftPressActive = false;
+		this.hoveredIndex = undefined;
 		this.pointerLayout = undefined;
 		for (const preview of this.previews.values()) preview.view.invalidate();
 	}
@@ -284,6 +304,7 @@ export class WorktreeChangesView {
 	dispose(): void {
 		this.disposed = true;
 		this.leftPressActive = false;
+		this.hoveredIndex = undefined;
 		this.pointerLayout = undefined;
 		for (const preview of this.previews.values()) preview.view.dispose();
 		this.previews.clear();
@@ -333,6 +354,7 @@ export class ChangesView {
 	private pointerLayout: PointerLayout | undefined;
 	private disposed = false;
 	private leftPressActive = false;
+	private hoveredIndex: number | undefined;
 	private readonly diffs = new Map<string, string[]>();
 
 	constructor(model: ChangesModel, deps: ChangesViewDeps) {
@@ -345,6 +367,7 @@ export class ChangesView {
 	// diffs for files whose counts moved so they reload.
 	update(model: ChangesModel): void {
 		this.leftPressActive = false;
+		this.hoveredIndex = undefined;
 		if (this.disposed) return;
 		this.pointerLayout = undefined;
 		const selectedPath = this.model.files[this.selected]?.path;
@@ -368,6 +391,7 @@ export class ChangesView {
 	dispose(): void {
 		this.disposed = true;
 		this.leftPressActive = false;
+		this.hoveredIndex = undefined;
 		this.pointerLayout = undefined;
 	}
 
@@ -409,6 +433,7 @@ export class ChangesView {
 			if (inDiff) return { handled: true, render: this.scrollDiff(event.wheelDelta ?? 0, layout.bodyRows) };
 			return undefined;
 		}
+		if (event.type === "move" && event.button === "none") return this.hoverRow(inFiles ? this.fileScroll + event.y - 1 : undefined);
 		if (!inFiles) return undefined;
 		if (event.type === "press") {
 			if (event.button !== "left") return undefined;
@@ -423,6 +448,15 @@ export class ChangesView {
 		return { handled: true, render: changed };
 	}
 
+	// Row hover: the shared hover role paints an unselected file row while the
+	// pointer is over it, never overriding the already-selected row's role.
+	private hoverRow(index: number | undefined): TuiMouseEventResult | undefined {
+		const next = index !== undefined && index >= 0 && index < this.model.files.length ? index : undefined;
+		if (next === this.hoveredIndex) return next === undefined ? undefined : { handled: true };
+		this.hoveredIndex = next;
+		return { handled: true, render: true };
+	}
+
 	render(width: number): string[] {
 		const theme = this.deps.theme;
 		const rows = this.bodyRows();
@@ -434,6 +468,7 @@ export class ChangesView {
 
 	invalidate(): void {
 		this.leftPressActive = false;
+		this.hoveredIndex = undefined;
 		this.pointerLayout = undefined;
 	}
 
@@ -451,8 +486,11 @@ export class ChangesView {
 		const file = this.model.files[index];
 		if (!file) return "";
 		const theme = this.deps.theme;
-		const marker = index === this.selected ? theme.fg(ROLE.SELECTED, "▸") : " ";
-		return `${marker} ${fileLabel(file, theme, index === this.selected ? ROLE.PATH : ROLE.PATH_IDLE)}`;
+		const selected = index === this.selected;
+		const marker = selected ? theme.fg(ROLE.SELECTED, "▸") : " ";
+		const hovered = !selected && index === this.hoveredIndex;
+		const idleRole = selected ? ROLE.PATH : ROLE.PATH_IDLE;
+		return `${marker} ${fileLabel(file, theme, hovered, idleRole)}`;
 	}
 
 	private visibleDiff(rows: number): string[] {

package/lib/shell-changes.ts

@@ -90,8 +90,13 @@ export function parsePorcelain(text: string): Map<string, ChangeStatus> {
 		const record = records[index];
 		const code = record.slice(0, 2);
 		const path = record.slice(3);
-		const status = STATUS_BY_CODE[code[0]] ?? STATUS_BY_CODE[code[1]] ?? CHANGE_STATUS.MODIFIED;
-		statuses.set(path, status);
+		// A trailing "/" is Git's own marker for an embedded repository (a
+		// nested .git directory, e.g. an inner repo inside an outer one) or an
+		// excluded directory -- never an individual file. Even with
+		// --untracked-files=all, Git reports these as one directory-shaped line
+		// instead of expanding into files, so keeping it would show a phantom
+		// changed "file" on whatever ancestor repository contains the nested one.
+		if (!path.endsWith("/")) statuses.set(path, STATUS_BY_CODE[code[0]] ?? STATUS_BY_CODE[code[1]] ?? CHANGE_STATUS.MODIFIED);
 		if (code[0] === "R" || code[0] === "C") index += 1;
 	}
 	return statuses;
@@ -163,6 +168,77 @@ export function parseWorktrees(text: string): Array<{ root: string; branch?: str
 	});
 }
 
+// A root the view shows as-is when its own HEAD could not be determined at
+// all -- distinct from "detached", which means git answered and there really
+// is no branch. Exported so callers and tests share one literal.
+export const UNKNOWN_BRANCH = "unknown";
+
+// Resolve a foreign clone's own HEAD directly instead of assuming "detached":
+// a real branch name, "no commits yet" for an unborn branch (a branch ref
+// that exists but has no commit), or undefined for a genuine detached HEAD
+// (the caller falls back to "detached" in that case). A GitRunner that
+// cannot even ask -- it rejects, e.g. because the root was removed or git
+// itself is unavailable -- rejects here too, on purpose: that is a real
+// failure to distinguish from git successfully reporting "no branch", and
+// callers must not fold the two into the same undefined result.
+export async function foreignRootBranch(git: GitRunner): Promise<string | undefined> {
+	const symbolic = await git(["symbolic-ref", "--quiet", "--short", "HEAD"]);
+	const branch = symbolic.code === 0 ? symbolic.stdout.trim() : "";
+	if (!branch) return undefined;
+	const verified = await git(["rev-parse", "--verify", "-q", "HEAD"]);
+	return verified.code === 0 ? branch : "no commits yet";
+}
+
+// The session-evidence tracker behind /gentle:changes records roots, never
+// branches, so the overlay would label every tree "detached". This resolves
+// each root's own HEAD state once (branch, "no commits yet", undefined for a
+// real detached HEAD, or UNKNOWN_BRANCH when the root could not even be
+// asked), decorates the trees from the cache, and tells the caller when a
+// fresh answer arrived so the view can repaint. Git is touched only while the
+// overlay is open, never at startup or on evidence refresh.
+export class RootBranchLabels {
+	private readonly labels = new Map<string, string | undefined>();
+	private readonly pending = new Map<string, Promise<void>>();
+	private readonly gitForRoot: (root: string) => GitRunner;
+	private readonly onChange: () => void;
+	constructor(gitForRoot: (root: string) => GitRunner, onChange: () => void = () => {}) {
+		this.gitForRoot = gitForRoot;
+		this.onChange = onChange;
+	}
+
+	decorate(trees: readonly WorktreeChanges[]): WorktreeChanges[] {
+		return trees.map((tree) => {
+			if (tree.branch !== undefined) return tree;
+			if (!this.labels.has(tree.root)) this.resolve(tree.root);
+			const branch = this.labels.get(tree.root);
+			return branch === undefined ? tree : { ...tree, branch };
+		});
+	}
+
+	/** Every in-flight resolution has finished. */
+	async settled(): Promise<void> {
+		while (this.pending.size) await Promise.all(this.pending.values());
+	}
+
+	private resolve(root: string): void {
+		if (this.pending.has(root)) return;
+		// A rejection here means the root could not even be asked -- distinct
+		// from foreignRootBranch resolving to undefined, which means git
+		// answered and there really is no branch (a real detached HEAD).
+		const task = foreignRootBranch(this.gitForRoot(root))
+			.then(
+				(branch) => branch,
+				() => UNKNOWN_BRANCH,
+			)
+			.then((branch) => {
+				this.labels.set(root, branch);
+				this.pending.delete(root);
+				this.onChange();
+			});
+		this.pending.set(root, task);
+	}
+}
+
 export class WorktreeChangesTracker {
 	worktrees: WorktreeChanges[] = [];
 	private inFlight: Promise<ChangesModel> | undefined;
@@ -208,11 +284,22 @@ export class WorktreeChangesTracker {
 		// Discovery labels registered roots; it never grants visibility to siblings.
 		const roots = new Set(this.registeredRoots());
 		for (const root of roots) {
-			const tree = metadata.get(root) ?? { root };
+			const known = metadata.get(root);
 			try {
-				const tracker = new ChangesTracker(this.gitForRoot(tree.root), this.linesForRoot(tree.root));
+				const tracker = new ChangesTracker(this.gitForRoot(root), this.linesForRoot(root));
 				await tracker.start();
-				if (tracker.model.files.length) trees.push({ ...tree, model: tracker.model });
+				if (!tracker.model.files.length) continue;
+				// A root missing from this discovery scan belongs to a different Git
+				// clone entirely (e.g. an inner repository nested inside an outer
+				// one) -- worktree list can never describe a foreign clone, so ask
+				// it directly instead of defaulting to "detached". A root the scan
+				// DID describe is trusted as-is: its own "detached" marker (or lack
+				// of a branch) is already accurate for that clone. The direct ask
+				// can fail on its own (root gone, git unavailable) without the
+				// change scan above failing -- that must label the root
+				// UNKNOWN_BRANCH, not drop real, already-captured changes.
+				const branch = known ? known.branch : await foreignRootBranch(this.gitForRoot(root)).catch(() => UNKNOWN_BRANCH);
+				trees.push({ root, ...(branch ? { branch } : {}), model: tracker.model });
 			} catch {
 				// Linked roots can disappear between discovery and status.
 			}

package/lib/shell-hover.ts

@@ -0,0 +1,39 @@
+// One shared hover treatment for every clickable inline text/button surface
+// in the shell: the usage overlay's footer hints, the changes modal's rows
+// and controls, the agents panel, and the todo card's collapse control. A
+// single role swap on hover -- no per-surface variant -- so every clickable
+// text reads the same way once the pointer is over it.
+//
+// The header's usage segment deliberately does NOT use this: it is a single
+// one-row component outside any wrapping region, so pi-tui's fullscreen
+// dispatch (which only calls handleMouse on whichever leaf is under the
+// pointer, lib/shell-sidebar-layout.ts) never delivers a "leave" once the
+// pointer moves off it into the body below -- there is no move event left to
+// clear the paint. A background self-expiry timer could paper over that, but
+// was rejected as inelegant; the header usage segment stays click-only.
+//
+// This is presentation only. Each surface still tracks its own hovered state
+// from its own "move" events (or, where it already uses NativePointerRegion,
+// from that region's onHover/onLeave); this module exists so they all paint
+// that state identically.
+//
+// Under tmux, zellij, and screen, pi-tui's alt-screen driver only forwards
+// button-motion mouse reports, never plain "move" events (see
+// node_modules/@earendil-works/pi-tui/dist/tui-alt-screen.js, the input
+// parser around its SGR mouse handling), so nothing here ever activates in
+// those multiplexers -- there is no hover to paint, and clicking still works
+// exactly as before. This is a known platform limitation, not a bug to work
+// around here.
+
+export interface HoverTheme {
+	fg(role: string, text: string): string;
+}
+
+/** The single role every clickable surface uses to paint its own hover. */
+export const HOVER_ROLE = "warning";
+
+/** Paint `text` in the shared hover role when `hovered`, unchanged otherwise. */
+export function paintHoverable(theme: HoverTheme, text: string, hovered: boolean, idleRole?: string): string {
+	if (hovered) return theme.fg(HOVER_ROLE, text);
+	return idleRole === undefined ? text : theme.fg(idleRole, text);
+}

package/lib/shell-prompt.ts

@@ -48,6 +48,13 @@ export interface PromptFrameOptions {
 	borderColor: (text: string) => string;
 	fg: (color: string, text: string) => string;
 	bold?: (text: string) => string;
+	/**
+	 * Overrides the editor's own bottom scroll indicator (e.g. "esc again to
+	 * cancel"). Both share the bottom rule's single label slot; an explicit
+	 * hint always wins because it reflects state the editor cannot render on
+	 * its own.
+	 */
+	escHint?: string;
 }
 
 // A terminal cell cannot grow, so the petal earns presence with weight and
@@ -55,6 +62,8 @@ export interface PromptFrameOptions {
 export const PROMPT_PETAL = "✿";
 const PETAL_FRAMES = ["✿", "❀", "❁", "✾"] as const;
 export const PROMPT_HINT = "type, or / for commands";
+export const DOUBLE_ESC_CANCEL_HINT = "esc again to cancel";
+export const IDLE_ESC_CLEAR_HINT = "esc again to clear";
 const LABEL_ROLE = "muted";
 const HINT_ROLE = "dim";
 const FAKE_CURSOR = "\x1b[7m \x1b[0m";
@@ -119,7 +128,7 @@ export function framePromptLines(lines: string[], width: number, options: Prompt
 	const top = lines[0];
 	const bottom = lines[lines.length - 1];
 	const content = lines.slice(1, -1).map((line) => sideRules(line, innerWidth, options));
-	return [topRule(width, options, scrollIndicator(top)), ...content, bottomRule(width, options, scrollIndicator(bottom))];
+	return [topRule(width, options, scrollIndicator(top)), ...content, bottomRule(width, options, options.escHint ?? scrollIndicator(bottom))];
 }
 
 export function withPromptHint(line: string, hint: string, fg: PromptFrameOptions["fg"]): string {

package/lib/shell-sidebar-layout.ts

@@ -1,4 +1,4 @@
-import { ScrollView, visibleWidth, type Component, type TUI, type TuiMouseEvent } from "@earendil-works/pi-tui";
+import { ScrollView, VStack, visibleWidth, type Component, type TUI, type TuiMouseEvent } from "@earendil-works/pi-tui";
 import { sidebarState, type SidebarRail } from "./shell-sidebar.ts";
 import type { ShellBarTheme } from "./shell-bar.ts";
 import { renderSidebarBanner } from "./shell-sidebar-banner.ts";
@@ -6,15 +6,22 @@ import { renderSidebarBanner } from "./shell-sidebar-banner.ts";
 export const SIDEBAR_BREAKPOINT = 140;
 const RAIL_WIDTH = 50;
 const RAIL_PADDING = 1;
+// The rail's ScrollView keeps one column for its scrollbar; with the rail
+// padding that puts the card's right border two columns in from the edge.
+// The header row stops at the same column so its right group lines up with
+// the card instead of touching the terminal edge.
+const HEADER_RIGHT_INSET = RAIL_PADDING + 1;
 const GAP = 3;
 // Experimental Pi 0.85.1 internals. Only the fullscreen layout tree is adapted;
 // regular mode keeps native scrollback and the original bottom components.
 const NODE = Symbol.for("@earendil-works/pi-tui/layout-node");
-type LayoutNode = { type: string; entries?: unknown[]; gap?: number; align?: string };
+type LayoutNode = { type: string; entries?: unknown[]; gap?: number; align?: "stretch" | "start" | "center" | "end" };
+type StackLayoutEntry = ConstructorParameters<typeof VStack>[0] extends Array<infer T> | undefined ? Exclude<T, Component> : never;
 type LayoutRoot = Component & { [NODE]?: () => LayoutNode };
 type Host = TUI & { mode?: string; layoutRoot?: LayoutRoot };
 type SidebarCache = { revision: number };
 type RailHit = { key: string; component: Component; startY: number; height: number; width: number };
+type SectionCacheEntry = { component: Component; digest: string | undefined; revision: number; contentWidth: number; theme: ShellBarTheme; lines: string[] };
 type SidebarPresentation = { scrollTop: number; output: LayoutNode };
 type PreparedRail = {
 	revision: number;
@@ -28,6 +35,11 @@ type PreparedRail = {
 	active: boolean;
 	lines: string[];
 	hits: RailHit[];
+	// The header row is a full-width sibling above the hstack, not a rail
+	// section: it never enters `lines`/`hits`, and an empty/blank result
+	// falls back to the old hstack-direct shape with the banner restored.
+	headerLines: string[];
+	headerActive: boolean;
 	presentation?: SidebarPresentation;
 };
 const CACHE = Symbol.for("gentle-pi.experimental-sidebar.cache");
@@ -66,7 +78,15 @@ export function installSidebar(tui: TUI, theme: ShellBarTheme): () => void {
 	let stopped = false;
 	let failed = false;
 	let railLines: string[] = [];
+	let headerLines: string[] = [];
 	let prepared: PreparedRail | undefined;
+	// One rendered-lines cache per rail section key, independent of the
+	// whole-rail `prepared` memo below: a section with its own digest is
+	// revalidated by that digest alone, so a sibling's ticking digest (the
+	// header/Status counters) never forces Agents or TODO to re-render. A
+	// section with no digest (or a throwing one) falls back to the shared
+	// revision counter, exactly like the whole-rail memo already did.
+	const sectionCache = new Map<string, SectionCacheEntry>();
 	state.active = false;
 	state.ownsHost = () => !stopped && host.mode === "fullscreen" && !!host.layoutRoot && roots.has(host.layoutRoot);
 	const rail: Component = {
@@ -76,6 +96,19 @@ export function installSidebar(tui: TUI, theme: ShellBarTheme): () => void {
 			for (const part of state.parts.values()) part.invalidate();
 		},
 	};
+	// The header row: a plain leaf component, one line tall, painted above the
+	// hstack when a "header" part is registered and has something to show.
+	// The header is not inside the rail's ScrollView, so it never goes through
+	// dispatchPartMouse: it is its own leaf in the layout tree (no [NODE]),
+	// and pi-tui's mouse dispatch (tui-alt-screen.js dispatchMouseToLayout)
+	// finds and calls handleMouse on whatever leaf box is under the pointer
+	// directly, without any wiring of our own. Delegate straight to whatever
+	// the registered "header" part declares.
+	const header: Component = {
+		render: () => headerLines,
+		invalidate() {},
+		handleMouse: (event) => state.parts.get("header")?.handleMouse?.(event),
+	};
 	const scroll = new ScrollView(rail, {
 		follow: "none",
 		primary: false,
@@ -133,28 +166,55 @@ export function installSidebar(tui: TUI, theme: ShellBarTheme): () => void {
 			return prepared.active;
 		}
 		try {
+			// The header is a full-width sibling row, not a rail section: it reads
+			// the terminal width (minus the rail's right inset), never the
+			// 50-column rail's content width.
+			const headerPart = state.parts.get("header");
+			const preparedHeaderLines = [...(headerPart?.render(Math.max(0, width - HEADER_RIGHT_INSET)) ?? [])];
+			const headerActive = headerPart !== undefined && preparedHeaderLines.some((line) => line.trim() !== "");
 			const contentWidth = scroll.getContentWidth(RAIL_WIDTH);
 			const sections = ["footer", "agents", "todo"].map((key) => {
 				const component = state.parts.get(key);
-				const lines = [...(component?.render(contentWidth - RAIL_PADDING * 2) ?? [])];
-				while (lines.length && lines[lines.length - 1]?.trim() === "") lines.pop();
+				if (!component) {
+					sectionCache.delete(key);
+					return { key, component, lines: [] as string[] };
+				}
+				const digest = railDigest(component);
+				const existing = sectionCache.get(key);
+				const reusable = existing?.component === component && existing.contentWidth === contentWidth && existing.theme === theme &&
+					(digest !== undefined ? existing.digest === digest : existing.digest === undefined && existing.revision === cache.revision);
+				const lines = reusable ? existing.lines : (() => {
+					const rendered = [...(component.render(contentWidth - RAIL_PADDING * 2) ?? [])];
+					while (rendered.length && rendered[rendered.length - 1]?.trim() === "") rendered.pop();
+					return rendered;
+				})();
+				sectionCache.set(key, { component, digest, revision: cache.revision, contentWidth, theme, lines });
 				return { key, component, lines };
 			}).filter((section) => section.component !== undefined && section.lines.length > 0) as Array<{ key: string; component: Component; lines: string[] }>;
-			const branding = renderSidebarBanner(theme, contentWidth - RAIL_PADDING * 2);
+			// The header carries the brand once it is active; the banner is the
+			// rail's fallback identity when no header is wired up.
+			const branding = headerActive ? [] : renderSidebarBanner(theme, contentWidth - RAIL_PADDING * 2);
 			const hits: RailHit[] = [];
 			railLines = [];
 			if (sections.length && branding.length) {
 				railLines.push(...branding.map((line) => " ".repeat(RAIL_PADDING) + line + " ".repeat(RAIL_PADDING)));
+			} else if (sections.length && headerActive) {
+				// The banner used to hold the first card off the top; the header
+				// took its place, so keep one blank row between them.
+				railLines.push("");
 			}
 			for (const section of sections) {
-				if (railLines.length > 0) railLines.push("");
+				// One blank row separates a section from the banner or the
+				// previous section; the header gap above is not a section.
+				if (hits.length > 0 || branding.length > 0) railLines.push("");
 				const startY = railLines.length;
 				railLines.push(...section.lines.map((line) => " ".repeat(RAIL_PADDING) + line + " ".repeat(RAIL_PADDING)));
 				hits.push({ key: section.key, component: section.component, startY, height: section.lines.length, width: contentWidth - RAIL_PADDING * 2 });
 			}
 			// Height is owned by the native ScrollView, never by the transcript.
 			const active = railLines.length > 0 && railLines.every((line) => visibleWidth(line) <= contentWidth);
-			prepared = { revision: cache.revision, width, mode: host.mode, root, theme, parts, digests, contentWidth, active, lines: railLines, hits };
+			headerLines = active && headerActive ? preparedHeaderLines : [];
+			prepared = { revision: cache.revision, width, mode: host.mode, root, theme, parts, digests, contentWidth, active, lines: railLines, hits, headerLines, headerActive: headerLines.length > 0 };
 			state.active = active;
 			return active;
 		} catch {
@@ -174,18 +234,54 @@ export function installSidebar(tui: TUI, theme: ShellBarTheme): () => void {
 			// Fullscreen gives this stretched stack an explicit viewport height.
 			// Its intrinsic-height probe is unused; real painting traverses NODE.
 			// Delegating that probe to root.render would render the transcript twice.
-			const left = { render: () => [], invalidate() {}, [NODE]: () => original.call(root) };
+			// Pi's dock reserves one row for the footer (chat-viewport: minSize 1)
+			// even though our footer paints nothing while the sidebar is active.
+			// The row is baked in twice: the dock's own VStack.render pads it into
+			// the intrinsic height the root measures, and its layout node keeps
+			// it as minSize. Overriding only the node leaves the measured blank
+			// row in place, so the dock is re-hosted in a real VStack over the
+			// same children with the footer entry free to shrink to zero. One
+			// wrapper per dock keeps component identity stable across frames.
+			const docks = new WeakMap<Component, VStack>();
+			const reclaimFooterRow = (node: LayoutNode): LayoutNode => {
+				if (node.type !== "vstack" || !node.entries?.length) return node;
+				const entries = node.entries as Array<{ component: Component & { [NODE]?: () => LayoutNode } }>;
+				const dock = entries[entries.length - 1]!.component;
+				if (typeof dock[NODE] !== "function") return node;
+				let wrapped = docks.get(dock);
+				if (!wrapped) {
+					const inner = dock[NODE]!();
+					if (inner.type !== "vstack" || !inner.entries?.length) return node;
+					const last = inner.entries.length - 1;
+					wrapped = new VStack(inner.entries.map((entry, index) => index === last ? { ...(entry as StackLayoutEntry), minSize: 0 } : entry as StackLayoutEntry), { gap: inner.gap, align: inner.align });
+					docks.set(dock, wrapped);
+				}
+				return { ...node, entries: entries.map((entry, index) => index === entries.length - 1 ? { ...entry, component: wrapped! } : entry) };
+			};
+			const left = { render: () => [], invalidate() {}, [NODE]: () => reclaimFooterRow(original.call(root)) };
+			// Stable component wrapping the [left, scroll] hstack behind its own
+			// NODE, exactly like `left` wraps the native transcript: the header
+			// vstack's second entry recurses into it the same way pi-tui already
+			// recurses into a nested layout via [NODE].
+			const hstackHost: Component & { [NODE](): LayoutNode } = {
+				render: () => [],
+				invalidate() {},
+				[NODE]: () => ({ type: "hstack", gap: GAP, align: "stretch", entries: [
+					{ component: left, basis: 0, grow: 1, shrink: 1, minSize: 1 },
+					{ component: scroll, basis: RAIL_WIDTH, grow: 0, shrink: 0, minSize: RAIL_WIDTH },
+				] }),
+			};
 			const replacement = () => {
 				if (!prepare(tui.terminal.columns, root)) return original.call(root);
 				const current = prepared!;
 				if (current.presentation?.scrollTop === scroll.scrollTop) return current.presentation.output;
-				return (current.presentation = {
-					scrollTop: scroll.scrollTop,
-					output: { type: "hstack", gap: GAP, align: "stretch", entries: [
-						{ component: left, basis: 0, grow: 1, shrink: 1, minSize: 1 },
-						{ component: scroll, basis: RAIL_WIDTH, grow: 0, shrink: 0, minSize: RAIL_WIDTH },
-					] },
-				}).output;
+				const output: LayoutNode = current.headerActive
+					? { type: "vstack", gap: 0, align: "stretch", entries: [
+						{ component: header, basis: 1, grow: 0, shrink: 0, minSize: 1 },
+						{ component: hstackHost, basis: 0, grow: 1, shrink: 1, minSize: 1 },
+					] }
+					: hstackHost[NODE]();
+				return (current.presentation = { scrollTop: scroll.scrollTop, output }).output;
 			};
 			root[NODE] = replacement;
 			roots.add(root);

package/lib/shell-sidebar.ts

@@ -39,3 +39,19 @@ export function sidebarPart<T extends Component & { dispose?(): void }>(tui: TUI
 		},
 	};
 }
+
+/**
+ * Register the fullscreen header rail: the one row above the hstack that
+ * carries the brand, session identity, and the per-frame counters. There is
+ * no narrow-mode bottom counterpart — the compact bar already carries this
+ * data when the sidebar is inactive — so this only ever writes the "header"
+ * slot in sidebarState(tui).parts, and returns its own disposer.
+ */
+export function sidebarHeader(tui: TUI, rail: SidebarRail): () => void {
+	if (!tui.terminal) return () => {};
+	const state = sidebarState(tui);
+	state.parts.set("header", rail);
+	return () => {
+		if (state.parts.get("header") === rail) state.parts.delete("header");
+	};
+}

package/lib/shell-todo.ts

@@ -1,6 +1,7 @@
 import { wrapTextWithAnsi } from "@earendil-works/pi-tui";
 import { CARD_TONE, cardInnerWidth, renderCard, type CardTheme } from "./shell-card.ts";
 import { sanitizeTerminalText } from "./terminal-theme.ts";
+import { paintHoverable } from "./shell-hover.ts";
 
 // Gentle Todo: the task list the model keeps while it works. Everything here
 // is pure. The state lives in the session branch (every tool result carries
@@ -77,6 +78,8 @@ export interface TodoRenderOptions {
 	collapsed: boolean;
 	staleTurns: number;
 	collapseKey?: string;
+	/** The pointer is over the clickable collapse/expand control. */
+	hovered?: boolean;
 }
 
 /** Tool results carry the snapshot under this key; the old rpiv-todo shape is read too. */
@@ -288,8 +291,11 @@ export function renderTodoCard(state: TodoState, theme: TodoTheme, width: number
 	const hint = options.collapseKey ? `${options.collapseKey} ${action}` : undefined;
 	const rows = options.collapsed ? [collapsedRow(state, theme, width)] : options.scrollable ? state.tasks.map((task) => taskRow(task, theme, width)) : bodyRows(state, theme, width);
 	const body = stale ? [theme.fg(NOTE_ROLE, `stale · ${options.staleTurns} turns`), ...rows] : rows;
+	// The clickable control paints the shared hover role while hovered --
+	// same treatment every other clickable surface uses -- instead of its
+	// ordinary accent role.
 	return renderCard(
-		{ title: `Todos ${theme.fg("accent", control)}`, subtitle: `${done} of ${total}`, body, tone: stale ? CARD_TONE.WARNING : CARD_TONE.INFO, glyph: TODO_GLYPH },
+		{ title: `Todos ${paintHoverable(theme, control, options.hovered, "accent")}`, subtitle: `${done} of ${total}`, body, tone: stale ? CARD_TONE.WARNING : CARD_TONE.INFO, glyph: TODO_GLYPH },
 		theme,
 		width,
 		{ expanded: true, hint },