pi-crew 0.9.5 → 0.9.8

package/src/skills/validate.ts

@@ -0,0 +1,267 @@
+/**
+ * SKILL.md frontmatter validation (L3 of deer-flow→pi-crew plan).
+ *
+ * Parses a SKILL.md's YAML frontmatter and validates it against the
+ * `ALLOWED_SKILL_PROPS` whitelist using HYBRID policy:
+ *   - HARD errors (missing/malformed `name`/`description`, type mismatches,
+ *     read/parse failures): EXCLUDE the skill from `discoverSkills()`.
+ *   - SOFT warnings (unknown props, missing `name` derived from directory):
+ *     KEEP the skill; surface via `getLastDiscoveryDiagnostics()`.
+ *
+ * YAML parsing uses the `yaml` package (^2.9.0). It is now a direct dep;
+ * before L3 it was only transitively available through
+ * `@earendil-works/pi-coding-agent`. Adding it as a direct dep is justified by:
+ *   - Replaces a fragile line-prefix parser that broke on multi-line folded
+ *     scalars (`description: >`), quoted strings, and nested YAML.
+ *   - Standard lib (eemeli/yaml), MIT, actively maintained.
+ *   - Already in the lockfile at the same version → zero install cost.
+ *   - Frontmatter is small and well-formed; YAML parsing cost is negligible.
+ *
+ * The validator runs once per skill at discovery. Discovery is already cached
+ * (`CACHE_TTL_MS = 30_000` in discover-skills.ts) so the validation cost is
+ * bounded regardless of how many skills exist.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import yaml from "yaml";
+
+/**
+ * Properties allowed in SKILL.md frontmatter.
+ *
+ * Why this list:
+ *   - `name`, `description` are the contract used by pi-crew's prompt
+ *     rendering (see src/runtime/skill-instructions.ts) and capability
+ *     inventory. Both are HARD-required.
+ *   - `license`, `allowed-tools`, `compatibility`, `version`, `author` are
+ *     common metadata; we surface but don't enforce content beyond type.
+ *   - `metadata` is a free-form key/value bag (mirrors deer-flow `validation.py`).
+ *
+ * Unknown props (e.g. bundled skills' `origin`, `triggers`) are SOFT-warned,
+ * not rejected — see HYBRID policy in the module docstring.
+ */
+export const ALLOWED_SKILL_PROPS = new Set<string>([
+	"name",
+	"description",
+	"license",
+	"allowed-tools",
+	"metadata",
+	"compatibility",
+	"version",
+	"author",
+]);
+
+/** Hyphen-case name regex (Anthropic Agent Skills spec compatible). */
+const NAME_REGEX = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+const NAME_MAX_LEN = 64;
+const DESCRIPTION_MAX_LEN = 1024;
+const VERSION_REGEX = /^\d+\.\d+(\.\d+)?(-[A-Za-z0-9.-]+)?$/;
+
+/**
+ * Structured error so callers (capability inventory, logs) can present
+ * actionable diagnostics instead of silently dropping malformed skills.
+ */
+export interface SkillValidationError {
+	/** Absolute path to the skill directory. */
+	path: string;
+	/** Field name (e.g. "name", "description", "<unknown-prop>") or "frontmatter" for parse errors. */
+	field: string;
+	/** Human-readable reason. Safe to surface in capability listings. */
+	reason: string;
+	/** Severity — "error" excludes the skill; "warn" keeps it. */
+	severity: "error" | "warn";
+}
+
+/**
+ * Validated manifest exposes the parsed frontmatter fields in a typed shape.
+ * Only present for valid skills; undefined for invalid ones.
+ */
+export interface ValidatedSkillManifest {
+	name: string;
+	description: string;
+	license?: string;
+	allowedTools?: string[];
+	metadata?: Record<string, unknown>;
+	compatibility?: string;
+	version?: string;
+	author?: string;
+}
+
+export interface ValidationResult {
+	ok: boolean;
+	errors: SkillValidationError[];
+	manifest?: ValidatedSkillManifest;
+}
+
+/**
+ * Parse YAML frontmatter from SKILL.md content.
+ *
+ * Returns an empty object when there is no frontmatter block. Parsing errors
+ * surface as `{ ok: false }` rather than throwing — discovery must remain
+ * exception-safe.
+ */
+export function parseSkillFrontmatter(
+	content: string,
+): { ok: true; data: Record<string, unknown> } | { ok: false; error: string } {
+	const match = /^---\r?\n([\s\S]*?)\r?\n---/.exec(content);
+	if (!match) return { ok: true, data: {} };
+	try {
+		const parsed = yaml.parse(match[1]);
+		if (parsed === null || parsed === undefined) return { ok: true, data: {} };
+		if (typeof parsed !== "object" || Array.isArray(parsed)) {
+			return { ok: false, error: "Frontmatter must be a YAML mapping, not a scalar or list." };
+		}
+		return { ok: true, data: parsed as Record<string, unknown> };
+	} catch (e) {
+		return { ok: false, error: `YAML parse error: ${(e as Error).message}` };
+	}
+}
+
+function hard(path: string, field: string, reason: string): SkillValidationError {
+	return { path, field, reason, severity: "error" };
+}
+
+function warn(path: string, field: string, reason: string): SkillValidationError {
+	return { path, field, reason, severity: "warn" };
+}
+
+/**
+ * Validate a single skill's frontmatter.
+ *
+ * @param skillDir Absolute path to the skill directory (must contain SKILL.md).
+ * @returns ValidationResult — `ok` is true when there are no HARD errors.
+ *          `errors[]` always lists ALL violations (HARD + SOFT).
+ *
+ * Back-compat: when `name` is missing from frontmatter, the validator
+ * DERIVES it from the directory name and emits a SOFT warning. Bundled
+ * pi-crew skills always set `name` explicitly, so the warning is informational.
+ */
+export function validateSkillFrontmatter(skillDir: string): ValidationResult {
+	const errors: SkillValidationError[] = [];
+	const skillMdPath = path.join(skillDir, "SKILL.md");
+	const derivedName = path.basename(skillDir);
+
+	let content: string;
+	try {
+		content = fs.readFileSync(skillMdPath, "utf-8");
+	} catch (e) {
+		errors.push(hard(skillDir, "SKILL.md", `Cannot read SKILL.md: ${(e as Error).message}`));
+		return { ok: false, errors };
+	}
+
+	const parsed = parseSkillFrontmatter(content);
+	if (!parsed.ok) {
+		errors.push(hard(skillDir, "frontmatter", parsed.error));
+		return { ok: false, errors };
+	}
+
+	const data = parsed.data;
+
+	// No frontmatter at all → back-compat: derive everything from the
+	// directory. Pre-L3 skills shipped without frontmatter and we don't want
+	// to regress them. Surface a SOFT warning so authors know to add YAML.
+	if (Object.keys(data).length === 0) {
+		errors.push(warn(skillDir, "frontmatter", "No frontmatter block; deriving name from directory and leaving description empty."));
+		return {
+			ok: true,
+			errors,
+			manifest: { name: derivedName, description: "" },
+		};
+	}
+
+	// ── name: HARD if type/length/regex bad; SOFT if missing (derive from dir)
+	const nameRaw = data.name;
+	let resolvedName = derivedName;
+	if (nameRaw === undefined || nameRaw === null) {
+		errors.push(warn(skillDir, "name", `Frontmatter 'name' missing; using directory name "${derivedName}" as fallback. Add explicit 'name' to silence this.`));
+	} else if (typeof nameRaw !== "string") {
+		errors.push(hard(skillDir, "name", `'name' must be a string, got ${typeof nameRaw}.`));
+	} else if (nameRaw.length === 0) {
+		errors.push(hard(skillDir, "name", "'name' is empty."));
+	} else if (nameRaw.length > NAME_MAX_LEN) {
+		errors.push(hard(skillDir, "name", `'name' exceeds ${NAME_MAX_LEN} chars (got ${nameRaw.length}).`));
+	} else if (!NAME_REGEX.test(nameRaw)) {
+		errors.push(hard(skillDir, "name", `'name' must be hyphen-case lowercase (a-z, 0-9, single hyphens); got "${nameRaw}".`));
+	} else {
+		resolvedName = nameRaw;
+	}
+
+	// ── description: HARD required
+	const descRaw = data.description;
+	if (descRaw === undefined || descRaw === null) {
+		errors.push(hard(skillDir, "description", "Required field 'description' is missing."));
+	} else if (typeof descRaw !== "string") {
+		errors.push(hard(skillDir, "description", `'description' must be a string, got ${typeof descRaw}.`));
+	} else if (descRaw.length > DESCRIPTION_MAX_LEN) {
+		errors.push(hard(skillDir, "description", `'description' exceeds ${DESCRIPTION_MAX_LEN} chars (got ${descRaw.length}).`));
+	} else if (descRaw.includes("<") || descRaw.includes(">")) {
+		errors.push(hard(skillDir, "description", `'description' must not contain '<' or '>' (prompt-safety).`));
+	}
+
+	// ── OPTIONAL: license
+	if (data.license !== undefined && typeof data.license !== "string") {
+		errors.push(hard(skillDir, "license", `'license' must be a string.`));
+	}
+
+	// ── OPTIONAL: allowed-tools
+	if (data["allowed-tools"] !== undefined) {
+		const at = data["allowed-tools"];
+		if (!Array.isArray(at) || !at.every((x) => typeof x === "string")) {
+			errors.push(hard(skillDir, "allowed-tools", `'allowed-tools' must be an array of strings.`));
+		}
+	}
+
+	// ── OPTIONAL: metadata
+	if (data.metadata !== undefined) {
+		const m = data.metadata;
+		if (typeof m !== "object" || m === null || Array.isArray(m)) {
+			errors.push(hard(skillDir, "metadata", `'metadata' must be an object.`));
+		}
+	}
+
+	// ── OPTIONAL: compatibility
+	if (data.compatibility !== undefined && typeof data.compatibility !== "string") {
+		errors.push(hard(skillDir, "compatibility", `'compatibility' must be a string.`));
+	}
+
+	// ── OPTIONAL: version
+	if (data.version !== undefined) {
+		if (typeof data.version !== "string" || !VERSION_REGEX.test(data.version)) {
+			errors.push(hard(skillDir, "version", `'version' must be a semver string (e.g. "1.2.3" or "1.2.3-beta.1"); got "${String(data.version)}".`));
+		}
+	}
+
+	// ── OPTIONAL: author
+	if (data.author !== undefined && typeof data.author !== "string") {
+		errors.push(hard(skillDir, "author", `'author' must be a string.`));
+	}
+
+	// ── UNKNOWN PROPS: SOFT warn (HYBRID policy)
+	for (const key of Object.keys(data)) {
+		if (!ALLOWED_SKILL_PROPS.has(key)) {
+			errors.push(warn(skillDir, `<unknown-prop:${key}>`, `Unknown property '${key}' is not in the whitelist; keeping for forward-compat.`));
+		}
+	}
+
+	// ── Result: ok iff no HARD errors
+	const hasHardError = errors.some((e) => e.severity === "error");
+	if (!hasHardError) {
+		const manifest: ValidatedSkillManifest = {
+			name: resolvedName,
+			description: typeof data.description === "string" ? data.description : "",
+		};
+		if (typeof data.license === "string") manifest.license = data.license;
+		if (Array.isArray(data["allowed-tools"])) {
+			manifest.allowedTools = (data["allowed-tools"] as unknown[]).filter((x) => typeof x === "string") as string[];
+		}
+		if (typeof data.metadata === "object" && data.metadata !== null && !Array.isArray(data.metadata)) {
+			manifest.metadata = data.metadata as Record<string, unknown>;
+		}
+		if (typeof data.compatibility === "string") manifest.compatibility = data.compatibility;
+		if (typeof data.version === "string") manifest.version = data.version;
+		if (typeof data.author === "string") manifest.author = data.author;
+		return { ok: true, errors, manifest };
+	}
+
+	return { ok: false, errors };
+}

package/src/state/contracts.ts

@@ -91,6 +91,7 @@ const TEAM_EVENT_TYPES = [
 	"dwf.phase_completed",
 	"dwf.completed",
 	"dwf.failed",
+	"dwf.log",
 ] as const;
 export type TeamEventType = typeof TEAM_EVENT_TYPES[number];
 

package/src/state/state-store.ts

@@ -228,6 +228,8 @@ export function createRunManifest(params: {
 	workspaceMode?: "single" | "worktree";
 	ownerSessionId?: string;
 	runKind?: "team-run" | "goal-loop" | "dynamic-workflow";
+	/** round-14 P1-5: typed workflow arguments for .dwf.ts scripts (ctx.args<T>()). */
+	args?: unknown;
 }): { manifest: TeamRunManifest; tasks: TeamTaskState[]; paths: RunPaths } {
 	const paths = createRunPaths(params.cwd);
 	const now = new Date().toISOString();
@@ -251,6 +253,7 @@ export function createRunManifest(params: {
 		artifacts: [],
 		...(params.ownerSessionId ? { ownerSessionId: params.ownerSessionId } : {}),
 		runKind: params.runKind ?? "team-run",
+		...(params.args !== undefined ? { args: params.args } : {}),
 	};
 	fs.mkdirSync(paths.stateRoot, { recursive: true });
 	fs.mkdirSync(paths.artifactsRoot, { recursive: true });

package/src/state/types.ts

@@ -116,6 +116,13 @@ export interface WorkerExitStatus {
 	signal?: string;
 	cleanupErrors: string[];
 	finalDrainMs: number;
+	/** Phase-0 diagnostic (HB-003a): final-drain race state for the exit-null
+	 *  disableTools bug. Optional + read-only — absent when no drain timer was
+	 *  ever armed. Phase 1 will use `finalDrainArmed` to decide whether a
+	 *  signal-death (exitCode=null) should be treated as a forced final drain. */
+	finalDrainArmed?: boolean;
+	forcedFinalDrain?: boolean;
+	finalDrainFiredMonotonicMs?: number;
 }
 
 export interface OperationTerminalEvidence {
@@ -185,6 +192,8 @@ export interface TeamRunManifest {
 	runConfig?: unknown;
 	/** Background dispatch discriminator. Default "team-run" runs executeTeamRun; "goal-loop" / "dynamic-workflow" dispatch to their respective runners. Absent = "team-run" for backward compatibility. */
 	runKind?: "team-run" | "goal-loop" | "dynamic-workflow";
+	/** round-14 P1-5: typed workflow arguments accessible in .dwf.ts scripts via ctx.args<T>(). Any JSON value; default {} when unset. */
+	args?: unknown;
 	summary?: string;
 	policyDecisions?: PolicyDecision[];
 }

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

@@ -1,5 +1,6 @@
 import type { RunUiSnapshot } from "../snapshot-types.ts";
 import { computePhaseProgress, formatPhaseProgressLine } from "../../runtime/phase-progress.ts";
+import { renderDwfPhaseLines } from "../dwf-phase-display.ts";
 
 export function renderProgressPane(snapshot: RunUiSnapshot | undefined): string[] {
 	if (!snapshot) return ["Progress pane: snapshot unavailable"];
@@ -16,8 +17,12 @@ export function renderProgressPane(snapshot: RunUiSnapshot | undefined): string[
 		})
 		: [];
 	const phaseHeader = phaseLines.length > 0 ? [formatPhaseProgressLine(runProgress), ...phaseLines] : [];
+	// DWF logical phases (round-15 P1-4): derived from dwf.phase_* events.
+	// Null/absent for non-DWF runs → zero visible change.
+	const dwfPhaseLines = snapshot.dwfPhaseState ? renderDwfPhaseLines(snapshot.dwfPhaseState) : [];
 	return [
 		`Progress pane: ${progress.completed}/${progress.total} completed · running=${progress.running} queued=${progress.queued} failed=${progress.failed}`,
+		...dwfPhaseLines,
 		...phaseHeader,
 		...cancellationLine,
 		...groupJoinLines,

package/src/ui/dwf-phase-display.ts

@@ -0,0 +1,151 @@
+/**
+ * DWF phase display — pure functions for extracting DWF phase state from the
+ * run's recent event window and rendering phase markers (▶/✓/⏸) in the
+ * progress pane.
+ *
+ * round-15 (P1-4). These functions are side-effect free and perform no I/O;
+ * they derive phase state entirely from the `recentEvents` slice already
+ * tailed by `run-snapshot-cache.ts`. Non-DWF runs (no `dwf.phase_*` events)
+ * yield `null`, so the progress pane stays unchanged for them.
+ */
+import type { TeamEvent } from "../state/event-log.ts";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export type DwfPhaseStatus = "running" | "completed" | "pending";
+
+export interface DwfPhaseEntry {
+	/** Phase title as passed to `ctx.phase(title)`. */
+	name: string;
+	/** Derived lifecycle status for display. */
+	status: DwfPhaseStatus;
+}
+
+export interface DwfPhaseState {
+	/** Ordered list of phases seen in the event window (first-seen order). */
+	phases: DwfPhaseEntry[];
+	/** Name of the currently running phase, or null if all are completed. */
+	currentPhase: string | null;
+}
+
+export interface RenderDwfPhaseOptions {
+	/** When true, render ASCII fallback markers instead of Unicode glyphs. */
+	ascii?: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Markers
+// ---------------------------------------------------------------------------
+
+// Unicode markers — consistent with the ▸/● glyphs already used in the dashboard.
+const MARKER_RUNNING = "▶";
+const MARKER_COMPLETED = "✓";
+const MARKER_PENDING = "⏸";
+
+// ASCII fallbacks for terminals that mis-render the Unicode glyphs above.
+const MARKER_RUNNING_ASCII = "[>]";
+const MARKER_COMPLETED_ASCII = "[v]";
+const MARKER_PENDING_ASCII = "[ ]";
+
+const DWF_PHASE_HEADER = "  ── DWF Phases ──";
+
+function markerFor(status: DwfPhaseStatus, ascii: boolean): string {
+	if (ascii) {
+		if (status === "running") return MARKER_RUNNING_ASCII;
+		if (status === "completed") return MARKER_COMPLETED_ASCII;
+		return MARKER_PENDING_ASCII;
+	}
+	if (status === "running") return MARKER_RUNNING;
+	if (status === "completed") return MARKER_COMPLETED;
+	return MARKER_PENDING;
+}
+
+// ---------------------------------------------------------------------------
+// Extraction
+// ---------------------------------------------------------------------------
+
+function phaseNameFrom(event: TeamEvent): string | undefined {
+	const phase = event.data?.phase;
+	return typeof phase === "string" && phase.length > 0 ? phase : undefined;
+}
+
+/**
+ * Derive DWF phase state from a (chronological) event window.
+ *
+ * Returns `null` when the window contains no `dwf.phase_started` /
+ * `dwf.phase_completed` events — i.e. a non-DWF run — so callers can short
+ * circuit phase rendering entirely.
+ *
+ * Because the window is bounded, the oldest phase events may have scrolled
+ * off. A phase whose `dwf.phase_started` scrolled off but whose
+ * `dwf.phase_completed` is still visible is still tracked (as completed). A
+ * phase that started but whose completion scrolled off and which is not the
+ * current phase is shown as `pending` (indeterminate).
+ */
+export function extractDwfPhaseState(events: TeamEvent[]): DwfPhaseState | null {
+	const order: string[] = [];
+	const seen = new Set<string>();
+	const completed = new Set<string>();
+	let currentPhase: string | null = null;
+
+	const remember = (phase: string): void => {
+		if (!seen.has(phase)) {
+			seen.add(phase);
+			order.push(phase);
+		}
+	};
+
+	for (const event of events) {
+		if (event.type === "dwf.phase_started") {
+			const phase = phaseNameFrom(event);
+			if (phase === undefined) continue;
+			remember(phase);
+			// The most recent phase_started marks the running phase.
+			currentPhase = phase;
+		} else if (event.type === "dwf.phase_completed") {
+			const phase = phaseNameFrom(event);
+			if (phase === undefined) continue;
+			remember(phase);
+			completed.add(phase);
+			// If the phase just closed was the running one, it is no longer running.
+			if (phase === currentPhase) {
+				currentPhase = null;
+			}
+		}
+	}
+
+	if (order.length === 0) return null;
+
+	const phases: DwfPhaseEntry[] = order.map((name) => {
+		if (name === currentPhase) return { name, status: "running" as const };
+		if (completed.has(name)) return { name, status: "completed" as const };
+		return { name, status: "pending" as const };
+	});
+
+	return { phases, currentPhase };
+}
+
+// ---------------------------------------------------------------------------
+// Rendering
+// ---------------------------------------------------------------------------
+
+/**
+ * Render phase marker lines for the progress pane.
+ *
+ * - One line per phase: `  ▶ Phase: Scan`, `  ✓ Phase: Scan`, `  ⏸ Phase: Review`.
+ * - A grouping header is emitted only when more than one phase is present.
+ * - When `options.ascii` is true, ASCII fallback markers are used.
+ *
+ * Always returns a non-empty array (the caller guarantees a non-null state).
+ */
+export function renderDwfPhaseLines(state: DwfPhaseState, options?: RenderDwfPhaseOptions): string[] {
+	const ascii = options?.ascii === true;
+	const lines: string[] = [];
+	if (state.phases.length > 1) lines.push(DWF_PHASE_HEADER);
+	for (const entry of state.phases) {
+		lines.push(`  ${markerFor(entry.status, ascii)} Phase: ${entry.name}`);
+	}
+	return lines;
+}

package/src/ui/keybinding-map.ts

@@ -1,3 +1,28 @@
+/**
+ * Dashboard keybinding map (L2 refactor: data-driven dispatch).
+ *
+ * Before L2 this module exposed `DASHBOARD_KEYS` (a data table) but dispatched
+ * via a 30-line `if (includes(...)) return "..."` chain — adding a key meant
+ * editing BOTH the table AND the dispatch, a DRY violation. L2 collapses the
+ * dispatch into a single `for (const b of BINDINGS)` loop driven by the
+ * `BINDINGS` table below. `DASHBOARD_KEYS` is retained as the raw key data so
+ * existing imports and the dead-but-intentional `KEY_RESERVED` set keep working.
+ *
+ * Recalibration vs. the original L2 plan: the plan also called for an
+ * `inTextInput` guard to prevent letter-key leaks into TUI text inputs.
+ * Verified during implementation that this is NOT needed — overlays are
+ * mutually exclusive and each has its own `handleInput`. `mailbox-compose-overlay.ts:111`
+ * captures every single-char key via `appendText(data)` and never delegates to
+ * `dashboardActionForKey`, so there is no leak path. Adding the guard would
+ * complicate the API (`run-dashboard.ts:485` has no text-input state to pass)
+ * for zero benefit. The input-guard half of L2 is therefore intentionally
+ * skipped; only the DRY/data-driven dispatch refactor landed.
+ *
+ * Origin pattern: deer-flow `frontend/src/components/workspace/command-palette.tsx:39-50`
+ * drives shortcuts from a single data array consumed by one loop in
+ * `use-global-shortcuts.ts:38-61`.
+ */
+
 export const DASHBOARD_KEYS = {
 	close: ["q", "\u001b"],
 	select: ["\r", "\n", "s"],
@@ -21,20 +46,23 @@ export const DASHBOARD_KEYS = {
 	notification: { dismissAll: ["H"] },
 } as const;
 
-/** @internal */
-const KEY_RESERVED = new Set<string>([
-	...DASHBOARD_KEYS.close,
-	...DASHBOARD_KEYS.select,
-	...Object.values(DASHBOARD_KEYS.root).flat(),
-	...Object.values(DASHBOARD_KEYS.pane).flat(),
-	...Object.values(DASHBOARD_KEYS.navigation).flat(),
-	...Object.values(DASHBOARD_KEYS.mailbox).flat(),
-	...Object.values(DASHBOARD_KEYS.health).flat(),
-	...Object.values(DASHBOARD_KEYS.notification).flat(),
-]);
+/**
+ * Pane identifiers that can scope a binding. `undefined` means the binding
+ * fires in every pane.
+ */
+export type ActivePane = "agents" | "progress" | "mailbox" | "output" | "health" | "metrics";
 
-function includes(values: readonly string[], data: string): boolean {
-	return values.includes(data);
+/**
+ * A single keybinding: the keys that trigger it, the action it produces, and
+ * an optional pane restriction. The dispatch loop returns the FIRST matching
+ * binding, so table ORDER IS SIGNIFICANT and must mirror the old if-chain
+ * precedence (pane-specific overrides before their generic competitors).
+ */
+export interface KeyBinding {
+	readonly keys: readonly string[];
+	readonly action: DashboardKeyAction;
+	/** When set, the binding only fires when `activePane === pane`. */
+	readonly pane?: ActivePane;
 }
 
 export type DashboardKeyAction =
@@ -65,34 +93,93 @@ export type DashboardKeyAction =
 	| "health-diagnostic-export"
 	| "notifications-dismiss";
 
-export function dashboardActionForKey(data: string, activePane?: "agents" | "progress" | "mailbox" | "output" | "health" | "metrics"): DashboardKeyAction | undefined {
-	if (includes(DASHBOARD_KEYS.close, data)) return "close";
-	if (activePane === "mailbox" && includes(DASHBOARD_KEYS.mailbox.openDetail, data)) return "mailbox-detail";
-	if (activePane === "health") {
-		if (includes(DASHBOARD_KEYS.health.recovery, data)) return "health-recovery";
-		if (includes(DASHBOARD_KEYS.health.killStale, data)) return "health-kill-stale";
-		if (includes(DASHBOARD_KEYS.health.diagnosticExport, data)) return "health-diagnostic-export";
+/**
+ * The dispatch table. ORDER MATTERS — first match wins.
+ *
+ * Precedence notes (must match the pre-L2 if-chain exactly):
+ *   1. `close` always wins (q / Esc).
+ *   2. `mailbox-detail` (\r, \n) is pane-scoped to mailbox and MUST precede
+ *      `select` (which also binds \r, \n) so Enter opens the detail instead of
+ *      triggering select while in the mailbox pane.
+ *   3. `health-*` are pane-scoped to health.
+ *   4. `notifications-dismiss` (H) is global.
+ *   5. `select`, then the root actions, pane switches, and navigation.
+ *
+ * NOTE: mailbox action keys A/N/C/P/X (ack/nudge/compose/preview/ackAll) are
+ * intentionally NOT in this table. They live in `DASHBOARD_KEYS.mailbox` for
+ * reservation but are handled by the mailbox overlay's own `handleInput`,
+ * not by the dashboard dispatch. Adding them here would change behavior.
+ */
+const BINDINGS: readonly KeyBinding[] = [
+	{ keys: DASHBOARD_KEYS.close, action: "close" },
+	{ 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" },
+	{ keys: DASHBOARD_KEYS.health.diagnosticExport, action: "health-diagnostic-export", pane: "health" },
+	{ keys: DASHBOARD_KEYS.notification.dismissAll, action: "notifications-dismiss" },
+	{ keys: DASHBOARD_KEYS.select, action: "select" },
+	{ keys: DASHBOARD_KEYS.root.summary, action: "summary" },
+	{ keys: DASHBOARD_KEYS.root.artifacts, action: "artifacts" },
+	{ keys: DASHBOARD_KEYS.root.api, action: "api" },
+	{ keys: DASHBOARD_KEYS.root.agents, action: "agents" },
+	{ keys: DASHBOARD_KEYS.root.mailbox, action: "mailbox" },
+	{ keys: DASHBOARD_KEYS.root.events, action: "events" },
+	{ keys: DASHBOARD_KEYS.root.output, action: "output" },
+	{ keys: DASHBOARD_KEYS.root.transcript, action: "transcript" },
+	{ keys: DASHBOARD_KEYS.root.liveConversation, action: "live-conversation" },
+	{ keys: DASHBOARD_KEYS.root.reload, action: "reload" },
+	{ keys: DASHBOARD_KEYS.root.progressToggle, action: "progressToggle" },
+	{ keys: DASHBOARD_KEYS.pane.agents, action: "pane-agents" },
+	{ keys: DASHBOARD_KEYS.pane.progress, action: "pane-progress" },
+	{ keys: DASHBOARD_KEYS.pane.mailbox, action: "pane-mailbox" },
+	{ keys: DASHBOARD_KEYS.pane.output, action: "pane-output" },
+	{ keys: DASHBOARD_KEYS.pane.health, action: "pane-health" },
+	{ keys: DASHBOARD_KEYS.pane.metrics, action: "pane-metrics" },
+	{ keys: DASHBOARD_KEYS.navigation.up, action: "up" },
+	{ keys: DASHBOARD_KEYS.navigation.down, action: "down" },
+];
+
+/**
+ * Reserved keys — every key the dashboard claims, including mailbox/health
+ * action keys that are NOT dispatched here but are handled by their own
+ * 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.
+ */
+const KEY_RESERVED = new Set<string>([
+	...DASHBOARD_KEYS.close,
+	...DASHBOARD_KEYS.select,
+	...Object.values(DASHBOARD_KEYS.root).flat(),
+	...Object.values(DASHBOARD_KEYS.pane).flat(),
+	...Object.values(DASHBOARD_KEYS.navigation).flat(),
+	...Object.values(DASHBOARD_KEYS.mailbox).flat(),
+	...Object.values(DASHBOARD_KEYS.health).flat(),
+	...Object.values(DASHBOARD_KEYS.notification).flat(),
+]);
+
+export { KEY_RESERVED };
+
+/**
+ * Resolve a raw input `data` string to a dashboard action.
+ *
+ * Data-driven dispatch: iterates `BINDINGS` in order and returns the action of
+ * the first binding whose `keys` contain `data` and whose optional `pane`
+ * restriction matches `activePane`. Behavior is identical to the pre-L2
+ * if-chain (verified by `test/unit/keybinding-map.parity.test.ts`).
+ *
+ * @param data Raw key input (single char or escape sequence).
+ * @param activePane Currently focused pane; pane-scoped bindings only fire
+ *                   when this matches. `undefined` disables all pane-scoped
+ *                   bindings (matching the old behavior where omitting the
+ *                   arg skipped the `activePane === ...` branches).
+ */
+export function dashboardActionForKey(data: string, activePane?: ActivePane): DashboardKeyAction | undefined {
+	for (const binding of BINDINGS) {
+		if (binding.pane !== undefined && binding.pane !== activePane) continue;
+		if (binding.keys.includes(data)) return binding.action;
 	}
-	if (includes(DASHBOARD_KEYS.notification.dismissAll, data)) return "notifications-dismiss";
-	if (includes(DASHBOARD_KEYS.select, data)) return "select";
-	if (includes(DASHBOARD_KEYS.root.summary, data)) return "summary";
-	if (includes(DASHBOARD_KEYS.root.artifacts, data)) return "artifacts";
-	if (includes(DASHBOARD_KEYS.root.api, data)) return "api";
-	if (includes(DASHBOARD_KEYS.root.agents, data)) return "agents";
-	if (includes(DASHBOARD_KEYS.root.mailbox, data)) return "mailbox";
-	if (includes(DASHBOARD_KEYS.root.events, data)) return "events";
-	if (includes(DASHBOARD_KEYS.root.output, data)) return "output";
-	if (includes(DASHBOARD_KEYS.root.transcript, data)) return "transcript";
-	if (includes(DASHBOARD_KEYS.root.liveConversation, data)) return "live-conversation";
-	if (includes(DASHBOARD_KEYS.root.reload, data)) return "reload";
-	if (includes(DASHBOARD_KEYS.root.progressToggle, data)) return "progressToggle";
-	if (includes(DASHBOARD_KEYS.pane.agents, data)) return "pane-agents";
-	if (includes(DASHBOARD_KEYS.pane.progress, data)) return "pane-progress";
-	if (includes(DASHBOARD_KEYS.pane.mailbox, data)) return "pane-mailbox";
-	if (includes(DASHBOARD_KEYS.pane.output, data)) return "pane-output";
-	if (includes(DASHBOARD_KEYS.pane.health, data)) return "pane-health";
-	if (includes(DASHBOARD_KEYS.pane.metrics, data)) return "pane-metrics";
-	if (includes(DASHBOARD_KEYS.navigation.up, data)) return "up";
-	if (includes(DASHBOARD_KEYS.navigation.down, data)) return "down";
 	return undefined;
 }