@zhuxixi/pi-agent-board 0.7.0 → 0.9.0

package/CHANGELOG.md

@@ -5,6 +5,52 @@ conventional commits by `scripts/release_helper.mjs`. Entries are
 forward-only: they begin with the first release after this file landed —
 for earlier history, see the git log and the pull-request list.
 
+## [0.9.0] - 2026-09-25
+
+### Features
+
+- **attach**: forward terminal queries to the real terminal — automatic theme works in attach sessions (issue #128) (#138)
+- **attach**: unconditional Ctrl+\ detach key, terminal-independent (issue #126) (#137)
+
+### Fixes
+
+- **runner**: probes leave attachedClients at hello (issue #130) (#142)
+- browse-mode Tab completes and drills down directories in cwd picker (issue #127) (#141)
+
+### Changes
+
+- **release**: orchestrate releases and publish from CI (#144)
+- control-reconcile flaky assertions — windowed recorder + invariant realignment (issue #140) (#143)
+- **attach**: scope A5 mid-stream seq assertion to post-snapshot window (issue #132) (#139)
+
+[0.9.0]: https://github.com/zhuxixi/pi-agent-board/compare/v0.8.0...v0.9.0
+
+## [0.8.0] - 2026-09-23
+
+### Features
+
+- **attach**: detach gate reads only editor_state — delete buffer heuristics (issue #91 phase 6, D1) (#135)
+- control command lifecycle — staged acks, durable journal, reconcile, generation token (issue #91 phase 5, D4) (#134)
+- switch attach to snapshot+subscribe with legacy fallback (issue #91 phase 4, D2 closure) (#122)
+- canonical terminal model and capture-and-subscribe protocol (issue #91 phase 3, D2+D5) (#117)
+- reader-side revision consistency, beat bootstrap, and paired-revision invariant (issue #91, D3 arc closure) (#111)
+
+### Fixes
+
+- **attach**: editor-shaped ← detach anchor + restore the editor-state reporter endpoint (issue #103) (#119)
+- **paths**: normalize root before hashing the win32 coordinator pipe name (issue #124) (#125)
+- **locks**: reclaim Windows lease orphans on publish-rename EPERM (issue #114) (#123)
+- **attach**: stop painting the PTY cursor block when the child hides it (issue #102) (#120)
+- **attach**: learn TUI frame cognition in terminal chain states (issue #106) (#118)
+- **host**: reclaim orphaned host-meta locks and add contention diagnostics (issue #112) (#116)
+- foreground preview read-your-writes cache for coordinator write races (issue #113) (#115)
+
+### Changes
+
+- move the A11 perf gate out of coverage instrumentation (issue #121) (#133)
+
+[0.8.0]: https://github.com/zhuxixi/pi-agent-board/compare/v0.7.0...v0.8.0
+
 ## [0.7.0] - 2026-09-10
 
 ### Features

package/README.md

@@ -93,7 +93,7 @@ From the board:
 - In Peek, press `r` to reply without attaching.
 - Press `v` for a read-only transcript, or `e` for evidence and diagnostics.
 - Press `Enter`, `Right`, or `>` to attach to the real Pi session.
-- In PTY attach mode, press `Left` on an empty child input line to return to the board, or `Ctrl+Left` at any time (even mid-draft). `Ctrl+]` is not a detach key — it is passed through to the child Pi editor. When the host is disconnected, `Left` always exits.
+- In PTY attach mode, press `Ctrl+Left` to return to the board at any time (even mid-draft), or `Ctrl+\` — the unconditional escape: it detaches regardless of editor state on any terminal that forwards the raw 0x1c byte (raw, kitty, and modifyOtherKeys keyboard modes all work). `Left` detaches only while the child Pi reports an empty editor; otherwise (draft, or unknown editor state) it is forwarded to the child. `Ctrl+]` is not a detach key — it is passed through to the child Pi editor. When the host is disconnected, `Left` always exits. `Ctrl+\` caveats: on keyboard layouts where `\` sits on AltGr (e.g. German) the chord may never produce the byte — use `Ctrl+Left` there; in legacy keyboard modes `Ctrl+4` emits the same byte and also detaches; and the key is captured from the child while attached, so the child's own `Ctrl+\` binding (e.g. the vim terminal-mode prefix) is unavailable. Automatic themes also resolve correctly in attach sessions: the child's background probe (OSC 11) and color-scheme change notifications are forwarded to your real terminal, replies flow back to the child when your terminal answers, and attach re-probes the background once when it settles so the theme is right from the first frame. Set `AGENT_BOARD_FORWARD_TERMINAL_QUERIES=0` to disable this (default on); keyboard-protocol negotiation (kitty/DA) is not forwarded — it happens once at child spawn, before attach exists.
 
 ## Dashboard Workflow
 
@@ -192,7 +192,9 @@ The `e` view shows durable session evidence, including changed files, commands a
 
 ### PTY attach
 
-PTY attach opens the real interactive Pi session. On an empty child input line, use `Left` to detach and return to the board; while you are editing text, `Left` is forwarded to the Pi editor, `Ctrl+Left` detaches regardless of editor state, and a disconnected host can always be exited with `Left`. `Ctrl+]` is not a detach key — it is passed through to the child Pi editor. While attached, `PageUp`, `PageDown`, `Home`, `End`, and the mouse wheel scroll local scrollback. Mouse drag or double-click selects and copies text, clicks open detected links, and middle-click paste is available on systems with the required X11 tooling.
+PTY attach opens the real interactive Pi session. `Ctrl+Left` detaches and returns to the board regardless of editor state, and `Ctrl+\` is the unconditional escape — a single raw ASCII byte (0x1c) that terminals forward unchanged in raw mode (kitty CSI-u and modifyOtherKeys encodings included), honored no matter what the child editor reports. `Left` detaches only while the child Pi reports an empty editor; while you are editing text — or when the child's editor state is unknown (e.g. the child extension is missing) — `Left` is forwarded to the Pi editor. A disconnected host can always be exited with `Left`. `Ctrl+]` is not a detach key — it is passed through to the child Pi editor. `Ctrl+\` caveats: on keyboard layouts where `\` sits on AltGr (e.g. German) the chord may never produce the byte — use `Ctrl+Left` there; in legacy keyboard modes `Ctrl+4` emits the same byte and also detaches; and the key is captured from the child while attached, so the child's own `Ctrl+\` binding (e.g. the vim terminal-mode prefix) is unavailable. While attached, `PageUp`, `PageDown`, `Home`, `End`, and the mouse wheel scroll local scrollback. Mouse drag or double-click selects and copies text, clicks open detected links, and middle-click paste is available on systems with the required X11 tooling.
+
+Automatic light/dark themes work in attach sessions too. The child Pi's background-color probe (OSC 11) and its color-scheme change notification switch are forwarded to your real terminal; replies and notifications flow back to the child when your terminal answers — a terminal that never answers keeps the dark fallback. Attach also re-probes the background once when it settles, so the theme is correct from the first frame without re-selecting it in `/settings`. All of this is on by default; set `AGENT_BOARD_FORWARD_TERMINAL_QUERIES=0` to disable it. Not covered: keyboard-protocol negotiation (kitty flags / DA1) is not forwarded — the child negotiates once at spawn, before any attach client exists, and forwarding it would retune the shared real-terminal keyboard stack — so modifier-key encoding can still differ from a directly-run Pi (the modifyOtherKeys fallback applies).
 
 The attach surface can forward terminal clipboard and image/file passthrough sequences. These behaviors can be disabled individually in [Configuration](#configuration). Cold hosts may briefly show a loading/reconnect surface while their PTY becomes ready.
 
@@ -314,6 +316,9 @@ Set these variables before starting Pi. Model-backed features fall back graceful
 | `AGENT_BOARD_FORWARD_OSC52` | enabled; `0` disables | Disable OSC 52 clipboard sequence forwarding from an attached session. |
 | `AGENT_BOARD_FORWARD_IMAGES` | enabled; `0` disables | Disable terminal image/file passthrough forwarding from an attached session. |
 | `AGENT_BOARD_IME_FIX` | enabled; `0` disables | Disable the attach-view IME cursor coalescer if your terminal has compatibility problems. |
+| `AGENT_BOARD_TERMINAL_SNAPSHOT` | enabled; `0` forces legacy | Force the pre-phase-4 attach path (screen.log replay + jiggle); escape hatch / rollback switch for the snapshot+subscribe attach protocol. |
+
+`AGENT_BOARD_TERMINAL_SNAPSHOT=0` routes attach onto the legacy fallback family: the screen.log replay tail plus the shrink-and-hold jiggle redraw. These paths exist only for pre-protocol runners and as a rollback hatch — they are not part of the snapshot+subscribe protocol path (issue #91 phase 4). They will be retired once the installed runner fleet is on the snapshot protocol baseline (detectable on the wire via hello protocol fields).
 
 Older `AGENT_VIEW_*` names are still read in selected compatibility paths. Prefer `AGENT_BOARD_*` for new setups. Internal child markers are managed by Agent Board and are not user settings.
 
@@ -376,23 +381,21 @@ npm install
 npm run verify
 ```
 
-`npm run verify` runs typecheck, tests, coverage, and a package dry-run. The same checks run in CI on Node 22 and Node 24. See [VERIFY.md](VERIFY.md) for the full verification checklist and known environment-dependent limitations.
+`npm run verify` runs typecheck, the perf gate (`npm run test:perf`), tests, coverage, and a package dry-run. The A11 perf assertions are opt-in — they skip under `npm test` / `npm run test:coverage` and only measure via `npm run test:perf` (issue #121). The same checks run in CI on Node 22 and Node 24. See [VERIFY.md](VERIFY.md) for the full verification checklist and known environment-dependent limitations.
 
 ## Publishing
 
-Before publishing a release, verify the package, generate the changelog, then bump, and publish — the changelog must be generated **before** `npm version`, because `npm version` commits and tags the bump, which would empty the generation range:
+Releases run through `scripts/release.mjs` and are published by CI when a GitHub Release is created. The flow checks the parts that are easy to get wrong — the changelog range, tag ancestry against `main`, and drift from a late merge — instead of assuming them. See [docs/RELEASE.md](docs/RELEASE.md) for the full process, the one-time npm trusted-publisher setup, and failure recovery.
 
 ```bash
-npm run verify
-npm run changelog -- --dry-run     # preview the next section (version = current + patch)
-npm run changelog -- patch         # inserts the section into CHANGELOG.md
-node scripts/release_helper.mjs verify   # must exit 0: no functional PR missing from the top section
-git add CHANGELOG.md && git commit -m "docs(changelog): <version>"
-npm version patch                  # bumps package.json, commits, and tags vX.Y.Z
-npm publish
+node scripts/release.mjs precheck          # gate: clean main, nothing in flight
+node scripts/release.mjs prepare minor     # changelog + verify + bump + tag + release branch
+node scripts/release.mjs open-pr 0.9.0     # push the branch and tag, open the release PR
+# merge the PR with a merge commit, then:
+node scripts/release.mjs finish 0.9.0      # GitHub Release → CI publishes to npm
 ```
 
-Use `minor`/`major` in both the changelog and `npm version` steps when appropriate. The changelog is generated from conventional commits since the last `vX.Y.Z` tag (`scripts/release_helper.mjs`, ported from the jfox release flow); review the preview before committing. The `verify` step guards against PRs merged after the changelog was generated — rerun it after any late merge and, after removing the stale top section, re-run `npm run changelog -- <bump>` if it reports missing PRs (apply refuses when the section already exists — remove the stale section first). Release notes for the GitHub Release are the top CHANGELOG section. After publishing, users install the scoped package with:
+After publishing, users install the scoped package with:
 
 ```bash
 pi install npm:@zhuxixi/pi-agent-board
@@ -403,6 +406,7 @@ The Pi package gallery uses the `pi.video` and `pi.image` URLs from `package.jso
 ## Further Reading
 
 - [Manual verification](VERIFY.md) — static checks, Pi loading, provider authentication, persistence, and dashboard flows.
+- [Release process](docs/RELEASE.md) — release commands, trusted publishing setup, and failure recovery.
 - [Product requirements](PRD.md) — original product scope and design context.
 - [Progress log](PROGRESS.md) — implementation checkpoints and known environment notes.
 - [Exploration notes](docs/EXPLORATION.md) — Pi API and integration research.

package/VERIFY.md

@@ -10,7 +10,8 @@ Steps you can run yourself to check the extension. Grouped from "no auth needed"
 ```bash
 npm install          # dev + runtime deps
 npm run typecheck    # expect: 0 errors
-npm test             # expect: 0 failures
+npm run test:perf    # expect: `burst:`/`paced:` value lines, pass 3 / skipped 0 — the ONLY path that measures perf assertions; they skip under npm test (issue #121)
+npm test             # expect: 0 failures (the 3 A11 perf tests skip here, reason points at `npm run test:perf`)
 npm run pack:dry     # expect: pi-agent-board-<version>.tgz contents only include deploy files
 ```
 

package/docs/PTY_ATTACH_IMPLEMENTATION_PLAN.md

@@ -282,6 +282,8 @@ Runner → client:
 
 For attach, the parent sends raw input bytes through `input`. The attach surface intercepts only `←` when the child input line appears empty; all other keys, including Pi's native `ctrl+]` editor shortcut, pass through to the child.
 
+> **Historical:** superseded by the editor_state side channel (issue #91 Phase 6) — `←` now detaches only when the child pushes `editorEmpty=true`; otherwise (draft or unknown state) it is forwarded to the child. `Ctrl+←` always detaches.
+
 The detach chord is `←` because it is already the board navigation key and preserves Pi editor keybindings.
 
 ## 6. Attach UI design
@@ -560,7 +562,7 @@ MVP live attach is accepted when:
 | child Pi extension recursion | medium | `AGENT_BOARD_CHILD=1`; skip dashboard auto-open/footer in child |
 | host liveness conflated with agent activity | high | add `host.json`; separate `hostAlive` from `row.alive` |
 | worktree safety too conservative with idle hosts | low/medium | conservative MVP, later refine with activity state |
-| `←` is also a child-editor cursor key | low | detach only when the child input line appears empty; keep all other editor shortcuts, including `ctrl+]`, pass-through |
+| `←` is also a child-editor cursor key | low | detach only when the child input line appears empty; keep all other editor shortcuts, including `ctrl+]`, pass-through. **Superseded (issue #91 Phase 6):** detach now gates on the pushed `editorEmpty` state, not the rendered buffer; `Ctrl+←` always detaches |
 | terminal images/OSC links not perfect in virtual renderer | medium | document limitation; raw takeover/core API if needed |
 
 ## 13. Confidence

package/docs/RELEASE.md

@@ -0,0 +1,148 @@
+# Release process
+
+Releases are driven by `scripts/release.mjs` and published by CI when a GitHub
+Release is created. Four commands and one merge:
+
+```
+precheck  →  prepare <bump>  →  open-pr <version>  →  merge (merge commit!)
+          →  finish <version>  →  .github/workflows/publish.yml publishes to npm
+```
+
+`main` is protected, so a release lands as a pull request — but the npm publish
+is not tied to that PR: it is tied to the GitHub Release, which is created only
+after the PR is merged and the tag is confirmed to be on `main`.
+
+## One-time setup: the npm trusted publisher
+
+`publish.yml` publishes with **trusted publishing** (OIDC), so no `NPM_TOKEN`
+secret is stored in the repository. npm has to be told which workflow may
+publish the package — this is a one-time, per-package web step:
+
+1. Open <https://www.npmjs.com/package/@zhuxixi/pi-agent-board> and sign in as
+   the package owner.
+2. Go to **Settings** → **Trusted Publisher** → **GitHub Actions**.
+3. Fill in: organization `zhuxixi`, repository `pi-agent-board`, workflow
+   filename `publish.yml`, environment left empty.
+4. Save.
+
+Until this is configured, the CI publish step fails with an authentication
+error. Publishing locally (the pre-2026-09 flow, see "Local publish fallback"
+below) still works, because the npm account keeps its normal credentials.
+
+## Commands
+
+### `node scripts/release.mjs precheck`
+
+Read-only gate. Run it before anything else; it fails closed when the tree is
+dirty, `main` is not in sync with `origin/main`, a `release/*` PR is still open,
+the last tag is not an ancestor of `origin/main` (an orphan tag from a past
+squash merge), or there is nothing functional to release.
+
+### `node scripts/release.mjs prepare <patch|minor|major|X.Y.Z> [--dry-run]`
+
+Runs the gate, then:
+
+1. renders the new CHANGELOG section from the conventional commits since the
+   last `v*` tag,
+2. commits it as `docs(changelog): add <version> section`,
+3. runs `npm version <bump>` — one commit plus the annotated `v<version>` tag,
+4. switches to `release/v<version>`.
+
+Nothing leaves the machine. `--dry-run` prints the section and the plan without
+writing anything; review the preview before running it for real. Pick the bump
+the same way as before: features are a `minor`, fixes alone are a `patch`.
+
+### `node scripts/release.mjs open-pr <version> [--dry-run]`
+
+Pushes the release branch and the tag, then opens the PR with the CHANGELOG
+section as its body. The tag is pushed separately because tags are not covered
+by the branch protection rule.
+
+### Merge the PR with a merge commit
+
+**Do not squash the release PR.** `npm version` created the tag on a commit that
+only exists on the release branch; a merge commit brings that commit into
+`main`, a squash does not, and the tag becomes unreachable from `main`
+(`git describe` then misreads the changelog range of the next release). Use the
+**Merge pull request** button, or `gh pr merge --merge`.
+
+### `node scripts/release.mjs finish <version> [--dry-run] [--sync-main]`
+
+Run it after the merge. It fetches, verifies that `v<version>` is an ancestor of
+`origin/main`, re-checks the CHANGELOG against any functional PR merged after the
+bump, and then creates the GitHub Release with the CHANGELOG section as its
+notes. That release is the publish trigger. `--sync-main` also resets a clean
+local `main` to `origin/main`, dropping the local copy of the two release
+commits (they are content-equal to what the merge brought in).
+
+To publish without the orchestration, the underlying commands are
+`gh release create v<version> --title v<version> --notes-file <notes>` where the
+notes are `node scripts/release.mjs notes <version>`.
+
+## What CI does
+
+`.github/workflows/publish.yml` runs on `release: published`, checks out the
+tag, and:
+
+1. asserts npm is at least 11.5.1 (trusted publishing needs it; Node 24 ships
+   a newer one),
+2. asserts the tag equals `package.json`'s version,
+3. runs `npm run typecheck` and `npm test`,
+4. skips the publish when that version is already on npm, and otherwise
+5. runs `npm publish --provenance --access public`.
+
+Provenance means npm records which repository, workflow, and commit built the
+tarball, and shows it on the package page.
+
+## Recovering from a broken release
+
+**Orphan tag** (`finish` refuses with "not an ancestor of origin/main"). The
+release PR was squash-merged. Re-point the tag at the content-equivalent commit
+on `main`, then retry:
+
+```bash
+git fetch origin
+git tag -f v0.9.0 <sha on origin/main with the same content>
+git push origin v0.9.0 --force
+node scripts/release.mjs finish 0.9.0 --sync-main
+```
+
+**CHANGELOG drift** (`finish` refuses with missing PR numbers, or
+`node scripts/release_helper.mjs verify` exits 1). A functional PR merged after
+the changelog section was generated. Add the missing entries to the top section
+in a `docs(changelog)` PR, merge it, then retry — the release notes are read
+again at that point, so the fix is picked up.
+
+**The publish failed** (npm outage, trusted publisher not configured yet).
+Re-run the same tag without recreating the release: Actions → **Publish to
+npm** → **Run workflow** → enter the tag.
+
+**`npm view <package>` returns 404 right after a successful publish.** That is
+the registry's view index lagging, not a failed publish. Compare endpoints: the
+tarball, `/<package>/latest`, and `/-/package/<package>/dist-tags` answer
+immediately while the root document 404s for a few minutes. Wait; re-publishing
+the same version is rejected with a 403 and is never the fix.
+
+**Local publish fallback.** When the trusted publisher is not configured and a
+release cannot wait:
+
+```bash
+npm run verify
+npm publish --registry=https://registry.npmjs.org --access public
+```
+
+The registry must be passed explicitly: this machine defaults to
+`registry.npmmirror.com`. This path skips provenance and the CI checks, so
+prefer fixing the CI path.
+
+## CHANGELOG conventions
+
+`scripts/release_helper.mjs` renders the section from conventional commits in
+the range `<last v* tag>..HEAD`. `feat`/`fix`/`perf` become Features / Fixes /
+Performance, everything else (including `test` and `docs`) lands under Changes,
+merges and `npm version` squash subjects are skipped, and `docs(changelog):`
+subjects are ignored so changelog fixes do not feed back into the verify check.
+
+Every entry carries the PR number parsed from the trailing `(#N)`. `verify`
+fails when a functional commit's PR is missing from the top section — that is
+what keeps a late merge from shipping without release notes.

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 项独立可验证。