@zhuxixi/pi-agent-board 0.7.0 → 0.8.0

package/CHANGELOG.md

@@ -5,6 +5,32 @@ 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.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). `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.
 
 ## Dashboard Workflow
 
@@ -192,7 +192,7 @@ 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. `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. 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.
 
 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 +314,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,7 +379,7 @@ 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
 

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