@huseynsnmz/pi-board 0.15.3 → 0.16.0

package/docs/superpowers/specs/2026-10-14-issue-189-mixed-input-segments-design.md

@@ -1,369 +0,0 @@
-Drafted: deepseek/deepseek-flash (selected) · deepseek/deepseek-flash (physical) @ 2026-10-14T12:45:00Z
-Revised: deepseek/deepseek-flash (selected) · deepseek/deepseek-flash (physical) @ 2026-10-14T13:10:00Z (round-1 findings R1-G1/G2/G3/D1/D2 all accepted)
-Revised: deepseek/deepseek-flash (selected) · deepseek/deepseek-flash (physical) @ 2026-10-14T13:22:00Z (round-2 finding R2-D1 accepted: report table row 3 relabelled as defensive-only)
-Revised: zai-coding-cn/glm-5.3-flash (selected) · zai-coding-cn/glm-5.3-flash (physical) @ 2026-10-15T00:24:50Z (round-2 review follow-up: A9 pinning strengthened)
-Revised: deepseek/deepseek-flash (selected) · deepseek/deepseek-flash (physical) @ 2026-10-16T00:30:00Z (post-merge composition with main's #194 inbound reply guard; zima CR advisory on PR #196)
-
-# Spec: #189 — attach(legacy): dispatch a mixed input read per segment, and stop treating terminal reports as user intent
-
-- Issue: https://github.com/zhuxixi/pi-agent-board/issues/189
-- Kind: bug — root-cause report + fix design
-- Repo: `zhuxixi/pi-agent-board` · baseline `main` @ `f81949d` · planned worktree `issue-189-mixed-input-segments`
-- Route: bug → `systematic-debugging` (Phase 1 root cause + runtime repro in `research/`, this document is the design)
-- Research: `~/.claude/github-issue-driven/zhuxixi/pi-agent-board/issue-189/research/`
-  (`01-root-cause-and-reachability.md`, `03-fix-hypothesis-validated.md`, prototype `02-prototype.patch`)
-- Scope: **#189 only.** #187 (motion-less drag) and #188 (X10 release) are separate, in-flight
-  issues; this fix must work with both still broken. #186 stays the UX umbrella.
-
-## 1. Problem
-
-In the legacy (regular-TUI) attach path the whole input read is classified all-or-nothing:
-
-| Spot | Location | Behaviour |
-|---|---|---|
-| `parseMouseInputChunk` | `src/core/pty-scroll.mjs:84` | Returns the decoded mouse events only when **every** byte of the chunk is a mouse report; one stray byte → `null`. |
-| `handleInput` head | `src/ui/pty-attach.ts:297-298` | `null` means "not a mouse chunk" → the whole chunk enters the keyboard chain. |
-| `handleInput` default branch | `src/ui/pty-attach.ts:373-376` | `clearPendingClick(); clearSelection(); scrollToBottom(); send({ type: "input", data })` — the **whole** chunk, mouse bytes included, is forwarded into the hosted session. |
-
-Terminals coalesce a mouse release with bytes they send for their own reasons — focus in/out
-reports (`\x1b[I`/`\x1b[O`), query replies, colour-scheme reports, OSC responses. When that happens
-the mouse events are dropped (no copy, selection cleared, viewport reset) **and** the raw mouse
-bytes are typed into the hosted session.
-
-The keyboard chain has no branch of its own for terminal *reports* either: a spontaneously arriving
-report takes the same default branch, so it destroys an in-progress selection and snaps the reading
-position to the bottom although it carries no user intent.
-
-### Runtime reproduction (this session, 2026-10-14, main `f81949d`)
-
-Real `PtyAttachComponent` + real runner socket + fake PTY, OSC 52 observed on a fake
-`tui.terminal.write`, `{type:"input"}` frames observed on a `Socket.write` tap
-(`research/01-root-cause-and-reachability.md`, probes 1+2):
-
-| Input (one `handleInput` call per step) | OSC 52 | selection | forwarded as input |
-|---|---|---|---|
-| control: press / move / release, separate chunks | `fake pi ready` | retained | — |
-| press, move, then `"\x1b[<0;16;2m\x1b[I"` (release + focus-in) | none | **`null`** | **whole chunk** |
-| press, move, then `"\x1b[I\x1b[<0;16;2m"` (report first) | none | **`null`** | **whole chunk** |
-| press, move, then `"\x1b[I"` (report alone) | none | **`null`** | `"\x1b[I"` |
-| `"\x1b[<64;10;3M\x1b[I"` (wheel + report) on a scrollable buffer | none | **`null`** | **whole chunk**, wheel never applied |
-| `"\x1b]11;rgb:0d0d/0d0d/0d0d\x07"` (OSC 11 reply) mid-drag | none | **`null`** | the reply (intended) |
-| `"\x1b[I"` while scrolled back (200-line buffer) | — | — | viewport `178` → **`null`** |
-
-Two findings beyond the issue text, both reproduced: the split must work in **both orders** (a
-report can precede the mouse report in the same read), and a coalesced **wheel** event both stops
-scrolling and leaks its bytes into the child.
-
-Why the offending bytes are realistically there: the host pi's own reply filters are whole-chunk
-anchored (`/^\x1b\[\?[\d;]*c$/`, `/^\x1b\[6;(\d+);(\d+)t$/`, `COLOR_SCHEME_REPORT_PATTERN`,
-`pi-tui terminal-colors.js` OSC pattern), so coalescing defeats them and the bytes land on the
-attach component's keyboard path; and the board **deliberately** forwards the child's terminal
-queries (`extractOscQuerySequences`, #128) whose replies have no local owner — the code comment at
-`src/ui/pty-attach.ts:658-662` states that they fall through `handleInput` into the child PTY.
-
-Not a regression: `git log -S parseMouseInputChunk -- src/` → single hit `ffc2c8c` (2026-08-30).
-
-## 2. Goal / non-goals
-
-**Goal.** One input read is dispatched segment by segment in arrival order: mouse runs go to the
-existing mouse path, terminal *reports* are passed through to the child without touching selection
-or viewport, everything else keeps today's keyboard semantics byte-for-byte. The issue's exact
-mixed chunk (either order) copies the selection again and leaks nothing into the child.
-
-**Non-goals.**
-
-- Mouse decoding itself: `parseMouseEventPrefix`, the SGR/X10 branches, wheel classification. #188
-  owns the X10 release bug; #187 owns the motion-less drag classification. Neither is assumed fixed.
-- The drag/click/copy/highlight contract (`shouldCopy`, pending click, #172 highlight retention) and
-  `handleLocalMouseEvent` — untouched.
-- Fullscreen host mode / `handleMouse` / pi-tui selection: in fullscreen `TuiAltScreen` consumes raw
-  mouse sequences and focus reports as an input listener before any overlay, so the legacy parser
-  never sees them (`tui-alt-screen.js:105,475-527`). Scope is regular TUI mode (and pi < 1.0).
-- #186 UX items (selection background colour, 1-cell press selection, `pbcopy` fallback, Shift+drag
-  docs).
-- Forwarding policy for reports (they are forwarded as today), `childInputReady`/startup echo
-  ordering (#165/#180), the run of a *key* clearing the selection and jumping to the bottom (stays).
-- No new env knob, no new dependency, no new I/O surface, no change to `parseMouseInputChunk`'s
-  contract (its unit tests and #188's planned cases depend on it).
-
-## 3. Design
-
-### 3.1 Pure decision layer — `src/core/pty-scroll.mjs`
-
-**(a) `parseMouseRun(data, offset)`** — module-private: reads a maximal run of concatenated mouse
-reports using the existing `parseMouseEventPrefix`. Returns `{ events, length }` or `null`.
-`parseMouseInputChunk` is re-expressed on top of it and keeps its exact contract:
-
-```js
-export function parseMouseInputChunk(data) {
-	if (!data) return null;
-	const run = parseMouseRun(data);
-	return run && run.length === data.length ? run.events : null;
-}
-```
-
-**(b) Report table + `parseReportPrefix` / `parseReportRun`** — module-private. A *report* is a
-complete byte sequence the real terminal sends in answer to a query, never in answer to a key.
-Every pattern is grounded in a query this stack actually issues — except row 3, which is kept as a
-defensive extra and labelled as such; anything not listed keeps today's keyboard semantics
-(fail-safe direction: an unknown sequence is typing).
-
-| # | Pattern | What produces it |
-|---|---|---|
-| 1 | `\x1b[I` / `\x1b[O` | focus in/out, DECSET 1004 (pi's fullscreen TUI enables it; regular mode only via leaked terminal state) |
-| 2 | `CSI ? <digits[;digits]> c` | DA1 reply to `\x1b[c` — the trailing sentinel of Pi's colour batch (`pi-tui tui.js:57`) |
-| 3 | `CSI > <digits[;digits]> c` | **not grounded (defensive only)**: this stack sends no DA2 query — the only DA query is `\x1b[c` (`pi-tui terminal.js:15`), whose reply row 2 covers — and XTVERSION replies are DCS-shaped, i.e. deliberately excluded below. Kept because no keystroke encodes as a `>`-prefixed CSI, and a stray DA2 reply would otherwise reach the keyboard path. |
-| 4 | `CSI ? <digits[;digits]> u` | kitty keyboard flag reply to `\x1b[?u` (`pi-tui terminal.js:210`) |
-| 5 | `CSI ? <digits[;digits]> n` | mode/status reports, incl. the colour-scheme report `\x1b[?997;1n` Pi parses (`terminal-colors.js:19`) |
-| 6 | `CSI <digits[;digits]> t` | XTWINOPS replies — the host asks for the cell size with `\x1b[16t` (`tui.js:603`) and consumes `CSI 6;h;wt` |
-| 7 | `OSC <body ≤4096 bytes> BEL\|ST` | colour replies (OSC 10/11/12, OSC 4) and other reply bodies (e.g. program status OSC 7501) |
-
-Deliberately **not** matched (a keystroke can look like them, so they keep key semantics, and the
-exclusion is part of the contract): `CSI … R` (cursor-position report, but also modifier-F3),
-`u`-final CSI without `?` (kitty key events), `CSI … $ y` (DECRPM — nothing in this stack queries
-modes), DCS replies (no in-repo DCS query).
-
-**(c) `splitAttachInput(data)`** — the new public function (the only one):
-
-```js
-/** @returns {Array<{kind:"mouse", events:[…]} | {kind:"report", data:string} | {kind:"key", data:string}>} */
-export function splitAttachInput(data) {
-	if (!data) return [];
-	const segments = [];
-	let offset = 0;
-	while (offset < data.length) {
-		const mouse = parseMouseRun(data, offset);
-		if (mouse) { pushSegment(segments, { kind: "mouse", events: mouse.events }); offset += mouse.length; continue; }
-		const report = parseReportRun(data, offset);
-		if (report) { pushSegment(segments, { kind: "report", data: report }); offset += report.length; continue; }
-		// Neither: keyboard text up to the next ESC.
-		const next = data.indexOf("\x1b", offset + 1);
-		const end = next === -1 ? data.length : next;
-		pushSegment(segments, { kind: "key", data: data.slice(offset, end) });
-		offset = end;
-	}
-	return segments;
-}
-```
-
-Decision table (consecutive same-kind segments are merged; a partial/trailing escape sequence is
-never recognised and becomes `key`, i.e. the bytes the all-or-nothing parser used to forward):
-
-| Input (one read) | Segments |
-|---|---|
-| `"\x1b[<64;10;20M\x1b[<65;10;20M"` | `[mouse(2)]` |
-| `"\x1b[<0;16;2m\x1b[I"` | `[mouse(1), report]` |
-| `"\x1b[I\x1b[<0;16;2m"` | `[report, mouse(1)]` |
-| `"\x1b[I\x1b[O\x1b[<0;16;2m"` | `[report ("\x1b[I\x1b[O"), mouse(1)]` |
-| `"\x1b[<0;16;2mx"` / `"x\x1b[<0;16;2m"` | `[mouse(1), key "x"]` / `[key "x", mouse(1)]` |
-| `"\x1b[Ix"` / `"x\x1b[I"` | `[report, key "x"]` / `[key "x", report]` |
-| `"\x1b[5~\x1b[6~"` (adjacent key runs **merge**) | `[key "\x1b[5~\x1b[6~"]` — one segment, so `matchesKey` sees the same concatenation as today |
-| `"hello"` | `[key "hello"]` |
-| `""` | `[]` |
-| `"\x1b[<0;16"` (truncated) | `[key "\x1b[<0;16"]` |
-| `"\x1b[?997;1"` (truncated report) | `[key "\x1b[?997;1"]` |
-| `"\x1b[1;2R"`, `"\x1b[97;5u"`, `"\x1bP1+r…\x1b\\"` (kept as keys) | `[key …]` |
-
-### 3.2 Component wiring — `src/ui/pty-attach.ts`
-
-`handleInput` becomes a dispatch loop; the existing keyboard chain moves verbatim into a private
-`handleKeyInput(segment)` (same branches, same `return`s — no logic change):
-
-```ts
-	handleInput(data: string): void {
-		for (const segment of splitAttachInput(data)) {
-			if (segment.kind === "mouse") {
-				this.handleMouseInputChunk(segment.events);
-			} else if (!this.consumeByReplyGuard(segment.data)) {
-				if (segment.kind === "report") this.send({ type: "input", data: segment.data });
-				else this.handleKeyInput(segment.data);
-			}
-			// A detach/close inside a segment must stop the rest of this read.
-			if (this.closed) return;
-		}
-	}
-```
-
-`consumeByReplyGuard(data)` (new private method) runs the issue #170/#194 inbound reply guard over one
-non-mouse **segment** and returns true when the guard took it — a complete protocol reply (DA1/DA2,
-kitty flags, cell-size, DCS) is dropped, a colour reply is forwarded as one whole sequence. Feeding
-segments instead of raw reads is what keeps a recognized report segment from absorbing keys that
-were coalesced into the same read — the very case #189 exists for. A still-fragmented head keeps
-the bounded #194 absorption (64 bytes / 250 ms, kill-switchable).
-
-- `mouse` → the existing `handleMouseInputChunk` (wheel branch + `handleLocalMouseEvent`), unchanged.
-- `report` → passed through the reply guard first; whatever the guard does not own is forwarded to
-  the child (it may be the answer the child's own query is waiting for) but **without**
-  `clearPendingClick()` / `clearSelection()` / `scrollToBottom()`: it arrives without user intent.
-- the reply guard (#170/#194) keeps its drop/forward policy per segment: reports are *not* always
-  forwarded unchanged — complete protocol replies stay dropped as before, and colour replies are
-  forwarded whole by the guard itself.
-- `key` → the existing keyboard chain (`handleKeyInput`), semantics unchanged: typing still clears
-  the selection and jumps to the bottom.
-- `if (this.closed) return;` after each segment: `detach()` sets `closed` (`:461`, `close():1609`),
-  so a detach chord mid-read cannot make the loop act on a closed component. This is **new reachable
-  behaviour**: today `"\x1b[1;5D\x1b[I"` (detach chord + report in one read) matches no key as a
-  whole chunk and is merely forwarded; after the fix the first segment is an exact `Key.ctrl("left")`
-  hit → `detach()`. A9 pins it.
-
-The fullscreen path (`handleMouse`) and everything below `handleKeyInput` are untouched.
-
-### 3.3 Alternatives considered
-
-| Alternative | Verdict |
-|---|---|
-| Split only a **leading** mouse prefix (the issue's `splitMouseInputPrefix` sketch), forward the remainder through the keyboard path | Rejected: reproduced counter-example — a report *first* (`"\x1b[I\x1b[<0;16;2m"`) still loses the release (probe 1, case D). The split must be order-agnostic. |
-| Teach `parseMouseInputChunk` to skip non-mouse bytes | Rejected: breaks its pinned all-or-nothing contract (`test/pty-scroll.test.mjs:83-99`) and #188's acceptance, and leaves the keyboard path unable to tell a report from typing. |
-| Route reports into a new dedicated branch of the keyboard chain (check before `matchesKey`) instead of segmenting them | Rejected: reports and keys can share one read; a branch that runs once for the whole chunk cannot keep "report does not clear, key immediately after does" correct. |
-| Keep reports on the keyboard path but wrap `clearSelection`/`scrollToBottom` in a flag | Rejected: adds state to the component for a pure input-classification fact, and does not fix the dropped mouse events. |
-| Decode the report bytes ourselves / forward only known-good replies | Rejected: out of scope — the child owns reply semantics; forwarding is today's contract. |
-
-## 4. Data flow
-
-```
-outer terminal ── stdin ──▶ pi host TUI ──(focused component)──▶ PtyAttachComponent.handleInput(data)
-                                                                    │
-                                                    splitAttachInput(data)   ← new (pure, pty-scroll.mjs)
-                                                                    │
-        ┌───────────────────────────┬──────────────────────────────┴───────────────┐
-        ▼                           ▼                                             ▼
-   mouse segment                report segment                              key segment
-   handleMouseInputChunk        send({type:"input"}) (pass-through)         handleKeyInput (unchanged chain)
-   wheel / handleLocalMouseEvent  no selection or viewport change            clear selection + scroll to bottom
-        │                                                                          │
-        └───────────────▶ this.send({type:"input"}) ──▶ runner socket ──▶ child PTY
-```
-
-## 5. Behaviour matrix (before → after)
-
-| Read | before | after |
-|---|---|---|
-| pure mouse reports | mouse path | unchanged |
-| mouse + any non-mouse bytes (either order) | keyboard default: gesture dropped, selection cleared, viewport reset, whole read forwarded to the child | mouse run processed; non-mouse run dispatched by kind |
-| report-only read with a selection in progress / scrolled back | selection cleared, viewport snapped to bottom | forwarded; local state untouched |
-| report followed/preceded by a real key | whole read treated as typing | report forwarded, key handled as typing |
-| complete DA1/DA2/kitty/cell-size reply (issue #194 guard) | dropped by the guard | **unchanged**: the guard still owns complete protocol replies, now fed one segment at a time |
-| colour reply (OSC 4/10/11/12, 997 report) | forwarded whole by the guard | **unchanged** (the guard forwards it before the kind dispatch) |
-| reply head coalesced with keys (guard window) | guard could absorb the keys into its window | keys are a separate segment, so a head can never absorb them |
-| wheel coalesced with a report | wheel not applied, bytes leaked to the child | wheel scrolls locally; only the report is forwarded |
-| two keys in one read (`"\x1b[5~\x1b[6~"`) | neither recognised → both forwarded to the child | **unchanged**: adjacent key runs merge into one segment, so `matchesKey` still sees the concatenation (a key is only recognised when it is the whole read) |
-| key-only read | typing semantics | unchanged |
-| truncated/partial escape sequence | forwarded as input | unchanged (becomes `key`) |
-| fullscreen host mode | `handleMouse` owns mouse; focus reports consumed by `TuiAltScreen` | unchanged |
-
-## 6. Acceptance matrix
-
-| ID | 功能点 | 验收方式 | 具体验证 | 通过标准 |
-|----|--------|----------|----------|----------|
-| A1 | 分段决策 `splitAttachInput` 决策表（§3.1 表全部行，含两种顺序、合并同类（含 report\|key 邻接两行）、键段合并、截断序列、`""`） | 自动化验证（unit） | `node --test test/pty-scroll.test.mjs`（新增用例组） | 每行 `kind` 序列与 `data`/`events` 内容逐字匹配；`parseMouseInputChunk` 既有 3 条断言（`:83-99`）不变仍绿 |
-| A2 | 报告序列判定表（§3.1 七类正例 + 刻意排除的反例） | 自动化验证（unit，同一文件；只经 `splitAttachInput` 断言，不新增 test-only 导出） | `node --test test/pty-scroll.test.mjs` | ① 七类正例（含 BEL 与 ST 两种 OSC 终止符、`\x1b[?1;2c`、`\x1b[>0;95;0c`、`\x1b[?1u`、`\x1b[?997;1n`、`\x1b[6;24;80t`）每条 → 恰好一个 `{kind:"report"}` 且 `data` 逐字相等；② 反例 `\x1b[1;2R`（shift-F3）、`\x1b[97;5u`（kitty ctrl+a）、`\x1bP1+r…\x1b\\`（DCS）→ `{kind:"key"}`；③ 正例中的 `\x1b[>0;95;0c` 属 §3.1(b) 表第 3 行的防御性保留项，断言它仍为 report |
-| A3 | 本 issue 的确切复现：release 与 report 同 chunk（两种顺序，含 OSC 11 reply 变体） | 自动化验证（integration，组件级：真 runner socket + fake PTY + fake TUI 捕获 `terminal.write`） | 新增 `test-support/pty-attach-mixed-input-scenario.ts` + `test/pty-attach-mixed-input.test.mjs`（`node --experimental-transform-types`，模式同 `test/pty-attach-mouse.test.mjs`） | ① 恰好一次 OSC 52 `\x1b]52;c;<base64("fake pi ready")>\x07`；② socket 收到的 input 帧里**不含任何** `\x1b[<` 鼠标字节，report 字节本身仍在；③ 组件 selection 仍非 null（场景 harness 已是白盒 `(component as any)`，另记渲染行仍带 inverse 选中 SGR 作辅助信号） |
-| A4 | 纯 report 读取不碰选择：`"\x1b[I"`、`"\x1b]11;rgb:…\x07"` 在拖选中途到达 | 自动化验证（integration，同场景） | 同场景 case 组 | ① selection 保持非 null；② 无 OSC 52 写出；③ report 仍以 `{type:"input"}` 转发给子进程 |
-| A5 | 视口语义（需可滚动缓冲：fixture 的 `burst` 输入 → 200 行）：① 读回滚时 report 不跳底；② wheel+report 同 chunk 时 wheel 本地生效 | 自动化验证（integration，同场景） | 同场景 case 组；断言只用公开可见量：`render()` 首行可见的 `burstline-####` 编号（回滚后应为较旧的编号） | ① report 到过后首行编号不变（不是 `burstline-0200`）；② wheel+report 后首行编号比之前更旧（回滚 1 行），且转发的 input 帧只有 report |
-| A6 | 键盘语义不回归 + 分类边界：真键 `"x"` 仍清选择并跳底；`"\x1b[1;2R"`（shift-F3）、`"\x1b[97;5u"`（kitty ctrl+a）仍按键入处理 | 自动化验证（integration，同场景） | 同场景 case 组 | ① 真键后 selection 为 null 且该键被转发；② 两个歧义序列都走键入路径（清选择） |
-| A7 | 类型 / 构建 / 打包 | 自动化验证（static + build） | `npm run typecheck`；`npm run verify` | exit 0（含 perf gate、coverage 阈值 lines 85 / funcs 80 / branches 70、`pack:dry`） |
-| A8 | 既有行为不回归（#167 鼠标分发、#171 中键粘贴、#174 选中镜像、滚轮、attach e2e） | 自动化验证（integration，既有套件） | `npm run test:coverage`（`test/pty-scroll.test.mjs`、`test/pty-attach-mouse.test.mjs`、`test/pty-attach-wheel.test.mjs`、`test/pty-attach-selection-mirror.test.mjs`、`test/pty-attach-*.test.mjs`） | 既有测试全绿，覆盖率不低于阈值 |
-| A9 | mid-read detach 守卫（§3.2 的 `if (this.closed) return;`，本轮新识别的可达行为） | 自动化验证（integration，同 A3 场景） | 同场景 case：一次读入三段 `"\x1b[1;5D" + "\x1b[I" + "x"`（ctrl+← / focus report / 尾随 key；report 分隔必不可少——相邻键段会合并（A1），无分隔时 chord 与 key 并成一段键文本、chord 永不匹配） | ① `closed === true`；② 该读取的后续段未被处理（用尾随 key 段作探针，断言 selection 仍存在；无守卫时尾随 key 会 `clearSelection()` 而尾随 report 的 `send()` 只是静默 no-op、无法区分）；③ 无 throw、无渲染报错 |
-| U1 | 真机：常规模式下注入本 issue 的确切字节流（两种顺序） | 用户实测（可执行：本机有 tmux + xclip + `DISPLAY=:0`；缺 tmux 时标 `pending`） | **部署前置（必须先做）**：把被测 checkout 装进 pi——合并后首选 `git -C ~/.pi/agent/git/github.com/zhuxixi/pi-agent-board stash`（该 checkout 有本地 `package-lock.json` 改动）→ `git pull` → 重启 `pi --tui-mode regular`；合并前试点则按 README:62-75 开发自发现路径 `ln -s <worktree> ~/.pi/agent/extensions/agent-board`，并临时从 `~/.pi/agent/settings.json` 的 `packages` 移除 `git:github.com/zhuxixi/pi-agent-board`（避免同一扩展双加载），测后恢复。**然后**：① tmux 内跑 `pi --tui-mode regular` → `/agent-board` → attach 到任一 session；② 在**一次** `tmux send-keys -H` 里传入全部字节以合成一次读取：`1b 5b 3c 30 3b 31 3b 32 4d`（press）、`1b 5b 3c 33 32 3b 38 3b 32 4d`（move）、`1b 5b 3c 30 3b 31 36 3b 32 6d 1b 5b 49`（release+focus-in）；③ 观察高亮与剪贴板/PRIMARY（复用 `xclip -o -selection primary` 检查） | 高亮保留到下一次点击（#172 契约），选中文本进入剪贴板/PRIMARY，子 session 不出现鼠标字节回显；若 tmux 把字节拆成多帧（合成失败），如实记录分帧观察结果并把该行标 `pending`，A3 仍是主证据（步骤 ①②③ 中仅 ② 依赖 tmux） |
-| U2 | 真机（可选）：日常使用中混合读取不再清掉选中 | 用户实测（可选，非阻塞） | 常规模式 attach 内拖选，同时触发焦点切换/主题探测 | 选中与阅读位置不再被无意图的 report 打断；失败如实记录 |
-
-Notes:
-
-- A1–A2 are the lowest level that can prove the classification rules (pure, no TUI/socket). A3–A6
-  and A9 are the lowest level that can prove the *effects*, because the dispatch lives behind a private
-  handler with TUI + socket + xterm dependencies (§7). A8/A7 are the repo's definition of done.
-- A3 is the issue's own reproduction; A4/A5 cover the second half of the issue's suggested fix
-  (reports must not cancel an in-progress selection), A6 pins the fail-safe boundary (ambiguous
-  sequences stay keys).
-
-## 7. Testability split design (hard constraint for implementation)
-
-- **Pure core** (`src/core/pty-scroll.mjs`): `splitAttachInput` is the single new export; the run
-  readers and the report table stay module-private. No env reads, no I/O, no component import, no
-  use of `Date.now()`. A1/A2 call it directly; the only other export touched is
-  `parseMouseInputChunk`, whose behaviour must be literally unchanged (re-expressed on
-  `parseMouseRun`, contract re-pinned by the existing assertions).
-- **I/O shell** (`PtyAttachComponent`): owns the socket, the xterm model, selection state, the
-  pending-click timer and the viewport. The dispatch loop is the only new logic; `handleKeyInput` is
-  the old body moved verbatim (a pure refactor — no branch, guard or ordering may change inside it).
-  The report branch adds exactly one `send()` and no state.
-- **Test seam** (A3–A6): the public `handleInput` legacy seam + a fake `tui.terminal.write` capture +
-  a real runner socket with the fake PTY — the seams `test/pty-attach-mouse.test.mjs` and
-  `test/pty-attach-selection-mirror.test.mjs` already use. No test-only export, no injection hook,
-  no new env knob. The scenario is white-box by construction (it already casts the component to
-  `any` to reach `handleMouse`), so reading the private `selection` field to prove "the highlight
-  survived" is allowed there; the behavioural proofs (OSC 52 payload, socket frames) and the
-  viewport proof (rendered content) stay black-box and are the primary assertions.
-- **Fixtures**: `test-support/fake-pty-pi.mjs` default mode prints exactly one stable line
-  (`fake pi ready`) → the expected OSC 52 payload is deterministic; the `burst` input channel emits
-  200 numbered lines → the scrollable-viewport cases (A5) need no new fixture. A PATH-stubbed `xclip`
-  keeps the scenario off the host clipboard.
-- **Boundary to preserve**: "what is a report" lives in exactly one place (the report table in
-  `pty-scroll.mjs`). The component must not re-inline report or mouse detection; it only switches on
-  the segment kind.
-
-## 8. Boundaries, interactions, risks
-
-**Sibling issues (must not be pre-empted).** #187 edits the release branch of
-`handleLocalMouseEvent` and moves `sameMousePoint` into `pty-scroll.mjs`; #188 edits the X10 branch of
-`parseMouseEventPrefix` and extends the `parseMouseInputChunk` unit block. #189 touches neither
-function body: it adds new private helpers plus one export, and its component edits sit in
-`handleInput` (top of the class) — disjoint from #187's release branch. Whichever merges second
-rebases and re-runs `npm run verify`; with #187/#188 unfixed this issue's cases still pass because it
-does not rely on their fixes (X10-only terminals still lose the copy — documented as their scope).
-
-**Documented guarantee boundaries.**
-
-- Report-shaped bytes inside a bracketed paste are split out as a report run: the byte stream and its
-  order are preserved (the child sees the same bytes), and the only local difference is that the
-  pasted report-shaped text does not clear the selection. **Mouse-report-shaped bytes are different**
-  and are stated here honestly: a pasted `\x1b[<…M` run is consumed by the local mouse path and is
-  **not** forwarded to the child (today the whole pasted chunk was forwarded). Pasting a captured
-  terminal log that contains mouse reports can therefore create a local selection/click instead of
-  reaching the child — a documented consequence of segmenting, not a paste-content loss (nothing is
-  dropped from the byte stream for report runs; mouse runs are consumed by design, exactly as they
-  are when typed by the terminal).
-- A report or mouse sequence **split across two reads** is not recognised and is forwarded as typing
-  — exactly today's behaviour for partial sequences; the outer terminal writes complete sequences.
-- Unknown/unlisted reply forms (CPR `CSI … R`, DECRPM `CSI … $ y`, DCS replies) keep key semantics:
-  they still clear the selection as today. Adding a form later is one line in the report table.
-- Reports the reply guard (#170/#194) does not own are forwarded to the child, including while the
-  child has not reached raw/bracketed-paste readiness — that is today's behaviour and belongs to
-  #165/#180, not here. Complete protocol replies stay dropped by the guard, and colour replies are
-  forwarded whole by the guard; #189 does not change that policy, it only feeds it segments.
-- No clipboard claim: the copy path (OSC 52 + PRIMARY mirror) is unchanged.
-- No claim about fullscreen mode: `handleMouse`/pi-tui still own that path.
-
-**Risks.**
-
-| Risk | Assessment / mitigation |
-|---|---|
-| The classifier misses a real report → selection still cleared | Fail-safe direction: the child still receives the bytes; the local state difference is a highlight/viewport artefact. A2 pins the excluded forms explicitly, and the table is documented as the extension point. |
-| The classifier swallows a key → selection no longer clears on typing | Patterns are grounded in queries this stack issues; A2/A6 pin `\x1b[1;2R`, `\x1b[97;5u`, `\x1bP…` as keys. |
-| `handleKeyInput` extraction changes keyboard behaviour | Pure move; A8 + `npm run verify` (the prototype already ran 1161 tests green on the patched tree — `research/03-fix-hypothesis-validated.md`). |
-| Extra per-read work (segment scanner) on large pastes | Only ESC positions are probed: one `parseMouseEventPrefix` (single regex) plus the report table (≤7 regexes, all anchored) per ESC, and one linear `indexOf` per key run. |
-| Shared file conflicts with #187/#188 | Disjoint functions; whichever lands second rebases and re-runs `npm run verify`. |
-| A5's viewport assertion touches component internals | Observed through the public `render()` output (the `burstline-####`编号 of the first visible body line); no private API is added or changed, and the private `selection` read (A3) is a white-box convenience with the OSC 52 payload as the primary evidence. |
-
-## 9. Deliverables
-
-- `src/core/pty-scroll.mjs`: `parseMouseRun` (private) + `parseMouseInputChunk` re-expressed on it;
-  report table + `parseReportPrefix` / `parseReportRun` / `pushSegment` (private); `splitAttachInput`
-  (new export + JSDoc typedef).
-- `src/ui/pty-attach.ts`: import `splitAttachInput` (dropping `parseMouseInputChunk`); `handleInput`
-  becomes the dispatch loop; keyboard chain moved into private `handleKeyInput`.
-- `test/pty-scroll.test.mjs`: segmentation + report-classification cases (A1, A2).
-- `test-support/pty-attach-mixed-input-scenario.ts` + `test/pty-attach-mixed-input.test.mjs`:
-  component-level cases (A3–A6, A9), including the `burst`-based viewport cases.
-- `docs/superpowers/specs/2026-10-14-issue-189-mixed-input-segments-design.md`: this spec, first
-  commit in the worktree (step 5).
-- CHANGELOG entry via the release tooling at release time (not in this PR).
-
-## 10. Open question for the design gate
-
-The report pass-through is the second half of the issue's own suggested fix and is reproduced as a
-real symptom (selection cleared + reading position lost). If the operator prefers a smaller blast
-radius, the dispatch loop alone still fixes the *copy* (the mouse run is processed), and the report
-rows can be trimmed to fewer forms (A2/A4/A5 shrink accordingly) — but then the remaining forms
-still wipe the just-created highlight and snap the viewport, which is exactly the second symptom of
-this issue.

package/docs/superpowers/specs/2026-10-15-issue-188-x10-mouse-release-design.md

@@ -1,252 +0,0 @@
-# Issue #188 — X10 mouse release (`Cb=3`) parsed as press: selection cleared, never copied
-
-- Issue: https://github.com/zhuxixi/pi-agent-board/issues/188
-- Kind: bug — root-cause report + fix design
-- Repo: `zhuxixi/pi-agent-board` · baseline `main` @ `2148360` (drafted and cross-reviewed against `f81949d`; rebases are citation-only) · worktree `issue-188-x10-release`
-- Drafted: deepseek/deepseek-flash (selected) · deepseek/deepseek-flash (physical) @ 2026-10-14T12:34:15Z
-- Revised: deepseek/deepseek-flash (selected) · deepseek/deepseek-flash (physical) @ 2026-10-14T12:52:00Z — after round-1 review (R1-G1/R1-G2/R1-D1 accepted; findings in `research/spec-review-round-1.md`)
-- Revised: deepseek/deepseek-flash (selected) · deepseek/deepseek-flash (physical) @ 2026-10-14T13:03:00Z — after round-2 review (R2-D1 accepted; 0 real gaps, converged; findings in `research/spec-review-round-2.md`)
-- Revised: deepseek/deepseek-flash (selected) · deepseek/deepseek-flash (physical) @ 2026-10-15T00:00:00Z — rebased onto `main` @ `7cf0853` (#190/#191 merged): line citations moved (+4 from `handleInput`, +25 from `handleMouseInputChunk`, osc52 +42); no design or boundary change, the X10 branch and the legacy handler are byte-identical to `f81949d`
-- Revised: deepseek/deepseek-flash (selected) · deepseek/deepseek-flash (physical) @ 2026-10-16T12:35:00Z — rebased onto `main` @ `074123c`, where the two sibling issues landed (#189 @ `8a5966e`, #187 @ `074123c`). §6.2/§8 updated with the realised interactions: the X10 release now reaches #187's geometry-based drag decision (so a motion-less X10 gesture also copies — #187's acceptance, not asserted here), and #189 kept `parseMouseInputChunk`'s all-or-nothing contract (the 7-byte row still holds; `splitAttachInput` owns mixed reads). One both-added-tests conflict in `test/pty-scroll.test.mjs` was resolved by keeping both sides.
-- Research: `research/01-root-cause-and-reachability.md` (root cause, reachability, fix validation)
-- Route: bug → `systematic-debugging` (Phase 1 root cause + live repro done in `research/`; this document is the design)
-
-## 1. Problem
-
-In the legacy (regular-TUI) mouse path, an X10/normal-encoded release — `Cb = 3` — is decoded as
-`action: "press"`. `handleLocalMouseEvent` then takes its non-primary press branch and clears the
-pending click and the selection, so the real release branch (the one that calls
-`copySelectionToClipboard()`) never runs: on a terminal that speaks only X10 the user drags, sees the
-highlight, and loses it the instant the button comes up — nothing is copied.
-
-Affected scope is narrow but real: X10 bytes reach the parser only from terminals that ignore the
-`?1006` SGR request while still reporting `?1000`/`?1002` mouse events (`MOUSE_ENABLE`,
-`src/ui/pty-attach.ts:45`), and only in regular TUI mode (in fullscreen, pi-tui's `TuiAltScreen`
-consumes raw mouse input and its own parser accepts SGR only). The defect is latent, not a
-regression: the X10 branch has been unchanged since it was introduced in `b1ee950`
-(2026-06-01).
-
-## 2. Root cause (evidence in `research/01-root-cause-and-reachability.md`)
-
-X10/normal encoding is `ESC [ M Cb Cx Cy`, one byte per field, each byte = value + 32. Per xterm
-ctlseqs, for the low two bits of `Cb`: `0 = MB1 pressed, 1 = MB2 pressed, 2 = MB3 pressed,
-3 = release` — release is a *button code*, not a bit, and it carries no button identity. Bits 2–4
-are shift/meta/ctrl, bit 5 (`32`) is motion, bit 6 (`64`) is wheel (wheel releases are never
-reported).
-
-`parseMouseEventPrefix` (`src/core/pty-scroll.mjs:53-66`) maps every X10 event that lacks the motion
-bit to `"press"`. A `Cb = 3` event therefore enters `handleLocalMouseEvent`
-(`src/ui/pty-attach.ts:1033`) with `button = 3`: `primary = (3 & 3) === 0` is `false`,
-`middleButton` is `false`, so the press branch runs `!primary` → `clearPendingClick()` +
-`clearSelection()` (`:1047-1051`).
-
-Live component-level repro on `f81949d` (real `PtyAttachComponent` + real runner socket + fake PTY,
-OSC 52 observed on `tui.terminal.write`): canonical SGR press → move → release copies
-(`osc52 = ["fake pi ready"]`); the same gesture encoded as X10 emits **no** OSC 52 and the selection
-is `null` synchronously at the release.
-
-## 3. Fix design
-
-### 3.1 Classification contract for the X10 branch (`parseMouseEventPrefix`)
-
-| `Cb` bits | `Cb` example | `action` |
-|---|---|---|
-| `(button & 96) === 0` and `(button & 3) === 3` | 3, 7 (shift), 19 (ctrl) | `"release"` |
-| `button & 32` (motion), not the above | 32, 35, 64\|32… | `"move"` |
-| otherwise | 0, 1, 2, 64, 65 | `"press"` |
-
-Bit 6 (`64`) is excluded from the release rule: wheel events (`64`/`65`, with or without modifiers)
-keep the `"press"` classification that the wheel path reads. Bit 5 (`32`) is excluded as well, so
-"motion with no button" (`35`) stays `"move"`. Modifier bits 4/8/16 leave `button & 3 === 3` intact,
-so a modifier-carrying release is still a release. The SGR branch (`M`/`m` suffix) and the passive
-branch are unchanged — see §6.
-
-Byte literals used from here on follow that encoding: `ESC [ M` + `chr(Cb + 32)` + `chr(col + 32)` +
-`chr(row + 32)`, six bytes total. Worked examples for body row 0 (= terminal row 2, `chr(34) = "`):
-press at col 1 = `\x1b[M !"`, motion at col 8 = `\x1b[M@("` (`"(" = 40 = 8 + 32`), release at col 20 =
-`\x1b[M#4"` (`"4" = 52 = 20 + 32`). A release report is therefore exactly six bytes — a seven-byte
-string is not an X10 report and `parseMouseInputChunk` rejects the whole chunk (all-or-nothing, §6.2).
-
-Intended implementation shape (behaviour above is normative; the exact shape may be adjusted in the
-plan as long as the decision table holds):
-
-```js
-	// X10/normal mouse: ESC [ M Cb Cx Cy. Cb is encoded as button + 32.
-	if (input.startsWith("\x1b[M") && input.length >= 6) {
-		// Cb packs the button (bits 0-1), modifiers (2-4), motion (5) and wheel (6).
-		// Bit value 3 in bits 0-1 is the protocol's release code: it carries no
-		// button identity, so treating it as a press cleared the drag selection on
-		// release instead of copying it (issue #188).
-		const button = input.charCodeAt(3) - 32;
-		const motion = (button & 32) !== 0;
-		const wheel = (button & 64) !== 0;
-		const release = !motion && !wheel && (button & 3) === 3;
-		return {
-			length: 6,
-			raw: input.slice(0, 6),
-			mouse: {
-				encoding: "x10",
-				button,
-				col: input.charCodeAt(4) - 32,
-				row: input.charCodeAt(5) - 32,
-				action: release ? "release" : motion ? "move" : "press",
-			},
-		};
-	}
-```
-
-### 3.2 Why the parser layer, not the handler
-
-`mouse.action` has exactly three consumers, all in `handleLocalMouseEvent`
-(`src/ui/pty-attach.ts:1036`, `:1065`, `:1075`), and the SGR branch already expresses release
-through this same field. Classifying in the parser keeps one source of truth for "what did the
-terminal report", leaves the handler's protocol-agnostic branches untouched, and keeps the decision
-inside a pure function (see §7). A handler-side patch (e.g. treating `button === 3` presses as
-releases) is rejected: it would make the same fact true in two places and would misfire on the SGR
-path, where `button` is carried on release with its real identity.
-
-### 3.3 Alternatives considered
-
-| Alternative | Verdict |
-|---|---|
-| Classify in the parser with the bit test above (chosen) | One edit site, pure, testable at the existing unit seam |
-| Detect release in `handleLocalMouseEvent` by `mouse.button === 3` | Rejected: duplicates truth, misfires for SGR releases that carry `button = 0/1/2`, and hides the protocol fact from the parser's unit tests |
-| Infer "release" from a stateful "a press is pending" flag in the component | Rejected: adds state to fix a stateless decoding bug; a lost press (e.g. mixed-chunk drop, #189) would invert the mapping |
-| Treat any non-primary press as a release | Rejected: right/middle presses are real events and must keep clearing/acting as they do today |
-
-## 4. Data flow
-
-`outer terminal → pi input pipeline → PtyAttachComponent.handleInput(data)` (`:301`) →
-`parseMouseInputChunk` (`src/core/pty-scroll.mjs:84`) → `parseMouseEventPrefix` per report →
-`{ raw, mouse }` → `handleMouseInputChunk` (`:981`) → wheel branch by `button & 64` **or**
-`handleLocalMouseEvent` by `action`. The fix changes only the `action` value produced for `Cb = 3`;
-everything downstream is unchanged.
-
-## 5. Acceptance matrix
-
-| ID | Functional point | Verification | Concrete check | Pass criterion |
-|---|---|---|---|---|
-| A1 | X10 press / motion / release / modifier-release classification | automated — **unit** | extend `test/pty-scroll.test.mjs` `parseMouseEvent` cases: `\x1b[M !"` → press, `\x1b[M@!"` → move, `\x1b[M#!"` → release, `\x1b[M'!"` (7 = shift+release) → release, `\x1b[M3!"` (19 = ctrl+release) → release; run `node --test test/pty-scroll.test.mjs` | every case decodes `button`, `col`, `row` and the `action` from §3.1 |
-| A2 | Failure and unchanged branches do not shift | automated — **unit** | same file: X10 wheel `\x1b[M\`!"` (64) and `\x1b[Ma!"` (65) → press and `mouseWheelDirection` still +1/−1; middle button `\x1b[M!!"` (1) → press, button 1 (backs §6.1's middle-press claim: the component path it feeds — `middleButton` → `pastePrimarySelection` — is already driven SGR-encoded by `test/pty-attach-mouse.test.mjs`, so classification is the only X10-specific link); motion-with-button-3 `\x1b[MC!"` (35) → move; right button `\x1b[M"!"` (2) → press; `parseMouseEvent("x")` → null; passive `\x1b[?32;7;8M` → move and `\x1b[?0;7;8m` → release; run `node --test test/pty-scroll.test.mjs` | values identical to `f81949d` except the intended release rows |
-| A3 | Multi-report X10 chunk decodes in order | automated — **unit** | same file: `parseMouseInputChunk` over the concatenation of three X10 reports — press col 1 row 2 `\x1b[M !"`, motion col 8 row 2 `\x1b[M@("`, release col 20 row 2 `\x1b[M#4"` (byte rule in §3.1) | 3 entries with exact `raw` slices and `action` = press / move / release |
-| A4 | X10 drag release copies the selection | automated — **component E2E** | new `test-support/pty-attach-x10-scenario.ts` (real `PtyAttachComponent` + real runner socket + fake PTY, modelled on `test-support/pty-attach-mouse-scenario.ts`) driven by new `test/pty-attach-x10.test.mjs` via `node --experimental-transform-types`; feed the same three reports as A3 (`\x1b[M !"` → `\x1b[M@("` → `\x1b[M#4"`) through `handleInput`, waiting for the fixture line to render first | exactly one OSC 52 (`\x1b]52;c;<base64>\x07`) write, whose payload is the selected line text (`fake pi ready`) |
-| A5 | Non-drag branches keep today's behaviour | automated — **component E2E** | same harness: same-point X10 click (`\x1b[M !"` → `\x1b[M#!"`), X10 right press + release (`\x1b[M"!"` → `\x1b[M#!"`), X10 wheel (`\x1b[M\`!"`) with a viewport that cannot scroll | click and right-button gestures emit **no** OSC 52; the click's 1-cell highlight is gone after the pending-click window; the wheel sequence is forwarded to the child as `{type:"input"}` and the process stays alive |
-| A6 | No regression across the repo, build integrity | automated — **static + full suite** | `npm run verify` (`package.json`) | exit code 0 (typecheck, perf gate, `node --test test/*.test.mjs`, coverage thresholds, `pack:dry`) |
-| U1 | Real-world X10-only terminal behaviour | manual — **optional, non-blocking** | see §6.3 | drag in the attach view of a terminal that reports X10 copies on release; recorded as `pending` unless executed |
-
-Notes on the matrix:
-
-- A1–A3 are the lowest-cost level that can prove the decoding rule; A4/A5 are the lowest level that
-  can prove the *effect* (copy on release), because the effect lives behind a private handler with
-  TUI + socket + xterm dependencies (see §7).
-- A4 asserts the copy effect only. Highlight persistence after a copy is today's behaviour and the
-  subject of the open bug #172, so #188 neither pins it nor changes it (see §6.2).
-- Failure branches are covered by A2 (unrecognised input → `null`, unchanged classifications) and A5
-  (click / right button / wheel).
-- A6 is the repo's definition of done (`AGENTS.md`); it is not a substitute for A4/A5, which pin the
-  new behaviour.
-
-## 6. Boundaries and non-goals
-
-### 6.1 Explicitly not changed
-
-- **Wheel** (`Cb` with bit 6), including wheel-with-modifier: classification stays `"press"`, which
-  is what the wheel branch (`button & 64`) and `mouseWheelDirection` read.
-- **Click semantics**: same-point press + release still schedules the pending click and clears the
-  1-cell highlight after `DOUBLE_CLICK_MS` (260 ms) — the release branch's `shouldCopy === false`
-  path is untouched.
-- **Middle press** (PRIMARY paste) and **right press** (selection clear) keep their behaviour; a
-  right release (`Cb = 3` after `Cb = 2`) now reaches the release branch, which, with no selection,
-  returns at `:1064` (`if (!this.selection) return;`) — same observable result as before (nothing
-  copied), verified by A5.
-- **SGR and passive branches.** SGR releases are already marked by the `m` suffix. The passive form
-  (`CSI ? … M/m`, contour-terminal passive mouse tracking, `CSI ? 2029 h`) marks release with the
-  lowercase `m` as well and a passive terminal "will ONLY allow SGR transport mode", so the X10
-  button-code rule does not apply there — A2 pins that the passive rows are unchanged.
-- **Fullscreen path** (`handleMouse`, pi-tui `TuiAltScreen`): untouched. pi-tui parses SGR only, so
-  X10 non-wheel reports are dropped upstream in that mode; that is an upstream limitation, not this
-  issue.
-- **Cutting back the X10 branch, or adding 1005/1015 encodings**: no.
-
-### 6.2 Interaction with sibling issues (must not be pre-empted)
-
-- **#187 (motion-less drags) — landed on `main` @ `074123c` while this PR was in flight.** The
-  release branch now decides "was this a drag?" by screen geometry (`selectionReleaseIsDrag`) instead
-  of the move flag alone. #188 still owns only the decoding of `Cb = 3`; the geometry rule stays
-  #187's. Interaction as landed: an X10 gesture *with* motion copies (A4), a same-point X10 release is
-  still a click (A5), and an X10 gesture *without* motion events now also copies — that last row is
-  #187's acceptance, not #188's, and is deliberately not asserted here. #188's acceptance never
-  depended on #187 landing.
-- **#172 (highlight survives a copy-on-release)** is an open bug asking to *clear* the selection in
-  the very `shouldCopy` branch this issue exercises. Retention is
-today's behaviour, not a contract; #188 must not add an assertion that pins it and must not add the
-  clearing either — that call belongs to #172. A4 therefore asserts the copy effect only. Whichever
-  of the two merges second rebases and re-runs A6.
-- **#189 (mixed chunks) — landed on `main` @ `8a5966e` while this PR was in flight.** It kept
-  `parseMouseInputChunk`'s all-or-nothing contract (verified after the rebase: the 7-byte chunk still
-  returns `null`) and added `splitAttachInput` for mixed reads, so A3's assertion is unchanged and the
-  component scenario's pure-mouse reports keep taking the same path. A4's three reports are exactly
-  six bytes each for this reason.
-
-### 6.3 Guarantee boundary and the manual item U1
-
-- **No release, no copy**: terminals in X10 *compatibility* mode (`?9`, press-only reports) never
-  send a release, so nothing changes for them; xterm encodes MB3 presses there as `Cb = 2`
-  ("`Cb` is button−1"), so the new release rule cannot capture a real press.
-- The mapping in §3.1 is the protocol definition, not a heuristic: xterm ctlseqs states the low two
-  bits are `0 = MB1 pressed, 1 = MB2 pressed, 2 = MB3 pressed, 3 = release`.
-- **U1 (optional, non-blocking, expected status `pending`)**: the operator has no X10-only terminal,
-  so the real-terminal check cannot gate this change. Recipe if it is ever run: start the board
-  (`pi`) inside a PTY wrapper that strips `\x1b[?1006h` from the byte stream on its way to the real
-  terminal (so the terminal falls back to the X10/normal encoding while the board still reports
-  `?1000`/`?1002`), then drag-select in an attach view and paste. Prerequisites: (a) the wrapper
-  (about 30 lines using the repo's `node-pty` dependency), a terminal that accepts `?1000`/`?1002`,
-  regular TUI mode (`tuiMode: "regular"`), and a session with selectable text; (b) the code under
-  test — point the dev symlink at the #188 worktree (`ln -s "$(pwd)" ~/.pi/agent/extensions/agent-board`,
-  `README.md:68`) or run U1 after the merge on a release that contains it, otherwise the run validates
-  whatever checkout the symlink already points at. Observation: on release the OSC 52 copy lands in
-  the clipboard (this is the acceptance); whether the highlight then stays is today's behaviour and an
-  open bug (#172), so it is not an acceptance criterion here. Failing an execution window, the
-  component-level E2E (A4/A5) drives the exact byte stream through the real component and socket, and
-  is the strongest evidence available.
-
-### 6.4 Rollback
-
-Single-commit revert of the parser change; no persisted state, no config, no env flag, no migration.
-Reverting restores today's (broken) X10 release classification and changes nothing else.
-
-## 7. Testability split design
-
-- **Pure decision layer (must stay pure)**: the rule lives inside `parseMouseEventPrefix`
-  (`src/core/pty-scroll.mjs:31`), reachable through the already-exported pure functions
-  `parseMouseEvent(data)` and `parseMouseInputChunk(data)`. A1–A3 drive those directly: no I/O, no
-  TUI, no socket. The implementation must not move the classification out of the parser (no new
-  export, no new helper needed, no new env flag or config key).
-- **Effect layer (private, covered at the component seam)**: `handleLocalMouseEvent`
-  (`src/ui/pty-attach.ts:1033`) is private and depends on the TUI, the runner socket and the inner
-  xterm instance; it is not unit-testable and gets no new seam. A4/A5 cover it through the public
-  `handleInput(data)` entry point with observable effects only: OSC 52 written to
-  `tui.terminal.write`, `{type:"input"}` frames written to the socket, and `render()` output.
-  Selection *state* is deliberately not asserted through private fields, and A4 asserts the copy
-  (OSC 52 payload) rather than the highlight's fate — its persistence is #172's contested subject
-  (§6.2). In A5, "the click's highlight is gone" is observed through the pending-click window
-  (`DOUBLE_CLICK_MS = 260`, `src/ui/pty-attach.ts:48`) plus the absence of a copy.
-- **Test boundary**: parser classification (A1–A3) / component reaction (A4–A5). The split mirrors
-  the existing pair `test/pty-scroll.test.mjs` (pure) + `test-support/pty-attach-mouse-scenario.ts`
-  with `test/pty-attach-mouse.test.mjs` (component, `node --experimental-transform-types` scenario
-  printing one JSON line consumed by the test). Naming follows those files
-  (`test-support/pty-attach-x10-scenario.ts`, `test/pty-attach-x10.test.mjs`).
-- **Fixture realism**: the scenario reuses `test-support/fake-pty-pi.mjs` (default mode prints
-  `fake pi ready`, stable, one body line) and a PATH-stubbed `xclip` so `writePrimarySelection()`
-  never touches the host clipboard.
-
-## 8. Risks
-
-| Risk | Assessment / mitigation |
-|---|---|
-| Misclassifying a real press as release | `Cb = 3` is defined as release by xterm; X10 compatibility mode encodes MB3 presses as 2 and sends no releases. A2 pins right-button press. |
-| Wheel regression | The release rule excludes bit 6; A2 pins both wheel directions and `mouseWheelDirection`. |
-| Changing shared files (`src/core/pty-scroll.mjs`, `test/pty-scroll.test.mjs`) while #187/#189 were in flight | Realised: both landed first (#189 @ `8a5966e`, #187 @ `074123c`). Rebase resolved one both-added-tests conflict in `test/pty-scroll.test.mjs`; the parser change auto-merged cleanly and `parseMouseInputChunk`'s contract survived #189. A6 re-run on the rebased head. |
-| A4's OSC 52 payload depends on the fixture line | The harness waits for the fixture line to render before the gesture (same pattern as the existing mouse scenario) and asserts the exact payload string. |
-| #172 lands and clears the selection in the copy branch | A4 carries no retention clause, so #172 does not invalidate it; only the rebase (same file, `src/ui/pty-attach.ts` release branch region) and a re-run of A6 are needed. |
-| Coverage thresholds (`npm run verify`) | New pure branches are exercised by A1/A2; the scenario adds one integration test. If coverage dips, the parser cases (not the assertions) are extended. |