pi-crew 0.11.0 → 0.11.2

package/src/ui/agents-jobs-browser.ts

@@ -7,15 +7,17 @@
  * precedent: a dedicated bottom-anchored overlay, NOT a new dashboard pane —
  * the pane route would churn the ActivePane union + keybinding parity goldens.
  *
- * Layout (width-aware for terminals 80..250):
+ * Layout (width-aware for terminals 80..250) — RAIL frame (M4, 2026-09-16):
+ * canopy + rail-prefixed body rows + `┗` cap, the two columns joined by DOT
+ * LEADERS (no inner `│` frame column):
  *
- *   Agents & Jobs — 2 agents · 1 job
- *   Live agents (2)            │ ▸ adaptive-01-executor
- *   › ⠋ Explorer · 41 tok/s    │   0/1 tasks · 1 agents
- *     ✓ Writer                 │   ⠋ adaptive-01-executor executor
- *   Scheduled jobs (1)         │     reading…
- *   › ⏰ watch: omo · cron · next 23h …   │
- *   [↑↓] navigate · [Enter] …  │
+ *   ┏ AGENTS ▸ 2 agents · 1 job ············· ↑/↓ move · Enter transcript
+ *   ┃ Live agents (2)          ··············· ▸ adaptive-01-executor
+ *   ┃ › ⠋ Explorer · 41 tok/s  ···············   0/1 tasks · 1 agents
+ *   ┃   ✓ Writer               ···············    ⠋ adaptive-01-executor
+ *   ┃ Scheduled jobs (1)       ···············      reading…
+ *   ┃   ⏰ watch: omo · cron · next 23h ······
+ *   ┗ Q close
  *
  * LEFT column — unified list: live agents first (status glyph via
  * iconForStatus/spinnerFrame, role name, tok/s while running — the SAME
@@ -67,10 +69,11 @@ import { pad, sanitizeLine, truncate, visibleWidth } from "../utils/visual.ts";
 import { renderAgentsPane } from "./dashboard-panes/agents-pane.ts";
 import { renderScheduleDetails, schedulesHiddenJobsHintLine } from "./dashboard-panes/schedules-pane.ts";
 import { computeLiveDurationMs } from "./live-duration.ts";
+import { CURSOR, canopyLine, formatHint, overflowHint, RAIL, railLeaders, railLine } from "./rail.ts";
 import type { RunUiSnapshot } from "./snapshot-types.ts";
 import { spinnerFrame } from "./spinner.ts";
 import { iconForStatus } from "./status-colors.ts";
-import type { CrewTheme } from "./theme-adapter.ts";
+import { asCrewTheme, type CrewTheme } from "./theme-adapter.ts";
 import { activeWidgetRuns } from "./widget/widget-model.ts";
 
 // ─── Public data types ─────────────────────────────────────────────────────
@@ -182,6 +185,7 @@ function watchAgentTranscriptScript(): string | undefined {
 /** tok/s for record-based entries (no live handle in this process). */
 function recordTokPerSec(record: CrewAgentRecord, nowMs: number): number | undefined {
 	if (record.status !== "running") return undefined;
+	if (!record.taskId) return undefined;
 	try {
 		const usage = getTaskUsage(record.taskId);
 		const total = (usage.input ?? 0) + (usage.output ?? 0) + (usage.cacheWrite ?? 0);
@@ -228,6 +232,9 @@ function shellQuote(value: string): string {
 
 export class AgentsJobsBrowser {
 	private readonly options: AgentsJobsBrowserOptions;
+	/** RAIL helpers need a theme; `asCrewTheme(undefined)` is the no-op theme,
+	 *  so a headless/test render stays plain text exactly as before. */
+	private readonly theme: CrewTheme;
 	private cachedEntries: AgentsJobsBrowserEntry[] = [];
 	private cachedAt = -Infinity;
 	private hiddenCount = 0;
@@ -243,6 +250,7 @@ export class AgentsJobsBrowser {
 
 	constructor(options: AgentsJobsBrowserOptions) {
 		this.options = options;
+		this.theme = options.theme ?? asCrewTheme(undefined);
 		this.refreshData(true);
 		this.pollTimer = setInterval(() => {
 			if (this.closed) return;
@@ -408,8 +416,8 @@ export class AgentsJobsBrowser {
 		const manifest = this.manifestFor(entry.runId);
 		if (!record || !manifest) {
 			return [
-				`▸ ${entry.taskId} (${entry.role})`,
-				`  status: ${entry.status}`,
+				`▸ ${entry.taskId ?? "?"} (${entry.role ?? "?"})`,
+				`  status: ${entry.status ?? "?"}`,
 				"  (agent record unavailable — run manifest not found)",
 			];
 		}
@@ -626,36 +634,31 @@ export class AgentsJobsBrowser {
 	 *  exceed `width` (truncate/visibleWidth from utils/visual — the same
 	 *  width model pi-tui enforces). */
 	render(width?: number): string[] {
-		// FRAMED PANEL (redesign 2026-09-14, "dễ nhìn"): a full box —
-		//
-		//   ╭─ Agents & Jobs ── 2 agents · 1 job ─────────────────────╮
-		//   │ Live agents (2)        │ ▸ adaptive-01-executor        │
-		//   │ › ⠋ Explorer · 41 t/s  │   0/1 tasks · 1 agents        │
-		//   ╰─ [↑↓] move · [⏎] detail · [p] pane · [q] close ────────╯
-		//
-		// Title + counts embed in the TOP border, key hints in the BOTTOM
-		// border (the omp EditorTopBorder idiom) so the body is pure content
-		// and the panel reads as one visual unit over the terminal.
+		// RAIL frame (M4, 2026-09-16) — the rounded box is retired. Canopy
+		// `┏ AGENTS ▸ 2 agents · 1 job` + hint segment, every body row prefixed
+		// with the rail, the two columns joined by DOT LEADERS (railLeaders
+		// absorbs the slack; NO inner `│` frame column) and the surface capped
+		// with `┗ <hint>`. railLine owns the glyph + space and the pad/truncate
+		// to `budget`, so no line can exceed `width`.
 		const w = Math.max(60, width ?? this.options.columns ?? 80);
+		const budget = Math.max(0, w - 2);
 		const nowMs = this.nowMs();
-		// Inner budget: 2 border cols + 4 padding cols + 1 divider col.
-		const inner = w - 7;
+		const inner = budget;
 		const listWidth = Math.max(20, Math.min(MAX_LIST_WIDTH, Math.round(inner * 0.42)));
-		const detailWidth = Math.max(16, inner - listWidth);
+		const detailWidth = Math.max(16, Math.max(0, inner - listWidth - 2));
 		const maxBody = Math.max(MIN_BODY, Math.min(MAX_BODY, (this.options.rows ?? 24) - 6));
-		const dim = (text: string) => (this.options.theme ? this.options.theme.fg("border", text) : text);
-		const accent = (text: string) => (this.options.theme ? this.options.theme.fg("accent", text) : text);
-		const sep = dim("│");
+		const dim = (text: string) => this.theme.fg("border", text);
 
 		const counts = [
 			`${this.countAgents()} agent${this.countAgents() === 1 ? "" : "s"}`,
 			`${this.countJobs()} job${this.countJobs() === 1 ? "" : "s"}`,
 		];
 		if (this.hiddenCount > 0) counts.push(`${this.hiddenCount} hidden`);
-		const activeNotice = this.notice && this.notice.until > nowMs ? ` ${this.notice.text} ` : ` ${counts.join(" · ")} `;
-		const lines: string[] = [this.framedBorderRow("top", accent(` Agents & Jobs `), dim(truncate(activeNotice, w - 20)), w)];
+		// A transient notice (when one is live) replaces the counts in the canopy.
+		const subject = this.notice && this.notice.until > nowMs ? this.notice.text : counts.join(" · ");
+		const lines: string[] = [canopyLine({ word: "AGENTS", subject, right: this.hintRow(), theme: this.theme, budget })];
 		const hiddenHint = schedulesHiddenJobsHintLine(this.hiddenCount);
-		if (hiddenHint) lines.push(`${dim("│")} ${pad(dim(truncate(hiddenHint, w - 4)), w - 3)}${dim("│")}`);
+		if (hiddenHint) lines.push(railLine(RAIL.body, "border", dim(truncate(hiddenHint, budget)), this.theme, budget));
 
 		const left = this.renderListColumn(listWidth, maxBody, nowMs);
 		const right = this.renderDetailColumn(detailWidth, maxBody);
@@ -663,30 +666,20 @@ export class AgentsJobsBrowser {
 		// as tall as its tallest column, clamped to [5, maxBody].
 		const bodyHeight = Math.max(5, Math.min(maxBody, Math.max(left.length, right.length)));
 		for (let i = 0; i < bodyHeight; i++) {
-			const l = pad(left[i] ?? "", listWidth);
-			const r = pad(right[i] ?? "", detailWidth);
-			lines.push(`${dim("│")} ${l} ${sep} ${r} ${dim("│")}`);
+			const rawLeft = left[i] ?? "";
+			const rawRight = right[i] ?? "";
+			// Filler row (both columns exhausted): a bare rail row — dot leaders
+			// across an empty row would just paint noise.
+			const content =
+				rawLeft.trim() === "" && rawRight.trim() === ""
+					? ""
+					: railLeaders(pad(rawLeft, listWidth), truncate(rawRight, detailWidth), budget, this.theme);
+			lines.push(railLine(RAIL.body, "border", content, this.theme, budget));
 		}
-		lines.push(this.framedBorderRow("bottom", dim(" " + this.hintRow() + " "), "", w));
+		lines.push(railLine(RAIL.close, "border", this.capHint(), this.theme, budget));
 		return lines;
 	}
 
-	/** `╭─ title ── right ─────╮` / `╰─ hint ───────────────╯` — always exactly `w` visible cells. */
-	private framedBorderRow(which: "top" | "bottom", title: string, right: string, w: number): string {
-		const cornerL = which === "top" ? "╭" : "╰";
-		const cornerR = which === "top" ? "╮" : "╯";
-		const rule = which === "top" ? "─" : "─";
-		const titleCells = visibleWidth(title);
-		const rightCells = right ? visibleWidth(right) : 0;
-		const budget = w - 2 - titleCells - rightCells;
-		if (budget < 1) {
-			// Degenerate narrow: title only, truncated.
-			const t = truncate(title, w - 2);
-			return `${cornerL}${t}${cornerR}`;
-		}
-		return `${cornerL}${title}${rule.repeat(budget)}${right}${cornerR}`;
-	}
-
 	private countAgents(): number {
 		return this.cachedEntries.filter((entry) => entry.kind === "agent").length;
 	}
@@ -695,14 +688,28 @@ export class AgentsJobsBrowser {
 		return this.cachedEntries.filter((entry) => entry.kind === "job").length;
 	}
 
+	/** Header hint (canopy right segment) — RAIL format: `keys label` pairs. */
 	private hintRow(): string {
-		const base = this.focus === "list" ? "[↑↓] move · [⏎] transcript · [q] close" : "[↑↓] scroll · [⏎/Esc] back";
-		return base;
+		return this.focus === "list"
+			? formatHint([
+					[["up", "down"], "move"],
+					["enter", "transcript"],
+				])
+			: formatHint([
+					[["up", "down"], "scroll"],
+					["enter", "back"],
+				]);
+	}
+
+	/** End cap hint — the close/cancel action, LAST (RAIL hint rule). */
+	private capHint(): string {
+		return this.focus === "list" ? formatHint([["q", "close"]]) : formatHint([["esc", "back"]]);
 	}
 
 	/** LEFT column: section labels + unified rows, windowed around selection. */
 	private renderListColumn(listWidth: number, bodyHeight: number, nowMs: number): string[] {
 		const out: string[] = [];
+		const dim = (text: string) => this.theme.fg("border", text);
 		const push = (text: string) => out.push(truncate(sanitizeLine(text), listWidth));
 		if (this.cachedEntries.length === 0) {
 			push("No live agents · no scheduled jobs");
@@ -712,9 +719,9 @@ export class AgentsJobsBrowser {
 		const jobs = this.cachedEntries.filter((entry): entry is AgentsBrowserJobEntry => entry.kind === "job");
 		// Rows: section labels + one row per entry, in merged order.
 		const rows: { entry?: AgentsJobsBrowserEntry; text: string }[] = [];
-		if (agents.length > 0) rows.push({ text: `Live agents (${agents.length})` });
+		if (agents.length > 0) rows.push({ text: dim(`Live agents (${agents.length})`) });
 		for (const entry of agents) rows.push({ entry, text: this.agentRow(entry, nowMs) });
-		if (jobs.length > 0) rows.push({ text: `Scheduled jobs (${jobs.length})` });
+		if (jobs.length > 0) rows.push({ text: dim(`Scheduled jobs (${jobs.length})`) });
 		for (const entry of jobs) rows.push({ entry, text: this.jobRow(entry) });
 
 		// Windowing: keep the selected entry's row inside the visible slot
@@ -727,7 +734,7 @@ export class AgentsJobsBrowser {
 		}
 		for (const row of rows.slice(this.listScroll, this.listScroll + slots)) {
 			const isSelected = row.entry !== undefined && this.indexOf(row.entry) === this.selected;
-			const marker = row.entry === undefined ? "" : isSelected ? "› " : "  ";
+			const marker = row.entry === undefined ? "" : isSelected ? `${CURSOR} ` : "  ";
 			push(`${marker}${row.text}`);
 		}
 		return out;
@@ -738,9 +745,10 @@ export class AgentsJobsBrowser {
 	}
 
 	private agentRow(entry: AgentsBrowserAgentEntry, nowMs: number): string {
-		const icon = iconForStatus(entry.status, { runningGlyph: spinnerFrame(entry.taskId, nowMs) });
+		// GUARD (M4 §4): these fields come from unvalidated disk JSON.
+		const icon = iconForStatus(entry.status, { runningGlyph: spinnerFrame(entry.taskId ?? "", nowMs) });
 		const tok = entry.tokPerSec !== undefined && entry.status === "running" ? ` · ${entry.tokPerSec} tok/s` : "";
-		return `${icon} ${entry.role}${tok} · ${entry.taskId.slice(-8)}`;
+		return `${icon} ${entry.role ?? "?"}${tok} · ${(entry.taskId ?? "").slice(-8)}`;
 	}
 
 	private jobRow(entry: AgentsBrowserJobEntry): string {
@@ -765,16 +773,14 @@ export class AgentsJobsBrowser {
 		const maxScroll = Math.max(0, detail.length - (bodyHeight - 1));
 		this.detailScroll = Math.max(0, Math.min(this.detailScroll, maxScroll));
 		const windowed = detail.slice(this.detailScroll, this.detailScroll + bodyHeight - 1);
-		const title = entry.kind === "agent" ? `▸ ${entry.role} · ${entry.taskId.slice(-8)}` : `▸ ${sanitizeLine(entry.job.name)}`;
+		const title =
+			entry.kind === "agent" ? `▸ ${entry.role ?? "?"} · ${(entry.taskId ?? "").slice(-8)}` : `▸ ${sanitizeLine(entry.job.name)}`;
 		const out = [truncate(sanitizeLine(title), detailWidth)];
 		for (const line of windowed) out.push(truncate(sanitizeLine(line), detailWidth));
 		if (this.detailScroll > 0 || this.detailScroll + windowed.length < detail.length) {
-			out.push(
-				truncate(
-					`… ${this.detailScroll} above · ${Math.max(0, detail.length - this.detailScroll - windowed.length)} below`,
-					detailWidth,
-				),
-			);
+			// RAIL overflow dialect only (`▲ n above · ▼ m below`).
+			const below = Math.max(0, detail.length - this.detailScroll - windowed.length);
+			out.push(truncate(overflowHint(this.detailScroll, below, this.theme), detailWidth));
 		}
 		return out;
 	}

package/src/ui/card-colors.ts

@@ -55,6 +55,35 @@ export function mixBg(base: Rgb, accent: Rgb, intensity: number): string {
 
 const BLACK: Rgb = { r: 0, g: 0, b: 0 };
 
+/**
+ * The background slots Pi's Theme actually exposes (`ThemeBg` in
+ * node_modules/@earendil-works/pi-coding-agent/dist/modes/interactive/theme/theme.d.ts).
+ *
+ * P1-6 (2026-09-15): this probe used to pass "background", which is NOT a
+ * ThemeBg member. Pi's `getBgAnsi` throws `Unknown theme background color:
+ * background` for it, the surrounding catch swallowed the throw, and `base`
+ * stayed BLACK on every theme — so crew card tints were derived from the wrong
+ * base (visibly wrong on light themes). Never pass a slot outside this union.
+ * `selectedBg` is the slot whose value is the surrounding card/selection
+ * background; it is the one both Pi's `ThemeBg` and pi-crew's `CrewThemeBg`
+ * (theme-adapter.ts) define. Enforced by
+ * test/unit/round23-ui-unicode.test.ts (a fake theme records every slot).
+ */
+type ThemeBgSlot =
+	| "selectedBg"
+	| "scrollbarThumb"
+	| "userMessageBg"
+	| "customMessageBg"
+	| "toolPendingBg"
+	| "toolSuccessBg"
+	| "toolErrorBg";
+
+/** Duck-typed view of Pi's Theme methods (CrewTheme does not declare them). */
+type ThemeProbe = {
+	getBgAnsi?: (slot: ThemeBgSlot) => string | undefined;
+	getFgAnsi?: (slot: string) => string | undefined;
+};
+
 // ── Theme → background derivation ───────────────────────────────────────
 
 /**
@@ -76,17 +105,17 @@ export function deriveCardBackground(
 ): string {
 	// Prefer the theme's bg color as base (matches the card's surroundings).
 	let base = BLACK;
-	const themeAny = theme as unknown as {
-		getBgAnsi?: (slot: string) => string | undefined;
-		getFgAnsi?: (slot: string) => string | undefined;
-	};
+	const themeAny = theme as unknown as ThemeProbe;
 	if (themeAny.getBgAnsi) {
 		try {
-			const bg = themeAny.getBgAnsi("background");
-			const parsed = parseAnsiRgb(bg);
+			// "selectedBg" is a valid ThemeBg slot (P1-6). The catch only guards
+			// third-party theme shims that throw on the probe; it can no longer
+			// hide a permanently-invalid slot, because the slot type and the
+			// regression test both pin it to the ThemeBg union.
+			const parsed = parseAnsiRgb(themeAny.getBgAnsi("selectedBg"));
 			if (parsed) base = parsed;
 		} catch {
-			/* fall back to black */
+			/* shim threw — fall back to black */
 		}
 	}
 

package/src/ui/dashboard-panes/agents-pane.ts

@@ -2,11 +2,14 @@ import type { CrewAgentRecord } from "../../runtime/crew-agent-runtime.ts";
 import { type LiveAgentHandle, listLiveAgents, listLiveAgentsByWorkspace } from "../../runtime/live-session/live-agent-manager.ts";
 import { formatCost } from "../../state/usage.ts";
 import { visibleWidth } from "../../utils/visual.ts";
+import { formatCount, formatDuration } from "../format-helpers.ts";
 import { computeLiveDurationMs } from "../live-duration.ts";
+import { overflowHint, statusIcon } from "../rail.ts";
 import type { RunDashboardOptions } from "../run-dashboard.ts";
 import type { RunUiSnapshot } from "../snapshot-types.ts";
 import { spinnerFrame } from "../spinner.ts";
 import { iconForStatus } from "../status-colors.ts";
+import { PANE_THEME } from "./pane-theme.ts";
 
 /**
  * Fixed visible widths for the per-agent numeric metrics (finding V-1).
@@ -16,7 +19,7 @@ import { iconForStatus } from "../status-colors.ts";
  */
 const TOKENS_METRIC_WIDTH = 5; // `1.2k`, `12.3k`, `123`
 const COST_METRIC_WIDTH = 7; // `$0.0500`, `$1.50`
-const DURATION_METRIC_WIDTH = 6; // `3.0s`, `59.9s`, `120.0s`
+const DURATION_METRIC_WIDTH = 6; // `3.0s`, `59.9s`, `5m14s` (formatDuration)
 
 /**
  * Width-aware right-align (padStart) for a numeric metric so its column stays
@@ -29,6 +32,30 @@ function alignMetric(value: string, width: number): string {
 	return gap > 0 ? " ".repeat(gap) + value : value;
 }
 
+/**
+ * Agent status glyph, from the shared RAIL vocabulary (`statusIcon`). Two
+ * deliberate exceptions, both kept because rail.ts cannot express them:
+ *  - `running` → the animated braille spinner (a live activity frame, not a
+ *    static status icon);
+ *  - `waiting`/`needs_attention`/`blocked` → ⏳/⚠/⏸: `statusIcon` has only
+ *    four outputs (✓ ✗ ⟳ ○) and would collapse all three into `○`, losing
+ *    the signal; the shared `status-colors` vocabulary is used for exactly
+ *    these.
+ * `queued` now renders rail's `○` instead of the legacy `◦`.
+ */
+function agentGlyph(status: string | undefined, taskId: string | undefined): string {
+	switch (status) {
+		case "running":
+			return spinnerFrame(taskId ?? "");
+		case "waiting":
+		case "needs_attention":
+		case "blocked":
+			return iconForStatus(status);
+		default:
+			return statusIcon(status ?? "unknown", PANE_THEME);
+	}
+}
+
 /**
  * Returns true if this agent did real work (LLM call, tool use, or non-trivial duration).
  * Scaffold-only agents (no tokens, no tools, no turns) are skipped in the agents pane —
@@ -99,17 +126,18 @@ export function renderAgentsPane(snapshot: RunUiSnapshot | undefined, options: R
 	const lineCount = Math.min(realAgents.length, 12);
 	const label =
 		realAgents.length !== snapshot.agents.length
-			? `${realAgents.length} real agents (${snapshot.agents.length} total)`
-			: `${realAgents.length} agents`;
+			? `${formatCount(realAgents.length, "real agent")} (${formatCount(snapshot.agents.length, "agent")} total)`
+			: formatCount(realAgents.length, "agent");
 
+	// `3/3 tasks · 3 agents` — the label arrives pre-pluralised by the caller
+	// ("N agents"); the task tally keeps the slash form on purpose (it reads as
+	// progress, not as a count).
 	lines.push(`${completed}/${total} tasks · ${label}`);
 
 	for (const agent of realAgents.slice(0, 12)) {
 		const liveHandle = liveForRun.find((h) => h.taskId === agent.taskId);
-		const icon = iconForStatus(agent.status, {
-			runningGlyph: spinnerFrame(agent.taskId),
-		});
-		const role = `${agent.role}`;
+		const icon = agentGlyph(agent.status, agent.taskId);
+		const role = `${agent.role ?? "?"}`;
 
 		// Compact activity line
 		const activity = liveHandle
@@ -145,23 +173,36 @@ export function renderAgentsPane(snapshot: RunUiSnapshot | undefined, options: R
 			// fired for EVERY running live agent in the dashboard. Use the shared,
 			// validated computeLiveDurationMs (mirrors widget-formatters.ts).
 			const ms = computeLiveDurationMs(liveHandle.activity, nowMs);
-			stats.push(alignMetric(`${(ms / 1000).toFixed(1)}s`, DURATION_METRIC_WIDTH));
+			stats.push(alignMetric(formatDuration(ms), DURATION_METRIC_WIDTH));
 			if (options.showModel !== false && liveHandle.modelName && liveHandle.modelName !== "default") {
 				stats.push(liveHandle.modelName);
 			}
 		} else if (agent.startedAt) {
-			const ms = nowMs - new Date(agent.startedAt).getTime();
-			if (Number.isFinite(ms)) stats.push(alignMetric(`${(ms / 1000).toFixed(1)}s`, DURATION_METRIC_WIDTH));
+			// Tier 13 (2026-09-21): a FINISHED agent's span must end at completedAt,
+			// never at the wall clock. The naive `nowMs - startedAt` made every
+			// completed agent of an old run inflate forever — the dashboard showed
+			// `01_explore … 29m39s` while the tool card showed the real `8m22s` for
+			// the same agent. Mirror computeLiveDurationMs: prefer a sane completedAt,
+			// else fall back to now; never emit a negative or absurd span.
+			const startedMs = new Date(agent.startedAt).getTime();
+			const rawCompleted = agent.completedAt ? new Date(agent.completedAt).getTime() : Number.NaN;
+			const completedMs = Number.isFinite(rawCompleted) && rawCompleted >= startedMs && rawCompleted <= nowMs ? rawCompleted : nowMs;
+			const ms = completedMs - startedMs;
+			if (Number.isFinite(ms) && ms >= 0) stats.push(alignMetric(formatDuration(ms), DURATION_METRIC_WIDTH));
 		}
 
 		const statsStr = stats.length ? ` · ${stats.join(" ")}` : "";
-		lines.push(`  ${icon} ${agent.taskId} ${role}${statsStr}`);
+		lines.push(`  ${icon} ${agent.taskId ?? "?"} ${role}${statsStr}`);
 		lines.push(`    ${activity}`);
 	}
 
-	if (snapshot.agents.length > 12) {
-		lines.push(`  … +${snapshot.agents.length - 12} more`);
-	}
+	// Overflow in the ONE rail dialect (`▲ n above` / `▼ m below`), replacing
+	// the legacy `… +N more`. The count is derived from the SAME list the cap
+	// slices (`realAgents`), not from `snapshot.agents` — the pre-migration
+	// line could report rows that were never hidden (scaffold agents filtered
+	// out above).
+	const hiddenBelow = realAgents.length - 12;
+	if (hiddenBelow > 0) lines.push(`  ${overflowHint(0, hiddenBelow, PANE_THEME)}`);
 
 	return lines;
 }

package/src/ui/dashboard-panes/cancellation-pane.ts

@@ -1,47 +1,5 @@
 import type { TeamRunManifest, TeamTaskState } from "../../state/types.ts";
 
-export interface CancellationPaneOptions {
-	maxReasons?: number;
-}
-
-export function renderCancellationPane(manifest: TeamRunManifest, tasks: TeamTaskState[], opts: CancellationPaneOptions = {}): string[] {
-	const maxReasons = opts.maxReasons ?? 5;
-	if (manifest.status !== "cancelled" && manifest.status !== "blocked") {
-		const cancellingTasks = tasks.filter((t) => t.status === "cancelled");
-		if (cancellingTasks.length === 0) return ["Cancellation pane: no active cancellations"];
-	}
-
-	const lines: string[] = ["Cancellation pane"];
-
-	if (manifest.status === "cancelled") {
-		lines.push(`  Run status: cancelled`);
-	} else if (manifest.status === "blocked") {
-		lines.push(`  Run status: blocked`);
-	}
-
-	const cancelledTasks = tasks.filter((t) => t.status === "cancelled");
-	if (cancelledTasks.length > 0) {
-		lines.push(`  Cancelled tasks (${cancelledTasks.length}):`);
-		for (const task of cancelledTasks.slice(0, maxReasons)) {
-			const reason = task.error ?? "unknown";
-			lines.push(`    ✗ ${task.id}: ${reason}`);
-		}
-		if (cancelledTasks.length > maxReasons) {
-			lines.push(`    ... and ${cancelledTasks.length - maxReasons} more`);
-		}
-	}
-
-	if (manifest.policyDecisions?.length) {
-		const decisions = manifest.policyDecisions.slice(0, maxReasons);
-		lines.push(`  Policy decisions (${manifest.policyDecisions.length}):`);
-		for (const d of decisions) {
-			lines.push(`    ${d.action}: ${d.message}`);
-		}
-	}
-
-	return lines;
-}
-
 /**
  * D-1 / L-2 — a one-line terminal-run reason for the dashboard detail row.
  *

package/src/ui/dashboard-panes/health-pane.ts

@@ -1,4 +1,5 @@
 import { summarizeHeartbeats } from "../heartbeat-aggregator.ts";
+import { formatHint } from "../rail.ts";
 import type { RunUiSnapshot } from "../snapshot-types.ts";
 
 export interface HealthPaneOptions {
@@ -19,12 +20,13 @@ export function renderHealthPane(snapshot: RunUiSnapshot | undefined, opts: Heal
 		`Health pane: ${summary.healthy}/${summary.totalTasks} healthy · stale=${summary.stale} · dead=${summary.dead} · missing=${summary.missing}`,
 	];
 	if (summary.worstStaleMs > 0) lines.push(`Worst stale: ${seconds(summary.worstStaleMs)} ago`);
-	const hints: string[] = [];
+	// One hint format (rail.ts `formatHint`): keys `label` joined by ` · `.
+	const hints: Array<readonly [string, string]> = [];
 	const foreground = opts.isForeground !== false;
-	if ((summary.dead > 0 || summary.missing > 0) && foreground) hints.push("R recovery");
-	if ((summary.dead > 0 || summary.stale > 0) && foreground) hints.push("K kill stale");
-	hints.push("D diagnostic export");
-	lines.push(`Actions: ${hints.join(" · ")}`);
+	if ((summary.dead > 0 || summary.missing > 0) && foreground) hints.push(["R", "recovery"]);
+	if ((summary.dead > 0 || summary.stale > 0) && foreground) hints.push(["K", "kill stale"]);
+	hints.push(["D", "diagnostic export"]);
+	lines.push(`Actions: ${formatHint(hints)}`);
 	if (!foreground && (summary.dead > 0 || summary.missing > 0 || summary.stale > 0))
 		lines.push("Async run: R/K disabled — inspect process manually or use /team-api.");
 	return lines;

package/src/ui/dashboard-panes/mailbox-pane.ts

@@ -1,12 +1,14 @@
+import { formatHint } from "../rail.ts";
 import type { RunUiSnapshot } from "../snapshot-types.ts";
 
 export function renderMailboxPane(snapshot: RunUiSnapshot | undefined): string[] {
 	if (!snapshot) return ["Mailbox pane: snapshot unavailable"];
 	const mailbox = snapshot.mailbox;
 	const approx = mailbox.approximate ? " · approximate (tail)" : "";
-	const lines: string[] = [
-		`Mailbox pane: inbox unread=${mailbox.inboxUnread} · outbox pending=${mailbox.outboxPending} · attention=${mailbox.needsAttention}${approx}`,
-	];
+	const unread = mailbox.inboxUnread ?? 0;
+	const outgoing = mailbox.outboxPending ?? 0;
+	const attention = mailbox.needsAttention ?? 0;
+	const lines: string[] = [`Mailbox pane: inbox unread=${unread} · outbox pending=${outgoing} · attention=${attention}${approx}`];
 	// Kind-separated breakdown
 	const kindParts: string[] = [];
 	const steer = mailbox.steerUnread ?? 0;
@@ -26,10 +28,24 @@ export function renderMailboxPane(snapshot: RunUiSnapshot | undefined): string[]
 			lines.push(`  📋 ${followUp} follow-up(s) pending review.`);
 		}
 	}
-	if (mailbox.needsAttention > 0) {
-		lines.push("Needs attention: press Enter for detail · A ack · N nudge · C compose · X ack all.");
+	if (attention > 0) {
+		// One hint format (rail.ts `formatHint`): keys `label` joined by ` · `.
+		lines.push(
+			`Needs attention: press ${formatHint([
+				["Enter", "for detail"],
+				["A", "ack"],
+				["N", "nudge"],
+				["C", "compose"],
+				["X", "ack all"],
+			])}.`,
+		);
 	} else {
-		lines.push("No mailbox items need attention. Press Enter for detail or C compose.");
+		lines.push(
+			`No mailbox items need attention. Press ${formatHint([
+				["Enter", "for detail"],
+				["C", "compose"],
+			])}.`,
+		);
 	}
 	return lines;
 }

package/src/ui/dashboard-panes/metrics-pane.ts

@@ -1,5 +1,5 @@
 import type { MetricRegistry } from "../../observability/metric-registry.ts";
-import type { HistogramPoint, MetricLabels, MetricPoint } from "../../observability/metrics-primitives.ts";
+import type { HistogramPoint, MetricLabels, MetricLabelValue, MetricPoint } from "../../observability/metrics-primitives.ts";
 import type { RunUiSnapshot } from "../snapshot-types.ts";
 
 export interface MetricsPaneOptions {
@@ -7,9 +7,17 @@ export interface MetricsPaneOptions {
 	maxCounters?: number;
 }
 
-function labelsText(labels: MetricLabels): string {
-	const entries = Object.entries(labels);
-	return entries.length ? `{${entries.map(([key, value]) => `${key}=${value}`).join(",")}}` : "";
+// Metric label values come from an unvalidated `Record` (disk/producer fed) —
+// every interpolation is guarded so `undefined` can never reach the pane.
+function labelValue(value: MetricLabelValue | undefined): string {
+	if (value === undefined || value === null) return "?";
+	if (typeof value === "number" && !Number.isFinite(value)) return "?";
+	return `${value}`;
+}
+
+function labelsText(labels: MetricLabels | undefined): string {
+	const entries = Object.entries(labels ?? {});
+	return entries.length ? `{${entries.map(([key, value]) => `${key}=${labelValue(value)}`).join(",")}}` : "";
 }
 
 function isHistogramPoint(point: MetricPoint | HistogramPoint): point is HistogramPoint {
@@ -24,14 +32,14 @@ export function renderMetricsPane(_snapshot: RunUiSnapshot | undefined, opts: Me
 	for (const snapshot of snapshots.slice(0, opts.maxCounters ?? 10)) {
 		const first = snapshot.values[0];
 		if (!first) {
-			lines.push(`${snapshot.name}: empty`);
+			lines.push(`${snapshot.name ?? "?"}: empty`);
 			continue;
 		}
 		if (isHistogramPoint(first))
 			lines.push(
-				`${snapshot.name}${labelsText(first.labels)} count=${first.count} p95=${Number.isFinite(first.quantiles.p95) ? Math.round(first.quantiles.p95) : "n/a"}`,
+				`${snapshot.name ?? "?"}${labelsText(first.labels)} count=${first.count ?? 0} p95=${Number.isFinite(first.quantiles?.p95) ? Math.round(first.quantiles.p95) : "n/a"}`,
 			);
-		else lines.push(`${snapshot.name}${labelsText(first.labels)} ${first.value}`);
+		else lines.push(`${snapshot.name ?? "?"}${labelsText(first.labels)} ${labelValue(first.value)}`);
 	}
 	return lines;
 }

package/src/ui/dashboard-panes/pane-theme.ts

@@ -0,0 +1,21 @@
+/**
+ * pane-theme.ts — the theme binding dashboard panes render RAIL primitives with.
+ *
+ * Contract (§2.G of docs/UI-DESIGN-SYSTEM.md): a pane returns CONTENT LINES
+ * ONLY and stays uncolored — the frame owner (run-dashboard.ts) prefixes the
+ * `┃ ` rail and colorizes embedded status glyphs through
+ * `colorizeStatusGlyphs`. The RAIL primitives in `src/ui/rail.ts`
+ * (`statusIcon`, `statusSlot`, `overflowHint`, `railLine`, `formatHint`, …)
+ * all take a `CrewTheme`, so panes hand them this identity theme: every glyph,
+ * overflow dialect and hint still comes from the one shared vocabulary, while
+ * no ANSI escapes leak into pane content.
+ *
+ * Not a fork of a rail primitive — a no-op `CrewTheme` adapter
+ * (`asCrewTheme(undefined)` → identity `fg`/`bold`) so uncolored producers can
+ * call the colored primitives.
+ */
+
+import { asCrewTheme } from "../theme-adapter.ts";
+
+/** Identity theme: `fg(color, text) === text`, `bold(text) === text`. */
+export const PANE_THEME = asCrewTheme(undefined);