pi-crew 0.11.0 → 0.11.1

package/src/ui/live-run-sidebar.ts

@@ -5,9 +5,12 @@ import { readCrewAgents } from "../runtime/crew-agent-records.ts";
 import { formatTaskGraphLines, waitingReason } from "../runtime/task-display.ts";
 import { loadRunManifestById } from "../state/stores/state-store.ts";
 import type { TeamTaskState } from "../state/types.ts";
-import { aggregateUsage, formatUsage } from "../state/usage.ts";
+import { aggregateUsage, formatTokens } from "../state/usage.ts";
 import { readJsonFileCoalesced } from "../utils/file-coalescer.ts";
-import { pad, truncate } from "../utils/visual.ts";
+import { truncate } from "../utils/visual.ts";
+import { formatCount, teamWorkflowLabel } from "./format-helpers.ts";
+import { DASHBOARD_KEYS } from "./keybinding-map.ts";
+import { ACTIVE, canopyLine, formatHint, RAIL, type RailSlot, railLine, sectionLine, shortId, statusSlot } from "./rail.ts";
 import type { OverlaySchedulerHandle } from "./shared-overlay-scheduler.ts";
 import { registerOverlayScheduler } from "./shared-overlay-scheduler.ts";
 import type { RunSnapshotCache, RunUiSnapshot } from "./snapshot-types.ts";
@@ -21,13 +24,11 @@ const TASK_READ_TTL_MS = 200;
 
 type Done = (value: undefined) => void;
 
-function line(text: string, width: number): string {
-	return `│ ${pad(truncate(text, width - 4), width - 4)} │`;
-}
-
-function border(left: string, fill: string, right: string, width: number): string {
-	return `${left}${fill.repeat(Math.max(0, width - 2))}${right}`;
-}
+/** The ONE footer hint of the sidebar: keys label pairs, close LAST (RAIL §1). */
+const SIDEBAR_HINT: ReadonlyArray<readonly [string, string]> = [
+	["/team-dashboard", "details"],
+	[DASHBOARD_KEYS.close[0] ?? "q", "close"],
+];
 
 function readTasks(path: string): TeamTaskState[] {
 	const parse = () => {
@@ -43,7 +44,25 @@ function readTasks(path: string): TeamTaskState[] {
 
 function shortUsage(tasks: TeamTaskState[]): string {
 	const usage = aggregateUsage(tasks);
-	return usage ? formatUsage(usage) : "usage=(none)";
+	return usage ? compactUsage(usage) : "usage=(none)";
+}
+
+/**
+ * TUI form of a usage record: `↑2.8k ↓3.7k $0.000`.
+ *
+ * `formatUsage` (state/usage.ts) is the `key=value` form used by CLI/status
+ * output (`input=2780, output=3715, cacheRead=57216, cost=0.000000, turns=0`) —
+ * correct for a log line, but on a 118-column rail row it buries the numbers
+ * the eye actually wants. The card's usage row has always used this compact
+ * form; the sidebar now matches it.
+ */
+function compactUsage(usage: ReturnType<typeof aggregateUsage>): string {
+	if (!usage) return "usage=(none)";
+	const parts: string[] = [];
+	if (usage.input !== undefined) parts.push(`↑${formatTokens(usage.input)}`);
+	if (usage.output !== undefined) parts.push(`↓${formatTokens(usage.output)}`);
+	if (usage.cost !== undefined && Number.isFinite(usage.cost) && usage.cost > 0) parts.push(`$${usage.cost.toFixed(3)}`);
+	return parts.length > 0 ? parts.join(" ") : "usage=(none)";
 }
 
 export class LiveRunSidebar {
@@ -147,13 +166,14 @@ export class LiveRunSidebar {
 
 	render(width: number): string[] {
 		const w = Math.max(36, width);
+		const budget = w - 2;
 
 		// P0-6: render from snapshots only — never read disk on every render tick.
 		// Production wires a snapshotCache (extension/registration/ui.ts). When
-		// the cache hasn't populated yet we paint a single "(loading…)" line so
-		// the pre-load frame is well-formed instead of an empty panel. When the
-		// cache is undefined (tests/dev) we fall back to direct disk reads so
-		// existing unit tests keep working.
+		// the cache hasn't populated yet we paint a well-formed two-row frame so
+		// the pre-load surface still wears the rail; when the cache is undefined
+		// (tests/dev) we fall back to direct disk reads so existing unit tests
+		// keep working.
 		let run: import("../state/types.ts").TeamRunManifest;
 		let tasks: TeamTaskState[];
 		let rawAgents: ReturnType<typeof readCrewAgents>;
@@ -165,7 +185,16 @@ export class LiveRunSidebar {
 				snapshot = undefined;
 			}
 			if (!snapshot) {
-				return ["(loading…)"];
+				// A well-formed pre-load frame: same canopy/cap grammar as the loaded
+				// one, with a single dim status row.
+				return this.renderFrame(
+					[
+						canopyLine({ word: "LIVE", subject: shortId(this.runId), theme: this.theme, budget }),
+						railLine(RAIL.body, "border", this.theme.fg("dim", "loading…"), this.theme, budget),
+					],
+					budget,
+					"border",
+				);
 			}
 			run = snapshot.manifest;
 			tasks = snapshot.tasks;
@@ -173,14 +202,13 @@ export class LiveRunSidebar {
 		} else {
 			const loaded = loadRunManifestById(this.cwd, this.runId); // NOTE: no withRunLock - best-effort only; concurrent writes may cause inconsistency;
 			if (!loaded) {
-				return renderLines(
+				return this.renderFrame(
 					[
-						border("╭", "─", "╮", w),
-						line(`${this.theme.fg("accent", "▐")} ${this.theme.bold("pi-crew live sidebar")}`, w),
-						line("run not found", w),
-						border("╰", "─", "╯", w),
+						canopyLine({ word: "LIVE", subject: shortId(this.runId), theme: this.theme, budget }),
+						railLine(RAIL.body, "border", this.theme.fg("muted", "run not found"), this.theme, budget),
 					],
-					w,
+					budget,
+					"border",
 				);
 			}
 			run = loaded.manifest;
@@ -194,6 +222,10 @@ export class LiveRunSidebar {
 		const waiting = tasks.filter((task) => task.status === "queued");
 		const signature = this.buildSignature(run.updatedAt, tasks, agents, waiting.length, snapshot);
 		if (signature !== this.cachedSignature || w !== this.cachedWidth) {
+			// RAIL (§2.E): the rounded `╭─╮│╰─╯` box is retired — the surface is a
+			// `┏ LIVE ▸ <run8>` canopy, `┃` body rows, `┣ SECTION` headers and a
+			// `┗ <hint>` cap. The rail colour carries the run's state.
+			const slot: RailSlot = statusSlot(run.status);
 			// L-2: surface the cancellation/failure reason for terminal runs so the
 			// user sees *why* a run ended without having to switch panes. The reason
 			// is already computed on the consumed snapshot (cancellationReason).
@@ -203,59 +235,98 @@ export class LiveRunSidebar {
 					? ` · ${truncate(snapshot.cancellationReason, 40)}`
 					: "";
 			const lines: string[] = [
-				border("╭", "─", "╮", w),
-				line(`${this.theme.fg("accent", "▐")} ${this.theme.bold("pi-crew live sidebar")}`, w),
-				line(`${run.runId.slice(-12)} · ${run.status}${reasonSuffix} · right default`, w),
-				line(`${run.team}/${run.workflow ?? "none"} · ${shortUsage(tasks)}`, w),
-				border("├", "─", "┤", w),
-				line(`Active agents (${active.length})`, w),
+				canopyLine({ word: "LIVE", subject: shortId(run.runId), theme: this.theme, budget, slot }),
+				railLine(
+					RAIL.body,
+					"border",
+					this.theme.fg(
+						"muted",
+						`${shortId(run.runId)} · ${run.status ?? "?"}${reasonSuffix} · ${run.workspaceMode ?? "single"}`,
+					),
+					this.theme,
+					budget,
+				),
+				railLine(
+					RAIL.body,
+					"border",
+					this.theme.fg("muted", `${teamWorkflowLabel(run.team, run.workflow)} · ${shortUsage(tasks)}`),
+					this.theme,
+					budget,
+				),
+				sectionLine({ name: "active", subject: formatCount(active.length, "agent"), theme: this.theme, budget, slot }),
 			];
 			for (const agent of active.slice(0, 8)) {
 				const status = iconForStatus(agent.status, {
 					runningGlyph: spinnerFrame(agent.taskId),
 				});
 				const usage = agent.usage
-					? formatUsage(agent.usage)
+					? compactUsage(agent.usage)
 					: agent.progress?.tokens
 						? `tokens=${agent.progress.tokens}`
 						: "usage=pending";
-				lines.push(line(`${status} ${agent.taskId} ${agent.role}->${agent.agent}`, w));
+				// The record comes from unvalidated `agents.json` — every field is
+				// guarded (`?? "?"`) and the legacy `role->agent` separator is `▸`.
 				lines.push(
-					line(
-						`  ${agent.routing ? `model ${agent.routing.requested ? `${agent.routing.requested} → ` : ""}${agent.routing.resolved}` : agent.model ? `model ${agent.model}` : "model pending"}`,
-						w,
+					railLine(
+						RAIL.body,
+						"border",
+						`${status} ${agent.taskId ?? "?"} ${agent.role ?? "?"} ${ACTIVE} ${agent.agent ?? "?"}`,
+						this.theme,
+						budget,
 					),
 				);
 				lines.push(
-					line(
-						`  ${agent.progress?.currentTool ? `tool ${agent.progress.currentTool} · ` : ""}${agent.toolUses ?? 0} tools · ${usage}`,
-						w,
+					railLine(
+						RAIL.body,
+						"border",
+						this.theme.fg(
+							"muted",
+							`  ${agent.routing ? `model ${agent.routing.requested ? `${agent.routing.requested} → ` : ""}${agent.routing.resolved ?? "pending"}` : agent.model ? `model ${agent.model}` : "model pending"}`,
+						),
+						this.theme,
+						budget,
+					),
+				);
+				lines.push(
+					railLine(
+						RAIL.body,
+						"border",
+						this.theme.fg(
+							"muted",
+							`  ${agent.progress?.currentTool ? `tool ${agent.progress.currentTool} · ` : ""}${formatCount(agent.toolUses ?? 0, "tool")} · ${usage}`,
+						),
+						this.theme,
+						budget,
 					),
 				);
 			}
-			if (!active.length) lines.push(line("- none", w));
-			lines.push(border("├", "─", "┤", w), line(`Waiting tasks (${waiting.length})`, w));
+			if (!active.length) lines.push(this.bodyRow(this.theme.fg("dim", "none"), budget));
+			lines.push(sectionLine({ name: "waiting", subject: formatCount(waiting.length, "task"), theme: this.theme, budget, slot }));
 			for (const task of waiting.slice(0, 8)) {
 				const status = iconForStatus("queued");
-				lines.push(line(`${status} ${task.id} ${waitingReason(task, tasks) ?? "waiting"}`, w));
+				lines.push(this.bodyRow(`${status} ${task.id ?? "?"} ${waitingReason(task, tasks) ?? "waiting"}`, budget));
 			}
-			if (waiting.length === 0) lines.push(line("- none", w));
-			lines.push(border("├", "─", "┤", w), line(`Completed agents (${completed.length})`, w));
+			if (waiting.length === 0) lines.push(this.bodyRow(this.theme.fg("dim", "none"), budget));
+			lines.push(sectionLine({ name: "done", subject: formatCount(completed.length, "agent"), theme: this.theme, budget, slot }));
 			for (const agent of completed) {
 				const status = iconForStatus(agent.status === "running" ? "stopped" : agent.status);
 				lines.push(
-					line(
-						`${status} ${agent.taskId} ${agent.model ? `· ${agent.model}` : ""}${agent.usage ? ` · ${formatUsage(agent.usage)}` : ""}`,
-						w,
+					this.bodyRow(
+						`${status} ${agent.taskId ?? "?"} ${agent.model ? `· ${agent.model}` : ""}${agent.usage ? ` · ${compactUsage(agent.usage)}` : ""}`,
+						budget,
 					),
 				);
 			}
-			if (completed.length === 0) lines.push(line("- none", w));
-			lines.push(border("├", "─", "┤", w));
-			for (const entry of formatTaskGraphLines(tasks).slice(0, 6)) lines.push(line(entry, w));
-			lines.push(line("q close · /team-dashboard details", w));
-			// F-6: compute the auto-close countdown BEFORE pushing the bottom border
-			// so the countdown renders inside the bordered box rather than below it.
+			if (completed.length === 0) lines.push(this.bodyRow(this.theme.fg("dim", "none"), budget));
+			lines.push(sectionLine({ name: "tasks", subject: formatCount(tasks.length, "task"), theme: this.theme, budget, slot }));
+			for (const entry of formatTaskGraphLines(tasks).slice(0, 6)) {
+				// `formatTaskGraphLines` (src/runtime/task-display.ts) still emits the
+				// legacy `role->agent` separator; normalize it at the render boundary
+				// so no `->` can reach the TUI (§4 consistency fix).
+				lines.push(this.bodyRow(this.theme.fg("muted", entry.replace(/->/g, ACTIVE)), budget));
+			}
+			// F-6: compute the auto-close countdown BEFORE the cap so the countdown
+			// renders inside the frame rather than below it.
 			// Auto-close logic: if run is terminal and no active agents, close after delay
 			const isTerminal = ["completed", "failed", "cancelled", "blocked"].includes(run.status);
 			const hasActiveAgents = agents.some((a) => a.status === "running");
@@ -268,7 +339,7 @@ export class LiveRunSidebar {
 						this.done(undefined);
 					}, autoCloseMs);
 					this.autoCloseTimeout?.unref();
-					lines.push(line(`auto-close in ${Math.round(autoCloseMs / 1000)}s…`, w));
+					lines.push(this.bodyRow(this.theme.fg("dim", `auto-close in ${Math.round(autoCloseMs / 1000)}s…`), budget));
 				}
 			}
 			// Clear timeout if conditions change
@@ -276,17 +347,25 @@ export class LiveRunSidebar {
 				clearTimeout(this.autoCloseTimeout);
 				this.autoCloseTimeout = undefined;
 			}
-			lines.push(border("╰", "─", "╯", w));
-			this.cachedLines = renderLines(
-				lines.map((entry) => this.colorLine(entry)),
-				w,
-			);
+			this.cachedLines = renderLines(this.renderFrame(lines, budget, slot), w);
 			this.cachedSignature = signature;
 			this.cachedWidth = w;
 		}
 		return this.cachedLines;
 	}
 
+	/** One `┃` body row (glyph + colour owned by the rail helper). */
+	private bodyRow(content: string, budget: number): string {
+		return railLine(RAIL.body, "border", content, this.theme, budget);
+	}
+
+	/** Append the `┗ <hint>` cap and colorize the glyphs (F-1 / V-3). */
+	private renderFrame(lines: string[], budget: number, slot: RailSlot): string[] {
+		const hint = this.theme.fg("dim", formatHint(SIDEBAR_HINT));
+		const framed = [...lines, railLine(RAIL.close, slot, hint, this.theme, budget)];
+		return framed.map((entry) => this.colorLine(entry));
+	}
+
 	handleInput(data: string): void {
 		if (data === "q" || data === "\u001b") this.done(undefined);
 	}

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);
 	}
 }