pi-crew 0.9.68 → 0.10.1

package/src/state/types.ts

@@ -1,6 +1,7 @@
 import type { CrewAgentProgress } from "../runtime/crew-agent-runtime.ts";
 import type { WorkerHeartbeatState } from "../runtime/heartbeat/worker-heartbeat.ts";
 import type { CrashClass } from "../runtime/recovery/crash-classification.ts";
+import type { FatalFsCause } from "../utils/fs-errno.ts";
 import type { TeamRunStatus, TeamTaskStatus } from "./contracts.ts";
 import type { TaskClaimState } from "./coordination/task-claims.ts";
 import type { CoherenceMark, RolloutEntry } from "./decision-ledger.ts";
@@ -55,6 +56,73 @@ export interface TaskOutputSchema {
 	example?: string;
 }
 
+export type SpecPriority = "must" | "should" | "could";
+
+/** T4/R6 (ADR-6 §1): workspace-level spec record — state/specs/<id>.json.
+ *  Revision machinery mirrors ADR-4 §1 PlanRecord (append-only revision list,
+ *  copy-forward linkage, stable requirement/acceptance ids). */
+export interface SpecRecord {
+	id: string;
+	version: number;
+	revisionOf?: number;
+	title: string;
+	requirements: Array<{ id: string; text: string; priority: SpecPriority }>;
+	acceptance: Array<{
+		id: string;
+		requirementId: string;
+		/** Free-text description of what counts as evidence (non-strict). */
+		check: string;
+		/** Strict mode (ADR-6 §4): machine-checkable form. */
+		command?: string;
+		expectedDigest?: string;
+		expectedExitCode?: number;
+		idempotent?: boolean;
+	}>;
+	source: { kind: "manual" | "generated"; by?: string; from?: string };
+	/** INFORMATIONAL copy of the store-mint provenance sidecar — the strict
+	 *  gate NEVER trusts this field alone (ADR-6 §4 provenance enforcement). */
+	trusted?: boolean;
+}
+
+/** Immutable per-task freeze (ADR-6 §1): embedded into the TaskPacket at
+ *  dispatch; the strict gate executes ONLY snapshot-frozen commands. */
+export interface SpecSnapshotItem {
+	requirement: SpecRecord["requirements"][number];
+	acceptance: SpecRecord["acceptance"][number];
+}
+
+export interface SpecSnapshot {
+	specId: string;
+	version: number;
+	frozenAt: string;
+	/** Provenance v2 (ADR-6 §4 + erratum): trust decided ONCE at freeze from
+	 *  the user-store digest sidecar; the strict gate reads only this frozen
+	 *  bit — post-freeze mint/delete cannot affect a running task. */
+	trustedAtFreeze: boolean;
+	items: SpecSnapshotItem[];
+}
+
+/** T4/R6 (ADR-6 §3): non-strict coverage-gate report persisted on the task.
+ *  Non-strict NEVER blocks — gaps surface as the `unverified` badge only. */
+export interface SpecGateResult {
+	/** "coverage" = non-strict (§3); "strict" arrives with the §4 sandbox. */
+	mode: "coverage" | "strict";
+	/** false for spec-less tasks — gate not applicable (regression guard). */
+	applicable: boolean;
+	footerPresent: boolean;
+	/** Cited ids in citation order (duplicates preserved). */
+	citedIds: string[];
+	/** Must-acceptance ids NOT cited — mechanically-detectable gap. */
+	missingMustIds: string[];
+	/** Cited ids that exist in no snapshot — fabrication signal (§2). */
+	unknownIds: string[];
+	/** Set ONLY on mechanically-detectable gaps (missing footer / missing
+	 *  must-ids / unknown ids). Full-coverage fabrication passes with NO badge. */
+	badge?: "unverified";
+	/** acceptanceId → one-line evidence text (verifier advisory input, §5). */
+	evidence: Record<string, string>;
+}
+
 export interface TaskPacket {
 	objective: string;
 	scope: TaskScope;
@@ -70,6 +138,17 @@ export interface TaskPacket {
 	expectedArtifacts: string[];
 	verification: VerificationContract;
 	outputSchema?: TaskOutputSchema;
+	/** T4/R6 (ADR-6): workspace spec ids this task is held to (frozen below). */
+	specRefs?: string[];
+	/** T4/R6 (ADR-6 §7): strict mode — coverage AND machine-check (§4). */
+	specStrict?: boolean;
+	/** Declared specRefs that resolved to NO record at freeze (typo / not
+	 *  imported / corrupted). Non-strict: unverified badge. Strict: the gate
+	 *  fails — a strict workflow must never silently degrade to ungated. */
+	unresolvedSpecRefs?: string[];
+	/** Frozen snapshots embedded at dispatch — later spec edits never rewrite
+	 *  what a running task was held to. */
+	specSnapshots?: SpecSnapshot[];
 }
 
 export type PolicyDecisionAction = "retry" | "reassign" | "escalate" | "block" | "notify" | "cleanup" | "closeout" | "fail";
@@ -164,6 +243,61 @@ export interface PlanApprovalState {
 }
 
 export type CrewActivityState = "active" | "active_long_running" | "needs_attention" | "stale";
+
+/** T2/R4 (ADR-4 docs/decisions/2026-08-17-plan-object.md §1): status vocabulary
+ *  shared by plan phases and items. `dropped` marks items removed by a re-plan
+ *  revision (kept for traceability + diff, never re-dispatched). */
+export type PlanItemStatus = "pending" | "active" | "done" | "dropped";
+
+export interface PlanPhaseRecord {
+	id: string;
+	title: string;
+	itemIds: string[];
+	status: PlanItemStatus;
+}
+
+export interface PlanItemRecord {
+	/** Stable across revisions (ADR-4 §3 producer contract) — the scheduler
+	 *  copies carried-over linkage forward at revision switch. */
+	id: string;
+	/** External reference (e.g. tagged section id in the source plan doc). */
+	ref?: string;
+	title: string;
+	/** Scheduler-owned (single writer, inside the run lock — ADR-4 §3).
+	 *  Producers NEVER set taskIds. */
+	taskIds: string[];
+	/** R6/T4 forward hook; T2 writes it empty (ADR-4 §1). */
+	specIds: string[];
+	acceptance: string[];
+	status: PlanItemStatus;
+}
+
+/** Plan-record side of the approval gate. Vocabulary note (ADR-4 §8): the
+ *  manifest side keeps `PlanApprovalState` ("cancelled" for deny); the record
+ *  side uses "rejected" — `plans reject` dual-writes both. */
+export interface PlanApprovalRecord {
+	status: "pending" | "approved" | "rejected";
+	by?: string;
+	at: string;
+	planVersion: number;
+}
+
+/** One revision in the append-only list persisted at
+ *  `<stateRoot>/plans/plans.json` (plan-store.ts). History is never mutated in
+ *  place — EXCEPT the current revision's `items[].taskIds`, the scheduler's
+ *  single-writer linkage field (ADR-4 §3). */
+export interface PlanRecord {
+	id: string;
+	runId: string;
+	version: number;
+	revisionOf?: { id: string; version: number };
+	title: string;
+	phases: PlanPhaseRecord[];
+	items: PlanItemRecord[];
+	approval?: PlanApprovalRecord;
+	createdAt: string;
+	authorTaskId?: string;
+}
 export type CrewAttentionReason = "idle" | "tool_failures" | "completion_guard" | "heartbeat_stale" | "plan_approval_pending";
 
 export interface CrewAttentionEventData {
@@ -226,7 +360,24 @@ export interface TeamRunManifest {
 	eventsPath: string;
 	artifacts: ArtifactDescriptor[];
 	async?: AsyncRunState;
+	/** @deprecated-plan-pointer T2/R4 (ADR-4 §2): dual-write era — PlanRecord at
+	 *  `<stateRoot>/plans/plans.json` is authoritative; this field is kept (never
+	 *  dropped) as the pre-v2 fallback and legacy UI surface. Deprecate-only. */
 	planApproval?: PlanApprovalState;
+	/** T2/R4 (ADR-4 §2): pointer to the CURRENT plan revision in
+	 *  `<stateRoot>/plans/plans.json`. Plan-record-first readers fall back to
+	 *  `planApproval` above when absent or no record exists (dual-read migration;
+	 *  the manifest field is deprecated, never dropped). */
+	plan?: { id: string; version: number };
+	/** WP-2/R2 (ADR-0 item 3): run-level park pointer while a worker is blocked
+	 *  in the `ask` tool. Purely additive coordination state — `status` above is
+	 *  NEVER flipped to express waiting (the run stays "running": registry entry,
+	 *  sidebar visibility and live-executor.isCurrent() all preserved). */
+	waitState?: {
+		taskId: string;
+		questionId: string;
+		askedAt: string;
+	};
 	/** Pi session that created the run, when available. Used to prevent cross-session destructive actions. */
 	ownerSessionId?: string;
 	/** pi-crew skill override selected when the run was created. false disables injected skill instructions. */
@@ -422,6 +573,10 @@ export interface TeamTaskState {
 	jsonEvents?: number;
 	agentProgress?: CrewAgentProgress;
 	error?: string;
+	/** Fatal fs failure cause (bug-026 sub-issue B): set when the failure was
+	 *  classified as enospc/edquot/emfile/enfile so operators see "failed
+	 *  (disk full)" instead of a generic timeout diagnostic. */
+	failureCause?: FatalFsCause;
 	claim?: TaskClaimState;
 	heartbeat?: WorkerHeartbeatState;
 	checkpoint?: TaskCheckpointState;
@@ -430,11 +585,35 @@ export interface TeamTaskState {
 	terminalEvidence?: OperationTerminalEvidence[];
 	taskPacket?: TaskPacket;
 	verification?: VerificationEvidence;
+	/** T4/R6 (ADR-6 §3): SPEC-EVIDENCE coverage report. Present only when the
+	  task carried specSnapshots; non-strict gaps show as badge:"unverified". */
+	specGate?: SpecGateResult;
 	graph?: TaskGraphNode;
 	adaptive?: {
 		phase: string;
 		task: string;
 	};
+	/** T2/R4 (ADR-4 §3): the plan item this task implements. Set by producers
+	 *  when they create tasks from PlanRecord items; the scheduler reads it at
+	 *  dispatch to link `items[].taskIds` (single writer, run-locked). */
+	planItem?: string;
+	/** T2/R4 (ADR-4 §4): set when the wrap-up advisory was delivered because the
+	 *  item was dropped by a re-plan (soft cancel; exactly-once across ticks).
+	 *  Doubles as the terminal marker "cancelled-by-replan". */
+	replanDroppedAt?: string;
+	/** T3/R5 (ADR-5 §3): delegation depth of THIS task. Workers are depth 1;
+	 *  delegate-spawned grandchildren are depth 2+. The spawn policy computes
+	 *  a grandchild's depth from this record field — NEVER from the requesting
+	 *  worker's env or self-report (design §7 rev-2 P0-2). Additive: absent on
+	 *  pre-v2 records (readers treat absent as depth 1). */
+	depth?: number;
+	/** T3/R5 (ADR-5 §5): per-task budget allocation for delegate accounting.
+	 *  `tokensGranted` is reserved at delegate admission; `tokensSpent` rolls up
+	 *  grandchild usage as events arrive (single writer, run lock). Additive. */
+	allocation?: {
+		tokensGranted: number;
+		tokensSpent: number;
+	};
 	policy?: {
 		retryCount?: number;
 		lastDecision?: PolicyDecision;
@@ -457,6 +636,24 @@ export interface TeamTaskState {
 	/** Steering messages queued before the task's session was ready.
 	 *  Delivered when the session initializes (mirrors pi-subagents3 pendingSteers pattern). */
 	pendingSteers?: string[];
+
+	/** WP-2/R2 (ADR-0 docs/decisions/2026-08-17-waiting-producer-ask.md item 3):
+	 *  park marker set while the worker is blocked in the `ask` tool awaiting a
+	 *  leader answer. Purely additive — `status` carries "waiting" for the whole
+	 *  park and the parked tool's terminal report flips it back via the normal
+	 *  task lifecycle. */
+	waiting?: {
+		/** Correlation id (randomUUID) — matches manifest.waitState.questionId and
+		 *  the mailbox `kind:"response"` entry carrying the answer. */
+		questionId: string;
+		/** ISO timestamp when the park was accepted (broker wait.request). */
+		askedAt: string;
+		/** Ms-epoch answer deadline. Server-clamped root-side by the broker to
+		 *  now + min(timeoutSec, 3600) — worker-controlled values never exceed 1h. */
+		deadline: number;
+		/** Optional answer choices the worker presented with the question. */
+		options?: string[];
+	};
 }
 
 export interface ControlReservation {

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

@@ -0,0 +1,136 @@
+/**
+ * plan-pane.ts — dashboard pane 7 "Plan" (WP-7 / R7, H4).
+ *
+ * Tree: phase → item → tasks, with per-item progress derived from linked
+ * tasks (deriveItemProgress) and a depth badge on grandchild tasks (depth>1,
+ * T3/R5). Approval pending → `A approve · n deny` hint line (same actions the
+ * progress pane exposes — plan-approve/plan-deny are pane-scoped to BOTH
+ * panes in keybinding-map). `X` toggles the multi-revision diff view
+ * (pane-scoped; V collides with root liveConversation, e with root events —
+ * X verified free).
+ *
+ * Flag-off: the dashboard never mounts this pane (key 7 still switches, but
+ * the snapshot carries no plans slice — the pane degrades to a hint line).
+ * Uncolored by design, mirroring the other dashboard panes.
+ */
+
+import { isPlanApprovalPending } from "../../runtime/plan-approval.ts";
+import { deriveItemProgress } from "../../state/stores/plan-store.ts";
+import type { PlanItemStatus, TeamTaskState } from "../../state/types.ts";
+import type { RunUiSnapshot } from "../snapshot-types.ts";
+
+const ITEM_GLYPH: Record<PlanItemStatus, string> = {
+	pending: "○",
+	active: "▸",
+	done: "✓",
+	dropped: "✗",
+};
+
+const TASK_GLYPH: Record<string, string> = {
+	queued: "○",
+	running: "▸",
+	waiting: "◷",
+	needs_attention: "⚠",
+	completed: "✓",
+	failed: "✗",
+	cancelled: "⊘",
+	skipped: "·",
+};
+
+function taskLine(task: TeamTaskState, indent: string): string {
+	const glyph = TASK_GLYPH[task.status] ?? "?";
+	// T3/R5 depth badge: grandchildren (depth 2+) surface explicitly so the
+	// tree shows delegation nesting without another pane.
+	const depth = typeof task.depth === "number" && task.depth > 1 ? ` d${task.depth}` : "";
+	const role = task.displayName ?? task.role;
+	return `${indent}${glyph} ${task.id}${depth} ${role} [${task.status}]`;
+}
+
+export interface PlanPaneOptions {
+	/** X-toggled multi-revision diff view (current vs previous revision). */
+	diff?: boolean;
+}
+
+/** Item-level diff between the current revision and its predecessor. */
+export function planRevisionDiff(snapshot: RunUiSnapshot): string[] {
+	const records = snapshot.plans ?? [];
+	// Current = highest-version record in the SNAPSHOT slice (in-memory truth —
+	// the pane must not re-read disk for what it already has).
+	const current = records.length ? records.reduce((a, b) => (b.version > a.version ? b : a)) : undefined;
+	if (!current) return ["Plan diff: no plan records"];
+	const prevVersion = current.revisionOf?.version;
+	const previous = prevVersion !== undefined ? records.find((r) => r.version === prevVersion) : undefined;
+	if (!previous) {
+		return [`Plan diff: v${current.version} has no prior revision`];
+	}
+	const prevItems = new Map(previous.items.map((i) => [i.id, i]));
+	const lines = [`Plan diff: v${previous.version} → v${current.version}`];
+	for (const item of current.items) {
+		const before = prevItems.get(item.id);
+		if (!before) {
+			lines.push(`  + ${item.id} ${item.title} [${item.status}]`);
+			continue;
+		}
+		if (before.status !== item.status || before.taskIds.length !== item.taskIds.length) {
+			lines.push(
+				`  ~ ${item.id} ${item.title} [${before.status}→${item.status} · ${before.taskIds.length}→${item.taskIds.length} tasks]`,
+			);
+		}
+		prevItems.delete(item.id);
+	}
+	for (const dropped of prevItems.values()) {
+		lines.push(`  - ${dropped.id} ${dropped.title} (dropped in v${current.version})`);
+	}
+	return lines;
+}
+
+export function renderPlanPane(snapshot: RunUiSnapshot, options: PlanPaneOptions = {}): string[] {
+	const records = snapshot.plans;
+	if (!records || records.length === 0) {
+		// Flag-off or plan-less run — one honest line, no I/O.
+		return ["Plan pane: no plan records (PI_CREW_PLAN_UI=1; plan-producing runs only)"];
+	}
+	if (options.diff) return planRevisionDiff(snapshot);
+
+	// Highest-version record in the snapshot slice (no disk re-read).
+	const current = records.reduce((a, b) => (b.version > a.version ? b : a));
+	if (!current) return ["Plan pane: no plan records"];
+	const progress = deriveItemProgress(current, snapshot.tasks);
+	const tasksById = new Map(snapshot.tasks.map((t) => [t.id, t]));
+	const itemById = new Map(current.items.map((i) => [i.id, i]));
+
+	const pending = isPlanApprovalPending(snapshot.manifest);
+	const header = `Plan pane: ${current.title} @v${current.version} (${current.phases.length} phases · ${current.items.length} items)`;
+	const approval = pending ? ["⚠ plan approval pending — A approve · n deny"] : [];
+
+	const lines: string[] = [header, ...approval];
+	for (const phase of current.phases) {
+		const glyph = ITEM_GLYPH[phase.status] ?? "?";
+		lines.push(`${glyph} ${phase.title}`);
+		for (const itemId of phase.itemIds) {
+			const item = itemById.get(itemId);
+			if (!item) continue;
+			const p = progress.get(itemId);
+			const counts = p ? ` ${p.done}/${p.total}${p.failed ? ` ✗${p.failed}` : ""}${p.running ? ` ▸${p.running}` : ""}` : "";
+			const droppedTag = item.status === "dropped" ? " ✗ dropped" : "";
+			lines.push(`  ${ITEM_GLYPH[item.status] ?? "?"} ${item.title}${counts}${droppedTag}`);
+			for (const taskId of item.taskIds) {
+				const task = tasksById.get(taskId);
+				if (task) lines.push(taskLine(task, "    "));
+			}
+		}
+	}
+	// Items not linked to any phase (producer-free-format plans) — still visible.
+	const phased = new Set(current.phases.flatMap((p) => p.itemIds));
+	const orphans = current.items.filter((i) => !phased.has(i.id));
+	if (orphans.length) {
+		lines.push("(unphased)");
+		for (const item of orphans) {
+			const p = progress.get(item.id);
+			const droppedTag = item.status === "dropped" ? " ✗ dropped" : "";
+			lines.push(`  ${ITEM_GLYPH[item.status] ?? "?"} ${item.title}${p ? ` ${p.done}/${p.total}` : ""}${droppedTag}`);
+		}
+	}
+	lines.push("X revision diff");
+	return lines;
+}

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

@@ -1,4 +1,5 @@
 import { computePhaseProgress, formatPhaseProgressLine } from "../../runtime/phase-progress.ts";
+import { isPlanApprovalPending } from "../../runtime/plan-approval.ts";
 import { renderDwfPhaseLines } from "../dwf-phase-display.ts";
 import type { RunUiSnapshot } from "../snapshot-types.ts";
 
@@ -23,8 +24,13 @@ export function renderProgressPane(snapshot: RunUiSnapshot | undefined): string[
 	// 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) : [];
+	// WP-3 (H4-subset): plan-approval gate banner. Mirrors the health-pane
+	// hint pattern — plain foreground text, no color codes (pane output is
+	// uncolored by design). One line while the run is parked on approval.
+	const planBanner = isPlanApprovalPending(snapshot.manifest) ? ["⚠ plan approval pending — A approve / n deny"] : [];
 	return [
 		`Progress pane: ${progress.completed}/${progress.total} completed · running=${progress.running} queued=${progress.queued} failed=${progress.failed}`,
+		...planBanner,
 		...dwfPhaseLines,
 		...phaseHeader,
 		...cancellationLine,

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

@@ -1,9 +1,40 @@
 import type { RunUiSnapshot } from "../snapshot-types.ts";
 
+/**
+ * Transcript pane (pane 4). WP-8 (R8): per-attempt model transparency —
+ * tasks that burned fallback attempts show which model each attempt used
+ * (`requested ✓` / `failed ✗ → next`), newest first, capped to the pane
+ * budget. Rendering stays uncolored (pane convention); status glyphs are
+ * colorized by the shared colorizeStatusGlyphs pass.
+ */
+
+const ATTEMPT_SUMMARY_TASKS = 3;
+
+function modelAttemptLines(snapshot: RunUiSnapshot): string[] {
+	const withAttempts = snapshot.tasks
+		.filter((task) => (task.modelAttempts?.length ?? 0) > 0)
+		.slice(-ATTEMPT_SUMMARY_TASKS)
+		.reverse();
+	if (!withAttempts.length) return [];
+	const lines = ["model attempts (newest first):"];
+	for (const task of withAttempts) {
+		const attempts = (task.modelAttempts ?? [])
+			.map(
+				(attempt) =>
+					`${attempt.model} ${attempt.success ? "✓" : `✗${attempt.exitCode !== undefined ? `(${attempt.exitCode})` : ""}`}`,
+			)
+			.join(" → ");
+		const resolved = task.modelRouting?.resolved ? ` · resolved ${task.modelRouting.resolved}` : "";
+		lines.push(`  ${task.id} (${task.role})${resolved}: ${attempts}`);
+	}
+	return lines;
+}
+
 export function renderTranscriptPane(snapshot: RunUiSnapshot | undefined): string[] {
 	if (!snapshot) return ["Output pane: snapshot unavailable"];
 	return [
 		`Output pane: ${snapshot.recentOutputLines.length} recent lines · press v for transcript viewer · o for raw output`,
+		...modelAttemptLines(snapshot),
 		...snapshot.recentOutputLines.slice(-12).map((line) => `⎿ ${line}`),
 		...(snapshot.recentOutputLines.length ? [] : ["No recent output"]),
 	];

package/src/ui/heartbeat-aggregator.ts

@@ -1,5 +1,6 @@
 import type { MetricRegistry } from "../observability/metric-registry.ts";
 import { classifyHeartbeat, heartbeatAgeMs } from "../runtime/heartbeat/heartbeat-gradient.ts";
+import { isTerminalRunStatus } from "../state/contracts.ts";
 import type { TeamTaskState } from "../state/types.ts";
 import type { RunUiSnapshot } from "./snapshot-types.ts";
 
@@ -45,8 +46,15 @@ export function summarizeHeartbeats(snapshot: RunUiSnapshot, opts: HeartbeatSumm
 		worstStaleMs: 0,
 		gradient: { healthy: 0, warn: 0, stale: 0, dead: 0 },
 	};
+	// bug-026 sub-issue C: a terminal run must never report dead/missing/stale
+	// workers. isActiveTask below already skips terminal tasks (the primary
+	// task-level gate — locked in by regression tests), but a stale snapshot can
+	// carry "running" task statuses that lag the run manifest's terminal
+	// transition. Defense-in-depth: skip ALL task counting when the run manifest
+	// itself is terminal. Runs with a non-terminal manifest are unaffected.
+	const runTerminal = isTerminalRunStatus(snapshot.manifest.status);
 	for (const task of snapshot.tasks) {
-		if (!isActiveTask(task)) continue;
+		if (runTerminal || !isActiveTask(task)) continue;
 		const heartbeat = task.heartbeat;
 		if (!heartbeat) {
 			summary.missing += 1;

package/src/ui/keybinding-map.ts

@@ -26,6 +26,7 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { type KeyId, matchesKey } from "@earendil-works/pi-tui";
+import { getCrewEnv } from "../config/env-vars.ts";
 import { keyOf } from "./key-utils.ts";
 
 export const DASHBOARD_KEYS = {
@@ -52,6 +53,7 @@ export const DASHBOARD_KEYS = {
 		output: ["4"],
 		health: ["5"],
 		metrics: ["6"],
+		plan: ["7"],
 	},
 	navigation: { up: ["k", "up"], down: ["j", "down"] },
 	mailbox: {
@@ -63,6 +65,7 @@ export const DASHBOARD_KEYS = {
 		openDetail: ["\r", "\n"],
 	},
 	health: { recovery: ["R"], killStale: ["K"], diagnosticExport: ["D"] },
+	plan: { approve: ["A"], deny: ["n"], diff: ["X"] },
 	notification: { dismissAll: ["H"] },
 } as const;
 
@@ -70,7 +73,7 @@ export const DASHBOARD_KEYS = {
  * Pane identifiers that can scope a binding. `undefined` means the binding
  * fires in every pane.
  */
-export type ActivePane = "agents" | "progress" | "mailbox" | "output" | "health" | "metrics";
+export type ActivePane = "agents" | "progress" | "mailbox" | "output" | "health" | "metrics" | "plan";
 
 /**
  * A single keybinding: the keys that trigger it, the action it produces, and
@@ -81,8 +84,8 @@ export type ActivePane = "agents" | "progress" | "mailbox" | "output" | "health"
 export interface KeyBinding {
 	readonly keys: readonly string[];
 	readonly action: DashboardKeyAction;
-	/** When set, the binding only fires when `activePane === pane`. */
-	readonly pane?: ActivePane;
+	/** When set, the binding fires only in these pane(s). */
+	readonly pane?: PaneScope;
 }
 
 export type DashboardKeyAction =
@@ -106,12 +109,16 @@ export type DashboardKeyAction =
 	| "pane-output"
 	| "pane-health"
 	| "pane-metrics"
+	| "pane-plan"
+	| "plan-diff"
 	| "up"
 	| "down"
 	| "mailbox-detail"
 	| "health-recovery"
 	| "health-kill-stale"
 	| "health-diagnostic-export"
+	| "plan-approve"
+	| "plan-deny"
 	| "notifications-dismiss";
 
 /**
@@ -125,14 +132,17 @@ export type DashboardKeyAction =
  *   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.
+ *   3. `health-*` and `plan-*` are pane-scoped (health / progress).
  *   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.
+ * intentionally NOT dispatched for the mailbox pane by 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. The `plan`
+ * group reuses uppercase "A" (approve) pane-scoped to "progress" — it never
+ * fires while the mailbox pane (or the mailbox-detail overlay) owns input,
+ * so `mailbox.ack` behavior is unchanged.
  */
 const DEFAULT_BINDINGS: readonly KeyBinding[] = [
 	{ keys: DASHBOARD_KEYS.close, action: "close" },
@@ -157,6 +167,22 @@ const DEFAULT_BINDINGS: readonly KeyBinding[] = [
 		action: "health-diagnostic-export",
 		pane: "health",
 	},
+	{
+		keys: DASHBOARD_KEYS.plan.approve,
+		action: "plan-approve",
+		// WP-7: shared by the progress banner and the Plan pane (pane 7).
+		pane: ["progress", "plan"],
+	},
+	{
+		keys: DASHBOARD_KEYS.plan.deny,
+		action: "plan-deny",
+		pane: ["progress", "plan"],
+	},
+	{
+		keys: DASHBOARD_KEYS.plan.diff,
+		action: "plan-diff",
+		pane: "plan",
+	},
 	{
 		keys: DASHBOARD_KEYS.notification.dismissAll,
 		action: "notifications-dismiss",
@@ -179,6 +205,7 @@ const DEFAULT_BINDINGS: readonly KeyBinding[] = [
 	{ 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.pane.plan, action: "pane-plan" },
 	{ keys: DASHBOARD_KEYS.navigation.up, action: "up" },
 	{ keys: DASHBOARD_KEYS.navigation.down, action: "down" },
 ];
@@ -202,6 +229,7 @@ const KEY_RESERVED = new Set<string>([
 	...Object.values(DASHBOARD_KEYS.navigation).flat(),
 	...Object.values(DASHBOARD_KEYS.mailbox).flat(),
 	...Object.values(DASHBOARD_KEYS.health).flat(),
+	...Object.values(DASHBOARD_KEYS.plan).flat(),
 	...Object.values(DASHBOARD_KEYS.notification).flat(),
 ]);
 
@@ -253,9 +281,22 @@ function parseKeybindingOverride(raw: unknown): KeybindingOverride {
  * bindings fire at once (so a shared key is genuinely ambiguous). Global
  * (`undefined`) matches anything; two different concrete panes never overlap.
  */
-function paneScopesCompatible(a: ActivePane | undefined, b: ActivePane | undefined): boolean {
+/** Pane scopes — a binding may fire in ONE pane, SEVERAL panes (WP-7: plan
+ *  approval keys are shared by progress + plan panes), or every pane
+ *  (undefined). */
+export type PaneScope = ActivePane | readonly ActivePane[];
+
+function paneScopeMatches(scope: PaneScope | undefined, pane: ActivePane | undefined): boolean {
+	if (scope === undefined) return true;
+	if (Array.isArray(scope)) return pane !== undefined && scope.includes(pane);
+	return scope === pane;
+}
+
+function paneScopesCompatible(a: PaneScope | undefined, b: PaneScope | undefined): boolean {
 	if (a === undefined || b === undefined) return true;
-	return a === b;
+	const as = Array.isArray(a) ? a : [a];
+	const bs = Array.isArray(b) ? b : [b];
+	return as.some((x) => bs.includes(x));
 }
 
 interface EffectiveBindingsResult {
@@ -311,7 +352,7 @@ function readConfigKeybindings(cwd: string): KeybindingOverride {
 
 /** Read the `PI_CREW_KEYBINDINGS` env var (JSON object string). */
 function readEnvKeybindings(): KeybindingOverride {
-	const raw = process.env[KEYBINDINGS_ENV];
+	const raw = getCrewEnv(KEYBINDINGS_ENV);
 	if (!raw) return {};
 	try {
 		return parseKeybindingOverride(JSON.parse(raw));
@@ -344,7 +385,7 @@ let _overrideWarnings: readonly string[] = [];
  * mtime, cwd); a single `statSync` per call detects on-disk config changes.
  */
 function getEffectiveBindings(cwd: string = process.cwd()): readonly KeyBinding[] {
-	const envRaw = process.env[KEYBINDINGS_ENV];
+	const envRaw = getCrewEnv(KEYBINDINGS_ENV);
 	const configMtime = configKeybindingsMtime(cwd);
 	if (_effectiveCache && _effectiveCache.env === envRaw && _effectiveCache.configMtime === configMtime && _effectiveCache.cwd === cwd) {
 		return _effectiveCache.bindings;
@@ -402,7 +443,7 @@ export function dashboardActionForKey(data: string, activePane?: ActivePane): Da
 	// Pass 1 — exact string match (case-sensitive). Handles literal ASCII
 	// keystrokes ('d', 'D', 'q', 'S', …) and preserves their distinct meanings.
 	for (const binding of BINDINGS) {
-		if (binding.pane !== undefined && binding.pane !== activePane) continue;
+		if (!paneScopeMatches(binding.pane, activePane)) continue;
 		if (binding.keys.includes(data)) return binding.action;
 	}
 	// Pass 2 — terminal-aware match for escape sequences / canonical KeyIds.
@@ -411,7 +452,7 @@ export function dashboardActionForKey(data: string, activePane?: ActivePane): Da
 	// legacy CSI, app-cursor-mode, and Kitty-protocol variants uniformly.
 	const key = keyOf(data);
 	for (const binding of BINDINGS) {
-		if (binding.pane !== undefined && binding.pane !== activePane) continue;
+		if (!paneScopeMatches(binding.pane, activePane)) continue;
 		for (const candidate of binding.keys) {
 			if (key === candidate) return binding.action;
 			if (matchesKey(data, candidate as KeyId)) return binding.action;