pi-crew 0.11.0 → 0.11.1

package/src/ui/keybinding-map.ts

@@ -18,6 +18,12 @@
  * for zero benefit. The input-guard half of L2 is therefore intentionally
  * skipped; only the DRY/data-driven dispatch refactor landed.
  *
+ * M2-1 (P1-9) adds the sibling `overlay:*` keyspace below. The migrated
+ * overlays dispatch through `overlayActionForKey("<name>", data)` — the same
+ * data-driven + override pipeline as the dashboard, but a SEPARATE namespace:
+ * an overlay never consults `dashboardActionForKey`, so the no-leak argument
+ * above is unchanged.
+ *
  * Origin pattern: deer-flow `frontend/src/components/workspace/command-palette.tsx:39-50`
  * drives shortcuts from a single data array consumed by one loop in
  * `use-global-shortcuts.ts:38-61`.
@@ -44,7 +50,6 @@ export const DASHBOARD_KEYS = {
 		transcript: ["v"],
 		liveConversation: ["V"],
 		reload: ["r"],
-		progressToggle: ["p"],
 		browser: ["b"],
 	},
 	pane: {
@@ -106,7 +111,6 @@ export type DashboardKeyAction =
 	| "transcript"
 	| "live-conversation"
 	| "reload"
-	| "progressToggle"
 	| "browser"
 	| "pane-agents"
 	| "pane-progress"
@@ -152,11 +156,13 @@ export type DashboardKeyAction =
  *
  * NOTE: mailbox action keys A/N/C/P/X (ack/nudge/compose/preview/ackAll) are
  * intentionally NOT dispatched for the mailbox pane by this table. They live
- * in `DASHBOARD_KEYS.mailbox` for reservation but are handled by the mailbox
- * overlay's own `handleInput`, not by the dashboard dispatch. The `plan`
- * group reuses uppercase "A" (approve) pane-scoped to "progress" — it never
- * fires while the mailbox pane (or the mailbox-detail overlay) owns input,
- * so `mailbox.ack` behavior is unchanged.
+ * in `DASHBOARD_KEYS.mailbox` for reservation and are resolved by the mailbox
+ * overlays' own input handling — since M2-1 through the sibling `overlay:*`
+ * keyspace (`OVERLAY_KEYS["mailbox-detail"]` / `OVERLAY_KEYS["mailbox-compose"]`),
+ * never by `dashboardActionForKey`. The `plan` group reuses uppercase "A"
+ * (approve) pane-scoped to "progress" — it never fires while the mailbox pane
+ * (or the mailbox-detail overlay) owns input, so `mailbox.ack` behavior is
+ * unchanged.
  */
 const DEFAULT_BINDINGS: readonly KeyBinding[] = [
 	{ keys: DASHBOARD_KEYS.close, action: "close" },
@@ -245,7 +251,6 @@ const DEFAULT_BINDINGS: readonly KeyBinding[] = [
 	{ keys: DASHBOARD_KEYS.root.transcript, action: "transcript" },
 	{ keys: DASHBOARD_KEYS.root.liveConversation, action: "live-conversation" },
 	{ keys: DASHBOARD_KEYS.root.reload, action: "reload" },
-	{ keys: DASHBOARD_KEYS.root.progressToggle, action: "progressToggle" },
 	// Agents & Jobs browser (one-keypress overlay, mirrors live-conversation).
 	// Collision analysis: "b" is unbound everywhere else — root-unscoped is
 	// safe; inside the browser overlay itself "p" is free because overlays
@@ -289,6 +294,103 @@ const KEY_RESERVED = new Set<string>([
 
 export { KEY_RESERVED };
 
+// ─── Overlay keybindings (P1-9 / M2-1) ─────────────────────────────────────
+//
+// Overlays used to hardcode their own key chains — the SAME
+// "↑/↓/Enter/Esc" concept re-implemented in every overlay file, none of them
+// remappable. M2-1 centralises them into an `overlay:<name>:<action>`
+// keyspace that rides the SAME override pipeline as the dashboard table
+// above: `.crew/config.json` → `keybindings` and `PI_CREW_KEYBINDINGS` both
+// accept `"overlay:<name>:<action>": ["<key>", …]`, a colliding override is
+// reverted to its default, and the revert is reported by
+// `getKeybindingOverrideWarnings()`.
+//
+// Overlay bindings are validated INDEPENDENTLY of dashboard bindings: the two
+// namespaces are never live at the same time (the host hands input to exactly
+// one component — an open overlay or the dashboard), so a shared key such as
+// `q`/`escape`/`A` is not a real ambiguity. Within one overlay a shared key IS
+// ambiguous and is treated as a collision.
+
+export const OVERLAY_KEYS = {
+	"agent-picker": {
+		close: ["escape", "q"],
+		up: ["k", "up"],
+		down: ["j", "down"],
+		select: ["return"],
+	},
+	confirm: {
+		confirm: ["y", "Y"],
+		/** Enter is dual-role: the overlay resolves it with `defaultAction`. */
+		submit: ["return"],
+		cancel: ["n", "N", "escape", "q"],
+	},
+	"mailbox-detail": {
+		close: ["escape", "q"],
+		toggleSide: ["tab", "\t"],
+		up: ["k", "up"],
+		down: ["j", "down"],
+		toggleDetail: ["return"],
+		ack: ["A"],
+		nudge: ["N"],
+		compose: ["C"],
+		ackAll: ["X"],
+	},
+	"mailbox-compose": {
+		cancel: ["escape"],
+		preview: ["P"],
+		nextField: ["tab", "\t"],
+		space: [" "],
+		backspace: ["backspace"],
+		submit: ["return"],
+	},
+} as const;
+
+type OverlayDefs = typeof OVERLAY_KEYS;
+
+/** Overlay namespaces that opt into the central keybinding map. */
+export type OverlayName = keyof OverlayDefs;
+
+/** Every action across every overlay (union). */
+export type OverlayAction = { [N in OverlayName]: keyof OverlayDefs[N] & string }[OverlayName];
+
+/** Actions of ONE overlay — the precise return type of `overlayActionForKey`. */
+export type OverlayActionOf<N extends OverlayName> = keyof OverlayDefs[N] & string;
+
+/** Override key as written in config/env: `overlay:<name>:<action>`. */
+export type OverlayBindingKey = { [N in OverlayName]: `overlay:${N & string}:${keyof OverlayDefs[N] & string}` }[OverlayName];
+
+/** A resolved overlay binding (one action of one overlay). */
+export interface OverlayBinding {
+	readonly overlay: OverlayName;
+	readonly action: OverlayAction;
+	readonly keys: readonly string[];
+}
+
+/** Compose the config/env override key for one overlay action. */
+function overlayBindingKey(overlay: OverlayName, action: OverlayAction): OverlayBindingKey {
+	return `overlay:${overlay}:${action}` as OverlayBindingKey;
+}
+
+// `Object.entries` widens the const-typed tables; this cast restores the exact
+// shape (no `any`; the `OverlayBinding` annotation below still checks it).
+type OverlayTableEntry = readonly [OverlayName, Readonly<Record<string, readonly string[]>>];
+
+const OVERLAY_TABLE = Object.entries(OVERLAY_KEYS) as readonly OverlayTableEntry[];
+
+/** Every valid `overlay:<name>:<action>` override key. */
+const OVERLAY_BINDING_KEYS: ReadonlySet<string> = new Set(
+	OVERLAY_TABLE.flatMap(([overlay, actions]) =>
+		Object.keys(actions).map((action) => overlayBindingKey(overlay, action as OverlayAction)),
+	),
+);
+
+const DEFAULT_OVERLAY_BINDINGS: ReadonlyMap<OverlayName, readonly OverlayBinding[]> = new Map<OverlayName, readonly OverlayBinding[]>(
+	OVERLAY_TABLE.map(([overlay, actions]) => [
+		overlay,
+		Object.entries(actions).map(([action, keys]): OverlayBinding => ({ overlay, action: action as OverlayAction, keys })),
+	]),
+);
+
 // ─── Keybinding overrides (UI-2) ───────────────────────────────────────────
 //
 // The hardcoded DEFAULT_BINDINGS above can be overridden per-action via two
@@ -309,13 +411,14 @@ export { KEY_RESERVED };
 // first-match-wins dispatch unambiguous — a shadowed override never silently
 // changes behaviour.
 
-/** Override map: action → replacement keys. `Partial` ⇒ only listed actions. */
-export type KeybindingOverride = Partial<Record<DashboardKeyAction, readonly string[]>>;
+/** Override map: action → replacement keys. `Partial` ⇒ only listed actions.
+ *  Keys are dashboard actions plus `overlay:<name>:<action>` binding keys. */
+export type KeybindingOverride = Partial<Record<DashboardKeyAction | OverlayBindingKey, readonly string[]>>;
 
 const KEYBINDINGS_ENV = "PI_CREW_KEYBINDINGS";
 
-/** Every dispatched action is a valid override target. */
-const VALID_OVERRIDE_ACTIONS: ReadonlySet<string> = new Set(DEFAULT_BINDINGS.map((b) => b.action));
+/** Every dispatched action + every `overlay:*` binding is a valid override target. */
+const VALID_OVERRIDE_ACTIONS: ReadonlySet<string> = new Set<string>([...DEFAULT_BINDINGS.map((b) => b.action), ...OVERLAY_BINDING_KEYS]);
 
 /** Coerce an unknown parsed value into a safe {@link KeybindingOverride}. */
 function parseKeybindingOverride(raw: unknown): KeybindingOverride {
@@ -355,42 +458,87 @@ function paneScopesCompatible(a: PaneScope | undefined, b: PaneScope | undefined
 
 interface EffectiveBindingsResult {
 	readonly bindings: readonly KeyBinding[];
-	/** Actions whose override was rejected due to a collision. */
-	readonly reverted: readonly DashboardKeyAction[];
+	/** Resolved bindings per overlay (defaults + non-colliding overrides). */
+	readonly overlayBindings: ReadonlyMap<OverlayName, readonly OverlayBinding[]>;
+	/** Override targets whose override was rejected due to a collision. */
+	readonly reverted: readonly string[];
 }
 
 /**
- * Apply `overrides` onto {@link DEFAULT_BINDINGS} (replace keys per action,
- * preserving each action's pane scope) and detect collisions. A colliding
- * override is reverted to its default so the dispatch stays unambiguous.
+ * Does `candidate` share a key with any `other` binding that could be live at
+ * the same time? Shared by the dashboard and the overlay namespaces so the
+ * collision rule (and its revert semantics) has ONE implementation.
+ */
+function collidesWithOthers<B extends { readonly keys: readonly string[]; readonly action: string }>(
+	candidate: B,
+	others: readonly B[],
+	compatible: (a: B, b: B) => boolean,
+): boolean {
+	for (const other of others) {
+		if (other.action === candidate.action) continue;
+		if (!compatible(candidate, other)) continue;
+		if (candidate.keys.some((k) => other.keys.includes(k))) return true;
+	}
+	return false;
+}
+
+/**
+ * Apply `overrides` onto {@link DEFAULT_BINDINGS} + {@link DEFAULT_OVERLAY_BINDINGS}
+ * (replace keys per target, preserving each binding's pane scope / overlay) and
+ * detect collisions. A colliding override is reverted to its default so the
+ * dispatch stays unambiguous. Dashboard and overlay namespaces are validated
+ * separately (they are never live simultaneously).
  */
 function computeEffectiveBindings(overrides: KeybindingOverride): EffectiveBindingsResult {
+	// ── dashboard namespace (semantics unchanged since UI-2) ──
 	const applied = new Map<DashboardKeyAction, KeyBinding>();
 	for (const def of DEFAULT_BINDINGS) {
 		const ov = overrides[def.action];
 		applied.set(def.action, ov && ov.length > 0 ? { keys: [...ov], action: def.action, pane: def.pane } : def);
 	}
 	const effective = [...applied.values()];
-	const reverted = new Set<DashboardKeyAction>();
+	const reverted = new Set<string>();
 	for (const def of DEFAULT_BINDINGS) {
 		const ov = overrides[def.action];
 		if (!ov || ov.length === 0) continue; // not overridden
 		const ob = applied.get(def.action);
 		if (!ob) continue;
-		for (const other of effective) {
-			if (other.action === def.action) continue;
-			if (!paneScopesCompatible(ob.pane, other.pane)) continue;
-			if (ob.keys.some((k) => other.keys.includes(k))) {
-				reverted.add(def.action);
-				break;
-			}
-		}
+		if (collidesWithOthers(ob, effective, (a, b) => paneScopesCompatible(a.pane, b.pane))) reverted.add(def.action);
 	}
 	const bindings =
 		reverted.size > 0
 			? effective.map((b) => (reverted.has(b.action) ? (DEFAULT_BINDINGS.find((d) => d.action === b.action) ?? b) : b))
 			: effective;
-	return { bindings, reverted: [...reverted] };
+
+	// ── overlay namespace (M2-1) ──
+	const overlayBindings = new Map<OverlayName, readonly OverlayBinding[]>();
+	for (const [overlay, defaults] of DEFAULT_OVERLAY_BINDINGS) {
+		const perOverlay: OverlayBinding[] = defaults.map((def) => {
+			const ov = overrides[overlayBindingKey(overlay, def.action)];
+			return ov && ov.length > 0 ? { overlay, action: def.action, keys: [...ov] } : def;
+		});
+		for (const def of defaults) {
+			const key = overlayBindingKey(overlay, def.action);
+			const ov = overrides[key];
+			if (!ov || ov.length === 0) continue; // not overridden
+			const ob = perOverlay.find((b) => b.action === def.action);
+			if (!ob) continue;
+			// Same overlay ⇒ same input lineage ⇒ any shared key is ambiguous.
+			if (collidesWithOthers(ob, perOverlay, () => true)) reverted.add(key);
+		}
+		if (reverted.size === 0) {
+			overlayBindings.set(overlay, perOverlay);
+			continue;
+		}
+		overlayBindings.set(
+			overlay,
+			perOverlay.map((b) =>
+				reverted.has(overlayBindingKey(overlay, b.action)) ? (defaults.find((d) => d.action === b.action) ?? b) : b,
+			),
+		);
+	}
+
+	return { bindings, overlayBindings, reverted: [...reverted] };
 }
 
 /** Read the `keybindings` section from `<cwd>/.crew/config.json`. */
@@ -428,15 +576,17 @@ interface EffectiveCache {
 	readonly configMtime: number | undefined;
 	readonly cwd: string;
 	readonly bindings: readonly KeyBinding[];
+	readonly overlayBindings: ReadonlyMap<OverlayName, readonly OverlayBinding[]>;
 }
 
 let _effectiveCache: EffectiveCache | null = null;
 let _overrideWarnings: readonly string[] = [];
 
 /**
- * Resolve the effective dispatch table: {@link DEFAULT_BINDINGS} with config +
- * env overrides applied (env wins per action). Memoised on (env value, config
- * mtime, cwd); a single `statSync` per call detects on-disk config changes.
+ * Resolve the effective dispatch tables: {@link DEFAULT_BINDINGS} and
+ * {@link DEFAULT_OVERLAY_BINDINGS} with config + env overrides applied (env
+ * wins per target). Memoised on (env value, config mtime, cwd); a single
+ * `statSync` per call detects on-disk config changes.
  */
 function getEffectiveBindings(cwd: string = process.cwd()): readonly KeyBinding[] {
 	const envRaw = getCrewEnv(KEYBINDINGS_ENV);
@@ -445,12 +595,18 @@ function getEffectiveBindings(cwd: string = process.cwd()): readonly KeyBinding[
 		return _effectiveCache.bindings;
 	}
 	const merged: KeybindingOverride = { ...readConfigKeybindings(cwd), ...readEnvKeybindings() };
-	const { bindings, reverted } = computeEffectiveBindings(merged);
+	const { bindings, overlayBindings, reverted } = computeEffectiveBindings(merged);
 	_overrideWarnings = reverted.map((a) => `keybinding override for '${a}' collides with another binding — reverting to default`);
-	_effectiveCache = { env: envRaw, configMtime, cwd, bindings };
+	_effectiveCache = { env: envRaw, configMtime, cwd, bindings, overlayBindings };
 	return bindings;
 }
 
+/** Resolved overlay bindings for one overlay (defaults + non-colliding overrides). */
+function getEffectiveOverlayBindings(overlay: OverlayName): readonly OverlayBinding[] {
+	getEffectiveBindings(); // ensures the memo is warm + warnings are populated
+	return _effectiveCache?.overlayBindings.get(overlay) ?? DEFAULT_OVERLAY_BINDINGS.get(overlay) ?? [];
+}
+
 /** Warnings from the most recent override resolution (e.g. collisions). */
 export function getKeybindingOverrideWarnings(): readonly string[] {
 	// Ensure a resolution has run so warnings are populated.
@@ -514,3 +670,45 @@ export function dashboardActionForKey(data: string, activePane?: ActivePane): Da
 	}
 	return undefined;
 }
+
+/**
+ * Resolve a raw input `data` string to an OVERLAY action (M2-1 / P1-9).
+ *
+ * Mirror image of {@link dashboardActionForKey} over the overlay keyspace:
+ * same two-pass dispatch (case-sensitive exact match first, then the
+ * terminal-aware `matchesKey` normalization), same override pipeline
+ * (`.crew/config.json` → `keybindings["overlay:<name>:<action>"]`, then the
+ * `PI_CREW_KEYBINDINGS` env var, collision → revert to default).
+ *
+ * With no override configured the result is identical to the key chains the
+ * overlays used to hardcode (asserted by
+ * `test/unit/ui/overlay-keybindings.test.ts`).
+ *
+ * @param overlay Overlay namespace, e.g. `"confirm"`.
+ * @param data Raw key input (single char or escape sequence).
+ */
+export function overlayActionForKey<N extends OverlayName>(overlay: N, data: string): OverlayActionOf<N> | undefined {
+	const bindings = getEffectiveOverlayBindings(overlay);
+	// Pass 1 — exact, case-sensitive match (keeps "y"/"Y" and "A"/"a" distinct).
+	for (const binding of bindings) {
+		if (binding.keys.includes(data)) return binding.action as OverlayActionOf<N>;
+	}
+	// Pass 2 — escape-sequence / canonical KeyId normalisation.
+	//
+	// Single-character candidates are deliberately EXCLUDED here: pi-tui's
+	// `matchesKey()` is case-INSENSITIVE for plain ASCII
+	// (`matchesKey("a", "A") === true`), which would collapse the deliberate
+	// case distinctions this keyspace relies on ("A"=ack vs lowercase "a"=free
+	// text in mailbox-compose; "y"/"Y" in confirm). Pass 1 already matched
+	// single chars exactly and case-sensitively, mirroring the pre-M2-1 chains
+	// (`data === "A"`, `data === "P"`, …).
+	const key = keyOf(data);
+	for (const binding of bindings) {
+		for (const candidate of binding.keys) {
+			if (candidate.length === 1) continue;
+			if (key === candidate) return binding.action as OverlayActionOf<N>;
+			if (matchesKey(data, candidate as KeyId)) return binding.action as OverlayActionOf<N>;
+		}
+	}
+	return undefined;
+}

package/src/ui/live-conversation-overlay.ts

@@ -3,16 +3,47 @@
  *
  * R8: Subscribes to session events for real-time streaming updates.
  * Falls back to polling LiveAgentHandle.activity when subscribe is unavailable.
+ *
+ * Frame (RAIL design language, M4/E1 2026-09-16):
+ *
+ *   ┏ LIVE ▸ explorer
+ *   ┃ ◉ building feature · turn 2/10 · 3 tools · 5.1s · ▕██░░░░░░▏ 24% ctx · sonnet
+ *   ┃ <streamed transcript rows…>
+ *   ┗ ↑/↓/PgUp/PgDn/G scroll · A pause · Esc/Q close ···· auto-scroll
+ *
+ * The rounded box (`╭─╮│╰─╯` + its two `│ ──── │` rules) is retired: the canopy
+ * opens the surface, every body row is a `┃` rail line, the `┗` close cap
+ * carries the hint (`formatHint`, close LAST) on the left and the scroll STATE
+ * (`auto-scroll` / `manual 12-30/31`) on the dot-led right segment, so the state
+ * is never the part that gets truncated. Chrome therefore drops from 6 rows to 3
+ * (canopy + meta + cap) and the viewport gains the three freed rows — keys,
+ * scroll rules and clamping are unchanged.
+ *
+ * Keyboard (P1-3: the overlay captures focus while open — see
+ * `handleInput` below for the full key set):
+ *   esc / q                            close, back to the main conversation
+ *   pgup / pgdn / ↑ ↓ / j k / g G      scroll the transcript
+ *   a                                  toggle auto-scroll
  */
+import { matchesKey } from "@earendil-works/pi-tui";
 import type { LiveAgentHandle } from "../runtime/live-session/live-agent-manager.ts";
-import { pad, truncate } from "../utils/visual.ts";
+import { truncate } from "../utils/visual.ts";
+import { formatCount } from "./format-helpers.ts";
 import { computeLiveDurationMs } from "./live-duration.ts";
+import { canopyLine, formatHint, gaugeBar, RAIL, railLeaders, railLine, statusSlot } from "./rail.ts";
 import { spinnerFrame } from "./spinner.ts";
 import { iconForStatus } from "./status-colors.ts";
-import type { CrewTheme } from "./theme-adapter.ts";
+import type { CrewTheme, CrewThemeColor } from "./theme-adapter.ts";
 
-const CHROME_LINES = 6;
+/** Chrome rows: canopy + meta row + close cap. Every other row is transcript. */
+const CHROME_LINES = 3;
 const MIN_VIEWPORT = 3;
+/** Lines moved by one ↑/k or ↓/j press. */
+const SCROLL_LINE_STEP = 1;
+/** Lines moved by one PgUp/PgDn press (same page size as the agent view overlay). */
+const SCROLL_PAGE_STEP = 10;
+/** Bar width of the `% ctx` gauge in the meta row. */
+const CTX_GAUGE_WIDTH = 8;
 
 export class LiveConversationOverlay {
 	private scrollOffset = 0;
@@ -46,7 +77,7 @@ export class LiveConversationOverlay {
 					const text = typeof obj.text === "string" ? obj.text : typeof obj.content === "string" ? obj.content : "";
 					if (text.trim()) {
 						this.pushLine(text);
-						if (this.autoScroll) this.scrollOffset = Math.max(0, this.cachedLines.length - this.viewportHeight());
+						if (this.autoScroll) this.scrollOffset = this.maxScrollOffset();
 					}
 				});
 			} catch {
@@ -86,83 +117,182 @@ export class LiveConversationOverlay {
 
 	private refreshSummary(): void {
 		const act = this.handle.activity;
-		const summary = `${LiveConversationOverlay.SUMMARY_PREFIX}[${act.turnCount} turns · ${act.toolUses} tools · ${(computeLiveDurationMs(act) / 1000).toFixed(1)}s]`;
+		const summary = `${LiveConversationOverlay.SUMMARY_PREFIX}[${formatCount(act.turnCount ?? 0, "turn")} · ${formatCount(act.toolUses ?? 0, "tool")} · ${(computeLiveDurationMs(act) / 1000).toFixed(1)}s]`;
 		const lastLine = this.cachedLines[this.cachedLines.length - 1];
 		if (lastLine?.startsWith(LiveConversationOverlay.SUMMARY_PREFIX)) {
 			this.cachedLines[this.cachedLines.length - 1] = summary;
 		} else {
 			this.pushLine(summary);
 		}
-		if (this.autoScroll) this.scrollOffset = Math.max(0, this.cachedLines.length - this.viewportHeight());
+		if (this.autoScroll) this.scrollOffset = this.maxScrollOffset();
 	}
 
 	private viewportHeight(): number {
 		return Math.max(MIN_VIEWPORT, this.rows - CHROME_LINES);
 	}
 
+	/** Largest offset that still shows the newest line in the viewport. */
+	private maxScrollOffset(): number {
+		return Math.max(0, this.cachedLines.length - this.viewportHeight());
+	}
+
+	/**
+	 * autoScroll rule (M1-6):
+	 *   - a manual scroll always recomputes autoScroll from the position — the
+	 *     viewport tails the stream only while it sits at the newest line;
+	 *   - scrolling DOWN to (or past) the newest line therefore restores
+	 *     autoScroll, and scrolling UP away from it pauses it so incoming lines
+	 *     cannot yank the viewport back;
+	 *   - `a` toggles explicitly: turning it on jumps to the newest line,
+	 *     turning it off pauses wherever the viewport currently is.
+	 */
+	private scrollBy(delta: number): void {
+		this.scrollOffset = Math.max(0, Math.min(this.maxScrollOffset(), this.scrollOffset + delta));
+		this.autoScroll = this.scrollOffset >= this.maxScrollOffset();
+	}
+
+	/** Jump to the oldest buffered line. */
+	private scrollHome(): void {
+		this.scrollBy(-this.cachedLines.length);
+	}
+
+	/** Jump to the newest line (re-enables auto-scroll). */
+	private scrollEnd(): void {
+		this.scrollBy(this.cachedLines.length);
+	}
+
+	/** Toggle auto-scroll; turning it on jumps to the newest line. */
+	private toggleAutoScroll(): void {
+		if (this.autoScroll) this.autoScroll = false;
+		else this.scrollEnd();
+	}
+
+	/**
+	 * Handle a keypress while the overlay has focus. Mirrors the key set of
+	 * src/ui/inline-panel/agent-view-overlay.ts:160-182:
+	 *
+	 *   esc / q            close the overlay
+	 *   ↓ / j              scroll down one line
+	 *   ↑ / k              scroll up one line
+	 *   PgDn / PgUp        scroll one page
+	 *   g (home)           jump to the oldest buffered line
+	 *   G (end)            jump to the newest line (re-enables auto-scroll)
+	 *   a                  toggle auto-scroll
+	 *
+	 * The host component in src/extension/registration/viewers.ts intercepts
+	 * esc/q itself (it owns the `done()` callback) and forwards every other key
+	 * here; the esc/q branch below keeps this class self-contained for direct
+	 * callers and for the host contract. Unrecognised keys are ignored — the
+	 * overlay never leaks keys into the editor underneath.
+	 */
+	handleInput(data: string): void {
+		if (this.closed) return;
+		if (matchesKey(data, "escape") || data === "q") {
+			this.close();
+			return;
+		}
+		if (matchesKey(data, "down") || data === "j") {
+			this.scrollBy(SCROLL_LINE_STEP);
+			return;
+		}
+		if (matchesKey(data, "up") || data === "k") {
+			this.scrollBy(-SCROLL_LINE_STEP);
+			return;
+		}
+		if (matchesKey(data, "pageDown")) {
+			this.scrollBy(SCROLL_PAGE_STEP);
+			return;
+		}
+		if (matchesKey(data, "pageUp")) {
+			this.scrollBy(-SCROLL_PAGE_STEP);
+			return;
+		}
+		if (matchesKey(data, "home") || data === "g") {
+			this.scrollHome();
+			return;
+		}
+		if (matchesKey(data, "end") || data === "G") {
+			this.scrollEnd();
+			return;
+		}
+		if (data === "a") {
+			this.toggleAutoScroll();
+		}
+	}
+
+	/** Left half of the close cap: the key legend, through `formatHint`. */
+	private hintText(): string {
+		return formatHint([
+			[["up", "down", "pageup", "pagedown", "g", "G"], "scroll"],
+			["a", this.autoScroll ? "pause" : "resume"],
+			[["escape", "q"], "close"],
+		]);
+	}
+
+	/**
+	 * Right half of the close cap: the scroll STATE (dot-led so it can never be
+	 * the segment that gets truncated). Every key advertised is handled by
+	 * `handleInput` in BOTH states (P1-3: the old `↑/k ↓/j G/g` hint lived in an
+	 * autoScroll === false branch that could never be reached, because nothing
+	 * ever turned autoScroll off).
+	 */
+	private stateText(): string {
+		if (this.autoScroll) return "auto-scroll";
+		const total = this.cachedLines.length;
+		const from = total === 0 ? 0 : this.scrollOffset + 1;
+		const to = Math.min(total, this.scrollOffset + this.viewportHeight());
+		return `manual ${from}-${to}/${total}`;
+	}
+
 	render(width?: number): string[] {
 		const w = width ?? this.columns;
 		if (w < 6) return [];
 		const th = this.theme;
-		const innerW = w - 4;
-		const row = (content: string) => th.fg("border", "│") + " " + pad(truncate(content, innerW), innerW) + " " + th.fg("border", "│");
-		const hrTop = th.fg("border", `╭${"─".repeat(w - 2)}╮`);
-		const hrBot = th.fg("border", `╰${"─".repeat(w - 2)}╯`);
-		const hrMid = row(th.fg("dim", "─".repeat(innerW)));
+		const budget = w - 2;
+		const act = this.handle.activity;
+		const slot = statusSlot(this.handle.status);
 
 		const lines: string[] = [];
-		lines.push(hrTop);
+		// Canopy: ┏ LIVE ▸ <agent> (every identity field guarded — the handle is
+		// assembled at runtime and a missing name must never print `undefined`).
+		lines.push(canopyLine({ word: "LIVE", subject: this.handle.agent ?? this.handle.taskId ?? "?", theme: th, budget }));
 
-		// Header
+		// Meta row: status glyph, description, then the counters.
 		const statusIcon =
 			this.handle.status === "running"
-				? th.fg("accent", spinnerFrame(this.handle.taskId ?? this.handle.agentId))
+				? th.fg("accent", spinnerFrame(this.handle.taskId ?? this.handle.agentId ?? ""))
 				: iconForStatus(this.handle.status);
-		const name = this.handle.agent ?? this.handle.taskId;
-		const act = this.handle.activity;
-		const elapsed = `${(computeLiveDurationMs(act) / 1000).toFixed(1)}s`;
-		const headerParts: string[] = [];
-		if (act.maxTurns != null) headerParts.push(`turn ${act.turnCount}/${act.maxTurns}`);
-		else if (act.turnCount > 0) headerParts.push(`turn ${act.turnCount}`);
-		if (act.toolUses > 0) headerParts.push(`${act.toolUses} tools`);
-		headerParts.push(elapsed);
-
-		// Context % + compaction
+		const desc = this.handle.description ?? this.handle.role ?? "";
+		const parts: string[] = [];
+		if (act.maxTurns != null) parts.push(`turn ${act.turnCount ?? 0}/${act.maxTurns}`);
+		else if ((act.turnCount ?? 0) > 0) parts.push(`turn ${act.turnCount}`);
+		if ((act.toolUses ?? 0) > 0) parts.push(formatCount(act.toolUses ?? 0, "tool"));
+		parts.push(`${(computeLiveDurationMs(act) / 1000).toFixed(1)}s`);
 		try {
 			const ctxPct = this.handle.session.getSessionStats?.()?.contextUsage?.percent;
 			if (ctxPct != null) {
-				const color = ctxPct >= 85 ? "error" : ctxPct >= 70 ? "warning" : "dim";
-				headerParts.push(th.fg(color, `${Math.round(ctxPct)}% ctx`));
+				const color: CrewThemeColor = ctxPct >= 85 ? "error" : ctxPct >= 70 ? "warning" : "dim";
+				parts.push(th.fg(color, `${gaugeBar(ctxPct / 100, CTX_GAUGE_WIDTH, th, color)} ${Math.round(ctxPct)}% ctx`));
 			}
 		} catch {
 			/* ignore */
 		}
-		if (act.compactionCount > 0) headerParts.push(th.fg("dim", `↻${act.compactionCount}`));
-		// Model name
-		if (this.handle.modelName) headerParts.push(th.fg("muted", this.handle.modelName));
+		if ((act.compactionCount ?? 0) > 0) parts.push(th.fg("dim", `↻${act.compactionCount}`));
+		if (this.handle.modelName) parts.push(th.fg("muted", this.handle.modelName));
+		const describe = desc ? `${th.fg("muted", desc)} ${th.fg("dim", "·")} ` : "";
+		lines.push(railLine(RAIL.body, slot, truncate(`${statusIcon} ${describe}${th.fg("dim", parts.join(" · "))}`, budget), th, budget));
 
-		const desc = this.handle.description ?? this.handle.role ?? "";
-		lines.push(
-			row(
-				`${statusIcon} ${th.fg("accent", name)}  ${th.fg("muted", desc)} ${th.fg("dim", "·")} ${th.fg("dim", headerParts.join(" · "))}`,
-			),
-		);
-		lines.push(hrMid);
-
-		// Content
+		// Transcript body.
 		const vh = this.viewportHeight();
 		const visible = this.cachedLines.slice(this.scrollOffset, this.scrollOffset + vh);
 		for (const line of visible) {
-			lines.push(row(th.fg("dim", line)));
+			lines.push(railLine(RAIL.body, "border", th.fg("dim", truncate(line, budget)), th, budget));
 		}
 
-		// Footer
-		lines.push(hrMid);
-		const footerText = this.autoScroll
-			? "auto-scroll · esc/q close"
-			: `line ${this.scrollOffset + 1}/${this.cachedLines.length} · ↑/k ↓/j G/g · esc/q close`;
-		lines.push(row(th.fg("dim", footerText)));
-		lines.push(hrBot);
+		// Close cap: hint (left) ···· scroll state (right).
+		lines.push(
+			railLine(RAIL.close, slot, railLeaders(th.fg("dim", this.hintText()), th.fg("dim", this.stateText()), budget, th), th, budget),
+		);
 		return lines;
 	}