@zhuxixi/pi-agent-board 0.9.0 → 0.10.0

package/docs/superpowers/specs/2026-09-30-issue-95-test-discipline-design.md

@@ -0,0 +1,226 @@
+# Spec — issue #95: real-process tests must not flake (runner stop-safety + budget/diagnosis discipline)
+
+Status: **branch spec (refreshed 2026-09-30 late): tonight's scope = F3 → F2 → F4 only** · Base: `main@43dca95` (2026-09-30) · Route: bug → systematic-debugging
+
+## Delivery status (2026-09-30)
+
+- **F1 delivered by #153 / PR #155** (squash `43dca95`, merged 23:34): stop latch + `stop_latch_replayed`; A1–A4 and A10 all green there, CR two-stream Round-1 PASS.
+- **A10's convergence fix also landed in #153** (`loadRow` recorded-pid-wins-over-mirror).
+- Acceptance matrix below is narrowed to what remains on THIS branch: **A5, A6, A7, A8** (+ A9 stays open as the 14-day CI observation; A11 N/A while D4 = defer; A12 N/A while D1 = O3).
+- F5 (serialization) stays deferred per D1 = O3 — the observation window is running; tonight's three flake observations are its first baseline samples.
+- F7 (issue trail) is complete: research conclusions + falsified-claim corrections are on the issue thread.
+Research: `research/2026-09-30-runner-stop-window-race.md`, `research/2026-09-30-flake-inventory-and-cost.md`
+
+## 1. Root-cause revision (this round's main result)
+
+The issue's previous framing — "CI machine is slow, the tests need bigger wall-clock budgets"
+(comment 1 §三) — is **falsified for the highest-frequency failure**
+(`stopping the runner finalizes the run as stopped`).
+
+`runner/job-runner.mjs` publishes an observable `working` state (via the coordinator's
+`run_started`, which creates `status.json`) **before** it spawns the worker and **before** it
+installs `process.on("SIGTERM", stop)` (`:95-112` vs `:356-371`). A stop request that lands in
+that window kills the runner with Node's default action: no `finalizeRun`, no `run_finalized`,
+no `endedAt`, no diagnostics. Proven by a controlled experiment (inject the window → 3/3
+deterministic failures; add an early stop latch → 3/3 passes; unmodified runner under load →
+2/2 failures locally, and the same signature appears in CI on 09-25 and 09-30 with
+`duration_ms ≈ 15200` against a 15 s internal wait).
+
+Sample-size honesty: each experiment arm is n = 2–3. The claim rests on the mechanism closing
+the loop — widen the window and the failure becomes deterministic, arm the latch and it
+disappears — not on the counts themselves.
+
+This is reachable in production: `archiveView()` kills the current run pid with SIGTERM
+(`src/runtime/service.mjs:726-735` → `killProcess`), so archiving/stopping a **just-started**
+run can leave the row pinned at `working/alive`. Whether anything then converges such a row
+(reconcile / pid-liveness watching) is **unverified** — promoted to acceptance item A10.
+
+The other three known signatures (the host-concurrency `A10` resolver burn,
+`subscribe_terminal` 15 s, `A5 burst` 30 s) were **not** re-proven; they stay in scope as "unexplained until the failure can name its
+own blocked step" (→ F3).
+
+## 2. Deliverables
+
+### F1 — Runner stop-safety (production fix) — *primary*
+
+Invariant: **no non-terminal state may be observable before the process can handle a stop, and
+a SIGTERM/SIGINT delivered at any time after the module is loaded must produce a terminal
+state.**
+
+Platform scope: the latch/handler mechanism is **Unix-only**. On Windows, Node's `process.kill`
+ignores the signal name and hard-kills the target — no handler can ever run — so the
+boot-window loss is unfixable at the signal layer there. Either Windows stays out of scope
+(current behaviour unchanged, recorded in Non-goals) or D2 option (d) is chosen, which does not
+depend on signals being catchable.
+
+Design (testability split):
+
+| Layer | Artifact | Kind |
+|---|---|---|
+| Pure state machine | `src/core/stop-latch.mjs` — `createStopLatch()` → `{ note(signal), pending(), take() }` (idempotent note, single take, SIGINT/SIGTERM collapse) | pure |
+| I/O shell | `runner/job-runner.mjs` — handlers installed at module scope; `take()` replayed into the existing `stop()` once it exists; emits a `stop_latch_armed` diagnostic as the run's **first** diagnostic, before the coordinator bootstrap | side-effectful |
+| Test-only window | `AGENT_BOARD_TEST_BOOT_WINDOW_MS` delaying the runner between `run_started` and the spawn, so the window can be hit deterministically instead of by luck | side-effectful, test-only |
+
+The test knob lives in a production file, so it carries the same guard as F4's knobs:
+`AGENT_BOARD_TEST_*` naming, a unit test proving it is inert when unset, and a behaviour test
+proving it actually widens the window (it must not be able to rot into a no-op).
+
+Replay semantics (this is what D2 weighs): with the latch alone, a stop landing in the window
+is *remembered*, the runner continues, spawns the worker, and the replayed `stop()` kills it
+immediately after the handlers are wired — i.e. a doomed worker really is spawned once.
+D2 (b) avoids that wasted spawn by publishing `run_started` only after spawn + handler wiring,
+at the cost of reordering the bootstrap (the coordinator's `run_progress` needs a materialized
+status).
+
+### F2 — Budget audit gate (mechanical discipline)
+
+`scripts/budget-audit.mjs` with pure exports `parseTestBudgets(source)` / `auditBudgets(files)`:
+- rule (a): a test declaring `{ timeout: T }` must satisfy `T ≥ max(single explicit wait in the
+  body) + margin`, where **`margin = max(5 000 ms, wait / 3)`** (a named constant in the audit
+  script, unit-tested). Summing all waits would demand 120 s+ timeouts for multi-wait files
+  (`terminal-snapshot` alone has four 30 s waits) — re-inflating the very budgets this issue
+  retires;
+- rule (b): a test that drives an app-level deadline ≥ 30 s must declare a timeout ≥ that
+  deadline **unless** it goes through an F4 knob, in which case `// budget: knob` exempts it
+  (static analysis cannot know a runtime knob compressed the deadline);
+- escape hatch: an inline `// budget: <reason>` comment exempts the line (audited by the unit test).
+
+Known tension, stated openly: derived budgets are still wall-clock numbers. The audit buys
+*accountability* — no unsatisfiable nesting, every number carries a recorded reason — not
+immunity to slow machines; that part is F1/F3/F4's job.
+
+Amends the two inversions the spec predicted rather than fixing them as written:
+`test/runner.integration.test.mjs:282` already satisfies rule (a) under max+margin
+(20000 ≥ 15000 + 5000) and needed no change; the delivered fixes are the two rule-derived
+widenings (`test/pty-attach-cold-start-e2e.test.mjs`'s slow-boot test 30000 → 35000 and
+`test/runner.integration.test.mjs:489` 30000 → 35000) plus `host-concurrency A10`'s explicit
+`// budget:` escape. Wired as `test/budget-audit.test.mjs` so `npm test` enforces it, plus
+unit fixtures that must fail.
+
+### F3 — Failure self-diagnosis (the next red names its own blocked step)
+
+`test-support/flake-postmortem.mjs`: pure `formatPostmortem({ status, state, host, diagnosticsTail, journalTail })`
+→ human-readable "last observed" block; I/O shell `capturePostmortem(root, viewId, runId)`; the
+four flaky helpers' `waitFor` wrappers attach it to the assertion error on timeout.
+Unit tested with fixtures (missing file, truncated tail, absent diagnostics).
+
+### F4 — Test-only ladder knobs (stop paying production grace)
+
+Expose test-scoped overrides for the wall-clock ladders that tests currently have to wait out:
+`HOST_START_GRACE_MS`, `HOST_RECOVERY_GRACE_MS`, `HOST_RECOVERY_POLL_MS`,
+`ATTACH_RESOLVE_TIMEOUT_MS` (`src/runtime/service.mjs:61-69`), `HOST_PROBE_TIMEOUT_MS`,
+`ATTACH_RECONNECT_TIMEOUT_MS`. Names are `AGENT_BOARD_TEST_*`-scoped; production defaults stay
+byte-identical when unset (unit-tested), and a test asserts the knob actually changes behaviour
+(so it can never rot into a no-op).
+
+Testability split: each constant gains a pure reader beside its definition — e.g.
+`resolveHostStartGraceMs(env = process.env)` returning override-or-default — and the I/O shell
+is reduced to passing `process.env` at the call site. Unit tests: unset ⇒ default byte-identical;
+set ⇒ override used; invalid value ⇒ default plus one warn diagnostic. The integration proof
+(A7) drives the host-concurrency `A10` recovery chain under the knob with a shortened budget.
+
+### F5 — Serialization (only if D1 says so)
+
+- O1: two-phase runner (`scripts/run-tests.mjs`) used by `test` / `test:coverage`: phase 1 =
+  real-process files (concurrency 1 or 2), phase 2 = the rest. No `ci.yml` change.
+- O2: split the CI step into two steps (`ci.yml` change).
+- O3: defer; re-measure after F1–F4 (the issue's own "若再红则升级串行方案" clause).
+  Measurement plan so O3 is falsifiable: count in-scope CI reds (failures matching the research
+  note's §3 signatures, or any new real-process red) per week, recorded in the issue thread;
+  observation window 14 days. Zero in-scope reds ⇒ close the issue; any in-scope red ⇒
+  revisit D1 with the accumulated evidence.
+Cost, recomputed from the same TAP model with honest makespan arithmetic (today's 67.7 s ≈
+max(45 s largest file, 321 s ÷ 3); the two phases are **sequential, they do not overlap**):
+two-lane ≈ 110 s (phase 1 at c=2) + 35–50 s (phase 2 at c=3) = 150–175 s → **+80–105 s
+(≈ +1.5 min) per CI job**; fully serial ≈ 260 s → **+3–3.5 min per job**. The same delta lands
+on every local `npm test` run. CI re-measurement stays mandatory before these numbers are
+treated as final.
+
+### F6 (optional) — Test hygiene
+
+924 leaked `/tmp/agentview-*` roots (9.7 MB) and one observed leaked detached coordinator.
+Scope if chosen: remove the roots in the leaking suites, add a static "no unremoved mkdtemp root"
+check, and a post-run assertion that no detached coordinator survives a test file.
+
+### F7 — Issue trail & fact correction (documentation, no code)
+
+Two actions inside the plan (not commit content): (1) post this round's research conclusions —
+the root-cause experiment table and the revised framing — as comments on issue #95; (2) correct
+the now-falsified claims in the thread, chiefly comment 1 §三's "环境问题而不是生产缺陷" and the
+budget-widening direction, so a future reader cannot re-derive the wrong design from the
+thread. This recovers the "comment-fact correction" decision point referenced in issue comment 3
+(the 09-25 spec draft it pointed to never landed on disk and was lost).
+
+## 3. Acceptance matrix
+
+| ID | Item | Verification type | Concrete check | Pass criterion |
+|---|---|---|---|---|
+| A1 | A stop signal inside the boot window still finalizes the run | integration (deterministic) | new `test/runner-stop-window.integration.test.mjs`: inject `AGENT_BOARD_TEST_BOOT_WINDOW_MS`, SIGTERM inside the window, and a second leg without injection | both legs: `status.json.endedAt != null` and `semanticState === "stopped"` |
+| A2 | Stop latch state machine | unit | `test/stop-latch.test.mjs` | note/take/repeat/no-signal paths covered; no double-fire |
+| A3 | "Nothing observable before stop is handleable" ordering | integration | assert `stop_latch_armed` is the **first entry** of the run's `diagnostics.jsonl` (ahead of the existing `runner_start`) — a single-file observable, no cross-file timestamp comparison | any other first entry fails the test |
+| A4 | The regression case survives load | integration (repeat) | 20 consecutive local runs of `test/runner.integration.test.mjs` while the full suite runs in parallel — **one-time acceptance procedure, not a recurring CI test** | 20/20 green (baseline: 2–3 failures in the first few runs before the fix) |
+| A5 | Budget audit gate | unit + static | `test/budget-audit.test.mjs` over fixtures **and** the real `test/` tree | fixtures with known inversions are reported; real tree reports zero violations |
+| A6 | Failure self-diagnosis | unit + integration | `formatPostmortem` fixtures (missing file, truncated tail) + the wrapped `waitFor` exercised with a **stubbed always-false predicate and a tiny real timeout** — no 15 s burn inside `npm test` | the failure message contains status/state/host/diagnostics excerpts and a "last observed state" line |
+| A7 | Ladder knobs | unit + integration | knob set/unset comparison, then the host-concurrency `A10` chain re-driven under the knob | unset ⇒ production defaults unchanged; set ⇒ same assertions pass with a shorter budget |
+| A8 | Full gate | static + build | `npm run verify` (typecheck, perf gate, tests, coverage thresholds, pack:dry) | exit 0 |
+| A9 | CI observation | automated E2E (CI) | ≥5 consecutive CI runs **or ≥2 days**, whichever comes first, after merge (matches the issue's original acceptance direction) | no in-scope red (other issues excluded explicitly) |
+| A10 | A dead-runner row is converged | integration | construct the boot-window death (runner killed after `run_started`, no `endedAt`); **locate** whichever convergence path actually exists (reconcile / refresh / sweeper) and drive it | a located path converges the row within 15 s; no path found, or no convergence ⇒ **blocking finding** and F1's scope extends with the convergence fix — U1 depends on it |
+| A11 | No leaked roots / processes (enforced only if D4 = yes) | static + integration | leak audit over `test/` + post-run process check | zero unremoved temp roots; zero surviving detached coordinators |
+| A12 | Two-phase runner is faithful (enforced only if D1 ≠ O3) | static + integration | one local run of the two-phase wrapper: aggregated test count vs the single-phase run; `npm run test:coverage`; record the wall-clock delta | identical test count (no double-run, no skip); coverage thresholds still pass; measured wall-clock delta within the bound declared in F5 |
+| U1 | User-observed: stop/delete a just-started run | user | on an installed build, archive/stop a row seconds after its run starts | the row reaches a terminal state (stopped/archived), never stuck at `working` |
+| U2 | User-observed: two days of normal use | user | daily board use | no row stuck at `working` without an error and without a converge/reconcile step |
+
+Automated items must be executed and recorded with their real commands in the PR; U1/U2 stay
+`pending` until the user runs them (they cannot be replaced by A-items).
+
+## 4. Decisions requested
+
+- **D1 (scope of serialization)**: O1 two-phase local-runner (no `ci.yml`) / O2 CI split /
+  O3 defer until F1–F4 are measured. Cost: see F5. **Recommendation: O3** — the proven defect
+  is F1, and the measurement plan makes revisiting D1 cheap and evidence-based.
+- **D2 (F1 shape)**: (a) module-scope latch replaying into `stop()` — a stop in the window
+  results in spawn-then-immediate-kill of a doomed worker (cheap, experimentally proven);
+  (b) publish `run_started` only after spawn + handler wiring — no wasted spawn, but reorders
+  the bootstrap and must re-prove the progress-beat path; (c) both; (d) durable stop-intent
+  marker (file / coordinator command) instead of a signal — the only option that also fixes
+  Windows, at materially higher design cost. **Recommendation: (a) now** — cheap and
+  experimentally proven; (d) stays parked as the long-term open question (§7).
+- **D3 (packaging)**: does F1 ship as **its own issue/PR** (it is a production defect found via
+  the test) with #95 keeping only the test-discipline work F2–F5, or does everything ride one
+  branch? Recommendation: split — F1's review question ("can a stop be lost?") is unrelated to
+  #95's review question ("is the suite stable?"), and F1 can merge first. If split: A1–A4 and
+  A10 travel with the F1 issue (they verify F1 alone); A5–A8, A11 stay here; ordering
+  constraint — **F2's budget fix for `runner.integration.test.mjs:282` must land after F1**, or
+  the budget change papers over the race again; and F7's comments cover both issues.
+- **D4 (optional F6 hygiene)**: include or defer. **Recommendation: defer** — cheap but
+  orthogonal; fold it into whichever branch lands last.
+
+## 5. Non-goals
+
+- No further wall-clock widening (40 → 90 → 150 s is the pattern being retired).
+- `ci.yml` untouched unless D1 chooses O2.
+- No reopening of #121 / #132 / #140; no changes to the attach subsystem's behaviour.
+- If D2 ≠ (d), Windows stop-safety is explicitly out of scope: signals are uncatchable there,
+  current Windows behaviour is unchanged, and that limitation is documented.
+- Serialization is not allowed to double-run tests or to break coverage aggregation.
+
+## 6. Risks
+
+| Risk | Mitigation |
+|---|---|
+| Residuum: a SIGTERM during module *import* (before the latch exists) still exits by default — but nothing has been published yet, so no observable state is lost | Documented as a known window; A3 pins "no observable state before the latch" |
+| F2's source regex mis-parses an exotic test shape | Minimal rules + explicit `// budget:` escape hatch + fixtures; audit is unit-tested |
+| F4 knobs leaking into production semantics | `AGENT_BOARD_TEST_*` naming, unit test asserting defaults are unchanged when unset, and a behaviour-change test |
+| F1 changes runner startup order (D2 b/c) and breaks the progress beat | Only considered if D2 = b/c; the coordinator's `run_progress` requires a materialized status, so the bootstrap order must be re-verified by the integration suite before landing |
+| Windows: signals cannot be caught at all (Node hard-kills on `process.kill`), so F1's mechanism cannot restore stop-safety there | D2 (d) is the only complete fix; with D2 = a/b/c the Windows behaviour is unchanged and recorded as a Non-goal |
+| The boot-window knob is a test hook inside a production file | Same guard as F4: `AGENT_BOARD_TEST_*` naming + inert-when-unset unit test + behaviour test (see F1) |
+| "Reconcile converges the stuck row" turns out to be false | A10 verifies it explicitly and is a blocking gate for U1; a negative result extends F1 rather than shipping a silent gap |
+
+## 7. Open questions (explicitly not scope)
+
+- Do `runner/pty-runner.mjs` (handlers at `:530`/`:754`) and `runner/state-coordinator.mjs`
+  (`:199`) have the same boot window — an observable state published before their handlers
+  exist? Not audited this round; F1 covers `job-runner` only. If the audit finds the same
+  pattern, that is a follow-up issue, not scope growth here.
+- Should the stop path migrate to a durable stop-intent marker for all platforms long-term
+  (supersedes D2 (d))? Parked until F1 lands and the residual failure modes are known.

package/docs/superpowers/specs/2026-09-30-publish-dispatch-tag-check-design.md

@@ -0,0 +1,129 @@
+# Spec：publish.yml 手动恢复后门的 tag 来源修复（issue #154）
+
+日期：2026-09-30 · 状态：**approved（用户确认方案 A，范围 A1–A4 + U1 全量）· 勘误（同日双审后）：A1 拆分为 A1a/A1b、A2 重写为探针 tag 法、A3 断言加严为计数 ≥2，改动点在各条目内注明**
+基线：`main @ 444199d`
+调研：issue #154 评论「调研：根因三源交叉验证」/ `~/.claude/github-issue-driven/zhuxixi/pi-agent-board/issue-154/research/root-cause.md`
+
+## 1. 问题陈述
+
+`docs/RELEASE.md:117-118` 记载的恢复路径——「Actions → **Publish to npm** → **Run workflow** → enter the tag」——按字面操作 100% 失败：从 `main` 触发手动恢复时，workflow 在第一个自检步骤退出 1，typecheck / 测试 / 发布全部未执行。
+
+后果是「文档承诺的自救路径是死的」：必须知道文档外的 `--ref <tag>` 绕法才能恢复一次发布，而失败信息（`tag: main`）看起来像发布内容出错，会把操作者引向错误方向。
+
+## 2. 根因（systematic-debugging 结论）
+
+### 2.1 一句话根因
+
+`.github/workflows/publish.yml:57` 把 **ref 名**当成 **本次要发布的 tag** 使用：
+
+```yaml
+TAG_VERSION="${GITHUB_REF_NAME#v}"
+```
+
+`GITHUB_REF_NAME` 的含义随触发方式变化，而该步骤按 release 事件的形状写死：
+
+| 事件 | ref | `GITHUB_REF_NAME` | `${GITHUB_REF_NAME#v}` | 与 `package.json` 版本比对 |
+| --- | --- | --- | --- | --- |
+| `release: published` | `refs/tags/v0.9.0` | `v0.9.0` | `0.9.0` | 通过 |
+| `workflow_dispatch`（从 main 触发） | `refs/heads/main` | `main` | `main` | **恒失败** |
+
+### 2.2 同文件内的正确范例（决定修复形态）
+
+checkout 步骤（`:32`）用事件感知表达式同时覆盖两种触发——手动触发时真正要发布的 tag 在 `inputs.tag` 里：
+
+```yaml
+ref: ${{ github.event.release.tag_name || inputs.tag }}
+```
+
+即：同一概念（"当前发布的 tag"）在本文件有两处实现，checkout 处对、自检处错。修复应让二者同源，而不是引入第三种解析机制。
+
+### 2.3 溯源：为什么潜伏了 5 天
+
+- `git log -S 'GITHUB_REF_NAME'` 只命中 `d982724`（#144，2026-09-25）——该自检步骤自引入起**从未被改动**，不是回归而是「引入即存在」。
+- #144 的 commit body 明确把手动恢复列为设计目标（"a `workflow_dispatch` input re-runs a tag whose publish failed"），但自检只按 release 事件形状写。
+- #144 的 PR body 把 npm 侧 trusted-publisher 配置列为 "Required follow-up (web action, not code)"。该配置滞后 → 09-25 发 0.9.0 时 release 事件发布 404 失败 → 0.9.0 卡在 npm 之外 4 天 → 09-30 配好配置后必须用恢复后门补发 → **首次使用后门，bug 当场暴露**。
+- #144 的 comments/reviews 均为 0 条，无 CR 讨论可复用。
+
+### 2.4 复现性（确定性，不依赖时序）
+
+9-30 两次真实 run 构成单变量对照，唯一变量是 dispatch 的 ref：
+
+| 实验 | 触发命令 | 自检步骤结果 |
+| --- | --- | --- |
+| 失败腿 | `gh workflow run publish.yml -f tag=v0.9.0 --ref main` | `package.json: 0.9.0, tag: main` → exit 1（[run 36726074913](https://github.com/zhuxixi/pi-agent-board/actions/runs/36726074913)） |
+| 通过腿 | `gh workflow run publish.yml -f tag=v0.9.0 --ref v0.9.0` | 自检通过，一路 publish 成功（[run 36726192171](https://github.com/zhuxixi/pi-agent-board/actions/runs/36726192171)） |
+
+### 2.5 影响面
+
+- 只影响手动恢复路径；release 事件路径不受影响，故潜伏至今。
+- 失败 fail-closed 且发生在最早一步：不会误发布、不污染注册表，代价是一次约 20 秒的无效 run。
+- 人因代价是主要危害：文档写的操作失败、文档外的操作可行。
+
+### 2.6 测试覆盖现状（决定可测性边界）
+
+- `test/release-flow.test.mjs` 的 13 个测试全部针对 `scripts/release.mjs`。
+- 全仓 grep `publish.yml|GITHUB_REF_NAME`：`test/` 下零命中——**本仓目前没有任何测试触碰 workflow YAML**。
+
+## 3. 方案决策
+
+| 候选 | 做法 | 评价 | 结论 |
+| --- | --- | --- | --- |
+| **A（采用）** | 自检步骤经 `env:` 接收 `github.event.release.tag_name \|\| inputs.tag`，与 checkout 同源 | 3 行改动；与既有正确写法一致；两种事件都覆盖；不引入新机制 | **采用** |
+| B | 改为 `git describe --tags --exact-match`（对已 checkout 的提交取 tag） | 也能对，但引入新失败面（轻量/附注 tag、一提交多 tag），且与 checkout 已解析的 ref 重复表达同一事实 | 否 |
+| C | 保留 `GITHUB_REF_NAME`，改为要求操作者必须用 `--ref <tag>` 触发 | 等于把 bug 固化进文档（文档已写 "enter the tag"），恢复路径继续反直觉 | 否 |
+| D | 自检改为只校验 `inputs.tag` 存在性、不比对版本 | 削弱护栏（版本错配护栏是 #144 的明确设计目标之一） | 否 |
+
+**改动内容**（`.github/workflows/publish.yml:54-59`）：
+
+```yaml
+- name: Check the tag matches package.json
+  env:
+    RELEASE_TAG: ${{ github.event.release.tag_name || inputs.tag }}
+  run: |
+    PKG_VERSION=$(node -p "require('./package.json').version")
+    TAG_VERSION="${RELEASE_TAG#v}"
+    echo "package.json: ${PKG_VERSION}, tag: ${TAG_VERSION}"
+    [ "${PKG_VERSION}" = "${TAG_VERSION}" ]
+```
+
+用 `env:` 中转而非把 `${{ }}` 直接写进 `run` 脚本，遵循 GitHub Actions 惯例（避免表达式拼接进 shell）。
+
+## 4. 契约与边界
+
+- **不变量**：`publish.yml` 中任何需要「本次要发布的 tag」的位置，都必须从 `github.event.release.tag_name || inputs.tag` 派生，**不得**从 ref 名派生。静态测试钉死 `GITHUB_REF_NAME`（见 A3）；`GITHUB_REF` 在语义上同属错误的派生源，但它存在合法用途（如日志），故不做文本级封禁。
+- **数据流**：`release.tag_name`（release 事件）或 `inputs.tag`（手动触发）→ `env.RELEASE_TAG` → 去 `v` 前缀 → 与 `package.json.version` 比对。
+- **降级**：若未来新增第三种触发方式（如 `push: tags`），该表达式需同步扩展；checkout 与自检必须一起改，二者共用同一表达式是这条降级的唯一保障。
+- **非目标**：不改 release 事件路径行为；不改 checkout 表达式；不改 `scripts/release.mjs`；不增加「workflow 是否已重跑成功」类护栏；不引入 workflow 级 lint 基础设施。
+
+## 5. 验收矩阵
+
+| ID | 功能点 | 验收方式 | 具体验证 | 通过标准 |
+| --- | --- | --- | --- | --- |
+| A1a | 手动触发恢复不再红（合并前验证修复本身） | 自动化验证（automated E2E，真实 dispatch） | `gh workflow run publish.yml -f tag=v0.9.0 --ref issue-154-publish-workflow-dispatch-tag-check`——**ref 必须指向修复分支**：`--ref` 决定运行哪份 workflow 定义，合并前从 main 触发跑的是未修复版，自检必红，会把正确的修复误判为失败。随后 `gh run view <id> --log` 取自检步骤输出 | 自检步骤打出 `package.json: 0.9.0, tag: 0.9.0` 并通过；命中「already published — skipping」分支；整 run `success`。选 v0.9.0 因为它已在 npm 上，**零重复发布风险**。注意：本条只验证到 skip 分支，恢复路径的 `npm publish` 环节本次不执行（与 release 路径共用、未改动） |
+| A1b | 文档承诺的路径按字面成立（**合并后**补验） | 自动化验证（automated E2E，真实 dispatch，合并后执行） | `docs/RELEASE.md:117-118` 的字面操作：Actions → Publish to npm → Run workflow → 填 `v0.9.0`（等价命令 `gh workflow run publish.yml -f tag=v0.9.0 --ref main`） | 同 A1a 的日志与结论。这一步验证的不是修复本身，而是**文档承诺的路径从用户视角成立**（ref=main、只填 tag） |
+| A2 | 版本错配护栏仍然有效（负向） | 自动化验证（automated E2E，负向） | **勘误**：原设计 `-f tag=v0.8.0 --ref main` 不成立——checkout 跟随 `inputs.tag`（`publish.yml:32`），工作区 `package.json` 也随之变成 0.8.0，比对恒等、无法触发失败；更糟的是若该版本不在 npm 上，run 会一路走到 `npm publish` **真实发布旧版本**。错配必须人为制造：在分支 HEAD 打探针 tag `issue-154-mismatch-probe`（**不带 `v` 前缀**，避开 `release.mjs:207` / `release_helper.mjs:182` 的 `v*` 基线通配）并 push（需用户许可），随后 `gh workflow run publish.yml -f tag=issue-154-mismatch-probe --ref issue-154-publish-workflow-dispatch-tag-check`；验后删除本地与远端 tag，`git ls-remote --tags origin` 确认远端无残留 | 自检步骤 exit 1，日志显示 `package.json: 0.9.0, tag: issue-154-mismatch-probe`，run `failure`（证明护栏没被改成「永远通过」） |
+| A3 | `GITHUB_REF_NAME` 不再出现在 publish.yml，且 tag 来源表达式在 checkout 与自检两处同源 | 自动化验证（static） | 新增 `test/publish-workflow.test.mjs`：读 `.github/workflows/publish.yml` 文本（**剥掉整行注释**，避免文档性注释误伤），断言不含 `GITHUB_REF_NAME`，且 `github.event.release.tag_name \|\| inputs.tag`（`\|\|` 两侧空白归一）出现 **≥2 次**（checkout + 自检；删掉自检的 `env:` 块必须红） | `npm test` 通过；修复前两条断言都红（`GITHUB_REF_NAME` 存在、表达式只出现 1 次），先写红再修 |
+| A4 | 既有代码不被破坏 | 自动化验证（unit + build + static） | `npm run verify`（typecheck + perf gate + 全量测试 + 覆盖率阈值 + pack dry-run） | 全绿，覆盖率不低于阈值（lines 85 / funcs 80 / branches 70） |
+| U1 | release 事件自动路径回归 | 用户实测（下个真实发版自然覆盖） | 发布 0.10.0 时走 `prepare → open-pr → merge → finish`，观察 publish.yml 由 release 事件触发的那次 run | 自检步骤通过（`tag: 0.10.0`），publish 步骤成功。本次修复不改变该路径的输入来源，属回归观察项而非新增验证 |
+
+### 5.1 可测性拆分设计
+
+本改动是 YAML 流程编排，逻辑量近零，可测性设计主要落在「把不变量钉死在可断言的形式上」：
+
+- 修复逻辑本身（表达式替换）无法在本地执行，**其唯一有效验证是真实 dispatch（A1/A2）**——这是本 issue 的核心验收，不设更廉价的替代品，也不因此降级为「用户实测」。
+- 唯一可静态化的产物是**不变量 A3**：纯文本断言，无副作用、无外部依赖。做成最小纯函数 `readWorkflowSource()`（读文件）+ 两条字符串断言；副作用（读文件）隔离在单个 helper 内，断言部分保持纯函数式，符合本仓「纯函数 + 薄 I/O 壳」的既有约定（参照 `scripts/release_helper.mjs` 的拆分方式）。
+- 该静态测试断言**否定式不变量**（剥整行注释后不含 `GITHUB_REF_NAME`）+ **正向表达式计数 ≥2**（钉住「checkout 与自检同源」——删掉自检的 `env:` 块必须红），不断言 YAML 结构或步骤名。剥注释与归一空白是为了让文档性注释、无害格式调整不触发假红；而计数断言的有意严苛（把表达式上提成 job 级 `env:` 会红）正是守卫测试的期望行为——改架构就必须重审本不变量。
+
+### 5.2 测试边界
+
+| 边界 | 覆盖 | 不覆盖（明确） |
+| --- | --- | --- |
+| workflow YAML 文本不变量 | A3（static，新增） | YAML 语法正确性（由 GitHub 解析器在 run 时校验，A1 覆盖） |
+| workflow 运行时行为 | A1a、A2（真实 dispatch）；A1b（合并后） | release 事件路径（U1，下个真实发版覆盖） |
+| 发布脚本逻辑 | A4（既有 13 个 release-flow 测试） | 本次不改 `scripts/release.mjs`，无新增 |
+
+## 6. 风险
+
+- **A1a/A1b 各消耗一次真实 run**：约 1 分钟、无副作用、不产生发布（版本已在注册表 → skip 分支）。可接受。
+- **A2 的错配必须人为制造**：checkout 跟随 `inputs.tag`，dispatch 路径下 tag 与工作区 `package.json` 恒同源，用既有 tag 造不出错配；更危险的是若误选未发布过的版本号，run 会一路走到 `npm publish` 真实发布。因此探针 tag 指向分支 HEAD（其 `package.json` 与 tag 名必然不一致），且**不带 `v` 前缀**——`release.mjs` / `release_helper.mjs` 以 `v*` 通配 tag 定 changelog 基线，`v*` 探针泄漏会污染下一次发版。
+- **静态测试（A3）的假红风险**：剥整行注释 + 空白归一已规避文档性假红；保留的假红面（计数 ≥2 对上提重构敏感）是守卫测试的期望行为，见 §5.1。

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@zhuxixi/pi-agent-board",
-	"version": "0.9.0",
+	"version": "0.10.0",
 	"description": "Agent-board dashboard for Pi: dispatch, monitor, peek/reply, and attach to background Pi sessions.",
 	"type": "module",
 	"main": "./index.ts",

package/runner/job-runner.mjs

@@ -18,7 +18,8 @@ import { fileURLToPath } from "node:url";
 import { appendLine, readJson } from "../src/core/atomic.mjs";
 import { createRunStatus, finalizeRun, reduceEvent } from "../src/core/events.mjs";
 import { encodePromptForCliArg } from "../src/core/prompt-transport.mjs";
-import { applyAutoStateToStatus, autoStateEnabled, autoStateFromModelOrHeuristic, autoStateModel, buildAutoStatePrompt, heuristicAutoState, isManualCompletion } from "../src/core/auto-state.mjs";
+import { createStopLatch } from "../src/core/stop-latch.mjs";
+import { applyAutoStateToStatus, autoStateEnabled, autoStateFromModelOrHeuristic, autoStateModel, buildAutoStatePrompt, heuristicAutoState, isManualVerdict } from "../src/core/auto-state.mjs";
 import { appendDiagnostic } from "../src/core/diagnostics.mjs";
 import { emptyEvidenceSnapshot, finalizeEvidence, reduceEvidence, summarizeEvidence, writeEvidence, writeRunEvidence } from "../src/core/evidence.mjs";
 import { updateCodeRefsFromEvidence } from "../src/core/code-refs-store.mjs";
@@ -35,6 +36,17 @@ import { buildApprovePlanPrompt, buildPlanChangesPrompt, buildPlanRequestPrompt
 
 const WRITE_THROTTLE_MS = 250;
 
+// Stop-intent latch (issue #153): a stop signal that arrives before the real
+// stop path exists (config read → run_started → worker spawn → handler
+// wiring) must not kill this process via Node's default action — the run
+// would never reach a terminal state. The latch records it; bootstrapRun
+// replays it into stop() once the handlers are wired. A signal during module
+// import (before these handlers exist) still exits by default, but nothing
+// has been published at that point, so no observable state is lost.
+const stopLatch = createStopLatch();
+process.on("SIGTERM", () => stopLatch.note("SIGTERM"));
+process.on("SIGINT", () => stopLatch.note("SIGINT"));
+
 /** @param {string[]} args */
 function redactWorkerArgs(args) {
 	return args.map((arg, idx) => {
@@ -72,6 +84,12 @@ function main() {
 	// queued frame flickering through run_started's first materialization.
 	status.semanticState = "working";
 	let evidence = emptyEvidenceSnapshot({ viewId, runId, source: "json-runner" });
+	// First observable write BY THE RUNNER (issue #153, A3): the stop latch was
+	// armed at module scope, before the runner publishes anything of its own.
+	// (The parent's mark_queued/pid.json predate the child; that pre-module shape
+	// is converged by service.reconcile() — A10.) Pinned by the stop-window
+	// integration test asserting this is diagnostics.jsonl's first entry.
+	appendDiagnostic(root, viewId, { source: "runner", runId, code: "stop_latch_armed", message: "Stop latch armed before any observable state", details: { signals: ["SIGTERM", "SIGINT"] } });
 	appendDiagnostic(root, viewId, { source: "runner", runId, code: "runner_start", message: "Runner started", details: { kind: config.kind, cwd: config.cwd, model: config.model } });
 	writeRunEvidence(root, evidence);
 	writeEvidence(root, evidence);
@@ -108,6 +126,12 @@ async function bootstrapRun({ root, viewId, runId, config, status, meta, evidenc
 		}
 	}
 
+	// Test-only boot-window knob (issue #153): deterministically widen the gap
+	// between the observable run_started and the handler wiring so a stop can
+	// be delivered inside the window without timing luck. Inert when unset.
+	const bootWindowMs = Number(process.env.AGENT_BOARD_TEST_BOOT_WINDOW_MS || 0);
+	if (bootWindowMs > 0) await new Promise((resolveDelay) => setTimeout(resolveDelay, bootWindowMs));
+
 	/**
 	 * One transient progress beat: ship the full in-memory status as a sparse
 	 * patch — the coordinator merges it onto the materialized status and lets
@@ -177,14 +201,14 @@ async function bootstrapRun({ root, viewId, runId, config, status, meta, evidenc
 	};
 
 	/**
-	 * Persist only if the user hasn't marked the row done manually since the last
+	 * Persist only if the row hasn't taken a manual verdict since the last
 	 * persist. projectViewState() overwrites the row state unconditionally, so a
 	 * post-exit model pass must never persist its stale in-memory status over a
-	 * fresh manual completion.
+	 * fresh manual verdict.
 	 */
 	const persistUnlessManual = (force = false) => {
 		const latestView = readState(root, viewId);
-		if (isManualCompletion(latestView)) return false;
+		if (isManualVerdict(latestView)) return false;
 		persist(force);
 		return true;
 	};
@@ -204,8 +228,8 @@ async function bootstrapRun({ root, viewId, runId, config, status, meta, evidenc
 	 * Refresh the evidence mirrors (status.evidenceSummary / state.review)
 	 * through the coordinator: `patch_fields` carries only whitelisted mirror
 	 * fields, and the coordinator's generic manual fence (source != user on a
-	 * manually-completed row) is the authoritative guard — the old fresh-read
-	 * + isManualCompletion pre-checks are no longer needed. Designed fences
+	 * row carrying a manual verdict) is the authoritative guard — the old
+	 * fresh-read pre-checks are no longer needed. Designed fences
 	 * (manual_fence / no_change) are informational; ambiguous outcomes never
 	 * fall back to a direct write.
 	 */
@@ -232,12 +256,12 @@ async function bootstrapRun({ root, viewId, runId, config, status, meta, evidenc
 		if (result.reason === "coordinator_disabled") {
 			// Legacy escape hatch: fresh-read + fence, pre-coordinator semantics.
 			const freshStatus = readStatus(root, viewId, runId);
-			if (freshStatus && !isManualCompletion(freshStatus)) {
+			if (freshStatus && !isManualVerdict(freshStatus)) {
 				freshStatus.evidenceSummary = status.evidenceSummary;
 				legacyWriteStatus(root, viewId, runId, freshStatus);
 			}
 			const freshState = readState(root, viewId);
-			if (freshState && !isManualCompletion(freshState)) {
+			if (freshState && !isManualVerdict(freshState)) {
 				freshState.review = status.evidenceSummary;
 				legacyWriteState(root, viewId, freshState);
 			}
@@ -370,6 +394,15 @@ async function bootstrapRun({ root, viewId, runId, config, status, meta, evidenc
 	process.on("SIGTERM", stop);
 	process.on("SIGINT", stop);
 
+	// Replay a stop observed before the real handlers existed (issue #153).
+	// take() clears, so this fires at most once and cannot double-fire with a
+	// later real signal; stop() itself is worker.killed-guarded. The diagnostic
+	// is emitted first so the latch path stays observable even if stop() no-ops.
+	if (stopLatch.take() != null) {
+		appendDiagnostic(root, viewId, { source: "runner", runId, code: "stop_latch_replayed", message: "Replaying a stop observed before the handlers were wired", details: {} });
+		stop();
+	}
+
 	worker.on("error", async (err) => {
 		// Cancel any in-flight throttled flush before finalizing: if the timer
 		// callback lands during the sendStateCommand await below, the stale
@@ -465,10 +498,11 @@ async function bootstrapRun({ root, viewId, runId, config, status, meta, evidenc
 async function finalizeSteeringIfNeeded(config, status, evidence) {
 	if (config.kind !== "plan" && config.kind !== "plan_change") return;
 	if (status.semanticState === "failed" || status.semanticState === "stopped") return;
-	// A manual completion racing the exit chain must not be resurrected for
+	// A manual verdict racing the exit chain must not be resurrected for
 	// approval: the user already closed this row. Same signal as the other
-	// post-exit guards (completeView writes completed+autoState null to state.json).
-	if (isManualCompletion(readState(config.root, config.viewId))) return;
+	// post-exit guards (mark_completed/mark_holding write the verdict state
+	// + autoState null to state.json).
+	if (isManualVerdict(readState(config.root, config.viewId))) return;
 	recordPlanReady(config.root, config.viewId, {
 		runId: config.runId,
 		planText: latestEvidenceText(evidence) || status.latestAssistantPreview || status.summary || "Plan ready",
@@ -494,11 +528,11 @@ async function finalizeSteeringIfNeeded(config, status, evidence) {
 /** @param {import("../src/core/types.mjs").RunConfig} config @param {import("../src/core/types.mjs").RunStatus} status */
 async function drainQueuedFollowUp(config, status) {
 	if (status.semanticState !== "idle" && status.semanticState !== "completed") return;
-	// A manual completion racing the exit chain must never be followed up: the
-	// user just finished this row, so don't launch a new run over it. The
+	// A manual verdict racing the exit chain must never be followed up: the
+	// user just closed this row, so don't launch a new run over it. The
 	// in-memory status may be stale (fresh-read guards skip classification), so
 	// check the authoritative state.json signal.
-	if (isManualCompletion(readState(config.root, config.viewId))) return;
+	if (isManualVerdict(readState(config.root, config.viewId))) return;
 	if (config.kind === "plan" || config.kind === "plan_change") return;
 	const claimed = claimNextFollowUp(config.root, config.viewId);
 	if (!claimed.ok || !claimed.item) return;
@@ -654,9 +688,9 @@ async function applyHeuristicAutoState(config, status, evidence) {
 	if (!canAutoState(config, status, evidence)) return false;
 	// Cheap pre-check kept as an optimization (avoids a pointless command);
 	// correctness no longer depends on it — the coordinator fences manual
-	// completions authoritatively (manual_fence).
+	// verdicts authoritatively (manual_fence).
 	const latestState = readState(config.root, config.viewId);
-	if (isManualCompletion(latestState)) return false;
+	if (isManualVerdict(latestState)) return false;
 	const latest = latestEvidenceText(evidence) || status.latestAssistantPreview || status.summary || "";
 	const classification = heuristicAutoState(latest, { lastAgentActivityAt: status.lastAgentActivityAt ?? null });
 	return classifyThroughCoordinator(config, status, classification);
@@ -673,11 +707,11 @@ async function maybeModelAutoState(config, status, evidence) {
 		[...config.piArgsPrefix, "--mode", "json", "-p", "--no-session", "--model", model, prompt],
 		15000,
 	);
-	// The user may have marked the row done manually during the model call. The
-	// cheap pre-check avoids a pointless command; the coordinator's manual_fence
+	// The user may have placed a manual verdict on the row during the model call.
+	// The cheap pre-check avoids a pointless command; the coordinator's manual_fence
 	// is the authoritative guard for races after this read.
 	const fresh = readStatus(config.root, config.viewId, config.runId);
-	if (!fresh || isManualCompletion(fresh)) return false;
+	if (!fresh || isManualVerdict(fresh)) return false;
 	Object.assign(status, fresh);
 	const classification = autoStateFromModelOrHeuristic(out, latest, { lastAgentActivityAt: status.lastAgentActivityAt ?? null });
 	return classifyThroughCoordinator(config, status, classification);
@@ -708,10 +742,10 @@ async function maybeModelSummary(config, status) {
 		[...config.piArgsPrefix, "--mode", "json", "-p", "--no-session", "--model", model, prompt],
 		15000,
 	);
-	// The user may have marked the row done manually during the summary call.
+	// The user may have placed a manual verdict on the row during the summary call.
 	// Updating the stale status and letting the caller persist would clobber the
-	// manual completion, so bail out before touching the in-memory status.
-	if (isManualCompletion(readState(config.root, config.viewId))) return false;
+	// manual verdict, so bail out before touching the in-memory status.
+	if (isManualVerdict(readState(config.root, config.viewId))) return false;
 	const text = out.trim().split("\n").slice(-1)[0]?.trim();
 	if (text) {
 		status.summary = text.replace(/^["']|["']$/g, "").slice(0, 80);

package/runner/pty-runner-legacy.mjs

@@ -4,7 +4,7 @@
  * Only reachable via `AGENT_BOARD_COORDINATOR=off` — the documented escape
  * hatch. The normal path routes `host_run_failed` through the View State
  * Coordinator (`runner/state-coordinator.mjs`), whose manual_fence / stale_run
- * guards own the decision; this direct write has NO manual-completion fence,
+ * guards own the decision; this direct write has NO manual-verdict fence,
  * which is exactly why it must stay unreachable in the default configuration.
  *
  * Lives in its own module so `runner/pty-runner.mjs` itself never imports the

package/runner/state-coordinator.mjs

@@ -69,7 +69,7 @@ const HEARTBEAT_MS = 1000;
  *  shell adds the wall-clock stamp — into the patch BEFORE the journal
  *  append, so boot replay re-applies the exact same fields deterministically
  *  (there is no clock at replay time either). (Task 1 review F5.) */
-const LAST_ACTIVITY_STAMP_KINDS = new Set(["mark_queued", "archive_view", "adopt_session", "reconcile_finalize", "plan_ready", "mark_completed", "host_run_failed"]);
+const LAST_ACTIVITY_STAMP_KINDS = new Set(["mark_queued", "archive_view", "adopt_session", "reconcile_finalize", "plan_ready", "mark_completed", "mark_holding", "clear_holding", "host_run_failed"]);
 /** Kinds whose status patch may CREATE the run's status file: they carry the
  *  full status content for a run that has no materialized status yet. Every
  *  other kind keeps PR #1's "patch presence ≠ file requirement" semantics

package/runner/state-runner.mjs

@@ -9,7 +9,7 @@
 import { spawn } from "node:child_process";
 import { readJson } from "../src/core/atomic.mjs";
 import { appendDiagnostic } from "../src/core/diagnostics.mjs";
-import { applyAutoStateToStatus, applyAutoStateToViewState, autoStateEnabled, autoStateFromModelOrHeuristic, autoStateModel, buildAutoStatePrompt, heuristicAutoState, isManualCompletion } from "../src/core/auto-state.mjs";
+import { applyAutoStateToStatus, applyAutoStateToViewState, autoStateEnabled, autoStateFromModelOrHeuristic, autoStateModel, buildAutoStatePrompt, heuristicAutoState, isManualVerdict } from "../src/core/auto-state.mjs";
 import { finalizeEvidence, readEvidence, summarizeEvidence, writeEvidence } from "../src/core/evidence.mjs";
 import { updateCodeRefsFromEvidence } from "../src/core/code-refs-store.mjs";
 import { readState, readStatus, readMeta, writeState, writeStatus } from "../src/core/store.mjs";
@@ -31,7 +31,7 @@ async function main() {
 	// Cheap pre-check (optimization only): skip a pointless command when the
 	// manual verdict is already materialized. The coordinator's manual_fence
 	// stays the authoritative guard for races after this read.
-	if (isManualCompletion(state)) process.exit(0);
+	if (isManualVerdict(state)) process.exit(0);
 
 	const evidence = readEvidence(config.root, config.viewId);
 	const latest = latestEvidenceText(evidence) || state.latestAssistantPreview || state.summary || "";