gentle-pi 2.4.0 → 2.6.0

package/lib/shell-changes.ts

@@ -0,0 +1,290 @@
+import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+
+// Gentle Shell changes: the working tree against HEAD, new files included.
+// Git is the source of truth; this module turns raw `git diff --numstat` and
+// `git status --porcelain -z` output into a model and renders the widget.
+
+export const CHANGE_STATUS = {
+	MODIFIED: "modified",
+	ADDED: "added",
+	DELETED: "deleted",
+	RENAMED: "renamed",
+	UNTRACKED: "untracked",
+} as const;
+
+export type ChangeStatus = (typeof CHANGE_STATUS)[keyof typeof CHANGE_STATUS];
+
+export interface ChangedFile {
+	path: string;
+	added: number;
+	deleted: number;
+	status: ChangeStatus;
+}
+
+export interface ChangesModel {
+	files: ChangedFile[];
+	added: number;
+	deleted: number;
+}
+
+export interface ChangesSnapshot {
+	numstat: string;
+	porcelain: string;
+}
+
+export interface ChangesTheme {
+	fg(color: string, text: string): string;
+}
+
+interface NumstatEntry {
+	path: string;
+	added: number;
+	deleted: number;
+}
+
+export const CHANGES_COMMAND = "/gentle:changes";
+const WIDGET_GLYPH = "✎";
+const STATUS_BY_CODE: Record<string, ChangeStatus> = {
+	A: CHANGE_STATUS.ADDED,
+	D: CHANGE_STATUS.DELETED,
+	R: CHANGE_STATUS.RENAMED,
+	C: CHANGE_STATUS.ADDED,
+	"?": CHANGE_STATUS.UNTRACKED,
+};
+const RENAME_BRACES = /\{([^{}]*) => ([^{}]*)\}/g;
+const HAS_RENAME_BRACES = /\{[^{}]* => [^{}]*\}/;
+const RENAME_ARROW = " => ";
+
+export function emptyChanges(): ChangesModel {
+	return { files: [], added: 0, deleted: 0 };
+}
+
+function renamedPath(path: string): string {
+	if (HAS_RENAME_BRACES.test(path)) return path.replace(RENAME_BRACES, "$2").replace(/\/\//g, "/");
+	const arrow = path.indexOf(RENAME_ARROW);
+	return arrow === -1 ? path : path.slice(arrow + RENAME_ARROW.length);
+}
+
+function count(value: string): number {
+	const parsed = Number.parseInt(value, 10);
+	return Number.isFinite(parsed) ? parsed : 0;
+}
+
+export function parseNumstat(text: string): NumstatEntry[] {
+	const entries: NumstatEntry[] = [];
+	for (const line of text.split("\n")) {
+		const [added, deleted, ...rest] = line.split("\t");
+		if (added === undefined || deleted === undefined || rest.length === 0) continue;
+		entries.push({ path: renamedPath(rest.join("\t")), added: count(added), deleted: count(deleted) });
+	}
+	return entries;
+}
+
+export function parsePorcelain(text: string): Map<string, ChangeStatus> {
+	const statuses = new Map<string, ChangeStatus>();
+	const records = text.split("\0").filter((record) => record.length > 0);
+	for (let index = 0; index < records.length; index += 1) {
+		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);
+		if (code[0] === "R" || code[0] === "C") index += 1;
+	}
+	return statuses;
+}
+
+export function snapshotChanges(snapshot: ChangesSnapshot): ChangedFile[] {
+	const counts = new Map(parseNumstat(snapshot.numstat).map((entry) => [entry.path, entry]));
+	const files: ChangedFile[] = [];
+	for (const [path, status] of parsePorcelain(snapshot.porcelain)) {
+		const entry = counts.get(path);
+		files.push({ path, added: entry?.added ?? 0, deleted: entry?.deleted ?? 0, status });
+	}
+	return files;
+}
+
+export function changesModel(changed: ChangedFile[]): ChangesModel {
+	const files = [...changed].sort((a, b) => a.path.localeCompare(b.path));
+	return {
+		files,
+		added: files.reduce((total, file) => total + file.added, 0),
+		deleted: files.reduce((total, file) => total + file.deleted, 0),
+	};
+}
+
+export function changesSummary(model: ChangesModel): string {
+	const noun = model.files.length === 1 ? "file" : "files";
+	return `${model.files.length} ${noun} · +${model.added} −${model.deleted}`;
+}
+
+// One line: summary, the files joined by dots, and the command pushed to
+// the right edge. The file list goes first when the terminal is narrow.
+export function renderChangesWidget(model: ChangesModel, theme: ChangesTheme, width: number): string[] {
+	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}`)}`;
+	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}`;
+	const gap = width - visibleWidth(left) - visibleWidth(hint);
+	if (gap >= 2) return [`${left}${" ".repeat(gap)}${hint}`];
+	const headGap = width - visibleWidth(head) - visibleWidth(hint);
+	if (headGap >= 2) return [`${head}${" ".repeat(headGap)}${hint}`];
+	return [truncateToWidth(head, width, "…")];
+}
+
+export interface GitResult {
+	stdout: string;
+	code: number;
+}
+
+export type GitRunner = (args: string[]) => Promise<GitResult>;
+export type LineCounter = (path: string) => Promise<number>;
+
+export interface WorktreeChanges {
+	root: string;
+	branch?: string;
+	model: ChangesModel;
+}
+
+// -z avoids Git's quoting of paths containing whitespace or newlines.
+export function parseWorktrees(text: string): Array<{ root: string; branch?: string }> {
+	return text.split("\0\0").flatMap((record) => {
+		const fields = record.split("\0");
+		const root = fields.find((field) => field.startsWith("worktree "))?.slice(9);
+		if (!root || fields.some((field) => field === "bare" || field.startsWith("prunable"))) return [];
+		const branch = fields.find((field) => field.startsWith("branch "))?.slice(7).replace(/^refs\/heads\//, "");
+		return [branch ? { root, branch } : { root }];
+	});
+}
+
+export class WorktreeChangesTracker {
+	worktrees: WorktreeChanges[] = [];
+	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[];
+
+	constructor(discover: GitRunner, gitForRoot: (root: string) => GitRunner, linesForRoot: (root: string) => LineCounter = () => noLines, registeredRoots: () => readonly string[] = () => []) {
+		this.discover = discover;
+		this.gitForRoot = gitForRoot;
+		this.linesForRoot = linesForRoot;
+		this.registeredRoots = registeredRoots;
+	}
+
+	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}`,
+		}))));
+	}
+
+	async start(): Promise<void> {
+		await this.refresh();
+	}
+
+	async refresh(): Promise<ChangesModel> {
+		// A scan can take longer than the polling interval in a large clone.
+		// Share it rather than extending it indefinitely with queued polls.
+		if (this.inFlight) return this.inFlight;
+		this.inFlight = this.capture();
+		try {
+			return await this.inFlight;
+		} finally {
+			this.inFlight = undefined;
+		}
+	}
+
+	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) {
+			const tree = metadata.get(root) ?? { root };
+			try {
+				const tracker = new ChangesTracker(this.gitForRoot(tree.root), this.linesForRoot(tree.root));
+				await tracker.start();
+				if (tracker.model.files.length) trees.push({ ...tree, model: tracker.model });
+			} catch {
+				// Linked roots can disappear between discovery and status.
+			}
+		}
+		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;
+		return this.model;
+	}
+}
+
+const noLines: LineCounter = async () => 0;
+
+const NUMSTAT_ARGS = ["diff", "--numstat", "HEAD"];
+const PORCELAIN_ARGS = ["status", "--porcelain=v1", "--untracked-files=all", "-z"];
+
+// Tracks working-tree changes. Concurrent refreshes coalesce: one git
+// round-trip runs at a time and a refresh requested meanwhile triggers
+// exactly one more.
+export class ChangesTracker {
+	private readonly git: GitRunner;
+	private readonly countLines: LineCounter;
+	private current: ChangesModel = emptyChanges();
+	private available = false;
+	private inFlight: Promise<ChangesModel> | undefined;
+	private queued = false;
+
+	constructor(git: GitRunner, countLines: LineCounter = noLines) {
+		this.git = git;
+		this.countLines = countLines;
+	}
+
+	get model(): ChangesModel {
+		return this.current;
+	}
+
+	async start(): Promise<void> {
+		const files = await this.capture();
+		this.available = files !== undefined;
+		this.current = files ? changesModel(files) : emptyChanges();
+	}
+
+	async refresh(): Promise<ChangesModel> {
+		if (!this.available) return this.current;
+		if (this.inFlight) {
+			this.queued = true;
+			return this.inFlight;
+		}
+		this.inFlight = this.runRefresh();
+		try {
+			return await this.inFlight;
+		} finally {
+			this.inFlight = undefined;
+		}
+	}
+
+	private async runRefresh(): Promise<ChangesModel> {
+		do {
+			this.queued = false;
+			const files = await this.capture();
+			if (files) this.current = changesModel(files);
+		} while (this.queued);
+		return this.current;
+	}
+
+	private async capture(): Promise<ChangedFile[] | undefined> {
+		const [numstat, porcelain] = await Promise.all([this.git(NUMSTAT_ARGS), this.git(PORCELAIN_ARGS)]);
+		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);
+		}
+		return files;
+	}
+}

package/lib/shell-gauge.ts

@@ -0,0 +1,40 @@
+// Shared gauge primitives for the Gentle Shell bar and panels.
+
+const GAUGE_TONE = {
+	ACCENT: "accent",
+	WARNING: "warning",
+	ERROR: "error",
+	DIM: "dim",
+} as const;
+
+export type GaugeTone = (typeof GAUGE_TONE)[keyof typeof GAUGE_TONE];
+
+export interface GaugeTheme {
+	fg(color: string, text: string): string;
+}
+
+export const GAUGE_CELLS = 8;
+const GAUGE_FILLED = "▰";
+const GAUGE_EMPTY = "▱";
+const GAUGE_EMPTY_ROLE = "border";
+const WARNING_THRESHOLD = 80;
+const ERROR_THRESHOLD = 95;
+
+export function renderGauge(percent: number | null, cells: number = GAUGE_CELLS): string {
+	const clamped = Math.max(0, Math.min(100, percent ?? 0));
+	const filled = Math.round((clamped / 100) * cells);
+	return GAUGE_FILLED.repeat(filled) + GAUGE_EMPTY.repeat(cells - filled);
+}
+
+export function gaugeTone(percent: number | null): GaugeTone {
+	if (percent === null) return GAUGE_TONE.DIM;
+	if (percent >= ERROR_THRESHOLD) return GAUGE_TONE.ERROR;
+	if (percent >= WARNING_THRESHOLD) return GAUGE_TONE.WARNING;
+	return GAUGE_TONE.ACCENT;
+}
+
+export function paintGauge(percent: number | null, theme: GaugeTheme, cells: number = GAUGE_CELLS): string {
+	const gauge = renderGauge(percent, cells);
+	const filled = gauge.replace(new RegExp(`${GAUGE_EMPTY}+$`), "");
+	return theme.fg(gaugeTone(percent), filled) + theme.fg(GAUGE_EMPTY_ROLE, gauge.slice(filled.length));
+}

package/lib/shell-prompt.ts

@@ -0,0 +1,115 @@
+import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+import { stripAnsi } from "./terminal-theme.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.
+
+export const PROMPT_STATE = {
+	IDLE: "idle",
+	WORKING: "working",
+	QUEUED: "queued",
+} as const;
+
+export type PromptState = (typeof PROMPT_STATE)[keyof typeof PROMPT_STATE];
+
+const PETAL_TONE = {
+	BRIGHT: "borderAccent",
+	ROSE: "accent",
+	SOFT: "thinkingHigh",
+	DEEP: "mdQuoteBorder",
+	WARNING: "warning",
+} as const;
+
+export type PetalTone = (typeof PETAL_TONE)[keyof typeof PETAL_TONE];
+
+// The Gentle themes map these to the rose ramp: active pink, rose, soft
+// rose, deep pink. The spin walks the ramp one shade per frame.
+const PETAL_TONE_FRAMES = [PETAL_TONE.BRIGHT, PETAL_TONE.ROSE, PETAL_TONE.SOFT, PETAL_TONE.DEEP] as const;
+
+export interface PromptFrameOptions {
+	state: PromptState;
+	tick: number;
+	borderColor: (text: string) => string;
+	fg: (color: string, text: string) => string;
+	bold?: (text: string) => string;
+}
+
+// A terminal cell cannot grow, so the petal earns presence with weight and
+// the brightest rose in the theme. Working spins through four flowers.
+export const PROMPT_PETAL = "✿";
+const PETAL_FRAMES = ["✿", "❀", "❁", "✾"] as const;
+export const PROMPT_HINT = "type, or / for commands";
+const LABEL_ROLE = "muted";
+const HINT_ROLE = "dim";
+const FAKE_CURSOR = "\x1b[7m \x1b[0m";
+const SCROLL_INDICATOR = /[↑↓] \d+ more/;
+const STATE_LABEL: Record<PromptState, string | undefined> = {
+	[PROMPT_STATE.IDLE]: undefined,
+	[PROMPT_STATE.WORKING]: "working",
+	[PROMPT_STATE.QUEUED]: "queued",
+};
+
+export function petalTone(state: PromptState, tick: number): PetalTone {
+	if (state === PROMPT_STATE.QUEUED) return PETAL_TONE.WARNING;
+	if (state === PROMPT_STATE.WORKING) return PETAL_TONE_FRAMES[tick % PETAL_TONE_FRAMES.length];
+	return PETAL_TONE.BRIGHT;
+}
+
+export function petalGlyph(state: PromptState, tick: number): string {
+	if (state === PROMPT_STATE.IDLE) return PROMPT_PETAL;
+	return PETAL_FRAMES[tick % PETAL_FRAMES.length];
+}
+
+function scrollIndicator(rule: string): string | undefined {
+	return stripAnsi(rule).match(SCROLL_INDICATOR)?.[0];
+}
+
+function rule(length: number): string {
+	return "─".repeat(Math.max(0, length));
+}
+
+function topRule(width: number, options: PromptFrameOptions, indicator: string | undefined): string {
+	const label = indicator ?? STATE_LABEL[options.state];
+	const glyph = petalGlyph(options.state, options.tick);
+	const petal = options.fg(petalTone(options.state, options.tick), options.bold ? options.bold(glyph) : glyph);
+	const labelText = label ? ` ${options.fg(LABEL_ROLE, label)}` : "";
+	const labelWidth = label ? label.length + 1 : 0;
+	const fill = width - 3 - visibleWidth(glyph) - labelWidth - 1 - 1;
+	if (fill < 0) return options.borderColor(`╭${rule(width - 2)}╮`);
+	return options.borderColor("╭─ ") + petal + labelText + options.borderColor(` ${rule(fill)}╮`);
+}
+
+function bottomRule(width: number, options: PromptFrameOptions, indicator: string | undefined): string {
+	if (!indicator) return options.borderColor(`╰${rule(width - 2)}╯`);
+	const fill = width - 3 - indicator.length - 1 - 1;
+	if (fill < 0) return options.borderColor(`╰${rule(width - 2)}╯`);
+	return options.borderColor("╰─ ") + options.fg(LABEL_ROLE, indicator) + options.borderColor(` ${rule(fill)}╯`);
+}
+
+function sideRules(line: string, innerWidth: number, options: PromptFrameOptions): string {
+	const clipped = innerWidth === 0 ? "" : truncateToWidth(line, innerWidth, "");
+	const padding = " ".repeat(Math.max(0, innerWidth - visibleWidth(clipped)));
+	const content = clipped + padding;
+	return options.borderColor("│") + content + options.borderColor("│");
+}
+
+export function framePromptLines(lines: string[], width: number, options: PromptFrameOptions): string[] {
+	width = Math.max(0, Math.floor(width));
+	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;
+	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))];
+}
+
+export function withPromptHint(line: string, hint: string, fg: PromptFrameOptions["fg"]): string {
+	const cursorAt = line.indexOf(FAKE_CURSOR);
+	if (cursorAt === -1) return line;
+	const afterCursor = cursorAt + FAKE_CURSOR.length;
+	const trailing = line.slice(afterCursor);
+	if (trailing.trim() !== "" || trailing.length < hint.length + 1) return line;
+	return `${line.slice(0, afterCursor)} ${fg(HINT_ROLE, hint)}${" ".repeat(trailing.length - hint.length - 1)}`;
+}

package/lib/shell-sidebar-banner.ts

@@ -0,0 +1,11 @@
+import { visibleWidth } from "@earendil-works/pi-tui";
+import type { ShellBarTheme } from "./shell-bar.ts";
+
+export function renderSidebarBanner(theme: ShellBarTheme, width: number): string[] {
+	const label = "✿ Gentle-Pi ✿";
+	const space = width - visibleWidth(label);
+	if (space < 0) return [];
+	// Gentleman's accent is pink; card titles use a separate champagne role.
+	const title = theme.fg("accent", "✿") + " " + theme.fg("text", "Gentle-Pi") + " " + theme.fg("accent", "✿");
+	return [" ".repeat(Math.floor(space / 2)) + title + " ".repeat(Math.ceil(space / 2))];
+}

package/lib/shell-sidebar-layout.ts

@@ -0,0 +1,213 @@
+import { ScrollView, 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";
+
+export const SIDEBAR_BREAKPOINT = 140;
+const RAIL_WIDTH = 50;
+const 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 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 SidebarPresentation = { scrollTop: number; output: LayoutNode };
+type PreparedRail = {
+	revision: number;
+	width: number;
+	mode: string | undefined;
+	root: LayoutRoot;
+	theme: ShellBarTheme;
+	parts: Array<[string, SidebarRail]>;
+	digests: Array<string | undefined>;
+	contentWidth: number;
+	active: boolean;
+	lines: string[];
+	hits: RailHit[];
+	presentation?: SidebarPresentation;
+};
+const CACHE = Symbol.for("gentle-pi.experimental-sidebar.cache");
+
+function sidebarCache(tui: TUI): SidebarCache {
+	const terminal = tui.terminal as unknown as Record<symbol, SidebarCache>;
+	return terminal[CACHE] ??= { revision: 0 };
+}
+
+/** Mark terminal-owned fullscreen sidebar output stale after a part state change. */
+export function invalidateSidebar(tui: TUI): void {
+	if (tui.terminal) sidebarCache(tui).revision++;
+}
+
+// The memo keys on part identity and an explicit revision, neither of which can
+// see live session state read inside a rail's render closure: a model switch, a
+// new context percentage or an extension status change leaves the prepared lines
+// intact. A rail that paints such state declares a digest of it, so the memo can
+// notice by itself; a throwing digest degrades that rail to invalidation-only
+// rather than taking the whole sidebar down with it.
+function railDigest(rail: SidebarRail): string | undefined {
+	try {
+		return rail.digest?.();
+	} catch {
+		return undefined;
+	}
+}
+
+export function installSidebar(tui: TUI, theme: ShellBarTheme): () => void {
+	if (!tui.terminal) return () => {};
+	const host = tui as Host;
+	const state = sidebarState(tui);
+	const cache = sidebarCache(tui);
+	const cleanups: Array<() => void> = [];
+	const roots = new Set<LayoutRoot>();
+	let stopped = false;
+	let failed = false;
+	let railLines: string[] = [];
+	let prepared: PreparedRail | undefined;
+	state.active = false;
+	state.ownsHost = () => !stopped && host.mode === "fullscreen" && !!host.layoutRoot && roots.has(host.layoutRoot);
+	const rail: Component = {
+		render: () => railLines,
+		invalidate() {
+			invalidateSidebar(tui);
+			for (const part of state.parts.values()) part.invalidate();
+		},
+	};
+	const scroll = new ScrollView(rail, {
+		follow: "none",
+		primary: false,
+		overscroll: "contain",
+		scrollbar: "always",
+		scrollbarTrackStyle: (text) => theme.fg("border", text),
+		scrollbarThumbStyle: (text) => theme.fg("accent", text),
+	});
+	const nativeMouse = scroll.handleMouse.bind(scroll);
+	const dispatchPartMouse = (event: TuiMouseEvent) => {
+		const current = prepared;
+		if (!current || stopped || failed || !current.active || current.revision !== cache.revision ||
+			host.mode !== "fullscreen" || tui.terminal.columns !== current.width || host.layoutRoot !== current.root ||
+			scroll.getContentWidth(event.width) !== current.contentWidth || event.x < RAIL_PADDING ||
+			event.x >= current.contentWidth || event.y < 0 || event.y >= event.height) return undefined;
+		const contentY = scroll.scrollTop + event.y;
+		const hit = current.hits.find((candidate) => contentY >= candidate.startY && contentY < candidate.startY + candidate.height);
+		if (!hit || state.parts.get(hit.key) !== hit.component || event.x >= RAIL_PADDING + hit.width) return undefined;
+		return hit.component.handleMouse?.({
+			...event,
+			x: event.x - RAIL_PADDING,
+			y: contentY - hit.startY,
+			width: hit.width,
+			height: hit.height,
+		});
+	};
+	scroll.handleMouse = (event) => {
+		if (event.type === "wheel") {
+			// 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);
+			return {
+				handled: true,
+				render: true,
+				target: { component: scroll, originX: event.screenX - event.x, originY: event.screenY - event.y, width: event.width, height: event.height },
+			};
+		}
+		return dispatchPartMouse(event) ?? nativeMouse(event);
+	};
+	const prepare = (width: number, root: LayoutRoot): boolean => {
+		state.active = false;
+		if (stopped || failed || host.mode !== "fullscreen" || width < SIDEBAR_BREAKPOINT) {
+			prepared = undefined;
+			return false;
+		}
+		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.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) {
+			railLines = prepared.lines;
+			state.active = prepared.active;
+			return prepared.active;
+		}
+		try {
+			const contentWidth = scroll.getContentWidth(RAIL_WIDTH);
+			const sections = ["footer", "changes", "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();
+				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);
+			const hits: RailHit[] = [];
+			railLines = [];
+			if (sections.length && branding.length) {
+				railLines.push(...branding.map((line) => " ".repeat(RAIL_PADDING) + line + " ".repeat(RAIL_PADDING)));
+			}
+			for (const section of sections) {
+				if (railLines.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 };
+			state.active = active;
+			return active;
+		} catch {
+			failed = true;
+			return false;
+		}
+	};
+	const attach = () => {
+		if (stopped || failed) return;
+		if (host.mode !== "fullscreen") { state.active = false; return; }
+		try {
+			const root = host.layoutRoot;
+			if (!root || typeof root[NODE] !== "function") { state.active = false; return; }
+			if (roots.has(root)) return;
+			const original = root[NODE]!;
+			const descriptor = Object.getOwnPropertyDescriptor(root, NODE);
+			const left = { render: (width: number) => root.render(width), invalidate() {}, [NODE]: () => original.call(root) };
+			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;
+			};
+			root[NODE] = replacement;
+			roots.add(root);
+			tui.requestRender();
+			cleanups.push(() => {
+				if (root[NODE] !== replacement) return;
+				if (descriptor) Object.defineProperty(root, NODE, descriptor);
+				else Reflect.deleteProperty(root, NODE);
+			});
+		} catch {
+			failed = true;
+			state.active = false;
+		}
+	};
+	attach();
+	// Pi replaces renderers without a session event. Rebind only that transition;
+	// resize and scroll remain owned by Pi's native layout/render loop.
+	const timer = setInterval(attach, 100);
+	timer.unref();
+	return () => {
+		stopped = true;
+		state.active = false;
+		clearInterval(timer);
+		scroll.hideTransientScrollbar();
+		for (const cleanup of cleanups.reverse()) cleanup();
+		tui.requestRender();
+	};
+}