@zhuxixi/pi-agent-board 0.5.2 → 0.6.1

package/docs/superpowers/specs/2026-09-04-warm-host-reclaim-design.md

@@ -0,0 +1,106 @@
+# Spec: warm host 回收 —— 周期 sweep + 退出清理（issue #75）
+
+日期：2026-09-04
+状态：draft，待用户确认
+仓库：zhuxixi/pi-agent-board
+
+## 1. 背景与根因
+
+detach / 关闭宿主后，空闲 PTY host（runner + child pi）无限期空转（实测 8.5h）。根因：
+
+1. `pruneWarmHosts()` 仅惰性触发（attach/prewarm/dispatch 时），用户 detach 后不再操作 board 则永不触发 → `AGENT_BOARD_WARM_HOST_TTL_MS`（默认 10min）与 `AGENT_BOARD_MAX_WARM_HOSTS`（默认 4）形同虚设
+2. 宿主 pi 退出/会话切换时无清理钩子（扩展未注册 `session_shutdown`）
+3. 无周期扫描兜底；Windows 下 runner detached 孤儿，宿主被 kill 后无任何回收
+
+## 2. 设计决策
+
+### M1：提取纯判定函数 `selectIdleHostsToEvict`（可测性核心）
+
+把淘汰判定从 `pruneWarmHosts` 闭包中提取为**纯函数**（无 IO、无 env）：
+
+```
+selectIdleHostsToEvict(rows, opts) -> { ttlEvicted: Row[], excessEvicted: Row[] }
+
+opts = { now, maxWarm, ttlMs, graceMs, keepViewId, isBusy? }
+```
+
+- idle 定义：`hostAlive && !isBusy(row) && (host.attachedClients ?? 0) === 0 && (row.meta.id !== keepViewId)`
+- **新增 graceMs 豁免**：`host.startedAt` 距今 < graceMs 的 host 不参与淘汰（防 ensureHost→attach 竞态；attach 重连兜底为第二保险）
+- 排序：survivors 按 `lastActivityAt ?? startedAt` 升序，超出 maxWarm 的从最旧淘汰
+- `isBusy` 默认 = 现 `isAgentBusy` 语义（queued/working/hasPendingQuestions），作为参数注入以保持纯性
+
+### M2：新增调度器 `createWarmHostSweeper`（新模块 `src/core/warm-host-sweeper.mjs`）
+
+```
+createWarmHostSweeper({ sweep, intervalMs }) -> { start, stop, sweepNow }
+```
+
+- `setInterval(sweep, intervalMs)`，`unref()`（不阻塞宿主退出）；`sweepNow()` 立即执行一次（错误吞掉，best-effort）
+- `stop()` 清定时器；`start()` 幂等
+- 新环境变量 `AGENT_BOARD_SWEEP_INTERVAL_MS`（默认 60_000；0 = 禁用周期 sweep，仅保留启动/session_shutdown 时 sweepNow）
+
+### M3：接线（src/index.ts，扩展模块级）
+
+- 扩展加载时：**非 isHostedChild** 才创建 sweeper（`sweep = () => pruneWarmHosts({})`），`start()` + 立即 `sweepNow()`（回收上一个宿主遗留的泄漏 host）
+- 注册 `session_shutdown`：`sweepNow()`（尽力清理）+ `stop()`
+- **isHostedChild 必须跳过**：child pi 内加载扩展时若启动 sweeper，会向自己的 runner 发 terminate（自杀链），绝对禁止
+- 新增环境变量 `AGENT_BOARD_WARM_HOST_GRACE_MS`（默认 30_000；0 = 无豁免，保持旧行为可调）
+
+### M4：dashboard 打开期间顺带 prune（低成本增强）
+
+`openDashboard` 的 POLL_MS 轮询回调里加一次 `pruneWarmHosts()`（dashboard 打开 = 用户正用 board，实时回收）。保持既有惰性调用点不变。
+
+### Non-goals（明确不做）
+
+- **runner 自退出兜底**：runner 无权威 busy 信号（state.json 是 service 层写的，跨进程读取引入耦合/竞态）；误杀风险（PRD stretch "detach while running 转 headless worker" 未实现时，pty child 可能正跑任务）。宿主被杀场景由"下一次任意宿主启动 sweepNow"覆盖，残余缺口（永不再开任何 pi）接受。
+- **detach-while-running 转 headless worker**：PRD stretch，独立议题。
+- 不改变 terminate 消息协议（沿用 `{type:"terminate"}` 既有语义：杀 child，runner 收尾退出）。
+
+## 3. 数据流
+
+```
+宿主扩展实例（每个 pi session 一个，随 session_shutdown 销毁）
+  ├─ module load（非 child）: createWarmHostSweeper(...).start() + sweepNow()
+  ├─ setInterval(60s, unref): pruneWarmHosts({}) → selectIdleHostsToEvict → sendHostMessage(terminate)
+  ├─ dashboard POLL_MS: pruneWarmHosts({})（UI 打开时）
+  └─ session_shutdown: sweepNow() + stop()
+
+selectIdleHostsToEvict(rows, opts)  ← 纯判定（无副作用）
+pruneWarmHosts(opts)                ← 薄执行层（listRows + select + sendHostMessage），既有惰性调用点行为等价
+sendHostMessage(row, terminate)     ← 既有 fire-and-forget socket 路径（#71 协议）
+```
+
+## 4. 验收矩阵
+
+| ID | 功能点 | 验收方式 | 具体验证 | 通过标准 |
+|----|--------|----------|----------|----------|
+| A1 | selectIdleHostsToEvict：TTL 到期淘汰、未到期保留、keepViewId 豁免 | 自动化(unit) | `node --test test/warm-host-sweeper.test.mjs` | 过期 idle host 进入 ttlEvicted；未过期/keepViewId 不进入 |
+| A2 | busy（queued/working/pendingQuestions）与 attachedClients>0 永不淘汰 | 自动化(unit) | 同上 | 两类 host 均不进入任何淘汰列表 |
+| A3 | graceMs 豁免：startedAt 距今 < grace 的 host 不淘汰 | 自动化(unit) | 同上 | 豁免窗口内不进淘汰列表；窗口外正常淘汰 |
+| A4 | maxWarm 超额时淘汰最旧 survivors（按 lastActivityAt/startedAt） | 自动化(unit) | 同上 | 淘汰对象为排序最旧者，数量 = survivors - maxWarm |
+| A5 | sweeper 调度：start 定时触发、stop 停止、sweepNow 立即执行、unref | 自动化(unit) | 同上（node:test mock timers） | fake timer 前进 intervalMs 后 sweep 被调用；stop 后不再调用；sweepNow 立即调用 |
+| A6 | 接线：非 child 宿主启动即 sweepNow + 周期 sweep；isHostedChild 不接线 | 自动化(integration) | `node --test test/service.test.mjs` 增补：临时 root + node:net 假 server 捕获 terminate | idle host 的 socketPath 收到 terminate；child 模式（flag）下无 sweeper 启动 |
+| A7 | session_shutdown 触发 sweepNow（退出清理） | 自动化(integration) | 同上：调用注册的 shutdown 回调 | terminate 发出；sweeper 已 stop |
+| A8 | 重构无回归：pruneWarmHosts 既有惰性调用点行为等价 | 自动化(全量) | `node --test test/*.test.mjs`（基线 409+ 含既有失败清单） | 与修复前基线一致，无新增失败 |
+| U1 | 真实场景回收 | 用户实测 | 开会话→attach→detach→设 `AGENT_BOARD_WARM_HOST_TTL_MS=10s` + `AGENT_BOARD_SWEEP_INTERVAL_MS=5s`→观察 | TTL 过后 host.json 变 exited，runner/child 进程退出，dashboard 状态正确 |
+
+## 5. 可测性拆分设计（实现硬约束）
+
+1. **`selectIdleHostsToEvict`**：纯函数，输入 rows + opts，输出淘汰分组；不触盘、不连 socket、不读 process.env（所有阈值参数显式传入）。测试直接构造内存 rows。**边界**：判定逻辑全部在此函数内；`pruneWarmHosts` 只做 IO 编排，不得内联任何判定分支。
+2. **`createWarmHostSweeper`**：调度器封装，`sweep` 回调依赖注入；timer 用全局 setInterval（node:test mock timers 可控）。**边界**：不 import service/store；与业务零耦合。
+3. **`attachWarmHostSweeperToLifecycle(piLike, deps)`**（index.ts 内接线函数）：接收 `pi`（on 事件注册）与 `deps = { createSweeper, isHostedChild, sweep }`，可注入 fake 断言注册行为。**边界**：index.ts 只调这个函数，不内联生命周期逻辑。
+4. **`pruneWarmHosts`**：重构为薄执行层（listRows → selectIdleHostsToEvict → sendHostMessage），原惰性调用点（dispatch/ensureHost/dashboard）签名不变，行为等价（A8 回归保障）。
+
+## 6. 风险与缓解
+
+- 竞态（attach 与 sweep 同时）：graceMs + attach 重连兜底（既有 #48 L3）
+- child pi 自杀链：isHostedChild 硬跳过（A6 覆盖）
+- 多宿主并发 sweep 重复 terminate：terminate 幂等（sendHostMessage 失败静默、runner 已死则 socket error 吞掉）
+- sweep 与 archive/stop 竞态：单进程内同 service 数据视图，均 fire-and-forget，最坏重复 terminate（幂等）
+
+## 7. 测试计划摘要
+
+- 新增 `test/warm-host-sweeper.test.mjs`：A1-A5（unit，含 mock timers）
+- 增补 `test/service.test.mjs`：A6-A7（integration，net 假 server 捕获 terminate）
+- 全量回归：A8
+- U1 用户实测清单写入 PR 描述与 issue 评论

package/docs/superpowers/specs/2026-09-05-issue-13-drainnextfollowup-pty-probe-design.md

@@ -0,0 +1,64 @@
+# Spec: issue #13 — drainNextFollowUp forces PTY probe refresh on the 700ms poll path
+
+## Problem
+
+`src/runtime/service.mjs` `drainNextFollowUp` (L496) calls
+`ptySupport({ refresh: true })` and is reachable from the 700ms `reconcile()`
+poll (L1007-1011: queued follow-up + `canAutoDrain` → `drainNextFollowUp`).
+When a queued follow-up repeatedly fails to start, every poll cycle forces a
+fresh PTY probe — `ptySpawnSupported` does a **real `pty.spawn`** process.
+This violates the probe-cache discipline (`shouldProbePtySupport`): success
+cached for process lifetime, failures retried on a 2s TTL; only `refresh`
+bypasses it.
+
+`dispatch` (L616) and `reply` (L649) also use `refresh: true` but are explicit
+user actions — fine as-is, untouched.
+
+## Decision (issue's fix sketch, verbatim)
+
+Replace in `drainNextFollowUp`:
+
+```js
+const pty = ptySupport({ refresh: true });
+```
+
+with default cached-probe semantics:
+
+```js
+const pty = ptySupport();
+```
+
+Plus a red-green test asserting the injected `ptySupport` never receives
+`refresh: true` from the reconcile→drain path (pattern from PR #12's service
+test "ensureHost probes PTY support with TTL cache, not forced refresh",
+test/service.test.mjs:940).
+
+## Behavior contract
+
+- Poll-path drains use the cache: after a successful probe, zero further real
+  spawns; after a failed probe, at most one real spawn per 2s window.
+- Explicit user actions (`dispatch`, `reply`) keep forced refresh.
+- No other behavior change in drain logic (claim/launch/complete paths
+  untouched).
+
+## Non-goals
+
+- No change to `dispatch`/`reply` refresh semantics.
+- No change to `ptySpawnSupported`/`shouldProbePtySupport` internals.
+
+## Acceptance matrix
+
+| ID | Feature point | Acceptance | Concrete verification | Pass criteria |
+|----|---------------|------------|----------------------|---------------|
+| A1 | reconcile→drain path never forces probe refresh | Automated (unit) | New test in `test/service.test.mjs`: idle row + queued follow-up → `svc.reconcile()` → injected ptySupport spy records opts; assert `probeCalls.length >= 1` and no call has `refresh === true` | New test passes; fails (red) if production line keeps `refresh: true` |
+| A2 | Explicit user actions unaffected | Automated (unit) | Existing service tests (dispatch/reply paths) green in full suite | `npm test` all green |
+| A3 | Full regression | Automated (integration) | Full `npm test` | All pass |
+| A4 | Change scope | Automated (static) | `git diff main` review | Production delta is exactly the one-line probe switch in `src/runtime/service.mjs`; test delta is one new test |
+
+## Testability split design
+
+Test-only seam already exists: `createService` opts inject `ptySupport`
+(spy) and `launch` (fake, avoids real spawn). The new test drives the public
+`reconcile()` API so the exact poll path is covered. Row state constructed
+via `readState`/`writeState` (idle + exited) so `canAutoDrain` holds. No new
+production functions.

package/docs/superpowers/specs/2026-09-05-issue-38-windows-wezterm-ime-design.md

@@ -0,0 +1,48 @@
+# Spec: issue #38 — document Windows WezTerm IME hardware-cursor requirement
+
+## Problem
+
+With #24/#28 shipped (v0.4.3), the IME candidate window is pinned and
+flicker-free on Linux (WezTerm + fcitx5/X11). On **Windows WezTerm (WSL2
+backend)** the candidate window stays stuck at the right edge: per upstream
+earendil-works/pi#5200, Windows WezTerm only updates the IME candidate
+position when the **hardware cursor is visible**, and pi-tui hides it by
+default. The visible block cursor in the editor is a fake (reverse-video
+content), so "I can see the cursor" does not imply the hardware cursor is on.
+
+Fix (verified on the real environment, per the issue): `PI_HARDWARE_CURSOR=1`
+env or `"showHardwareCursor": true` in pi's settings.json. Trade-off: the
+real terminal cursor becomes visible in the TUI (cosmetic only; harmless on
+Linux).
+
+## Decision
+
+Add one Troubleshooting subsection to README.md:
+
+- Title: IME candidate window stuck at the right edge (Windows WezTerm)
+- Content: symptom + platform scope (Windows WezTerm → WSL2, Windows IME/TSF;
+  Linux unaffected), root cause in one sentence (hardware cursor hidden by
+  default; Windows WezTerm needs it visible to track IME position; the editor
+  block cursor is fake content, not the hardware cursor), both fixes with
+  sync/scope guidance (machine-local env vs synced settings.json), and the
+  cosmetic trade-off.
+
+Placement: after "### Attach is slow or keeps reconnecting" (IME is an
+attach-surface concern, keeps related attach topics adjacent).
+
+## Non-goals
+
+- No code changes.
+- No upstream comment on earendil-works/pi#5200 (owner's voice, left to the
+  repo owner — noted in the issue comment).
+
+## Acceptance matrix
+
+| ID | Feature point | Acceptance | Concrete verification | Pass criteria |
+|----|---------------|------------|----------------------|---------------|
+| A1 | Troubleshooting entry exists with both fixes | Automated (static) | grep README.md for the new section + `PI_HARDWARE_CURSOR=1` + `showHardwareCursor` | All three present in the Troubleshooting section |
+| A2 | Scope: docs-only change | Automated (static) | `git diff main --stat` | Only README.md (plus process docs under docs/superpowers/) |
+
+## Testability split design
+
+Docs-only: verification is content presence + scope, no behavioral seam.

package/docs/superpowers/specs/2026-09-05-issue-39-truncate-codepoint-boundary-design.md

@@ -0,0 +1,64 @@
+# Spec: issue #39 — truncate() cuts surrogate pairs, producing lone surrogates (U+FFFD) and wrap-misaligned dashboard rows
+
+## Problem
+
+`src/core/heuristics.mjs` `truncate(s, n)` uses `str.length` and `str.slice()`
+(UTF-16 code units). When the cut lands inside a surrogate pair (e.g. emoji,
+2 units), the output keeps a lone high surrogate → renders as U+FFFD →
+pi-tui counts it 1 column while WezTerm renders 2 → line over-wide → terminal
+wrap → TUI diff-render row misalignment → stacked stale frames on the
+dashboard (issue's repro chain).
+
+`truncate` feeds `deriveSummary` (max=80), `events.mjs`
+(`latestAssistantPreview`), `evidence.mjs`, `auto-state.mjs` — all display
+text paths.
+
+## Decision (fix direction A, repo-side)
+
+Two changes inside `truncate`:
+
+1. **Code-point-safe cut (cut-point back-off, NOT code-point budget).** Keep
+   the existing UTF-16 unit budget `n` (all callers pass display budgets; CJK
+   chars occupy 2 units — switching to a code-point count would double the
+   effective width of CJK summaries from 80 to ~160 columns and *reintroduce*
+   over-wide lines). Instead: if the character just before the cut point is a
+   high surrogate whose low surrogate is the first dropped unit, back the cut
+   off by one unit so the pair stays whole. Output length only shrinks by one
+   unit in that rare case; the ellipsis still fits the budget.
+
+2. **Defensive lone-surrogate strip on output.** Input text (from agent
+   output stored in status.json) may already contain lone surrogates; strip
+   them from the returned string on both the short path and the truncated
+   path (`/[\uD800-\uDBFF](?![\uDC00-\uDFFF])/g` and the mirrored
+   low-surrogate regex).
+
+Out of scope (per goal boundary): pi-tui width-table changes for Ambiguous
+characters (fix direction B) and terminal-side clamping (direction C) —
+upstream/external. Completion here = truncate no longer produces or passes
+through lone surrogates; "visual overlap fully gone" additionally depends on
+those upstream items.
+
+## Non-goals
+
+- No `Intl.Segmenter` grapheme segmentation (ZWJ emoji families remain
+  multi-codepoint; the defect being fixed is lone surrogates, not grapheme
+  splitting).
+- No caller changes; no width-function changes.
+
+## Acceptance matrix
+
+| ID | Feature point | Acceptance | Concrete verification | Pass criteria |
+|----|---------------|------------|----------------------|---------------|
+| A1 | Cut never splits a surrogate pair | Automated (unit) | New tests in `test/heuristics.test.mjs`: e.g. `truncate("a👍b", 3) === "a…"` (back-off) and a long-string case whose cut lands on an emoji; assert output matches `/\uD83D$/` never (no trailing lone high surrogate) | Tests pass |
+| A2 | Output is lone-surrogate-free even when input isn't | Automated (unit) | `truncate("ab\ud83d", 10) === "ab"`, `truncate("ab\udc4dzzzzzzzzzz", 5)` has no lone low surrogate | Tests pass |
+| A3 | Existing behavior preserved for ASCII and CJK | Automated (unit) | Existing tests unchanged (`truncate("hello world", 5) === "hell…"`) + new: `truncate("一二三四五", 5) === "一二…"` (2-unit budget semantics kept) | Tests pass |
+| A4 | Full regression | Automated (integration) | Full `npm test` | All green |
+| A5 | Scope | Automated (static) | `git diff main -- src/ test/` | Only `src/core/heuristics.mjs` (truncate) and `test/heuristics.test.mjs` |
+
+## Testability split design
+
+`truncate` is already a pure exported function — tests exercise it directly
+at unit level. Two internal helpers (back-off check, lone-surrogate strip)
+stay private; they are covered through truncate's public behavior at the
+exact boundaries (cut on high surrogate, lone surrogate in input on both
+paths).

package/docs/superpowers/specs/2026-09-05-issue-61-mention-fallback-design.md

@@ -0,0 +1,71 @@
+# Spec: issue #61 — mention fallback lifts placeholder numbers (no left-boundary guard, kind-blind, code-span-blind)
+
+## Problem
+
+The Rule 6 bare `#N` mention fallback (`src/core/code-refs.mjs`
+`mentionFallback`, L767) misfires on internal-platform sessions: the real
+work object was internal issue `#18` (only `acli` commands — no builtin rules
+for that CLI), while a skill doc's example placeholder `#1378` won the
+fallback and was written into `github.json` as the session's issue
+(`strength: mention, confidence: low`).
+
+Four gaps (issue G1-G4):
+
+- **G2** `MENTION_RE = /#(\d{1,7})/g` has no left boundary: `##1378`
+  (markdown heading / double-hash typo) still matches `#1378` as a substring.
+- **G4** mention counting does not distinguish prose from inline code spans:
+  `` `monitor pr #1378` `` (a doc example) counts the same as a real
+  reference.
+- **G3** counting is kind-blind: `monitor pr #1378` — explicitly PR context —
+  feeds the *issue* candidate.
+- **G1** no documented `providers.json` example for internal-platform CLIs,
+  so such sessions systematically slide into the fallback at all.
+
+## Decision (issue's fixes 1-4)
+
+In `src/core/code-refs.mjs`:
+
+1. **Left-boundary guard (G2):** `MENTION_RE = /(?<![#\w])#(\d{1,7})/g` —
+   rejects a preceding `#` or word character; `#18`, `( #18 )`, `text #18`
+   still match.
+2. **Code-span exclusion (G4):** before counting, strip inline code spans
+   from each assistant text (`text.replace(/`[^`\n]*`/g, " ")`).
+3. **Kind-aware counting (G3):** for each surviving match, inspect a small
+   window before the match (16 chars); if it contains a standalone
+   `pr|pull|mr|merge` token (case-insensitive, word-bounded), the match does
+   not count toward the issue fallback (PR-context numbers must not lift an
+   issue). Dropped, not reclassified — the fallback is issue-only by design;
+   fabricating a PR mention candidate is out of scope.
+4. **Docs (G1):** README "Evidence and Code References" gains a compact
+   `providers.json` example: an internal-platform provider with a claim
+   strength rule (e.g. `acli issue update #N --assignee`) and a hosts entry,
+   so users can configure claim/action rules in five minutes and such
+   sessions stop depending on the fallback at all.
+
+## Non-goals
+
+- No new builtin rules for any specific internal CLI (that's per-user config).
+- No PR-side mention fallback (issue-only fallback stays).
+- No fenced-block stripping (assistantTexts are prose; inline spans are the
+  observed vector).
+
+## Acceptance matrix
+
+| ID | Feature point | Acceptance | Concrete verification | Pass criteria |
+|----|---------------|------------|----------------------|---------------|
+| A1 | Left boundary guard | Automated (unit) | New tests: `##1378` and `a#1`-style texts produce no mention winner; plain `#18` texts still win | Tests pass |
+| A2 | Code-span exclusion | Automated (unit) | `` `monitor pr #1378` `` inside backticks contributes zero counts | Tests pass |
+| A3 | Kind-aware skip | Automated (unit) | Prose `monitor pr #1378` ×5 does not produce an issue winner | Tests pass |
+| A4 | Issue repro shape regresses fixed | Automated (unit) | Composite fixture: placeholder `#1378` only in guarded forms (heading / code span / pr-context) + real `#18` prose ×3 → winner is 18; without the `#18` prose → no winner | Tests pass |
+| A5 | Existing fallback behavior preserved | Automated (unit + integration) | Existing tests ("picks #40 (5x) over #7 (2x)", "no winner when tied") unchanged and green; full `npm test` green | All green |
+| A6 | providers.json example documented | Automated (static) | README Evidence section contains a valid `providers.json` example with a claim rule for an internal CLI + `hosts` | grep + render check |
+| A7 | Scope | Automated (static) | `git diff main -- src/ README.md test/` | Only `src/core/code-refs.mjs` (MENTION_RE + mentionFallback), README Evidence section, and `test/code-refs-extract.test.mjs` |
+
+## Testability split design
+
+`mentionFallback` is exercised through the public `extractCodeRefs` (same
+seam as all existing mention tests) — no new export needed. Guards are pure
+regex/substring logic on the existing pure function; each gap gets one
+focused test plus one composite repro test (A4). The providers.json example
+is docs; its JSON validity is asserted by pasting it through
+`validateProvider` in a unit test (bonus guard, cheap).

package/docs/superpowers/specs/2026-09-05-issue-63-flaky-manual-completion-design.md

@@ -0,0 +1,49 @@
+# Spec: issue #63 — runner.integration "manual completion" flaky
+
+## Problem
+
+`test/runner.integration.test.mjs` "runner does not clobber a manual completion
+made during post-exit model passes" asserts `markCompleted()` returns
+`{ok:true}` immediately after `endedAt` becomes visible in status.json. But
+`runner/job-runner.mjs` `persist()` writes status.json **before** state.json
+(no transaction). In the window between the two writes, `markCompleted` →
+`completeView` still sees an active run (pid liveness via `loadRow` →
+`isAgentBusy`) and rejects with
+`{ok:false, error:'Wait for the active run to finish before marking done'}`.
+
+CI caught this once on PR #60 (Node 24); rerun + 5 local runs passed. Pure
+timing window, no behavior regression.
+
+## Decision (issue option 1 — poll the assertion target itself)
+
+Replace the one-shot assertion with a `waitFor` poll of `markCompleted` until
+it returns `{ok:true}` (then assert the exact shape). The assertion then checks
+**durability after success** rather than racing the exact call. The existing
+`waitFor(fn, timeoutMs = 15000, intervalMs = 50)` helper is reused; default
+15s timeout is ample (the race window is millisecond-scale: two evidence file
+writes).
+
+The durability assertions that are the actual behavior under test stay
+unchanged: after the runner exits, `semanticState === "completed"` and
+`autoState === null`.
+
+## Non-goals
+
+- No production code change (`runner/`, `src/` untouched) — test-only fix.
+- No refactor of `persist()` write ordering (would change production behavior;
+  the ordering is deliberate: endedAt converges first, see code comment).
+
+## Acceptance matrix
+
+| ID | Feature point | Acceptance | Concrete verification | Pass criteria |
+|----|---------------|------------|----------------------|---------------|
+| A1 | Test no longer asserts `markCompleted` return immediately after `endedAt` visibility | Automated (unit/integration) | Inspect diff: one-shot `assert.deepEqual(createService(...).markCompleted(...), {ok:true})` replaced by waitFor-poll + shape assert | Code review of diff; no immediate assert after `endedAt` waitFor remains |
+| A2 | Flaky assertion semantics preserved | Automated (integration) | `npm test` (node --test, the runner.integration test itself) | Test passes; durability asserts (`semanticState === "completed"`, `autoState === null`) unchanged in diff |
+| A3 | Suite stability (the CI flake mode) | Automated (integration) | 10 consecutive full `npm test` runs | All 10 green, zero flakes |
+| A4 | No production behavior change | Automated (static) | `git diff main --stat` in PR | Only `test/runner.integration.test.mjs` modified |
+
+## Testability split design
+
+Test-only change; no new production functions. The poll helper (`waitFor`)
+already exists and is exercised by every other use in the file — no new test
+boundary introduced.

package/docs/superpowers/specs/2026-09-05-issue-64-changelog-helper-design.md

@@ -0,0 +1,76 @@
+# Spec: issue #64 — CHANGELOG.md driven by conventional commits (port of jfox release helper)
+
+## Problem
+
+No CHANGELOG exists; releases are bare version squashes (`0.5.2 (#74)`).
+npm users and gallery visitors have no "what changed in this version" entry
+point. Commits are already highly conventional (QA baseline #32 onward), so
+generation is mechanical.
+
+## Decision (jfox approach, Node port)
+
+Port the jfox release helper (`zhuxixi/jfox/.claude/skills/release/release_helper.py`)
+to `scripts/release_helper.mjs` (repo stack: Node ESM). Architecture:
+
+- **Pure, exported functions** (unit-testable, no git in unit tests):
+  - `parseCommitLines(lines)` — conventional-commit parse: type
+    (feat/fix/perf/refactor/docs/chore/test + `!`), scope, message, trailing
+    `(#N)` PR number; skip `bump version`-ish and pure merge subjects;
+    dedupe.
+  - `generateChangelog({ version, date, entries, prevTag })` —
+    `## [version] - date` section grouped Features / Fixes / Performance /
+    Changes, each entry `- message (#N)`, plus compare link
+    `https://github.com/zhuxixi/pi-agent-board/compare/vPREV...vNEXT`.
+  - `changelogTopPrs(text)` — PR numbers inside the first `## [...]` section.
+  - `verifyFrom({ functionalLines, changelogText })` — functional whitelist
+    (feat/fix/refactor/docs/perf, skipping merges / version-bump commits /
+    `docs(changelog)` maintenance commits to avoid a verify fix loop), diff
+    against top-section PRs → `{ ok, missing, extra, functionalCommits }`,
+    fail-closed on bad input.
+- **CLI** (git-backed, thin): `node scripts/release_helper.mjs [--dry-run]
+  [patch|minor|major|X.Y.Z]` (default patch; version read from
+  package.json; `--dry-run` prints JSON preview without touching files;
+  apply inserts the section at the top of CHANGELOG.md) and
+  `node scripts/release_helper.mjs verify` (exit 1 + missing list when
+  `last v* tag..HEAD` functional commits' PR numbers are absent from the
+  CHANGELOG top section — guards against a PR merged after the changelog
+  was generated).
+- **Forward-only**: CHANGELOG.md is created with a header stub only; entries
+  start from the next release after this lands. No backfill of ≤0.5.2.
+- **npm script**: `"changelog": "node scripts/release_helper.mjs"` so
+  `npm run changelog -- --dry-run` works (issue acceptance wording).
+- **README Publishing section** updated to the new flow (changelog BEFORE
+  `npm version`, because the bump commit+tag would empty the generation
+  range): `npm run verify` → `npm run changelog -- --dry-run` (review) →
+  `npm run changelog -- <bump>` (insert section) → `verify` must exit 0 →
+  commit CHANGELOG → `npm version <bump>` → `npm publish` → GitHub Release
+  with notes from the top section.
+
+Tag format: this repo tags `vX.Y.Z` (verified: v0.4.2..v0.5.2), same as
+jfox's `--match v*` logic.
+
+## Non-goals
+
+- No GitHub Release automation (manual step, per jfox flow).
+- No backfilling historical versions.
+- No changes to the existing `verify` npm script.
+
+## Acceptance matrix
+
+| ID | Feature point | Acceptance | Concrete verification | Pass criteria |
+|----|---------------|------------|----------------------|---------------|
+| A1 | dry-run preview | Automated (integration) | `npm run changelog -- --dry-run` exits 0, prints JSON with `changelog_preview` containing `## [0.6.0]` or next-patch section and grouped entries from v0.5.2..HEAD; CHANGELOG.md unmodified | Command output assertions |
+| A2 | apply inserts top section | Automated (unit) | Unit test on a temp file via exported `insertSection`/CLI with fixture dir: header-stub CHANGELOG gains the new `## [...]` section above prior content | Test passes |
+| A3 | parse correctness | Automated (unit) | Fixtures: `feat(scope): msg (#12)`, `fix: msg (#13)` with `!`, bare merge, `0.5.2 (#74)` version squash (skipped), non-conventional fallback, dedupe | Test passes |
+| A4 | verify missing detection | Automated (unit + integration) | Unit: constructed lines/text → missing/extra/fail-closed paths. Integration: `node scripts/release_helper.mjs verify` on this branch (CHANGELOG stub, v0.5.2..HEAD has functional PRs #77-#82) exits 1 with missing listing those PRs | Both pass |
+| A5 | Full regression | Automated (integration) | `npm test` | All green |
+| A6 | Publishing docs updated | Automated (static) | README Publishing section mentions the changelog script and flow | grep |
+| A7 | Scope | Automated (static) | `git diff main --stat` | Only scripts/release_helper.mjs, test/release-helper.test.mjs, package.json (one script line), CHANGELOG.md (stub), README.md |
+
+## Testability split design
+
+Pure functions take plain inputs (string lines, text, options) and return
+plain data — no fs/git in unit tests. The CLI layer (git + fs) is covered by
+two integration assertions (A1 dry-run on the real repo, A4 verify on the
+real repo) executed as plain commands in the workflow, plus a tmp-dir apply
+test via the exported path. This mirrors the repo's existing DI style.