pi-crew 0.11.0 → 0.11.2

package/src/ui/mascot.ts

@@ -1,6 +1,5 @@
 import { matchesKey } from "@earendil-works/pi-tui";
-import { pad } from "../utils/visual.ts";
-import { DynamicCrewBorder } from "./dynamic-border.ts";
+import { canopyLine, formatHint, RAIL, railLeaders, railLine } from "./rail.ts";
 import type { CrewTheme } from "./theme-adapter.ts";
 import { asCrewTheme } from "./theme-adapter.ts";
 
@@ -356,10 +355,8 @@ export class AnimatedMascot {
 		this.onDone();
 	}
 
-	private formatLine(line: string, width: number, color: Parameters<CrewTheme["fg"]>[0] = "accent"): string {
-		const contentWidth = Math.max(0, width - 4);
-		const themed = this.theme.fg(color, line);
-		return `│ ${pad(themed, contentWidth)} │`;
+	private formatLine(line: string, budget: number, color: Parameters<CrewTheme["fg"]>[0] = "accent"): string {
+		return railLine(RAIL.body, "border", this.theme.fg(color, line), this.theme, budget);
 	}
 
 	private currentCatFrame(): readonly string[] {
@@ -397,25 +394,44 @@ export class AnimatedMascot {
 			return this.cachedLines;
 		}
 		const safeWidth = Math.max(20, width);
-		const horizontal = new DynamicCrewBorder(this.theme).render(Math.max(0, safeWidth - 2))[0];
+		// M4/RAIL (2026-09-16): the rounded box + DynamicCrewBorder were retired;
+		// this surface paints the same rail frame as every other pi-crew surface.
+		const budget = Math.max(4, safeWidth - 2);
 		const result: string[] = [
-			`${this.theme.fg("border", "╭")}${horizontal}${this.theme.fg("border", "╮")}`,
-			this.formatLine(this.theme.bold(" ARMIN SAYS HI "), safeWidth),
-			this.formatLine("", safeWidth),
+			canopyLine({ word: "MASCOT", subject: this.style, theme: this.theme, budget }),
+			this.formatLine(this.theme.bold("ARMIN SAYS HI"), budget),
+			this.formatLine("", budget),
 		];
 		if (this.style === "armin") {
 			for (const row of this.currentArminGrid) {
 				const text = row.join("");
-				result.push(this.formatLine(text, safeWidth));
+				result.push(this.formatLine(text, budget));
 			}
 		} else {
 			const frameLines = this.applyCatEffect(this.currentCatFrame());
-			for (const line of frameLines) result.push(this.formatLine(line, safeWidth));
+			for (const line of frameLines) result.push(this.formatLine(line, budget));
 		}
-		const hint =
-			this.style === "armin" ? `Press q or Esc to close · effect: ${this.effect}` : "Press q or Esc to close · animated preview";
-		result.push(this.formatLine(hint, safeWidth, "muted"));
-		result.push(`${this.theme.fg("border", "╰")}${horizontal}${this.theme.fg("border", "╯")}`);
+		const state = this.style === "armin" ? `effect: ${this.effect}` : "animated preview";
+		result.push(
+			railLine(
+				RAIL.close,
+				"border",
+				railLeaders(
+					this.theme.fg(
+						"dim",
+						formatHint([
+							["esc", "close"],
+							["q", "close"],
+						]),
+					),
+					this.theme.fg("dim", state),
+					budget,
+					this.theme,
+				),
+				this.theme,
+				budget,
+			),
+		);
 		this.cachedWidth = safeWidth;
 		this.cachedVersion = this.gridVersion;
 		this.cachedFrame = this.frame;

package/src/ui/overlays/agent-picker-overlay.ts

@@ -1,8 +1,30 @@
+/**
+ * Agent picker overlay — RAIL design language (M4/E1, 2026-09-16).
+ *
+ *   ┏ AGENTS ▸ <runId8>
+ *   ┃ › explorer · running · executor ▸ worker
+ *   ┗ ↑/↓ move · Enter select · Esc cancel
+ *
+ * Grammar: `canopyLine` opens the surface, every body row is a `┃` line built
+ * by `railLine` (which owns the width budget), the close cap carries the hint
+ * built by `formatHint` (close LAST, keys through `keyToken`). The rounded
+ * `╭─╮│╰─╯` frame and the hand-typed "↑/↓ move · Enter select · ESC cancel"
+ * string are retired.
+ *
+ * Keys/behaviour are unchanged: same `overlay:*` keyspace dispatch, same
+ * selection and clamping.
+ *
+ * File-sourced risk (audit §4): `agents.json` is NOT schema-validated at read
+ * time, so every interpolated record field is guarded (`?? "?"`) before it can
+ * reach a line — a missing field must never print as `undefined`.
+ */
+
 import { readCrewAgents } from "../../runtime/crew-agent-records.ts";
 import type { CrewAgentRecord } from "../../runtime/crew-agent-runtime.ts";
 import { loadRunManifestById } from "../../state/stores/state-store.ts";
-import { pad, truncate } from "../../utils/visual.ts";
-import { keyOf, matchesKey } from "../key-utils.ts";
+import { truncate } from "../../utils/visual.ts";
+import { overlayActionForKey } from "../keybinding-map.ts";
+import { ACTIVE, CURSOR, canopyLine, formatHint, RAIL, railLine, shortId } from "../rail.ts";
 import { asCrewTheme, type CrewTheme } from "../theme-adapter.ts";
 
 export interface AgentPickerSelection {
@@ -13,6 +35,7 @@ export class AgentPickerOverlay {
 	private readonly agents: CrewAgentRecord[];
 	private readonly done: (selection: AgentPickerSelection | undefined) => void;
 	private readonly theme: CrewTheme;
+	private readonly runId: string;
 	private selected = 0;
 
 	constructor(opts: {
@@ -25,6 +48,7 @@ export class AgentPickerOverlay {
 		this.agents = loaded ? readCrewAgents(loaded.manifest) : [];
 		this.done = opts.done;
 		this.theme = asCrewTheme(opts.theme ?? {});
+		this.runId = opts.runId;
 	}
 
 	invalidate(): void {
@@ -32,35 +56,66 @@ export class AgentPickerOverlay {
 	}
 
 	render(width: number): string[] {
-		const inner = Math.max(24, width - 4);
-		const lines = [
-			this.theme.bold("Select agent"),
-			"↑/↓ move · Enter select · ESC cancel",
-			...this.agents.map(
-				(agent, index) =>
-					`${index === this.selected ? "›" : " "} ${agent.taskId} · ${agent.status} · ${agent.role}->${agent.agent}`,
+		if (width < 6) return [];
+		const theme = this.theme;
+		const budget = width - 2;
+		const lines: string[] = [
+			canopyLine({ word: "AGENTS", subject: shortId(this.runId), theme, budget }),
+			...this.agents.map((agent, index) =>
+				railLine(
+					RAIL.body,
+					"border",
+					truncate(
+						`${index === this.selected ? CURSOR : " "} ${agent.taskId ?? "?"} · ${agent.status ?? "?"} · ${
+							agent.role ?? "?"
+						} ${ACTIVE} ${agent.agent ?? "?"}`,
+						budget,
+					),
+					theme,
+					budget,
+				),
 			),
 		];
-		if (!this.agents.length) lines.push("No agents found.");
-		return lines.map((line) => pad(truncate(line, inner), inner));
+		if (!this.agents.length) {
+			lines.push(railLine(RAIL.body, "border", theme.fg("dim", "No agents found."), theme, budget));
+		}
+		lines.push(
+			railLine(
+				RAIL.close,
+				"border",
+				theme.fg(
+					"dim",
+					formatHint([
+						[["up", "down"], "move"],
+						["enter", "select"],
+						["escape", "cancel"],
+					]),
+				),
+				theme,
+				budget,
+			),
+		);
+		return lines;
 	}
 
 	handleInput(data: string): void {
-		if (matchesKey(data, "escape") || data === "q") {
-			this.done(undefined);
-			return;
-		}
-		if (data === "k" || keyOf(data) === "up") {
-			this.selected = Math.max(0, this.selected - 1);
-			return;
-		}
-		if (data === "j" || keyOf(data) === "down") {
-			this.selected = Math.min(Math.max(0, this.agents.length - 1), this.selected + 1);
-			return;
-		}
-		if (matchesKey(data, "return")) {
-			const agent = this.agents[this.selected];
-			this.done(agent ? { agentId: agent.taskId } : undefined);
+		// M2-1: keys come from the central `overlay:*` keyspace (remappable via
+		// `.crew/config.json` → keybindings["overlay:agent-picker:<action>"]).
+		switch (overlayActionForKey("agent-picker", data)) {
+			case "close":
+				this.done(undefined);
+				return;
+			case "up":
+				this.selected = Math.max(0, this.selected - 1);
+				return;
+			case "down":
+				this.selected = Math.min(Math.max(0, this.agents.length - 1), this.selected + 1);
+				return;
+			case "select": {
+				const agent = this.agents[this.selected];
+				this.done(agent ? { agentId: agent.taskId } : undefined);
+				return;
+			}
 		}
 	}
 }

package/src/ui/overlays/confirm-overlay.ts

@@ -1,6 +1,23 @@
-import { pad, truncate } from "../../utils/visual.ts";
-import { matchesKey } from "../key-utils.ts";
-import { Box, Text } from "../layout-primitives.ts";
+/**
+ * Confirm dialog overlay — RAIL design language (M4/E1, 2026-09-16).
+ *
+ *   ┏ CONFIRM ▸ Delete?
+ *   ┃ Danger
+ *   ┗ Y confirm · N/Esc cancel
+ *
+ * The rounded `╭─╮├─┤│╰─╯` box (and its inline `├───┤` rules) is retired; the
+ * surface is now canopy / `┃` body / `┗` close cap. The rail colour carries the
+ * danger level (high → error, medium → warning, else neutral border) instead of
+ * colouring only the title, and the hint is built by `formatHint` (cancel LAST,
+ * keys through `keyToken` → `Esc`, never `ESC`).
+ *
+ * Keys/behaviour are unchanged: same `overlay:*` keyspace dispatch, Enter stays
+ * dual-role exactly as before.
+ */
+
+import { truncate } from "../../utils/visual.ts";
+import { overlayActionForKey } from "../keybinding-map.ts";
+import { canopyLine, formatHint, RAIL, type RailSlot, railLine } from "../rail.ts";
 import { asCrewTheme, type CrewTheme } from "../theme-adapter.ts";
 
 export interface ConfirmOptions {
@@ -26,36 +43,45 @@ export class ConfirmOverlay {
 	}
 
 	render(width: number): string[] {
-		const innerWidth = Math.max(24, Math.min(width - 4, 72));
-		const color = this.opts.dangerLevel === "high" ? "error" : this.opts.dangerLevel === "medium" ? "warning" : "accent";
-		const title = this.theme.bold(this.theme.fg(color, this.opts.title));
-		const hint = this.opts.defaultAction === "confirm" ? "Enter/Y confirm · N/ESC cancel" : "Y confirm · Enter/N/ESC cancel";
+		if (width < 6) return [];
+		const theme = this.theme;
+		const budget = width - 2;
+		// Rail colour = state (§1): the danger level is the state of a confirm.
+		const slot: RailSlot = this.opts.dangerLevel === "high" ? "error" : this.opts.dangerLevel === "medium" ? "warning" : "border";
+		const hint =
+			this.opts.defaultAction === "confirm"
+				? formatHint([
+						[["enter", "y"], "confirm"],
+						[["n", "escape"], "cancel"],
+					])
+				: formatHint([
+						["y", "confirm"],
+						[["enter", "n", "escape"], "cancel"],
+					]);
 		const bodyLines = (this.opts.body ?? "").split(/\r?\n/).filter(Boolean);
-		const lines = [
-			`╭${"─".repeat(innerWidth)}╮`,
-			`│ ${pad(truncate(title, innerWidth - 1), innerWidth - 1)}│`,
-			`├${"─".repeat(innerWidth)}┤`,
-			...(bodyLines.length ? bodyLines : ["Are you sure?"]).map(
-				(line) => `│ ${pad(truncate(line, innerWidth - 1), innerWidth - 1)}│`,
-			),
-			`├${"─".repeat(innerWidth)}┤`,
-			`│ ${pad(truncate(this.theme.fg("dim", hint), innerWidth - 1), innerWidth - 1)}│`,
-			`╰${"─".repeat(innerWidth)}╯`,
-		];
-		const box = new Box(0, 0);
-		for (const line of lines) box.addChild(new Text(line));
-		return box.render(width);
+		const lines: string[] = [canopyLine({ word: "CONFIRM", subject: this.opts.title ?? "?", theme, budget, slot })];
+		for (const line of bodyLines.length ? bodyLines : ["Are you sure?"]) {
+			lines.push(railLine(RAIL.body, slot, truncate(line, budget), theme, budget));
+		}
+		lines.push(railLine(RAIL.close, slot, theme.fg("dim", hint), theme, budget));
+		return lines;
 	}
 
 	handleInput(data: string): void {
-		if (data === "y" || data === "Y") {
-			this.done(true);
-			return;
-		}
-		if (matchesKey(data, "return") && this.opts.defaultAction === "confirm") {
-			this.done(true);
-			return;
+		// M2-1: keys come from the central `overlay:*` keyspace (remappable via
+		// `.crew/config.json` → keybindings["overlay:confirm:<action>"]).
+		switch (overlayActionForKey("confirm", data)) {
+			case "confirm":
+				this.done(true);
+				return;
+			// Enter is dual-role: it confirms when the overlay defaults to confirm
+			// and cancels otherwise (byte-identical to the pre-M2-1 chain).
+			case "submit":
+				this.done(this.opts.defaultAction === "confirm");
+				return;
+			case "cancel":
+				this.done(false);
+				return;
 		}
-		if (data === "n" || data === "N" || matchesKey(data, "escape") || data === "q" || matchesKey(data, "return")) this.done(false);
 	}
 }

package/src/ui/overlays/help-overlay.ts

@@ -1,52 +1,51 @@
 /**
- * K-1 — dashboard keybinding cheatsheet overlay.
+ * K-1 — dashboard keybinding cheatsheet overlay (RAIL design language, M4/E1).
  *
  * Toggled by `?` (bound in keybinding-map.ts). Renders the dashboard's
- * keybindings grouped by scope (general / navigation / panes / run actions /
- * mailbox / health) directly from `DASHBOARD_KEYS`, so adding a key in one
- * place is reflected here automatically.
+ * keybindings grouped by scope (general / navigation / panes / schedules /
+ * plan / run actions / mailbox / health) directly from `DASHBOARD_KEYS`, so
+ * adding a key in one place is reflected here automatically.
  *
- * Uses the same `innerWidth = max(20, width - 4)` formula as `run-dashboard.ts`
- * so the overlay's border column aligns with the dashboard's stable-height
- * blank-padding rows (preserves the "stable overlay height" strength — the
- * blank rows injected by the dashboard's pad/trim must land in the same
- * column as this overlay's `│` borders).
+ * Grammar (docs/UI-DESIGN-SYSTEM.md §2.E):
  *
- * Template origin: `confirm-overlay.ts`.
+ *   ┏ HELP ▸ dashboard
+ *   ┣ GENERAL
+ *   ┃ Q/Esc   close dashboard    Enter/S/Tab/Space   open run status
+ *   ┗ ? toggle · Esc dismiss
+ *
+ * The legacy rounded box (`╭─╮│╰─╯├─┤`) is retired: the overlay is a canopy +
+ * `┣ SECTION` group headers + `┃` rows. Each group title is a RAIL section
+ * (replacing the old accent-only row), and the always-visible column key/token
+ * pair now goes through the SHARED `keyToken()` from `src/ui/rail.ts`.
+ *
+ * Why that mattered: the old file-local `keyToken` had no `case "\t"` branch, so
+ * `DASHBOARD_KEYS.select`'s raw tab byte was rendered verbatim into the table
+ * and knocked the row's alignment out by one column (audit §4). The shared
+ * tokenizer maps it to `Tab` (and `Esc`/`↑/↓`/`PgUp`/`Space` consistently).
+ *
+ * Width contract: `render(width)` — every line is built through `railLine`,
+ * which owns the `glyph + space` separator and never emits a line wider than
+ * the render width. Nothing is baked at build time.
  */
 
-import { pad, truncate } from "../../utils/visual.ts";
+import { pad, truncate, visibleWidth } from "../../utils/visual.ts";
 import { DASHBOARD_KEYS } from "../keybinding-map.ts";
-import { Box, Text } from "../layout-primitives.ts";
+import { canopyLine, formatHint, keyToken, RAIL, railLine, sectionLine } from "../rail.ts";
 import { asCrewTheme, type CrewTheme } from "../theme-adapter.ts";
 
-/** Translate a raw key sequence into a readable token for the cheatsheet. */
-function keyToken(key: string): string {
-	switch (key) {
-		case "\u001b":
-			return "Esc";
-		case "\u001b[A":
-			return "↑";
-		case "\u001b[B":
-			return "↓";
-		case "\r":
-		case "\n":
-			return "Enter";
-		default:
-			return key;
-	}
-}
-
+/** Translate a raw key sequence into a readable token for the cheatsheet.
+ *  Delegates to the SHARED `keyToken` (rail.ts) so the cheatsheet, the footer
+ *  hints and the tool cards can never drift apart. */
 function keyList(keys: readonly string[]): string {
-	return [...keys].map(keyToken).join("/");
+	return [...new Set(keys.map((key) => keyToken(key)))].join("/");
 }
 
-interface HelpEntry {
+export interface HelpEntry {
 	readonly keys: string;
 	readonly label: string;
 }
 
-interface HelpGroup {
+export interface HelpGroup {
 	readonly title: string;
 	readonly entries: readonly HelpEntry[];
 }
@@ -62,7 +61,24 @@ const ROOT_LABELS: Record<string, string> = {
 	transcript: "transcript",
 	liveConversation: "live conv",
 	reload: "reload",
-	progressToggle: "progress",
+	// NOTE: `progressToggle` deliberately has no label here — the `p` binding
+	// had no visible effect (P1-5, phantom key) and is being removed from
+	// keybinding-map.ts. Entries derive from Object.entries(DASHBOARD_KEYS.root),
+	// so the row disappears entirely once that key is gone.
+};
+
+const SCHEDULES_LABELS: Record<string, string> = {
+	toggle: "toggle",
+	runNow: "run now",
+	details: "details",
+	delete: "delete",
+	refresh: "refresh",
+};
+
+const PLAN_LABELS: Record<string, string> = {
+	approve: "approve",
+	deny: "deny",
+	diff: "diff",
 };
 
 const MAILBOX_LABELS: Record<string, string> = {
@@ -88,6 +104,16 @@ function buildHelpGroups(): HelpGroup[] {
 		keys: keyList(keys),
 		label: ROOT_LABELS[name] ?? name,
 	}));
+	// P1-14: pane 8 (schedules) and pane 7 (plan) have pane-scoped action keys
+	// that were missing from this cheatsheet entirely.
+	const scheduleEntries: HelpEntry[] = Object.entries(DASHBOARD_KEYS.schedules).map(([name, keys]) => ({
+		keys: keyList(keys),
+		label: SCHEDULES_LABELS[name] ?? name,
+	}));
+	const planEntries: HelpEntry[] = Object.entries(DASHBOARD_KEYS.plan).map(([name, keys]) => ({
+		keys: keyList(keys),
+		label: PLAN_LABELS[name] ?? name,
+	}));
 	const mailboxEntries: HelpEntry[] = Object.entries(DASHBOARD_KEYS.mailbox)
 		.filter(([name]) => name !== "openDetail")
 		.map(([name, keys]) => ({
@@ -117,12 +143,18 @@ function buildHelpGroups(): HelpGroup[] {
 			title: "Navigation",
 			entries: [
 				{
-					keys: `${keyList(DASHBOARD_KEYS.navigation.up)}/${keyList(DASHBOARD_KEYS.navigation.down)}`,
+					// Union of the up/down aliases, deduped through the shared
+					// `keyToken` (`k`/`up` and `j`/`down` collapse to one `↑/↓`).
+					keys: [
+						...new Set([...DASHBOARD_KEYS.navigation.up, ...DASHBOARD_KEYS.navigation.down].map((key) => keyToken(key))),
+					].join("/"),
 					label: "move selection",
 				},
 			],
 		},
 		{ title: "Panes", entries: paneEntries },
+		{ title: "Schedules (pane 8)", entries: scheduleEntries },
+		{ title: "Plan (pane 7)", entries: planEntries },
 		{ title: "Run actions", entries: rootEntries },
 		{ title: "Mailbox (pane 3)", entries: mailboxEntries },
 		{
@@ -138,6 +170,21 @@ function buildHelpGroups(): HelpGroup[] {
 	];
 }
 
+/** Test seam (mirrors `__test__openPane` / `__resetInlinePanelForTest`): the
+ *  generated groups, so tests can assert keys/labels without parsing the
+ *  rendered surface. The overlay itself renders through `buildHelpGroups()`. */
+export function __test__buildHelpGroups(): HelpGroup[] {
+	return buildHelpGroups();
+}
+
+/** Width of the key column: the widest rendered token list, capped at 20 so a
+ *  future key set cannot push the labels off the row. Derived from the data —
+ *  never a hand-tuned constant that silently misaligns when a key is added. */
+function keyColumnWidth(groups: readonly HelpGroup[]): number {
+	const widths = groups.flatMap((group) => group.entries.map((entry) => visibleWidth(entry.keys)));
+	return Math.min(20, Math.max(1, ...widths));
+}
+
 export class HelpOverlay {
 	private readonly theme: CrewTheme;
 
@@ -150,28 +197,36 @@ export class HelpOverlay {
 	}
 
 	render(width: number): string[] {
-		// MUST mirror run-dashboard.ts's innerWidth so the dashboard's
-		// stable-height blank-padding rows align with this overlay's borders.
-		const innerWidth = Math.max(20, width - 4);
-		const fg = (color: Parameters<CrewTheme["fg"]>[0], text: string) => this.theme.fg(color, text);
-		const row = (text: string) => `│ ${pad(truncate(text, innerWidth - 1), innerWidth - 1)}│`;
-		const bar = "─".repeat(innerWidth);
-		const top = fg("border", `╭${bar}╮`);
-		const mid = fg("border", `├${bar}┤`);
-		const bot = fg("border", `╰${bar}╯`);
-		const keyCol = 9;
-		const lines: string[] = [top, row(`${fg("accent", "pi-crew dashboard")} ${fg("dim", "— key reference (press ? to close)")}`), mid];
-		for (const group of buildHelpGroups()) {
-			lines.push(row(fg("accent", group.title)));
+		if (width < 6) return [];
+		const theme = this.theme;
+		const budget = width - 2;
+		const groups = buildHelpGroups();
+		const keyCol = keyColumnWidth(groups);
+		const lines: string[] = [canopyLine({ word: "HELP", subject: "dashboard", theme, budget })];
+		for (const group of groups) {
+			lines.push(sectionLine({ name: group.title, theme, budget }));
 			for (let i = 0; i < group.entries.length; i += 2) {
 				const pair = group.entries.slice(i, i + 2);
-				const cell = (entry: HelpEntry) => `${this.theme.bold(pad(entry.keys, keyCol))}${fg("dim", truncate(entry.label, 16))}`;
-				lines.push(row(pair.map(cell).join("   ")));
+				const cell = (entry: HelpEntry) =>
+					`${theme.bold(pad(truncate(entry.keys, keyCol), keyCol))} ${theme.fg("dim", truncate(entry.label, 16))}`;
+				lines.push(railLine(RAIL.body, "border", truncate(pair.map(cell).join("   "), budget), theme, budget));
 			}
 		}
-		lines.push(bot);
-		const box = new Box(0, 0);
-		for (const line of lines) box.addChild(new Text(line));
-		return box.render(width);
+		lines.push(
+			railLine(
+				RAIL.close,
+				"border",
+				theme.fg(
+					"dim",
+					formatHint([
+						["?", "toggle"],
+						["escape", "dismiss"],
+					]),
+				),
+				theme,
+				budget,
+			),
+		);
+		return lines;
 	}
 }