@zhuxixi/pi-agent-board 0.5.1 → 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-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（门禁可靠性原则：视图必须始终可退出）

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

@@ -0,0 +1,99 @@
+# SPEC：#69 tier-2 字形兜底收紧 —— fallback 路径下 ← 恒可逃生
+
+- Issue: zhuxixi/pi-agent-board#69
+- 基线: main @ 9a61dd5（含 PR #71 editor_state 门禁）
+- 状态: 已批准（方案 B，2026-09-03）
+- 调研依据: `~/.claude/github-issue-driven/zhuxixi/pi-agent-board/issue-69/research/`（R1 代码影响面 / R2 KB / R3 PR 上下文），结论已评论回 issue
+
+## 1. 背景与根因（已实锤，不再重复调试）
+
+`←` detach 门禁三层结构（#71 后）：
+
+```
+handleInput(←)
+  └─ connected? ── no ──→ 无条件逃生（#48，不动）
+       └─ yes → resolveEditorEmpty(editorEmpty, heuristic)
+                  ├─ editorEmpty ≠ null → 权威子进程状态（#71，不动）
+                  └─ editorEmpty = null → 启发式 childInputLooksEmpty()
+                        ├─ tier-1: 反色假光标锚点（不动）
+                        ├─ tier-2: 字形兜底 ← ★ 本次唯一改动点 ★
+                        └─ 兜底: return true 逃生
+```
+
+**根因**：fallback 模式（子会话无 editor-state reporter：旧版 pi 无 `ctx.ui.getEditorText`、扩展未加载、socket 未建立）下，真实 attach buffer 常零反色 cell → tier-1 落空 → tier-2 自底向上扫到 `isProbablyPiInputLine` 命中的聊天区 markdown 表格行（`│ … │`）或引用行（`> …`）→ `isProbablyEmptyPiInputLine` 判非空 → return false → `←` 被转发给子进程，用户被困。已在 main(9a61dd5) 上以 smoke 场景 K 复现（零反色 + `│ Issue #778 │ open │` + `> quote` + editorEmpty=null → didDetach=false）。
+
+## 2. 修复设计
+
+### 2.1 tier-2 行为决策表（唯一行为变化面）
+
+| tier-2 扫到的行（自底向上首个 glyph 行） | 现行为 | 新行为 | 理由 |
+|---|---|---|---|
+| 空 glyph 行（`> `、`› `、`┃  `） | true（detach） | true（不变） | 编辑器为空 |
+| 内容 glyph 行（`│ table │`、`> quote`、真草稿 `> draft`） | **false（gated，#69 bug）** | **true（detach）** | fallback 下无法区分表格/引用/草稿；可退出性优先 |
+| 无 glyph 行 / 扫不到 | true | true（不变） | 既有逃生 |
+
+**收紧后 tier-2 语义恒为 true**（内容行跳过 + 扫不到逃生）——fallback 恒放行，这是有意取舍：草稿保护的可靠路径已由 #71 editor_state 承担；fallback 模式下误判代价不对称（误 detach = 意外退视图、草稿不丢、重新 attach 即回；误 gate = 用户被困）。与 #42/#48「视图必须始终可退出」哲学同向。
+
+### 2.2 改动点（两案行为完全等价，纯代码形态选择）
+
+**方案 B（推荐，与维护者在 #69 评论中已本地验证的实现一致）**：
+
+```ts
+// src/ui/pty-attach.ts  childInputLooksEmpty() tier-2 循环
+for (let y = active.baseY + active.length - 1; y >= active.baseY; y--) {
+    const line = active.getLine(y)?.translateToString(true) ?? "";
+    // 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 and keep
+    // scanning; the loop-end escape stays authoritative.
+    if (isProbablyPiInputLine(line) && isProbablyEmptyPiInputLine(line)) return true;
+}
+return true;
+```
+
+- 保留扫描骨架：为中期方案（按 pi TUI dock 结构：底部 `─` 分隔线与 footer 间定位编辑器行，可恢复 fallback 草稿保护）留结构；注释固化取舍理由。
+- `isProbablyPiInputLine` 继续有生产调用点，不需要删除。
+
+**方案 A（备选）**：直接删循环 `return true` + 注释。语义/测试与 B 完全一致，diff 更小，但丢掉骨架与意图表达。
+
+### 2.3 数据流与组件契约
+
+- 无新组件、无协议消息、无公共 API 变化；`resolveEditorEmpty`、tier-1、editor_state 链路（reporter → runner broadcast → attach 缓存 → hello 重置）一概不动。
+- 唯一触碰的生产文件：`src/ui/pty-attach.ts`（tier-2 循环体）。
+- 触发窗口说明：收紧只影响 editorEmpty=null 的降级判定（reporter 缺席）；reporter 活跃时 `resolveEditorEmpty` 短路，主路径零变化。
+
+## 3. 验收矩阵
+
+| ID | 功能点 | 验收方式 | 具体验证 | 通过标准 |
+|----|--------|----------|----------|----------|
+| A1 | #69 真实场景放行：零反色 + 聊天区 `│` 表格行/`>` 引用行 + editorEmpty=null + connected=true → `←` detach | 自动化验证（integration：detach-gate smoke，经 `test/pty-attach-detach-gate.test.mjs` 驱动） | `npm test`；新增 smoke key `leftDetachesOnTableRowsWithoutFakeCursor` | 新 key 断言 true，全量测试通过 |
+| A2 | 有意回归被钉住：内容 glyph 行（真草稿形态 `> draft`）+ 零反色 + editorEmpty=null → `←` detach（fallback 草稿保护失效是有意取舍，防止未来被"顺手修"）。**与既有 smoke B 互为对照**：同为草稿形态，B 带 inverse 走 tier-1 → gated，A2 零反色走 fallback → detach——两种判定不矛盾，正是本取舍的教科书示例（smoke 场景注释中须写明此对照） | 自动化验证（integration：同上） | 新增 smoke key `leftDetachesOnContentGlyphFallback` | 新 key 断言 true |
+| A3 | 既有行为零回归：B（tier-1 草稿 gate）、J（hello null 重置）、空 glyph 行 detach、editor_state 系列（H/J 全部 key）、ctrl+] 透传、断线逃生等 | 自动化验证（integration + unit 全量） | `npm test`（基线 437；新 smoke key 是既有 test 块内的新断言，node:test 计数不变） | 全量 437 全绿，既有 key 结果不变 |
+| A4 | 类型/静态约束 | 自动化验证（static/build） | `npm run typecheck` | 0 错误（CI Node 22/24 等价覆盖） |
+| U1 | 真实仪表盘复测 #69 场景：attach 一个聊天区含 markdown 表格输出的 warm 会话，输入框空时按 `←` | 用户实测 | 在运行副本 `~/.pi/agent/git/github.com/zhuxixi/pi-agent-board` 里 `git fetch && git checkout <PR 分支>`（#67 实测已验证的本地加载法），重启 pi 后打开 dashboard → attach → 空输入按 `←`；测完 checkout 回 main 并重启 | 回到 dashboard，不被困（可执行时机：实现完成、PR 分支推送后、合并前） |
+| U2 | 主路径草稿保护不受影响：reporter 活跃会话输入草稿后按 `←` | 用户实测 | 同 U1 环境，attach 后输入草稿，按 `←` | 光标在草稿内左移，不 detach（复测 #67 U3 同款；可执行时机同 U1） |
+
+**用户实测不可自动化的原因（U1/U2）**：真实 dashboard attach 涉及宿主 pi TUI 差分渲染 + pty-runner + editor-state reporter socket 的全链路，headless harness 用内存 xterm 无法复现真实终端渲染与扩展加载，只能人测。注意：实测需重启 pi，当前开发会话所在的 pi 实例会中断——在另一个终端/pi 实例里执行。
+
+## 4. 可测性拆分设计（自动化项）
+
+- **纯函数层（不变）**：`isProbablyEmptyPiInputLine` / `isProbablyPiInputLine` / `resolveEditorEmpty` 已在 `test/pty-input.test.mjs` 有 unit 钉语义；本次不改其行为，不新增纯函数——收紧后 tier-2 决策恒为 true，为常量行为建纯函数无判别价值，强行抽取只会产生恒真断言的空转测试。
+- **组件决策层（改动面）**：`childInputLooksEmpty()` 本身无副作用（只读 xterm buffer + 纯判定），判别性（detach vs forward）落在组件级 smoke harness（`test-support/detach-gate-smoke.ts`，经 `test/pty-attach-detach-gate.test.mjs` 以子进程运行并断言全部 key）——沿用 #42/#48/#66/#68 的既有测试边界，不引入新测试形态。
+- **测试边界总结**：unit 钉 helper 语义（A3 覆盖）→ integration smoke 钉组件门禁决策（A1/A2/A3）→ static/typecheck 钉类型（A4）。A1/A2 ↔ smoke 新场景；A3 ↔ smoke 既有 key + unit 全量；A4 ↔ typecheck。双向可追溯。
+- **smoke 惯例**：在线 gate 场景必须显式 pin `connected=true`（B 段既有惯例；不 pin 时断线逃生语义会抢跑，测不到在线门禁）；新场景 K1（A1）/K2（A2）同样遵守。
+
+## 5. 非目标
+
+- ❌ 中期 dock 结构锚点（底部 `─` 分隔线与 footer 间定位编辑器行）——未来若要恢复 fallback 草稿保护再立项
+- ❌ 触碰 tier-1 反色锚点、editor_state 链路（#71 成果）
+- ❌ 删除渲染启发式整体（继续作为 #71 的 fallback 层存在）
+- ❌ 方案 A 下的 `isProbablyPiInputLine` 去留不在本 spec 讨论（选 B 则无此问题）
+- ❌ 不改 README：line 96/195 的 `←` 行为描述以受支持主路径（reporter 活跃）为准，fallback 降级细节属实现层，由 A2 钉住——此为明确决定，防止未来被当成文档漂移
+
+## 6. 风险与降级
+
+- 风险 1：fallback 下真草稿按 `←` 变为 detach（有意回归，A2 钉住；草稿不丢，重新 attach 即回）。
+- 风险 2：`←` 在 attach 初建窗口（hello 尚未带回 editorEmpty、reporter 首推未达）若子进程恰有草稿，会 detach——窗口极短且后果同上，接受。
+- 无运行时降级路径需求：本改动本身就是降级路径的加固；不合并时现状是「fallback 可被困」（更差）。
+- **post-merge 生效**：运行副本 `~/.pi/agent/git/github.com/zhuxixi/pi-agent-board`（当前停在 0.5.1 / fac9e91，连 #66 都没有）需 `git pull`（或 `pi update`）并重启 pi 后才带本修复——人工部署步骤，不在自动化环内。

package/package.json

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

package/runner/pty-runner.mjs

@@ -72,6 +72,9 @@ function main() {
 	// "exited" update (the handler kills the child, so its exit callback fires
 	// inside the 50ms flush window — CR round-1, issue #48).
 	let crashed = false;
+	/** Authoritative child editor emptiness, pushed by the child Pi extension
+	 * (issue #68). null = unknown (extension missing / not yet reported). */
+	let editorEmpty = null;
 	/** @type {import("../src/core/types.mjs").HostStatus} */
 	let host = {
 		version: 1,
@@ -195,6 +198,8 @@ function main() {
 		// exit; this callback must not overwrite that state.
 		if (!crashed) {
 			update({ state: "exited", endedAt: Date.now(), exitCode, childPid: null });
+			editorEmpty = null;
+			broadcast({ type: "editor_state", empty: null });
 			broadcast({ type: "exit", exitCode });
 		}
 		if (!shutdownStarted) setTimeout(() => process.exit(exitCode ?? 0), 50).unref?.();
@@ -209,7 +214,7 @@ function main() {
 	server = createServer((socket) => {
 		clients.add(socket);
 		update({ attachedEver: true });
-		socket.write(JSON.stringify({ type: "hello", status: host }) + "\n");
+		socket.write(JSON.stringify({ type: "hello", status: host, editorEmpty }) + "\n");
 		let buffer = "";
 		socket.on("data", (chunk) => {
 			buffer += chunk.toString("utf8");
@@ -238,7 +243,7 @@ function main() {
 		try { msg = JSON.parse(line); } catch { return send(socket, { type: "error", message: "invalid json" }); }
 		switch (msg.type) {
 			case "hello":
-				send(socket, { type: "hello", status: host });
+				send(socket, { type: "hello", status: host, editorEmpty });
 				break;
 			case "input":
 				if (typeof msg.data === "string") child.write(msg.data);
@@ -264,6 +269,11 @@ function main() {
 			case "get_status":
 				send(socket, { type: "status", status: host });
 				break;
+			case "editor_state": {
+				editorEmpty = typeof msg.empty === "boolean" ? msg.empty : null;
+				broadcast({ type: "editor_state", empty: editorEmpty });
+				break;
+			}
 		}
 	}
 

package/src/core/editor-state-reporter.mjs

@@ -0,0 +1,102 @@
+/** Child-Pi editor-state reporter (issue #68): polls the child Pi's editor text
+ * and pushes `{type:"editor_state", empty}` over the control socket whenever the
+ * text changes, so the attach surface can gate ← on the authoritative state
+ * instead of render heuristics. Dependency-injected for unit testing. */
+
+/** @typedef {{ write(jsonLine: string): void; on?(event: "close" | "error", fn: () => void): void }} SocketLike */
+
+const defaultScheduler = {
+	interval(fn, ms) { const h = setInterval(fn, ms); h.unref?.(); return h; },
+	timeout(fn, ms) { const h = setTimeout(fn, ms); h.unref?.(); return h; },
+	clear(handle) { clearInterval(handle); clearTimeout(handle); },
+};
+
+export function createEditorStateReporter({ getEditorText, connect, intervalMs = 100, scheduler = defaultScheduler }) {
+	let started = false;
+	let stopped = false;
+	let socket = null;
+	let pollTimer = null;
+	let reconnectTimer = null;
+	let backoffMs = 1000;
+	let lastText = null;
+
+	function send(json) {
+		if (!socket) return;
+		try {
+			socket.write(JSON.stringify(json) + "\n");
+		} catch {
+			teardownSocket();
+			scheduleReconnect();
+		}
+	}
+
+	function teardownSocket() {
+		if (pollTimer !== null) { scheduler.clear(pollTimer); pollTimer = null; }
+		const s = socket;
+		socket = null;
+		try { s?.destroy?.(); } catch { /* already torn down */ }
+		try { s?.removeAllListeners?.(); } catch { /* already torn down */ }
+	}
+
+	function poll() {
+		if (stopped || !socket) return;
+		let text;
+		try {
+			text = getEditorText();
+		} catch {
+			return;
+		}
+		text = typeof text === "string" ? text : "";
+		if (text !== lastText) {
+			lastText = text;
+			send({ type: "editor_state", empty: text.length === 0 });
+		}
+	}
+
+	function startPolling() {
+		if (pollTimer !== null) return;
+		lastText = null; // force a first report after (re)connect
+		pollTimer = scheduler.interval(poll, intervalMs);
+	}
+
+	function scheduleReconnect() {
+		if (stopped) return;
+		teardownSocket();
+		reconnectTimer = scheduler.timeout(tryConnect, backoffMs);
+		backoffMs = Math.min(backoffMs * 2, 5000);
+	}
+
+	function tryConnect() {
+		reconnectTimer = null;
+		if (stopped) return;
+		let s;
+		try {
+			s = connect();
+		} catch {
+			scheduleReconnect();
+			return;
+		}
+		socket = s;
+		s?.resume?.();
+		s?.unref?.();
+		s?.on?.("data", () => {}); // consume and discard broadcast traffic
+		s?.on?.("connect", () => { if (socket === s) { backoffMs = 1000; startPolling(); } });
+		s?.on?.("close", () => { if (socket === s) scheduleReconnect(); });
+		s?.on?.("error", () => { if (socket === s) scheduleReconnect(); });
+	}
+
+	function start() {
+		if (started) return;
+		started = true;
+		stopped = false;
+		tryConnect();
+	}
+
+	function stop() {
+		stopped = true;
+		if (reconnectTimer !== null) { scheduler.clear(reconnectTimer); reconnectTimer = null; }
+		teardownSocket();
+	}
+
+	return { start, stop };
+}

package/src/core/pty-input.mjs

@@ -13,3 +13,35 @@ export function isProbablyEmptyPiInputLine(line) {
 	const content = withoutRightPadding.replace(/^[\s\u00a0›>┃│|┆╎╏:]+/u, "");
 	return content.length === 0;
 }
+
+/** Glyphs Pi uses to render editor prompt / continuation lines (`>` main prompt,
+ * `›`/`┃`/`│` and variants in older releases). Must stay in sync with the
+ * trim charset of isProbablyEmptyPiInputLine below. */
+const PROMPT_GLYPHS = "›>┃│|┆╎╏:";
+
+/**
+ * Whether the given terminal line looks like a Pi editor input line: leading
+ * whitespace followed by a prompt/continuation glyph. The attach surface uses
+ * this to locate the editor line inside the buffer instead of trusting the
+ * terminal cursor, which wanders onto output/working lines while Pi streams
+ * (issue #66).
+ * @param {string} line
+ * @returns {boolean}
+ */
+export function isProbablyPiInputLine(line) {
+	const withoutLeftPadding = String(line || "").replace(/^[\s\u00a0]+/u, "");
+	return withoutLeftPadding.length > 0 && PROMPT_GLYPHS.includes(withoutLeftPadding[0]);
+}
+
+/**
+ * Resolve the ← detach gate's emptiness signal: when the child Pi pushes its
+ * authoritative editor state (boolean), it wins; when it is unknown (null/
+ * undefined — child extension missing or socket never connected), fall back
+ * to the render heuristic.
+ * @param {boolean | null | undefined} editorEmpty
+ * @param {boolean} heuristic
+ * @returns {boolean}
+ */
+export function resolveEditorEmpty(editorEmpty, heuristic) {
+	return editorEmpty === null || editorEmpty === undefined ? heuristic : editorEmpty;
+}