@zhuxixi/pi-agent-board 0.4.3 → 0.5.1

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-circular-navigation.md

@@ -0,0 +1,308 @@
+# Circular List Navigation 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:** Make dashboard list arrow-key navigation wrap around (last ⇄ first) instead of clamping at boundaries.
+
+**Architecture:** Change index clamping to modulo wrap in `moveSelection()` and `peekStep()` in `src/ui/dashboard.ts`. Scroll-follow needs no change (`windowBody()` keeps the selected row visible regardless of direction). Behavior is covered by a new child-process test following the `ui-smoke` pattern.
+
+**Tech Stack:** Node 24 (`--experimental-transform-types`), node:test, TypeScript (parameter properties, no typecheck on test-support).
+
+**Spec:** `docs/superpowers/specs/2026-08-30-circular-navigation-design.md`
+
+## Global Constraints
+
+- Work only in the worktree: `/home/elling/git-repo/github/pi-agent-board/.pi/worktrees/issue-52-circular-navigation` (all paths below are relative to it).
+- `npm test` = `node --test test/*.test.mjs`; `npm run typecheck` = `tsc --noEmit`. Both must stay green.
+- `src/ui/dashboard.ts` uses TS parameter properties → it can only be imported from a child process spawned with `--experimental-transform-types` (the `test-support/ui-smoke.ts` pattern). Never import it directly from `test/*.test.mjs`.
+- `tsconfig.json` excludes `test/` and `test-support/` — no type casts needed in the probe script.
+- Do NOT touch the launch dialog pickers (`dashboard.ts` L539-547) — out of scope for this issue.
+- Commit per task with conventional commits; `git add <file>` per file, never `git add -A`.
+- `cur < 0` fallback semantics: out-of-list `selectedId` uses base index 0 — ↓ yields index 1 (second row, same as before); ↑ wraps to the last row (**changed** from the old clamp's first row — intentional, wrap-consistent, and effectively unreachable since `refresh()` keeps `selectedId` ∈ `orderedIds`).
+
+---
+
+### Task 1: `moveSelection()` 取模回绕 + 行为测试
+
+**Files:**
+- Modify: `src/ui/dashboard.ts:250-258` (`moveSelection`)
+- Create: `test-support/navigation-wrap.ts` (probe script, prints JSON)
+- Create: `test/dashboard-navigation.test.mjs` (node:test wrapper)
+
+**Interfaces:**
+- Consumes: existing `createService` (`src/runtime/service.mjs`), `createView` (`src/core/store.mjs`), `DashboardComponent` (`src/ui/dashboard.ts`), public method `handleInput(data: string)`.
+- Produces: `test-support/navigation-wrap.ts` prints one JSON line `{ ids: string[], seq: (string|null)[] }`; Task 2 extends the same probe with a peek-mode segment (do not rewrite the file structure).
+
+- [ ] **Step 1: Worktree dependency setup**
+
+Worktree has no `node_modules`. Symlink from the main checkout (instant; postinstall patches already applied there):
+
+```bash
+WT=/home/elling/git-repo/github/pi-agent-board/.pi/worktrees/issue-52-circular-navigation
+ln -s /home/elling/git-repo/github/pi-agent-board/node_modules "$WT/node_modules"
+ls "$WT/node_modules/@mariozechner"  # sanity: pi-tui present
+```
+
+(Fallback if the symlink misbehaves: `cd "$WT" && npm ci`.)
+
+- [ ] **Step 2: Write the failing test probe**
+
+Create `test-support/navigation-wrap.ts`:
+
+```ts
+// Nav wrap probe: construct a dashboard with 3 views, drive arrow keys through
+// the public handleInput(), and report the selection sequence as JSON.
+// Run via `node --experimental-transform-types` (dashboard.ts uses TS
+// parameter properties). Not typechecked (tsconfig excludes test-support).
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createService } from "../src/runtime/service.mjs";
+import { createView } from "../src/core/store.mjs";
+import { DashboardComponent } from "../src/ui/dashboard.ts";
+
+const root = mkdtempSync(join(tmpdir(), "agentview-nav-wrap-"));
+createView(root, { id: "v1", name: "one", cwd: root });
+createView(root, { id: "v2", name: "two", cwd: root });
+createView(root, { id: "v3", name: "three", cwd: root });
+
+const service = createService({
+	root,
+	runnerScript: "/no/runner.mjs",
+	piCommand: "pi",
+	piArgsPrefix: [],
+	defaultCwd: root,
+	launch: () => ({ pid: null, configPath: "/no/config.json" }),
+	launchHost: () => ({ pid: null, configPath: "/no/host-config.json" }),
+	launchTitle: () => ({ pid: null, configPath: "/no/title-config.json" }),
+});
+
+const writes = [];
+const tui = {
+	terminal: { rows: 24, cols: 80, columns: 80, write: (d) => writes.push(d) },
+	requestRender: () => {},
+};
+const theme = { fg: (_c, t) => t, bold: (t) => t };
+
+const dash = new DashboardComponent(tui, theme, {}, () => {}, {
+	service,
+	root,
+	defaultCwd: root,
+	availableModels: [],
+	currentModel: null,
+	currentThinkingLevel: "off",
+});
+
+// TS-private is runtime-accessible; read white-box state for assertions.
+const ids = dash.orderedIds;
+const seq = [];
+seq.push(dash.selectedId); // initial selection = ids[0]
+dash.handleInput("\x1b[B"); // ↓ -> ids[1]
+seq.push(dash.selectedId);
+dash.handleInput("\x1b[B"); // ↓ -> ids[2]
+seq.push(dash.selectedId);
+dash.handleInput("\x1b[B"); // ↓ at last -> WRAP to ids[0]
+seq.push(dash.selectedId);
+dash.handleInput("\x1b[A"); // ↑ at first -> WRAP to ids[2]
+seq.push(dash.selectedId);
+
+dash.dispose();
+console.log(JSON.stringify({ ids, seq }));
+```
+
+- [ ] **Step 3: Write the failing test wrapper**
+
+Create `test/dashboard-navigation.test.mjs`:
+
+```js
+import assert from "node:assert/strict";
+import { execFileSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { join } from "node:path";
+import test from "node:test";
+
+const ROOT_DIR = fileURLToPath(new URL("../", import.meta.url));
+const PROBE = join(ROOT_DIR, "test-support", "navigation-wrap.ts");
+
+test("list arrow-key navigation wraps around at both ends (issue #52)", () => {
+	// dashboard.ts uses TS parameter properties, which strip-only mode rejects;
+	// --experimental-transform-types handles them (Node 22.7+ / 24).
+	const out = execFileSync(process.execPath, ["--experimental-transform-types", PROBE], {
+		encoding: "utf8",
+		timeout: 30_000,
+	});
+	const { ids, seq } = JSON.parse(out);
+	assert.equal(ids.length, 3, "probe must see 3 rows");
+	assert.deepEqual(
+		seq,
+		[ids[0], ids[1], ids[2], ids[0], ids[2]],
+		"down past the last row wraps to first; up past the first wraps to last",
+	);
+});
+```
+
+- [ ] **Step 4: Run test to verify it fails**
+
+```bash
+cd /home/elling/git-repo/github/pi-agent-board/.pi/worktrees/issue-52-circular-navigation
+node --test test/dashboard-navigation.test.mjs
+```
+
+Expected: FAIL — `seq[3]` is `ids[2]` (clamped at last) instead of `ids[0]`, and `seq[4]` is `ids[0]` instead of `ids[2]`.
+
+If the probe itself crashes (e.g. key sequence mismatch), debug the probe first — `matchesKey(data, Key.up/down)` must match `\x1b[A` / `\x1b[B]`; verify against `@mariozechner/pi-tui` `Key` defaults if not.
+
+- [ ] **Step 5: Implement modulo wrap in `moveSelection()`**
+
+In `src/ui/dashboard.ts`, replace:
+
+```ts
+	private moveSelection(delta: number): void {
+		if (this.orderedIds.length === 0) return;
+		const cur = this.selectedId ? this.orderedIds.indexOf(this.selectedId) : 0;
+		const next = Math.max(0, Math.min(this.orderedIds.length - 1, (cur < 0 ? 0 : cur) + delta));
+```
+
+with:
+
+```ts
+	private moveSelection(delta: number): void {
+		if (this.orderedIds.length === 0) return;
+		const cur = this.selectedId ? this.orderedIds.indexOf(this.selectedId) : 0;
+		const len = this.orderedIds.length;
+		// Wrap around both ends: down past last -> first, up past first -> last.
+		const next = (((cur < 0 ? 0 : cur) + delta) % len + len) % len;
+```
+
+Everything below that line (`const nextId = ...` through the end of the method) stays unchanged — the `nextId === this.selectedId` early return keeps single-row lists a no-op.
+
+- [ ] **Step 6: Run test to verify it passes**
+
+```bash
+cd /home/elling/git-repo/github/pi-agent-board/.pi/worktrees/issue-52-circular-navigation
+node --test test/dashboard-navigation.test.mjs
+```
+
+Expected: PASS.
+
+- [ ] **Step 7: Full test suite + typecheck**
+
+```bash
+cd /home/elling/git-repo/github/pi-agent-board/.pi/worktrees/issue-52-circular-navigation
+npm test && npm run typecheck
+```
+
+Expected: all green.
+
+- [ ] **Step 8: Commit**
+
+```bash
+cd /home/elling/git-repo/github/pi-agent-board/.pi/worktrees/issue-52-circular-navigation
+git add src/ui/dashboard.ts test-support/navigation-wrap.ts test/dashboard-navigation.test.mjs
+git commit -m "fix: wrap list arrow-key navigation at both ends (issue #52)"
+```
+
+---
+
+### Task 2: `peekStep()` 取模回绕 + peek 段测试
+
+**Files:**
+- Modify: `src/ui/dashboard.ts:1094-1101` (`peekStep`)
+- Modify: `test-support/navigation-wrap.ts` (append peek segment)
+- Modify: `test/dashboard-navigation.test.mjs` (assert extended sequence)
+
+**Interfaces:**
+- Consumes: Task 1's probe file and test wrapper; `peekId` / `mode` are TS-private fields on `DashboardComponent`, runtime-accessible from the probe (same white-box pattern as `selectedId`).
+- Produces: probe JSON gains nothing new — `seq` grows by one entry (peek-mode wrap result); test asserts the 6-element sequence.
+
+- [ ] **Step 1: Extend the probe with a peek-mode segment (failing)**
+
+In `test-support/navigation-wrap.ts`, insert immediately BEFORE `dash.dispose();`:
+
+```ts
+// Peek mode: stepping down from the last row wraps to the first.
+dash.peekId = ids[2];
+dash.selectedId = ids[2];
+dash.mode = "peek";
+dash.handleInput("\x1b[B"); // ↓ at last in peek -> WRAP to ids[0]
+seq.push(dash.selectedId);
+```
+
+And in `test/dashboard-navigation.test.mjs`, replace the final assertion with:
+
+```js
+	assert.deepEqual(
+		seq,
+		[ids[0], ids[1], ids[2], ids[0], ids[2], ids[0]],
+		"list and peek navigation wrap around at both ends",
+	);
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+```bash
+cd /home/elling/git-repo/github/pi-agent-board/.pi/worktrees/issue-52-circular-navigation
+node --test test/dashboard-navigation.test.mjs
+```
+
+Expected: FAIL — `seq[5]` is `ids[2]` (peek clamped at last) instead of `ids[0]`.
+
+- [ ] **Step 3: Implement modulo wrap in `peekStep()`**
+
+In `src/ui/dashboard.ts`, replace:
+
+```ts
+	private peekStep(delta: number): void {
+		if (!this.peekId) return;
+		const idx = this.orderedIds.indexOf(this.peekId);
+		if (idx < 0) return;
+		const next = Math.max(0, Math.min(this.orderedIds.length - 1, idx + delta));
+```
+
+with:
+
+```ts
+	private peekStep(delta: number): void {
+		if (!this.peekId) return;
+		const idx = this.orderedIds.indexOf(this.peekId);
+		if (idx < 0) return;
+		const len = this.orderedIds.length;
+		// Wrap around both ends, same as moveSelection().
+		const next = ((idx + delta) % len + len) % len;
+```
+
+The two lines below (`this.peekId = ...; this.selectedId = ...`) stay unchanged. `len` is guaranteed `>= 1` here because `idx >= 0` implies the id was found in `orderedIds`.
+
+- [ ] **Step 4: Run test to verify it passes**
+
+```bash
+cd /home/elling/git-repo/github/pi-agent-board/.pi/worktrees/issue-52-circular-navigation
+node --test test/dashboard-navigation.test.mjs
+```
+
+Expected: PASS.
+
+- [ ] **Step 5: Full test suite + typecheck**
+
+```bash
+cd /home/elling/git-repo/github/pi-agent-board/.pi/worktrees/issue-52-circular-navigation
+npm test && npm run typecheck
+```
+
+Expected: all green.
+
+- [ ] **Step 6: Commit**
+
+```bash
+cd /home/elling/git-repo/github/pi-agent-board/.pi/worktrees/issue-52-circular-navigation
+git add src/ui/dashboard.ts test-support/navigation-wrap.ts test/dashboard-navigation.test.mjs
+git commit -m "fix: wrap peek-mode stepping at both ends (issue #52)"
+```
+
+---
+
+## Self-Review 记录
+
+- **Spec coverage**：spec 改动点 #1 → Task 1；改动点 #2 → Task 2；滚动跟随"不改"已在 Global Constraints 外无对应任务（无需任务）；launch picker 非目标 → Global Constraints 显式禁止。测试要求 → 两任务各带 TDD 循环。✅ 无缺口。
+- **Placeholder scan**：无 TBD/TODO；每个代码步骤含完整可运行代码。✅
+- **Type consistency**：`orderedIds` / `selectedId` / `peekId` / `mode` / `handleInput(data: string)` / `dispose()` 名称与 `src/ui/dashboard.ts` 实际成员一致；probe 的 JSON 形状 `{ ids, seq }` 在两个任务间一致（Task 2 只扩 seq 长度）。✅

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.