@zhuxixi/pi-agent-board 0.5.0 → 0.5.2

package/docs/superpowers/plans/2026-09-03-detach-gate-glyph-fallback.md

@@ -0,0 +1,146 @@
+# Detach-Gate Tier-2 Glyph Fallback Tightening 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:** Tighten the attach-surface `←` detach gate's tier-2 glyph fallback so content glyph lines (markdown table rows / quotes / drafts) no longer trap the user when `editor_state` is unavailable (issue #69).
+
+**Architecture:** One-line condition change in `PtyAttachComponent.childInputLooksEmpty()` (src/ui/pty-attach.ts): the tier-2 loop now only treats an EMPTY prompt-glyph line as proof of an empty editor (`isProbablyPiInputLine(line) && isProbablyEmptyPiInputLine(line)`), skipping content glyph lines; loop-end escape stays authoritative. Tier-1 (inverse fake-cursor anchor), the `editor_state` authoritative path (#71), and all protocol/public API surfaces are untouched. Behavior is pinned by two new detach-gate smoke scenarios (K1/K2) asserted inside the existing `test/pty-attach-detach-gate.test.mjs` case.
+
+**Tech Stack:** TypeScript (Node `--experimental-transform-types`), node:test, @xterm/headless in-memory smoke harness.
+
+**Spec:** `docs/superpowers/specs/2026-09-03-detach-gate-glyph-fallback-design.md` (accepted 2026-09-03, Option B).
+
+**Acceptance traceability:** Task 1 → A1, A2, A3, A4 (automated). Task 2 → U1, U2 (manual, human-executed after push, before merge). No orphan tasks, no orphan acceptance IDs.
+
+## Global Constraints
+
+- Work only inside this worktree: `/home/elling/git-repo/github/pi-agent-board/.pi/worktrees/issue-69-detach-gate-glyph-fallback`. Never edit the main checkout at `/home/elling/git-repo/github/pi-agent-board` (`node_modules` there is only the read-only symlink target).
+- Commit messages: English, conventional commits, suffix `(issue #69)`.
+- Stage files explicitly (`git add <file> ...`); never `git add -A`.
+- Do NOT touch: tier-1 inverse anchor, `editor_state` path (`resolveEditorEmpty`, reporter, runner), README.md, or the pure helpers in `src/core/pty-input.mjs` (spec non-goals).
+- Do NOT extract new pure functions — the tightened tier-2 is constant-true by design; the discriminating tests live at smoke level (spec §4).
+- Every new online-gate smoke scenario MUST pin `connected=true` explicitly before `handleInput` (B-section convention; otherwise the disconnected-escape semantics fire instead of the online gate).
+- `node --test` case count stays 437: the new smoke keys are assertions inside the existing test case in `test/pty-attach-detach-gate.test.mjs`, not new `test()` blocks.
+- Verification commands: `npm test` (expect 437 pass, 0 fail) and `npm run typecheck` (expect 0 errors). Faster smoke-only loop: `node --experimental-transform-types test-support/detach-gate-smoke.ts` (prints a JSON of scenario keys).
+
+---
+
+### Task 1: Tighten tier-2 glyph fallback (TDD) — covers A1, A2, A3, A4
+
+**Files:**
+- Modify: `src/ui/pty-attach.ts` (the tier-2 loop inside `childInputLooksEmpty()`, right after the `// Fallback: Pi variants that render no fake cursor` comment, line 359)
+- Test: `test-support/detach-gate-smoke.ts` (insert two scenarios after the J-scenario block, before the `// E2.` comment)
+- Test: `test/pty-attach-detach-gate.test.mjs` (two assertions after the `leftHelloNullResetsStaleEditorState` assertion)
+
+**Interfaces:**
+- Consumes: `isProbablyPiInputLine(line)`, `isProbablyEmptyPiInputLine(line)` from `src/core/pty-input.mjs` (both already imported in `pty-attach.ts`); smoke harness helpers `makeAttach()`, `writeToTerm(attach, data)` (already defined in the smoke file).
+- Produces: smoke output keys `leftDetachesOnTableRowsWithoutFakeCursor` (A1) and `leftDetachesOnContentGlyphFallback` (A2) in the JSON printed by `test-support/detach-gate-smoke.ts`.
+
+- [ ] **Step 1: Write the failing smoke scenarios (A1, A2)**
+
+In `test-support/detach-gate-smoke.ts`, insert these two blocks immediately BEFORE the line starting with `// E2. A terminal at the minimum supported size`:
+
+```ts
+// K1. Issue #69 real-world shape: zero inverse cells anywhere in the buffer,
+// the chat area carries a markdown table row (`│ … │`) and a quote line
+// (`> …`) that isProbablyPiInputLine misreads as a draft-bearing input line,
+// and editor_state never arrives (editorEmpty stays null — child without the
+// reporter). tier-2 must skip content glyph lines and ← must detach: the
+// gate philosophy is "never trap the user" (issues #42/#48).
+{
+	const { attach, sent, didDetach } = makeAttach();
+	await writeToTerm(attach, "chat content\r\n│ Issue #778 │ open │\r\n> quote line\r\n");
+	(attach as unknown as { connected: boolean }).connected = true;
+	attach.handleInput("\x1b[D");
+	out.leftDetachesOnTableRowsWithoutFakeCursor = didDetach() && sent.length === 1 && sent[0].type === "detach";
+	attach.dispose();
+}
+
+// K2. The deliberate flip side of K1 — pair with scenario B: the SAME draft
+// shape (`> draft`) is gated when the fake cursor is present (tier-1, scenario
+// B) but detaches when the buffer carries no inverse cells (tier-2 fallback
+// cannot tell a real draft from a table row; a spurious detach beats a trapped
+// user, and detach never loses the draft — the child session keeps running).
+// This pins the intentional loss of fallback draft protection (issue #69);
+// restoring it needs the mid-term dock-structure anchor, not a revert.
+{
+	const { attach, sent, didDetach } = makeAttach();
+	await writeToTerm(attach, "chat content\r\n> draft\r\n");
+	(attach as unknown as { connected: boolean }).connected = true;
+	attach.handleInput("\x1b[D");
+	out.leftDetachesOnContentGlyphFallback = didDetach() && sent.length === 1 && sent[0].type === "detach";
+	attach.dispose();
+}
+```
+
+In `test/pty-attach-detach-gate.test.mjs`, insert these two assertions immediately AFTER the `assert.equal(parsed.leftHelloNullResetsStaleEditorState, true, ...)` line:
+
+```js
+	assert.equal(parsed.leftDetachesOnTableRowsWithoutFakeCursor, true, "← must detach when a zero-inverse buffer holds only table/quote glyph lines and editor_state is unknown (issue #69)");
+	assert.equal(parsed.leftDetachesOnContentGlyphFallback, true, "← must detach on a content glyph line in the no-fake-cursor fallback — spurious detach beats trapping (issue #69)");
+```
+
+- [ ] **Step 2: Run to verify both fail (A1, A2 red)**
+
+Run: `node --experimental-transform-types test-support/detach-gate-smoke.ts`
+Expected: JSON contains `"leftDetachesOnTableRowsWithoutFakeCursor":false` and `"leftDetachesOnContentGlyphFallback":false` (all pre-existing keys stay `true`).
+
+- [ ] **Step 3: Implement the tier-2 tightening (minimal change)**
+
+In `src/ui/pty-attach.ts`, inside `childInputLooksEmpty()`, replace this exact block:
+
+```ts
+		// Fallback: Pi variants that render no fake cursor — look for a
+		// prompt-glyph line.
+		for (let y = active.baseY + active.length - 1; y >= active.baseY; y--) {
+			const line = active.getLine(y)?.translateToString(true) ?? "";
+			if (isProbablyPiInputLine(line)) return isProbablyEmptyPiInputLine(line);
+		}
+```
+
+with:
+
+```ts
+		// Fallback: Pi variants that render no fake cursor — look for an EMPTY
+		// prompt-glyph line. Only an empty glyph line proves an empty editor:
+		// content glyph lines (markdown table rows `│ … │`, quotes `> …`, or a
+		// real draft in a no-fake-cursor Pi variant) cannot be told apart, and
+		// trapping the user is worse than a spurious detach (issue #69) — skip
+		// them and keep scanning; the loop-end escape below stays authoritative.
+		for (let y = active.baseY + active.length - 1; y >= active.baseY; y--) {
+			const line = active.getLine(y)?.translateToString(true) ?? "";
+			if (isProbablyPiInputLine(line) && isProbablyEmptyPiInputLine(line)) return true;
+		}
+```
+
+- [ ] **Step 4: Run smoke to verify the fix (A1, A2 green)**
+
+Run: `node --experimental-transform-types test-support/detach-gate-smoke.ts`
+Expected: EVERY key in the JSON is `true`, including the two new ones.
+
+- [ ] **Step 5: Full automated acceptance (A3, A4)**
+
+Run: `npm test`
+Expected: `pass 437`, `fail 0` (count unchanged — the new keys are assertions inside the existing test case).
+
+Run: `npm run typecheck`
+Expected: exit 0, no output errors.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add src/ui/pty-attach.ts test-support/detach-gate-smoke.ts test/pty-attach-detach-gate.test.mjs
+git commit -m "fix: tighten ← detach tier-2 glyph fallback to empty-only lines (issue #69)"
+```
+
+### Task 2: Manual verification U1/U2 (human-executed; after PR branch is pushed, before merge) — covers U1, U2
+
+> Not a subagent task. The controller surfaces this checklist to the human partner at the pre-merge gate.
+
+**Environment:** the running extension copy is the git-source clone at `~/.pi/agent/git/github.com/zhuxixi/pi-agent-board` (currently at 0.5.1 / fac9e91). Steps:
+
+- [ ] **Step 1:** `git -C ~/.pi/agent/git/github.com/zhuxixi/pi-agent-board fetch origin && git -C ~/.pi/agent/git/github.com/zhuxixi/pi-agent-board checkout issue-69-detach-gate-glyph-fallback`
+- [ ] **Step 2:** Restart pi IN ANOTHER TERMINAL (restarting kills the session running this agent — do not run inside the controlling session's pi instance).
+- [ ] **Step 3 (U1):** Open dashboard → attach a warm session whose chat area contains markdown table output (`│ … │` rows) → with an empty input box press `←`. Pass = returns to dashboard, not trapped.
+- [ ] **Step 4 (U2):** In the same or another reporter-active hosted session, type a draft → press `←`. Pass = cursor moves left inside the draft, no detach (same as #67 U3).
+- [ ] **Step 5:** `git -C ~/.pi/agent/git/github.com/zhuxixi/pi-agent-board checkout main` and restart pi to restore the running copy.

package/docs/superpowers/specs/2026-08-21-attach-coldstart-jiggle-rearm-design.md

@@ -1,5 +1,9 @@
 # Spec：attach 冷启动双光标根治 — jiggle 重试链编排修复（issue #10）
 
+> **历史设计，已被 issue #25 的 shrink-and-hold 及 issue #42 的 G6
+> post-restore verify supersede。** 当前实现和测试以
+> `src/core/pty-attach-jiggle-controller.mjs` 为准。
+
 ## 日期
 2026-08-21（v2：评审后修订，补三项编排严谨性修正）
 

package/docs/superpowers/specs/2026-08-22-jiggle-shrink-and-hold-design.md

@@ -1,5 +1,9 @@
 # Spec：attach jiggle 协议改造 — shrink-and-hold（issue #25）
 
+> **历史设计，部分内容已被 issue #42 superseded。** 当前实现保留 G1–G5，
+> 并在首帧快速 restore 后增加 G6 post-restore verify：900ms 内没有 clear
+> 时重新 shrink；attach detach 只使用空输入时的 `←`，`ctrl+]` 透传给 Pi。
+
 ## 日期
 2026-08-22
 

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-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/docs/superpowers/specs/2026-09-01-attach-detach-gate-cursor-anchor-design.md

@@ -0,0 +1,78 @@
+# Issue #66 Spec：← detach 门禁锚点重构（反白假光标）
+
+> Draft：2026-09-01。state: **pending user review**（⏸ 等用户确认后再进 worktree）
+
+## 1. 根因（调研结论，详见 issue 评论）
+
+`childInputLooksEmpty()` 以 **xterm 硬件光标所在行**为锚点（`baseY + cursorY`），而 pi 渲染时：
+- streaming：差分帧只重绘 Working 行，光标**持续**停在 `⠙ Working...` 行（~120ms/帧）；
+- attach 完成瞬间：光标停在输出区/提示行。
+
+两态下输入框为空但光标行非空 → `isProbablyEmptyPiInputLine` 判非空 → `←` 被转发给子进程。
+v0.5.1 起 `ctrl+]` 已透传 Pi，`←` 是 attach 表面**唯一 detach 键** → 用户被困。
+
+**可靠锚点（实证）**：pi 输入行恒渲染**反白假光标**（`\x1b[7m...\x1b[27m`，pi-tui `input.js` render + 本机 screen.log 双重确认），且反白 cell 在 xterm buffer 中**持久存在**（差分帧不重绘也保留）。从 buffer 底部向上扫"含 inverse cell 的行"即可定位输入行，**不依赖光标位置**。
+
+## 2. 修复设计
+
+### 2.1 `src/core/pty-input.mjs`
+
+新增纯函数（现有 `isProbablyEmptyPiInputLine` 不变）：
+
+```js
+export function isProbablyPiInputLine(line) // 行首（trim 左空白）为 prompt/continuation 字形
+```
+
+字形集：`›>┃│|┆╎╏:`（与 isProbablyEmptyPiInputLine 的 trim 字符集一致，兼容有字形 pi 版本）。
+
+### 2.2 `src/ui/pty-attach.ts` — `childInputLooksEmpty()` 重构
+
+三层判定，按优先级：
+
+1. **反白假光标锚点**（主）：从 `active.baseY + active.length - 1` 向上扫，找第一个含 `isInverse()` cell 的行 → 返回 `isProbablyEmptyPiInputLine(line.translateToString(true))`；
+2. **字形行 fallback**（兼容无反白光标渲染的 pi 变体）：找不到反白行时，同向扫 `isProbablyPiInputLine` 行 → 判空；
+3. **逃生兜底**：都找不到（损坏 buffer / replay 窗口无输入行帧）→ 视为空 → `←` 可 detach。
+
+行为矩阵：
+
+| 状态 | 反白行 | 字形行 | 判定 | ← 行为 |
+|------|--------|--------|------|--------|
+| 输入框空（attach 后 / streaming 中） | 空行 | — | 空 | detach ✓ |
+| 输入框有草稿 | 非空行 | — | 非空 | 转发（不抢编辑键）✓ |
+| 损坏残影 buffer | 无 | 无 | 空 | detach（逃生）✓ |
+| 有字形 pi 版本 | 空行(`> `) | `> ` | 空 | detach ✓ |
+
+## 3. 非目标
+
+- ❌ ← 无条件 detach（违背"编辑中不抢键"产品意图，attach-flow.ts 亦保留门禁）
+- ❌ 控制 socket 编辑器状态查询（pi 无此协议）
+- ❌ 修改 `ctrl+]` 语义（v0.5.1 已透传 Pi，保持）
+
+## 4. 验收矩阵
+
+| ID | 功能点 | 验收方式 | 具体验证 | 通过标准 |
+|----|--------|----------|----------|----------|
+| A1 | `isProbablyPiInputLine` 纯函数行为 | 自动化验证（unit） | `node --test test/pty-input.test.mjs` | 字形行 true；内容行/空行 false |
+| A2 | 反白锚点：空输入行（光标漂移）→ detach | 自动化验证（unit） | `node --test test/pty-attach-detach-gate.test.mjs`（smoke B3） | `leftDetachesWhenCursorOffEmptyInputLine === true` |
+| A3 | 反白锚点：草稿行 → 转发 | 自动化验证（unit） | 同上（smoke B） | `leftStaysGatedOnNonEmptyLine === true` |
+| A4 | 反白锚点：无假光标行 + 空行 fallback | 自动化验证（unit） | 同上（smoke 新增） | `leftDetachesOnEmptyInput === true` 保持 |
+| A5 | 损坏 buffer（无输入行）→ 逃生 | 自动化验证（unit） | 同上（smoke B1） | `leftEscapesOnGarbledBuffer === true` |
+| A6 | 全套回归 + 覆盖率门禁 | 自动化验证（build/static + unit） | `npm run verify`（typecheck + 全部测试 + coverage 门禁 lines85/funcs80/branches70 + pack:dry，Node 22/24） | 全绿；无既有测试被改语义 |
+| U1 | attach 后输入框空按 ← 回退 | 用户实测 | attach 进入 pi session → 立即按 ← | 回退到 dashboard，无需 ↑↓/输入删除 |
+| U2 | pi 思考中（Working...）按 ← 回退 | 用户实测 | 触发 pi 思考（Working 动画）→ 按 ← | 回退到 dashboard |
+
+## 5. 可测性拆分设计
+
+| 函数 | 位置 | 职责 | 测试边界 |
+|------|------|------|----------|
+| `isProbablyPiInputLine(line)` | pty-input.mjs（纯函数） | 行首字形判定 | 输入字符串 → boolean；不碰 buffer/term |
+| `findLastInverseCellLine(active)` | pty-attach.ts（私有，仅依赖 xterm buffer 接口） | 底部向上扫含 inverse cell 的行号 | 输入 fake buffer（{baseY, length, getLine}）→ 行号/null；**不依赖 cursorY** |
+| `childInputLooksEmpty()` | pty-attach.ts | 三层组合判定 | 输入 buffer 状态 → boolean；经 smoke 场景验证 |
+
+约束：`findLastInverseCellLine` 只读 buffer（无副作用）；`isProbablyPiInputLine` 无状态；smoke 场景构造 xterm 渲染序列（`\x1b[7m \x1b[27m` 等）验证端到端判定，不 mock 内部函数。
+
+## 6. 风险
+
+- pi 未来版本假光标不再反白渲染 → 字形/兜底 fallback 接管（判定仍可用，只是可能放宽为"视为空"）
+- 多行编辑器最后一行空 → 判空 detach（与现状光标行逻辑一致，非回归）
+- buffer 中其他反白元素（选中文本等）在输入行下方 → 极罕见；底部扫描以"最靠下"优先，选中文本在输出区（输入行上方）不干扰

package/docs/superpowers/specs/2026-09-02-attach-detach-editor-state-design.md

@@ -0,0 +1,120 @@
+# Issue #68 Spec：editor_state 推送 —— detach 门禁从渲染启发式迁移到子 pi 编辑器真实状态
+
+> Draft：2026-09-02。state: **pending user review**（⏸ 等用户确认后再进 worktree）
+
+## 1. 背景与根因
+
+#66 的三层渲染启发式（反色假光标锚点 → 字形行 → 逃生兜底）在真实 pi 渲染下全部失效：
+- 空编辑器行行首**无 prompt 字形**；attach buffer 常**无反色 cell**（差分渲染不重绘编辑器行）；
+- 结果 tier-1 落空 → tier-2 误命中聊天区 markdown 表格行（`│ ... │`）/ 冒号行（`:` 开头）→ 判"有草稿" → `←` 被吞（#68/#69 实锤）。
+
+渲染流**不是**编辑器状态的可靠载体。根治方案（本 spec）：子 pi 扩展直接读取 `ctx.ui.getEditorText()`（pi 官方 API，权威状态），经现有 control socket 推送给 runner → broadcast 给 attach 面板 → 门禁直接用。渲染启发式降级为 fallback。
+
+## 2. 架构设计
+
+```
+子 pi 扩展（isHostedChild 时 session_start 启动上报循环）
+  └─ 每 100ms 轮询 ctx.ui.getEditorText()，文本变化时：
+       → {type:"editor_state", empty} → control socket（JSONL client）
+pty-runner（handleClientLine 新 case "editor_state"）
+  ├─ 缓存 host.editorEmpty + persist 到 host.json（可选，见 §7）
+  ├─ broadcast({type:"editor_state", empty}) 给所有 attach clients
+  └─ hello 消息带初始 editorEmpty（新 attach 立即同步）
+attach 面板（pty-attach.ts）
+  ├─ 缓存 this.editorEmpty: boolean | null（null = 未知）
+  ├─ onSocketData 新 case "editor_state" 更新缓存
+  └─ ← 判定：resolveEditorEmpty(editorEmpty, 启发式结果)
+       editorEmpty !== null ? editorEmpty : 现有启发式（fallback）
+```
+
+### 2.1 协议（JSONL，向后兼容）
+
+```jsonc
+// 子 pi 扩展 → runner
+{ "type": "editor_state", "empty": true }
+
+// runner → attach clients（广播 + hello 初始值）
+{ "type": "editor_state", "empty": true }
+{ "type": "hello", "status": {...}, "editorEmpty": true }
+```
+
+旧端忽略未知字段/消息（现有 parser 已忽略未知 type）→ 协议向后兼容。
+
+### 2.2 子 pi 扩展上报循环（新文件 `src/core/editor-state-reporter.mjs`）
+
+- 激活条件：`process.env.AGENT_BOARD_CHILD === "1" || process.env.AGENT_VIEW_CHILD === "1"`（与 index.ts 同判据）
+- socket 路径：`controlSocketPathFor(process.platform, root, viewId)`（复用 `src/core/paths.mjs`）
+- 连接策略：runner **先 spawn 子 pi 后 listen** → 初始连接带重试（退避 1s→2s→…封顶 5s，永久重试）；断开后同样重连
+- 轮询：`setInterval(100ms)` 读 `getEditorText()`，`text !== lastText` 才发送（dedupe，避免常发）
+- 生命周期：session_start 启动、进程退出自然回收；`stop()` 供测试
+- 依赖注入设计（可测性，§5）：`createEditorStateReporter({ getEditorText, connect, intervalMs = 100, scheduler = defaultScheduler })` → `{ start, stop }`；`scheduler = { interval(fn, ms), timeout(fn, ms), clear(handle) }`（默认 setInterval/setTimeout 包装）；生产接线在 index.ts
+
+### 2.3 runner 改动（`runner/pty-runner.mjs`）
+
+- `handleClientLine` switch 加 `case "editor_state"`：`host.editorEmpty = !!msg.empty; broadcast({type:"editor_state", empty: host.editorEmpty})`（不 persist，见 §7）
+- `hello` 消息：`{ type:"hello", status: host, editorEmpty: host.editorEmpty ?? null }`
+- 子 pi 断开（child exit）→ editorEmpty 复位 null 并 broadcast（attach 端退回启发式）
+
+### 2.4 attach 面板改动（`src/ui/pty-attach.ts`）
+
+- 字段 `private editorEmpty: boolean | null = null`
+- `onSocketData`：`case "editor_state"` → `this.editorEmpty = !!msg.empty`；`case "hello"` → 读 `msg.editorEmpty`
+- `←` 判定（handleInput）：`shouldEscapeAttach(this.connected, this.resolveEditorEmpty())`
+- 纯函数 `resolveEditorEmpty(editorEmpty, heuristic)`（放 `src/core/pty-input.mjs` 或新纯函数文件）：
+  `editorEmpty === null ? heuristic : editorEmpty`
+- `ctrl+]` 语义不变；现有三层启发式**原样保留**（fallback）
+
+## 3. 行为矩阵
+
+| 场景 | editorEmpty | 判定 | ← 行为 |
+|------|-------------|------|--------|
+| 空输入（attach/streaming/任意时刻） | true | 空 | detach ✓ |
+| 草稿（多行/单行/autocomplete 后/↑ 召回） | false | 非空 | 转发（编辑保护）✓ |
+| 提交瞬间 | true（清空） | 空 | detach ✓ |
+| 子 pi 扩展缺失/socket 断流 | null | 启发式 | 现状 fallback 行为 |
+| 损坏 buffer + editor_state 正常 | true/false | 权威 | 正确判定（不再被残影误导）✓ |
+
+## 4. 非目标
+
+- ❌ 删除现有渲染启发式（保留为 fallback）
+- ❌ #69 的短期 tier-2 收紧（#68 长期方案落地后启发式仅 fallback；#69 由维护者按需处理）
+- ❌ RPC 模式特判（子 pi 恒 PTY/TUI；RPC 下 getEditorText 恒 "" → empty 恒 true → ← 恒 detach，无 TUI 草稿概念，方向安全）
+- ❌ 击键级拦截（评论 2 已排除：会覆盖编辑器光标行为，hack 且危险）
+
+## 5. 可测性拆分设计
+
+| 单元 | 位置 | 职责 | 测试边界 |
+|------|------|------|----------|
+| `createEditorStateReporter({getEditorText, connect, intervalMs, scheduler})` | src/core/editor-state-reporter.mjs | 轮询、变化 dedupe、断线重连退避、stop | 依赖全注入（scheduler 为 {interval, timeout, clear} 手动时钟）；fake connect/getEditorText/scheduler → 断言 send 序列与时机；不碰真实 socket/interval |
+| `resolveEditorEmpty(editorEmpty, heuristic)` | src/core/pty-input.mjs | 判定优先级 | 纯函数：4 种输入组合 → boolean |
+| runner `editor_state` case + hello 字段 | runner/pty-runner.mjs | 缓存、broadcast、复位 | 现有 integration harness（pty-runner.integration.test.mjs 模式）：注入 client line → 断言 broadcast 与 hello 载荷 |
+| attach `editorEmpty` 缓存 + 判定 | src/ui/pty-attach.ts | 消息 case、字段、← 判定 | detach-gate-smoke 场景 H（editor_state 消息 + 草稿 buffer → detach）；场景 I（草稿 + editor_state:false → 转发） |
+
+约束：reporter 的生产接线只做「注入真实依赖」，纯逻辑全在工厂函数内；实现不得把轮询/重连逻辑重新耦合进 index.ts。
+
+## 6. 验收矩阵
+
+| ID | 功能点 | 验收方式 | 具体验证 | 通过标准 |
+|----|--------|----------|----------|----------|
+| A1 | reporter：轮询变化才上报、dedupe、stop | 自动化验证（unit） | `node --test test/editor-state-reporter.test.mjs` | 变化序列上报次数/内容精确匹配；无变化零上报 |
+| A2 | reporter：初始连接重试退避 + 断线重连 | 自动化验证（unit） | 同上 | fake connect 先拒后通 → 按退避序列重试并在连通后恢复上报 |
+| A3 | runner：editor_state case 缓存 + broadcast + hello 初始值 + exit 复位 | 自动化验证（integration） | `node --test test/pty-runner.integration.test.mjs` | 注入 editor_state line → 其他 client 收到广播；新 client hello 带 editorEmpty；exit 后 editorEmpty=null 广播 |
+| A4 | attach：editor_state 消息更新缓存、判定优先级（null 走启发式） | 自动化验证（unit） | detach-gate-smoke 场景 H/I | 空输入+editorEmpty=true → detach；草稿+editorEmpty=false → 转发；无消息 → 走启发式（既有场景全绿） |
+| A5 | 纯函数 resolveEditorEmpty | 自动化验证（unit） | `node --test test/pty-input.test.mjs` | 4 组合精确匹配 |
+| A6 | 全套回归 + 覆盖率门禁 | 自动化验证（build/static + unit） | `npm run verify`（typecheck + 全测 + c8 门禁 85/80/70 + pack:dry）；CI Node 22/24 | 全绿；既有 430+ 测试无语义改动 |
+| U1 | 空输入 attach 后 ← 回退 | 用户实测 | attach 进入 → 立即 ← | 回 dashboard |
+| U2 | Working... 中 ← 回退 | 用户实测 | 思考动画中 ← | 回 dashboard |
+| U3 | 草稿中 ← 左移不被抢 | 用户实测 | 输入草稿 → ← | 光标左移，不 detach |
+| U4 | 断流 fallback（子 pi 扩展被禁用时仍可退出） | 用户实测 | 临时禁用扩展的 editor_state 上报（env 开关）→ ← | 仍可回退（启发式兜底） |
+
+## 7. 决策与风险
+
+- **不 persist editorEmpty**（首版）：host.json 是行状态持久化，editor 状态是瞬态（毫秒级），重启后 attach 的 hello 里 null → 启发式兜底 1-2s 内收到首个 editor_state 修正。避免 host.json 写放大（100ms 级变化频率）。
+- **100ms 轮询开销**：getEditorText 是内存 join，忽略不计；socket 仅在变化时写。
+- **风险：editorEmpty=false 但用户实际想退出**（草稿场景）：与既有"编辑中不抢键"哲学一致（attach-flow 同样）；用户清空草稿即可退出。
+- **风险：子 pi 扩展未安装/旧版**（fallback 启发式接管，U4 验证）。
+- **风险：runner 老版本**（不认识 editor_state case，忽略）→ attach 收不到 → 启发式兜底，向后兼容。
+
+## 8. 关联
+
+- #68（本 issue 长期方案）、#66/#67（启发式起源与失效）、#69（同症状短期方案，由维护者处理）、#42/#48（门禁可靠性原则：视图必须始终可退出）