@huseynsnmz/pi-board 0.15.3 → 0.16.0

package/docs/superpowers/specs/2026-10-16-issue-198-attach-wheel-forward-fallback-design.md

@@ -1,67 +0,0 @@
-# Issue #198 — attach wheel forward-fallback (production topology)
-
-- Issue: https://github.com/zhuxixi/pi-agent-board/issues/198
-- Kind: bug — root-cause report + fix design (follow-up to #183 / #185)
-- Baseline: `main` @ `eab48d0` · worktree `issue-198-attach-wheel-forward-fallback`
-- Drafted: deepseek/deepseek-flash (selected) · deepseek/deepseek-flash (physical) @ 2026-10-16T00:1xZ
-
-## 1. Problem
-
-#185 shipped and the fullscreen wheel was still dead in the reporter's real session, while `PageUp`/`PageDown` and middle-click paste both worked. That combination rules out the input channel (mouse events reach `handleMouse`, keys reach the child) and points at the wheel's own routing decision.
-
-## 2. Root cause
-
-`#185` routes on `this.term.buffer.active.type`, and that signal is structurally unavailable in production:
-
-1. **The screen-log replay is a 100 KB tail** (`SCREEN_LOG_REPLAY_BYTES = 100_000`, `src/core/screen-log.mjs:15`). A real fullscreen child sends `\x1b[?1049h` once at startup, long before the window.
-2. **The snapshot path carries no alternate-screen state.** `src/core/terminal-model.mjs`, `src/core/terminal-snapshot.mjs` and `src/core/terminal-attach-protocol.mjs` have no `alternate` / `1049` / `altScreen` handling; the synthesized frame carries rendered content only.
-3. **Measured:** the reporter's live `screen.log` (420 KB) contains **zero** `\x1b[?1049h`; the new fallback scenario pins the consequence — with the enable outside the window the attach reads `buffer.active.type === "normal"` with `bottomViewportTop(bodyHeight) === 0`.
-
-So the wheel routes `"local"`, finds no attach-local scrollback (a fullscreen TUI paints with absolute positioning, so the normal buffer never scrolls and `baseY` stays 0), and #183's contract returns `undefined`: pi then scrolls the transcript hidden behind the overlay. The `"alternate"` → `"child"` route is effectively **unreachable in production** today; #185's local test only saw it because its fixture re-asserted the enable on every tick, which put the sequence back into the live stream. Removing that hack is part of this fix.
-
-## 3. Fix design
-
-Route order inside `handleMouse` (`src/ui/pty-attach.ts`), unchanged helpers (`wheelScrollLinesUp`, `resolveAttachWheelRoute`, `encodeWheelReport`):
-
-| Condition | Behaviour |
-| --- | --- |
-| `wheelLinesUp === 0`, or the kill switches are off (`route === "none"`) | unchanged: `undefined` |
-| `route === "local"` and `tryScrollBy(linesUp)` moved | unchanged #183: `{handled:true, render:false}` |
-| `route === "child"`, or `route === "local"` with a viewport that cannot move | **new**: forward one synthesized SGR report — the same fallback the raw-SGR path and `PageUp`/`PageDown` already use |
-| any forward, attach disconnected | unchanged #185 CR rule: `undefined` (a forward `send()` would drop is not an effect) |
-
-The `"child"` fast path is kept: when the type *is* known, skipping the inert local viewport avoids a two-line jitter before the child takes over. Correctness no longer depends on it.
-
-README (`PTY attach` paragraph) states the parity rule: local scrollback while it can move, otherwise forwarded to the session.
-
-## 4. Testability split
-
-No new pure helper: the decision is a reordering of existing branches. Coverage instead pins the two topologies:
-
-| Scenario | Topology | Asserts |
-| --- | --- | --- |
-| `test-support/pty-attach-wheel-fallback-scenario.ts` (**new**) | child enters the alternate screen once, floods >130 KB with absolute-positioned frames, then the attach connects — i.e. the enable is outside the replay window | `buffer.type === "normal"`, local room `0`, wheel up/down forwarded as `\x1b[<64;4;3M` / `\x1b[<65;4;3M`, `{handled:true, render:false}`, viewport stays `null`, kill switch falls through |
-| `test-support/pty-attach-alt-wheel-scenario.ts` (updated) | same child, young log, **legacy replay path forced** (`AGENT_BOARD_TERMINAL_SNAPSHOT=0`) so the enable is replayed | the `"child"` route still skips the local viewport; documents *why* it needs the legacy path |
-| `test-support/pty-attach-wheel-scenario.ts` (#183, updated comment) | socketless/ disconnected | the disconnected half of the rule: falls through instead of dropping a forward |
-
-## 5. Acceptance matrix
-
-| ID | 功能点 | 验收方式 | 具体验证 | 通过标准 |
-| --- | --- | --- | --- | --- |
-| A1 | 生产拓扑下滚轮转发 | 自动化（integration） | `node --test test/pty-attach-wheel-fallback.test.mjs` | 拓扑断言（normal + room 0）成立；up/down 各转发一条精确 SGR 报文；`{handled:true,render:false}`；视口保持 null |
-| A2 | `"child"` 分支仍覆盖 | 自动化（integration） | `node --test test/pty-attach-alt-wheel.test.mjs` | legacy 重放路径下 `bufferType === "alternate"`，视口不动，报文转发 |
-| A3 | 断连不消费 | 自动化（integration） | `node --test test/pty-attach-wheel.test.mjs` | socketless 场景仍返回 `undefined` |
-| A4 | 既有行为不回归 | 自动化（integration） | `npm test`（mouse / mouse-mode / selection-mirror / wheel 套件） | 全绿 |
-| A5 | 门禁 | 自动化（static + suite） | `npm run verify` | typecheck / perf / tests / coverage / pack:dry 全过 |
-| A6 | 文档同步 | 自动化（static） | `rg -n "mouse wheel" README.md` | 描述为「本地能滚就滚本地，滚不动就转发」 |
-| U1 | 真实会话里滚轮可用 | 用户实测 | 合并 → `git pull` → 重启 pi → attach 长会话滚轮上下 | 与 `PageUp`/`PageDown` 等效；中键与拖选不变 |
-
-## 6. Non-goals / boundaries
-
-- Not fixing the signal itself (teaching the runner's terminal model + snapshot DTO the alternate-screen flag) — a protocol change that is no longer needed for correctness; recorded as a possible follow-up.
-- The `"alternate"` route stays as a fast path; in today's production it is usually not taken, which is documented here and in the scenario header.
-- No change to `AGENT_BOARD_WHEEL_LINES` semantics, the kill switches, or the middle-click/selection paths.
-
-## 7. Next step
-
-Step 5 of `github-issue-driven`: land this spec in the worktree, plan, implement (done, TDD red → green), local CR, PR with Zima single-bot CR.

package/docs/superpowers/specs/2026-10-18-attach-wheel-replay-pseudo-scrollback-design.md

@@ -1,250 +0,0 @@
-Drafted: deepseek/deepseek-flash (selected) · deepseek/deepseek-flash (physical) @ 2026-10-18T13:34:00+08:00
-Revised: deepseek/deepseek-flash (selected) · deepseek/deepseek-flash (physical) @ 2026-10-18T14:05:00+08:00 — 第 1 轮复核处置（R1-G1 公式修正、R1-G2 测试接缝、R1-D1..D9）
-Revised: deepseek/deepseek-flash (selected) · deepseek/deepseek-flash (physical) @ 2026-10-18T14:20:00+08:00 — 第 2 轮复核处置（R2-G1 非有限数归零、R2-G2 reset 接线与验收、R2-D1 帧投递接缝、R2-D2 记号）
-Revised: deepseek/deepseek-flash (selected) · deepseek/deepseek-flash (physical) @ 2026-10-18T14:35:00+08:00 — 第 3 轮复核处置（收敛轮，0 真缺口；R3-D1..D5 细化）
-
-# issue #205 根因报告与修复设计：attach 滚轮被「快照帧溢出」的伪 scrollback 吞掉
-
-仓库：zhuxixi/pi-agent-board · 基线：`origin/main` @ `b837286`（含 #204）
-
-## 1. 症状（报告者环境）
-
-pi fullscreen TUI → `/agent-board` → attach 会话：
-
-- 滚轮能"动"，但滚动出来的是**旧屏幕碎片**（同一 editor 行重复），不是子会话 transcript
-- PageUp/PageDown 正常滚动子会话
-- `AGENT_BOARD_WHEEL_LINES=3` 在 fullscreen 下无效（文档已注明，非根因）
-- 表现随终端高度变化，矮终端更严重
-
-## 2. 根因
-
-### 2.1 结论
-
-`PtyAttachComponent` 把 **hydrate 快照帧时滚出本地视口的行**当成了"会话历史"，
-于是 `tryScrollBy()` 恒为真，#199 的 `forwardWheelToChild()` 兜底永不触发。
-
-### 2.2 机制
-
-协议路径（`attachMode === "protocol"`）下：
-
-1. 构造期 `replayScreenLog()` 先写入 60 KB legacy 重放（本问题无关，见 §2.4）
-2. runner 用**它自己的尺寸**（子进程 PTY 尺寸，如 `300x65`）`captureTerminalSnapshot()` 并合成
-   `synthesizeFullRedrawFrame()`（65 行 viewport + 0 行 scrollback）
-3. attach 收到 `snapshot_begin { cols: 300, rows: 65 }`，发现与自身尺寸（`rows = terminal.rows - 2 = 38`）不符，
-   只 `sendResize()`，**仍然接受并按 38 行终端 hydrate 这个 65 行的 frame**
-4. `synthesizeFullRedrawFrame` 前导 `\x1b[2J\x1b[3J` 清了 viewport 与 scrollback
-   （`src/core/terminal-snapshot.mjs:329-335`），但随后写入的 65 行 > 38 行，
-   xterm 自然滚动出 **`65 - 38 = 27` 行** → `buffer.active.baseY = 27`
-5. `bottomViewportTop(38) = min(65, 27 + 38) - 38 = 27` → `tryScrollBy()` 认为有 27 行历史可滚
-6. 这 27 行是**当前屏幕顶部若干行**（不是历史），用户滚轮看到的就是它们 → "滚的是输入框内容的历史"
-
-**行溢出不是唯一来源**：列宽不匹配（300 列的绝对定位帧写入更窄的本地 xterm）会按列换行，
-同样推高 `baseY`。因此判据不能只算 `rows` 差，必须取**实际写入后的 `baseY` 增量**。
-
-核心关系：
-
-```
-baseY_after_hydrate = 真实历史行（runner 快照的 scrollback）+ 溢出伪历史行（帧写入时被挤出视口的屏幕顶部行）
-真实历史行          = snapshot.scrollback.length    ← runner 唯一知道，需随协议下发
-可向上滚的行数       = max(0, baseY - historyFloor)
-historyFloor        = baseY_after_hydrate > scrollbackLines ? baseY_after_hydrate : 0
-```
-
-**为什么是"全有或全无"**：`synthesizeFullRedrawFrame` 先写真实 scrollback 行、再写 viewport 行
-（`src/core/terminal-snapshot.mjs:336-351`），所以 hydrate 之后本地 buffer 的布局是
-
-```
-[0 .. S)        真实历史（最旧优先）
-[S .. S+k)      制造行：被挤出视口的屏幕顶部 k 行
-[S+k ..)        视口
-baseY_after = S + k
-```
-
-制造行**夹在真实历史和视口之间**，任何本地滚动都必然先穿过它们；单一 floor 常量无法跳过中间块。
-因此只要发生溢出就把 floor 设为 `baseY`（本地历史整体禁用、滚轮全部转发），不牺牲最旧的真实行。
-
-### 2.3 实证（真实链路，无 mock 组件）
-
-一次性探针：假 runner 用**完整** `screen.log` 构建 `createTerminalModel()`（模拟真实 pty-runner），
-`captureTerminalSnapshot()` + `synthesizeFullRedrawFrame()` 原样回包；attach 侧用真实
-`TuiAltScreen` + 真实 `PtyAttachComponent`，喂真实 `ESC[<64;10;10M`。
-
-```
-protocolReady: true, attachMode: "protocol"
-runnerType: normal, runnerBaseY: 0, runnerLength: 65
-snapshotScrollback: 0, snapshotViewportRows: 65
-attachType: normal, attachBaseY: 27, attachLength: 65
-bodyHeight: 38, bottomViewportTop: 27
-→ firstForwardAt: 28   （第 28 个滚轮事件才到达子会话）
-```
-
-该探针是一次性脚本（未入库），**A4 的 scenario 落地后必须复现同组数值**（见 §5/§6）。
-legacy（无 protocol）路径同源：`rows=30` 时测得 `firstForwardAt: 65`。
-
-### 2.4 与 legacy 重放的关系
-
-构造函数里的 60 KB 重放（`ATTACH_REPLAY_BYTES = 60_000`）在 protocol 路径会被
-`\x1b[3J` 清空，**不是**本次根因；它只在 pre-protocol runner / `AGENT_BOARD_TERMINAL_SNAPSHOT=0`
-降级路径下贡献同类伪历史。本修复**不覆盖**该路径（见 §4 非目标）。
-
-## 3. 修复设计
-
-### 3.1 核心：`historyFloor` 基线
-
-组件维护 `historyFloor`（"早于它的一切都是伪历史"的 baseY 基线），
-"能否向上滚"的判定为 `maxScrollUp = max(0, baseY - historyFloor)`。
-
-更新时机（唯一三处）：
-
-| 时机 | 动作 |
-| --- | --- |
-| `pushOutput(frame, { authoritative: true })` 的 `term.write` 回调 | `historyFloor = historyFloorAfterHydrate(baseY, scrollbackLines)`，`scrollbackLines` 取自本次 `snapshot_ready` 的 payload（见 §3.5），缺省 0 |
-| `term.reset()`（`snap.empty` / `resnapshot`） | `historyFloor = 0`；接线位置见 §3.3，验收见 A6b |
-| `term.resize()` 之后（`resizeIfNeeded`） | `historyFloor = buffer.active.baseY`（见 §3.4 保证边界） |
-
-**不使用 `snapshot_begin.rows` 推算溢出**：行差会被列换行放大，`baseY` 是实测值，唯一可靠。
-
-### 3.2 纯函数拆分（`src/core/pty-scroll.mjs`）
-
-```js
-/**
- * baseY 在 hydrate 之后包含了「本次写入强制滚出的行」。runner 快照里真正属于
- * 历史的只有 scrollbackLines 行，其余一律是伪历史。返回可视为历史的起点。
- */
-export function historyFloorAfterHydrate(baseYAfter, scrollbackLines)
-
-/** max(0, baseY - historyFloor)：真正可以往回滚的历史行数。 */
-export function scrollableHistoryLines(baseY, historyFloor)
-
-/** 现有函数增加 floor 参数（视口起点下限），默认 0 时与原实现逐例等价。 */
-export function scrollViewportTop(viewportTop, bottom, linesUp, floor = 0)
-```
-
-`scrollViewportTop` 语义扩展：
-
-```
-safeBottom = max(0, floor(bottom))
-safeFloor  = clampInt(floor, 0, safeBottom)
-current    = viewportTop == null ? safeBottom : clampInt(viewportTop, safeFloor, safeBottom)
-next       = clampInt(current - linesUp, safeFloor, safeBottom)
-→ { viewportTop: next >= safeBottom ? null : next, changed: next !== current }
-```
-
-`historyFloorAfterHydrate(baseYAfter, scrollbackLines)`：
-
-```
-// 非有限数（undefined / NaN / Infinity）一律归 0——老 runner 不发送该字段
-safeBase       = Number.isFinite(baseYAfter)     ? Math.max(0, Math.floor(baseYAfter))     : 0
-safeScrollback = Number.isFinite(scrollbackLines) ? Math.max(0, Math.floor(scrollbackLines)) : 0
-// 溢出（baseY > scrollback）=> 制造行夹在真实历史与视口之间 => 整体禁用本地历史
-// 未溢出          => 视口之上的每一行都是真实历史 => floor 0，全部可滚
-return safeBase > safeScrollback ? safeBase : 0
-```
-
-语义：`baseYAfter` 至少为 0；`scrollbackLines` 只用来判断"是否溢出"，不用来计算"保留多少行历史"。
-**不得**用 `max(0, floor(x))` 处理未校验的输入（`Math.floor(undefined) === NaN`，会污染整条判定链）。
-
-### 3.3 组件接线（`src/ui/pty-attach.ts`）
-
-- `pushOutput(data, opts)` 增加可选 `opts.scrollbackLines?: number`；
-  `term.write` 回调里 `if (opts.authoritative) this.historyFloor = historyFloorAfterHydrate(this.term.buffer.active.baseY, opts.scrollbackLines)`（回调内没有 `buf` 绑定，必须重新取 `this.term.buffer.active`）
-- `handleAttachEvent("snapshotReady")` 的 `else if (snap.empty || snap.resnapshot)` 分支（`src/ui/pty-attach.ts:1597-1601`）：`this.term.reset()` 之后**必须** `this.historyFloor = 0`，否则 host 重启/重订阅后的 `baseY` 已归零而 floor 仍是旧值，前 floor 行无法本地滚动
-- `handleAttachEvent("snapshotReady")`：`this.pushOutput(snap.frame, { authoritative: true, scrollbackLines: snap.scrollbackLines })`
-  （不再在组件里计算 overflow，也不引入 `pendingFrameOverflow` / `snapshotRows`）
-- 新增 `private scrollFloorStart(height)`：
-  `bottom = bottomViewportTop(height)`；`floorStart = max(0, bottom - scrollableHistoryLines(baseY, historyFloor))`
-- `tryScrollBy` / `tryScrollToTop` / `clampViewportTop` 改用 `scrollFloorStart()` 作为下限
-- `resizeIfNeeded` 的 `term.resize()` 后：`this.historyFloor = buffer.active.baseY`
-
-### 3.4 保证边界
-
-- **hydration 溢出即禁用本地历史**：只要 `baseY > scrollbackLines`，`historyFloor = baseY`，本地一行都滚不动、滚轮全部转发给子会话。制造行夹在真实历史与视口之间（见 §2.2），这是唯一不牺牲最旧真实行的选择。
-- **resize 之后本地滚动历史清零**：`historyFloor` 被设为当前 `baseY`，"宁可暂时不能本地滚，也不把伪历史当历史滚"。resize 之后的真实历史只保留在子会话侧（可转发滚动）。
-- **老 runner 没有 `scrollbackLines`**：按 0 处理 → 本地历史被禁，滚轮全部转发给子会话（对 fullscreen 子会话是正确的；对 regular 子会话是本地滚动能力的退化，记录在 §4）。
-- frame 解析是异步的：解析完成前的滚轮事件按旧 floor 处理（最坏情况 = 现状），解析完成后收敛。
-
-### 3.5 协议扩展（向后兼容）
-
-`src/core/terminal-attach-protocol.mjs`：`snapshot_end` 增加
-`scrollbackLines: dto.scrollback.length`（runner 侧 `captureTerminalSnapshot()` 已经产出该数组）。
-
-`src/core/terminal-attach-client.mjs`：把 `snapshot_end.scrollbackLines` 并入 `snapshotReady` payload，
-**仅当它是 number 时写入该键，否则省略该键**（不写 `scrollbackLines: undefined`）——
-`test/terminal-attach-client.test.mjs:94-95` 的 `deepEqual` 钉死了 `snapshotReady` 的精确形状，
-无条件写键会让既有 happy-path 用例变红；同时更新该文件 `:85` 处 payload 形状的头部注释。
-
-老 runner 不发该字段 → 客户端省略键 → `snap.scrollbackLines === undefined` → §3.3 按 0 处理。**无版本闸门**（字段可选，无需 frameVersion 变更）。
-
-## 4. 非目标
-
-- **不改变 legacy（pre-protocol runner）路径的本地滚动**：那条路径的 60 KB 重放是唯一历史来源，
-  `historyFloor` 保持 0，行为与现状逐例等价。该路径的伪历史问题不在本 issue 范围。
-- 不修改 `AGENT_BOARD_WHEEL_LINES` 在 fullscreen 下的语义（上游 `fullscreenWheelScrollLines` 已负责步长）
-- 不修正 #198 的 buffer-type 探测（本修复不再依赖它）
-- 不新增 `frameVersion` 变更（`scrollbackLines` 是可选字段，缺失即降级）
-
-## 5. 验收矩阵
-
-| ID | 功能点 | 验收方式 | 具体验证 | 通过标准 |
-| --- | --- | --- | --- | --- |
-| A1 | `historyFloorAfterHydrate` 纯函数 | 自动化（unit） | `test/pty-scroll.test.mjs` 新增用例 | `(27,0)=27`（溢出）、`(127,100)=127`（溢出→禁用）、`(5,10)=0`（未溢出）、`(undefined,0)=0`、`(27,undefined)=27` |
-| A2 | `scrollableHistoryLines` 纯函数 | 自动化（unit） | 同上 | `(27,27)=0`、`(127,27)=100`、`(0,0)=0` |
-| A3 | `scrollViewportTop` floor 语义 | 自动化（unit） | 同上（含对拍） | floor=bottom 时 `changed=false`；floor=0 时对现有全部输入逐例与旧实现一致 |
-| A4 | protocol 快照溢出后首次滚轮即转发 | 自动化（integration） | 新增 `test-support/pty-attach-frame-overflow-scenario.ts` + `test/pty-attach-frame-overflow.test.mjs`：假 runner 用真实 `captureTerminalSnapshot`/`synthesizeFullRedrawFrame`（**runner 模型 rows=65，attach rows=38，scrollback=0**），attach 侧真实 `PtyAttachComponent`，直接调 `component.handleMouse` 驱动 | `attachBaseY===27`、`historyFloor===27`、`scrollableHistoryLines===0`；首个 wheel 返回 `{handled:true,render:false}` 并发出 `{type:"input","data":"\x1b[<64;…M"}`；`viewportTop` 保持 `null` |
-| A5 | 溢出时禁用本地历史而不是牺牲最旧真实行 | 自动化（integration） | 同 scenario 变体：runner 先写 100 行普通文本再快照（`scrollbackLines=100`，帧 165 行写入 38 行终端 → 溢出） | `historyFloor === baseY`、`scrollableHistoryLines === 0`，首个 wheel 即转发（未溢出且带历史的情形由 A1 的 `(5,10)=0` 覆盖） |
-| A6 | resize 后基线重置（含保证边界） | 自动化（integration） | 同 scenario：hydrate 后 `component.render(<更窄宽度>)` 触发 `term.resize` | `historyFloor === baseY`、`scrollableHistoryLines===0`，下一次 wheel 立即转发 |
-| A6b | `term.reset()` 后基线归零 | 自动化（integration） | 同 scenario 的 `snap.empty`（或 `resnapshot`）变体：hydration 后投递一次 empty 基线 | `historyFloor === 0` 且 `baseY === 0`；随后以超过 `bodyHeight` 行的 live 输出填满视口，wheel 可本地滚动（floor 不再残留旧值） |
-| A7 | `scrollbackLines` 缺失降级 | 自动化（unit + integration） | unit：`historyFloorAfterHydrate(27, undefined)=27`；integration：scenario 不发 `scrollbackLines` 的变体 | 与 A4 同结果（本地不滚、直接转发），不抛错 |
-| A8 | 真实 fullscreen 调度 smoke | 自动化（integration，附加保护） | 同 scenario 额外用例：真实 `TuiAltScreen` + `showOverlay` + `(tui as any).handleTerminalInput("\x1b[<64;10;10M")`（`handleTerminalInput` 在运行时可达，private 只是 TS 类型层；一次性探针已验证可调用） | `handleMouse` 被调用且首个 notch 即转发 |
-| A9 | legacy 路径不回归 | 自动化（integration） | 现有 `pty-attach-wheel`、`pty-attach-alt-wheel`、`pty-attach-wheel-fallback` 套件 | 全部通过 |
-| A10 | 协议字段兼容 | 自动化（integration） | `test/terminal-attach-protocol*.test.mjs` / client 套件新增断言；同步更新 `test/terminal-attach-client.test.mjs:94-95` 的 `deepEqual` 与 `:85` 形状注释 | `snapshot_end` 带 `scrollbackLines`；client 透传到 `snapshotReady`；`scrollbackLines` 为非 number 时**省略该键**且不报错 |
-| A11 | 类型与构建 | 自动化（static/build） | `npm run typecheck`、`npm run verify` | 通过（含 perf gate + coverage 阈值） |
-| U1 | 真实终端滚轮 | 用户实测 | 见 §5.1 | 面板立即显示子会话 transcript 的上一行（而非输入框碎片）；PageUp 行为保持一致 |
-
-### 5.1 U1 执行时机与部署前置
-
-1. A1–A11 全绿、PR 合并到 `main`
-2. `cd C:/Users/27499/proj/opensource/pi-agent-board && git pull`
-3. **刷新 pi 的 git 包缓存**（pi 加载的是 `~/.pi/agent/git/github.com/zhuxixi/pi-agent-board`，
-   不是本工作区）：`pi update`（或重启 pi 让其重新拉取），并确认
-   `git -C ~/.pi/agent/git/github.com/zhuxixi/pi-agent-board log --oneline -1` 含本 PR 提交
-4. 完整重启 pi（旧进程内的模块缓存不会热更新）
-5. pi fullscreen → `/agent-board` → attach 一个输出超过 60 KB 的长会话 → 拨一次滚轮
-6. 通过标准：第一次滚轮即显示子会话 transcript 的上一行；不出现输入框/旧屏幕碎片；PageUp 仍正常
-
-## 6. 可测性拆分设计
-
-- **决策逻辑全部下沉到 `src/core/pty-scroll.mjs` 纯函数**：`historyFloorAfterHydrate`、
-  `scrollableHistoryLines`、`scrollViewportTop(…, floor)`。无 I/O、无环境变量读取，可直接单测。
-- **组件只承担接线与状态**：`historyFloor` 一个字段 + 三个赋值点（hydrate 回调 / reset / resize），
-  不新增任何"计算"逻辑，避免把已拆分的纯函数重新耦合回组件。
-- **帧投递接缝（A4–A7 的构造前提）**：scenario 必须让 65 行帧**原样**送达组件，不得触发 runner 侧重新 capture。具体两种合法写法（选一并在场景注释里写明）：
-  1. 走完整协议链路，但**假 runner 忽略 `snapshot_begin` 之后到达的 `resize` 控制消息**，按固定 65 行 `captureTerminalSnapshot()` 原样回包；
-  2. 跳过协议层，直接 `component.pushOutput(frame, { authoritative: true, scrollbackLines })` 投递由真实 `synthesizeFullRedrawFrame()` 生成的帧。
-  若假 runner 响应 resize 并重新 capture（38 行），`attachBaseY === 27` 的前提塌陷，A4 永远不成立。
-- **连接与发送可观测（A4–A7 的第二个前提）**：`forwardWheelToChild` 只在 `this.socket && this.connected` 为真时才真正 `send`
-  （`src/ui/pty-attach.ts:474-476`）。scenario 必须建立连接并拦截发送，复用仓库既有模式：
-  真实 host socket / 假 runner 监听 pipe，并拦截 `Socket.prototype.write` 收集 `{type:"input"}`
-  （见 `test-support/pty-attach-wheel-fallback-scenario.ts:113-119`）。用 disconnected 的假 TUI（例如
-  `nonexistent.sock`）会让 forward 静默 no-op 并返回 `undefined`，A4 永远失败。
-- **await 解析完成再断言**：`historyFloor` 在 `term.write` 的回调里才写入（§3.3），而 `@xterm/headless` 是异步解析。
-  A4/A6b 断言前必须 `await` 写入回调，沿用既有模式
-  （`test-support/pty-attach-wheel-scenario.ts:75` 的 `await new Promise((resolve) => component.term.write(..., resolve))`）或轮询到回调完成。
-- **测试边界**：
-  - `test/pty-scroll.test.mjs` —— 纯函数（A1–A3、A7 的 unit 部分）
-  - `test-support/pty-attach-frame-overflow-scenario.ts` —— 真实帧合成 + 真实组件 + 直接 `handleMouse`（A4–A7、A6b）
-  - 同一 scenario 的真实 `TuiAltScreen` 用例 —— 附加保护（A8），断言"事件确实到达 `handleMouse`"
-  - 协议/client 套件 —— 字段透传（A10）
-  - 现有 wheel / alt-wheel / wheel-fallback 套件 —— legacy 无回归（A9）
-- A8 用到的 `handleTerminalInput` 是运行时可达的公开实例方法（`private` 只在 TS 类型层不可见），
-  通过 `(tui as unknown as { handleTerminalInput(d: string): void }).handleTerminalInput(...)` 构造；
-  场景落地时若该签名变化，A8 允许退化为直接调 `dispatchMouseToOverlay`，但**不得**删掉该用例而不记录。
-
-## 7. 风险
-
-| 风险 | 缓解 |
-| --- | --- |
-| `scrollbackLines` 语义与 frame 内容不一致（runner 快照后又有新 chunk 被 flush） | `snapshot_end` 的 `scrollbackLines` 取自同一次 `captureTerminalSnapshot()` 的 dto，与 frame 同源；catch-up flush 的 chunk 是增量（live output），不影响已 hydrate 的行数 |
-| `historyFloor` 让真实历史被判成伪历史 | 只在 hydrate/reset/resize 三处设置；`scrollbackLines` 由 runner 权威给出；resize 场景见 §3.4 明示边界 |
-| 老 runner 造成本地滚动退化 | 明确写入 §3.4 / §4：对 fullscreen 子会话是正确行为，对 regular 子会话是能力退化；`pi update` 后消失 |
-| 现有测试直接调 `handleMouse`，改动可能未被覆盖 | A4 用真实帧合成覆盖 hydrate 路径；A8 补真实调度链路 |

package/docs/superpowers/specs/2026-10-19-issue-213-reply-guard-csi-key-design.md

@@ -1,165 +0,0 @@
-Drafted: deepseek/deepseek-flash (selected) · deepseek/deepseek-flash (physical) @ 2026-10-19T12:40:00+08:00
-Revised: deepseek/deepseek-flash (selected) · deepseek/deepseek-flash (physical) @ 2026-10-19T13:05:00+08:00 — 第 1 轮复核处置（R1-G1/G2/G3 + D1/D2/D3）
-Revised: deepseek/deepseek-flash (selected) · deepseek/deepseek-flash (physical) @ 2026-10-19T13:15:00+08:00 — 第 2 轮复核处置（R2-G1 + D1/D2/D3）
-Revised: deepseek/deepseek-flash (selected) · deepseek/deepseek-flash (physical) @ 2026-10-19T13:25:00+08:00 — 第 3 轮复核处置（收敛轮，R3-D1/D2/D3 细化）
-Revised: deepseek/deepseek-flash (selected) · deepseek/deepseek-flash (physical) @ 2026-10-19T14:20:00+08:00 — 代码评审批次修复（A8③ 空转 grep、REPLY_HEADS 注释未改、armed 路径未覆盖）
-
-# issue #213 根因报告与修复设计：reply guard 的 cell-size 前缀吞掉 kitty 编码的 PageDown
-
-仓库：zhuxixi/pi-agent-board · 基线：`origin/main` @ `ef4317f`
-
-## 1. 症状
-
-`v0.12.0` + WezTerm 20240203 + pi fullscreen 1.3.0 → `/agent-board` → attach：
-
-| 键 | 结果 |
-| --- | --- |
-| `PageUp` | 正常（本地滚动 / 转发） |
-| `PageDown` | **完全无反应** |
-| 鼠标滚轮 | 正常 |
-
-不对称本身就是线索：两个键在 `handleKeyInput` 里走**完全相同**的
-`tryScrollBy(±pageSize)` → `send()` 兜底，所以差异只能出在更上游的输入分类层。
-
-## 2. 根因
-
-`src/core/terminal-reply-guard.mjs` 的 `REPLY_HEADS` 含：
-
-```js
-{ family: "cell-size", prefix: "\x1b[6;" }
-```
-
-本意是吸收被拆碎的 XTWINOPS cell-size 回复（`CSI 6;<rows>;<cols>t`）。
-但 **PageDown 的 legacy 功能键编号正是 6**：kitty 键盘协议下带修饰键的 PageDown 编码为
-`CSI 6;<mod>u`（`\x1b[6;1u`），modifyOtherKeys 回退下为 `CSI 6;<mod>~`（`\x1b[6;5~`）。
-两者都以 `\x1b[6;` 开头 → `classifyReplyEvent` 判成 `reply-head` → guard 进入 armed
-→ 250ms/64 字节吸收窗口把按键吞掉。PageUp 的编号是 5（`\x1b[5;1u`），永不命中，所以不受影响。
-
-附带发现的**文档与代码矛盾**：`REPLY_HEADS` 上方的注释写着
-「Deliberately absent: … `\x1b[5`/`\x1b[6` (PageUp/PageDown heads)」，
-但列表里实际存在 `\x1b[6;` —— 注释想表达的是"不吸收 `\x1b[6` 开头的裸键位"，
-实现却用了一个更宽的前缀，正是这条矛盾掩盖了本次冲突。
-
-引入点：`2148360 fix(attach): stop terminal reply fragments leaking into the attached child's input (#194)`。
-
-## 3. 证据（对仓库当前代码实测）
-
-```
-"\x1b[6;1u"     → { kind: "reply-head", family: "cell-size" }   ❌ PageDown 被吞
-"\x1b[6;5~"     → { kind: "reply-head", family: "cell-size" }   ❌ modifyOtherKeys PageDown 被吞
-"\x1b[5;1u"     → { kind: "other" }                             ✓ PageUp
-"\x1b[6~"       → { kind: "other" }                             ✓ 无修饰的 legacy PageDown
-"\x1b[57422u"   → { kind: "other" }                             ✓ kitty codepoint 形式
-"\x1b[6;"       → { kind: "reply-head", family: "cell-size" }   ✓ 真 fragment 仍 arm
-"\x1b[6;24"     → { kind: "reply-head", family: "cell-size" }   ✓
-"\x1b[6;24;80t" → { kind: "reply-complete", action: "drop" }    ✓
-```
-
-现有测试（15 个 `test()` / 63 条 assert，全绿）**没有覆盖** `\x1b[6;<mod>u` / `\x1b[6;<mod>~` 形态 —— 这是回归缺口。
-`test/terminal-reply-guard.test.mjs:58` 只测了裸 `\x1b[5~` / `\x1b[6~`，
-`:96` 测了 `\x1b[6;` 仍需 arm。
-
-## 4. 修复
-
-**在 head 前缀之前**识别"完整的 CSI 键序列"：真 cell-size fragment 没有 `u`/`~` 终结符，
-所以完整键序列可以安全地判成用户输入。
-
-```js
-// Kitty / modifyOtherKeys keys: `CSI <num>[;<mod>…]{u,~}`. PageDown's legacy number
-// is 6, which shares the `\x1b[6;` prefix with the cell-size reply head.
-const CSI_KEY_SEQUENCE = /^\x1b\[\d+(?:[;:]\d+)*[u~]$/;
-
-export function classifyReplyEvent(data) {
-    …DROP/FORWARD 判定不变…
-    // A COMPLETE CSI key is user input, never a reply fragment.
-    if (CSI_KEY_SEQUENCE.test(data)) return { kind: "other" };
-    for (const head of REPLY_HEADS) { … }
-    …
-}
-```
-
-**正则比 issue 原文更宽一点**：issue 给的 `/^\x1b\[\d+(?:;\d+)?(?::\d+)?[u~]$/` 覆盖不了
-kitty 的"交替键"编码 `\x1b[6;1:2;65u`（`;65` 在主修饰符之后），会重新落回 reply-head。
-`(?:[;:]\d+)*` 覆盖全部 `CSI <num>;[<mod>[:<event>][;<alternate>]]u` 形态。
-
-保持不变的行为：
-
-- `\x1b[6;`、`\x1b[6;24`（无终结符）→ 仍然 `reply-head`（arm）
-- `\x1b[6;24;80t` → 仍然 `reply-complete` drop（DROP_SHAPES 命中在前）
-- 其余 `REPLY_HEADS`（`\x1b[?`、`\x1b[>`、`\x1bP`、`\x1b]1`、`\x1b]4`）无键位冲突，不动
-
-顺带修掉 `REPLY_HEADS` 上方与新语义矛盾的注释（说明 `\x1b[6;` 只能靠"完整键序列优先"来消解冲突）。
-
-### 4.1 推翻既有设计文档的 pinned 不变式（R1-G3）
-
-`docs/superpowers/specs/2026-10-14-issue-170-attach-reply-guard-design.md:106` 钉死了：
-
-> 窗口只由 `reply-head` 武装，只有「**永不可能是按键/鼠标编码前缀**」的形状才武装：
-> `ESC[?`、`ESC[>`、**`ESC[6;`**、`ESC P`、`ESC]1`、`ESC]4`。
-
-本次根因正是这条论断的反例：kitty 功能键编号形态 `ESC[6;1u`（PageDown）打破「永不可能是按键前缀」。
-因此本修复**显式推翻**该不变式，替换为：
-
-> 完整 CSI 键序列（`CSI <num>[;<mod>[:<event>][;<alt>]]{u,~}`）优先于 head 前缀判定；
-> 只有**不带** `u`/`~` 终结符的片段才按 head 武装。
-
-同步要求（实现阶段必做）：
-
-- **改掉 `REPLY_HEADS` 上方那段与新语义矛盾的注释**（源码 :76-79，「can never be a key/mouse/paste
-  encoding」「Deliberately absent: … `[5`/`[6`（PageUp/PageDown heads）」）：不得再出现
-  绝对断言，改为说明「完整键序列优先，只有不带终结符的片段才武装」。
-  模块 header 用**英文**写同一条规则（`complete CSI key sequence … beats the head prefixes`），
-  中文仅在 #170 文档里作为跨引用出现。
-- 在 #170 设计文档 §3.3 的「设计要点」清单里补上「完整 CSI 键序列优先于 head 前缀」这一新类别，
-  并把 L106 的论断标注为已被 #213 修正（追加而非改写历史）
-- #170 文档 L112 与 A4 清单里「`ESC[6;` 必须武装」仍然成立（本修复只对**完整**键序列例外）
-
-## 5. 边界与风险
-
-| 风险 | 说明 / 缓解 |
-| --- | --- |
-| 真 cell-size 回复被误判成键 | 不可能：cell-size 以 `t` 结尾，不带 `u`/`~` |
-| kitty 其他功能键（`\x1b[5;1u` 等） | 本就未被 head 命中，行为不变 |
-| modifyOtherKeys 其他键（`\x1b[3;5~`） | 不命中 `\x1b[6;`，行为不变 |
-| 极少数终端把 PageDown 编码成 `\x1b[6;`（截断） | 仍会 arm 并吞掉；这是 issue #170 的保护方向，保留 |
-| 安全方向 | 修复只是让**用户按键**更早地判定为非回复；不会让回复碎片更容易漏进子会话 |
-
-## 6. 验收矩阵
-
-| ID | 功能点 | 验收方式 | 具体验证 | 通过标准 |
-| --- | --- | --- | --- | --- |
-| A1 | kitty/modifyOtherKeys PageDown 判为键 | 自动化（unit） | `test/terminal-reply-guard.test.mjs`：`\x1b[6;1u`、`\x1b[6;5u`、`\x1b[6;1:2u`、`\x1b[6;1:2;65u`、`\x1b[6;5~` | 全部 `{ kind: "other" }` |
-| A2 | PageUp 与其他键不受影响 | 自动化（unit） | 同文件：`\x1b[5;1u`、`\x1b[5;5~`、`\x1b[57422u`、`\x1b[57421u`、`\x1b[3;5~` | 全部 `{ kind: "other" }` |
-| A3 | 真 cell-size fragment 仍 arm | 自动化（unit） | 同文件：`\x1b[6;`、`\x1b[6;24` | 均 `{ kind: "reply-head", family: "cell-size" }` |
-| A4 | 完整 cell-size 回复仍 drop | 自动化（unit） | 同文件：`\x1b[6;24;80t` | `{ kind: "reply-complete", family: "cell-size", action: "drop" }` |
-| A5 | guard 状态机不回归 | 自动化（unit） | 现有 `terminal-reply-guard` 全部用例 | 全绿 |
-| A6 | attach 按键真的转发到子会话（不被 guard 吞） | 自动化（integration） | `test-support/attach-reply-guard-smoke.ts` 新增：`handleInput("")` / `handleInput("[6;5~")` 后 `sent` 含该字节；断言归 `test/pty-attach-reply-guard.test.mjs` | `sent` 收到完整键序列；且随后的普通文本仍正常转发 |
-| A7 | 语法/静态检查 | 自动化（static） | `npm run typecheck`（`tsconfig` 对 `.mjs` 是 `allowJs` + `checkJs:false`，只做语法解析）+ `npm run pack:dry` | 均通过 |
-| A8 | §4.1 的文档同步真的落地 | 自动化（static） | 三条独立 grep，全部锚定**英文** marker（源码是英文注释，中文只出现在 #170 文档）：① `grep -c "complete CSI key" src/core/terminal-reply-guard.mjs`（≥1，且位于模块顶部注释区）；② `grep -n "完整 CSI 键序列优先.*#213" docs/superpowers/specs/2026-10-14-issue-170-attach-reply-guard-design.md`（≥1）；③ `grep -c "can never be a key" src/core/terminal-reply-guard.mjs`（**必须为 0** —— 旧的绝对断言已删除） | ①② ≥1、③ ==0 |
-| U1 | 真实终端 PageDown | 用户实测 | 见 §6.1 三步前置 + WezTerm + pi fullscreen → attach → 按 PageDown | 面板按页向后滚动（或转发给子会话），与 PageUp 对称 |
-
-### 6.1 U1 执行时机与部署前置
-
-仓库加载补丁 checkout 的方式见 `README.md:54`（`pi install "$(pwd)"`）或 `README.md:68`（symlink 到
-`~/.pi/agent/extensions/agent-board`）。U1 必须在以下三步之后执行，否则测的是旧代码：
-
-1. 用上述任一方式把**当前 worktree/checkout** 加载到 pi（不是 `~/.pi/agent/git/...` 的缓存克隆）
-2. 完整重启 pi（模块缓存不会热更新），并新开一个 attach 会话
-3. 时机：本地 `npm run typecheck` + 目标套件全绿之后、合并之前
-
-> **验收 ID 作用域**：#213 的 `A1–A8` 仅指本 issue。新增测试名一律带 `#213-` 前缀
-> （如 `test("#213-A1: kitty PageDown is a key, not a reply head")`），
-> 因为 `test/terminal-reply-guard.test.mjs` 里已有 #170 遗留的 `A1:`/`A2:`/… 测试名，
-> 直接用 `--test-name-pattern="A1"` 会同时命中两套语义不同的用例。
-
-## 7. 可测性拆分设计
-
-- **判定逻辑已经是纯函数**（`classifyReplyEvent`），零改动地单测；本次只新增一个正则常量。
-- 测试边界：`test/terminal-reply-guard.test.mjs` 覆盖 A1–A5（纯函数层）；`test-support/attach-reply-guard-smoke.ts` + `test/pty-attach-reply-guard.test.mjs` 覆盖 A6（真实 `PtyAttachComponent.handleInput` → `sent` 转发，只替换 socket）。`test/pty-scroll.test.mjs` 与本次改动无关，不作为护栏。
-- 正则常量导出与否：**不导出**（内部实现细节），测试通过 `classifyReplyEvent` 的公开行为验证，避免把实现形状钉进测试。
-
-## 8. 非目标
-
-- 不改变 guard 的吸收窗口（250ms / 64 字节）与 kill switch 语义
-- 不改动其他 `REPLY_HEADS` 条目
-- 不处理 `PageUp`/`PageDown` 在 legacy 路径的行为差异（本就正常）

package/docs/superpowers/specs/2026-10-19-issue-214-attach-forward-alt-modifier-design.md

@@ -1,131 +0,0 @@
-Drafted: deepseek/deepseek-flash (selected) · deepseek/deepseek-flash (physical) @ 2026-10-19T13:58:00+08:00
-Revised: deepseek/deepseek-flash (selected) · deepseek/deepseek-flash (physical) @ 2026-10-19T14:10:00+08:00 — 第 1 轮复核处置（收敛轮，R1-D1..D4 细化）
-
-# issue #214 根因报告与修复设计：attach 转发丢 Alt 修饰位，Alt+滚轮退化为 1 行
-
-仓库：zhuxixi/pi-agent-board · 基线：`origin/main` @ `64bca89`
-
-## 1. 症状
-
-pi fullscreen 1.3.0 + WezTerm，在 attach 一个 fullscreen 子会话时：
-
-| 手势 | 正常 fullscreen | attach 内 |
-| --- | --- | --- |
-| 滚轮 | 1 notch = 加速后的行数 | 相同（转发给子会话） |
-| **Alt + 滚轮** | **5×**（`ALT_WHEEL_SCROLL_MULTIPLIER = 5`） | **1×** —— Alt 被静默丢弃 |
-
-其余滚轮行为（普通滚轮、PageUp/PageDown、本地 scrollback）都正常。
-
-## 2. 根因
-
-fullscreen 子会话的滚轮走**转发**路径（alternate buffer 无 scrollback，见 #185/#198/#199/#205）。该路径**从零重建** SGR 报告，只保留方向：
-
-`src/ui/pty-attach.ts:1477`：
-
-```ts
-private forwardWheelToChild(linesUp: number, event: TuiMouseEvent): void {
-    this.send({
-        type: "input",
-        data: encodeWheelReport(linesUp > 0 ? "up" : "down", {
-            col: clampInt(event.x + 1, 1, this.cols),
-            row: clampInt(event.y, 1, Math.max(1, this.bodyHeight())),
-            // ← event.alt 没有传
-        }),
-    });
-}
-```
-
-`src/core/pty-scroll.mjs:370`：
-
-```js
-export function encodeWheelReport(direction, { col, row } = {}) {
-    const button = direction === "up" ? 64 : 65;   // 永远不置 SGR bit 3 (值 8 = Alt)
-    ...
-}
-```
-
-真实终端用 SGR **bit 3（值 8）** 表示 Alt：Alt+wheel-up = `72 = 64 + 8`，Alt+wheel-down = `73 = 65 + 8`。
-子会话的 pi-tui 正是读这一位来决定 5× 加速
-（`@earendil-works/pi-tui/dist/tui-alt-screen.js` `handleViewportInput`）：
-
-```js
-const wheelDelta = wheelEvent.direction * ((wheelEvent.button & 8) !== 0 ? lines * ALT_WHEEL_SCROLL_MULTIPLIER : lines);
-```
-
-attach 覆盖层**本来就拿到了** Alt：pi-tui 的 `TuiMouseEvent` 带 `alt: boolean`（`createMouseEvent` 里 `alt: (button & 8) !== 0`）。它只是没被传下去。
-
-## 3. 证据（对仓库当前代码实测）
-
-```
-encodeWheelReport("up",   {col:5,row:3})            → "\x1b[<64;5;3M"
-encodeWheelReport("up",   {col:5,row:3,alt:true})   → "\x1b[<64;5;3M"   ❌ alt 被忽略（应为 72）
-encodeWheelReport("down", {col:5,row:3,alt:true})   → "\x1b[<65;5;3M"   ❌（应为 73）
-```
-
-子会话侧对照：
-
-| 子会话收到的报告 | 结果 |
-| --- | --- |
-| `\x1b[<64;5;3M`（plain） | 1× |
-| `\x1b[<72;5;3M`（Alt+up，**当前永远收不到**） | 5× |
-| `\x1b[<65;5;3M`（plain） | 1× |
-| `\x1b[<73;5;3M`（Alt+down，**当前永远收不到**） | 5× |
-
-## 4. 修复
-
-把覆盖层的 `alt` 透传进编码器，置 SGR bit 3：
-
-`src/core/pty-scroll.mjs`：
-
-```js
-export function encodeWheelReport(direction, { col, row, alt = false } = {}) {
-	const base = direction === "up" ? 64 : 65;
-	const button = alt === true ? base + 8 : base;
-	const cell = (v) => (Number.isFinite(v) ? Math.max(1, Math.floor(v)) : 1);
-	return `\x1b[<${button};${cell(col)};${cell(row)}M`;
-}
-```
-
-`src/ui/pty-attach.ts` `forwardWheelToChild`：在参数对象里补 `alt: event.alt === true`。
-
-## 5. 边界与风险
-
-| 风险 | 说明 / 缓解 |
-| --- | --- |
-| 影响本地滚动 | 不影响：本地路径用 `wheelDelta`（外层 pi 已加速的值），不经 `encodeWheelReport` |
-| 影响 legacy regular-mode 路径 | 不影响：该路径（`handleMouseInputChunk`，`src/ui/pty-attach.ts:1110`）把原始 SGR `raw` **原样**转发，从不重建报告，因此天然保留 alt 位，本次不动它 |
-| `event.alt` 缺失（老 pi-tui） | `alt = false` 默认值兜底；`=== true` 显式比较，`undefined` 不会误开位 |
-| Alt 被终端吞掉 | 不在本次范围：终端若不发 Alt 位，覆盖层也拿不到；本次只保证"拿到就转发" |
-| shift / ctrl 修饰位 | **非目标**：pi-tui 只消费 Alt 位做加速，转发其他位不会改变行为却扩大改动面；若将来需要，同一参数可扩展 |
-| 与 #170 reply guard 的交互 | 无关：本次只改出站编码，入站分类不动 |
-| 与 #213 的交互 | 无关：`\x1b[<` 开头是 SGR mouse，不命中 `CSI_KEY_SEQUENCE` 也不命中任何 reply head |
-
-## 6. 验收矩阵
-
-| ID | 功能点 | 验收方式 | 具体验证 | 通过标准 |
-| --- | --- | --- | --- | --- |
-| A1 | Alt+wheel-up 编码为 72 | 自动化（unit） | `test/pty-scroll.test.mjs`：`encodeWheelReport("up", { col: 5, row: 3, alt: true })` | `"\x1b[<72;5;3M"` |
-| A2 | Alt+wheel-down 编码为 73 | 自动化（unit） | 同上 | `"\x1b[<73;5;3M"` |
-| A3 | 无 Alt 时行为不变，且严格比较（`=== true`） | 自动化（unit） | 同上：`alt: false` / 缺省 / `alt: undefined` / **`alt: 1`** / **`alt: "yes"`**（truthy 非布尔） | 全部为 64 / 65，无一置 bit 3 —— 锁死 `event.alt === true` 的严格比较契约 |
-| A4 | 转发链路真的把 `event.alt` 传下去 | 自动化（integration） | `test-support/pty-attach-wheel-fallback-scenario.ts` 增加 `alt: true` 的 wheel 事件，断言 runner 收到 `\x1b[<72;…M` | 收到的报告含 `72`（up）/ `73`（down） |
-| A5 | 本地滚动路径不受影响 | 自动化（integration） | 既有 `pty-attach-wheel` / `pty-attach-frame-overflow` / `pty-attach-alt-wheel` 套件 | 全绿 |
-| A6 | 静态检查 | 自动化（static） | `npm run typecheck` + `npm run pack:dry` | 通过 |
-| U1 | 真实终端 Alt+滚轮 | 用户实测 | 部署前置见 §6.1；attach 一个 fullscreen 子会话，按住 Alt 滚一格 | 子会话滚动 5 行（与 attach 外一致） |
-
-### 6.1 U1 执行时机与部署前置
-
-1. 用 `pi install "$(pwd)"`（`README.md:54`）或 symlink 到 `~/.pi/agent/extensions/agent-board` 加载**当前 checkout**，而不是 `~/.pi/agent/git/...` 缓存
-2. 完整重启 pi，新开一个 attach 会话
-3. 时机：目标套件全绿之后、合并之前
-
-## 7. 可测性拆分设计
-
-- **编码逻辑是纯函数**（`encodeWheelReport`），签名扩展一个可选参数即可单测；无 I/O。
-- **接线在 `forwardWheelToChild`**（薄壳），只多传一个字段；集成测试落在既有的 `pty-attach-wheel-fallback-scenario.ts`（真实 `Socket.prototype.write` 拦截），与 #198/#205 的断言模式一致。
-- **测试边界**：A1–A3 在 `test/pty-scroll.test.mjs`（纯函数）；A4 在 `test/pty-attach-wheel-fallback.test.mjs` + 对应 scenario；A5 复用既有套件；不新增测试文件。
-
-## 8. 非目标
-
-- 不转发 shift / ctrl 修饰位（见 §5）
-- 不改本地滚动路径的任何行为
-- 不改 reply guard / 输入分类