pi-crew 0.9.11 → 0.9.12

package/CHANGELOG.md

@@ -1,5 +1,43 @@
 # Changelog
 
+## [v0.9.12] — TUI UI/UX polish (21 findings) (2026-06-27)
+
+Comprehensive TUI UX review of pi-crew's UI layer (`src/ui/` + `src/utils/visual.ts`). 21 findings (5×P1, 10×P2, 6×P3), all addressed. Full review with evidence-backed file:line citations: `research-findings/pi-crew-uiux-review.md`.
+
+### Bug fixes
+
+- **F-3 (P1)** — `src/ui/live-conversation-overlay.ts`: local `pad` used `s.length` (counted ANSI escape bytes) and `content.slice` (UTF-16 units) → border drift on every colored or CJK line. Replaced with `pad`/`truncate` from `utils/visual.ts` (reference impl: `transcript-viewer.ts`).
+- **F-1 / F-2 / V-3 (P1/P2)** — `src/ui/status-colors.ts` (new shared `colorizeStatusGlyphs()`): unified status-glyph colorization covers ⏳ (waiting), ⚠ (needs_attention), and the braille spinner range ⠁–⣿ — the two most attention-demanding states were previously uncolored. Replaces duplicated per-module glyph maps/regexes in `widget-renderer.ts`, `live-run-sidebar.ts`, and `run-dashboard.ts`.
+- **L-1 (P1)** — `src/ui/run-dashboard.ts`: windowed run list with `scrollOffset`; selection can no longer escape the rendered 8-row window. ↓ past row 7 previously hid the highlight and Enter acted on an invisible run. Brute-force verified for 0–30 runs.
+- **L-2 (P1)** — cancellation/failure reason now shown in default detail row (`run-dashboard.ts`) and `live-run-sidebar.ts`. Previously rendered only in `progress-pane` (pane `2`). `cancellation-pane.ts` wired in via `summarizeTerminalReason()` (D-1).
+- **V-1 (P2)** — tabular-aligned numeric metrics across `run-dashboard` footer, `dashboard-panes/agents-pane.ts`, and `widget/widget-formatters.ts` via width-aware `alignMetric` (visibleWidth-based). Eliminates per-tick column jitter on transitions like 9.9s→10.0s and 950→1.0k.
+- **F-5 (P2)** — `src/runtime/process-status.ts`: `ERROR_VISIBILITY_GRACE_MS = 10 * 60_000` (was the 8s `COMPLETED_VISIBILITY_GRACE_MS` shared with completed runs). Failed/cancelled runs now linger 10 min in the crew widget — the run-level header (✗ team/workflow · X/Y agents) is the "one-line trace". Successful completions still vanish in 8s.
+- **K-1 (P2)** — new `src/ui/overlays/help-overlay.ts`: `?` opens the HelpOverlay rendering `BINDINGS[]` grouped by scope. ~16/20 keybindings were previously undiscoverable (no `?` cheatsheet existed). Header hint updated.
+- **F-6 (P2)** — `src/ui/live-run-sidebar.ts`: auto-close countdown moved inside the bordered box (was rendered below the bottom border).
+- **V-2 (P2)** — `src/ui/crew-footer.ts`, `src/ui/crew-select-list.ts`: dropped ASCII `'...'` 3rd arg from `truncate(...)` so they use the default `'…'` (U+2026) consistently with the rest of the UI. Test updated.
+- **L-3 / L-4 / L-5 (P2/P3)** — width-aware `runLabel` keeps the goal visible (the most meaningful field); widget prioritizes running > queued > waiting with `finishedSlots` so finished rows only fill leftover budget and never push a live agent's activity line off-screen; run-list separator unified to ` · `.
+- **F-4 / F-7 (P2/P3)** — stale-snapshot hint in the default dashboard view when manifest reads are flaky; actionable empty/error states (no more "Dashboard error — see logs").
+- **T-1 (P3)** — `src/utils/visual.ts`: ZWJ (`U+200D`) removed from `WIDE_RANGES` (now correctly width-0; was inflating compound-emoji width and over-truncating).
+- **T-2 (P3)** — `src/ui/widget/index.ts`: debounced (~120ms) SIGWINCH + stdout-resize listener busts the render cache and requests a repaint. Guarded against double-registration across widget reinstalls.
+- **D-1 (P3)** — `src/ui/dashboard-panes/cancellation-pane.ts` wired in via `summarizeTerminalReason()` (was dead-imported by `test/unit/cancellation-pane.test.ts`, so kept and given a real consumer instead of deleted).
+
+### Shortcut collision fix
+
+- **Extension-load warning**: `alt+d` collided with `tui.editor.deleteWordForward` (verified in pi-tui `TUI_KEYBINDINGS`). Pi resolved in favor of the extension, *stripping* the editor's delete-word-forward binding. Moved dashboard shortcut to **`alt+c`** (mnemonic: **C**rew — verified free against the full built-in `alt+` keymap: occupied letters are `b, d, f, v, y`).
+- **Test guard hardened**: `test/unit/crew-shortcuts.test.ts` collision set now includes the editor keys (`alt+b/d/f/y`, `alt+backspace`, `alt+delete`). The previous set was incomplete (`alt+v, alt+enter, alt+arrows` only), which is why the bug slipped past tests. This class of regression is now caught at test time.
+
+### Decisions (deviations from the initial review)
+
+- **K-3 `KEY_RESERVED`**: NOT dead code — consumed by `test/unit/keybinding-map.parity.test.ts:29,185-203` and `test/manual/l2-keybinding-dispatch-smoke.mjs`. Corrected the misleading "dead code" doc instead of deleting (deleting would have broken the parity test).
+- **K-2 `alt+m` / `alt+t`**: blocked — mailbox overlay is run-scoped (requires a runId; reached via the dashboard); `team-status` is a text command (`handleTeamTool({action:"status"})`), not an overlay opener. `alt+d → dashboard` is the only wired shortcut.
+- **F-5 location**: fixed at the correct layer (`process-status.ts` run-level grace) rather than the report's suggested `widget-renderer.ts` agent-row linger; the run-level header line is the right "one-line trace" per the finding.
+
+### Verification
+
+- `npx tsc --noEmit` + `npm run typecheck`: 0 errors (incl. strip-types import smoke).
+- Focused UI cluster: **74/74 pass** across 8 suites — `crew-shortcuts` (incl. strengthened collision assertion), `crew-footer` (incl. renamed V-2 test), `keybinding-map parity`, `cancellation-pane`, `process-status ×3`, `agents-pane-cost`.
+- Full suite baseline (before this batch): 5642 / 5639 pass / 0 fail. Two post-change full runs hit `ETIMEDOUT` on `spawnSync` inside integration child-spawn tests (`worktree-run`, `cleanup-full-flow`) under load (0 assertion failures — environmental flake). To be reconfirmed against CI.
+
 ## [v0.9.11] — Per-run lock path for background-runner (parallel-spawn race) (2026-06-27)
 
 Bug caught by an E2E parallel-spawn test in this session, NOT by unit tests (which cannot spawn multiple real processes). Independent of the F1-F5/redaction batches.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-crew",
-  "version": "0.9.11",
+  "version": "0.9.12",
   "description": "Pi extension for coordinated AI teams, workflows, worktrees, and async task orchestration",
   "author": "baphuongna",
   "license": "MIT",

package/src/extension/crew-shortcuts.ts

@@ -6,9 +6,25 @@
  * built-in keymap (see analysis of pi-tui core/keybindings defaults):
  *
  *   alt+s → open the pi-crew settings overlay (config + theme picker)
+ *   alt+c → open the pi-crew run dashboard overlay (mnemonic: **C**rew)
  *
- * `alt+<letter>` combos are safe: Pi only binds `alt+v`, `alt+enter`, and the
- * alt+arrow navigation keys. `alt+s` is mnemonic (settings) and free.
+ * OCCUPIED alt+ keys in the built-in keymap (must NOT reuse — verified against
+ * pi-tui TUI_KEYBINDINGS + pi core keybindings.js):
+ *   alt+b (cursor word left)   alt+f (cursor word right)
+ *   alt+d (delete word forward) alt+y (yank pop)
+ *   alt+v (paste)              alt+s (crew settings — this module)
+ *   alt+enter / alt+up/down/left/right / alt+backspace / alt+delete
+ * Free alt+<letter> keys include: a, c, e, g, h, i, j, k, l, m, n, o, p, q,
+ * r, t, u, w, x, z.
+ *
+ * NOTE: an earlier revision used `alt+d` for the dashboard; that collided
+ * with `tui.editor.deleteWordForward` and Pi's conflict detector stripped the
+ * editor binding. `alt+c` is free AND mnemonic.
+ *
+ * NOTE: alt+m (mailbox) and alt+t (status) were considered but are NOT wired
+ * — the mailbox overlay is run-scoped (requires a runId; reached via the
+ * dashboard) and there is no standalone status overlay (status is a text
+ * command). See the K-2 note accompanying openTeamDashboard in commands.ts.
  *
  * Shortcuts are guarded by `hasUI` so they never fire in print/RPC mode, and
  * by the optional `registerShortcut` API so older Pi versions degrade
@@ -39,6 +55,17 @@ const CREW_SHORTCUTS: ReadonlyArray<ShortcutRegistration> = [
 			await openTeamSettingsOverlay(ctx);
 		},
 	},
+	{
+		key: "alt+c",
+		description: "pi-crew: open run dashboard (Crew)",
+		// Lazy-import so the heavy UI module chain (RunDashboard etc.) is only
+		// loaded on first use, not at extension load.
+		handler: async (ctx) => {
+		// LAZY: defer dynamic import of ./registration/commands.ts to its call site.
+			const { openTeamDashboard } = await import("./registration/commands.ts");
+			await openTeamDashboard(ctx);
+		},
+	},
 ];
 
 /**

package/src/extension/registration/commands.ts

@@ -260,6 +260,66 @@ async function handleHealthDashboardAction(ctx: ExtensionCommandContext, selecti
 
 let depsRef: RegisterTeamCommandsDeps | undefined;
 
+/**
+ * Open the pi-crew run dashboard overlay and run its action loop.
+ *
+ * Extracted verbatim from the `team-dashboard` command so it is reusable from
+ * a keyboard shortcut (alt+c, see crew-shortcuts.ts). Takes the base
+ * `ExtensionContext` (the shortcut handler's context) — uses only `hasUI`,
+ * `cwd`, `ui`, and `sessionManager` fields, so both `ExtensionContext` and
+ * `ExtensionCommandContext` satisfy it. Reads run caches via the module-level
+ * `depsRef` (set by `registerTeamCommands`), so it is a no-op if commands
+ * have not been registered yet. `deps` is captured into a local const so the
+ * non-undefined narrowing survives the awaited overlay call.
+ *
+ * The dashboard action helpers (handleMailboxDashboardAction, the viewers,
+ * notifyCommandResult, teamCommandContext/handleTeamTool) are declared for
+ * `ExtensionCommandContext` but only ever read base `ExtensionContext` fields
+ * (verified). The keyboard-shortcut path supplies an `ExtensionContext`, so we
+ * bridge those over-typed helpers with a single cast rather than relaxing
+ * signatures across several modules (some outside this file's scope).
+ */
+export async function openTeamDashboard(ctx: ExtensionContext): Promise<void> {
+	if (!ctx.hasUI) return;
+	const deps = depsRef;
+	if (!deps) return;
+	const cmdCtx = ctx as ExtensionCommandContext;
+	for (;;) {
+		// Extract sessionId for workspace-scoped filtering
+		const sessionId = cmdCtx.sessionManager?.getSessionId?.();
+		const runs = deps.getManifestCache(cmdCtx.cwd).list(50);
+		const uiConfig = loadConfig(cmdCtx.cwd).config.ui;
+		const rightPanel = (uiConfig?.dashboardPlacement ?? DEFAULT_UI.dashboardPlacement) === "right";
+		const width = rightPanel ? Math.min(90, Math.max(40, uiConfig?.dashboardWidth ?? DEFAULT_UI.dashboardWidth)) : "90%";
+		const { RunDashboard } = await ui();
+		const selection = await cmdCtx.ui.custom<RunDashboardSelection | undefined>((tui, theme, _keybindings, done) => new RunDashboard(runs, done, theme, { placement: rightPanel ? "right" : "center", showModel: uiConfig?.showModel, showTokens: uiConfig?.showTokens, showTools: uiConfig?.showTools, snapshotCache: deps.getRunSnapshotCache?.(cmdCtx.cwd), runProvider: () => deps.getManifestCache(cmdCtx.cwd).list(50), registry: deps.getMetricRegistry?.(), workspaceId: sessionId, requestRender: () => requestRenderTarget(tui) }), { overlay: true, overlayOptions: rightPanel ? { width, minWidth: 40, maxHeight: "100%", anchor: "top-right", offsetX: 0, offsetY: 0, margin: { top: 0, right: 0, bottom: 0, left: 0 } } : { width, maxHeight: "90%", anchor: "center", margin: 2 } });
+		if (!selection) return;
+		if (selection.action === "reload") continue;
+		if (selection.action === "notifications-dismiss") {
+			deps.dismissNotifications?.();
+			cmdCtx.ui.notify("pi-crew notifications dismissed.", "info");
+			continue;
+		}
+		if (selection.action === "mailbox-detail") {
+			await handleMailboxDashboardAction(cmdCtx, selection.runId);
+			deps.getRunSnapshotCache?.(cmdCtx.cwd).invalidate(selection.runId);
+			continue;
+		}
+		if (selection.action === "health-recovery" || selection.action === "health-kill-stale" || selection.action === "health-diagnostic-export") {
+			await handleHealthDashboardAction(cmdCtx, selection);
+			deps.getRunSnapshotCache?.(cmdCtx.cwd).invalidate(selection.runId);
+			continue;
+		}
+		if (selection.action === "agent-transcript" && await openTranscriptViewer(cmdCtx, selection.runId)) continue;
+		if (selection.action === "agent-live" && await openLiveConversation(cmdCtx, selection.runId)) continue;
+		if (selection.action === "agent-live") { await notifyCommandResult(cmdCtx, commandText({ content: [{ type: "text", text: "No live agent found for this run." }] })); continue; }
+		const result = selection.action === "api" ? await handleTeamTool({ action: "api", runId: selection.runId, config: { operation: "read-manifest" } }, teamCommandContext(cmdCtx)) : selection.action === "agents" ? await handleTeamTool({ action: "api", runId: selection.runId, config: { operation: "agent-dashboard" } }, teamCommandContext(cmdCtx)) : selection.action === "mailbox" ? await handleTeamTool({ action: "api", runId: selection.runId, config: { operation: "read-mailbox" } }, teamCommandContext(cmdCtx)) : selection.action === "agent-events" ? await handleTeamTool({ action: "api", runId: selection.runId, config: { operation: "read-agent-events", limit: 50 } }, teamCommandContext(cmdCtx)) : selection.action === "agent-output" ? await handleTeamTool({ action: "api", runId: selection.runId, config: { operation: "read-agent-output", maxBytes: 32_000 } }, teamCommandContext(cmdCtx)) : selection.action === "agent-transcript" ? await handleTeamTool({ action: "api", runId: selection.runId, config: { operation: "read-agent-transcript" } }, teamCommandContext(cmdCtx)) : // eslint-disable-next-line @typescript-eslint/no-explicit-any
+			await handleTeamTool({ action: selection.action as any, runId: selection.runId }, teamCommandContext(cmdCtx));
+		await notifyCommandResult(cmdCtx, commandText(result));
+		return;
+	}
+}
+
 export function registerTeamCommands(pi: ExtensionAPI, deps: RegisterTeamCommandsDeps): void {
 	depsRef = deps;
 	pi.registerCommand("teams", {
@@ -497,40 +557,7 @@ export function registerTeamCommands(pi: ExtensionAPI, deps: RegisterTeamCommand
 	} });
 
 	pi.registerCommand("team-dashboard", { description: "Open a pi-crew run dashboard overlay", handler: async (_args: string, ctx: ExtensionCommandContext) => {
-		for (;;) {
-			// Extract sessionId for workspace-scoped filtering
-			const sessionId = ctx.sessionManager?.getSessionId?.();
-			const runs = deps.getManifestCache(ctx.cwd).list(50);
-			const uiConfig = loadConfig(ctx.cwd).config.ui;
-			const rightPanel = (uiConfig?.dashboardPlacement ?? DEFAULT_UI.dashboardPlacement) === "right";
-			const width = rightPanel ? Math.min(90, Math.max(40, uiConfig?.dashboardWidth ?? DEFAULT_UI.dashboardWidth)) : "90%";
-			const { RunDashboard } = await ui();
-			const selection = await ctx.ui.custom<RunDashboardSelection | undefined>((tui, theme, _keybindings, done) => new RunDashboard(runs, done, theme, { placement: rightPanel ? "right" : "center", showModel: uiConfig?.showModel, showTokens: uiConfig?.showTokens, showTools: uiConfig?.showTools, snapshotCache: deps.getRunSnapshotCache?.(ctx.cwd), runProvider: () => deps.getManifestCache(ctx.cwd).list(50), registry: deps.getMetricRegistry?.(), workspaceId: sessionId, requestRender: () => requestRenderTarget(tui) }), { overlay: true, overlayOptions: rightPanel ? { width, minWidth: 40, maxHeight: "100%", anchor: "top-right", offsetX: 0, offsetY: 0, margin: { top: 0, right: 0, bottom: 0, left: 0 } } : { width, maxHeight: "90%", anchor: "center", margin: 2 } });
-			if (!selection) return;
-			if (selection.action === "reload") continue;
-			if (selection.action === "notifications-dismiss") {
-				deps.dismissNotifications?.();
-				ctx.ui.notify("pi-crew notifications dismissed.", "info");
-				continue;
-			}
-			if (selection.action === "mailbox-detail") {
-				await handleMailboxDashboardAction(ctx, selection.runId);
-				deps.getRunSnapshotCache?.(ctx.cwd).invalidate(selection.runId);
-				continue;
-			}
-			if (selection.action === "health-recovery" || selection.action === "health-kill-stale" || selection.action === "health-diagnostic-export") {
-				await handleHealthDashboardAction(ctx, selection);
-				deps.getRunSnapshotCache?.(ctx.cwd).invalidate(selection.runId);
-				continue;
-			}
-			if (selection.action === "agent-transcript" && await openTranscriptViewer(ctx, selection.runId)) continue;
-			if (selection.action === "agent-live" && await openLiveConversation(ctx, selection.runId)) continue;
-			if (selection.action === "agent-live") { await notifyCommandResult(ctx, commandText({ content: [{ type: "text", text: "No live agent found for this run." }] })); continue; }
-			const result = selection.action === "api" ? await handleTeamTool({ action: "api", runId: selection.runId, config: { operation: "read-manifest" } }, teamCommandContext(ctx)) : selection.action === "agents" ? await handleTeamTool({ action: "api", runId: selection.runId, config: { operation: "agent-dashboard" } }, teamCommandContext(ctx)) : selection.action === "mailbox" ? await handleTeamTool({ action: "api", runId: selection.runId, config: { operation: "read-mailbox" } }, teamCommandContext(ctx)) : selection.action === "agent-events" ? await handleTeamTool({ action: "api", runId: selection.runId, config: { operation: "read-agent-events", limit: 50 } }, teamCommandContext(ctx)) : selection.action === "agent-output" ? await handleTeamTool({ action: "api", runId: selection.runId, config: { operation: "read-agent-output", maxBytes: 32_000 } }, teamCommandContext(ctx)) : selection.action === "agent-transcript" ? await handleTeamTool({ action: "api", runId: selection.runId, config: { operation: "read-agent-transcript" } }, teamCommandContext(ctx)) : // eslint-disable-next-line @typescript-eslint/no-explicit-any
-				await handleTeamTool({ action: selection.action as any, runId: selection.runId }, teamCommandContext(ctx));
-			await notifyCommandResult(ctx, commandText(result));
-			return;
-		}
+		await openTeamDashboard(ctx);
 	} });
 
 	pi.registerCommand("team-mascot", { description: "Show an animated mascot splash", handler: async (args: string, ctx: ExtensionCommandContext) => {

package/src/runtime/process-status.ts

@@ -16,7 +16,11 @@ export interface ProcessLiveness {
  */
 const ORPHANED_ACTIVE_RUN_MS = 2 * 60 * 1000;
 /** How long a completed run stays visible in the widget after completion. */
-const COMPLETED_VISIBILITY_GRACE_MS = 8000;
+const COMPLETED_VISIBILITY_GRACE_MS = 8_000;
+/** Errors (failed/cancelled) linger far longer so a failed run leaves a visible
+ * trace in the crew widget for ~10 min (F-5). Successful completions vanish
+ * quickly to keep the widget quiet. */
+const ERROR_VISIBILITY_GRACE_MS = 10 * 60 * 1000;
 /** Maximum age (ms) for an active run before it's considered stale.
  * After this time, PID-only liveness is unreliable due to PID recycling. */
 const STALE_ACTIVE_RUN_MS = 30 * 60 * 1000;
@@ -120,12 +124,13 @@ export function isDisplayActiveRun(run: TeamRunManifest, agents: CrewAgentRecord
 	}
 	// Grace period: show completed runs for a few seconds so users see the result.
 	if (run.status === "completed" || run.status === "failed" || run.status === "cancelled") {
+		const grace = run.status === "completed" ? COMPLETED_VISIBILITY_GRACE_MS : ERROR_VISIBILITY_GRACE_MS;
 		const lastAgentActivity = agents.reduce<number>((max, agent) => {
 			const ts = agent.completedAt ?? agent.startedAt;
 			const parsed = ts ? new Date(ts).getTime() : 0;
 			return Number.isFinite(parsed) && parsed > max ? parsed : max;
 		}, new Date(run.updatedAt).getTime());
-		if (Number.isFinite(lastAgentActivity) && now - lastAgentActivity < COMPLETED_VISIBILITY_GRACE_MS) return true;
+		if (Number.isFinite(lastAgentActivity) && now - lastAgentActivity < grace) return true;
 		return false;
 	}
 	if (!isActiveRunStatus(run.status)) return false;

package/src/ui/crew-footer.ts

@@ -90,9 +90,9 @@ export class CrewFooter {
 		].join(" • ");
 		const badges = this.data.badges?.length ? this.data.badges.map((badge) => `[${badge}]`).join(" ") : "";
 		this.cacheLines = [
-			this.theme.fg("dim", pad(truncate(firstParts.join(" • "), lineWidth, "..."), lineWidth)),
-			this.theme.fg("dim", pad(truncate(usageLine, lineWidth, "..."), lineWidth)),
-			this.theme.fg("dim", pad(truncate(badges, lineWidth, "..."), lineWidth)),
+			this.theme.fg("dim", pad(truncate(firstParts.join(" • "), lineWidth), lineWidth)),
+			this.theme.fg("dim", pad(truncate(usageLine, lineWidth), lineWidth)),
+			this.theme.fg("dim", pad(truncate(badges, lineWidth), lineWidth)),
 		];
 		this.cacheKey = key;
 		this.cacheWidth = width;

package/src/ui/crew-select-list.ts

@@ -86,7 +86,7 @@ export class CrewSelectList<T = string> {
 			const suffix = item.description ? this.theme.fg("dim", ` — ${item.description}`) : "";
 			const raw = `${prefix}${item.label}${suffix}`;
 			const line = index === this.selectedIndex ? this.theme.inverse?.(raw) ?? raw : raw;
-			lines.push(pad(truncate(line, width, "..."), Math.max(1, width)));
+			lines.push(pad(truncate(line, width), Math.max(1, width)));
 		}
 		if (hasBottom) lines.push(this.theme.fg("muted", `↓ ${this.items.length - (this.scrollOffset + slots)} more`));
 		return lines.slice(0, maxHeight);

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

@@ -6,6 +6,28 @@ import type { CrewAgentRecord } from "../../runtime/crew-agent-runtime.ts";
 import { formatCost } from "../../state/usage.ts";
 import { listLiveAgents, listLiveAgentsByWorkspace, type LiveAgentHandle } from "../../runtime/live-agent-manager.ts";
 import { computeLiveDurationMs } from "../live-duration.ts";
+import { visibleWidth } from "../../utils/visual.ts";
+
+/**
+ * Fixed visible widths for the per-agent numeric metrics (finding V-1).
+ * Right-aligning each field to a constant width stops the right edge of the
+ * stats block from jittering every tick as values change width
+ * (e.g. `9.9s`→`10.0s`, `950`→`1.0k`, `$0.9`→`$1.0`).
+ */
+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`
+
+/**
+ * Width-aware right-align (padStart) for a numeric metric so its column stays
+ * stable across ticks. Uses `visibleWidth` so wide/CJK glyphs never misalign
+ * the padding. Values wider than `width` are returned verbatim (no truncation)
+ * so outliers overflow gracefully instead of crashing the render.
+ */
+function alignMetric(value: string, width: number): string {
+	const gap = width - visibleWidth(value);
+	return gap > 0 ? " ".repeat(gap) + value : value;
+}
 
 /**
  * Returns true if this agent did real work (LLM call, tool use, or non-trivial duration).
@@ -89,12 +111,12 @@ export function renderAgentsPane(snapshot: RunUiSnapshot | undefined, options: R
 		const tokenTotal = (agent.usage?.input ?? 0) + (agent.usage?.output ?? 0) + (agent.usage?.cacheRead ?? 0) + (agent.usage?.cacheWrite ?? 0);
 		if (tokenTotal > 0) {
 			const tok = tokenTotal >= 1000 ? `${(tokenTotal / 1000).toFixed(1)}k` : `${tokenTotal}`;
-			stats.push(tok);
+			stats.push(alignMetric(tok, TOKENS_METRIC_WIDTH));
 		}
 		// Per-agent cost (Round 17 BS-1): the data is already on task.usage.cost;
 		// surface it live so the user sees $ burn per agent during a run.
 		if (agent.usage?.cost && agent.usage.cost > 0) {
-			stats.push(formatCost(agent.usage.cost));
+			stats.push(alignMetric(formatCost(agent.usage.cost), COST_METRIC_WIDTH));
 		}
 		if (liveHandle) {
 			// Round 23 (BUG 1): the duration math here was naive —
@@ -104,13 +126,13 @@ 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);
-			stats.push(`${(ms / 1000).toFixed(1)}s`);
+			stats.push(alignMetric(`${(ms / 1000).toFixed(1)}s`, DURATION_METRIC_WIDTH));
 			if (options.showModel !== false && liveHandle.modelName && liveHandle.modelName !== "default") {
 				stats.push(liveHandle.modelName);
 			}
 		} else if (agent.startedAt) {
 			const ms = Date.now() - new Date(agent.startedAt).getTime();
-			if (Number.isFinite(ms)) stats.push(`${(ms / 1000).toFixed(1)}s`);
+			if (Number.isFinite(ms)) stats.push(alignMetric(`${(ms / 1000).toFixed(1)}s`, DURATION_METRIC_WIDTH));
 		}
 
 		const statsStr = stats.length ? ` · ${stats.join(" ")}` : "";

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

@@ -40,4 +40,27 @@ export function renderCancellationPane(manifest: TeamRunManifest, tasks: TeamTas
 	}
 
 	return lines;
+}
+
+/**
+ * D-1 / L-2 — a one-line terminal-run reason for the dashboard detail row.
+ *
+ * Surfaces *why* a failed/cancelled/stopped run ended without forcing the
+ * user to switch panes. This also gives this module a real consumer (it was
+ * previously zero-importer dead code per the UI/UX review), wiring it in as
+ * the natural home for cancellation/failure reason display.
+ *
+ * Resolution order: structured `run.cancelled` event reason → first failed
+ * task's error → first policy-decision message.
+ */
+export function summarizeTerminalReason(
+	manifest: TeamRunManifest,
+	tasks: TeamTaskState[],
+	cancellationReason?: string,
+): string | undefined {
+	if (cancellationReason) return cancellationReason;
+	const failed = tasks.find((task) => task.status === "failed" && task.error);
+	if (failed?.error) return failed.error;
+	if (manifest.policyDecisions?.length) return manifest.policyDecisions[0]?.message;
+	return undefined;
 }

package/src/ui/keybinding-map.ts

@@ -26,6 +26,7 @@
 export const DASHBOARD_KEYS = {
 	close: ["q", "\u001b"],
 	select: ["\r", "\n", "s"],
+	help: ["?"],
 	root: {
 		summary: ["u"],
 		artifacts: ["a"],
@@ -67,6 +68,7 @@ export interface KeyBinding {
 
 export type DashboardKeyAction =
 	| "close"
+	| "help"
 	| "select"
 	| "summary"
 	| "artifacts"
@@ -112,6 +114,7 @@ export type DashboardKeyAction =
  */
 const BINDINGS: readonly KeyBinding[] = [
 	{ keys: DASHBOARD_KEYS.close, action: "close" },
+	{ keys: DASHBOARD_KEYS.help, action: "help" },
 	{ keys: DASHBOARD_KEYS.mailbox.openDetail, action: "mailbox-detail", pane: "mailbox" },
 	{ keys: DASHBOARD_KEYS.health.recovery, action: "health-recovery", pane: "health" },
 	{ keys: DASHBOARD_KEYS.health.killStale, action: "health-kill-stale", pane: "health" },
@@ -145,13 +148,14 @@ const BINDINGS: readonly KeyBinding[] = [
  * overlays. Derived from `DASHBOARD_KEYS` (the full key set) rather than from
  * `BINDINGS` (the dispatched subset) so overlay-handled keys stay reserved.
  *
- * @internal Currently unused outside this module but retained to document
- * intent and support future callers that need to know which keys the
- * dashboard ecosystem owns.
+ * @internal Consumed by `test/unit/keybinding-map.parity.test.ts` (asserts
+ * reserved-key membership) and the L2 dispatch smoke script. It is the
+ * canonical "keys the dashboard ecosystem owns" set — NOT dead code.
  */
 const KEY_RESERVED = new Set<string>([
 	...DASHBOARD_KEYS.close,
 	...DASHBOARD_KEYS.select,
+	...DASHBOARD_KEYS.help,
 	...Object.values(DASHBOARD_KEYS.root).flat(),
 	...Object.values(DASHBOARD_KEYS.pane).flat(),
 	...Object.values(DASHBOARD_KEYS.navigation).flat(),

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

@@ -8,6 +8,7 @@ import type { LiveAgentHandle } from "../runtime/live-agent-manager.ts";
 import { iconForStatus } from "./status-colors.ts";
 import { spinnerFrame } from "./spinner.ts";
 import type { CrewTheme } from "./theme-adapter.ts";
+import { pad, truncate } from "../utils/visual.ts";
 
 const CHROME_LINES = 6;
 const MIN_VIEWPORT = 3;
@@ -119,9 +120,8 @@ export class LiveConversationOverlay {
 		if (w < 6) return [];
 		const th = this.theme;
 		const innerW = w - 4;
-		const pad = (s: string, len: number) => s + " ".repeat(Math.max(0, len - s.length));
 		const row = (content: string) =>
-			th.fg("border", "│") + " " + pad(content.slice(0, innerW), innerW) + " " + th.fg("border", "│");
+			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)));

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

@@ -8,7 +8,7 @@ import { aggregateUsage, formatUsage } from "../state/usage.ts";
 import type { TeamTaskState } from "../state/types.ts";
 import { readJsonFileCoalesced } from "../utils/file-coalescer.ts";
 import { pad, truncate } from "../utils/visual.ts";
-import { iconForStatus } from "./status-colors.ts";
+import { colorizeStatusGlyphs, iconForStatus } from "./status-colors.ts";
 import type { CrewTheme } from "./theme-adapter.ts";
 import { asCrewTheme, subscribeThemeChange } from "./theme-adapter.ts";
 import { Box, Text } from "./layout-primitives.ts";
@@ -93,13 +93,11 @@ export class LiveRunSidebar {
 	}
 
 	private colorLine(line: string): string {
-		const iconColor = (icon: string): Parameters<CrewTheme["fg"]>[0] => {
-			if (icon === "✓") return "success";
-			if (icon === "✗") return "error";
-			if (icon === "■" || icon === "⏸") return "warning";
-			return "accent";
-		};
-		return line.replace(/[✓✗■⏸◦·▶]/g, (icon) => this.theme.fg(iconColor(icon), icon));
+		// F-1 / V-3: delegate to the shared glyph colorizer so ⏳ (waiting),
+		// ⚠ (needs_attention) and the braille spinner frames are colored
+		// consistently with the rest of the UI. The previous local map/regex
+		// omitted all three, leaving the most attention-demanding states uncolored.
+		return colorizeStatusGlyphs(line, this.theme);
 	}
 
 	invalidate(): void {
@@ -150,10 +148,17 @@ 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) {
+			// 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).
+			const TERMINAL_WITH_REASON = ["failed", "cancelled", "stopped"];
+			const reasonSuffix = TERMINAL_WITH_REASON.includes(run.status) && snapshot?.cancellationReason
+				? ` · ${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} · right default`, 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),
@@ -180,7 +185,9 @@ export class LiveRunSidebar {
 			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), border("╰", "─", "╯", 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.
 			// 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");
@@ -199,6 +206,7 @@ export class LiveRunSidebar {
 				clearTimeout(this.autoCloseTimeout);
 				this.autoCloseTimeout = undefined;
 			}
+			lines.push(border("╰", "─", "╯", w));
 			this.cachedLines = renderLines(lines.map((entry) => this.colorLine(entry)), w);
 			this.cachedSignature = signature;
 			this.cachedWidth = w;