pi-crew 0.1.49 → 0.2.0

package/docs/research-phase8-operator-experience-plan.md

@@ -1,819 +0,0 @@
-# Phase 8 — Operator Experience: Interactive Mailbox, Health Pane, Smart Notifications
-
-> Tiếp nối tự nhiên của Phase 7 (UI Optimization). Mục tiêu: biến dashboard từ "viewer" thành "operator console" — actions thực hiện được trực tiếp từ UI, không phải toggle CLI. Path X chosen (Phase 8 = Theme A, Phase 9 = Theme B+C Observability+Reliability deferred).
-
-**Open Questions Resolution (Q1-Q6 đã chốt — xem Section 7 chi tiết):**
-- Q1=(b) Có preview compose pane | Q2=(c) Sink JSONL khi `telemetry.enabled` | Q3=(b) Cross-day quiet-hours wrap
-- Q4=(c) Full action menu R/K/D trên health pane | Q5=(c) Confirm chỉ destructive | Q6=(a) ESC discard + confirm-if-long guard
-
-## 0. Implementation Status
-
-- [x] 8.0 Foundation: keybinding contract + action dispatcher + RunActionResult shape + ConfirmOverlay primitive
-- [x] 8.1.A Mailbox detail overlay (passive list view, no actions yet)
-- [x] 8.1.B Mailbox ack action (hotkey `A` trên message đang chọn)
-- [x] 8.1.C Mailbox nudge action (hotkey `N` + agent picker)
-- [x] 8.1.D Mailbox compose action (hotkey `C` + form overlay) — Q6: ESC discard + confirm-if-long (>50 chars)
-- [x] 8.1.E Mailbox compose preview pane (key `P` toggle, render markdown read-only) — Q1
-- [x] 8.1.F Mailbox ackAll destructive action (hotkey `Shift+X`) — Q5: requires confirm overlay
-- [x] 8.2.A Heartbeat aggregator (`heartbeat-aggregator.ts`)
-- [x] 8.2.B Health pane (pane index `5`) trong dashboard
-- [x] 8.2.C Auto-recovery prompt (stuck worker > N minutes → toast + confirm) — throttled 5min/run
-- [x] 8.2.D Health pane action menu — `R` recovery (foreground only), `K` kill stale workers, `D` diagnostic export — Q4
-- [x] 8.3.A Notification router (severity classifier + dedup window)
-- [x] 8.3.B Notification quiet-hours (cross-day wrap parser) + batching config — Q3
-- [x] 8.3.C Toast badge counter trong widget/powerbar (đếm số notification chưa ack)
-- [x] 8.3.D Notification JSONL sink rotate 7 ngày, gated bởi `telemetry.enabled` — Q2
-- [x] 8.4 Wire `register.ts` + `commands.ts`
-- [x] 8.5 Tests: unit + integration
-
-## 1. Roadmap-Level Decisions
-
-| # | Decision | Chosen | Rationale |
-|---|---|---|---|
-| D1 | Mailbox actions chạy trực tiếp hay dispatch về team API? | **Dispatch** qua `handleTeamTool({action:"api", config:{operation:...}})` | Tận dụng API hiện có (`ack-message`, `send-message`, `nudge-agent`); zero state-machine duplication; locks/events được giữ nguyên |
-| D2 | Overlay form vs inline edit? | **Overlay form** (modal-like, anchor center) | Dashboard sidebar quá hẹp cho text input; overlay tách biệt focus; ESC dễ cancel |
-| D3 | Health pane là pane mới (`5`) hay tab trong progress? | **Pane mới `5`** | Tránh pollute progress pane; cho user toggle độc lập; consistent với existing 1-4 |
-| D4 | Notification sink: optional opt-in hay default-on? | **Default-on khi `telemetry.enabled !== false`** (Q2=c) | Đồng nhất pattern Phase 6 telemetry; debug-friendly; user opt-out qua telemetry config chung. Path: `<crewRoot>/state/notifications/{YYYY-MM-DD}.jsonl`, rotate 7 ngày |
-| D5 | Quiet-hours format + cross-day? | **HH:MM-HH:MM trong config local timezone, support cross-day wrap** (Q3=b) | Single range `"22:00-07:00"` parser tự nhận diện wrap-around; intuitive vs multi-range array |
-| D6 | Compose-form fields scope? | **Phase 8: from/to/body/taskId + preview pane** (Q1=b) | Preview key `P` toggle render markdown read-only; thread/attachment defer Phase 9 |
-| D7 | Action mới có break keybinding cũ? | **No** — phím mới: `A/N/C/P/Shift+X` (mailbox), `R/K/D` (health), `H/X` (notification); phím hiện hành (`s/u/a/i/d/m/e/o/v/r/p/1-4/k/j`) giữ nguyên (lowercase `r` vẫn = reload root, uppercase `R` = recovery in health pane only) | Backward-compat; context-scoped uppercase |
-| D8 | Mailbox detail panel: inline expand hay separate overlay? | **Separate overlay** (mở khi nhấn Enter trên pane mailbox) | Pane chính giữ nguyên density; overlay scrollable |
-| D9 | Health pane action mode: prompt-only vs full menu? | **Full action menu (Q4=c)**: `R` recovery (foreground-only), `K` kill stale workers, `D` diagnostic export | Operator power-user toolkit; async runs `R/K` disabled with hint; `D` cực hữu ích cho bug report |
-| D10 | Foundation 8.0: tách RunActionDispatcher hay inline? | **Tách module** `src/ui/run-action-dispatcher.ts` | Reuse cho overlay con; dễ test; không bloat dashboard |
-| D11 | Compose ESC behavior? | **Discard + confirm-if-long** (Q6=a) | ESC không lưu draft; nếu body > 50 ký tự → confirm overlay `Y=discard, N=continue editing`; defer draft persistence Phase 9 |
-| D12 | Confirm overlay: per-action ad-hoc hay reusable primitive? | **Reusable primitive** `src/ui/overlays/confirm-overlay.ts` | Q5=c destructive (ackAll/recovery/diagnostic-export-with-secrets) cần consistent UX; reuse cho mọi confirm |
-| D13 | Auto-recovery throttle window? | **5 phút/run/condition-type** | Tránh notification storm khi run dead lâu; `recovery_dead_workers` riêng biệt với `recovery_missing_heartbeat` |
-| D14 | Diagnostic export `D` format & destination? | **JSON + redact secrets** vào `<crewRoot>/artifacts/{runId}/diagnostic-{timestamp}.json` | Self-contained snapshot (manifest + tasks + recent events + heartbeat summary); confirm before write nếu artifact-dir đã có file diag cũ < 1 phút |
-| D15 | Preview pane render scope (Q1=b)? | **Read-only markdown render**: bold/italic/code-block/list — no images/links | Đủ cho operator đọc nội dung trước khi gửi; không cần markdown engine đầy đủ; reuse từ existing transcript-viewer markdown helper nếu có |
-
-## 2. Phase Breakdown
-
-### Phase 8.0 — Foundation (2 dev-day, +0.5 cho ConfirmOverlay)
-
-**File mới:**
-- `src/ui/run-action-dispatcher.ts` — wrapper gọi `handleTeamTool` với `runId` + `operation`, normalize result thành `{ ok, message, data }`.
-- `src/ui/keybinding-map.ts` — central registry mapping `data` (raw stdin) → action name; export `KEY_RESERVED` để overlay con check conflict.
-- `src/ui/overlays/confirm-overlay.ts` — **(Q5)** reusable confirm primitive, anchor center, auto-focus `N` (safe default), Y/Enter=confirm, N/ESC=cancel. ~80 LOC.
-
-**Sửa:**
-- `src/ui/run-dashboard.ts` — refactor `handleInput` dùng `keybinding-map`; không thay đổi behavior cũ.
-
-**Skeleton:**
-
-```ts
-// run-action-dispatcher.ts
-import type { ExtensionContext } from "@mariozechner/pi-coding-agent";
-import { handleTeamTool } from "../extension/team-tool.ts";
-
-export interface RunActionResult {
-	ok: boolean;
-	message: string;
-	data?: unknown;
-}
-
-export async function dispatchMailboxAck(ctx: ExtensionContext, runId: string, messageId: string): Promise<RunActionResult> {
-	try {
-		const r = await handleTeamTool({ action: "api", runId, config: { operation: "ack-message", messageId } }, ctx);
-		return { ok: r.metadata?.status === "ok", message: r.text, data: r };
-	} catch (error) {
-		return { ok: false, message: error instanceof Error ? error.message : String(error) };
-	}
-}
-
-export async function dispatchMailboxNudge(ctx: ExtensionContext, runId: string, agentId: string, message: string): Promise<RunActionResult> { /* ... */ }
-export async function dispatchMailboxCompose(ctx: ExtensionContext, runId: string, payload: { from: string; to: string; body: string; taskId?: string; direction: "inbox" | "outbox" }): Promise<RunActionResult> { /* ... */ }
-export async function dispatchMailboxAckAll(ctx: ExtensionContext, runId: string): Promise<RunActionResult> { /* read-mailbox → loop ack-message */ }
-export async function dispatchHealthRecovery(ctx: ExtensionContext, runId: string): Promise<RunActionResult> { /* foreground-interrupt API */ }
-export async function dispatchKillStaleWorkers(ctx: ExtensionContext, runId: string): Promise<RunActionResult> { /* mark dead heartbeats; emit event */ }
-export async function dispatchDiagnosticExport(ctx: ExtensionContext, runId: string): Promise<RunActionResult> { /* read-manifest + list-tasks + read-events limit=200 + heartbeat summary → write artifact */ }
-```
-
-```ts
-// keybinding-map.ts (Q4 + Q5 expanded)
-export const DASHBOARD_KEYS = {
-	close: ["q", "\u001b"],
-	select: ["\r", "\n", "s"],
-	pane: { agents: ["1"], progress: ["2"], mailbox: ["3"], output: ["4"], health: ["5"] },
-	// Mailbox detail overlay context
-	mailbox: { ack: ["A"], nudge: ["N"], compose: ["C"], preview: ["P"], ackAll: ["X"], openDetail: ["\r", "\n"] },
-	// Health pane context (Q4=c full menu)
-	health: { recovery: ["R"], killStale: ["K"], diagnosticExport: ["D"] },
-	// Notification context
-	notification: { dismissAll: ["H"] },  // 'H' for Hush
-} as const;
-```
-
-```ts
-// confirm-overlay.ts
-export interface ConfirmOptions {
-	title: string;
-	body?: string;
-	dangerLevel?: "low" | "medium" | "high";  // colors theme accent
-	defaultAction?: "confirm" | "cancel";  // default "cancel"
-}
-export class ConfirmOverlay {
-	constructor(private opts: ConfirmOptions, private done: (confirmed: boolean) => void, private theme: unknown) {}
-	render(width: number): string[] { /* anchor-center box, dim Y/N hint */ }
-	handleInput(data: string): void {
-		if (data === "y" || data === "Y" || data === "\r" || data === "\n") return this.done(true);
-		if (data === "n" || data === "N" || data === "\u001b" || data === "q") return this.done(false);
-	}
-}
-```
-
-**Tests:**
-- `test/unit/run-action-dispatcher.test.ts` (7 test cases — 4 mailbox dispatchers + 3 health dispatchers, mock `handleTeamTool`).
-- `test/unit/confirm-overlay.test.ts` (4 cases: render, Y confirms, N cancels, default cancel safety).
-
----
-
-### Phase 8.1 — Mailbox Interactivity
-
-#### 8.1.A Mailbox detail overlay (1 dev-day)
-
-**File mới:**
-- `src/ui/overlays/mailbox-detail-overlay.ts` — class `MailboxDetailOverlay` implement Pi UI custom widget; render 2-column (inbox | outbox); ↑/↓ select; Enter expand body; ESC/q close.
-
-**Cập nhật:**
-- `src/ui/dashboard-panes/mailbox-pane.ts` — line cuối cùng đổi từ "use /team-api ..." thành `"Press Enter on mailbox pane to open detail (A=ack, N=nudge, C=compose)"`.
-- `src/ui/run-dashboard.ts` — khi `activePane === "mailbox"` và user nhấn Enter, return `{action: "mailbox-detail"}` thay vì close.
-- `src/extension/registration/commands.ts` — handle `selection.action === "mailbox-detail"` → mở `MailboxDetailOverlay` qua `ctx.ui.custom`.
-
-**Skeleton:**
-
-```ts
-export class MailboxDetailOverlay {
-	private inbox: MailboxMessage[] = [];
-	private outbox: MailboxMessage[] = [];
-	private selected = 0;
-	private side: "inbox" | "outbox" = "inbox";
-	constructor(private opts: { runId: string; cwd: string; ctx: ExtensionContext; done: (sel?: MailboxAction) => void; theme: unknown }) {
-		this.refresh();
-	}
-	private refresh(): void { /* read mailbox via team api */ }
-	render(width: number): string[] { /* 2-col layout, highlight selected */ }
-	handleInput(data: string): void { /* arrow nav, A/N/C dispatch via this.opts.done */ }
-}
-
-export interface MailboxAction {
-	type: "ack" | "nudge" | "compose" | "reply";
-	messageId?: string;
-	agentId?: string;
-}
-```
-
-**Tests:** `test/unit/mailbox-detail-overlay.test.ts` — 4 cases (render empty, render with items, key navigation, action dispatch).
-
-#### 8.1.B Ack action (0.75 dev-day)
-
-**Logic:** trong `MailboxDetailOverlay.handleInput`, key `A` (uppercase, để tránh conflict với `a`=artifacts ở dashboard root) → `done({type:"ack", messageId: selectedMessage.id})`.
-
-**Update `commands.ts`:** sau khi overlay close, nếu action.type === "ack" → call `dispatchMailboxAck(ctx, runId, action.messageId!)` → toast result.
-
-**Acceptance:** ack thành công → mailbox pane re-render với attention count giảm trong < 250ms (snapshot cache invalidate khi `crew.mailbox.acknowledged` event).
-
-#### 8.1.C Nudge action (0.75 dev-day)
-
-**Logic:** key `N` → mở agent picker overlay (reuse pattern từ existing `LiveRunSidebar`); chọn xong → message input → dispatch `dispatchMailboxNudge`.
-
-**File mới:** `src/ui/overlays/agent-picker-overlay.ts` (nhỏ, 80-120 LOC).
-
-**Acceptance:** nudge → `crew.mailbox.message` event fire → snapshot invalidate → mailbox pane attention count tăng đúng.
-
-#### 8.1.D Compose form (1.25 dev-day)
-
-**File mới:** `src/ui/overlays/mailbox-compose-overlay.ts` — form 4 field (from/to/body/taskId), Tab navigation, Enter submit, ESC cancel.
-
-**Behavior chi tiết (Q6=a):**
-- Tab/Shift+Tab: cycle giữa các field.
-- Body multi-line: Ctrl+Enter → newline; Enter trên field body với content non-empty → submit.
-- ESC khi body ≤ 50 ký tự → discard immediately, close overlay.
-- ESC khi body > 50 ký tự → mở `ConfirmOverlay` với title `"Discard draft?"` body `"Body has N chars. Y=discard, N=continue editing"`. Cancel default = continue editing (safe).
-- Submit validate: body required (non-whitespace), to required, from default `"operator"` if empty.
-- Direction toggle: Tab vào checkbox `[ ] Send to outbox` → Space toggle.
-
-**Logic dispatch:** `dispatchMailboxCompose` với `direction` từ checkbox (default `"inbox"` — operator gửi vào inbox của run).
-
-**Tests:** `test/unit/mailbox-compose-overlay.test.ts` — 8 cases (render, tab nav, ESC short discard, ESC long → confirm overlay, confirm overlay cancel = stay editing, confirm overlay confirm = discard, Enter submit, validation empty body, validation empty to).
-
-#### 8.1.E Compose preview pane (0.75 dev-day) — Q1=b
-
-**File mới:** `src/ui/overlays/mailbox-compose-preview.ts` — read-only render markdown của body field hiện tại; share state với `mailbox-compose-overlay.ts`.
-
-**Layout:** compose overlay split horizontal khi preview active — 60% form / 40% preview pane (pane render markdown read-only, không cho focus).
-
-**Render scope (D15):** bold (`**`), italic (`*`), code-block (`` ``` ``), inline code (`` ` ``), unordered list (`-`), numbered list (`1.`), heading (`#`/`##`/`###`). Skip images/links (out of scope; render link text only).
-
-**Behavior:**
-- Key `P` toggle preview on/off (state in compose overlay).
-- Preview cập nhật real-time khi body thay đổi (debounce 100ms để tránh re-render mỗi keystroke).
-- Khi preview active, header help line update: `"P close preview · Tab cycle · Enter submit · ESC discard"`.
-
-**Skeleton:**
-
-```ts
-// mailbox-compose-preview.ts
-export function renderComposePreview(body: string, width: number, theme: CrewTheme): string[] {
-	const tokens = tokenizeMarkdown(body);  // simple tokenizer ~80 LOC
-	return tokens.flatMap((t) => renderToken(t, width, theme));
-}
-
-function tokenizeMarkdown(body: string): MdToken[] { /* line-by-line scan */ }
-type MdToken = { type: "heading" | "code-block" | "list-item" | "paragraph"; level?: number; text: string };
-```
-
-**Tests:** `test/unit/mailbox-compose-preview.test.ts` — 6 cases (plain text, bold/italic, code block, list, heading, mixed content).
-
-#### 8.1.F Mailbox ackAll (0.5 dev-day) — Q5=c destructive
-
-**Logic:** trong `MailboxDetailOverlay.handleInput`, key `Shift+X` (raw stdin `"X"` uppercase) → mở `ConfirmOverlay`:
-- Title: `"Acknowledge all N unread messages?"`
-- Body: `"This cannot be undone. Y=ack all, N=cancel."`
-- DangerLevel: `"medium"`.
-
-Confirm `Y` → `dispatchMailboxAckAll(ctx, runId)` (dispatcher loop ack-message từng id) → toast result `"Acknowledged N messages."`.
-
-**Acceptance:** ackAll trong run với 10 unread → all marked acknowledged trong < 2s; mailbox pane attention → 0; emit 10x `crew.mailbox.acknowledged` event.
-
-**Tests:** `test/unit/mailbox-detail-overlay.test.ts` thêm 3 cases (Shift+X opens confirm, confirm Y dispatches loop, confirm N stays).
-
----
-
-### Phase 8.2 — Health Pane & Recovery
-
-#### 8.2.A Heartbeat aggregator (1 dev-day)
-
-**File mới:** `src/ui/heartbeat-aggregator.ts`
-
-```ts
-export interface HeartbeatSummary {
-	runId: string;
-	totalTasks: number;
-	healthy: number;       // alive=true, lastSeenAt < threshold
-	stale: number;         // lastSeenAt > stale threshold (default 60s)
-	dead: number;          // lastSeenAt > dead threshold (default 5min) hoặc alive=false
-	missing: number;       // task running nhưng no heartbeat record
-	worstStaleMs: number;
-}
-
-export function summarizeHeartbeats(snapshot: RunUiSnapshot, opts?: { staleMs?: number; deadMs?: number; now?: number }): HeartbeatSummary { /* ... */ }
-```
-
-**Tests:** `test/unit/heartbeat-aggregator.test.ts` — 6 cases (all healthy, mixed, all dead, missing record, custom threshold, edge `lastSeenAt=now`).
-
-#### 8.2.B Health pane (0.75 dev-day)
-
-**File mới:** `src/ui/dashboard-panes/health-pane.ts`
-
-```ts
-export function renderHealthPane(snapshot: RunUiSnapshot | undefined, opts?: { staleMs?: number; deadMs?: number; isForeground?: boolean }): string[] {
-	if (!snapshot) return ["Health pane: snapshot unavailable"];
-	const summary = summarizeHeartbeats(snapshot, opts);
-	const lines: string[] = [
-		`Health: ${summary.healthy}/${summary.totalTasks} healthy · stale=${summary.stale} · dead=${summary.dead} · missing=${summary.missing}`,
-	];
-	if (summary.worstStaleMs > 0) lines.push(`Worst stale: ${Math.round(summary.worstStaleMs / 1000)}s ago`);
-	// Q4=c: show full action menu hint
-	const actionHints: string[] = [];
-	if ((summary.dead > 0 || summary.missing > 0) && opts?.isForeground !== false) actionHints.push("R recovery");
-	if (summary.dead > 0 || summary.stale > 0) actionHints.push("K kill stale");
-	actionHints.push("D diagnostic export");
-	if (actionHints.length > 0) lines.push(`Actions: ${actionHints.join(" · ")}`);
-	if (summary.dead > 0 && opts?.isForeground === false) lines.push("(Async run: R/K disabled — use kill <pid> manually)");
-	return lines;
-}
-```
-
-**Update `run-dashboard.ts`:**
-- Thêm `"health"` vào type `Pane`.
-- Key `5` → `activePane = "health"`.
-- Switch case render `renderHealthPane` với `isForeground` từ `selectedRun.async ? false : true`.
-- Trong `handleInput`: nếu `activePane === "health"`:
-  - `R` → emit `{action: "health-recovery", runId}` (handler sẽ check foreground + ConfirmOverlay).
-  - `K` → emit `{action: "health-kill-stale", runId}` (handler ConfirmOverlay if dead > 5).
-  - `D` → emit `{action: "health-diagnostic-export", runId}` (handler check existing diag < 1min → confirm overwrite).
-- Header help line update: `"1 agents 2 progress 3 mailbox 4 output 5 health • s/u/a/i actions • R/K/D health"`.
-
-**Tests:** `test/unit/health-pane.test.ts` — 6 cases (no snapshot, all healthy → only D hint, dead foreground → R+K+D, dead async → only D + warning, mixed states, foreground false hint visible).
-
-#### 8.2.C Auto-recovery toast (0.5 dev-day) — Q4 simplified
-
-**Logic:** `RenderScheduler.tick` callback (đã có) gọi `summarizeHeartbeats`; nếu `dead > 0` hoặc `missing > 0` lần đầu → fire toast qua `notification-router` (8.3.A) với severity `"warning"`:
-- Title: `"Run {runId} has {N} dead workers"`.
-- Body: `"Open dashboard → 5 health → R recovery / K kill stale / D diagnostic"`.
-
-**Throttle (D13):** dedup id = `recovery_dead_workers_${runId}` — router dedup 5 phút/run/condition-type. Riêng `recovery_missing_heartbeat` có id khác để alert song song nếu cả hai cùng xảy ra.
-
-**Tests:** `test/integration/health-recovery.test.ts` — simulate stale heartbeat, verify single toast emitted; emit lần 2 trong window → drop; emit lần 2 sau 5min → fire lại.
-
-#### 8.2.D Health action handlers (1.5 dev-day) — Q4=c full menu
-
-**Update `src/extension/registration/commands.ts`:** handle 3 new actions từ dashboard:
-
-```ts
-// pseudo-code
-if (selection.action === "health-recovery") {
-	const run = manifestCache.get(selection.runId);
-	if (run?.async) { ctx.ui.notify("Recovery only available for foreground runs.", "warning"); return; }
-	const confirmed = await openConfirmOverlay(ctx, { title: "Interrupt foreground run?", body: "Tasks will be marked failed. Y=interrupt, N=cancel.", dangerLevel: "high" });
-	if (!confirmed) return;
-	const r = await dispatchHealthRecovery(ctx, selection.runId);
-	ctx.ui.notify(r.message, r.ok ? "info" : "error");
-}
-
-if (selection.action === "health-kill-stale") {
-	const summary = summarizeHeartbeats(snapshotCache.get(selection.runId)!);
-	if (summary.dead + summary.stale > 5) {
-		const confirmed = await openConfirmOverlay(ctx, { title: `Kill ${summary.dead + summary.stale} stale workers?`, dangerLevel: "medium" });
-		if (!confirmed) return;
-	}
-	const r = await dispatchKillStaleWorkers(ctx, selection.runId);
-	ctx.ui.notify(r.message, r.ok ? "info" : "error");
-}
-
-if (selection.action === "health-diagnostic-export") {
-	// D14: check existing diag in last 1min
-	const diagDir = path.join(run.artifactsRoot, "diagnostic");
-	const recentDiag = listRecentDiagnostic(diagDir, 60_000);
-	if (recentDiag) {
-		const confirmed = await openConfirmOverlay(ctx, { title: "Recent diagnostic exists", body: `File ${recentDiag} created < 1min ago. Overwrite?`, defaultAction: "cancel" });
-		if (!confirmed) return;
-	}
-	const r = await dispatchDiagnosticExport(ctx, selection.runId);
-	ctx.ui.notify(`Diagnostic exported to ${r.data}`, r.ok ? "info" : "error");
-}
-```
-
-**File mới:** `src/runtime/diagnostic-export.ts` — collect manifest + tasks + recent events (limit 200) + heartbeat summary + agent status snapshot; redact secrets từ env/config (block list: `*token*`, `*key*`, `*password*`, `*secret*`); write JSON vào `<crewRoot>/artifacts/{runId}/diagnostic-{ISO-timestamp}.json`.
-
-**Skeleton:**
-
-```ts
-// diagnostic-export.ts
-export interface DiagnosticReport {
-	runId: string;
-	exportedAt: string;
-	manifest: TeamRunManifest;
-	tasks: TeamTaskState[];
-	recentEvents: TeamEvent[];
-	heartbeat: HeartbeatSummary;
-	agents: { taskId: string; status: AgentStatus }[];
-	envRedacted: Record<string, string>;  // env vars with secrets masked as "***"
-}
-
-export async function exportDiagnostic(ctx: ExtensionContext, runId: string): Promise<{ path: string; report: DiagnosticReport }> { /* ... */ }
-
-function redactSecrets(obj: unknown): unknown { /* recursive replace values where key matches block list */ }
-```
-
-**Tests:**
-- `test/unit/diagnostic-export.test.ts` — 5 cases (basic export, secret redaction, missing run errors, file path generation, JSON validity).
-- Smoke: export → open file → verify đầy đủ field + 0 secrets.
-
----
-
-### Phase 8.3 — Smart Notifications
-
-#### 8.3.A Notification router (1 dev-day)
-
-**File mới:** `src/extension/notification-router.ts`
-
-```ts
-export type Severity = "info" | "warning" | "error" | "critical";
-
-export interface NotificationDescriptor {
-	id?: string;        // dedup key; nếu cùng id trong window → drop
-	severity: Severity;
-	source: string;     // "run-completed" | "subagent-stuck" | "health" | ...
-	runId?: string;
-	title: string;
-	body?: string;
-	timestamp?: number;
-}
-
-export interface NotificationRouterOptions {
-	dedupWindowMs?: number;   // default 30000
-	batchWindowMs?: number;   // default 0 (no batching by default)
-	quietHours?: string;      // "22:00-07:00" local
-	severityFilter?: Severity[];  // default: ["warning", "error", "critical"]
-	sink?: (n: NotificationDescriptor) => void;  // optional file/stream sink
-}
-
-export class NotificationRouter {
-	constructor(private opts: NotificationRouterOptions = {}, private deliver: (n: NotificationDescriptor) => void) {}
-	enqueue(n: NotificationDescriptor): void { /* dedup check, severity filter, quiet-hours skip, batch buffer, sink */ }
-	flush(): void { /* deliver batched */ }
-	dispose(): void { /* clear timers */ }
-}
-```
-
-**Wrap `sendFollowUp`:** trong `register.ts`, thay 2 call sites `sendFollowUp(...)` thành `notificationRouter.enqueue({...})`. Router decides có deliver qua `sendFollowUp` hay không.
-
-**Tests:** `test/unit/notification-router.test.ts` — 8 cases (dedup, severity filter, quiet hours mock clock, batch, sink invocation, dispose cleanup).
-
-#### 8.3.B Quiet-hours + batching config (0.75 dev-day) — Q3=b cross-day wrap
-
-**Update `src/schema/config-schema.ts`:**
-```ts
-notifications: Type.Optional(Type.Object({
-	enabled: Type.Optional(Type.Boolean()),
-	severityFilter: Type.Optional(Type.Array(Type.Union([Type.Literal("info"), Type.Literal("warning"), Type.Literal("error"), Type.Literal("critical")]))),
-	dedupWindowMs: Type.Optional(Type.Integer({ minimum: 1000 })),
-	batchWindowMs: Type.Optional(Type.Integer({ minimum: 0 })),
-	quietHours: Type.Optional(Type.String({ pattern: "^\\d{2}:\\d{2}-\\d{2}:\\d{2}$" })),
-	sinkRetentionDays: Type.Optional(Type.Integer({ minimum: 1, maximum: 90 })),  // Q2=c, default 7
-})),
-```
-
-**Update `src/config/defaults.ts`:** sane defaults (`severityFilter: ["warning","error","critical"]`, `dedupWindowMs: 30_000`, `batchWindowMs: 0`, `sinkRetentionDays: 7`).
-
-**Update `src/config/config.ts`:** parse + merge giống các section khác.
-
-**Cross-day parser (Q3=b):** trong `notification-router.ts`, helper isolated cho easy testing:
-
-```ts
-// notification-router.ts (excerpt)
-export function parseHHMMRange(range: string): { startMin: number; endMin: number } {
-	const [s, e] = range.split("-").map((part) => {
-		const [hh, mm] = part.split(":").map(Number);
-		return hh * 60 + mm;
-	});
-	return { startMin: s, endMin: e };
-}
-
-export function isInQuietHours(range: string, now: Date = new Date()): boolean {
-	const { startMin, endMin } = parseHHMMRange(range);
-	const cur = now.getHours() * 60 + now.getMinutes();
-	if (startMin === endMin) return false;  // empty range
-	// Q3=b: cross-day wrap when start > end
-	return startMin <= endMin
-		? (cur >= startMin && cur < endMin)
-		: (cur >= startMin || cur < endMin);
-}
-```
-
-**Tests:** `test/unit/notification-router.test.ts` thêm 4 cases parser:
-- `"09:00-17:00"` ở 12:00 → quiet (true).
-- `"09:00-17:00"` ở 22:00 → not quiet (false).
-- `"22:00-07:00"` ở 23:30 → quiet (cross-day true).
-- `"22:00-07:00"` ở 03:00 → quiet (cross-day true).
-- `"22:00-07:00"` ở 12:00 → not quiet (false).
-- Edge: `"00:00-23:59"` ở 12:00 → quiet (always-quiet within day).
-- Edge: `"00:00-00:00"` → always not quiet (empty range).
-
-#### 8.3.C Toast badge integration (0.75 dev-day)
-
-**Logic:** `NotificationRouter.deliver` → ngoài `sendFollowUp`, cộng `unreadCount++` trong `widgetState.notificationCount`. Reset khi user mở mailbox detail hoặc nhấn `H` (Hush — dismiss-all notifications visible badge).
-
-**Update `crew-widget.ts`:** model render thêm `🔔${count}` nếu `count > 0`. Để tránh emoji compatibility issue → fallback `[!${count}]` khi terminal không support emoji (detect qua `process.env.TERM`).
-
-**Update `powerbar-publisher.ts`:** segment `pi-crew-active` text append ` 🔔${count}` (hoặc fallback) khi active.
-
-**Tests:** `test/unit/widget-notification-badge.test.ts` — 5 cases (no count, count=1, count>9, dismiss reset, terminal fallback).
-
-#### 8.3.D Notification JSONL sink (0.5 dev-day) — Q2=c
-
-**File mới:** `src/extension/notification-sink.ts`
-
-**Logic:** khi config `telemetry.enabled !== false`, NotificationRouter delivery cũng gọi `sink.write(descriptor)`. Sink writes vào `<crewRoot>/state/notifications/{YYYY-MM-DD}.jsonl` (1 file/day, append-only).
-
-**Rotation:** start-of-day check (lazy, khi write đầu tiên) → delete files cũ hơn `notifications.sinkRetentionDays` (default 7).
-
-**Skeleton:**
-
-```ts
-// notification-sink.ts
-export interface NotificationSink {
-	write(n: NotificationDescriptor): void;
-	dispose(): void;
-}
-
-export function createJsonlSink(crewRoot: string, retentionDays: number): NotificationSink {
-	const dir = path.join(crewRoot, "state", "notifications");
-	let lastRotateDate = "";
-	return {
-		write(n) {
-			const today = new Date().toISOString().slice(0, 10);
-			if (today !== lastRotateDate) {
-				rotateOldFiles(dir, retentionDays);
-				lastRotateDate = today;
-			}
-			fs.mkdirSync(dir, { recursive: true });
-			fs.appendFileSync(path.join(dir, `${today}.jsonl`), JSON.stringify({ ...n, timestamp: n.timestamp ?? Date.now() }) + "\n");
-		},
-		dispose() { /* no-op */ },
-	};
-}
-
-function rotateOldFiles(dir: string, retentionDays: number): void {
-	if (!fs.existsSync(dir)) return;
-	const cutoff = Date.now() - retentionDays * 24 * 60 * 60 * 1000;
-	for (const file of fs.readdirSync(dir)) {
-		if (!file.endsWith(".jsonl")) continue;
-		const stat = fs.statSync(path.join(dir, file));
-		if (stat.mtimeMs < cutoff) fs.unlinkSync(path.join(dir, file));
-	}
-}
-```
-
-**Wire trong `register.ts`:** instantiate sink khi `telemetry.enabled !== false`, pass vào `NotificationRouter` options. Dispose trong `cleanupRuntime`.
-
-**Tests:** `test/unit/notification-sink.test.ts` — 5 cases (write basic, daily rotation, retention prune, no rotation cùng ngày, telemetry disabled = no-op).
-
----
-
-### Phase 8.4 — Wiring (0.75 dev-day)
-
-**Update `src/extension/register.ts`:**
-- Instantiate `NotificationRouter` cùng cấp với `runSnapshotCache`; check `loadConfig.telemetry?.enabled !== false` để decide có pass `JsonlSink` không.
-- Pass router vào `subagentManager` callback (line 64-86) thay vì gọi trực tiếp `sendFollowUp`.
-- Pass router vào `RenderScheduler` callback cho 8.2.C auto-recovery alert.
-- Pass `getRunSnapshotCache` + `notificationRouter` vào `commands.ts` deps.
-- Dispose router + sink trong `cleanupRuntime`.
-
-**Update `src/extension/registration/commands.ts`:**
-- Handle `selection.action === "mailbox-detail"` → mở `MailboxDetailOverlay`, dispatch action result, toast.
-- Handle `selection.action === "health-recovery" | "health-kill-stale" | "health-diagnostic-export"` (Q4=c) — flow chi tiết 8.2.D.
-- Pass `getRunSnapshotCache` cho overlay (cần để re-render sau action).
-- Pass `confirmOverlayFactory` để các handler reuse `ConfirmOverlay`.
-
----
-
-### Phase 8.5 — Tests + Validation (2 dev-day)
-
-**Unit (mới ~52 cases):**
-- `run-action-dispatcher.test.ts` (7)
-- `confirm-overlay.test.ts` (4)
-- `mailbox-detail-overlay.test.ts` (7 — bao gồm 3 cases ackAll Shift+X)
-- `mailbox-compose-overlay.test.ts` (8)
-- `mailbox-compose-preview.test.ts` (6) — Q1
-- `agent-picker-overlay.test.ts` (4)
-- `heartbeat-aggregator.test.ts` (6)
-- `health-pane.test.ts` (6) — Q4 expanded
-- `diagnostic-export.test.ts` (5) — Q4
-- `notification-router.test.ts` (8 + 4 quiet-hours parser cases = 12) — Q3
-- `notification-sink.test.ts` (5) — Q2
-- `widget-notification-badge.test.ts` (5)
-
-**Integration (mới ~6 cases):**
-- `test/integration/mailbox-action-roundtrip.test.ts` — open dashboard → ack → snapshot invalidate → count giảm.
-- `test/integration/mailbox-ackall-confirm.test.ts` — ackAll trigger ConfirmOverlay → confirm → loop ack 10 messages.
-- `test/integration/notification-dedup.test.ts` — emit cùng event 5 lần trong 30s → 1 toast.
-- `test/integration/notification-quiet-hours.test.ts` — set quietHours `"22:00-07:00"`, mock now=23:30 → 0 toast; mock now=12:00 → 1 toast.
-- `test/integration/notification-sink-rotation.test.ts` — write 8 days → oldest file deleted on day 8.
-- `test/integration/health-recovery-foreground.test.ts` — foreground run dead → R action → ConfirmOverlay → confirm → foreground-interrupt fired.
-- `test/integration/health-diagnostic-export.test.ts` — D action → diagnostic file written với secrets redacted; emit lần 2 trong 1min → ConfirmOverlay overwrite.
-
-**Acceptance trước commit:**
-- `npm test` ≥ 351 unit (current 299 + 52), 35 integration (current 29 + 6); 0 fail. Verified current suite: 351 unit + 44 integration.
-- `npm run typecheck` clean.
-- Manual smoke coverage (8 scenarios — mục 6) captured as automated smoke in `test/integration/phase8-smoke.test.ts`.
-
-## 3. Wave Organization (parallel-friendly) — Updated với Q1-Q6
-
-```
-Wave 1 (parallel, 2.5 days)
-├─ 8.0 Foundation (dispatcher + keybinding-map + ConfirmOverlay)
-├─ 8.3.A NotificationRouter primitive
-└─ 8.2.A Heartbeat aggregator
-
-Wave 2 (sequential, 5 days) — depends on Wave 1
-├─ 8.1.A Mailbox detail overlay
-├─ 8.1.B Ack action
-├─ 8.1.C Nudge action
-├─ 8.1.D Compose form (Q6 ESC discard + confirm-if-long)
-├─ 8.1.E Compose preview pane (Q1)
-└─ 8.1.F ackAll Shift+X destructive (Q5)
-
-Wave 3 (parallel, 4 days) — depends on Wave 1
-├─ 8.2.B Health pane
-├─ 8.2.C Auto-recovery toast (throttled 5min D13)
-├─ 8.2.D Health action handlers R/K/D (Q4) + diagnostic-export module
-├─ 8.3.B Quiet-hours cross-day parser (Q3) + batching config
-├─ 8.3.C Toast badge widget/powerbar
-└─ 8.3.D JSONL sink + retention (Q2)
-
-Wave 4 (sequential, 2.75 days)
-├─ 8.4 Wire register.ts + commands.ts (router, sink, action handlers)
-└─ 8.5 Tests + smoke validation (52 unit + 6 integration mới)
-```
-
-**Total estimate: 14-18 dev-days** (vs Phase 7 baseline 18 days). Effort tăng 3.35 day so với plan gốc 11-14d do Q1-Q6 chosen options enrich scope. Phase 8 vẫn smaller hơn Phase 7 vì chủ yếu UI overlay + event router, không động state machine.
-
-## 4. Files Affected — Updated với Q1-Q6
-
-### New (24 files)
-| Path | Purpose | Est LOC |
-|---|---|---|
-| `src/ui/run-action-dispatcher.ts` | Wrapper team-tool calls (7 dispatchers) | ~140 |
-| `src/ui/keybinding-map.ts` | Key registry (mailbox/health/notification scopes) | ~70 |
-| `src/ui/overlays/confirm-overlay.ts` | **(Q5)** Reusable confirm primitive | ~80 |
-| `src/ui/overlays/mailbox-detail-overlay.ts` | 2-col mailbox view + ackAll | ~250 |
-| `src/ui/overlays/mailbox-compose-overlay.ts` | Compose form + ESC guard | ~210 |
-| `src/ui/overlays/mailbox-compose-preview.ts` | **(Q1)** Markdown preview pane | ~120 |
-| `src/ui/overlays/agent-picker-overlay.ts` | Agent selector | ~110 |
-| `src/ui/heartbeat-aggregator.ts` | Heartbeat summary fn | ~70 |
-| `src/ui/dashboard-panes/health-pane.ts` | Health pane renderer with action hints | ~80 |
-| `src/extension/notification-router.ts` | Router + dedup + quiet-hours parser **(Q3)** | ~220 |
-| `src/extension/notification-sink.ts` | **(Q2)** JSONL sink + retention rotation | ~100 |
-| `src/runtime/diagnostic-export.ts` | **(Q4)** Diagnostic JSON exporter + secret redaction | ~140 |
-| `test/unit/run-action-dispatcher.test.ts` | | ~140 |
-| `test/unit/confirm-overlay.test.ts` | | ~80 |
-| `test/unit/mailbox-detail-overlay.test.ts` | | ~180 |
-| `test/unit/mailbox-compose-overlay.test.ts` | | ~180 |
-| `test/unit/mailbox-compose-preview.test.ts` | **(Q1)** | ~120 |
-| `test/unit/agent-picker-overlay.test.ts` | | ~80 |
-| `test/unit/heartbeat-aggregator.test.ts` | | ~120 |
-| `test/unit/health-pane.test.ts` | Q4 expanded scenarios | ~140 |
-| `test/unit/diagnostic-export.test.ts` | **(Q4)** | ~110 |
-| `test/unit/notification-router.test.ts` | + 4 cross-day parser cases | ~260 |
-| `test/unit/notification-sink.test.ts` | **(Q2)** | ~100 |
-| `test/unit/widget-notification-badge.test.ts` | | ~80 |
-| `test/integration/mailbox-action-roundtrip.test.ts` | | ~120 |
-| `test/integration/mailbox-ackall-confirm.test.ts` | **(Q5)** | ~100 |
-| `test/integration/notification-dedup.test.ts` | | ~90 |
-| `test/integration/notification-quiet-hours.test.ts` | **(Q3)** mock clock | ~110 |
-| `test/integration/notification-sink-rotation.test.ts` | **(Q2)** | ~110 |
-| `test/integration/health-recovery-foreground.test.ts` | **(Q4)** | ~120 |
-| `test/integration/health-diagnostic-export.test.ts` | **(Q4)** | ~120 |
-
-### Modified (10 files)
-| Path | Change |
-|---|---|
-| `src/ui/run-dashboard.ts` | Refactor `handleInput` dùng keybinding-map; thêm pane "health" key `5`; help line; emit `health-recovery/health-kill-stale/health-diagnostic-export` actions (Q4) |
-| `src/ui/dashboard-panes/mailbox-pane.ts` | Update help text gợi ý A/N/C/Enter/Shift+X (ackAll) |
-| `src/ui/crew-widget.ts` | Render notification badge `🔔N` (fallback `[!N]` cho terminal không support emoji) |
-| `src/ui/powerbar-publisher.ts` | Append badge cho `pi-crew-active` segment |
-| `src/extension/register.ts` | Instantiate NotificationRouter + JsonlSink (gated bởi telemetry); wrap `sendFollowUp`; pass vào RenderScheduler + commands deps |
-| `src/extension/registration/commands.ts` | Handle `mailbox-detail` + 3 health actions (Q4); mở overlay; reuse ConfirmOverlay (Q5) |
-| `src/extension/team-tool/api.ts` | (no change) — dispatchers reuse existing operations |
-| `src/schema/config-schema.ts` | Thêm `notifications` section + `sinkRetentionDays` (Q2) |
-| `src/config/{config.ts,defaults.ts}` | Parse + default cho notifications (severityFilter, dedupWindowMs, batchWindowMs, quietHours, sinkRetentionDays) |
-| `package.json` | Bump version `0.1.33` → `0.1.34` |
-
-### Docs (chỉ update khi user yêu cầu, theo project rule)
-- `docs/architecture.md` — bổ sung mục "Operator Actions", "Notification Router", "Diagnostic Export".
-
-## 5. Risk Assessment — Updated với Q1-Q6
-
-| Risk | Likelihood | Impact | Mitigation |
-|---|---|---|---|
-| Overlay hijack stdin của Pi UI | Med | High | Reuse pattern `LiveRunSidebar` (đã hoạt động); test với `pi-ui-compat.ts` shim |
-| Keybinding conflict với Pi global hotkeys | Low | Med | Uppercase `A/N/C/P/H/X` (mailbox), `R/K/D` (health) — context-scoped; lowercase Pi defaults không đụng |
-| Notification spam khi nhiều run concurrent | Med | Low-Med | Dedup window 30s default; severity filter excludes "info"; quiet-hours wrap (Q3) |
-| Quiet-hours cross-day parser bug | Low | Med | Q3=b: 7 unit test cases bao gồm cross-midnight; mock clock pattern |
-| MailboxDetailOverlay re-render slow | Low | Low | Reuse signature pattern từ `RunDashboard`; cache lines |
-| Race khi ack trong khi snapshot đang refresh | Low | Med | Dispatch awaits then invalidate cache; render scheduler debounce 75ms |
-| `sendFollowUp` swap break existing flow | Low | High | Wrap không thay; router default-on chỉ khi `notifications.enabled !== false`; fallback gọi `sendFollowUp` raw nếu router throws |
-| Config schema breaking change | Low | High | New section `notifications` purely optional; missing → defaults |
-| **(Q1)** Compose preview pane re-render bottleneck (debounce miss) | Low | Low | Debounce 100ms; cache last rendered tokens; tokenizer < 1ms cho 5KB body |
-| **(Q1)** Markdown tokenizer edge case (nested code in list) | Med | Low | Reuse pattern parser nếu có; 6 unit test edge cases; preview "best-effort" |
-| **(Q2)** Sink disk full / write fail | Low | Low | `appendFileSync` swallow errors qua `logInternalError`; sink failure không crash router |
-| **(Q2)** Retention prune deletes file đang được tail | Low | Low | Chỉ prune `.jsonl` cũ hơn cutoff; daily rotation đảm bảo file hôm nay không bị touch |
-| **(Q2)** PII trong notification body leak vào sink | Med | Med | Sink reuse secret redactor từ `diagnostic-export.ts` (Q4); router tag PII fields nếu cần |
-| **(Q4)** `R` recovery accidentally interrupt healthy run | Low | High | ConfirmOverlay với `dangerLevel: "high"` + default cancel; foreground-only check; clear "tasks marked failed" warning |
-| **(Q4)** `K` kill stale workers race với worker self-recovery | Low | Med | Mark dead heartbeats first → emit event → giải phóng claims; worker tự detect token mismatch sẽ exit |
-| **(Q4)** Diagnostic export ghi đè artifact dir đang dùng | Low | Med | D14: check existing diag < 1min → ConfirmOverlay overwrite; timestamp suffix unique |
-| **(Q4)** Diagnostic secret redaction miss key pattern mới | Med | High | Block list: `*token*`, `*key*`, `*password*`, `*secret*`, `*credential*`, `*auth*`; review qua test fixture với 20 key patterns |
-| **(Q5)** ConfirmOverlay default `Y` accidentally confirms destructive | Low | High | Default action = "cancel"; first focus là `[N]`; ESC = cancel; UI hint underlined N |
-| **(Q6)** ESC discard confirm fatigue (user complain phải confirm mỗi ESC) | Low | Low | Threshold 50 ký tự (configurable nếu user feedback); short body → discard ngay |
-| **(Q6)** Body multi-line Ctrl+Enter not detected on Windows | Med | Low | Test với `pi-ui-compat.ts`; fallback `Alt+Enter` if Ctrl+Enter fails detection |
-
-## 6. Testing Strategy — Updated với Q1-Q6
-
-**Unit-level (Wave 1-3):**
-- Mock `handleTeamTool` → assert dispatcher returns đúng `{ok, message}` cho 7 dispatchers.
-- Render overlay với fixture snapshot → assert lines layout.
-- Heartbeat aggregator: parameterized test với fixture timestamps (6 cases).
-- Health pane: 6 cases bao phủ foreground/async/healthy/dead/stale variations (Q4).
-- Notification router: mock clock (`globalThis.Date.now` override theo pattern Phase 7); 8 base cases + 4 cross-day parser (Q3).
-- Sink: rotation, retention, telemetry-disabled no-op (Q2).
-- Diagnostic export: secret redaction với 20-key fixture; JSON schema validate (Q4).
-- Confirm overlay: 4 cases verify default-cancel safety (Q5).
-- Compose preview: 6 cases markdown render (Q1).
-
-**Integration (Wave 4) — 7 scenarios:**
-- `mailbox-action-roundtrip.test.ts`: open dashboard → ack → snapshot invalidate → count giảm.
-- `mailbox-ackall-confirm.test.ts` (Q5): Shift+X → ConfirmOverlay → confirm → loop ack 10 messages → all `acknowledged`.
-- `notification-dedup.test.ts`: emit 5x cùng `crew.run.failed` trong 30s → `sendFollowUp` mock called once.
-- `notification-quiet-hours.test.ts` (Q3): quiet `"22:00-07:00"` mock now=23:30 → 0 toast; mock now=12:00 → 1 toast.
-- `notification-sink-rotation.test.ts` (Q2): write 8 ngày fake mtime → oldest deleted on day 8.
-- `health-recovery-foreground.test.ts` (Q4): foreground run với 2 dead workers → R action → ConfirmOverlay confirm → `foreground-interrupt` API called → tasks marked failed.
-- `health-diagnostic-export.test.ts` (Q4): D action → file written với 0 secrets in JSON; emit lần 2 trong 1min → ConfirmOverlay overwrite.
-
-**Smoke manual (8 scenarios):**
-1. Chạy `team run` 1 task foreground → mở `/team-dashboard` → key `3` mailbox → Enter → key `N` nudge → verify `events.jsonl` có `agent.nudged`.
-2. Chạy 2 run, đợi xong → verify nhận 1-2 toast (dedup).
-3. Set `notifications.quietHours = "00:00-23:59"` → verify 0 toast.
-4. **(Q1)** Compose form, gõ markdown body với bold/list/code → key `P` preview → verify render đúng.
-5. **(Q5)** ackAll trên run với 5 unread → ConfirmOverlay xuất hiện → N cancel → 0 message acked.
-6. **(Q4)** Foreground run với worker stuck > 1min → key `5` health → key `R` → ConfirmOverlay → Y → tasks failed; key `D` → diagnostic file viết.
-7. **(Q2)** Disable telemetry → run + emit notification → verify `<crewRoot>/state/notifications/` không tồn tại.
-8. **(Q6)** Compose body 100 chars → ESC → ConfirmOverlay xuất hiện → N → vẫn editing.
-
-**Performance budget:**
-- Mailbox overlay first render < 50ms với 100 messages.
-- Compose preview render < 30ms với 5KB markdown body (Q1).
-- Notification router enqueue overhead < 1ms.
-- Sink write < 5ms (single append) (Q2).
-- Health pane render < 5ms cho 50 tasks.
-- Diagnostic export complete < 200ms cho run với 50 tasks + 200 events (Q4).
-
-## 7. Open Questions — RESOLVED (Path X chosen)
-
-| Q | Câu hỏi | Lựa chọn | Implementation reference |
-|---|---|---|---|
-| **Q1** | Compose form có cần preview render trước khi submit? | **(b) Có preview pane** | 8.1.E `mailbox-compose-preview.ts`, key `P` toggle, render markdown read-only (bold/italic/code/list/heading), debounce 100ms. D15. +0.75d |
-| **Q2** | Notification sink default ghi `<crewRoot>/state/notifications.jsonl`? | **(c) Sink khi `telemetry.enabled !== false`** | 8.3.D `notification-sink.ts`, JSONL `<crewRoot>/state/notifications/{YYYY-MM-DD}.jsonl`, rotate `sinkRetentionDays` default 7. D4. +0.5d |
-| **Q3** | Quiet-hours cross-day wrap? | **(b) Wrap parser** | 8.3.B `parseHHMMRange` + `isInQuietHours` cross-day logic; 7 unit cases bao gồm `"22:00-07:00"`. D5. +0.25d |
-| **Q4** | Health pane recovery action button inline? | **(c) Full action menu R/K/D** | 8.2.D `R` recovery (foreground-only), `K` kill stale workers, `D` diagnostic export với secret redaction; 3 confirm flows. D9, D14. +1.5d |
-| **Q5** | Ack/nudge confirm cho destructive? | **(c) Confirm chỉ destructive (ackAll/recovery/diag-overwrite)** | 8.0 `ConfirmOverlay` reusable primitive; 8.1.F ackAll Shift+X with confirm. D12. +0.25d |
-| **Q6** | Compose form persist draft khi ESC? | **(a) ESC discard + confirm-if-long** | 8.1.D ESC behavior: body ≤ 50 chars → discard; > 50 → ConfirmOverlay. Defer draft persistence Phase 9. D11. +0.1d |
-
-**Tổng effort delta từ Q1-Q6: ~3.35 dev-day** → bump từ 11-14d → 14-18d.
-
-**Mục tiêu Q1-Q6 đã đạt:** mọi quyết định scope-shaping đã chốt; team có thể start Wave 1 mà không bị blocked clarification giữa chừng.
-
-## 8. Dependencies & Sequencing
-
-```
-Phase 7 (DONE) ─────► Phase 8.0 Foundation
-                         │
-              ┌──────────┼──────────┐
-              ▼          ▼          ▼
-         8.1 Mailbox  8.2 Health  8.3 Notif
-              │          │          │
-              └──────────┼──────────┘
-                         ▼
-                    8.4 Wiring
-                         │
-                         ▼
-                    8.5 Tests
-```
-
-**Hard prerequisites Phase 7:** ✅ `RunSnapshotCache`, `RenderScheduler`, dashboard panes — đã có.
-
-## 9. Effort Summary — Updated với Q1-Q6
-
-| Wave | Items | Dev-days | Parallelizable |
-|---|---|---|---|
-| 1 | 8.0 (Foundation + ConfirmOverlay Q5) + 8.3.A (Router) + 8.2.A (Heartbeat) | 2.5 | Yes (3 streams) |
-| 2 | 8.1.A → B → C → D (Q6) → E (Q1) → F (Q5) | 5 | No (sequential UX, share overlay state) |
-| 3 | 8.2.B + 8.2.C + 8.2.D (Q4 R/K/D) + 8.3.B (Q3) + 8.3.C + 8.3.D (Q2) | 4 | Yes (5 streams) |
-| 4 | 8.4 (Wire) + 8.5 (Tests) | 2.75 | No |
-| **Total** | **17 sub-phases** | **14-18** | — |
-
-**So với plan gốc:** +3.35 dev-day, +5 sub-phases, +8 file mới, +27 unit case, +4 integration case.
-
-## 10. Acceptance Checklist (Wave 4 exit criteria) — Updated
-
-- [x] Tất cả checkbox 8.0 → 8.5 ở mục 0 (Implementation Status) tick `[x]`.
-- [x] `npm test` ≥ **351 unit** (current 299 + 52 mới), ≥ **35 integration** (current 29 + 6 mới), 0 fail. Verified: 351 unit + 44 integration pass.
-- [x] `npm run typecheck` clean.
-- [x] Manual smoke **8 scenarios** pass (mục 6). Verified via automated smoke suite `test/integration/phase8-smoke.test.ts`.
-- [x] Performance budget thỏa: mailbox overlay <50ms, compose preview <30ms, sink write <5ms, diagnostic export <200ms. Verified microbench: mailbox 6.39ms, preview 1.61ms, health 0.29ms, sink 2.12ms, diagnostic 4.83ms.
-- [x] No regression: 299 unit + 29 integration cũ vẫn pass.
-- [x] Config breaking? **No.** Schema additive (`notifications` section optional).
-- [x] Bump `package.json` version `0.1.33` → `0.1.34`.
-- [x] Q1-Q6 implementations match decisions table mục 7.
-- [x] Secret redaction (Q4): test fixture with recursive key/value redaction pass; audit log avoids known token fixture.
-
-## 11. Out of Scope (defer Phase 9+)
-
-> Phase 9 plan đã được tạo riêng tại [`research-phase9-observability-reliability-plan.md`](./research-phase9-observability-reliability-plan.md).
-
-- **Telemetry/Metrics backbone** (Counter/Gauge/Histogram + correlation ID + OTLP/Prometheus export) → **Phase 9 (Theme B)** per Path X plan.
-- **Run reliability** — auto-retry executor + crash recovery + deadletter + heartbeat watcher → **Phase 9 (Theme C)**.
-- Cross-run mailbox routing (operator-broadcast) — **Phase 10+**.
-- Mailbox threading / reply chains — **Phase 10+**.
-- **Compose draft persistence (Q6 b/c options)** — defer Phase 9 nếu user feedback than.
-- Multi-host run aggregation — **Phase 10+**.
-- Slack/Discord webhook sink (router supports it via custom sink, but no built-in adapter) — **Phase 10+**.
-- Markdown preview với images/links rendered (Q1 D15 skip) — **Phase 10+**.
-
-### Path X roadmap summary
-
-| Phase | Theme | Effort | Plan file |
-|---|---|---|---|
-| 6 | `.crew/` migration + autonomous policy | ~12d | `refactor-tasks-phase6.md` (DONE) |
-| 7 | UI Optimization | ~18d | `research-ui-optimization-plan.md` (DONE) |
-| **8** | **Operator Experience (Theme A)** | **14-18d** | **THIS FILE — ✅ DONE (verified 351 unit + 44 integration pass, version 0.1.34)** |
-| **9** | **Observability + Reliability (B+C)** | **19.5-22.5d** | `research-phase9-observability-reliability-plan.md` (post-review updated 2026-04-29) |
-| 10+ | TBD: Perf baseline, distributed | — | Future |
-
----
-
-## 12. Implementation Kickoff Checklist (Pre-Wave 1)
-
-Trước khi bắt đầu Wave 1, verify:
-
-- [x] Phase 7 đã commit (snapshot cache + render scheduler + 4 panes). Included in `phase-8-operator-experience` release commit.
-- [x] `npm test` baseline pass (299 unit + 29 integration). Verified current suite: 351 unit + 44 integration pass.
-- [x] `npm run typecheck` clean.
-- [x] Q1-Q6 đã chốt (đã làm — table mục 7).
-- [x] Branch mới `phase-8-operator-experience` từ main.
-- [x] Read once: `src/extension/team-tool/api.ts` (đã có ack-message/send-message/nudge-agent operations — KHÔNG cần modify).
-- [x] Read once: `src/ui/run-dashboard.ts:handleInput` để hiểu pattern key dispatch hiện tại.
-- [x] Read once: `src/ui/live-run-sidebar.ts` để có template cho overlay implementation.
-
-**Sẵn sàng triển khai Phase 8 Path X.**