@zhuxixi/pi-agent-board 0.4.3 → 0.5.0

package/README.md

@@ -82,6 +82,7 @@ Useful environment variables:
 | `AGENT_BOARD_AUTO_STATE=off` | Disable automatic terminal-state moves. |
 | `AGENT_BOARD_AUTO_STATE_MODEL=<model>` | Model for classifying finished turns. Defaults to `gpt-4o`; use `off` for heuristic-only. |
 | `AGENT_BOARD_AUTO_STATE_NO_DONE` | Disables automatic `completed` classification (default: enabled). Set to `0`/`false`/`off`/`no` to restore auto-done. |
+| `AGENT_BOARD_CODE_REFS=off` | Disable issue/PR badge extraction from session evidence. |
 | `AGENT_BOARD_SUMMARY_MODEL=<model>` | Model for short row summaries. Defaults to `gpt-4o`; use `off` to disable. |
 | `AGENT_BOARD_TITLE_MODEL=<model>` | Model for generated session titles. Defaults to `openai-codex/gpt-5.5`; use `off` to disable. |
 | `AGENT_BOARD_TITLE_THINKING_LEVEL=<level>` | Thinking level for title generation. Defaults to `low`; use `off` to omit it. |

package/docs/superpowers/plans/2026-08-29-code-refs-badges.md

@@ -0,0 +1,223 @@
+# Code-Refs Badges Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Show each board row's associated issue number and submitted PR number as inline badges, extracted locally from session evidence via a platform-agnostic regex-rule engine.
+
+**Architecture:** Pure extraction engine (`src/core/code-refs.mjs`, zero I/O) driven by per-platform regex rule bundles ("providers": builtin GitHub/GitLab + user `providers.json`, append-merged); artifact persistence in `src/core/code-refs-store.mjs` (per-view `github.json`, atomic writes); write-through hooks at all five `writeEvidence` call sites; rendering via existing RowView badge + peek detail patterns. Spec: `docs/superpowers/specs/2026-08-29-code-refs-badges-design.md` (decisions D1–D5 govern).
+
+**Tech Stack:** Node 20+ ESM `.mjs` (JSDoc types, no TS in core), `node --test`, pi-agent-board store layout.
+
+## Global Constraints
+
+- **Work only in this worktree**: `/home/elling/git-repo/github/pi-agent-board/.pi/worktrees/issue-40-code-refs-badges`. Never touch the main checkout.
+- Core modules are `.mjs` with JSDoc typedefs; **indent with tabs** (match existing files); `node:assert/strict` + `node:test` for tests; tmp dirs via `mkdtempSync(join(tmpdir(), ...))` with `rmSync(..., {recursive:true, force:true})` cleanup.
+- All artifact writes go through `atomicWriteJson` from `src/core/atomic.mjs`; reads through `readJson`.
+- Commit per task, conventional commits (`feat:`/`test:`/`fix:`), stage files explicitly (`git add <file>`), never `git add -A`.
+- Coverage gate (CI-enforced): lines 85% / functions 80% / branches 70% (`npm run test:coverage`); new core modules must be thoroughly covered.
+- No network calls anywhere in v1. `gh`/`glab` are only ever *parsed as text*, never executed. Only `git` may be shelled out to (repo.mjs pattern: `execFileSync` with `stdio:["ignore","pipe","ignore"]`, try/catch → null).
+- Kill switch: env `AGENT_BOARD_CODE_REFS=off` disables extraction (checked in the hook helper).
+- English code comments and commit messages.
+
+---
+
+### Task 1: `gitRemoteHost` in repo.mjs
+
+**Files:**
+- Modify: `src/core/repo.mjs`
+- Test: `test/repo.test.mjs`
+
+**Interfaces:**
+- Produces: `gitRemoteHost(repoRoot: string) → string|null` — host of `origin` remote, lowercase, no port. Supports `https://host/owner/repo(.git)` and `git@host:owner/repo(.git)`. Module-level `Map` cache keyed by repoRoot (failures cached as null). Also `clearRemoteHostCacheForTests() → void`.
+- Consumed by: Task 4 (store) / Task 5 (hook helper).
+
+- [ ] **Step 1: failing tests** in `test/repo.test.mjs` (follow existing temp-repo style, `skip: !gitAvailable()`):
+  - https remote `https://github.com/zhuxixi/pi-agent-board.git` → `"github.com"`
+  - ssh remote `git@gitlab.example.com:team/demo.git` → `"gitlab.example.com"`
+  - no remote → `null`; not a repo → `null`
+  - cache: second call returns same value; after `git remote set-url` + no cache clear, still old value; after `clearRemoteHostCacheForTests()`, new value
+- [ ] **Step 2: run tests, see them fail** (`node --test test/repo.test.mjs`)
+- [ ] **Step 3: implement** in `src/core/repo.mjs` (same `execFileSync("git", ["-C", root, "remote", "get-url", "origin"], …)` pattern as `gitRepoRoot`; parse with two regexes; cache both hits and misses)
+- [ ] **Step 4: tests pass**
+- [ ] **Step 5: commit** `feat(repo): gitRemoteHost with per-root cache`
+
+---
+
+### Task 2: provider layer in code-refs.mjs (schema, builtins, merge, host match)
+
+**Files:**
+- Create: `src/core/code-refs.mjs`
+- Test: `test/code-refs-providers.test.mjs`
+
+**Interfaces:**
+- Produces (all pure, zero I/O except `loadProviders` reading one JSON file path passed in):
+  - `builtinProviders() → Provider[]` — GitHub + GitLab bundles (rules below)
+  - `genericFallbackProvider() → Provider` — name `"generic"`, hosts `[]`, URL-only rules: `/issues/(\d+)` (issue/view), `/pull/(\d+)` (pr/action), `/-/issues/(\d+)` (issue/view), `/-/merge_requests/(\d+)` (pr/action); prefixes `#` / `▸#`; no urlTemplates
+  - `validateProvider(raw: any) → { provider: Provider|null, errors: string[] }` — each rule compiled with `new RegExp(pattern)`; invalid regex → skipped with error message; missing required fields → error
+  - `mergeProviders(builtins: Provider[], user: Provider[]) → Provider[]` — same `name` → user rules **prepended** to builtin rules, user scalar fields (hosts/prefixes/urlTemplates) override; unknown names appended as-is
+  - `loadProviders(root: string) → Provider[]` — reads `<root>/providers.json` if present (via `readJson` from atomic.mjs), validates + merges with builtins; on any error returns builtins alone (never throws). Result cached by file mtime in a module Map.
+  - `matchProvider(providers: Provider[], host: string|null) → Provider` — exact host match (lowercase); null host or no match → `genericFallbackProvider()`
+  - Provider typedef: `{ name, hosts: string[], issuePrefix: string, prPrefix: string, urlTemplates: { issue?: string, pr?: string }|null, rules: Rule[] }`; Rule typedef: `{ regex: RegExp, pattern: string, kind: "issue"|"pr", strength: "claim"|"action"|"view", numberFrom: "capture"|"outputUrl" }`
+- Consumed by: Task 3 (engine), Task 5 (hook helper calls `loadProviders`).
+
+Builtin GitHub rules (patterns are matched **unanchored** against full command strings and assistant texts):
+```
+claim:  gh\s+issue\s+edit\s+#?(\d+)(?=[\s\S]*--add-assignee)            kind: issue
+action: gh\s+issue\s+(?:comment|edit|close|reopen)\s+#?(\d+)            kind: issue
+action: gh\s+issue\s+create\b                                            kind: issue, numberFrom: outputUrl
+action: gh\s+pr\s+(?:checkout|merge|comment|review|close)\s+#?(\d+)      kind: pr
+action: gh\s+pr\s+create\b                                               kind: pr, numberFrom: outputUrl
+action: github\.com/[\w.-]+/[\w.-]+/pull/(\d+)                           kind: pr
+view:   gh\s+issue\s+view\s+#?(\d+)                                      kind: issue
+view:   gh\s+pr\s+(?:view|diff|checks)\s+#?(\d+)                         kind: pr
+view:   github\.com/[\w.-]+/[\w.-]+/issues/(\d+)                         kind: issue
+urlTemplates: issue "https://{host}/{owner}/{repo}/issues/{number}", pr "https://{host}/{owner}/{repo}/pull/{number}"
+```
+Builtin GitLab rules:
+```
+claim:  glab\s+issue\s+(?:edit|update)\s+#?(\d+)(?=[\s\S]*--assignee)    kind: issue
+action: glab\s+issue\s+(?:note|comment|close|reopen)\s+#?(\d+)           kind: issue
+action: glab\s+mr\s+(?:checkout|merge)\s+!?(\d+)                         kind: pr
+action: glab\s+mr\s+create\b                                             kind: pr, numberFrom: outputUrl
+action: /-/merge_requests/(\d+)                                          kind: pr
+view:   glab\s+(?:issue|mr)\s+view\s+!?#?(\d+)                           kind: issue-or-pr by matched subcommand — implement as two rules: glab\s+issue\s+view\s+#?(\d+) (issue) and glab\s+mr\s+view\s+!?(\d+) (pr)
+view:   /-/issues/(\d+)                                                  kind: issue
+prefixes: issue "#", pr "!"
+urlTemplates: issue "https://{host}/{owner}/{repo}/-/issues/{number}", pr "https://{host}/{owner}/{repo}/-/merge_requests/{number}"
+```
+
+- [ ] **Step 1: failing tests**: builtin shape sanity (every rule regex compiles, kinds/strengths in enum); validateProvider rejects bad regex / missing kind; mergeProviders prepends user rules and overrides prefixes; loadProviders with missing file → builtins; with broken JSON → builtins; with valid user file → merged; matchProvider exact/lowercase/fallback
+- [ ] **Step 2: run, fail**
+- [ ] **Step 3: implement**
+- [ ] **Step 4: tests pass**
+- [ ] **Step 5: commit** `feat(code-refs): provider schema, builtin github/gitlab rules, append-merge loading`
+
+---
+
+### Task 3: extraction + scoring engine in code-refs.mjs
+
+**Files:**
+- Modify: `src/core/code-refs.mjs`
+- Test: `test/code-refs-extract.test.mjs`
+
+**Interfaces:**
+- Consumes: Provider/Rule from Task 2.
+- Produces:
+  - `extractCodeRefs(input, provider) → CodeRefsResult`
+    - `input: { commands: Array<{ command: string }>, assistantTexts: string[], worktreePath: string|null, branch: string|null, repoUrl: string|null }` (`repoUrl` = `owner/repo` path part of the remote, used for urlTemplates; may be null)
+    - `CodeRefsResult: { provider: string, issue: Ref|null, pr: Ref|null, allRefs: Ref[] }`
+    - `Ref: { kind: "issue"|"pr", number: number, strength: "claim"|"action"|"view"|"mention", confidence: "high"|"medium"|"low", source: string, url: string|null, lastIndex: number }`
+  - `parseRepoPath(repoRoot) → string|null` — **move-free helper**: parse `owner/repo` from remote URL. NOTE: Task 1 didn't produce this; add `gitRemoteUrl(repoRoot)` to repo.mjs here (same pattern, also cached) returning the raw URL, and keep URL→host and URL→path parsing pure in code-refs.mjs (`parseRemoteHost(url)`, `parseRemotePath(url)`). Refactor Task 1's `gitRemoteHost` to use `gitRemoteUrl` + `parseRemoteHost` internally. Update repo tests accordingly.
+
+Engine rules (implement exactly):
+1. Scan `commands` in array order; each rule regex applied to `command`; capture group 1 = number (rules with `numberFrom:"outputUrl"` yield no number here — record a *pending create* marker with kind+index).
+2. Scan `assistantTexts` (treat as ordered sequence after commands, indexes continue) with only the URL rules (patterns containing `/` path segments — select rules whose pattern contains `issues/|pull/|merge_requests/`).
+3. Pending-create resolution: for each `pr create`/`issue create`/`mr create` marker, search **subsequent** texts/commands for the provider's URL rule of the same kind; first hit assigns the number at strength `action`, `source:"create-url"`. Unresolved markers contribute nothing (outputPreview bug #41 means bash output is unreadable — do **not** read outputPreview).
+4. PR back-link: within a `pr create` command string, `(?:close[sd]?|fix(?:e[sd])?|resolve[sd]?|issue)\s+#(\d{1,7})` → issue ref at `claim` strength, `source:"pr-body"`.
+5. Worktree naming (engine-builtin, not configurable): `(?:^|[/\\])issue-(\d{1,7})(?:-|$)` against `worktreePath` and `branch` → issue ref at `claim`, `source:"worktree"`.
+6. Mention fallback (only if no issue candidate of strength ≥ view exists): count `#(\d{1,7})` over the **last 20** assistantTexts; winner needs count ≥3 **and** ≥ 2× runner-up; strength `mention`, confidence `low`, kind issue, no url.
+7. Aggregation per kind: candidate with highest strength wins; tie → highest `lastIndex`; `view` candidates with total count < 2 are discarded first. Confidence: claim/action → `high`, view → `medium`, mention → `low`. `allRefs`: distinct (kind,number) sorted by strength desc then lastIndex desc, max 10. `url`: fill from provider.urlTemplates when repoUrl + template exist (`{host}` needs host — pass host in via provider match context: extend input with `host: string|null`; substitute `{host}/{owner}/{repo}` — owner/repo split from repoUrl path, repo name minus trailing `.git`).
+8. Empty input → `{ provider: provider.name, issue: null, pr: null, allRefs: [] }`.
+
+Test cases must include (synthetic but modeled on real observed sessions):
+- assign claim beats later plain `issue view` of another number
+- worktree path `issue-40-code-refs-badges` yields issue 40 claim with zero commands
+- `gh pr create --body "…issue #40…"` sets both pr (pending → resolved by later assistant URL text) and issue 40 (pr-body claim)
+- ambiguity case: commands viewing 439/440/441 each once, commenting 453 twice → issue = none from view (count<2), pr… construct exact expectation per rules (453 is a pr comment → pr=453 action)
+- mention fallback: `#40` ×5, `#7` ×2 → issue 40 low confidence; `#40` ×3, `#41` ×3 → no winner (not 2×)
+- unresolved `gh pr create` (no later URL) → pr null
+- empty input; null host with generic fallback provider still extracts from URLs
+
+- [ ] **Step 1: failing tests** (above list, one test each)
+- [ ] **Step 2: run, fail**
+- [ ] **Step 3: implement** (including the repo.mjs `gitRemoteUrl` refactor)
+- [ ] **Step 4: tests pass; re-run task-1 tests**
+- [ ] **Step 5: commit** `feat(code-refs): extraction engine with 4-tier signal scoring`
+
+---
+
+### Task 4: github.json artifact + store plumbing
+
+**Files:**
+- Create: `src/core/code-refs-store.mjs`
+- Modify: `src/core/paths.mjs`, `src/core/types.mjs`, `src/core/store.mjs`
+- Test: `test/code-refs-store.test.mjs`, extend `test/store.test.mjs`
+
+**Interfaces:**
+- `paths.mjs`: `providersPath(root) → <root>/providers.json`; `codeRefsPath(root, viewId) → <root>/views/<id>/github.json`
+- `code-refs-store.mjs`:
+  - `emptyCodeRefsSnapshot({viewId}) → snapshot` `{ version:1, viewId, updatedAt, provider:null, issue:null, pr:null, allRefs:[] }`
+  - `normalizeCodeRefsSnapshot(raw, {viewId})` (same defensive shape as evidence's normalize)
+  - `readCodeRefs(root, viewId) → snapshot` / `writeCodeRefs(root, snapshot) → snapshot` (atomicWriteJson, bumps updatedAt)
+  - `summarizeCodeRefs(snapshot) → { provider, issue, pr, allRefs }`
+  - `updateCodeRefsFromEvidence(root, viewId, evidence) → boolean` — the hook helper: returns false without writing when `AGENT_BOARD_CODE_REFS=off`; reads meta via `readMeta` (lazy import cycle check — store.mjs must not import code-refs-store.mjs if code-refs-store imports store.mjs: therefore `updateCodeRefsFromEvidence` takes `meta` as a parameter instead; callers pass `row.meta`/config). Resolves repoRoot = `meta.repoRoot ?? meta.cwd`, host via `gitRemoteUrl`+parse, provider via `loadProviders(root)`+`matchProvider`, worktreePath/branch (`branch`: `git -C <cwd> branch --show-current`, best-effort cached 60s in module Map), builds engine input from `evidence.commands` + last 20 `assistantEvidence[].text`, writes snapshot only when serialized content changed. Never throws (catch → appendDiagnostic `code_refs_extract_failed`, return false).
+- `types.mjs`: `CodeRefsSummary` typedef; `ViewState` optional `codeRefs`; Row typedef gains `codeRefs`.
+- `store.mjs` `readViewArtifactSummaries`: add `codeRefs: summarizeCodeRefs(readCodeRefs(root, viewId))` (mirror evidence lines; archived short-circuit untouched).
+
+- [ ] **Step 1: failing tests**: paths shape; snapshot normalize (garbage in → safe defaults); write→read roundtrip; summarize; updateCodeRefsFromEvidence with a fabricated evidence (commands containing `gh issue view 40` ×2) + fabricated meta (cwd = temp repo with github remote) → github.json contains issue 40 medium confidence; `AGENT_BOARD_CODE_REFS=off` → no file; broken providers.json in root → still extracts via builtins
+- [ ] **Step 2: run, fail**
+- [ ] **Step 3: implement**
+- [ ] **Step 4: tests pass (incl. existing store.test.mjs)**
+- [ ] **Step 5: commit** `feat(code-refs): per-view github.json artifact + store plumbing`
+
+---
+
+### Task 5: hook the five writeEvidence sites
+
+**Files:**
+- Modify: `runner/job-runner.mjs` (2 sites: initial write ~L66, shared `persist()` ~L105), `src/runtime/service.mjs` (syncRowEvent ~L519 and agent_end ~L550), `runner/state-runner.mjs` (~L57)
+- Test: extend `test/service.test.mjs` (or the existing runner integration style) minimally; full coverage arrives in Task 7.
+
+**Interfaces:**
+- Consumes: `updateCodeRefsFromEvidence(root, viewId, evidence, meta)` from Task 4.
+- Call it immediately after each `writeEvidence(root, evidence)`:
+  - job-runner sites have `config` (with cwd) but need meta → use `readMeta(root, viewId)` once at runner start, reuse
+  - service.mjs `syncRowEvent(row, event)` → pass `row.meta`
+  - state-runner has `config` → `readMeta(config.root, config.viewId)` once
+- All call sites wrapped so a throw can never escape (helper already never throws; still call inside existing try blocks where present).
+
+- [ ] **Step 1: failing test**: service-level — feed `syncRowEvent`-equivalent path (see how service.test.mjs fabricates rows) an event stream whose bash command is `gh issue comment 40 --body hi`; assert `<root>/views/<id>/github.json` exists with issue 40
+- [ ] **Step 2: run, fail**
+- [ ] **Step 3: implement the 5 hook calls**
+- [ ] **Step 4: tests pass**
+- [ ] **Step 5: commit** `feat(code-refs): extract on every evidence write (job-runner/service/state-runner)`
+
+---
+
+### Task 6: RowView badges + peek Refs section + README
+
+**Files:**
+- Modify: `src/core/rows.mjs` (rowView), `src/ui/dashboard.ts` (renderRow badges ~L1364-1365; renderPeek after Auto-state block ~L1400), `README.md` (env var table row)
+- Test: `test/rows.test.mjs`, `test/dashboard-render.test.mjs`
+
+**Interfaces:**
+- RowView gains: `refsBadge: string` (e.g. `"#40 ▸#45"`, `""` when nothing), `refsLowConfidence: boolean` (true when the winning issue or pr confidence is `low`), `codeRefs: CodeRefsSummary|null` (peek consumes).
+  - Badge format: `${issuePrefix}${issue.number}` and `${prPrefix}${pr.number}` joined by space; prefixes from `summary.provider`'s bundle — simplest: store resolved prefixes in the snapshot at write time (add `issuePrefix`/`prPrefix` fields to snapshot in Task 4's normalize with defaults `#`/`▸#`; if you do this, update Task 4 tests — do it as part of this task's implementation and keep Task 4 commit green by amending its tests here).
+- renderRow: append `refsBadge` to `statusBadges` string; when `refsLowConfidence` wrap badge in `t.fg("dim", …)` (compose with existing badge assembly; verify width math still clamps via existing `visibleWidth(badge)` path).
+- renderPeek: after the Auto-state block add a `Refs` section (mirror that block's structure): provider name; one line per allRefs entry `kind #number · confidence · source · url`; section omitted when `codeRefs` is null/empty.
+- README env table: add `AGENT_BOARD_CODE_REFS` row (`off` disables issue/PR badge extraction).
+
+- [ ] **Step 1: failing tests**: rows.mjs rowView maps summary → badge strings (incl. dim flag, empty case); dashboard-render test asserting badge appears in the row line and Refs section renders in peek (follow existing dashboard-render.test.mjs patterns)
+- [ ] **Step 2: run, fail**
+- [ ] **Step 3: implement**
+- [ ] **Step 4: tests pass**
+- [ ] **Step 5: commit** `feat(dashboard): inline issue/PR badges + peek Refs section`
+
+---
+
+### Task 7: end-to-end integration + full verify
+
+**Files:**
+- Modify: `test-support/fake-pi.mjs` (new `FAKE_PI_MODE=github-refs`: emitted event stream includes a bash tool_execution for `gh issue edit 40 --add-assignee @me`, later an assistant message containing `https://github.com/zhuxixi/pi-agent-board/pull/45`), `test/runner.integration.test.mjs` (new case: run with that mode, assert `github.json` has issue 40 claim + pr 45 action, and row view badge `#40 ▸#45`)
+- Test only.
+
+- [ ] **Step 1: write the failing integration test** (mirror existing runner.integration.test.mjs setup: tmp AGENT_BOARD_ROOT etc.)
+- [ ] **Step 2: extend fake-pi.mjs mode**, run test, iterate to green
+- [ ] **Step 3: full `npm run verify`** (typecheck + tests + coverage + pack:dry) — all green; if coverage dips below gate, add focused unit tests to the new modules (do not weaken thresholds)
+- [ ] **Step 4: commit** `test(code-refs): fake-pi github-refs mode + end-to-end badge assertion`
+
+---
+
+## Post-implementation (controller, not a task)
+
+- Dispatch final broad code review, then open PR (`Closes #40`), label `zima:needs-review`, monitor CR per zima-pr-monitor skill.

package/docs/superpowers/plans/2026-08-30-post-exit-timing-fix.md

@@ -0,0 +1,37 @@
+# Plan: fix post-exit timing test failure (issue #46)
+
+Branch: `issue-46-post-exit-timing` · Worktree: `.pi/worktrees/issue-46-post-exit-timing`
+Spec: `docs/superpowers/specs/2026-08-30-post-exit-timing-fix-design.md`
+
+## Task 1 — persist() order in `runner/job-runner.mjs`
+Move `updateCodeRefsFromEvidence(root, viewId, evidence, meta)` to **after**
+`writeState(...)` inside the `persist()` closure (line ~100-108).
+- Verify: `git diff` shows only the reordering in `persist()`.
+
+## Task 2 — manual-completion guards in the exit chain
+1. `applyHeuristicAutoState`: skip when state.json shows a manual completion
+   (`isManualCompletion(readState(...))` early-return before classification).
+2. Heuristic branch `persist(true)` → `persistUnlessManual(true)`.
+3. `drainQueuedFollowUp` and `finalizeSteeringIfNeeded`: early-return on
+   `isManualCompletion(readState(...))` (no follow-up run / no plan
+   resurrection over a manually completed row).
+- Verify: `git diff` shows only these four call-site changes.
+
+## Task 3 — targeted test verification (Node 24)
+```bash
+node --test --test-name-pattern "clobber a manual completion" test/runner.integration.test.mjs
+```
+- Run 3×: all pass on the assertion part (364/377).
+- Windows EPERM in the cleanup `finally` is acceptable (pre-existing env noise).
+
+## Task 4 — full test file + typecheck
+```bash
+node --test test/runner.integration.test.mjs
+npm run typecheck   # if script exists
+```
+- Failure set must not be worse than baseline (before fix: clobber + stopping-the-runner fail).
+
+## Task 5 — commit & summary
+- Commit: `fix: prevent post-exit auto-state from clobbering manual completion (issue #46)`
+- Note: the `stopping the runner finalizes the run as stopped` failure is
+  pre-existing (fails on `23c7c46` too) and out of scope.

package/docs/superpowers/specs/2026-08-29-code-refs-badges-design.md

@@ -0,0 +1,128 @@
+# Spec: 行内展示 session 关联的 issue / PR 编号（code-refs）
+
+- Issue: https://github.com/zhuxixi/pi-agent-board/issues/40
+- 日期：2026-08-29
+- 状态：待用户确认
+
+## 1. 背景与目标
+
+Dashboard 每行（一个后台 pi session）目前只有 name + summary + age，看不到「这行在处理哪个 issue、它提交了哪个 PR」。本特性在行内徽章区展示这两个编号，peek 视图给完整信息。
+
+**平台无关是硬约束**：GitHub、GitLab、公司内网代码平台都有 issue/PR（MR）概念但 CLI 与 URL 不同。平台差异全部做成正则规则数据，提取引擎保持通用。
+
+### 目标（Goals）
+
+1. 行内徽章显示最近一个 issue 编号 + 最近一个 PR 编号（如 `#40 ▸#45`），前缀随平台规则（GitLab MR 用 `!`）。
+2. peek 视图显示完整引用列表（编号 + 置信度 + 平台链接）。
+3. 平台规则可由用户配置扩展（内网平台 = 加一段 JSON，引擎零改动）。
+4. 纯本地提取，零网络调用；实时性 = 事件驱动（session 跑到相关命令时徽章即出现）。
+
+### 非目标（Non-goals）
+
+- 不做网络补全（`gh pr list --head` 查分支对应 PR、抓取 issue/PR 标题与状态）——列为 v2 候选，本期不做。
+- 不做 PR 状态着色（open/merged）、不做 `refs:has` 过滤器——v2 候选。
+- 不修 `outputPreview` 的 `[object Object]` bug——拆独立 issue #41。
+- 不识别「无编号」的平台对象（如纯分支名）。
+
+## 2. 决策表（已与用户对齐）
+
+| # | 决策点 | 结论 |
+|---|---|---|
+| D1 | 评分规则 | 信号分四级（认领/worktree 命名/PR 回链 = 最强；动作 = 强；查看 = 中；裸引用 = 弱兜底），平局时最近的最强信号赢 |
+| D2 | 多候选显示 | 行内只显示最近一个 issue + 一个 PR；完整列表进 peek |
+| D3 | 用户规则与内置同名 provider 冲突 | 按规则追加（用户规则优先匹配，其后是内置规则） |
+| D4 | outputPreview bug | 拆独立 issue #41，本特性不含 |
+| D5 | 隔离测试 | `PI_CODING_AGENT_DIR` + `AGENT_BOARD_ROOT` 双变量隔离，不动 `~/.pi`；软链开发方式不用 |
+
+## 3. 架构
+
+复刻仓库既有「artifact → summarize → 合并进 Row → renderRow 徽章」模式（evidence/diagnostics/followUps/steering 同构）。新增一个纯函数引擎模块、一个 per-view artifact、五处写入钩子、两处渲染改动。
+
+```
+事件流 → reduceEvidence → evidence.json ──┐
+                                          ├─→ extractCodeRefs() → github.json → Row.github → 徽章/peek
+providers.json（用户规则）+ 内置规则 ──────┘        ▲
+repo.mjs remoteHost()（带缓存）───────────────────┘
+```
+
+### 组件契约
+
+**C1 `src/core/code-refs.mjs`（新，纯函数，零 I/O，主测试对象）**
+
+- `extractCodeRefs(input, providerSet) → CodeRefsResult`
+  - `input`: `{ commands: EvidenceCommand[], assistantTexts: string[], worktreePath: string|null, branch: string|null }`
+  - `providerSet`: 解析后的规则包列表（已按 host 选好 + 用户规则已合并）
+  - 输出: `{ issue: {number, confidence, source} | null, pr: {number, confidence, source} | null, repoUrl: string|null }`
+- `loadProviders(builtIns, userConfig) → provider 列表`（实现 D3 追加语义：同名 provider 时用户规则排在内置规则前面）
+- `matchProvider(providers, remoteHost) → provider | null`（host 匹配；无匹配返回 null，调用方走兜底规则）
+- 信号强度枚举：`claim > action > view > mention`，每级带置信度 high/medium/low。
+
+**C2 信号来源与评分规则（D1 落地）**
+
+| 强度 | 信号 | 检测方式 |
+|---|---|---|
+| claim（最强） | 认领命令：provider 规则里 `strength: "claim"` 的命令模式（GitHub 内置：`gh issue edit N --add-assignee`） | commands 正则 |
+| claim | worktree 命名：`issue-<N>-<slug>`（issue-driven 工作流强制规范） | worktreePath / branch 结构化解析（非正则配置，引擎内置） |
+| claim | PR 回链：`gh pr create` 的 body/后续文本中的 `issue #N` / `Closes #N`（同时定 issue + PR 两个值） | commands + assistantTexts |
+| action（强） | `issue comment/edit/close N`、`pr checkout/view/merge N`、`pr create`（编号从 outputUrl 或后续 URL 反查，见 D4 限制） | commands 正则 |
+| view（中） | `issue view N` / `pr view N` | commands 正则，要求频次 ≥2，取最近一次 |
+| mention（弱，兜底） | 裸 `#N` | assistantTexts，要求频次显著最高（≥3 且 ≥ 第二名的 2 倍） |
+
+平局：命令序列中位置最靠后的最高强度信号赢（commands 有序，按数组下标比较，不用时间戳）。置信度：claim/action → high；view → medium；mention → low。渲染时 low 用 dim 色（宁可不显示也不错显示——mention 级仅在无任何更强信号时出现）。
+
+**C3 `providers.json` 规则 schema（用户配置）**
+
+- 位置：`$AGENT_BOARD_ROOT/providers.json`（随 store root 隔离，E2E 天然不污染真实配置）。
+- 结构：`{ providers: [{ name, hosts[], issuePrefix, prPrefix, urlTemplates: { issue, pr }, rules[] }] }`；每条 rule = `{ pattern, kind: "issue"|"pr", strength: "claim"|"action"|"view", numberFrom?: "capture"|"outputUrl" }`。urlTemplates 用占位符拼链接，如 `"https://{host}/{owner}/{repo}/-/issues/{number}"`（owner/repo 从 remote URL 解析）。
+- 内置默认：GitHub + GitLab 两份（含 hosts、URL 正则、CLI 正则、前后缀、链接模板）。
+- 加载失败（JSON 语法错 / 单条正则非法）：跳过该条并记 diagnostics（`code_refs_config` 码），不炸 dashboard。
+
+**C4 `repo.mjs` 增补**
+
+- `gitRemoteHost(repoRoot) → string|null`：`git remote get-url origin` 解析 host，支持 ssh（`git@host:path`）与 https 两种形式；结果按 repoRoot 缓存在模块级 Map（一个仓库只查一次，失败也缓存 null）。
+
+**C5 artifact `github.json`（per-view）**
+
+- `paths.mjs` 加 `codeRefsPath(root, viewId)` → `views/<id>/github.json`。
+- 内容：`{ version: 1, viewId, updatedAt, provider: string|null, issue: {...}|null, pr: {...}|null, allRefs: [...]（peek 用，最多 10 条） }`。
+- 读写走 `atomicWriteJson`（并发写者多，KB 已有教训）。
+- `readViewArtifactSummaries` 增加 `codeRefs:` 汇总；`Row`/`RowView` 加 `codeRefs` 字段。
+
+**C6 写入钩子（5 处，`writeEvidence` 的全部调用点）**
+
+`runner/job-runner.mjs` ×2（共用 persist()）、`src/runtime/service.mjs` ×2、`runner/state-runner.mjs` ×1。统一收敛为一个 helper：`updateCodeRefsFromEvidence(root, viewId, evidence, meta)`——增量不重算：引擎输入只取 evidence 的 commands + 最近若干条 assistantTexts + meta.worktreePath/branch，纯正则，实测成本微秒级；每次 evidence 写入后顺带调用。失败只记 diagnostics，不影响主流程。
+
+**C7 渲染**
+
+- `rows.mjs` `rowView`：透传 `codeRefs`。
+- `dashboard.ts` `renderRow`：statusBadges 追加 `issuePrefix+number`（issue）与 `prPrefix+number`（PR），low 置信度用 `dim` 色；宽度沿用现有「从 name 预算扣」机制。
+- peek 视图：新增 "Refs" 段（复刻 Auto-state 段模式）：provider 名、issue/PR 编号 + 置信度 + 由 `urlTemplate` 拼出的终端超链接、allRefs 完整列表。
+
+## 4. 错误处理与降级
+
+- 无 git 仓库 / 无 remote / host 不认识 → 只用「通用 URL 兜底规则」（匹配任意 host 的 `/issues/N`、`/pull/N`、`/-/issues/N`、`/-/merge_requests/N`）+ worktree 命名解析；都没有则不显示徽章。
+- 用户 providers.json 损坏 → 内置规则仍生效，diagnostics 记一条 warn。
+- 提取过程任何异常 → catch 后记 diagnostics，evidence 主流程不受影响（与既有 artifact 容错一致）。
+- 无任何引用 → `github.json` 写空结果（`issue: null, pr: null`），渲染跳过徽章，不留 stale 数据。
+
+## 5. 测试策略（四层，详见 issue 评论）
+
+1. **单元**：`code-refs.mjs` 全分支覆盖——每级信号命中、强度排序、平局规则、mention 兜底阈值、provider 追加合并（D3）、host 匹配、损坏配置容错。
+2. **真实数据回测**：脱敏后的真实 evidence.json 命令序列做 fixture（`moc 439` 行的多引用歧义场景是核心用例）。
+3. **集成**：fake-pi.mjs 注入含 `gh issue edit 40 --add-assignee` / `gh pr create` 的事件流 → 断言 `github.json` 内容与渲染徽章字符串。
+4. **手工 E2E**：`PI_CODING_AGENT_DIR` + `AGENT_BOARD_ROOT` 隔离环境；scratch 仓库换 remote host 验证 provider 匹配；PR 编号用 `echo <url>` 模拟（全程零真实 GitHub 变更）。
+5. 验收：`npm run verify` 全绿（typecheck + test + c8 行 85%/分支 70% + pack dry-run）。
+
+## 6. 分阶段
+
+- **v1（本 issue）**：C1–C7 全部（纯本地提取 + 渲染 + 配置）。
+- **v2（另开 issue，不在本期）**：网络补全（`pr list --head`、标题/状态）、PR 状态着色、`refs:has` 过滤器、outputPreview 修复后的 `outputUrl` 反查增强（依赖 #41）。
+
+## 7. 实现顺序（供 plan 参考）
+
+1. `repo.mjs` `gitRemoteHost` + 缓存（含单测）
+2. `code-refs.mjs` 引擎 + 内置规则 + schema 校验（含单测，覆盖率大头）
+3. `github.json` artifact 读写 + `readViewArtifactSummaries` 汇总 + Row/RowView 字段
+4. 5 处写入钩子
+5. 渲染：徽章 + peek Refs 段
+6. 四层测试补齐 + `npm run verify`

package/docs/superpowers/specs/2026-08-30-eprm-atomicwrite-race-design.md

@@ -0,0 +1,77 @@
+# Issue #48 根因报告 + 修复 spec
+
+Windows: pty-runner dies with uncaught EPERM when host.json atomicWrite races a reader; attach view stuck in reconnect loop
+
+状态：**草稿，待用户确认**（2026-08-30）
+
+---
+
+## 1. 根因（已代码层验证，非推测）
+
+### 机制（Windows 特有）
+libuv 打开文件默认共享模式不含 `FILE_SHARE_DELETE`；Node `renameSync` 在 Windows 映射为 MoveFileExW(MOVEFILE_REPLACE_EXISTING)，替换已存在目标需先删除旧目标，而删除要求所有持句柄进程带 FILE_SHARE_DELETE——否则抛 `EPERM: operation not permitted`（本机 100/100 复现，见 issue 正文复现代码）。
+
+### 触发链
+1. `runner/pty-runner.mjs` 1s 心跳 `update()` → `persist()` → `writeHost()` → `atomicWriteJson()`（`src/core/atomic.mjs`：写 `.tmp` → `renameSync`，**无重试**）
+2. service 渲染路径高频 `readHost()/loadRow()`（`readFileSync` host.json）——密集工具调用 + 任意面板渲染即构成 reader
+3. 窗口重叠 → renameSync 抛 EPERM → **无 try/catch**（update/persist 均无防护，全文件无 uncaughtException 兜底）→ runner 以 `detached: true, stdio: "ignore"`（`launch.mjs`）静默死亡，留 `.tmp` 残留
+4. 连锁：runner 死 → ConPTY 断 → 托管 child pi 随死
+5. attach 视图：只有 socket `{type:"exit"}` 消息才置 `status="host exited"`（`pty-attach.ts` onSocketData L871）；崩溃 runner 不发 → `scheduleReconnect()` 150ms **无限重连**
+6. 逃生失败：`handleInput` 中 `←`/`ctrl+]` 仅当 `childInputLooksEmpty()` 才 detach（崩溃画面停在非空输出行，不满足）；`send()`（L852）`!connected` 时**静默丢弃**；pi-tui 无系统级兜底键
+
+### 次要发现
+- `failEarly()` 硬编码 `/tmp/pi-agent-board-pty-runner.err`（Windows 无 /tmp，写失败被吞）——崩溃零痕迹的原因之一
+- 二次崩溃无 `host_reconciled` 诊断（reconcile 只在 panel open / session_start 跑）→ idle 行掩盖崩溃
+
+## 2. 修复设计（四层，L1-L3 必做，L4 待确认）
+
+### L1 `src/core/atomic.mjs` — rename 重试（根因层）
+- 新增内部 `renameWithRetry(tmp, file, opts?)`：
+  - 错误码白名单重试：`EPERM` / `EBUSY` / `EACCES`（Windows 共享冲突三兄弟）
+  - 3 次重试 + 退避 10ms → 50ms → 250ms（同步调用，上限阻塞 ~310ms，可接受）
+  - 重试无需重写 tmp（写文件已在 rename 前完成，tmp 内容完整）
+  - 全部失败：`unlinkSync(tmp)`（try/catch 清理残留）→ 抛**原错误**（保持调用方语义，由 L2 降级）
+- `atomicWrite` 调 `renameWithRetry`；导出 `renameWithRetry` 供单测注入失败回调
+
+### L2 `runner/pty-runner.mjs` — 持久化防御 + 崩溃兜底（防御层）
+- `persist()` 包 try/catch：失败时 `appendDiagnostic(root, viewId, { type: "persist_error", ... })`（`core/diagnostics.mjs` 仅依赖 atomic/paths，runner 可安全导入）→ 降级继续，下个心跳 tick 再试，**不杀进程**
+- `update()`：persist 失败不影响 `broadcast()`（socket 消息是 attach 主通道，host.json 短暂陈旧可接受）
+- `process.on("uncaughtException")` 一次性兜底：
+  1. 移除 handler（防循环）
+  2. appendDiagnostic 记录
+  3. 尽力最终 persist：`state:"failed", error, endedAt`（try/catch 包住）
+  4. `broadcast({ type: "exit", exitCode: 1 })` ← **关键**：让已连 attach 正常退出，不再无限重连
+  5. `process.exit(1)`
+- `failEarly` 的 `/tmp` 硬编码 → `os.tmpdir()`（Windows 兼容小修）
+
+### L3 `src/ui/pty-attach.ts` — 逃生键 + 重连超时（UI 层）
+- **逃生**：DETACH 分支条件改为 `if (!this.connected || this.childInputLooksEmpty()) this.detach()` —— 断连/启动中随时可按 `←`/`ctrl+]` 退出（`send({type:"detach"})` 在 !connected 时被丢弃，无害）
+- **重连超时**（新增 `everConnected` 标志，首个 socket connect 成功置位）：
+  - `everConnected === true` 断开后：15s 重连窗口 → 超时置 `status = "host exited"`、停止重连、保持可 detach（覆盖 issue 主场景：host 已崩）
+  - `everConnected === false`（host 冷启动中，service 在 attach 前已 launchHost）：保留无限重连 + 宽松上限 120s → 超时置 `status = "host not reachable"` 停止重连（覆盖 launchHost 失败场景）
+  - 超时到期不自动 `done()`，显示错误状态等用户按 `←` 退出（避免突然弹走）
+
+### L4（可选，待确认）— idle 行掩盖崩溃的展示级检测
+- 落点：`loadRow()` 已派生 `hostAlive`；dashboard 渲染时对 `host.state==="alive" && !hostAlive && lastSeenAt 陈旧(>10s)` 的行显示 host-lost 标记（**仅展示级，不改 state.json**，避免与 resume/重启中误判）
+- 不做 state 级 reconcile 触发时机修改（范围外）
+
+## 3. 测试计划（TDD 先行）
+
+| 层 | 测试 | 方式 |
+|---|---|---|
+| L1 | `renameWithRetry` 重试次数/退避/白名单/最终抛错/失败后 tmp 清理/happy path | 单测注入失败回调（新增 `test/atomic-retry.test.mjs`） |
+| L2 | persist 持续失败 → runner 不崩溃 + diagnostics 有记录 + host.json 陈旧但不死 | 集成：host.json 目标路径被同名**目录**占位（rename 必失败，跨平台稳定触发） |
+| L2 | 崩溃兜底 `finalizeCrash`：写 failed 状态 + broadcast exit | 抽纯函数单测（外部无法稳定注入 uncaughtException） |
+| L3 | handleInput 逃生分支（!connected 时 detach） | 现有 pty-attach render 测试基建（mock tui/theme/term） |
+| L3 | 重连超时状态机（everConnected × 超时 × 状态文案） | 抽纯函数或组件级测试 |
+
+回归：全量 `node --test test/*.test.mjs` + `npm run typecheck`（Windows 全量已知 6 个既有失败，基线对比排除回归）。
+
+## 4. 非目标
+- 不做 unlink-then-rename 兜底（短暂缺失窗口影响并发 reader；重试已覆盖）
+- 不改 reconcile 触发时机（L4 仅展示级）
+- 不做历史 `.tmp` 残留 GC（screen-log-gc 范围外，可后续单列）
+
+## 5. 交付
+- worktree：`issue-48-eprm-atomicwrite-race`（spec 批准后）
+- PR 标题：`fix: harden host.json persistence against Windows EPERM rename races (issue #48)`，覆盖 L1-L3（L4 视确认）

package/docs/superpowers/specs/2026-08-30-post-exit-timing-fix-design.md

@@ -0,0 +1,80 @@
+# Spec: fix deterministic post-exit test failure after #43 (issue #46)
+
+## Problem
+
+`test/runner.integration.test.mjs` → `runner does not clobber a manual completion
+made during post-exit model passes` fails deterministically on Node 24 since
+#43 (`ffc2c8c`). Upstream `main` CI is red (`e14cc41`, `ffc2c8c`) and blocks
+subsequent PRs (#44).
+
+## Root cause (research: `~/.claude/github-issue-driven/zhuxixi/pi-agent-board/issue-46/`)
+
+#43 added a synchronous `updateCodeRefsFromEvidence()` call (git subprocesses,
+hundreds of ms) into `runner/job-runner.mjs`'s `persist()` chain, widening two
+pre-existing race windows:
+
+### Window 1 — `markCompleted` rejected (CI failure point)
+`persist()` order: `writeStatus` (endedAt visible) → `updateCodeRefsFromEvidence`
+(slow) → `writeState` (semanticState converges). The test sees `endedAt` while
+`state.json` is still `working`; the runner process is still alive
+(`pid.json` records the runner pid) → `isAgentBusy(row)` → `markCompleted`
+returns `'Wait for the active run to finish before marking done'`.
+
+### Window 2 — manual completion clobbered (the actual bug)
+`finalizeSemanticState` (`src/core/derive.mjs:33`) returns `"idle"` for a clean
+worker exit. `applyHeuristicAutoState` (`runner/job-runner.mjs:360`) calls
+`applyAutoStateToStatus` with the **in-memory** status; `isManualCompletion`
+requires `semanticState === "completed"` (it is `"idle"`), so the guard does not
+fire and the post-exit heuristic classification (`in_progress`, since
+`autoStateDoneDisabled()` defaults to true) overwrites the manual completion —
+`state.json` becomes `idle` + `autoState: {kind: "in_progress"}`.
+`maybeModelAutoState` has a fresh-read guard for this exact case;
+`applyHeuristicAutoState` does not.
+
+## Fix (minimal, four changes in `runner/job-runner.mjs`)
+
+### Change 1 — persist order
+Move `writeState` before `updateCodeRefsFromEvidence` inside `persist()`:
+```js
+writeStatus(root, status);
+writeRunEvidence(root, evidence);
+writeEvidence(root, evidence);
+writeState(root, projectViewState(status, now, readState(root, viewId)));
+updateCodeRefsFromEvidence(root, viewId, evidence, meta);
+```
+Semantics unchanged (code-refs extraction depends only on evidence + git).
+Verified experimentally: markCompleted assertion passes again.
+
+### Change 2 — heuristic persist goes through persistUnlessManual
+In the close handler, the `applyHeuristicAutoState` branch's `persist(true)`
+becomes `persistUnlessManual(true)` so a manual completion racing the
+heuristic classification is not overwritten. `persistUnlessManual` checks
+`isManualCompletion(readState(...))` (state.json — the only place
+`completeView` writes the `completed` + `autoState: null` signal; it only
+clears autoState in status.json) before writing.
+
+### Change 3 — applyHeuristicAutoState manual-completion guard
+Skip classification when state.json shows a manual completion, so the
+in-memory status isn't mutated in a way a later drain/persist could replay
+over the user's verdict:
+```js
+const latestState = readState(config.root, config.viewId);
+if (isManualCompletion(latestState)) return false;
+```
+
+### Change 4 — drainQueuedFollowUp / finalizeSteeringIfNeeded guards
+`drainQueuedFollowUp` (follow-up runs) and `finalizeSteeringIfNeeded`
+(plan approval resurrection) both early-return on
+`isManualCompletion(readState(...))` so the exit chain never starts new
+work or resurrects a row the user just manually completed.
+
+## Non-goals
+- No changes to #44/#45 code (windowsHide / control socket)
+- No handling of Windows-local EPERM cleanup noise (environment-only)
+- No auto-state state machine refactor
+
+## Verification
+1. clobber test ≥3× on Node 24: all pass (assertion part)
+2. Full `test/runner.integration.test.mjs`: failure set not worse than baseline
+3. `npm run typecheck` if present
+4. CI green (Node 22/24) after merge

package/package.json

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