@huseynsnmz/pi-board 0.15.3 → 0.16.0

package/docs/superpowers/specs/2026-10-06-attach-settle-scheme-delivery-design.md

@@ -1,196 +0,0 @@
-# Spec: 修复 attach 落定的亮暗交付（issue #161）
-
-Drafted: zai-coding-cn/glm-5.3 (selected) · zai-coding-cn/glm-5.3 (physical) @ 2026-10-04T23:59:27+08:00
-Revised: zai-coding-cn/glm-5.3 (selected) · zai-coding-cn/glm-5.3 (physical) @ 2026-10-05T23:16:10+08:00
-Revised: zai-coding-cn/glm-5.3 (selected) · zai-coding-cn/glm-5.3 (physical) @ 2026-10-06T22:29:11+08:00
-
-> 状态：v3（第 2 轮复核收敛：真缺口 0，细化 R2-D1~D3 已处置）——⏸ 等待用户确认设计，确认后进步 5（worktree）。
-> 依据：issue #161 正文 + 三轮调研（`research/root-cause-probe-api-rename.md`、
-> `research/fix-surface-api-availability.md`、`research/observability-hook-points.md`）。
-
-## 1. 根因（已证实）
-
-**落定探测调用的 pi-tui 方法在 pi ≥ 0.99 已改名，调用抛 `TypeError` 被 `catch {}` 吞掉，
-probe 从未执行——settle 时刻的亮暗交付在 pi ≥ 0.99 上恒为 no-op。**
-
-证据链：
-
-1. `src/ui/pty-attach.ts:664`（origin/main，#165 后）调用
-   `this.tui.queryTerminalBackgroundColor({ timeoutMs })`；665-667 行 `catch {}` 静默。
-2. pi-tui 版本考古（npm tarball `tui.d.ts` 核对）：0.79.8 / 0.87.1 仅有旧名；
-   0.99.0 / 0.99.2 / 1.0.0 / 1.0.2 仅有 `queryTerminalColors`。改名点 = 0.87.1 → 0.99.0。
-3. `pi-coding-agent@0.99.2` 依赖 pi-tui ^0.99.2 → 事发环境（2026-10-01，pi 0.99.2）已改名，
-   probe 当时即 no-op；当前本机 pi 1.0.2 亦然。
-4. CI 绿的原因：repo devDeps 钉 0.79.8（旧名在，typecheck 过），测试 fake 只带旧名；
-   运行时扩展副本 node_modules/@earendil-works 为空，peer 依赖由宿主 pi 解析（仅新名）
-   → 开发面与运行面漂移。
-5. 排除备选：settle 未触发 / 发送链路断——#165 修的回声残渣证明 settle 钩子在跑；
-   「应答被僵尸条目吃掉」是旧实现的失败模式，且根本走不到那一步（调用即抛）。
-6. （复核补强）扩展组件拿到的 tui 是 `createInteractiveTuiReference` 返回的透明 Proxy
-   （pi 1.0.2 tui-renderer.js:37-66，get/set/has 全量转发底层 TuiBase）→ 旧名经
-   `Reflect.get` 得 undefined、调用即 TypeError（与根因自洽）；新名 `queryTerminalColors`
-   真实存在且可调（TuiBase 实现，tui.js:1056）——修复假设实现级成立。
-
-**#165 合并后的现状**：settle 交付只剩 probe 一条路（D3 已删；D2 桥只转发宿主消费到的
-scheme 事件，救不了落定即错的子 pi）→ 任何「子 pi spawn 时拿不到真实亮暗」的 attach 必现
-恒 dark，直到外部 997 推送。比 issue 提交时更严重（当时 D3 至少还会发裸查询）。
-
-## 2. 修复设计
-
-### 2.1 决策表
-
-| 决策点 | 选择 | 理由 | 被拒备选 |
-|---|---|---|---|
-| 探测 API | feature-detect：优先 `queryTerminalColors`（新），回退 `queryTerminalBackgroundColor`（旧），皆无则不发探测 | peerDependencies 为 `*`，须同时覆盖新旧宿主；#165 后 settle 只剩这条路 | 只用新名（砍掉 ≤0.87 宿主）；维持旧名（= 现状，坏的） |
-| 迟到应答 | 新 API 传 `onLateReply`；到达时若组件未 closed **且 scheme 不同于已发送值**才补发一次 997；相同则跳过 | 上游已把迟到应答导向回调（tui.js:1064-1068）；997 幂等但重复发送是诊断噪音、违背 #148「一次探测」克制精神 | 忽略迟到（慢链路首拍仍 dark）；无去重（每次 attach 可能发两条相同 997） |
-| 「读已解析状态」 | 不做 | 扩展面 TUI 接口无同步 getter（1.0.2 tui.d.ts 无 getTerminalTheme 暴露）；宿主进程直连真实终端、队列干净、WezTerm 毫秒级答 OSC 11，一次查询等价可靠 | issue 方向 2 原案（无 API 可用） |
-| scheme 事件缓存重发 | 本期不做 | scheme 事件只在外部推送时触发；board 重启场景宿主是新进程、缓存必空，边际价值低 | 记为后续可选加固（开放问题 2） |
-| 可观测性 | 组件 `onDiagnostic` 发 **DiagnosticEvent 兼容 patch**（code/source/level/message/details），两处构造点 wiring 直传 `appendDiagnostic(root, viewId, patch)` | `normalizeDiagnostic` 只保留 level/code/runId/source/message/details 白名单，其余字段会被丢弃——事件必须在源头就按既有 schema 构造 | 组件直写文件（层穿透、难单测）；自定义字段名（会被白名单丢弃，R1-G1） |
-| devDeps 0.79.8 → 1.0.x | 本期不做 | 全量类型面迁移，独立 PR；本期用 feature-detect + 本地结构类型 + 局部 cast | 混入会放大回归面 |
-| kill switch | 保留 `AGENT_BOARD_FORWARD_TERMINAL_QUERIES=0` | 既有回退语义（probe + D2 桥同关） | — |
-
-### 2.2 数据流（settle 时刻）
-
-```
-finishAttachTransition（现有，不变）
- └─ probeAndReportRealTerminalColorScheme（重写编排）
-     ├─ resolveProbeApi(this.tui)                      [新纯函数，terminal-query-sequences.mjs]
-     │    api=colors    → tui.queryTerminalColors({timeoutMs, onLateReply})
-     │                    → colors.background → RgbColor
-     │    api=background→ tui.queryTerminalBackgroundColor({timeoutMs}) → RgbColor
-     │    api=none      → 仅诊断事件，不发探测
-     ├─ colorSchemeForBackgroundRgb(rgb)               [现有纯函数，不动]
-     ├─ toColorSchemeReport(scheme)                    [现有纯函数，不动]
-     ├─ this.send({type:"input", data:997…})           [现有通道，不动]
-     └─ onDiagnostic(DiagnosticEvent 兼容 patch)       [新回调，缺省 no-op]
-onLateReply(colors) →
-    closed                            → 不发送，记 outcome=dropped_closed
-    scheme 与已发送值相同             → 不发送，记 outcome=duplicate_skipped
-    否则                              → 补发一次 997，记 outcome=reported + late:true
-```
-
-### 2.3 组件契约与改动面
-
-- `src/core/terminal-query-sequences.mjs`（落点钉死，与 `colorSchemeForBackgroundRgb` 同域）：
-  - `resolveProbeApi(tuiLike) → {api:"colors"|"background"|"none", invoke(tuiLike, timeoutMs, onLateReply?) → Promise<RgbColor|undefined>}`
-    —— 纯检测 + 适配器，输入输出 plain object，零副作用。
-  - `backgroundRgbFromTerminalColors(colors) → RgbColor|undefined`——纯映射。
-  - **编译期类型约束**：本仓编译面是 pi-tui 0.79.8，没有 `TerminalColors` 类型也没有
-    `queryTerminalColors` 方法 → 上述两个函数使用**本地定义的最小结构类型**
-    （如 `interface TerminalColorsLike { background?: RgbColor }`），**禁止
-    `import type { TerminalColors }` 自 pi-tui**；`typeof` 检测与必要的 cast 封装在
-    `invoke` 内部，不外溢到编排层。
-- `src/ui/pty-attach.ts`：
-  - `PtyAttachOptions`（pty-attach.ts:24，实名）增加可选
-    `onDiagnostic?: (event: AttachSettleDiagnosticPatch) => void`（缺省 no-op）。
-  - `probeAndReportRealTerminalColorScheme` 重写为上述编排；每步失败写诊断后静默返回
-    （保持 #148 的 best-effort 语义，但可观测）。
-- **两处构造点都要注入**（当前为同构重复的两个 `openPtyAttach`，是否去重由 plan 决定，
-  去重本身非目标）：
-  - `src/commands/attach-flow.ts:33-37`（export 的 `openPtyAttach`，供 `attach()` /
-    键盘回退路径）；
-  - `src/commands/agent-board.ts:226-251`（私有 `openPtyAttach`，供 dashboard attach
-    动作，构造在 238-240 行）。
-  两处工厂闭包均持有 `root` 与 `viewId`，把 `onDiagnostic` 接到
-  `appendDiagnostic(root, viewId, patch)`（与现有 `screenLogPath(root, viewId)` 同源）。
-- **诊断事件契约（映射到既有 `DiagnosticEvent` schema，字段名必须落在
-  `normalizeDiagnostic` 白名单内，否则会被静默丢弃）**：
-  - `code: "attach_settle_scheme"`（snake_case，对齐 `host_crashed` /
-    `host_crash_owner_changed` 等现有 code 命名）
-  - `source: "attach"`
-  - `level`: **「预期交付但失败」才 `"warn"`**——`timeout` / `error` / `no_background` /
-    `no_probe_api` / `dropped_disconnected`；正常/预期操作用 `"info"`——`reported` / `duplicate_skipped` /
-    `dropped_closed` / `suppressed`（后三者是慢链路正常去重、用户快速 detach、用户主动
-    kill switch；标 warn 会污染 `summarizeDiagnostics` 的 warningCount——diagnostics.mjs:60
-    计数、store.mjs:425 并入行摘要被 dashboard 消费）
-  - `message`: 人类可读摘要（如 `attach settle scheme reported via queryTerminalColors (light)`）
-  - `details: { probeApi: "colors"|"background"|"none", outcome:
-    "reported"|"timeout"|"error"|"no_background"|"no_probe_api"|"dropped_closed"|
-    "dropped_disconnected"|"duplicate_skipped"|"suppressed", report?: "997;1"|"997;2", late?: true }`
-    （camelCase，对齐既有 details 键风格如 `ownerChanged`；`report` 仅在发送 997 时携带；
-    kill switch 的 suppressed 事件不填 `probeApi`）
-  - 组件的 `onDiagnostic` 即以上述 patch 形状发出，wiring 层直接透传给
-    `appendDiagnostic(root, viewId, patch)`，不做二次映射。
-  - **outcome 判定规则（实现与 A9 的对齐依据）**：
-    (a) `timeout` 与 `no_background` 的区分——api=colors 时，返回对象**任一字段**
-    （foreground / background / palette 任一项）有值但 `background` 缺失 →
-    `no_background`（终端应答了但没答 OSC 11）；返回对象**完全为空** → `timeout`
-    （pi-tui 1.0.2 tui.d.ts:376-378：未应答的颜色为 undefined，两种情形在返回值层面
-    仅靠「是否有任何字段有值」区分）；api=background 时 `undefined` → `timeout`
-    （旧 API 只查 OSC 11，无法细分）。
-    (b) 去重基准 `sentScheme` 初始为 `null`；`null` 不命中 duplicate 判定——保证
-    「超时 → 迟到应答补发」这条主路径不被去重吞掉。
-
-### 2.4 降级路径
-
-- probe 超时 / 异常 / 无 background → 诊断 `outcome=timeout|error|no_background`
-  （level `"warn"`；判定规则见 §2.3 outcome 判定规则），不发 997。
-- 无任何 probe API → 诊断 `details.probeApi="none"`、`outcome=no_probe_api`，不发探测。
-- `onLateReply` 到达且组件已 closed → 不发送，诊断 `outcome=dropped_closed`（level `"info"`）。
-- `onLateReply` 的 scheme 与已发送值（`sentScheme`，初始 `null`）相同 → 不发送，诊断
-  `outcome=duplicate_skipped`（level `"info"`）；不同（含尚未发送过任何值的 `null` 情形，
-  即「超时 → 迟到补发」主路径）→ 补发一次 997，诊断 `outcome=reported`、`late:true`。
-- kill switch（`AGENT_BOARD_FORWARD_TERMINAL_QUERIES=0`）→ 全链路跳过，诊断
-  `outcome=suppressed`（level `"info"`，不填 `probeApi`），行为回到修复前。
-- 控制.socket 未连接时 settle 交付命中 send() 静默 no-op（硬超时落定、宿主连接慢的角落）→
-  不没 sentScheme、不发 997，诊断 `outcome=dropped_disconnected`（level `"warn"`）——同 scheme
-  的迟到应答之后重试而非被去重吞掉。（CR round-1 advisory 采纳）
-- 以上降级均不抛错、不影响 attach 主流程。
-
-### 2.5 非目标
-
-- pi-tui 上游 `pendingTerminalColorQueries` 超时条目累积的队列卫生（上游问题）。
-- WezTerm mode 2031 支持（上游 wezterm/wezterm#6454）。
-- 子 pi 侧 OSC 11 僵尸条目泄漏（上游）。
-- devDependencies 升级到 pi 1.0.x（独立 issue/PR，见开放问题 1）。
-- 复活 #165 删除的 D3 raw replay。
-- 两个 `openPtyAttach` 同构重复的去重（由 plan 自行决定，不作为本期验收项）。
-
-## 3. 验收矩阵
-
-| ID | 功能点 | 验收方式 | 具体验证 | 通过标准 |
-|----|--------|----------|----------|----------|
-| A1 | 新 API 探测与 997 交付 | 自动化验证（unit） | `node --test test/pty-attach-settle-scheme.test.mjs`：fake tui 仅带 `queryTerminalColors`，light/dark 两个 background 值 | probe 被调用；向 child 各发一次 `997;2` / `997;1` |
-| A2 | 旧 API 回退不回归 | 自动化验证（unit） | 同文件：fake tui 仅带 `queryTerminalBackgroundColor` | 旧路径行为与 #149 语义一致（997 照发） |
-| A3 | 双 API 皆缺 | 自动化验证（unit） | 同文件：fake tui 两者皆无 | 不抛错、不发探测；`onDiagnostic` 收到 `details.probeApi:"none"`、`outcome:"no_probe_api"` |
-| A4 | 颜色→亮暗映射 | 自动化验证（unit） | `colorSchemeForBackgroundRgb` 现有边界用例保持 + `backgroundRgbFromTerminalColors` 新用例 | 亮度阈值与 pi 对齐；`background` 缺失返回 `undefined` |
-| A5 | 迟到应答补发与去重 | 自动化验证（unit） | fake：resolve 后再触发 `onLateReply`（scheme 相同 / 不同两组）+ closed 场景 | scheme 不同补发一次 997 且 `late:true`；相同跳过且 `outcome:"duplicate_skipped"`；closed 后不发送且 `outcome:"dropped_closed"` |
-| A6 | 诊断事件流（schema 兼容） | 自动化验证（unit） | fake `onDiagnostic` 捕获各阶段事件，并**将 patch 过一遍 `normalizeDiagnostic(viewId, patch)` 直证字段不丢** | 事件 `code:"attach_settle_scheme"`、`source:"attach"`、`details.{probeApi,outcome,report?}` 全部在 normalize 后存活；kill switch 下 `details.outcome:"suppressed"` |
-| A7 | 真实 PTY 端到端 | 自动化验证（integration） | 扩展 `test-support/detach-gate-smoke.ts`：新增「tui 仅新 API」场景，真实 node-pty 子进程 | 子 PTY 输入流收到正确 997 恰一次 |
-| A8 | 既有面无回归 | 自动化验证（static + build + integration） | `npm run verify`（= typecheck + perf gate + tests + coverage 阈值 lines 85 / funcs 80 / branches 70 + pack:dry，见 AGENTS.md:20-24） | 全绿；c8 分支阈值由 A1/A2/A3 三向覆盖满足；#165 的 `attach-startup-color-smoke` 不受影响 |
-| A9 | 失败分支不发 997 | 自动化验证（unit） | A1 同文件：fake 分别返回 timeout（resolve 完全为空对象 `{}`，不触发 late）/ throw / 有应答但无 `background`（resolve 含 foreground 的对象） | 三种降级下 sent 均为空；`details.outcome` 分别为 `timeout` / `error` / `no_background`（判定规则见 §2.3） |
-| U1 | 真机 board 重启场景（两条入口路径各验一次） | 用户实测 | 前置（必须）：① 快进运行时副本 `git -C ~/.pi/agent/git/github.com/zhuxixi/pi-agent-board pull --ff-only`（至含本修复的 main）；② **重启宿主 pi**（扩展随宿主启动加载，不重启跑的是旧代码）。然后：浅色 WezTerm 下宿主 pi 起 board → board 级重启 → **两次 attach 各走一条入口**：① dashboard 选中 view 回车 attach（验 agent-board.ts 构造点）；② detach 后用 ← 键盘路径或 bg 命令再 attach（验 attach-flow.ts 构造点）；观察子 pi 首帧配色 + 两次各自 view 的 `diagnostics.jsonl` | 两次首帧均 light-warm 系（userMsg ≈ `#f0f0f0` 而非 `#343541`）；两次的 diagnostics.jsonl 均出现 `code:"attach_settle_scheme"`、`details.probeApi:"colors"`、`details.report:"997;2"` |
-| U2 | kill switch 回退 | 用户实测 | 同 U1 前置两步 + `AGENT_BOARD_FORWARD_TERMINAL_QUERIES=0` 起宿主，重复 U1 场景 | 无探测（diagnostics `details.outcome:"suppressed"`）、无报错，行为回到修复前（dark） |
-
-分层说明：A1-A6/A9 用 unit（行为可由注入 fake 完全证明，不跨进程）；A7 必须 fake tui + 真实 PTY
-跨组件，用 integration；A8 是类型/构建/既有集成回归（`npm run verify` 是仓约定的 done 门）。
-U1/U2 依赖真实终端 + 真实宿主 pi 进程与 board 运行时，无法在自动化环境稳定复现（需要真实
-OSC 11 应答方与 board 级重启），故为用户实测；可执行时机 = 修复合入 main 后按前置两步更新
-运行时副本并重启宿主 pi。
-
-## 4. 可测性拆分设计（硬约束）
-
-- `resolveProbeApi`：纯检测器，落点 `src/core/terminal-query-sequences.mjs`。三种 tui
-  形状（仅新 / 仅旧 / 皆无）直测 → 形成 A1/A2/A3 的测试边界：**API 形状判定不依赖真实
-  pi-tui**；参数与返回使用本地结构类型（`TerminalColorsLike` 等），禁止 import pi-tui 的
-  `TerminalColors`。
-- `backgroundRgbFromTerminalColors`：纯映射函数，独立于探测与发送 → A4 边界。
-- `probeAndReportRealTerminalColorScheme`：编排层，副作用序列（query→map→send→diagnose）。
-  unit 测试以注入 fake（tui、send 捕获、onDiagnostic 捕获）断言 → A1/A3/A5/A6/A9 边界：
-  **编排测试不碰真 PTY / 真 socket**。
-- 诊断 wiring（两处 openPtyAttach → appendDiagnostic）：A6 用 `normalizeDiagnostic` 直证
-  组件发出的 patch schema 兼容（字段在白名单内存活）；`appendDiagnostic` 本身已有 core
-  层测试，不在本期改动范围。
-- A7 的真实 PTY 边界：复用 detach-gate-smoke harness（fake tui + 真 node-pty 子进程），
-  不新造 harness。
-- 实现不得把 resolveProbeApi / backgroundRgbFromTerminalColors 的逻辑内联回编排函数
-  （保持可测边界）；不得在编排层引入对 pi-tui 版本的硬编码判断。
-
-## 5. 开放问题
-
-1. devDeps 0.79.8 → 1.0.x 迁移：单独开 issue（类型面变化大：TUI 接口、扩展 API 均有改动；
-   迁移后本 spec 的本地结构类型与 cast 可去除）。是否现在开，等用户确认。
-2. 「宿主已知 scheme 缓存 + settle 重发」（issue 方向 3 保险丝）：本期不做；若 U1 实测发现
-   WezTerm 下探测超时率不为零，再评估。
-3. `pendingTerminalColorQueries` 超时条目是否出队（上游细节）：不影响本期决策（每 attach
-   一次 + onLateReply 的用量与 pi 自身启动探测同量级）；如后续观察到吞应答再上游报 bug。

package/docs/superpowers/specs/2026-10-09-issue-167-attach-middle-paste-design.md

@@ -1,125 +0,0 @@
-# Spec: #167 — middle-click paste in attach views under pi ≥1.0 fullscreen TUI
-
-Status: DRAFT (awaiting user approval — github-issue-driven step 4 gate)
-Issue: https://github.com/zhuxixi/pi-agent-board/issues/167
-Date: 2026-10-09
-
-## Problem (root cause, verified)
-
-pi ≥1.0 defaults to fullscreen TUI. `TuiAltScreen` parses and consumes all SGR mouse
-sequences itself; overlays receive mouse only through the normalized `handleMouse(event)`
-API. `PtyAttachComponent` implements only the legacy `handleInput(data)` path, so its
-middle-click paste (`pastePrimarySelection()`, commit a1c5f08) never runs in fullscreen.
-Regular mode (`pi --tui-mode regular`) is unaffected. Evidence: pi-tui 1.1.0
-`tui-alt-screen.js:520-526`, `tui.js:507-532`; research notes in
-`~/.claude/github-issue-driven/zhuxixi/pi-agent-board/issue-167/research/`.
-
-## Goal / non-goals
-
-**Goal**: middle-click inside the attach view pastes the X11 PRIMARY selection into the
-hosted session in fullscreen mode, with the same semantics and escape hatch as regular
-mode; regular mode behavior unchanged.
-
-**Non-goals** (explicitly deferred):
-- X11 PRIMARY *mirroring* of selections made in fullscreen (pi's own fullscreen selection
-  writes CLIPBOARD, not PRIMARY). Taking over left-button events would displace pi's
-  fullscreen selection — needs its own design (follow-up).
-- #169 (attach teardown disabling outer-terminal mouse reporting) — separate issue/PR.
-- Any wheel behavior change (today's defer-to-overlay fallback keeps working; we return
-  `undefined` for wheel).
-
-## Design
-
-### 1. Pure decision helper (new, `src/core/pty-scroll.mjs` — same module that owns
-`parseMouseInputChunk`)
-
-```js
-// Returns the attach-surface action for a normalized pi-tui mouse event.
-// "paste-primary": read X11 PRIMARY and forward as input (middle-click paste).
-// null: not ours — let the event fall through untouched (today's behavior).
-resolveAttachMouseAction(event, { nativePasteEnabled }) → "paste-primary" | null
-```
-
-Decision table (`event.type`, `event.button`, `nativePasteEnabled`):
-
-| type | button | nativePasteEnabled | result |
-| --- | --- | --- | --- |
-| press | middle | true | `"paste-primary"` |
-| press | middle | false | `null` (kill switch = today's silent drop) |
-| press/release/click | left/right/none | * | `null` (pi fullscreen selection & default behavior untouched) |
-| wheel | any | * | `null` (existing defer-to-`handleInput` path preserved) |
-| move/drag | any | * | `null` |
-
-`nativePasteEnabled` is computed once per call site from
-`process.env.AGENT_BOARD_ATTACH_NATIVE_PASTE !== "0"` (same rule as `pastePrimarySelection`).
-
-### 2. Component wiring (`src/ui/pty-attach.ts`)
-
-```ts
-handleMouse(event: TuiMouseEvent): TuiMouseEventResult | undefined {
-	const action = resolveAttachMouseAction(event, {
-		nativePasteEnabled: process.env.AGENT_BOARD_ATTACH_NATIVE_PASTE !== "0",
-	});
-	if (action === "paste-primary") {
-		this.clearPendingClick();
-		this.clearSelection();
-		this.pastePrimarySelection();
-		return { handled: true, render: false };
-	}
-	return undefined;
-}
-```
-
-- `{ handled: true }` stops propagation and suppresses alt-screen fallback for that
-  press; `render: false` because a successful paste repaints via child output (async)
-  and a failed one (no xclip) needs no repaint.
-- Legacy `handleInput` raw path stays exactly as is — regular mode and wheel keep working.
-- No changes to outer-terminal mouse-mode writes (`MOUSE_ENABLE`/`MOUSE_DISABLE`) — #169.
-
-### 3. devDependencies bump (enabling task)
-
-Bump `@earendil-works/pi-tui` and `@earendil-works/pi-coding-agent` devDeps 0.79.8 → 1.1.0
-(match the runtime the extension actually runs under). Gate: `npm run typecheck` +
-`npm run verify` green. If unrelated type breakage from 0.79.8→1.1.0 turns out to be large,
-fallback: keep 0.79.8 and declare local structural `TuiMouseEvent`/result types in the
-component — decision point recorded in the plan; the bump is the preferred path.
-
-## Acceptance matrix
-
-| ID | 功能点 | 验收方式 | 具体验证 | 通过标准 |
-|----|--------|----------|----------|----------|
-| A1 | 决策表：哪些归一化鼠标事件触发中键粘贴 | 自动化验证（unit） | `node --test test/pty-scroll.test.mjs`（新增用例直接调 `resolveAttachMouseAction`，覆盖决策表全部行 + `AGENT_BOARD_ATTACH_NATIVE_PASTE=0`） | 新增用例全绿，且现有点击/滚轮用例不回归 |
-| A2 | 组件接线：`PtyAttachComponent.handleMouse` 中键 press → 读 PRIMARY → 作为 input 发往 attach socket；kill switch 时返回 undefined | 自动化验证（integration，组件级场景） | 新增 `test-support/pty-attach-mouse-scenario.ts`（仿 `pty-attach-protocol-scenario.ts`：fake tui + stub-`xclip` 目录 prepend PATH 打印 fixture 文本），由 `test/pty-attach-mouse.test.mjs` 以 `node --experimental-transform-types` 运行并断言 JSON 输出 | ① 中键 press 返回 `{handled:true}` 且 socket 收到 `{type:"input",data:fixture}`；② 同场景 legacy `handleInput` 注入 SGR 中键序列行为一致（regular 路径回归）；③ `AGENT_BOARD_ATTACH_NATIVE_PASTE=0` 时 `handleMouse` 返回 undefined 且无 input 发出 |
-| A3 | 类型与构建在 pi-tui 1.1.0 下成立 | 自动化验证（static/build） | `npm run typecheck`、`npm run verify`（含 pack:dry） | 全部通过，无 0.79.8→1.1.0 引入的未处理类型错误 |
-| A4 | 全部既有行为不回归 | 自动化验证（unit+integration，既有套件） | `npm test` / `npm run test:coverage` | 既有测试全绿，覆盖阈值不降 |
-| U1 | 真实终端里 fullscreen 中键粘贴生效 | 用户实测 | ① pi 1.1.0 fullscreen → `/agent-board` → attach；② 在别的 X11 应用选中一段文字；③ 在 attach 视图内中键 | 子 session 收到粘贴文本并有反应；同机 `pi --tui-mode regular` 行为不变；`AGENT_BOARD_ATTACH_NATIVE_PASTE=0` 后中键回到无反应 |
-
-## Testability split design (hard constraint for implementation)
-
-- **Pure core**: `resolveAttachMouseAction(event, {nativePasteEnabled})` — plain function,
-  no I/O, no env reads inside (env read at call site). Unit-tested decision table (A1).
-  Test boundary: `src/core/pty-scroll.mjs` exports; tests import only this.
-- **I/O shell**: `PtyAttachComponent.handleMouse` maps action → `pastePrimarySelection()`
-  (existing xclip spawn) + result object. Tested at component level (A2) through public
-  seams only: `handleMouse`/`handleInput` in, fake tui terminal writes + attach-socket
-  messages out, `xclip` stubbed via PATH. No test-only constructor options.
-- The pure function must not be re-coupled into the component (no inline decision logic).
-
-## Risks / notes
-
-- devDep bump may expose type breakage elsewhere (0.79.8 typings vs 1.1.0). Contained by
-  A3 as its own task; fallback documented above.
-- `AGENT_BOARD_ATTACH_MOUSE=0` does not disable the new path (it governs outer-terminal
-  mode writes only); in fullscreen the alt screen owns reporting regardless. Documented
-  here as intended.
-- Behavior when xclip is absent: unchanged silent no-op (existing contract), but the
-  event is still consumed (`handled:true`) — same as regular mode today.
-
-## Deliverables
-
-- `src/core/pty-scroll.mjs`: + `resolveAttachMouseAction`
-- `src/ui/pty-attach.ts`: + `handleMouse`
-- `package.json`: devDeps bump (pi-tui, pi-coding-agent → 1.1.0)
-- `test/pty-scroll.test.mjs`: decision-table cases
-- `test-support/pty-attach-mouse-scenario.ts` + `test/pty-attach-mouse.test.mjs`
-- CHANGELOG entry via release tooling at release time (not in this PR)

package/docs/superpowers/specs/2026-10-09-issue-169-fullscreen-mouse-ownership-design.md

@@ -1,130 +0,0 @@
-Drafted: zai-coding-cn/glm-5.3 (selected) · zai-coding-cn/glm-5.3 (physical) @ 2026-10-09T12:49:41Z
-
-# Spec: #169 — detaching from a PTY attach view kills outer-terminal mouse reporting for the rest of the fullscreen session
-
-Status: DRAFT (awaiting spec-cross-review, then user approval — github-issue-driven step 4 gates)
-Issue: https://github.com/zhuxixi/pi-agent-board/issues/169
-Repo state baseline: main @ `fee345c` (post-#171)
-
-## Problem (root cause, verified from source)
-
-In fullscreen mode (pi ≥1.0 default) `TuiAltScreen` owns outer-terminal mouse reporting:
-it writes the enable set `?1000h?1002h?1003h?1004h?1006h` exactly once in
-`beforeTerminalStart` (pi-tui 1.1.0 `tui-alt-screen.js:194`) and disables it only at
-`beforeTerminalStop` (:196-206); there is no re-assert path. `PtyAttachComponent` nonetheless
-manages the outer terminal's mouse mode itself — ctor writes
-`MOUSE_DISABLE`+`MOUSE_ENABLE` (downgrading `?1003h`/`?1004h`), and `close()` writes
-`MOUSE_DISABLE` unconditionally (src/ui/pty-attach.ts:278-280, :1524 via
-`disableMouseScroll` :882 — which, unlike `enableMouseScroll`, has no env guard). After
-the first detach, pi-tui still believes mouse is on but the terminal stopped sending
-events: fullscreen selection / copy-on-select / wheel / click regions are dead until pi
-restarts. In regular mode the same writes are correct (board is the sole mouse owner).
-
-Full evidence: `research/2026-10-09-fullscreen-mouse-ownership.md`,
-`research/2026-10-09-repo-state-and-testability.md` in this directory.
-
-## Goal / non-goals
-
-**Goal**: in fullscreen mode the attach component performs **zero** outer-terminal
-mouse-mode writes for its entire lifecycle (ctor, refresh timers, connect, resize,
-close) — `TuiAltScreen` owns the mode and its full `?1003h/?1004h` set survives
-attach AND detach. Regular-mode behavior (including the
-disable→enable→refresh pairing and the kill-switch semantics) is unchanged. Old pi
-runtimes without `tui.mode` keep today's (regular) behavior.
-
-**Non-goals**:
-- X11 PRIMARY mirroring of the fullscreen-native selection (deferred with #167).
-- Any pi-tui change or new re-assert API (unnecessary).
-- Wheel/scroll/selection behavior inside attach views (unchanged by design: deferred
-  wheel still reaches `handleInput`; clicks via `handleMouse` from #171).
-- #170 (reply guard), #168 (session resume) — unrelated paths.
-
-## Design
-
-### 1. Pure decision helper (new, `src/core/pty-scroll.mjs` — mouse helpers live here)
-
-```js
-/**
- * Issue #169: whether the attach surface should manage the OUTER terminal's mouse
- * mode. Only in regular TUI mode — in fullscreen, TuiAltScreen owns mouse reporting
- * (asserted once at startup, never re-asserted), so any write from here can only
- * downgrade or kill it. Old runtimes without tui.mode behave as regular.
- * Pure: mode and the env-derived flag are resolved at the call site.
- */
-shouldOwnOuterMouseMode(mode, mouseEnabled) → boolean   // mode !== "fullscreen" && mouseEnabled
-```
-
-### 2. Component gating (`src/ui/pty-attach.ts`)
-
-All outer-terminal mouse writes funnel through exactly two private methods —
-`enableMouseScroll()` (:852) and `disableMouseScroll()` (:882). Gate both:
-
-```ts
-private ownsOuterMouseMode(): boolean {
-	return shouldOwnOuterMouseMode(this.tui.mode, this.mouseScrollEnabled());
-}
-```
-
-- `enableMouseScroll()`: early-return `if (!this.ownsOuterMouseMode())` (replaces the
-  current `mouseScrollEnabled()` check; also gates the `XTSHIFTESCAPE_SELECT` write).
-- `disableMouseScroll()`: early-return `if (!this.ownsOuterMouseMode())` (new guard —
-  fixes both the fullscreen teardown kill and the flagged unguarded disable under
-  `AGENT_BOARD_ATTACH_MOUSE=0`).
-- `refreshMouseScrollMode()` keeps its `mouseScrollEnabled()` early-return (cheap) and
-  its timers call the now-gated `enableMouseScroll` — no other call-site changes
-  (ctor :278-280, connect :487, resize :1203, close :1524 all route through the two
-  choke points).
-- Comment on `ownsOuterMouseMode()` noting `tui.mode` is typed non-optional but may be
-  absent on old runtimes — strict inequality handles it.
-
-### Resulting behavior matrix
-
-| tui.mode | AGENT_BOARD_ATTACH_MOUSE | ctor/connect/resize writes | close() write | fullscreen session after detach |
-| --- | --- | --- | --- | --- |
-| fullscreen | any | none | none | mouse alive (BUG FIXED) |
-| regular / undefined (old runtime) | on (default) | today's pairing | MOUSE_DISABLE | n/a (unchanged) |
-| regular / undefined | off | none | none | n/a (also fixes unguarded-disable defect) |
-| fullscreen (host built with TuiAltScreenOptions.mouse: false) | n/a | none | none | consistent: host explicitly disabled mouse; nothing owns it — attach-view mouse features inert by host choice |
-
-## Acceptance matrix
-
-| ID | 功能点 | 验收方式 | 具体验证 | 通过标准 |
-|----|--------|----------|----------|----------|
-| A1 | 鼠标模式所有权决策表（mode × env 开关） | 自动化验证（unit） | `node --test test/pty-scroll.test.mjs`（新增用例直接调 `shouldOwnOuterMouseMode`，覆盖 6 格：fullscreen×on/off、regular×on/off、undefined×on/off） | 新增用例全绿，现有点击/滚轮/中键用例不回归 |
-| A2 | fullscreen 全生命周期零外层鼠标写；regular 配对保留；kill switch 零写 | 自动化验证（integration，组件级场景） | 新增 `test-support/pty-attach-mouse-mode-scenario.ts`（fake tui 的 `terminal.write` 采集字节 + `mode` 可控 + 不可达 socketPath），由 `test/pty-attach-mouse-mode.test.mjs` 以 `node --experimental-transform-types` 运行断言 JSON 输出 | ① `mode:"fullscreen"`：ctor+250ms 刷新窗+close 全程 0 个 `?1000/?1002/?1003/?1004/?1006/XTSHIFTESCAPE` 写；② `mode:"regular"`：ctor 有 `MOUSE_ENABLE`、close 有 `MOUSE_DISABLE`；③ regular+`AGENT_BOARD_ATTACH_MOUSE=0`：全程 0 写（含 close）；④ 无 `mode` 字段的 fake tui 行为同 regular |
-| A3 | 类型与构建 | 自动化验证（static/build） | `npm run typecheck`、`npm run verify`（含 pack:dry） | 全部通过 |
-| A4 | 既有行为不回归（含 #171 中键粘贴场景） | 自动化验证（unit+integration，既有套件） | `npm test` / `npm run test:coverage` | 既有测试全绿，覆盖阈值不降 |
-| U1 | 真机：detach 后外层鼠标存活 | 用户实测 | ① pi ≥1.0 fullscreen → `/agent-board` → attach → detach（ctrl+\）；② dashboard 里拖选文字 → 应高亮且 copy-on-select 生效；③ 滚轮/点击区域正常；④ attach 中 pi 自身全屏选中/复制正常（`?1003h/?1004h` 不再被降级）；⑤ `pi --tui-mode regular` 下 attach→detach 行为与从前一致 | ①–⑤ 全部符合；修复前 ①③④ 在 detach 后失效 |
-
-## Testability split design (hard constraint for implementation)
-
-- **Pure core**: `shouldOwnOuterMouseMode(mode, mouseEnabled)` — plain function, no env
-  reads inside (both args resolved at the call site). Unit-tested decision table (A1).
-  Test boundary: `src/core/pty-scroll.mjs` exports; tests import only this.
-- **I/O shell**: `PtyAttachComponent.ownsOuterMouseMode()` reads `this.tui.mode` +
-  `this.mouseScrollEnabled()` and delegates to the pure helper; the two write methods
-  keep ALL terminal writes. Component-level tests (A2) drive only public seams
-  (constructor, time, `dispose()`) and observe `terminal.write` bytes of a fake tui —
-  no test-only constructor options, no reading private state.
-- The pure helper must not be re-inlined into the component; the two choke-point methods
-  must remain the only places that write mouse-mode/XTSHIFTESCAPE sequences.
-
-## Risks / notes
-
-- A2 uses an unreachable socketPath to keep the scenario runner-free; if the ctor's
-  connect-error path proves non-deterministic for the write-spy assertions, fall back to
-  the #171-style real-runner scenario asserting the same facts around a real
-  attach/detach (decision at plan time; record whichever is used).
-- Existing scenarios' fake tuis have no `mode` field → they stay on the regular path and
-  don't assert terminal bytes → unaffected by the gating.
-- `AGENT_BOARD_ATTACH_MOUSE` semantics in fullscreen become moot (no writes either way);
-  document in the behavior matrix rather than redefining the switch.
-
-## Deliverables
-
-- `src/core/pty-scroll.mjs`: + `shouldOwnOuterMouseMode`
-- `src/ui/pty-attach.ts`: + `ownsOuterMouseMode()` private method; guards in
-  `enableMouseScroll` / `disableMouseScroll`
-- `test/pty-scroll.test.mjs`: decision-table cases
-- `test-support/pty-attach-mouse-mode-scenario.ts` + `test/pty-attach-mouse-mode.test.mjs`
-- CHANGELOG entry via release tooling at release time (not in this PR)