@zhuxixi/pi-agent-board 0.4.3 → 0.5.1

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

@@ -0,0 +1,47 @@
+# Spec: dashboard 列表方向键导航循环回绕（issue #52）
+
+日期：2026-08-30 · 状态：draft（等用户确认）
+
+## 根因报告
+
+**现象**：dashboard 主列表 ↑/↓ 移动选中项，到达首/尾边界后按键无效，无法循环。
+
+**根因**（已通过代码直读确认，systematic-debugging Phase 1 完成）：
+`src/ui/dashboard.ts` `moveSelection()`（L250-258）用 `Math.max(0, Math.min(len-1, ...))` 钳制新索引，而非取模回绕。该写法来自 MVP commit `72c0d8f`，非有意设计。
+
+**调用链**：`handleListKey`（L334-335，normal 模式）与 `handleSelectKey`（L370-371，multi-select 模式）→ `moveSelection(±1)`。
+
+## 设计
+
+### 改动点
+
+| # | 位置 | 改动 |
+|---|------|------|
+| 1 | `moveSelection()` L250-258 | 钳制 → 取模回绕：`next = ((base + delta) % len + len) % len` |
+| 2 | `peekStep()` L1094-1101 | 同上，保持与主列表一致 |
+
+### 决策表
+
+| 决策点 | 决定 | 理由 |
+|--------|------|------|
+| `cur < 0`（selectedId 不在列表中） | 取模语义：按 ↓ 得 index 1（第二条，与旧实现一致）；按 ↑ 得 index len-1（最后一条，**与旧实现不同**——旧钳制得第一条）。有意为之：与回绕语义一致；该路径实际不可达（`refresh()` 不变量保证按键处理时 selectedId ∈ orderedIds，或 selectedId=null 走 base 0） | 修正记录（Zima CR round 1）：旧版写"保持现状语义"不属实，↑ 方向兜底行为确有变化 |
+| 单条列表（len=1） | 取模后索引恒为 0，`nextId === selectedId` early return 挡掉无效更新 | 现有兜底继续生效，无需特判 |
+| 空列表 | 现有 `length === 0` early return 保留 | 不变 |
+| 滚动跟随 | **不改**——`windowBody()` 渲染时强制选中行可见，方向无关，回绕自动跟随 | 已验证 |
+| 按键热路径性能 | 改动只涉及一次取模运算，不影响 #9/PR #12 的 prewarm debounce 设计 | 调研结论 |
+| launch picker（cwd/model/thinking，L539-547） | **本 issue 不改**（非目标），另开 issue 跟踪 | 弹窗内短列表，回绕收益低；避免一次 PR 混两个行为变更 |
+
+### 非目标
+
+- launch 对话框 picker 的回绕（另议）
+- 任何渲染层、滚动层改动
+- 其他模式的按键行为
+
+### 测试
+
+目前 `moveSelection`/`peekStep` 无测试覆盖。补一个针对 Dashboard 的轻量测试（参考 `test/ui-smoke.test.mjs` 的实例化方式）：构造 3 条 orderedIds，断言 尾→↓→首、首→↑→尾 的回绕行为，以及单条/空列表不炸。
+
+## 验证
+
+1. `npm test` 全绿（含新增用例）
+2. 手动跑 dashboard：多 session 列表，尾按 ↓ 回首、首按 ↑ 回尾，peek 模式同样验证

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/docs/superpowers/specs/2026-08-30-pty-attach-quality-debt-design.md

@@ -0,0 +1,105 @@
+# Spec: pty-attach.ts legacy quality debt cleanup (issue #8)
+
+- **Date**: 2026-08-30
+- **Issue**: zhuxixi/pi-agent-board#8
+- **Type**: chore — zero behavior change (comments + signature trim only)
+- **Status**: approved and implemented (final review clean; see docs/superpowers/plans/2026-08-30-pty-attach-quality-debt.md)
+
+## Background
+
+pi-lens flagged 10 legacy quality issues in `src/ui/pty-attach.ts` on 2026-08-21
+(upstream original author's style, pre-existing). The issue tracked them for
+separate cleanup so they wouldn't pollute feature PRs. Since then, #45 and #48
+modified the file, so every line number in the issue has drifted. A fresh scan
+of current main (1324 lines) found:
+
+- **9 empty `catch {}` blocks** (issue said 8): L484, 510, 724, 745, 755, 766,
+  924, 951, 1010
+- **1 `as unknown as` cast without a SAFETY comment**: L795 (`currentSize()`)
+- **1 unused parameter**: L970 (`project(height, width)` — `width` never read)
+
+Two other catches are out of scope: L902 (`onSocketData`, multi-line catch with
+an explanatory comment) and L1048 (`openExternalTarget`, catch returns `false`).
+
+## Goals
+
+1. Every empty catch documents *why* silence is correct (intentional vs forgot).
+2. The as-cast states the invariant that makes it safe.
+3. No unused parameters in `project()`.
+4. Zero behavior change: no logic, no logging, no reformatting beyond the edits.
+
+## Non-goals
+
+- No logging infrastructure (no logger is imported in pty-attach today; these
+  failures have no consumer; `forwardTerminalProtocols` runs at frame frequency
+  and would spam).
+- No changes outside `src/ui/pty-attach.ts`.
+- No touching L902/L1048 (already documented/behavioral).
+- No drive-by refactors of nearby code.
+
+## Decision: empty catches stay silent + explanatory comment (Option A)
+
+Rejected alternative (Option B): debug-level logging — needs new UI-layer log
+plumbing, has no consumer, and high-frequency paths would flood output.
+
+Precedent in this repo: `dashboard.ts` uses `/* best effort: stats must never
+block dispatch */` style comments for the same pattern.
+
+Per-site comment text (implementation is mechanical):
+
+| Line | Method | Failure tolerated | Comment to add |
+|------|--------|-------------------|----------------|
+| 484 | `enableMouseScroll()` | `terminal.write(XTSHIFTESCAPE/MOUSE_ENABLE)` | `/* best-effort: some terminals reject these sequences; mouse reporting is optional */` |
+| 510 | `disableMouseScroll()` | `terminal.write(MOUSE_DISABLE)` | `/* best-effort: terminal may already be gone at teardown */` |
+| 724 | `copySelectionToClipboard()` | OSC52 write | `/* best-effort: OSC52 clipboard support is optional */` |
+| 745 | `pastePrimarySelection()` inner timer | `child.kill("SIGKILL")` | `/* the child may have already exited before the timeout fired */` |
+| 755 | `pastePrimarySelection()` outer | `spawn("xclip")` | `/* silent no-op when xclip is absent — documented contract of this helper */` |
+| 766 | `writePrimarySelection()` | `spawn("xclip")` | `/* silent no-op when xclip is absent */` |
+| 924 | `forwardTerminalProtocols()` | per-sequence `terminal.write` | `/* best-effort: forwarded sequences are enhancements, never critical */` |
+| 951 | `replayScreenLog()` | screen.log read/replay | `/* best-effort: a missing or racing screen.log must not block attach */` |
+| 1010 | `close()` | `socket.destroy()` | `/* best-effort teardown: socket may already be destroyed */` |
+
+## Decision: SAFETY comment for the as-cast (L795)
+
+`currentSize()` reads `this.tui.terminal as unknown as { cols?: number;
+columns?: number; rows?: number } | undefined`. Comment to add above the line:
+
+```
+// SAFETY: duck-typed read — Pi TUI's Terminal type does not consistently expose
+// cols/columns/rows across versions (see resizeIfNeeded below). Runtime
+// fallbacks (120/24) keep this safe when the fields are absent.
+```
+
+## Decision: delete `width` param (not `_` prefix)
+
+`private project(height: number, width: number)` → `private project(height: number)`;
+single call site L271 `this.project(bodyHeight, width)` → `this.project(bodyHeight)`.
+Deleting is cleaner than `_width`: private method, exactly one caller, no
+interface stability concerns.
+
+## Verification
+
+1. `npm run typecheck` — clean.
+2. `npm test` — all pass (attach-related suites must stay green).
+3. `grep -c "catch {}" src/ui/pty-attach.ts` — 0 (each expanded to a documented
+   3-line catch block).
+4. `grep -n "project(" src/ui/pty-attach.ts` — signature and call site both
+   single-arg.
+5. Coverage thresholds unaffected (comments + signature trim don't move lines/funcs/branches).
+
+## Risks & mitigations
+
+- **Line drift vs this spec**: implementation re-locates sites by method name
+  (as in the table), not by line number.
+- **Untracked files in main checkout** (`scratch/`, `test-support/*`,
+  `test/pty-attach-*.test.mjs`): all work happens in a worktree; staging is
+  per-file, never `git add -A`.
+- **Zero-behavior guarantee**: no statement is added/removed except the param
+  deletion and its call-site argument; review diff must show comments + two-line
+  signature/call-site change only.
+
+## Rollout
+
+- Worktree: `issue-8-pty-attach-quality-debt` (from main).
+- Spec lands in worktree `docs/superpowers/specs/2026-08-30-pty-attach-quality-debt-design.md`
+  as the first commit, then plan → implement → local CR → PR.

package/docs/superpowers/specs/2026-08-30-readme-v2-design.md

@@ -0,0 +1,115 @@
+# Design: User-first README v2 for Pi Agent Board
+
+**Issue:** #51
+**Date:** 2026-08-30
+**Status:** Approved
+**Language:** English
+
+## Outcome
+
+Rewrite `README.md` into a user-first English guide that accurately describes the currently shipped Pi Agent Board package, verified by current source, package metadata, tests, and manual verification notes.
+
+The README will take a new user from installation to a first background session, then serve as a practical reference for dashboard actions, attach mode, filters, configuration, limitations, troubleshooting, and maintainer entry points.
+
+This is documentation-only. No product behavior changes are part of the work.
+
+## Source of truth
+
+- `package.json` is authoritative for package identity, version, Node engine, repository, scripts, and Pi package metadata.
+- `src/index.ts`, `src/commands/*`, `src/ui/dashboard.ts`, `src/ui/pty-attach.ts`, `src/runtime/service.mjs`, and `src/core/*` are authoritative for shipped behavior.
+- `PRD.md`, `PROGRESS.md`, `REMAINING_WORK.md`, and dated design/plan documents are historical or planning material; they must not advertise disabled or planned behavior.
+- Every command, shortcut, environment variable, default, and limitation must be checked against an exact source location or a verified command.
+- Clearly distinguish shipped behavior, fallback behavior, disabled behavior, and planned/internal behavior.
+- Avoid hard-coded test counts; state that CI and `npm run verify` are authoritative.
+- Use `AGENT_BOARD_*` names for new configuration. Mention selected `AGENT_VIEW_*` names only as migration aliases.
+
+## Information architecture
+
+Use this task-oriented structure:
+
+1. Title, package links, value proposition
+2. What it does / when to use it
+3. Requirements
+4. Installation
+5. Quick start
+6. Entry points
+7. Dashboard workflow
+8. Views and actions
+9. States, grouping, and filters
+10. Attach mode
+11. Persistence, safety, and limitations
+12. Configuration
+13. Troubleshooting
+14. Development
+15. Publishing
+16. Further reading
+
+The first half should be readable without knowing Pi internals. Advanced QA and implementation details should be linked rather than expanded inline.
+
+## Content requirements
+
+### Positioning
+
+State that Agent Board is a full-screen TUI dashboard for dispatching, monitoring, inspecting, replying to, attaching to, and managing multiple durable background Pi sessions. Emphasize global cross-project visibility, resumability, dashboard triage, inline reply/evidence, and PTY/JSON fallback. Do not imply cloud execution, multi-user sharing, automatic worktree isolation, or full Claude parity.
+
+### Requirements and installation
+
+Include Pi, Node.js 20+, working Pi provider authentication, and PTY support for live attach/start-and-attach. Use `pi install npm:@zhuxixi/pi-agent-board` everywhere. Keep local path installation and symlink discovery as separate alternatives. Include a short one-shot auth sanity check and link detailed checks to `VERIFY.md`.
+
+### Quick start and entry points
+
+Use a concrete five-step first-task flow: `i` INSERT mode → type task → `Enter` to open the Start session dialog → review cwd/model/thinking/action → `Enter` on Start session to launch. Explain Space Peek, `r` in Peek, `v`, `e`, attach with Enter/Right/`>`, and that PTY detach with `Left` is gated by the child input line: it detaches on empty input, is forwarded while editing, and remains unconditional when disconnected. `Ctrl+]` is not a detach key — it is passed through to the child Pi editor.
+
+Document `/agent-board`, `pi /agent-board`, `pi --agent-board`, and `/bg [prompt]`, including that `--agent-board` startup cannot attach and normal `/agent-board` is required for attach.
+
+### Dashboard and actions
+
+Explain Normal vs INSERT mode, draft-vs-empty `Enter`, Ctrl+N entering INSERT mode with a pre-filled `hello` prompt (the next Enter opens the launch flow), cwd favorites/path completion, model/thinking/action fields, persisted launch preferences, and PTY-dependent start-and-attach fallback.
+
+Document exact destructive semantics: `d` confirms inactive Done; manual completion is default; Ctrl+X twice quickly archives; archive preserves the session file; X deletes inactive rows in the selected state; `m` batch selection supports Space/a/u/d/Ctrl+X.
+
+Keep shortcut reference separated by view. State that `r` is available from Peek/Transcript/Evidence, not directly from the main list, and pending Pi questions must be answered via attach rather than inline reply.
+
+### States, views, and filters
+
+Document the seven labels: Queued, Running, Needs answer, Needs instructions, Done, Failed, Stopped. Explain separate process liveness, state grouping, folder grouping, pinned-first stable creation ordering, unread indicators, Peek, read-only transcript, Evidence/Diagnostics, durable FIFO follow-up queue, and `qN`.
+
+Document filter syntax: `s:`, `review:ready`, `diag:stalled`, `evidence:error`, `queued:true|yes|1`, `steer:`, and free-text AND over name/summary/cwd. Explain aliases and case-insensitivity. Caveat that `diag:stalled` can consume persisted diagnostics but there is no general current provider-stall detector.
+
+Explain locally extracted issue/PR badges and optional per-root `providers.json`, without asserting an unverified custom schema.
+
+### Attach and persistence
+
+Describe PTY attach, conditional `Left` detach (empty child input detaches; edited input forwards the key; disconnected hosts can always be exited), `Ctrl+]` passthrough to the child Pi editor, PageUp/PageDown/Home/End/mouse wheel scrollback, link opening, drag/double-click copy, optional X11 middle-click paste, clipboard/image passthrough, cold-host loading/reconnect, warm host pool, and Windows named-pipe/hidden-console behavior without promising terminal-emulator parity.
+
+Explain PTY vs JSON fallback, adopted external-session PTY requirement, and `!` diagnostics. Document the default store at `~/.pi/agent/agent-board/`, high-level artifacts, persistence across reload/restart/worker exit, and stale-row reconciliation.
+
+Prominently state that worktree isolation is currently disabled and not automatically created; same-repository concurrent writes are unsafe unless the user manually avoids overlap or supplies isolation. Also state no cloud/multi-user coordination, row deletion preserves session files, auth remains required, startup attach limitation, and PTY native-dependency limitation.
+
+### Configuration
+
+List supported user-facing settings with exact defaults/disable values: ROOT, AUTO_STATE, AUTO_STATE_MODEL, AUTO_STATE_NO_DONE, SUMMARY_MODEL, TITLE_MODEL, TITLE_THINKING_LEVEL, CODE_REFS, DISABLE_PTY, FORCE_PTY, ATTACH_MOUSE, ENABLE_MOUSE_SCROLL, WHEEL_LINES, MAX_WARM_HOSTS, WARM_HOST_TTL_MS, ATTACH_NATIVE_PASTE, FORWARD_OSC52, and FORWARD_IMAGES.
+
+Do not list internal child markers. Do not advertise `AGENT_BOARD_ALLOW_PIPE_FALLBACK` as a normal user toggle because current service dispatch does not pass the ambient variable into the injected PTY runner config. Mention selected legacy `AGENT_VIEW_*` aliases only as compatibility paths.
+
+### Troubleshooting and maintainer sections
+
+Troubleshoot stuck Running/auth, `node-pty unavailable`, slow/reconnecting attach, start-and-attach fallback, rejected inline replies, and same-repo conflicts. Link `VERIFY.md`.
+
+Keep Development to `npm install` and `npm run verify`; explain verify briefly. Keep Publishing to verify, version bump, and publish. Link further reading (`VERIFY.md`, `PRD.md`, `PROGRESS.md`, and relevant design docs) without turning README into a historical log.
+
+## Supporting documentation
+
+Correct the old unscoped install command in `VERIFY.md` from `pi install npm:pi-agent-board` to `pi install npm:@zhuxixi/pi-agent-board`, because README links to it. Make no other supporting-doc changes.
+
+## Validation
+
+- Line-by-line compare the final README with source and package metadata.
+- Check Markdown link targets and stale package names/status wording.
+- Run targeted documentation scans.
+- Run verification in the isolated worktree; do not count the main session's untracked PTY tests as evidence.
+- Final diff should contain README, this approved spec, the implementation plan, and the one-line VERIFY correction only.
+
+## Non-goals
+
+No runtime behavior, worktree implementation, plan-approval UI, provider-stall detection, docs generator, changelog, or broad PRD/progress rewrite.

package/package.json

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