gentle-pi 3.7.0 → 4.1.0

package/lib/shell-changes.ts

@@ -27,7 +27,6 @@ export interface ChangesModel {
 	files: ChangedFile[];
 	added: number;
 	deleted: number;
-	notice?: string;
 }
 
 export interface ChangesSnapshot {
@@ -46,6 +45,11 @@ interface NumstatEntry {
 }
 
 export const CHANGES_COMMAND = "/gentle:changes";
+// One selected file's diff is the only bounded thing in Changes: past either
+// limit the panel shows DIFF_TOO_LARGE instead of buffering and coloring it.
+export const DIFF_MAX_BYTES = 1024 * 1024;
+export const DIFF_MAX_LINES = 20_000;
+export const DIFF_TOO_LARGE = "Diff too large — press o to open in editor.";
 const WIDGET_GLYPH = "✎";
 const STATUS_BY_CODE: Record<string, ChangeStatus> = {
 	A: CHANGE_STATUS.ADDED,
@@ -123,7 +127,7 @@ export function changesModel(changed: ChangedFile[]): ChangesModel {
 
 export function changesSummary(model: ChangesModel): string {
 	const noun = model.files.length === 1 ? "file" : "files";
-	return `${model.files.length} ${noun} · +${model.added} −${model.deleted}${model.files.some(file => file.countsUnavailable) ? " · partial counts" : ""}${model.notice ? " · capture limit reached" : ""}`;
+	return `${model.files.length} ${noun} · +${model.added} −${model.deleted}${model.files.some(file => file.countsUnavailable) ? " · partial counts" : ""}`;
 }
 
 // One line: summary, the files joined by dots, and the command pushed to
@@ -132,7 +136,7 @@ export function renderChangesWidget(model: ChangesModel, theme: ChangesTheme, wi
 	if (model.files.length === 0) return [];
 	const noun = model.files.length === 1 ? "file" : "files";
 	const dot = theme.fg("muted", "·");
-	const head = `${theme.fg("accent", WIDGET_GLYPH)} ${theme.fg("text", `${model.files.length} ${noun}`)} ${dot} ${theme.fg("success", `+${model.added}`)} ${theme.fg("error", `−${model.deleted}`)}${model.files.some(file => file.countsUnavailable) ? " · partial counts" : ""}${model.notice ? ` ${dot} ${theme.fg("warning", "capture limit reached")}` : ""}`;
+	const head = `${theme.fg("accent", WIDGET_GLYPH)} ${theme.fg("text", `${model.files.length} ${noun}`)} ${dot} ${theme.fg("success", `+${model.added}`)} ${theme.fg("error", `−${model.deleted}`)}${model.files.some(file => file.countsUnavailable) ? " · partial counts" : ""}`;
 	const hint = theme.fg("dim", CHANGES_COMMAND);
 	const list = model.files.map((file) => theme.fg("muted", file.path)).join(` ${dot} `);
 	const left = `${head} ${dot} ${list}`;
@@ -146,10 +150,14 @@ export function renderChangesWidget(model: ChangesModel, theme: ChangesTheme, wi
 export interface GitResult {
 	stdout: string;
 	code: number;
+	/** The runner stopped reading at its output bound; stdout is partial. */
+	truncated?: boolean;
 }
 
 export type GitRunner = (args: string[]) => Promise<GitResult>;
 export type LineCounter = (path: string) => Promise<number>;
+/** A cheap content identity (e.g. size and mtime) so same-count edits refresh their diff. */
+export type FileRevision = (path: string) => Promise<string | undefined>;
 
 export interface WorktreeChanges {
 	root: string;
@@ -189,76 +197,41 @@ export async function foreignRootBranch(git: GitRunner): Promise<string | undefi
 	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);
-	}
-}
-
+// /gentle:changes: one group per registered root holding its working tree
+// against HEAD. A root whose Git fails (timed out, rejected) has no group but
+// is listed in failedRoots: a failed scan is never reported as a clean root.
 export class WorktreeChangesTracker {
 	worktrees: WorktreeChanges[] = [];
+	failedRoots: string[] = [];
+	scannedRootCount = 0;
 	private inFlight: Promise<ChangesModel> | undefined;
 	private readonly discover: GitRunner;
 	private readonly gitForRoot: (root: string) => GitRunner;
 	private readonly linesForRoot: (root: string) => LineCounter;
 	private readonly registeredRoots: () => readonly string[];
+	private readonly revisionForRoot: (root: string) => FileRevision | undefined;
 
-	constructor(discover: GitRunner, gitForRoot: (root: string) => GitRunner, linesForRoot: (root: string) => LineCounter = () => noLines, registeredRoots: () => readonly string[] = () => []) {
+	constructor(discover: GitRunner, gitForRoot: (root: string) => GitRunner, linesForRoot: (root: string) => LineCounter = () => noLines, registeredRoots: () => readonly string[] = () => [], revisionForRoot: (root: string) => FileRevision | undefined = () => undefined) {
 		this.discover = discover;
 		this.gitForRoot = gitForRoot;
 		this.linesForRoot = linesForRoot;
 		this.registeredRoots = registeredRoots;
+		this.revisionForRoot = revisionForRoot;
 	}
 
+	private modelOf: WorktreeChanges[] | undefined;
+	private combined: ChangesModel = emptyChanges();
+
+	// Footers read this every frame; rebuild only when a scan replaced the trees.
 	get model(): ChangesModel {
-		return changesModel(this.worktrees.flatMap((tree) => tree.model.files.map((file) => ({
-			...file,
-			path: this.worktrees.length === 1 ? file.path : `${tree.root}/${file.path}`,
-		}))));
+		if (this.modelOf !== this.worktrees) {
+			this.modelOf = this.worktrees;
+			this.combined = changesModel(this.worktrees.flatMap((tree) => tree.model.files.map((file) => ({
+				...file,
+				path: this.worktrees.length === 1 ? file.path : `${tree.root}/${file.path}`,
+			}))));
+		}
+		return this.combined;
 	}
 
 	async start(): Promise<void> {
@@ -278,17 +251,29 @@ export class WorktreeChangesTracker {
 	}
 
 	private async capture(): Promise<ChangesModel> {
-		const result = await this.discover(["worktree", "list", "--porcelain", "-z"]).catch(() => ({ code: 128, stdout: "" }));
-		const trees: WorktreeChanges[] = [];
-		const metadata = new Map((result.code === 0 ? parseWorktrees(result.stdout) : []).map((tree) => [tree.root, tree]));
 		// Discovery labels registered roots; it never grants visibility to siblings.
 		const roots = new Set(this.registeredRoots());
-		for (const root of roots) {
+		// No root to scan means no Git at all, not even branch discovery.
+		if (roots.size === 0) {
+			this.worktrees = [];
+			this.failedRoots = [];
+			this.scannedRootCount = 0;
+			return this.model;
+		}
+		const result = await this.discover(["worktree", "list", "--porcelain", "-z"]).catch(() => ({ code: 128, stdout: "" }));
+		const metadata = new Map((result.code === 0 ? parseWorktrees(result.stdout) : []).map((tree) => [tree.root, tree]));
+		// Roots scan in parallel so one slow root does not delay the others.
+		const failed: string[] = [];
+		const scanned = await Promise.all([...roots].map(async (root): Promise<WorktreeChanges | undefined> => {
 			const known = metadata.get(root);
 			try {
-				const tracker = new ChangesTracker(this.gitForRoot(root), this.linesForRoot(root));
+				const tracker = new ChangesTracker(this.gitForRoot(root), this.linesForRoot(root), this.revisionForRoot(root));
 				await tracker.start();
-				if (!tracker.model.files.length) continue;
+				if (!tracker.statusRead) {
+					failed.push(root);
+					return undefined;
+				}
+				if (!tracker.model.files.length) return undefined;
 				// 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
@@ -299,22 +284,40 @@ export class WorktreeChangesTracker {
 				// 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 });
+				return { root, ...(branch ? { branch } : {}), model: tracker.model };
 			} catch {
-				// Linked roots can disappear between discovery and status.
+				// A root the caller stops registering mid-scan (e.g. a removed
+				// worktree) triggers the rescan below without it, not a failure.
+				failed.push(root);
+				return undefined;
 			}
-		}
+		}));
+		const trees = scanned.filter((tree): tree is WorktreeChanges => tree !== undefined);
 		const latest = new Set(this.registeredRoots());
 		// A root admitted during status must not wait for a later poll (which may
 		// be disabled). Ordinary overlapping polls still share exactly one scan.
 		if (latest.size !== roots.size || [...latest].some((root) => !roots.has(root))) return this.capture();
 		this.worktrees = trees;
+		this.failedRoots = failed;
+		this.scannedRootCount = roots.size;
 		return this.model;
 	}
 }
 
 const noLines: LineCounter = async () => 0;
 
+// Per-file line counts and revision lookups are file IO: a large change set
+// runs this many files at a time instead of one by one or all at once.
+export const FILE_WORK_CONCURRENCY = 8;
+
+async function eachLimited<T>(items: readonly T[], limit: number, work: (item: T) => Promise<void>): Promise<void> {
+	let next = 0;
+	const worker = async () => {
+		while (next < items.length) await work(items[next++]);
+	};
+	await Promise.all(Array.from({ length: Math.min(limit, items.length) }, worker));
+}
+
 const NUMSTAT_ARGS = ["diff", "--numstat", "HEAD"];
 const PORCELAIN_ARGS = ["status", "--porcelain=v1", "--untracked-files=all", "-z"];
 
@@ -324,20 +327,27 @@ const PORCELAIN_ARGS = ["status", "--porcelain=v1", "--untracked-files=all", "-z
 export class ChangesTracker {
 	private readonly git: GitRunner;
 	private readonly countLines: LineCounter;
+	private readonly revision: FileRevision | undefined;
 	private current: ChangesModel = emptyChanges();
 	private available = false;
 	private inFlight: Promise<ChangesModel> | undefined;
 	private queued = false;
 
-	constructor(git: GitRunner, countLines: LineCounter = noLines) {
+	constructor(git: GitRunner, countLines: LineCounter = noLines, revision?: FileRevision) {
 		this.git = git;
 		this.countLines = countLines;
+		this.revision = revision;
 	}
 
 	get model(): ChangesModel {
 		return this.current;
 	}
 
+	/** False when the last start could not read `git status`. */
+	get statusRead(): boolean {
+		return this.available;
+	}
+
 	async start(): Promise<void> {
 		const files = await this.capture();
 		this.available = files !== undefined;
@@ -372,9 +382,14 @@ export class ChangesTracker {
 		if (porcelain.code !== 0) return undefined;
 		const files = snapshotChanges({ numstat: numstat.stdout, porcelain: porcelain.stdout });
 		// Untracked files never appear in numstat; count their lines directly.
-		for (const file of files) {
-			if (file.status === CHANGE_STATUS.UNTRACKED) file.added = await this.countLines(file.path).catch(() => 0);
-		}
+		await eachLimited(files, FILE_WORK_CONCURRENCY, async (file) => {
+			const [added, revision] = await Promise.all([
+				file.status === CHANGE_STATUS.UNTRACKED ? this.countLines(file.path).catch(() => 0) : undefined,
+				this.revision?.(file.path).catch(() => undefined),
+			]);
+			if (added !== undefined) file.added = added;
+			if (revision) file.diffRevision = revision;
+		});
 		return files;
 	}
 }

package/lib/shell-prompt.ts

@@ -1,9 +1,9 @@
 import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
 import { stripAnsi } from "./terminal-theme.ts";
+import { CARD_STYLE, type CardStyle } from "./shell-card.ts";
 
-// Gentle Shell prompt frame. pi's editor renders a top rule, padded content
-// lines, and a bottom rule; this module wraps those lines in a rounded frame
-// with a petal that shows what the agent is doing. Everything here is pure.
+// Pure prompt chrome: neon keeps Pi's rule/content/rule rows in a rounded
+// frame; float retains those indices as painted status/content/padding.
 
 export const PROMPT_STATE = {
 	IDLE: "idle",
@@ -43,6 +43,8 @@ export function scanWorkingText(text: string, tick: number, fg: (role: string, t
 const PETAL_TONE_FRAMES = [PETAL_TONE.DEEP, PETAL_TONE.SOFT, PETAL_TONE.ROSE, PETAL_TONE.BRIGHT, PETAL_TONE.ROSE, PETAL_TONE.SOFT, PETAL_TONE.DEEP, PETAL_TONE.DEEP] as const;
 
 export interface PromptFrameOptions {
+	style?: CardStyle;
+	bg?: (role: string, text: string) => string;
 	state: PromptState;
 	tick: number;
 	borderColor: (text: string) => string;
@@ -50,11 +52,17 @@ export interface PromptFrameOptions {
 	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
+	 * cancel"). Both share the bottom rule / float hint slot; an explicit
 	 * hint always wins because it reflects state the editor cannot render on
 	 * its own.
 	 */
 	escHint?: string;
+	/**
+	 * Overrides the generic "working…" label while state is WORKING with an
+	 * explicit, orchestrator-reported ODD phase label (e.g. "exploring…").
+	 * Ignored outside the WORKING state; undefined falls back to "working…".
+	 */
+	workingLabel?: string;
 }
 
 // A terminal cell cannot grow, so the petal earns presence with weight and
@@ -93,8 +101,13 @@ function rule(length: number): string {
 	return "─".repeat(Math.max(0, length));
 }
 
+function stateLabel(options: PromptFrameOptions): string | undefined {
+	if (options.state === PROMPT_STATE.WORKING) return options.workingLabel ?? STATE_LABEL[PROMPT_STATE.WORKING];
+	return STATE_LABEL[options.state];
+}
+
 function topRule(width: number, options: PromptFrameOptions, indicator: string | undefined): string {
-	const label = indicator ?? STATE_LABEL[options.state];
+	const label = indicator ?? stateLabel(options);
 	const scanning = options.state === PROMPT_STATE.WORKING;
 	const glyph = petalGlyph(options.state, options.tick);
 	const petal = options.fg(petalTone(options.state, options.tick), options.bold ? options.bold(glyph) : glyph);
@@ -120,8 +133,91 @@ function sideRules(line: string, innerWidth: number, options: PromptFrameOptions
 	return options.borderColor("│") + content + options.borderColor("│");
 }
 
-export function framePromptLines(lines: string[], width: number, options: PromptFrameOptions): string[] {
+export interface PromptLayout {
+	width: number;
+	nativeWidth: number;
+	prefixWidth: number;
+	background: string;
+}
+
+/** Resolve fallback before native wrapping, selection, completion and mouse geometry. */
+export function resolvePromptLayout(width: number, style?: CardStyle, bg?: PromptFrameOptions["bg"]): PromptLayout {
+	width = Math.max(0, Math.floor(width));
+	let background = "";
+	if (style === CARD_STYLE.FLOAT && width >= 10 && bg) {
+		try {
+			const painted = bg("toolSuccessBg", " ");
+			const match = painted.match(/^((?:\x1b\[[\d;]*m)+) (?:\x1b\[(?:49|0)?m)$/);
+			if (match) {
+				for (const sgr of match[1].matchAll(/\x1b\[([\d;]*)m/g)) {
+					for (const command of promptSgrCommands(sgr[1])) {
+						const code = command[0];
+						if (code === 0 || code === 49) background = "";
+						else if ((code >= 40 && code <= 47) || (code >= 100 && code <= 107) ||
+							(code === 48 && ((command[1] === 5 && command.length === 3) || (command[1] === 2 && command.length === 5)))) {
+							background = `\x1b[${command.join(";")}m`;
+						}
+					}
+				}
+			}
+		} catch { /* Missing theme background: retain the entire neon path. */ }
+	}
+	return { width, nativeWidth: Math.max(1, width - (background ? 5 : 2)), prefixWidth: background ? 3 : 1, background };
+}
+
+// Extended-colour parameters belong to one command: zero RGB channels
+// must never be interpreted as full styling resets.
+function promptSgrCommands(parameters: string): number[][] {
+	const codes = parameters.split(";").map(Number);
+	const commands: number[][] = [];
+	for (let i = 0; i < codes.length;) {
+		const extended = codes[i] === 38 || codes[i] === 48 || codes[i] === 58;
+		const length = extended && codes[i + 1] === 2 ? 5 : extended && codes[i + 1] === 5 ? 3 : 1;
+		commands.push(codes.slice(i, i + length));
+		i += length;
+	}
+	return commands;
+}
+
+// Rearm only the panel background, leaving marker/inversion bytes intact.
+function rearmPromptBackground(text: string, background: string): string {
+	return text.replace(/\x1b\[([\d;]*)m/g, (sgr, parameters: string) =>
+		promptSgrCommands(parameters).some(([code]) => code === 0 || code === 49) ? sgr + background : sgr);
+}
+
+/** Same chrome and horizontal prefix for editable and native completion rows. */
+export function floatPromptRow(line: string, layout: PromptLayout, borderColor: PromptFrameOptions["borderColor"]): string {
+	const clipped = truncateToWidth(line, layout.nativeWidth, "");
+	const content = borderColor("▎") + " " + clipped + " ".repeat(Math.max(0, layout.nativeWidth - visibleWidth(clipped))) + " ";
+	return " " + layout.background + rearmPromptBackground(content, layout.background) + "\x1b[49m ";
+}
+
+function floatPromptHint(top: string, bottom: string, options: PromptFrameOptions, width: number): string {
+	const glyph = petalGlyph(options.state, options.tick);
+	const petal = options.fg(petalTone(options.state, options.tick), options.bold ? options.bold(glyph) : glyph);
+	const label = stateLabel(options) ?? "waiting for input";
+	let paintedLabel = "";
+	if (label) {
+		paintedLabel = options.state === PROMPT_STATE.WORKING
+			? scanWorkingText(label, options.tick, options.fg)
+			: options.fg(LABEL_ROLE, label);
+	}
+	const info = [scrollIndicator(top), options.escHint ?? scrollIndicator(bottom)]
+		.filter((text): text is string => Boolean(text))
+		.map((text) => options.fg(LABEL_ROLE, text));
+	const hint = truncateToWidth("  " + petal + (paintedLabel ? " " + paintedLabel : "") + (info.length ? " · " + info.join(" · ") : ""), width, "");
+	return hint + " ".repeat(Math.max(0, width - visibleWidth(hint)));
+}
+
+export function framePromptLines(lines: string[], width: number, options: PromptFrameOptions, layout = resolvePromptLayout(width, options.style, options.bg)): string[] {
 	width = Math.max(0, Math.floor(width));
+	if (layout.background && lines.length >= 2) {
+		return [
+			floatPromptRow(floatPromptHint(lines[0], lines[lines.length - 1], options, layout.nativeWidth).slice(2), layout, options.borderColor),
+			...lines.slice(1, -1).map((line) => floatPromptRow(line, layout, options.borderColor)),
+			floatPromptRow("", layout, options.borderColor),
+		];
+	}
 	if (lines.length < 2) return lines.map((line) => truncateToWidth(line, width, ""));
 	if (width < 2) return lines.map((_line, index) => width === 0 ? "" : options.borderColor(index === 0 ? "╭" : index === lines.length - 1 ? "╰" : "│"));
 	const innerWidth = width - 2;

package/lib/shell-sidebar-layout.ts

@@ -1,7 +1,9 @@
 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 { CARD_STYLE, cardStyle, type CardStyle } from "./shell-card.ts";
 import { renderSidebarBanner } from "./shell-sidebar-banner.ts";
+import type { Density, HeaderPlacement, StatusPlacement } from "./visual-customization-policy.ts";
 
 export const SIDEBAR_BREAKPOINT = 140;
 const RAIL_WIDTH = 50;
@@ -12,6 +14,8 @@ const RAIL_PADDING = 1;
 // the card instead of touching the terminal edge.
 const HEADER_RIGHT_INSET = RAIL_PADDING + 1;
 const GAP = 3;
+/** Right-edge columns the painting rail takes from the editor column; published as `railColumns`. */
+export const SIDEBAR_RAIL_COLUMNS = RAIL_WIDTH + GAP;
 // 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");
@@ -27,6 +31,8 @@ type PreparedRail = {
 	revision: number;
 	width: number;
 	mode: string | undefined;
+	headerPlacement: HeaderPlacement;
+	cardStyle: CardStyle;
 	root: LayoutRoot;
 	theme: ShellBarTheme;
 	parts: Array<[string, SidebarRail]>;
@@ -68,8 +74,28 @@ function railDigest(rail: SidebarRail): string | undefined {
 	}
 }
 
+export const STATUS_OWNER = { HEADER: "header", BOTTOM: "bottom" } as const;
+export type StatusOwner = (typeof STATUS_OWNER)[keyof typeof STATUS_OWNER];
+export interface StatusOwnerInput {
+	mode: string | undefined;
+	columns: number;
+	statusPlacement: StatusPlacement;
+	headerPlacement: HeaderPlacement;
+}
+
+/**
+ * Which single status row owns a narrow fullscreen terminal, so the header and
+ * the bottom bar never both paint there. A configured top header wins;
+ * otherwise the bottom bar does, unless Status is hidden and the below-input
+ * header is all that is left. Wide and regular layouts keep their own rules.
+ */
+export function narrowStatusOwner(input: StatusOwnerInput): StatusOwner | undefined {
+	if (input.mode !== "fullscreen" || input.columns >= SIDEBAR_BREAKPOINT) return undefined;
+	return input.headerPlacement === "top" || input.statusPlacement === "hidden" ? STATUS_OWNER.HEADER : STATUS_OWNER.BOTTOM;
+}
+
 /** Installs the fullscreen rail: wraps the host layout root with the [rail, transcript] hstack and returns a disposer restoring the original layout. */
-export function installSidebar(tui: TUI, theme: ShellBarTheme): () => void {
+export function installSidebar(tui: TUI, theme: ShellBarTheme, placement: () => StatusPlacement = () => "auto", headerPlacement: () => HeaderPlacement = () => "top", density: () => Density = () => "comfortable"): () => void {
 	if (!tui.terminal) return () => {};
 	const host = tui as Host;
 	const state = sidebarState(tui);
@@ -89,7 +115,17 @@ export function installSidebar(tui: TUI, theme: ShellBarTheme): () => void {
 	// 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);
+	// Hidden removes Status everywhere, including regular mode where the rail
+	// never mounts, so it is published independently of the fullscreen layout.
+	state.statusHidden = () => !stopped && placement() === "hidden";
+	// A narrow top header is the only status row there. Whether it paints comes
+	// from the last layout pass (a blank or failed header never swallows the
+	// bottom bar); the geometry is read live so a resize applies before the next pass.
+	const headerOwnsStatus = () => !stopped && !failed && headerLines.length > 0 && headerPlacement() === "top" &&
+		narrowStatusOwner({ mode: host.mode, columns: tui.terminal.columns, statusPlacement: placement(), headerPlacement: headerPlacement() }) === STATUS_OWNER.HEADER;
+	state.headerOwnsStatus = headerOwnsStatus;
+	state.railColumns = SIDEBAR_RAIL_COLUMNS;
+	state.ownsHost = () => !stopped && host.mode === "fullscreen" && tui.terminal.columns >= SIDEBAR_BREAKPOINT && (placement() === "auto" || placement() === "right") && !!host.layoutRoot && roots.has(host.layoutRoot);
 	const rail: Component = {
 		render: () => railLines,
 		invalidate() {
@@ -143,6 +179,10 @@ export function installSidebar(tui: TUI, theme: ShellBarTheme): () => void {
 	};
 	scroll.handleMouse = (event) => {
 		if (event.type === "wheel") {
+			// A bounded section (Todo) owns its inner viewport. Only wheel
+			// events it declines should move the surrounding rail.
+			const sectionResult = dispatchPartMouse(event);
+			if (sectionResult?.handled) return sectionResult;
 			// Consume even at the boundary or over blank rail space: Pi 0.85.1
 			// can send unconsumed delta to the primary transcript despite containment.
 			scroll.scrollBy(event.wheelDelta ?? 0);
@@ -156,14 +196,30 @@ export function installSidebar(tui: TUI, theme: ShellBarTheme): () => void {
 	};
 	const prepare = (width: number, root: LayoutRoot): boolean => {
 		state.active = false;
-		if (stopped || failed || host.mode !== "fullscreen" || width < SIDEBAR_BREAKPOINT) {
+		if (stopped || failed || host.mode !== "fullscreen") {
 			prepared = undefined;
+			headerLines = [];
 			return false;
 		}
+		const railEligible = width >= SIDEBAR_BREAKPOINT && placement() !== "bottom" && placement() !== "hidden";
+		if (!railEligible) {
+			prepared = undefined;
+			try {
+				const headerPart = state.parts.get("header");
+				headerLines = headerPlacement() === "top" && headerPart
+					? [...(headerPart.render(Math.max(0, width)) ?? [])] : [];
+				if (!headerLines.some((line) => line.trim() !== "")) headerLines = [];
+			} catch {
+				failed = true;
+				headerLines = [];
+			}
+			return false;
+		}
+		const style = cardStyle();
 		const parts = [...state.parts.entries()];
 		const digests = parts.map(([, rail]) => railDigest(rail));
 		const unchanged = prepared?.revision === cache.revision &&
-			prepared.width === width && prepared.mode === host.mode && prepared.root === root && prepared.theme === theme &&
+			prepared.width === width && prepared.mode === host.mode && prepared.headerPlacement === headerPlacement() && prepared.cardStyle === style && prepared.root === root && prepared.theme === theme &&
 			prepared.parts.length === parts.length && prepared.parts.every(([key, part], index) => parts[index]?.[0] === key && parts[index]?.[1] === part) &&
 			prepared.digests.length === digests.length && prepared.digests.every((digest, index) => digest === digests[index]);
 		if (unchanged) {
@@ -179,7 +235,7 @@ export function installSidebar(tui: TUI, theme: ShellBarTheme): () => void {
 			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 sections = ["footer", "agents", "todo"].filter((key) => key !== "todo" || state.visibility?.todo !== false).map((key) => {
 				const component = state.parts.get(key);
 				if (!component) {
 					sectionCache.delete(key);
@@ -204,23 +260,23 @@ export function installSidebar(tui: TUI, theme: ShellBarTheme): () => void {
 			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.
+			} else if (sections.length && headerActive && density() === "comfortable" && style === CARD_STYLE.NEON) {
+				// Preserve neon's header gap. Float's painted top padding starts
+				// on the same body row as the transcript, without an external gap.
 				railLines.push("");
 			}
 			for (const section of sections) {
 				// 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("");
+				// previous section; neon's header gap above is not a section.
+				if ((hits.length > 0 || branding.length > 0) && density() === "comfortable") 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);
-			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 };
+			headerLines = headerActive && headerPlacement() === "top" ? preparedHeaderLines : [];
+			prepared = { revision: cache.revision, width, mode: host.mode, headerPlacement: headerPlacement(), cardStyle: style, root, theme, parts, digests, contentWidth, active, lines: railLines, hits, headerLines, headerActive: headerLines.length > 0 };
 			state.active = active;
 			return active;
 		} catch {
@@ -264,6 +320,11 @@ export function installSidebar(tui: TUI, theme: ShellBarTheme): () => void {
 				}
 				return { ...node, entries: entries.map((entry, index) => index === entries.length - 1 ? { ...entry, component: wrapped! } : entry) };
 			};
+			// Without a rail the native layout stays in place; a hidden Status, or a
+			// narrow top header owning it, only frees the footer's reserved dock row,
+			// exactly as the rail does.
+			const nativeLayout = () => placement() === "hidden" || headerOwnsStatus() ? reclaimFooterRow(original.call(root)) : original.call(root);
+			const nativeHost = { render: () => [], invalidate() {}, [NODE]: nativeLayout };
 			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
@@ -278,10 +339,17 @@ export function installSidebar(tui: TUI, theme: ShellBarTheme): () => void {
 				] }),
 			};
 			const replacement = () => {
-				if (!prepare(tui.terminal.columns, root)) return original.call(root);
+				if (!prepare(tui.terminal.columns, root)) {
+					if (failed || stopped || host.mode !== "fullscreen") return original.call(root);
+					if (!headerLines.length) return nativeLayout();
+					return { type: "vstack", gap: 0, align: "stretch", entries: [
+						{ component: header, basis: "auto", grow: 0, shrink: 0, minSize: 1 },
+						{ component: nativeHost, basis: 0, grow: 1, shrink: 1, minSize: 1 },
+					] };
+				}
 				const current = prepared!;
 				if (current.presentation?.scrollTop === scroll.scrollTop) return current.presentation.output;
-				const output: LayoutNode = current.headerActive
+				const output: LayoutNode = current.headerActive && headerPlacement() !== "below-input"
 					? { type: "vstack", gap: 0, align: "stretch", entries: [
 						{ component: header, basis: "auto", grow: 0, shrink: 0, minSize: 1 },
 						{ component: hstackHost, basis: 0, grow: 1, shrink: 1, minSize: 1 },
@@ -311,7 +379,7 @@ export function installSidebar(tui: TUI, theme: ShellBarTheme): () => void {
 		stopped = true;
 		state.active = false;
 		clearInterval(timer);
-		scroll.hideTransientScrollbar();
+		scroll.setScrollbar("hidden");
 		for (const cleanup of cleanups.reverse()) cleanup();
 		tui.requestRender();
 	};

package/lib/shell-sidebar.ts

@@ -3,9 +3,23 @@ import type { Component, TUI } from "@earendil-works/pi-tui";
 // Store on the terminal, not a module singleton: extension loaders may isolate
 // modules, while Pi keeps this terminal across regular/fullscreen transitions.
 const STATE = Symbol.for("gentle-pi.experimental-sidebar.state");
+/** In-process notification after a visual preference is persisted. */
+export const VISUAL_SETTINGS_CHANGED = "gentle-pi.visual-settings-changed";
 export interface SidebarState {
 	active: boolean;
+	visibility?: { todo?: boolean };
 	ownsHost?: () => boolean;
+	/**
+	 * Columns the fullscreen rail reserves at the right edge (rail plus gap)
+	 * while `active && ownsHost()`. Overlays read it to stay inside the editor
+	 * column (the prompt-history picker's right margin) without importing
+	 * gentle-shell.
+	 */
+	railColumns?: number;
+	/** True while Status placement is "hidden": the bottom Status bar paints nothing at any width or mode. */
+	statusHidden?: () => boolean;
+	/** True while a painting top header is the only status row of a narrow fullscreen terminal: the bottom Status bar steps aside. */
+	headerOwnsStatus?: () => boolean;
 	parts: Map<string, SidebarRail>;
 }
 
@@ -32,7 +46,7 @@ export function sidebarPart<T extends Component & { dispose?(): void }>(tui: TUI
 	state.parts.set(key, rail);
 	return {
 		...bottom,
-		render: (width: number) => state.active && state.ownsHost?.() ? [] : bottom.render(width),
+		render: (width: number) => (key === "todo" && state.visibility?.todo === false) || (key === "footer" && (state.statusHidden?.() || state.headerOwnsStatus?.())) || (state.active && state.ownsHost?.()) ? [] : bottom.render(width),
 		dispose() {
 			if (state.parts.get(key) === rail) state.parts.delete(key);
 			bottom.dispose?.();