@huseynsnmz/pi-board 0.15.3 → 0.17.0

package/docs/superpowers/specs/2026-10-27-issue-172-fullscreen-selection-clear-design.md

@@ -1,248 +0,0 @@
-Drafted: ollama/deepseek-v4.1-flash:1017-cloud (selected) · ollama/deepseek-v4.1-flash:1017-cloud (physical) @ 2026-10-27T00:16:00Z
-Revised: ollama/deepseek-v4.1-flash:1017-cloud (selected) · ollama/deepseek-v4.1-flash:1017-cloud (physical) @ 2026-10-27T00:41:00Z — R1-G1 (U1 deployment preconditions), R1-D1 (README decision), R1-D2 (follow-up issue #250)
-Revised: ollama/deepseek-v4.1-flash:1017-cloud (selected) · ollama/deepseek-v4.1-flash:1017-cloud (physical) @ 2026-10-27T00:52:00Z — R2-D1 (U1 sequencing), R2-D2 (supersession note), R2-D3 (baseline)
-Revised: ollama/deepseek-v4.1-flash:1017-cloud (selected) · ollama/deepseek-v4.1-flash:1017-cloud (physical) @ 2026-10-27T01:25:00Z — local code review F1 (gesture-generation guard) + F3 (deferral pin) + F4 (predicate table)
-
-# Spec: #172 — attach view keeps the fullscreen selection highlight after copy-on-release
-
-Status: DRAFT (awaiting spec-cross-review, then user approval — github-issue-driven step 4 gates)
-Issue: https://github.com/zhuxixi/pi-agent-board/issues/172
-Repo state baseline: `origin/main` @ `3fcc2a4` (local working copy `724c4da`, one docs-only commit behind; every cited line number was re-verified at `3fcc2a4`), pi-tui / pi-coding-agent 1.1.0
-
-## Problem (root cause, verified against source)
-
-The reported symptom is real, but the issue's Root cause paragraph points at the wrong
-mechanism. In **fullscreen** (pi ≥1.0, `TuiAltScreen` owns left-drag), the highlight is
-painted by pi-tui's own `applySelection()` from `selectionAnchor` / `selectionFocus`.
-`PtyAttachComponent.handleLocalMouseEvent` — the `shouldCopy` branch the issue blames — is
-never reached in fullscreen (the component's own comment at `pty-attach.ts:474`), so
-`this.selection` stays null and no board-side `clearSelection()` can affect what the user
-sees.
-
-pi-tui 1.1.0 `dist/tui-alt-screen.js:1090-1139` release path:
-
-```js
-if (this.copyOnSelect)
-    void this.copySelectionToClipboard();
-this.requestRender();
-return;
-```
-
-The copy is done, the selection state is not reset, so the inverse-video highlight stays
-lit until pi clears it on a later gesture (`clearTextSelection()` is invoked by pi itself
-when the user clicks a component or moves focus).
-
-The repo already has the one hook that runs after pi finalizes a selection: #174's
-`process.nextTick` callback scheduled from `handleMouse` for left `release`/`click`
-(`pty-attach.ts:523-528` → `mirrorFullscreenSelectionToPrimary()`, `:1376`).
-
-## Goal / non-goals
-
-**Goal**: in fullscreen, once pi's copy-on-select has completed for a selection gesture
-that ends inside the attach view, drop pi's selection so the highlight disappears
-immediately — without changing what reaches the clipboard, and without breaking pi's
-multi-click chain (double-click word, triple-click line).
-
-**Supersedes** #174's "pi's own selection behavior (visuals, CLIPBOARD copy) is untouched" for
-the post-copy highlight only; #174's mirror, kill-switch and no-consume contracts are
-preserved.
-
-**Non-goals**:
-
-- The legacy/regular-mode gap (`handleLocalMouseEvent` `shouldCopy` missing
-  `clearSelection()`). It is a real, separate bug; this PR leaves regular-mode behavior
-  untouched and the existing `pty-attach-legacy-drag` assertions intact. It will be tracked
-  separately: issue #250.
-- Selections that end outside the attach overlay (dashboard, other pi UI): outside the
-  component's event window, same limitation as the #174 mirror.
-- Any upstream change to pi/pi-tui. The change uses a feature-detected private method; if
-  pi ever exposes a public "clear visual selection" API, this code can switch to it.
-- Changing `AGENT_BOARD_ATTACH_NATIVE_PASTE` semantics beyond making the highlight clear
-  independent of it (see D2 below).
-
-## Decisions
-
-**D1 — clear via `clearTextSelection()`, not `resetTextSelection()`.**
-`resetTextSelection()` is public but also clears `lastClick`; `getClickCount` uses
-`lastClick` with `DOUBLE_CLICK_INTERVAL_MS = 500`, so clearing it on every release would
-make the second press of a double-click count as a first click and break word/line
-selection. `clearTextSelection()` only drops the visual selection
-(`tui-alt-screen.js:689-698`), preserving the click chain. It is declared `private` in
-pi-tui's typings but is a plain prototype method at runtime; the board already reads the
-private `getActiveSelectionText` the same way (`pty-attach.ts:1379`). Access is
-feature-detected so older/newer pi degrades to today's behavior instead of throwing.
-
-**D2 — decouple the clear from `AGENT_BOARD_ATTACH_NATIVE_PASTE`.**
-That switch is documented as X11 PRIMARY copy + middle-click paste integration. The stale
-highlight is a pi-selection-state issue, not a clipboard concern: with the switch off, pi
-still copies on release and the highlight still lingers. `writePrimarySelection()` already
-self-gates on the env var, so the scheduling predicate does not need it — the mirror keeps
-its exact behavior, and the clear runs regardless.
-
-**D3 — only clear when pi actually copied.**
-`getCopyOnSelect()` (public) is checked before clearing. With copy-on-select disabled the
-user keeps the selection deliberately (pi's `Ctrl+X` copies it), so the highlight must
-stay. With it enabled, the text is already in the clipboard, so the highlight has no
-remaining purpose.
-
-**D4 — clear only for a non-empty selection.**
-`getActiveSelectionText()` returning empty/undefined means no selection was made (bare
-press-release, click on a link) — nothing to clear, and pi's own click handling is left
-untouched.
-
-**D5 — a settle may not consume the next gesture.**
-pi-tui emits batched mouse reports synchronously in one loop, so a `release` and the next
-left `press` can land in the same stdin chunk. Without a guard, the deferred settle would
-run after that press has already started a new (word/line) selection, mirror it, and clear
-it — the double-click would then copy nothing. A monotonic `selectionGestureSerial`,
-bumped on every left press, is captured when the settle is scheduled; a mismatch on the
-next tick drops the settle.
-
-## Design
-
-### 1. Pure predicate (`src/core/pty-scroll.mjs`)
-
-Replace the env-gated mirror helper with an env-free gesture predicate:
-
-```js
-/** Issue #174/#172: whether a normalized mouse event ends a fullscreen text
- * selection gesture the attach overlay settles — mirror the selection into
- * X11 PRIMARY (#174) and drop pi's highlight once copy-on-select has run (#172).
- * Only release/click of the left button ends a selection in TuiAltScreen; pi
- * owns the gesture, so the overlay observes without consuming. Pure. */
-export function isFullscreenSelectionEnd(event) → boolean
-```
-
-Decision table:
-
-| type | button | result |
-| --- | --- | --- |
-| release / click | left | `true` |
-| press / move / drag / wheel | any | `false` |
-| release / click | middle / right / none | `false` |
-
-`shouldMirrorSelectionToPrimary` is removed; `writePrimarySelection()` remains the single
-place that honours `AGENT_BOARD_ATTACH_NATIVE_PASTE`.
-
-### 2. Component wiring (`src/ui/pty-attach.ts`)
-
-```ts
-const nativePasteEnabled = process.env.AGENT_BOARD_ATTACH_NATIVE_PASTE !== "0";
-// D5: a press starts a new gesture; see the serial check below.
-if (event.type === "press" && event.button === "left") this.selectionGestureSerial += 1;
-if (isFullscreenSelectionEnd(event)) {
-    // Overlays are dispatched before TuiAltScreen finalizes (and copies) the
-    // selection for this event, so settle on the next tick (issue #174).
-    const serial = this.selectionGestureSerial;
-    process.nextTick(() => {
-        if (serial !== this.selectionGestureSerial) return;   // D5: next gesture started
-        this.settleFullscreenSelection(nativePasteEnabled);
-    });
-    return undefined;   // observe only — pi keeps the gesture
-}
-```
-
-`mirrorFullscreenSelectionToPrimary()` is renamed and extended:
-
-```ts
-interface FullscreenSelectionHost {
-    getActiveSelectionText?: () => string | undefined;
-    getCopyOnSelect?: () => boolean;
-    clearTextSelection?: () => void;   // private in pi-tui's typings; feature-detected
-}
-
-/** Issue #174 (B2) + #172: after a selection gesture ends inside this overlay,
- * pi has finalized (and copied) its selection. Mirror the text into X11 PRIMARY
- * so middle-click paste works, then drop pi's selection so the inverse-video
- * highlight does not outlive the copy. Clearing is gated on copy-on-select and
- * on the pi-tui method being present; a missing method degrades to the old
- * behaviour (highlight persists) rather than throwing. */
-private settleFullscreenSelection(nativePasteEnabled: boolean): void {
-    if (this.closed) return;
-    const alt = this.tui as FullscreenSelectionHost;
-    const text = alt.getActiveSelectionText?.();
-    if (typeof text !== "string" || text.length === 0) return;
-    if (nativePasteEnabled) this.writePrimarySelection(text);
-    if (alt.getCopyOnSelect?.() === false) return;
-    if (typeof alt.clearTextSelection !== "function") return;
-    alt.clearTextSelection();
-    this.scheduleRender();   // pi's own release repaint happened before this tick
-}
-```
-
-### Resulting behavior matrix
-
-| Scenario | Behavior |
-| --- | --- |
-| fullscreen: drag-select inside attach, release | copied by pi; PRIMARY mirrored; highlight cleared on the next tick ✅ |
-| fullscreen: double-click a word, release | word copied by pi; word highlighted momentarily, then cleared; triple-click chain still works (`lastClick` untouched) ✅ |
-| fullscreen: plain left click | empty selection → nothing cleared, pi's own click handling untouched |
-| fullscreen: `fullscreenCopyOnSelect = false` | selection kept for `Ctrl+X`; highlight stays (intended) |
-| fullscreen: `AGENT_BOARD_ATTACH_NATIVE_PASTE=0` | no PRIMARY write; highlight still cleared |
-| older pi without `clearTextSelection` | no PRIMARY-write change, highlight stays (graceful degradation) |
-| regular / legacy mode | unchanged: `handleMouse` is not called; the local selection path is untouched |
-
-## Acceptance matrix
-
-| ID | 功能点 | 验收方式 | 具体验证 | 通过标准 |
-|----|--------|----------|----------|----------|
-| A1 | 手势谓词决策表 | 自动化验证（unit） | `node --test test/pty-scroll.test.mjs`（替换原 `shouldMirrorSelectionToPrimary` 用例，覆盖 release/click × left 为 true，press/move/drag/wheel/其它按钮为 false） | 新增用例全绿 |
-| A2 | 非空选区 release：镜像 + 清高亮，且先取文本后清 | 自动化验证（integration，组件级场景） | `test/pty-attach-selection-mirror-scenario.ts` 的 fake TUI 增加 `clearTextSelection()`（置空 fixture 并计数）与 `getCopyOnSelect()`；`test/pty-attach-selection-mirror.test.mjs` 断言 | xclip 日志收到 `-selection primary` 与 fixture 文本（证明清除前已读取），`clearCalls === 1`，`handleMouse` 返回 `undefined` |
-| A3 | 空选区 / press / move 不清 | 自动化验证（同上） | 同场景 | `clearCalls === 0`，无 PRIMARY 写 |
-| A4 | `copyOnSelect === false` 不清、仍镜像 | 自动化验证（同上） | 同场景，fake TUI 返回 false | `clearCalls === 0`，PRIMARY 写 1 次 |
-| A5 | `NATIVE_PASTE=0`：不写 PRIMARY 但仍清高亮 | 自动化验证（同上） | 同场景，env 覆盖 | `killSwitchWrites === 0`，`killSwitchClears === 1` |
-| A6 | 旧 pi（无 `clearTextSelection`）：降级不抛错 | 自动化验证（同上） | 同场景，fake TUI 省略该方法 | 无异常，PRIMARY 写 1 次，`clearCalls` 不可用（不适用） |
-| A7 | 类型与构建 | 自动化验证（static/build） | `npm run typecheck`、`npm run verify` | 全部通过（含既有套件、覆盖率阈值、perf gate、pack:dry） |
-| A8 | release + 下一次 press 同 tick 合并：排队中的 settle 不得读/清新选区 | 自动化验证（同上） | 同场景：`handleMouse(release)` 后立即 `handleMouse(press)`，再等 tick | `coalescedWrites === 0` 且 `coalescedClears === 0`；另在 release 后同步断言 `releaseSyncWrites === 0`（deferral 钉死） |
-| U1 | 真机 fullscreen 体验 | 用户实测 | **前置**：① 合并后把 pi 实际加载的 git checkout 更新到 main —— 扩展在 `~/.pi/agent/settings.json` 以 `git:github.com/zhuxixi/pi-agent-board` 注册，路径为 `~/.pi/agent/git/github.com/zhuxixi/pi-agent-board`，入口 `./index.ts`（免构建）；执行 `git -C ~/.pi/agent/git/github.com/zhuxixi/pi-agent-board pull --ff-only`，若因本地 `package-lock.json` 改动被拒就先 `git stash push -- package-lock.json`、测完 `git stash pop`；② 完全退出并重启 pi（扩展启动时加载；fullscreen 是默认模式，必要时用 `pi --tui-mode fullscreen` 显式指定）；③ 确认 X11 会话且 `which xclip` 有输出。**步骤**：① fullscreen attach 内拖选一段文字并松开 → 高亮立即消失；② 中键粘贴仍粘贴刚选内容；③ 双击选词 → 高亮消失且双击仍能选词；④ 三击选行仍生效；⑤ 把 `~/.pi/agent/settings.json` 的 `"fullscreenCopyOnSelect"` 设为 `false` 并重启，拖选松开 → 高亮保留、`Ctrl+X` 可复制；测完恢复默认并重启 | ①–⑤ 全部符合 |
-
-## Testability split design (hard constraint for implementation)
-
-- **Pure core**: `isFullscreenSelectionEnd(event)` — no env reads, no side effects; full
-  event-shape decision table at unit level (A1).
-- **I/O shell**: `handleMouse` maps the predicate to one `process.nextTick` schedule;
-  `settleFullscreenSelection()` owns the ordering (`getActiveSelectionText` →
-  `writePrimarySelection` → clear → `scheduleRender`). The gesture serial lives on the
-  component (`handleMouse` bumps it on left press, the scheduled closure compares it) and
-  needs no separate unit test: A8 drives it through the public seam. The only xclip touch point stays
-  `writePrimarySelection`; the only pi-selection touch points stay `getActiveSelectionText`
-  / `getCopyOnSelect` / `clearTextSelection`, all through the structural cast.
-- **Fake TUI seams** (component scenario): `getActiveSelectionText`, `getCopyOnSelect`,
-  `clearTextSelection`, `requestRender`. `clearTextSelection` must invalidate the fixture
-  so that a wrong order (clear → read) produces zero PRIMARY writes and fails A2 — the
-  test must not merely count calls.
-- The clear must not be inlined into `handleMouse` (it needs the deferred tick) and must
-  not be replicated in the legacy path.
-
-## Risks / notes
-
-- Private API coupling: `clearTextSelection` can disappear in a future pi-tui. Mitigated
-  by feature detection (degrade, never throw) and by a comment naming the upstream ask
-  (expose a public "clear visual selection, keep click history" method).
-- If pi ever defers selection finalization across ticks, the clear would land before the
-  copy; the `copyOnSelect` gate would then clear a selection pi is about to copy. Accepted
-  risk recorded here; the ordering assumption is pinned by A2's read-before-clear fixture.
-- `Ctrl+X` (pi's copy binding) after a drag becomes a no-op when copy-on-select is on —
-  by construction, the text is already in the clipboard; when the user disabled
-  copy-on-select, the clear is skipped and `Ctrl+X` still works.
-- The highlight for gestures ending outside the overlay remains (same as #174's mirror
-  limitation).
-- A release followed by another press inside one stdin chunk is guarded by the gesture
-  serial (D5/A8). A press that lands outside the overlay does not touch the serial, but
-  pi's own press path has already reset its selection, so the settle reads nothing.
-- Updating the issue's Root cause / Environment text is part of the PR narrative, not of
-  the code change.
-
-## Deliverables
-
-- `src/core/pty-scroll.mjs`: replace `shouldMirrorSelectionToPrimary` with
-  `isFullscreenSelectionEnd`
-- `src/ui/pty-attach.ts`: predicate branch in `handleMouse`; rename/extend
-  `settleFullscreenSelection`; `FullscreenSelectionHost` structural type
-- `test/pty-scroll.test.mjs`: decision-table update
-- `test-support/pty-attach-selection-mirror-scenario.ts` + `test/pty-attach-selection-mirror.test.mjs`:
-  clear/order/copyOnSelect/kill-switch/fallback cases
-- No README change: the `AGENT_BOARD_ATTACH_NATIVE_PASTE` row (README:323) describes X11
-  PRIMARY copy + middle-click paste, which is still exactly what the switch governs; the
-  highlight clear is neither, so the current wording stays accurate after the decoupling.
-- CHANGELOG entry via release tooling at release time (not in this PR)

package/docs/superpowers/specs/2026-10-27-issue-252-select-key-hints-design.md

@@ -1,95 +0,0 @@
-# spec — issue #252：SELECT 模式的 in-app 文案对齐（hint 行 / `?` 覆盖层 / `!` 措辞）
-
-Drafted: deepseek/deepseek-flash (selected) · deepseek/deepseek-flash (physical) @ 2026-10-27T23:28:00+08:00
-Revised: deepseek/deepseek-flash (selected) · deepseek/deepseek-flash (physical) @ 2026-10-27T23:47:00+08:00 — cross-review R2（收敛轮，0 真缺口）：R2-D1 接受（§5 残留的 `rg` 改为 `grep -c`，与 §4 A8 一致）；R2-D2 接受（`pty-support.mjs:155` → `src/core/pty-support.mjs:155`）；R2-D3 接受（U1 前置补 checkout 加载出处 + 重开 pi 会话）
-
-基线：`main @ 3fcc2a4`（#249 之后）。调研留档（仓外，不随 PR 提交）：`~/.github-issue-driven/zhuxixi/pi-agent-board/issue-252/research/` 下的 `01-surfaces-audit.md`、`02-wording-evidence.md`、`03-test-harness.md`。
-授权：`authorization.md` → `Gate: auto`（合并前仍需用户明确批准）。
-
-## 1. 背景
-
-`handleSelectKey`（`src/ui/dashboard.ts:398-423`）绑 9 组键：移动（`↑`/`↓`/`j`/`k`）、`space` toggle、`a` 全选、`u` 清空、`d` 批量 Done、`ctrl+x` 批量删除、`m`/`esc`/`ctrl+c` 退出、`?` 帮助、`!` PTY 诊断。
-
-面向用户的两个 in-app 表面都落后于这份清单：
-
-- **SELECT hint 行**（`listHints()`，`:1347-1358`）写 7 项，缺 `m`/`?`/`!`，且**现状已 122 字符**——120 列终端就被裁掉 2 字符（`esc cancel` → `esc canc`）。
-- **`?` 覆盖层**（`renderHelp`，`:1723`）的 `In select` 行写的是 `j/k move · a select all · u clear · d move done · ctrl+x delete · esc cancel`：缺 `space`（该模式最常用的键）、方向键、`m`、`?`、`!`。
-
-另外 `!` 的措辞三处不一致：README 六处 `repair hints`，覆盖层 `fix steps`，运行时面板用 `Fix:` + `Suggested steps`。
-
-本 issue 是**纯文案同步**，无键位/行为变更。
-
-## 2. 设计决策表
-
-| # | 决策 | 依据 |
-|---|---|---|
-| D1 | SELECT hint 行改为 11 个 token 的紧凑形态：`${n} selected` · [`•${u} unread`] · `↑↓/j/k move` · `space toggle` · `a all visible` · `u clear` · `d done` · `ctrl+x delete` · `m/esc cancel` · `? help` · `! pty`（131 可见字符；带 unread 143） | 9 项全在；相对现状只长 9 字符。压缩方式：`d move done`→`d done`、`ctrl+x delete done`→`ctrl+x delete`、`esc cancel`→`m/esc cancel`。保留 `all visible` 的语义精度（过滤态下 `a` 只选可见行） |
-| D2 | `In select` 行改为：`↑↓/j/k move · space toggle · a all · u clear · d done · ctrl+x delete · m/esc cancel`（渲染 101 列） | 只写本模式专属语义；`?`/`!` 由 D3 的全局行覆盖，不在本行重复。**该行决定整个帮助盒子的宽度**（`renderCenteredBox` 取最长行）：在 D2 行基础上再补 `? help`/`! pty` 为 118 列（若保留原 `a all visible` 写法则为 126 列），两种形态都超过 120 列终端的 `width-6=114` 上限，在 120 列也照样被裁（research/01 §B） |
-| D3 | 覆盖层新增一行 `["?", "Open the key help overlay (list and multi-select)"]`，位置在 `/` 行与 `!` 行之间 | `?` 只绑在 list（`:373`）与 select（`:421`），覆盖层 26 行里一句都没有——这是 issue 未点明的第三处缺口。`!` 已有全局行，故 D2 不重复它 |
-| D4 | `!` 的 canonical 措辞 = `fix steps`：README 六处改齐（4 张表 + `:289` + `:368`）；覆盖层 `:1716` 不动 | 面板自己写 `Fix:` / `Suggested steps`，字段名 `fixHint`/`steps`，代码注释（`src/core/pty-support.mjs:155`）也是 `fix steps`；反向对齐要改运行时代码且与面板自相矛盾（research/02） |
-| D5 | 不动 handler、不动键位、不动 `#246` 的高度适配、不新增 README 表格、不回改历史 spec/plan | 范围纪律。#245 的 D5 是「in-app 三处就其 j/k/l 范围而言已正确，故不动」，并非把 in-app 侧 defer 给后续 issue；本 issue 处理的是 #245 范围**之外**的 SELECT 表面（hint 行的 `m`/`?`/`!`、`In select` 行、`!` 措辞），两者不冲突 |
-
-### D1 的取舍：为什么接受「窄终端裁尾」
-
-11 个 token 在任何布局下都塞不进 80 列，131 字符在 120 列仍会裁掉尾部（`? help`/`! pty`）。三个理由支撑这个取舍：
-
-1. 仓库既有行为就是裁尾：NORMAL hint 行 **238 字符**，240 列才完整（实测，research/01 §A）。
-2. 裁掉的恰好是两个辅助键：`m/esc cancel` 止于第 114 列，在 120 列终端**完整可见**，被裁的只有尾部 `? help` / `! pty`——安全优先。
-3. `?`/`!` 在覆盖层（D3 + `!` 全局行）与 README 里都有完整说明，不依赖 hint 行发现。
-
-**被否决的替代方案**：SELECT footer 折成两行（改 `renderFooter`，让 select 模式多占一行）。它能让 80 列也全可见，但会改变 footer 高度、且仓库没有任何多行 hint 先例，属于布局变更而非文案同步——留给 `#246` 的高度适配一并考虑。
-
-### 与 `#246` 的交互
-
-新增 `?` 行使帮助盒子从 32 行变 **33 行**，`#246` 的裁剪阈值随之多一行。此处不做补偿（不加行数压缩、不删 `normal`/`insert` 说明行）：`#246` 的方向就是重构高度适配，提前在文案侧做布局妥协会让它的方案空间变窄。
-
-## 3. 改动清单
-
-| 文件 | 位置 | 改动 |
-|---|---|---|
-| `src/ui/dashboard.ts` | `listHints()` SELECT 分支 `:1348-1357` | 按 D1 替换 token 列表 |
-| `src/ui/dashboard.ts` | `renderHelp()` rows `:1723` | `In select` 行按 D2 替换 |
-| `src/ui/dashboard.ts` | `renderHelp()` rows `:1715` 后 | 按 D3 插入 `?` 行 |
-| `README.md` | `:148` `:166` `:180` `:200` | `repair hints` → `fix steps` |
-| `README.md` | `:289` | `diagnosis and repair hints` → `diagnosis and fix steps` |
-| `README.md` | `:368` | `follow its repair hints` → `follow its fix steps` |
-| `test-support/vim-keys-wrap.ts` | capture 段 `:130` 之后 | 先插捕获代码：`tui.terminal.rows = 40`，在 SELECT 模式下取 `dash.render(160).join("\n")`，随后恢复 `rows = 24`（照 `:122-126` 的既有手法） |
-| `test-support/vim-keys-wrap.ts` | `out.copy`（`:146`，单行对象字面量） | 把 `selectWide` 加进该对象 |
-| `test/dashboard-vim-keys.test.mjs` | 末尾 | 新增一条 test（A1-A6） |
-
-## 4. 验收矩阵
-
-| ID | 功能点 | 验收方式 | 具体验证 | 通过标准 |
-|----|--------|----------|----------|----------|
-| A1 | SELECT hint 行文档化 9 组绑定中的 7 个键 + 2 个辅助键 | 自动化（unit，探针渲染） | `node --test test/dashboard-vim-keys.test.mjs`，对 `selectWide` 断言 `/↑↓\/j\/k move/`、`/space toggle/`、`/a all visible/`、`/u clear/`、`/d done/`、`/ctrl\+x delete/`、`/m\/esc cancel/`、`/· \? help · ! pty/` | 8 条全部通过 |
-| A2 | 旧措辞不再出现 | 自动化（unit） | 同命令，`assert.doesNotMatch(selectWide, /d move done/)`、`/ctrl\+x delete done/` | 2 条负向断言通过 |
-| A3 | hint 行宽度受控（防再次膨胀） | 自动化（unit） | 从 `selectWide` 取含 `[SELECT]` 的行，`trimEnd().length` 断言 `<= 132` | 131 ≤ 132 通过；超过即红 |
-| A4 | 覆盖层 `In select` 行同步 | 自动化（unit，探针 `help120`，rows=40） | `/In select.*↑↓\/j\/k move/`、`/In select.*space toggle/`、`/In select.*a all · u clear/`、`/In select.*d done/`、`/In select.*ctrl\+x delete/`、`/In select.*m\/esc cancel/`；负向 `/In select.*a select all/` | 6 条正向 + 1 条负向通过 |
-| A5 | 覆盖层新增 `?` 行 | 自动化（unit，`help120`） | `/\?\s+Open the key help overlay \(list and multi-select\)/` | 通过 |
-| A6 | `!` 措辞统一（in-app 侧） | 自动化（unit，`help120`） | `/Open node-pty diagnostics and fix steps/` 且 `doesNotMatch(/repair hints/)` | 通过 |
-| A7 | 无回归 | 自动化（unit，全量） | `npm test` | 全绿，尤其既有 `dashboard-vim-keys` 两条用例 |
-| A8 | README 六处措辞改齐 | 自动化（static，grep；dev 工具，未入 CI） | `grep -c 'repair hints' README.md` → 0 行匹配；`grep -c 'fix steps' README.md` → 6 | 两个计数符合预期 |
-| A9 | 类型/构建/覆盖率门槛 | 自动化（build + test） | `npm run verify` | typecheck、perf gate、全测试、coverage（lines 85 / funcs 80 / branches 70）、pack:dry 全过 |
-| U1 | 真机观感 | 用户实测 | **前置**：PR 合并后在本 checkout `git pull`；确认扩展从本 checkout 加载（README `### Development auto-discovery`：`ln -s "$(pwd)" ~/.pi/agent/extensions/agent-board`，或 `pi install "$(pwd)"`；npm registry 副本要等发版才能看到改动）；**重开 pi 会话**后测（扩展只在 pi 启动时加载，已在跑的实例不会拾取新代码）。**步骤**：① `pi /agent-board`，按 `m`，看底栏是否完整列出 9 项（终端 ≥132 列时可全见，120 列时尾部 `? help`/`! pty` 会被裁——符合 D1 取舍）② 按 `?`，看 `In select` 行含 `space toggle` ③ 在覆盖层确认 `?` 行与 `!` 行文案 ④ 按 `!`：面板标题恒为 `node-pty diagnostics`；**若 PTY 健康**，确认只显示 `Status: healthy`（正文无 `repair hints` 旧措辞即符合 D4）；**若面板进故障分支**，确认分节标签为 `Fix:` / `Suggested steps`（这两段只在非健康分支渲染，健康机器上不出现是预期的） ⑤ 按 `m` 或 `esc` 退出 | 五步观察与 D1-D4 一致；若 120 列下尾部裁剪超出预期，记录实际宽度并回报（不视为失败，D1 已声明取舍） |
-
-## 5. 可测性拆分设计
-
-**不新增函数、不改拆分。** 两个改动点都是既有渲染路径里的字符串字面量：
-
-- `listHints()`（`:1340`）已是纯字符串构造：输入 `this.mode` / `selectionCount()` / `unreadCount()` / `input`，输出 `string`，无 I/O、无副作用；由 `renderFooter` 消费。**不把 token 数组提成模块常量**：那样测试只能断言常量自身（同义反复），反而弱于在渲染面上断言。
-- `renderHelp()`（`:1698`）已是 `width -> string[]` 的纯渲染方法，`rows` 是方法内字面量；同样保持内联。
-
-**测试边界**：`test-support/vim-keys-wrap.ts`（探针，`node --experimental-transform-types`）→ `test/dashboard-vim-keys.test.mjs`（`node:test` + `assert/strict`）。这是本仓既定的 dashboard 文本断言层级（unit），不需要 integration / E2E：改动不跨组件、不涉及文件或协议。
-
-**探针改造（最小）**：现有 `selectRender`（`test-support/vim-keys-wrap.ts:130`）是 120 列，新行 131 字符会被 `clip()` 裁尾 → A1/A3 假红。故新增 `selectWide`（`rows = 40` 下 `render(160)`，插在 `:130` 之后，结果挂进 `:146` 的 `out.copy`）。覆盖层断言复用既有 `help120`（已是 rows=40，绕开 `#246` 的裁剪）。
-
-**红绿校验**：A1/A2/A4/A5 在改动前必须是红的。已核对：`space toggle` 早在 `9612d92` 就在 SELECT hint 行里，因此**不能**用它做唯一断言（issue 原建议的 `assert.match(selectRender, /space toggle/)` 今天就是绿的）；`m/esc`、`? help`、`! pty`、`In select.*space toggle`、`?` 行在本改动前均不存在（research/03 红绿表）。
-
-**不可自动化项**：README 文本（A8 用 `grep -c` 静态核对，不新建 README-lint 测试——仓内无读 README 的测试先例，为此基建超出范围）；U1 的真机观感（终端宽度、配色、截断位置只能在真终端上判断）。
-
-## 6. 非目标
-
-- 不修 `#246`（帮助面板在 <32 行终端的裁剪）——D3 会让它多一行，属于 `#246` 的自留地。
-- 不改任何键位绑定、不改 handler 分支逻辑。
-- 不新增 README 表格、不调整 README 章节结构、不回改 `docs/superpowers/{specs,plans}/2026-10-26-issue-245-*` 历史留档。
-- 不改 `renderPtyHelp` 的面板标签（`Fix:` / `Suggested steps`）——D4 以它们为准。