@zhuxixi/pi-agent-board 0.6.2 → 0.8.0

package/docs/superpowers/plans/2026-09-09-single-writer-completion.md

@@ -0,0 +1,252 @@
+# Single-Writer Completion (PR #2, issue #91 Phase 2b) Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** 迁移 PR #1 白名单中的全部剩余 writeState/writeStatus 直写点到 View State Coordinator，使架构边界白名单清零到仅剩「设计内豁免」，A7 完全闭合；同时关闭 PR #1 遗留的 pty-runner `markRowFailed` 无 manual-fence 残留风险。
+
+**Architecture:** 扩展 `src/core/state-commands.mjs` 的命令种类（lifecycle 命令显式建类 + 元数据/镜像合并为 `patch_fields` 通用命令），coordinator 支持「非 journal 的瞬时命令」（run_progress 热路径），各 runner/service/dashboard 的剩余站点逐个迁移。读侧 revision 一致性 enforcement 明确留给 PR #3（需要所有写者先打戳）。
+
+**Tech Stack:** Node.js ESM、node:net JSONL、现有 coordinator/journal/client（PR #1 已建）。
+
+**Spec:** `docs/superpowers/specs/2026-09-09-harden-runner-architecture-design.md`（D3 + 验收 A7 + 根治条件 1/2/5 写侧）；本 plan 不覆盖读侧 enforcement（PR #3）。
+
+## 设计决策（本 plan 锁定）
+
+1. **新命令种类**（加入 `STATE_COMMAND_KINDS`，决策层每个有显式分支）：
+   - lifecycle（改 semanticState/processState/currentRunId）：`mark_queued`、`run_started`、`run_progress`、`reconcile_finalize`、`host_run_failed`、`archive_view`、`adopt_session`、`sync_foreground`、`plan_ready`、`followup_started`
+   - 元数据/镜像合并：`patch_fields`，带 per-source 字段白名单 + 通用守卫
+2. **`run_progress` 是瞬时命令，不进 journal**：进度写是周期性快照（250ms 节流），被下一拍自愈；journal 化会让 journal 无界膨胀（4 条/秒/run），违背 GC 设计。模糊失败（timeout/reset）→ 跳过 + debug 级 diagnostic，等下一拍。落地仍打 materializedRevision（单调性由 boot counter 的 views 扫描保证）。
+3. **`host_run_failed` 必须带 manual fence**（通用守卫已覆盖非 user 来源）——这关闭 PR #1 遗留的 pty-runner markRowFailed 残留风险（手动完成后宿主迟到崩溃不再能把行翻成 failed）。
+4. **永久豁免**（边界测试白名单的终态）：(a) 各 runner 的 `coordinator_disabled` 遗留分支（显式 debug 逃生门，文档化）；(b) `store.mjs` createView bootstrap（不可能竞争：新 viewId 是随机生成的，不存在其他知情的写者）。豁免理由写进白名单条目；A7 的「清零」含义 = 无未治理写点，不是字面零条目。
+5. **dashboard.ts 热重载兼容回退直接删除**（旧 service 对象不跨重启存活，窗口是瞬时的）。
+6. **M2 summary 分歧**：coordinator 的 mark_completed 保持「保留现有 summary」（PR #1 裁决），本 PR 不改；如用户反馈再议。
+
+## Global Constraints
+
+- 所有 runner 进程 plain ESM `.mjs`，不依赖 jiti。
+- Commit message 英文 conventional commits；`git add <file>` 显式 stage，禁止 `-A`。
+- 测试 `node --test`；隔离必须同时设 `AGENT_BOARD_ROOT` + `PI_CODING_AGENT_DIR`；coordinator 一律用 tracked fixture（test-support/ensure-coordinator-helper.mjs，带 readiness wait + finally kill）。
+- 可测性硬约束：决策层保持纯函数；新命令的守卫逻辑在 state-commands.mjs 内，不碰 I/O。
+- 模糊结果（timeout/connection_reset）不回退直写；只有 `coordinator_disabled` 走 legacy 分支。
+- 工作区：`$WT = /home/elling/git-repo/github/pi-agent-board/.pi/worktrees/issue-91-single-writer-completion`，全部用绝对路径 + `git -C $WT`。
+
+## 验收映射
+
+| Task | 验收 ID | 说明 |
+|---|---|---|
+| Task 1 | A7 基础 | 决策层新命令种类 + 守卫（纯函数） |
+| Task 2 | A7/A7b | coordinator 支持瞬时命令 + patch_fields + host_run_failed |
+| Task 3 | A7 | job-runner 全量迁移（含热路径 run_progress） |
+| Task 4 | A7 | state-runner 镜像迁移 |
+| Task 5 | A7 + PR#1 残留风险 #2 | pty-runner markRowFailed → host_run_failed（带 fence） |
+| Task 6 | A7 | service.mjs 全量迁移 |
+| Task 7 | A7 | dashboard 回退删除 |
+| Task 8 | A7 闭合 | 边界测试白名单 → 设计内豁免；justification 更新 |
+| Task 9 | 对账 | 全量回归 + 验收对账 |
+
+A8 已在 PR #1 闭合（本 PR 不破坏其测试）；根治条件 5 的读侧在 PR #3。
+
+---
+
+### Task 1: 决策层扩展——新命令种类与守卫（纯函数）
+
+**Files:**
+- Modify: `src/core/state-commands.mjs`
+- Test: `test/state-commands.test.mjs`
+
+**Interfaces:**
+- Consumes: 现有 `validateCommand`/`decideStateTransition` 结构、守卫顺序（unknown_view → revision_conflict → stale_run → manual_fence → kind 分支）。
+- Produces（后续 task 依赖的精确契约）:
+  - `STATE_COMMAND_KINDS` 扩展为 13 种（现有 3 种 + 新增 10 种）
+  - `TRANSIENT_KINDS` = `["run_progress"]`（coordinator 据此跳过 journal）
+  - `PATCHABLE_FIELDS` per source 白名单：
+    - `job-runner`/`state-runner`: `["review","evidenceSummary"]`（镜像）+ status 侧 `evidenceSummary`
+    - `service`: `["lastVisitedAt"]`（markVisited 经此）
+  - 每个新 kind 的守卫（决策层分支，全部纯函数）：
+
+| kind | 额外守卫（通用守卫之外） | mutate 语义 |
+|---|---|---|
+| `mark_queued` | 无 | state: {currentRunId: payload.runId, semanticState:"queued", processState:"alive", summary:"Queued", needsInput:false, hasError:false, question:null, pendingQuestions:[], error:null, autoState:null} |
+| `run_started` | runId 必须等于 payload.runId | status 新建字段补丁（createRunStatus 形状由调用方算好放在 payload.status）；state: {processState:"alive", semanticState:"working", currentRunId} |
+| `run_progress` | `state.currentRunId === command.runId && state.processState === "alive"`，否则 reject "stale_run"（活跃性语义） | payload.statusPatch 稀疏合并 status；state 侧由 coordinator 用 projectViewState(statusClone) 重算（委托，不复制规则） |
+| `reconcile_finalize` | `state.processState === "alive"`（否则 no_change） | payload: {semanticState: "failed"\|"idle", reason}；state: {semanticState, processState:"exited", error?}；currentRunId 对应 status 存在则同步 finalize 字段 |
+| `host_run_failed` | 无（通用 manual_fence 即 PR#1 残留风险 #2 的关闭点） | state: {semanticState:"failed", processState:"exited", error: payload.error ?? null}；status 同理（currentRunId 匹配时） |
+| `archive_view` | busy 时 allow（archive 的 busy 分支原本就写 stopped） | state: {semanticState:"stopped", processState:"exited", needsInput:false, hasError:false, question:null, pendingQuestions:[], error:null, autoState:null, summary:"Stopped"} |
+| `adopt_session` | `processState !== "alive"`（否则 reject "busy"） | state: {semanticState:"idle", processState:"exited", summary:"Backgrounded session"} |
+| `sync_foreground` | 无 | payload.projection（service 侧 projectViewState 已算好，currentRunId 强制 null 由本分支保证）稀疏合并 state |
+| `plan_ready` | `processState === "alive"`（否则 no_change） | state: {needsInput:true, question: payload.question ?? null}；status 侧 recordPlanReady 对应字段 |
+| `followup_started` | 无 | payload.statusPatch → status；state 侧 projectViewState 重算 |
+| `patch_fields` | 字段白名单（`PATCHABLE_FIELDS[command.source]`，越界字段 reject "field_not_allowed"）；payload.runId 存在时 stale_run 通用守卫生效 | payload.state/payload.status 稀疏合并（仅限白名单字段） |
+
+- [ ] **Step 1: 写失败测试**——每种新 kind 至少 1 个 happy-path + 1 个守卫测试；`patch_fields` 越界字段拒绝测试；`run_progress` 的 stale/alive 守卫测试；`host_run_failed` 的 manual_fence 测试（复用现有 manualCompletedState fixture 模式）。
+- [ ] **Step 2: 运行确认失败** → **Step 3: 实现** → **Step 4: PASS** → **Step 5: Commit**
+
+```bash
+git -C $WT add src/core/state-commands.mjs test/state-commands.test.mjs
+git -C $WT commit -m "feat(core): extend state commands with lifecycle kinds and patch_fields (issue #91)"
+```
+
+---
+
+### Task 2: Coordinator 支持瞬时命令与新 kinds
+
+**Files:**
+- Modify: `runner/state-coordinator.mjs`
+- Test: `test/state-coordinator.integration.test.mjs`
+
+**Interfaces:**
+- Consumes: Task 1 的 `TRANSIENT_KINDS` 与新 kinds。
+- Produces:
+  - 瞬时命令（`TRANSIENT_KINDS`）路径：validate → dedupe 不需要（无 commandId 幂等语义——run_progress 无需 commandId 去重，client 可省略 commandId）→ decide → 直接物化（仍打 materializedRevision、仍 under view lock）→ 返回结果。**不写 journal、不进 processed 集合**。
+  - `run_progress` 的 revision bump 照常（单调性由全局 counter 保证；boot 时 views 扫描已覆盖）。
+  - 其余新 kinds 走正常 journaled 路径。
+
+- [ ] **Step 1: 失败测试**：run_progress 瞬时命令 applied 且 journal 行数不增长；host_run_failed applied；mark_queued applied；并发 run_progress 不交错（同一 view 两客户端连发）。
+- [ ] **Step 2–5: 失败 → 实现 → PASS → Commit**
+
+```bash
+git -C $WT add runner/state-coordinator.mjs test/state-coordinator.integration.test.mjs
+git -C $WT commit -m "feat(runner): transient run_progress and new lifecycle kinds in coordinator (issue #91)"
+```
+
+---
+
+### Task 3: job-runner 全量迁移（含热路径）
+
+**Files:**
+- Modify: `runner/job-runner.mjs`
+- Test: `test/runner.integration.test.mjs`
+
+**Interfaces:**
+- Consumes: Task 1-2 的命令；`sendStateCommand`。
+- Produces:
+  - boot bootstrap（L65/69、L95）→ `run_started` 命令
+  - `persist()` 热路径（L103-112 及 125/201/217 调用点）→ `run_progress` 瞬时命令（fire-and-forget：不等结果、失败 debug 级忽略——下一拍自愈；**这是本 PR 唯一允许 fire-and-forget 的命令**，理由：周期性快照 + 下一拍覆盖）
+  - `refreshEvidenceMirrors`（L152/157）→ `patch_fields`（review/evidenceSummary）
+  - plan-ready（L382）→ `plan_ready`；follow-up bootstrap（L408-409）→ `followup_started`
+  - post-exit summary persist（maybeModelSummary 尾部的 persistUnlessManual(true)）→ `patch_fields`（summary/latestAssistantPreview；manual fence 由通用守卫保证）
+  - `coordinator_disabled` 分支保留为设计内豁免（不迁移，但保持现状可用）
+  - **迁移完成后 runner/job-runner.mjs 不再 import writeState/writeStatus**（coordinator_disabled 分支改为调 legacy helper——见下）
+
+**关键设计点（防回归）：** coordinator_disabled 分支需要直写能力。方案：把 PR #1 之前的直写逻辑收进 `runner/job-runner-legacy.mjs`（新文件，只有 disabled 分支 import 它），使 job-runner.mjs 本身不再 import write 函数——边界测试白名单条目从 job-runner.mjs 移到 job-runner-legacy.mjs（justification：disabled 逃生门）。
+
+- [ ] **Step 1: 失败测试**：run_progress 经 coordinator 的集成测试（runner 活跃期间 state.json 由 coordinator 物化、journal 不增长）；#46 回归与既有 runner.integration 用例保持绿。
+- [ ] **Step 2–5: 失败 → 实现 → PASS → Commit**
+
+```bash
+git -C $WT add runner/job-runner.mjs runner/job-runner-legacy.mjs test/runner.integration.test.mjs
+git -C $WT commit -m "refactor(runner): migrate job-runner writes to coordinator incl. transient run_progress (issue #91)"
+```
+
+---
+
+### Task 4: state-runner 镜像迁移
+
+**Files:**
+- Modify: `runner/state-runner.mjs`（镜像写 → `patch_fields`）；disabled 分支同样收进 legacy helper 或直接保留（该文件小，保留 disabled 分支并更新白名单 justification 即可，不必拆文件）
+- Test: `test/state-coordinator.integration.test.mjs`（state-runner 真实进程用例更新断言）
+
+- [ ] **Step 1–5: TDD 循环 → Commit**
+
+```bash
+git -C $WT add runner/state-runner.mjs test/state-coordinator.integration.test.mjs
+git -C $WT commit -m "refactor(runner): migrate state-runner evidence mirrors to patch_fields (issue #91)"
+```
+
+---
+
+### Task 5: pty-runner markRowFailed → host_run_failed（关闭残留风险 #2）
+
+**Files:**
+- Modify: `runner/pty-runner.mjs`（markRowFailed，~L1021-1048）
+- Test: `test/pty-runner.integration.test.mjs`
+
+**Interfaces:**
+- markRowFailed 改为发送 `host_run_failed` 命令（source "pty-runner"——需加入 COMMAND_SOURCES）；payload `{ error, exitCode? }`。
+- 手动完成的行不再能被迟到崩溃翻成 failed（通用 manual_fence 守卫）；这是本 task 的核心回归测试。
+- pty-runner 是 detached 进程，coordinator-client 是 plain ESM 可 import。
+- 模糊结果处理：warn diagnostic + 继续（崩溃路径不能因此卡住退出）；coordinator_disabled → 保留 legacy 直写（收进 legacy helper 或保留原位并更新白名单 justification）。
+
+- [ ] **Step 1: 失败测试**（核心回归）：手动 completed 的行 + 宿主迟到崩溃 → state.json 保持 completed（fence 拒绝 host_run_failed）；无 fence 时正常 failed。
+- [ ] **Step 2–5: TDD → Commit**
+
+```bash
+git -C $WT add runner/pty-runner.mjs test/pty-runner.integration.test.mjs
+git -C $WT commit -m "fix(runner): route host crash finalization through fenced host_run_failed command (issue #91)"
+```
+
+---
+
+### Task 6: service.mjs 全量迁移
+
+**Files:**
+- Modify: `src/runtime/service.mjs`
+- Test: `test/service.test.mjs`
+
+**迁移映射（站点 → 命令）：**
+- L423 markQueued → `mark_queued`
+- L433 markVisited → `patch_fields`（lastVisitedAt；metadata，但统一走 coordinator 保持边界干净）
+- L524 archiveView 的 state 部分 → `archive_view`（meta.archived 直写保留——meta.json 是文档化例外）
+- L606 writeForegroundState → `sync_foreground`
+- L1602/1629 adoptSession → `adopt_session`
+- L1855/1864/1873 reconcile 终态 → `reconcile_finalize`
+- `completeViewDirect`（coordinator_disabled 分支）保留为设计内豁免——收进 `src/runtime/service-legacy.mjs` 或原位保留并更新白名单 justification（择实现复杂度低者；service.mjs 很大，原位保留 + justification 更新更简单）
+- 全部迁移后 service.mjs 的直接 writeState/writeStatus 调用点只剩 disabled 分支
+
+- [ ] **Step 1–5: TDD → Commit**（现有 service 测试全部保持绿；reconcile 相关用例更新为 coordinator 断言）
+
+```bash
+git -C $WT add src/runtime/service.mjs test/service.test.mjs
+git -C $WT commit -m "refactor(service): migrate remaining state writes to coordinator commands (issue #91)"
+```
+
+---
+
+### Task 7: dashboard.ts 兼容回退删除
+
+**Files:**
+- Modify: `src/ui/dashboard.ts`（删除 ~L981-1020 的 stale-service-object 回退；markCompleted 调用统一走新 async 路径）
+- Test: `test/service.test.mjs` / dashboard 相关测试保持绿
+
+- [ ] **Step 1–5: TDD → Commit**
+
+```bash
+git -C $WT add src/ui/dashboard.ts
+git -C $WT commit -m "refactor(dashboard): drop pre-coordinator markCompleted compat fallback (issue #91)"
+```
+
+---
+
+### Task 8: 边界测试白名单 → 设计内豁免（A7 闭合）
+
+**Files:**
+- Modify: `test/architecture-writer-boundary.test.mjs`
+
+**终态白名单（每项带永久 justification）：**
+- `runner/job-runner-legacy.mjs`（或 state-runner/pty-runner 的 disabled 原位分支）——「coordinator_disabled 逃生门，设计内豁免」
+- `src/runtime/service.mjs`——仅当 disabled 分支原位保留时；若收进 service-legacy.mjs 则换成该文件
+- `src/core/store.mjs`——「createView bootstrap 不可能竞争（新 viewId 随机生成，无其他写者知情），永久豁免」
+- 其余条目全部删除；测试断言白名单外零 importer。
+- 更新文件头注释：从「PR #2 迁移并删除条目」改为「设计内豁免清单」。
+- 顺手修 PR #1 的 deferred minor：non-rotting 检查对 importer 条目改用 import-level 正则（mention-level 只留给 store.mjs）。
+
+- [ ] **Step 1–5: TDD → Commit**
+
+```bash
+git -C $WT add test/architecture-writer-boundary.test.mjs
+git -C $WT commit -m "test(arch): shrink writer allowlist to designed exceptions only (issue #91)"
+```
+
+---
+
+### Task 9: 全量回归 + 验收对账
+
+- [ ] `node --test test/*.test.mjs` 全绿 + `npm run typecheck` + 零泄漏进程检查
+- [ ] 验收对账写入 PR 描述：A7 ✅（豁免清单版）；A8 不回归；根治条件 1/2 写侧闭合；根治条件 5 读侧 → PR #3
+- [ ] PR 描述诚实声明：读侧 revision 一致性未启用；coordinator 不可用时 mutation fail-closed（mark-done 显示原始 reason）
+
+## Self-Review 记录
+
+- Spec 覆盖：D3 写侧全覆盖；读侧 enforcement 明确 PR #3（spec §8 分阶段允许）。
+- 与 PR #1 的接口一致性：`TRANSIENT_KINDS`/`PATCHABLE_FIELDS`/新 kind 名在 Task 1 定义、Task 2-6 消费，名称在 Global Constraints 与各 task Interface 块一致。
+- 占位符：无 TBD；Task 6 的「原位保留 vs 收进 legacy 文件」给了明确的取舍指引（实现复杂度低者）。

package/docs/superpowers/plans/2026-09-10-reader-consistency.md

@@ -0,0 +1,115 @@
+# Reader Consistency & Residual Convergence (PR #3, issue #91) Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** 关闭 spec 根治条件 5 的读侧（revision 一致性 enforcement）+ 收敛 PR #2 已知残留（coordinator 硬宕窗口的无 status 文件行）+ 合并后卫生波。完成后 **D3「状态所有权」弧线全部闭合**（写侧 PR #1/#2、读侧本 PR）。
+
+**Architecture:** 三个小面：(1) 决策层让 `run_progress` 在「行存活 + runId 匹配 + status 文件缺失」时从 beat 的全量 patch 自举（部分反转 F2 守卫——F2 防的是稀疏 patch 物化 undefined，而 beat 的 patch 是全量的，且硬宕残留正是需要自愈的场景）；(2) reconcile 作为唯一组合读者，读侧做 revision mismatch 检测——不一致则丢弃组合、踢 ensureCoordinator（boot replay 修复）、记 diagnostic；(3) 卫生波（.catch、双击窗口、JSDoc、warn 措辞、void+catch pass）。
+
+**Tech Stack:** 既有 coordinator/journal/client/决策层（PR #1/#2 已建并稳定）。
+
+**Spec:** `docs/superpowers/specs/2026-09-09-harden-runner-architecture-design.md`（根治条件 5；§5 降级条款）。
+
+## 设计决策（本 plan 锁定）
+
+1. **run_progress bootstrap 是 F2 的部分反转，有边界**：F2 的 `!currentStatus → stale_run` 改为——行 `processState === "alive" && currentRunId === command.runId` 时从 patch 自举（决策层校验 patch 携带 `processState`/`semanticState`/`runId` 一致性后才自举；稀疏或身份不符仍 stale_run）。coordinator 的 `STATUS_BOOTSTRAP_KINDS` 增加 `run_progress`。理由：beat 是 runner 内存中权威状态的全量快照；硬宕残留（mark_queued applied 但 run_started 丢失）下，coordinator 恢复后第一条 beat 即自愈。
+2. **读侧 mismatch 的语义**：reconcile 读 `s.currentRunId` 对应 status 时，若 `state.materializedRevision != null && status?.materializedRevision != null && 二者不等` → 视为不一致：跳过本行投影（不拼）、`appendDiagnostic(code: "state_status_revision_desync")`、异步 `ensureCoordinator(root)`（boot replay 从 journal 修复半物化对）、不计入 fixed。**legacy 行（任一侧无 revision）不检查**——与 spec 的 legacy 迁移条款一致。
+3. **mismatch 只可能来自 coordinator 崩溃窗口**（写侧已全部在 view lock 内配对打戳）；活着的 coordinator 不会产生 mismatch。所以修复路径 = ensureCoordinator spawn → boot replay，无需新命令 kind。
+4. **双击窗口修复选「同步清理」**：`submitDispatch` 在发起异步 dispatch 前**同步**清 `this.launch`/input/mode（不等 .then），消除 coordinator 冷启动 round-trip 期间的重复提交窗口；.catch 兜底 fs 类异常。
+5. **decided-rejection warn 措辞**：job-runner/state-runner 中对 `manual_fence`/`stale_run`/`no_change` 等**确定性拒绝**的分支不再使用「outcome unknown … replay will recover」句式——改为 info 级 `*_skipped` 或措辞明确的 warn（确定性拒绝已 journal，无恢复语义）。
+
+## Global Constraints
+
+- 所有 runner 进程 plain ESM `.mjs`。
+- Commit message 英文 conventional commits；`git add <file>` 显式 stage，禁止 `-A`。
+- 测试 `node --test`；隔离必须同时设 `AGENT_BOARD_ROOT` + `PI_CODING_AGENT_DIR`；coordinator 一律 tracked fixture（`test-support/ensure-coordinator-helper.mjs`，readiness wait + finally kill）。
+- 决策层保持纯函数。
+- 模糊结果（timeout/connection_reset）不回退直写；只有 `coordinator_disabled` 走 legacy 分支。
+- **大 task 时间纪律**：分阶段提交工作增量，保持树常绿（吸取 PR #2 三次超时教训）。
+- `$WT = /home/elling/git-repo/github/pi-agent-board/.pi/worktrees/issue-91-reader-consistency`；全部绝对路径 + `git -C $WT`。
+
+## 验收映射
+
+| Task | 验收目标 | 说明 |
+|---|---|---|
+| Task 1 | 根治条件 5 残留收敛（决策层） | run_progress bootstrap 守卫 + 纯函数测试 |
+| Task 2 | 残留收敛（端到端） | 硬宕场景：beat 自举 → finalize 收敛 |
+| Task 3 | **根治条件 5 读侧闭合** | reconcile mismatch 检测 + 修复踢 + diagnostic |
+| Task 4 | 卫生波 | .catch / 双击窗口 / JSDoc / warn 措辞 / void+catch |
+| Task 5 | 对账 | 全量回归 + 根治条件 1/2/5 全闭合声明 |
+
+---
+
+### Task 1: 决策层——run_progress 缺失 status 时的自举分支
+
+**Files:**
+- Modify: `src/core/state-commands.mjs`
+- Test: `test/state-commands.test.mjs`
+
+**Interfaces:**
+- Consumes: 现有 `run_progress` 分支（~L358：`if (!currentStatus) return reject("stale_run")`）、`applyStatusProjection`。
+- Produces（Task 2 依赖）:
+  - run_progress 分支新语义：
+    - `currentStatus == null` 且 `currentState.processState === "alive" && currentState.currentRunId === command.runId`：校验 `payload.statusPatch` 为自举合格（含 `processState`、`semanticState` 字段且 `statusPatch.runId === command.runId`）→ 以 patch 自身为基座走 applyStatusProjection（基座 = patch 本身，非 `{}`），mutate.status 为全量 patch；
+    - `currentStatus == null` 且行不存活或 runId 不匹配：维持 `stale_run` 拒绝（F2 原语义）；
+    - `currentStatus != null`：原逻辑不变（liveness 守卫 + 投影）。
+  - 更新 F2 的既有测试（`run_progress` 缺 status → stale_run）为分场景：行不匹配仍拒；行匹配 → 自举 applied。
+- [ ] **Step 1: 失败测试**——三个场景（自举 applied + 全量 status patch；行 exited → stale_run；patch 稀疏缺 processState → stale_run）
+- [ ] **Step 2–5: 失败 → 实现 → PASS → Commit**（`feat(core): run_progress bootstraps a missing status from its full patch (issue #91)`）
+
+---
+
+### Task 2: Coordinator——bootstrap kinds 扩展 + 硬宕残留端到端
+
+**Files:**
+- Modify: `runner/state-coordinator.mjs`（`STATUS_BOOTSTRAP_KINDS` 增加 `"run_progress"`）
+- Test: `test/state-coordinator.integration.test.mjs`
+
+**Interfaces:**
+- 端到端回归测试（残留关闭证明）：`mark_queued` applied → **不发 run_started**（模拟硬宕窗口错过）→ 发一条 `run_progress` beat（全量 patch）→ 断言 status 文件自举创建（含 revision 戳）+ state 投影 applied → 再发 `run_finalized` → 断言 applied（此前会 stale_run 拒绝）。全程 journal 只有 mark_queued + run_finalized（beat 不落 journal）。
+- 既有 F2 集成测试同步更新。
+- [ ] **Step 1–5: TDD → Commit**（`feat(runner): beats bootstrap missing status, closing the hard-down window (issue #91)`）
+
+---
+
+### Task 3: 读侧 revision 一致性（reconcile enforcement）
+
+**Files:**
+- Create: `src/core/status-consistency.mjs`（纯函数 helper）
+- Modify: `src/runtime/service.mjs`（reconcile 组合读处）
+- Test: `test/status-consistency.test.mjs` + `test/service.test.mjs`
+
+**Interfaces:**
+- Produces:
+  - `statusRevisionDesynced(state, status)` → boolean：`state?.materializedRevision != null && status?.materializedRevision != null && state.materializedRevision !== status.materializedRevision`（legacy 任一侧缺失 → false，不检查）。
+  - reconcile（~L2022 读 status 处）集成：desynced → `appendDiagnostic(code: "state_status_revision_desync", level: "warn")` + `void ensureCoordinator(root).catch(() => {})`（异步踢修复；boot replay 修复半物化对）+ `continue`（跳过本行，不计 fixed，不拼状态）。
+  - `ensureCoordinator` 需从 `src/core/coordinator-client.mjs` 导出（检查是否已导出；PR #1 Task 5 建过，确认签名）。
+- 测试：纯函数表驱动（desync/一致/legacy 侧缺失/双侧缺失）；service 集成（手动构造半物化对——state 戳 N+1、status 戳 N——reconcile 跳过该行 + diagnostic 落盘 + 不计入 fixed；coordinator spawn 后可另行验证修复，不强求同测试内）。
+- [ ] **Step 1–5: TDD → Commit**（`feat(core): reader-side revision consistency enforcement in reconcile (issue #91)`）
+
+---
+
+### Task 4: 卫生波
+
+**Files:**
+- Modify: `src/ui/dashboard.ts`、`src/runtime/service.mjs`、`runner/job-runner.mjs`、`runner/state-runner.mjs`（措辞）+ 相关调用点（void+catch pass）
+
+**清单（每项独立可验证）：**
+1. `submitDispatch`（dashboard.ts ~L844+）：发起异步 dispatch 前**同步**清 `this.launch`/输入/mode；`.then` 链尾加 `.catch`（notice "Dispatch failed"）。
+2. JSDoc：`launchForView` `@returns` → Promise 形状；`startHostUnderLease` `@returns` 修正。
+3. decided-rejection 措辞：job-runner 的 run_started/finalize 处 `manual_fence`/`stale_run` 分支改 info 级 skipped diagnostic（或明确措辞 warn，不再用 "outcome unknown … replay will recover"）；state-runner 同类分支对齐。
+4. void+catch pass：13 处 `markVisited?.()`、7 处 `service.reconcile()` 调用点加 `void …catch(() => {})`（仅吞 fs 类异常；调用点文件：dashboard.ts、attach-flow.ts、agent-board.ts、index.ts）。
+- [ ] **验证**：受影响套件 + typecheck → Commit（`chore: post-merge hygiene wave — catch guards, dispatch double-submit window, honest diagnostics (issue #91)`）
+
+---
+
+### Task 5: 全量回归 + 验收对账
+
+- [ ] `node --test test/*.test.mjs` 全绿 + `npm run typecheck` + 零测试进程泄漏（按 root 路径区分生产 coordinator）
+- [ ] 对账写入 PR 描述：**根治条件 1/2/5 全闭合**（D3 弧线完成）；3/4/6 属 Phase 3-6；已知残留清单更新（硬宕窗口已关，剩「coordinator 永不回来」= 既有 fail-closed 语义）
+
+## Self-Review 记录
+
+- Spec 覆盖：根治条件 5 读侧 + §5 降级；不越界到 Phase 3-6。
+- 接口一致性：`statusRevisionDesynced`/bootstrap 分支语义/`STATUS_BOOTSTRAP_KINDS` 在 Task 1/2/3 间一致。
+- 无占位符；每个 hygiene 项独立可验证。