@zhuxixi/pi-agent-board 0.7.0 → 0.9.0

package/docs/superpowers/plans/2026-09-23-cwd-browse-tab-drill.md

@@ -0,0 +1,393 @@
+# cwd 选择器 browse 模式 Tab 补全 Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** 让 Start session 的 cwd 选择器在文件系统浏览（browse）模式下 Tab 键可用：补全高亮候选、连续 Tab 像 shell 一样逐层下钻（issue #127，选项 B）。
+
+**Architecture:** 新语义全部沉到 `src/core/launch-options.mjs` 的两个纯函数（`sameResolvedDir`、`browseTabCompletion`）；`src/ui/dashboard.ts` 的 Tab 分支删掉 favorites-only 模式守卫，browse 走新 helper，favorites 逻辑一字不动。探针式集成测试（test-support/*.ts + `node --experimental-transform-types`）覆盖接线层，沿用 `navigation-wrap.ts` 既有模式。
+
+**Tech Stack:** Node.js (node:test)、TypeScript（dashboard.ts，strip-types 经 transform 跑）、纯 JSDoc 的 .mjs core 层。
+
+**Worktree（所有作业路径基准，记作 $WT）:** `/home/elling/git-repo/github/pi-agent-board/.pi/worktrees/issue-127-cwd-browse-tab-drill`
+
+**Spec:** `$WT/docs/superpowers/specs/2026-09-23-cwd-browse-tab-drill-design.md`（已提交，含验收矩阵 A1–A6/U1）
+
+## Global Constraints
+
+- 只在 $WT 内作业；git 操作用 `git -C $WT`；**禁碰主 checkout**。
+- 测试命令：`node --test test/<file>.test.mjs`（在 $WT 下跑）；全量 `npm test`（= `node --test test/*.test.mjs`）。
+- dashboard.ts 用了 TS parameter properties，测试必须经 `node --experimental-transform-types` 子进程跑探针；test-support/ 不在 tsconfig 内、不做 typecheck。
+- 纯函数边界是实现硬约束：`sameResolvedDir` / `browseTabCompletion` 不得依赖 dashboard 状态；dashboard.ts 只接线。
+- favorites 模式的既有 Tab 语义（补全进输入框、回车确认）一行不改。
+- 不做 `~` 展开进收藏匹配（spec 已确认范围外）；不做 fuzzy 匹配。
+- commit message 用 conventional commits（`fix:` / `feat:` / `test:`），按文件 `git add`，禁用 `git add -A`。
+
+## 验收追溯（spec 验收 ID ↔ task）
+
+| 验收 ID | 归属 task |
+|---------|-----------|
+| A4 纯函数 helper 边界 | Task 1 |
+| A1 browse Tab 补全 + 重算 | Task 2 |
+| A2 连续 Tab 逐层下钻 | Task 2 |
+| A3 favorites Tab 不回归 | Task 2 |
+| A5 browse 提示含 tab | Task 2 |
+| A6 全量测试 + typecheck 无回归 | Task 3 |
+| U1 真实 TUI 手感（用户实测） | Task 4（post-implementation manual verification） |
+
+---
+
+### Task 1: 纯函数 helpers —— `sameResolvedDir` + `browseTabCompletion`
+
+**Files:**
+- Modify: `$WT/src/core/launch-options.mjs`（在 `filterCwdCandidates` 附近追加；`expandHome` 定义于 :279，同文件可直接调用；`path` 已 import）
+- Test: `$WT/test/launch-options.test.mjs`（现有 import 行 :6 追加两个函数名；文件已 import `node:assert/strict`、`node:test`；另需 `import os from "node:os";` 与 `import path from "node:path";`，若已有则复用）
+
+**Interfaces:**
+- Produces:
+  - `sameResolvedDir(a: string, b: string): boolean` — 两路径串是否解析到同一目录；空白输入永不匹配。
+  - `browseTabCompletion(query: string, suggestions: string[], index: number): { query: string, completed: string, usedIndex: number } | null` — browse 模式 Tab 补全计算；suggestions 为空返回 null。
+- Consumes: 无（首个 task）。
+
+- [ ] **Step 1: 写失败测试**（追加到 `$WT/test/launch-options.test.mjs`；先确认文件头部的 import 行，缺 `os`/`path` 就补）
+
+```js
+test("sameResolvedDir: matches across trailing separator and ~; blank never matches", () => {
+	const home = os.homedir();
+	assert.equal(sameResolvedDir("~/work", `${home}/work/`), true);
+	assert.equal(sameResolvedDir("/a/b", "/a/c"), false);
+	assert.equal(sameResolvedDir("", "/a"), false);
+	assert.equal(sameResolvedDir("   ", "/a"), false);
+});
+
+test("browseTabCompletion: completes highlighted suggestion with trailing separator", () => {
+	const res = browseTabCompletion("/tmp/x/wo", ["/tmp/x/work"], 0);
+	assert.deepEqual(res, { query: `/tmp/x/work${path.sep}`, completed: "/tmp/x/work", usedIndex: 0 });
+});
+
+test("browseTabCompletion: no-progress highlight advances cyclically", () => {
+	const s = ["/tmp/x/work", "/tmp/x/work/app", "/tmp/x/work/notes"];
+	const res = browseTabCompletion(`/tmp/x/work${path.sep}`, s, 0);
+	assert.equal(res.usedIndex, 1);
+	assert.equal(res.query, `/tmp/x/work/app${path.sep}`);
+	// wraps from the last entry back to the first
+	const res2 = browseTabCompletion("/tmp/x/work/notes", ["/tmp/x/work", "/tmp/x/work/notes"], 1);
+	assert.equal(res2.usedIndex, 0);
+	assert.equal(res2.query, `/tmp/x/work${path.sep}`);
+});
+
+test("browseTabCompletion: single self suggestion stays put (drill naturally stops)", () => {
+	const res = browseTabCompletion(`/tmp/x/work${path.sep}`, ["/tmp/x/work"], 0);
+	assert.equal(res.query, `/tmp/x/work${path.sep}`);
+	assert.equal(res.usedIndex, 0);
+});
+
+test("browseTabCompletion: empty suggestions -> null; out-of-range index clamps", () => {
+	assert.equal(browseTabCompletion("x", [], 0), null);
+	assert.equal(browseTabCompletion("x", null, 0), null);
+	const res = browseTabCompletion("x", ["/a"], 7);
+	assert.equal(res.usedIndex, 0);
+});
+```
+
+- [ ] **Step 2: 跑测试确认失败**
+
+Run: `cd $WT && node --test test/launch-options.test.mjs`
+Expected: FAIL（`sameResolvedDir is not defined` / import 报错）
+
+- [ ] **Step 3: 实现 helpers**（追加到 `$WT/src/core/launch-options.mjs`，放在 `filterCwdCandidates` 之后、`nextCwdPickerState` 之前）
+
+```js
+/**
+ * Whether two path strings resolve to the same directory. Blank inputs never
+ * match (path.resolve("") would silently equal process.cwd()).
+ * @param {string} a
+ * @param {string} b
+ * @returns {boolean}
+ */
+export function sameResolvedDir(a, b) {
+	const na = String(a ?? "").trim();
+	const nb = String(b ?? "").trim();
+	if (!na || !nb) return false;
+	return path.resolve(expandHome(na)) === path.resolve(expandHome(nb));
+}
+
+/**
+ * Browse-mode Tab completion for the cwd picker. Completes to the highlighted
+ * suggestion with a trailing separator (so the next recompute lists that
+ * directory's children); when the highlight already equals the current query
+ * (no progress), advances cyclically so repeated Tab drills downward. A lone
+ * self suggestion stays put, so drilling stops naturally at leaf directories.
+ * @param {string} query
+ * @param {string[]} suggestions
+ * @param {number} index
+ * @returns {{query: string, completed: string, usedIndex: number} | null}
+ */
+export function browseTabCompletion(query, suggestions, index) {
+	if (!suggestions || suggestions.length === 0) return null;
+	const len = suggestions.length;
+	let usedIndex = ((index % len) + len) % len;
+	let completed = suggestions[usedIndex];
+	if (len > 1 && sameResolvedDir(completed, query)) {
+		usedIndex = (usedIndex + 1) % len;
+		completed = suggestions[usedIndex];
+	}
+	return { query: completed + path.sep, completed, usedIndex };
+}
+```
+
+- [ ] **Step 4: 跑测试确认通过**
+
+Run: `cd $WT && node --test test/launch-options.test.mjs`
+Expected: PASS（新旧用例全绿）
+
+- [ ] **Step 5: Commit**
+
+```bash
+git -C $WT add src/core/launch-options.mjs test/launch-options.test.mjs
+git -C $WT commit -m "feat: add browse-mode Tab completion helpers for cwd picker (issue #127)"
+```
+
+---
+
+### Task 2: dashboard 接线 + browse 提示文案 + 探针集成测试
+
+**Files:**
+- Create: `$WT/test-support/cwd-browse-tab-probe.ts`
+- Create: `$WT/test/dashboard-cwd-tab.test.mjs`
+- Modify: `$WT/src/ui/dashboard.ts`（import 行；Tab 分支 :598-608；提示文案 :1586）
+
+**Interfaces:**
+- Consumes: Task 1 的 `sameResolvedDir`（不直接用）、`browseTabCompletion`（dashboard.ts 引用）。
+- Produces: 无新对外接口（行为修复）。
+
+- [ ] **Step 1: 写失败探针与测试**
+
+Create `$WT/test-support/cwd-browse-tab-probe.ts`:
+
+```ts
+// cwd browse-Tab probe (issue #127): drive Tab through the public handleInput()
+// in browse and favorites picker modes and report picker state as JSON.
+// Run via `node --experimental-transform-types` (dashboard.ts uses TS
+// parameter properties). Not typechecked (tsconfig excludes test-support).
+import { mkdirSync, mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, sep } from "node:path";
+import { createService } from "../src/runtime/service.mjs";
+import { DashboardComponent } from "../src/ui/dashboard.ts";
+import { nextCwdPickerState } from "../src/core/launch-options.mjs";
+
+const root = mkdtempSync(join(tmpdir(), "agentview-cwd-tab-"));
+const work = join(root, "work");
+mkdirSync(join(work, "app"), { recursive: true });
+mkdirSync(join(work, "notes"), { recursive: true });
+
+const service = createService({
+	root,
+	runnerScript: "/no/runner.mjs",
+	piCommand: "pi",
+	piArgsPrefix: [],
+	defaultCwd: root,
+	launch: () => ({ pid: null, configPath: "/no/config.json" }),
+	launchHost: () => ({ pid: null, configPath: "/no/host-config.json" }),
+	launchTitle: () => ({ pid: null, configPath: "/no/title-config.json" }),
+});
+
+const tui = {
+	terminal: { rows: 24, cols: 80, columns: 80, write: () => {} },
+	requestRender: () => {},
+};
+const theme = { fg: (_c, t) => t, bold: (t) => t };
+
+const dash = new DashboardComponent(tui, theme, {}, () => {}, {
+	service,
+	root,
+	defaultCwd: root,
+	availableModels: [],
+	currentModel: null,
+	currentThinkingLevel: "off",
+});
+
+// TS-private is runtime-accessible; white-box the launch dialog open
+// (input must be non-empty or openLaunchDialog bails back to list mode).
+dash.input = "go";
+dash.openLaunchDialog();
+dash.openLaunchPicker("cwd", join(root, "wo"));
+
+const out = { root, work };
+out.mode0 = dash.launch.cwdPickerMode;
+out.sugg0 = dash.launch.cwdSuggestions;
+
+// Browse Tab 1: completes the highlighted candidate with a trailing separator.
+dash.handleInput("\t");
+out.afterTab1 = {
+	query: dash.launch.cwdQuery,
+	mode: dash.launch.cwdPickerMode,
+	suggestions: dash.launch.cwdSuggestions,
+	index: dash.launch.cwdSuggestionIndex,
+};
+
+// Browse Tab 2: highlight sits on the just-completed dir (no progress) -> drill into first child.
+dash.handleInput("\t");
+out.afterTab2 = { query: dash.launch.cwdQuery, mode: dash.launch.cwdPickerMode };
+
+// Browse Tab 3: leaf dir has a lone self suggestion -> stable no-op.
+dash.handleInput("\t");
+out.afterTab3 = dash.launch.cwdQuery;
+
+// Browse hint advertises tab completion (render while still in browse mode).
+out.browseHint = dash.render(80).join("\n").includes("type to filter folders · tab complete");
+
+// Favorites regression: ranked hit keeps the old complete-into-input semantics (no trailing separator).
+const launch = dash.launch;
+launch.cwdRanked = [{ path: work, count: 3 }];
+launch.cwdQuery = "wo";
+const st = nextCwdPickerState("wo", launch.cwdRanked, launch.cwd);
+launch.cwdPickerMode = st.mode;
+launch.cwdSuggestions = st.suggestions;
+launch.cwdSuggestionIndex = 0;
+dash.handleInput("\t");
+out.fav = { query: dash.launch.cwdQuery, mode: dash.launch.cwdPickerMode };
+
+dash.dispose();
+console.log(JSON.stringify(out));
+```
+
+Create `$WT/test/dashboard-cwd-tab.test.mjs`:
+
+```js
+import assert from "node:assert/strict";
+import { execFileSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { join, sep } from "node:path";
+import test from "node:test";
+
+const ROOT_DIR = fileURLToPath(new URL("../", import.meta.url));
+const PROBE = join(ROOT_DIR, "test-support", "cwd-browse-tab-probe.ts");
+
+test("cwd picker: browse-mode Tab completes and drills; favorites Tab unchanged (issue #127)", () => {
+	// dashboard.ts uses TS parameter properties, which strip-only mode rejects;
+	// --experimental-transform-types handles them (Node 22.7+ / 24).
+	const out = execFileSync(process.execPath, ["--experimental-transform-types", PROBE], {
+		encoding: "utf8",
+		timeout: 30_000,
+	});
+	const r = JSON.parse(out);
+	const work = r.work;
+
+	// A1: browse-mode Tab completes the highlighted candidate into the query.
+	assert.equal(r.mode0, "browse");
+	assert.deepEqual(r.sugg0, [work]);
+	assert.equal(r.afterTab1.query, `${work}${sep}`);
+	assert.equal(r.afterTab1.mode, "browse");
+	assert.equal(r.afterTab1.suggestions[0], work);
+
+	// A2: repeated Tab drills down like a shell (work/ -> work/app/), stopping at the leaf.
+	assert.equal(r.afterTab2.query, `${join(work, "app")}${sep}`);
+	assert.equal(r.afterTab2.mode, "browse");
+	assert.equal(r.afterTab3, `${join(work, "app")}${sep}`);
+
+	// A5: browse-mode hint advertises tab completion.
+	assert.equal(r.browseHint, true);
+
+	// A3: favorites mode keeps the original semantics (bare path, mode stays favorites).
+	assert.equal(r.fav.query, work);
+	assert.equal(r.fav.mode, "favorites");
+});
+```
+
+- [ ] **Step 2: 跑测试确认失败（复现 bug）**
+
+Run: `cd $WT && node --test test/dashboard-cwd-tab.test.mjs`
+Expected: FAIL —— `r.afterTab1.query` 仍是探针 seed 的 `join(root, "wo")`（browse 模式 Tab 被静默吞掉），A1 断言先挂。
+
+- [ ] **Step 3: 实现修复**
+
+a) `$WT/src/ui/dashboard.ts` 顶部 import（:24 附近，现有 `nextCwdPickerState` 同一条 import 里）追加 `browseTabCompletion`。
+
+b) 替换 Tab 分支（:598-608）为：
+
+```ts
+		if (launch.picker === "cwd" && matchesKey(data, Key.tab)) {
+			if (launch.cwdSuggestions.length > 0) {
+				if (launch.cwdPickerMode === "browse") {
+					const completion = browseTabCompletion(launch.cwdQuery, launch.cwdSuggestions, launch.cwdSuggestionIndex);
+					if (completion) {
+						launch.cwdQuery = completion.query;
+						const state = nextCwdPickerState(launch.cwdQuery, launch.cwdRanked, launch.cwd);
+						launch.cwdPickerMode = state.mode;
+						launch.cwdSuggestions = state.suggestions;
+						launch.cwdSuggestionIndex = Math.max(0, state.suggestions.indexOf(completion.completed));
+					}
+				} else {
+					const completed = launch.cwdSuggestions[launch.cwdSuggestionIndex] ?? launch.cwdSuggestions[0];
+					launch.cwdQuery = completed;
+					const state = nextCwdPickerState(launch.cwdQuery, launch.cwdRanked, launch.cwd);
+					launch.cwdPickerMode = state.mode;
+					launch.cwdSuggestions = state.suggestions;
+					launch.cwdSuggestionIndex = Math.max(0, state.suggestions.indexOf(completed));
+				}
+			}
+			return;
+		}
+```
+
+c) browse 提示文案（:1586）：
+
+```ts
+				lines.push(t.fg("dim", "type to filter folders · tab complete · enter choose · esc back"));
+```
+
+- [ ] **Step 4: 跑测试确认通过**
+
+Run: `cd $WT && node --test test/dashboard-cwd-tab.test.mjs`
+Expected: PASS（A1/A2/A3/A5 全绿）
+
+- [ ] **Step 5: Commit**
+
+```bash
+git -C $WT add src/ui/dashboard.ts test-support/cwd-browse-tab-probe.ts test/dashboard-cwd-tab.test.mjs
+git -C $WT commit -m "fix: browse-mode Tab completes and drills down directories in cwd picker (issue #127)"
+```
+
+---
+
+### Task 3: 全量回归 + typecheck（A6）
+
+**Files:** 无改动（纯验证）。
+
+**Interfaces:**
+- Consumes: Task 1、Task 2 的全部产物。
+- Produces: 无。
+
+- [ ] **Step 1: 全量测试**
+
+Run: `cd $WT && npm test`
+Expected: PASS（`node --test test/*.test.mjs` 全绿；特别关注 launch-options / dashboard 相关文件无回归）
+
+- [ ] **Step 2: typecheck**
+
+Run: `cd $WT && npm run typecheck`
+Expected: PASS（`tsc --noEmit` 无错；dashboard.ts 对 `browseTabCompletion` 的调用类型正确，含 null 收窄）
+
+- [ ] **Step 3: 如全量中有与本改动无关的既存 flake（对照 issue #95/#140 清单）失败，隔离复跑该文件确认；与本改动相关则回到对应 task 修**
+
+---
+
+### Task 4: 用户实测 U1（post-implementation manual verification）
+
+**Files:** 无改动。
+
+- [ ] **Step 1: 请用户实测**（PR 合并前执行；自动化测试通过不能替代本项）
+
+操作步骤：
+1. 从本 worktree 构建/链接后打开 agent-board 面板，进入 Start session。
+2. 聚焦 cwd 字段，输入 `~/wo`（或任意 `~` 开头路径片段），确认候选列表出现后按 Tab。
+3. 连续按 Tab 观察逐层下钻；用 ↑/↓ 调整高亮后再按 Tab；Enter 确认并启动 session。
+
+观察结果（记录）：
+- Tab 是否补全高亮候选进输入框；连续 Tab 是否逐层深入；叶子目录是否自然停止。
+- 启动的 session cwd 是否为最终确认的目录。
+
+通过标准：补全/下钻手感符合 shell 习惯；session cwd 正确；favorites 场景（输入收藏目录名片段）Tab 行为与 main 一致。
+
+实测结果：**pending**（待用户执行）

package/docs/superpowers/plans/2026-09-23-terminal-query-forwarding.md

@@ -0,0 +1,51 @@
+# Plan: attach 终端能力透传（issue #128）
+
+Spec: `docs/superpowers/specs/2026-09-23-terminal-query-forwarding-design.md`（commit a3a7374）
+Base: main 4ccb427
+
+## Task 1: 提取器与纯函数（A1, A2）
+
+**Files:**
+- 新建 `src/core/terminal-query-sequences.mjs`：
+  - `extractOscQuerySequences(input) → { sequences, carry }` — 转发 `\x1b]11;?` + BEL(`\x07`)/ST(`\x1b\\`) 定界、`\x1b[?2031h`、`\x1b[?2031l`；**排除** `\x1b]11;rgb:...` 设置形态与 kitty/DA（`\x1b[>7u`/`\x1b[?u`/`\x1b[c`）；carry 模式照抄 `extractOsc52Sequences` 结构（部分前缀保留、carry 上限）
+  - `toColorSchemeReport(scheme) → string` — light/dark → 颜色方案报告序列（997）；**格式先读 pi-tui `parseTerminalColorSchemeReport`（node_modules/@earendil-works/pi-tui/dist/tui.js）源码对齐**，来源在测试注释标注
+  - `OSC_QUERY_CARRY_MAX_BYTES` 常量（对齐既有家族取值）
+- 新建 `test/terminal-query-sequences.test.mjs`（unit）：
+  - A1: 查询 BEL/ST 各转发一次；设置形态不转发；2031h/l 转发；跨 chunk（查询截半 → carry 拼接后识别）；carry 不含完整序列时丢弃防积压
+  - A2: toColorSchemeReport light/dark 两态输出与 pi-tui parser 双向验证（序列喂 parser 能解回 scheme）
+
+**Verify:** `node --test test/terminal-query-sequences.test.mjs` 全绿
+
+**Constraints:** 纯函数零副作用；不 import pi-tui（格式对齐靠测试里 parser 交叉验证，生产代码硬编码序列——避免对 pi-tui 内部结构的运行时依赖）
+
+## Task 2: attach 组件接线（A3, A4, A5, A6, A7）
+
+**Files:**
+- `src/ui/pty-attach.ts`:
+  - import 提取器；`forwardTerminalProtocols` 增加第三段（独立 `oscQueryCarry` 字段，kill switch `AGENT_BOARD_FORWARD_TERMINAL_QUERIES !== "0"` 默认开）
+  - `attachColorSchemeBridge()` — settle 时 `this.tui.onTerminalColorSchemeChange(...)` 注册，回调 `this.send({type:"input", data: toColorSchemeReport(scheme)})`；`done()`/detach 路径退订（A7 对称）
+  - `replayBackgroundQuery()` — settle 后一次性 `this.tui.terminal.write("\x1b]11;?\x07")`；不截获应答（靠既有兜底穿透）；仅在本次 attach 从未发过时发（防重复 settle 重放）
+  - settle 路径接线两方法；确认 settle 判定处（attach loading banner 消失点）只调一次
+- `test-support/detach-gate-smoke.ts` 扩展场景（P8-P11）+ `test/pty-attach-detach-gate.test.mjs` 断言：
+  - A3: 远端 output 含 `\x1b]11;?\x07` → localTerminalWrites 含之；含 `\x1b]11;rgb:ffff/ffff/ffff\x07` → 不写
+  - A4: 伪 tui 触发 colorScheme listener("light") → socket 收到 `type:"input"` + 997 报告；模拟 detach 后再触发 → 不发（A7）
+  - A5: attach settle → localTerminalWrites 恰一条 `\x1b]11;?\x07`；kill switch=0 时零条
+  - A6: 远端 output 含 `\x1b[>7u\x1b[?u\x1b[c` → localTerminalWrites 不含任何一段
+
+**Verify:** 定向 `node --test test/pty-attach-detach-gate.test.mjs` + 全量 `node --test test/*.test.mjs`（账本 flake 除外）+ `npm run typecheck`
+
+**Constraints:** 转发写失败静默（沿用既有 catch）；桥/回放不影响 attach 主流程；kill switch 覆盖全部新行为
+
+## Task 3: 文档同步（A 矩阵文案面, U1-U3 步骤引用）
+
+**Files:**
+- `README.md` attach 特性两段：新增「终端能力透传」小节——亮暗探测转发/桥接/首帧回放的行为描述 + kill switch + 已知未覆盖（kitty/DA 协商、OSC 10/12）
+- spec 验收矩阵 U1/U3 的实测步骤引用 README 步骤
+
+**Verify:** 文案与实现行为一致（reviewer 对照）；无自动化新增
+
+## Review 焦点预设
+
+- T1: carry 边界（截半在定界符处/前缀处）、设置形态误匹配（`\x1b]11;?` 前缀是 rgb 设置的前缀吗——不是，`?` vs `r` 第一字符即分岔，测试钉死）
+- T2: settle 只触发一次的路径证明；桥退订覆盖所有 done 路径（exit/error/detach/kill）；kill switch 三处（转发/桥/回放）全覆盖
+- T3: 文案不过度承诺（OSC 11「正常场景穿透」而非「总是」——本地 pending>0 边角如实）

package/docs/superpowers/plans/2026-09-23-unconditional-detach-key.md

@@ -0,0 +1,58 @@
+# Plan: 终端无关的无条件 detach 逃生键 Ctrl+\（issue #126）
+
+Spec: docs/superpowers/specs/2026-09-23-unconditional-detach-key-design.md（首个 commit 69eb7d6，含验收矩阵与可测性拆分）。
+
+## Verified ground truth (do not re-litigate)
+
+- `matchesKey` 对三种编码全部原生匹配（spec review 实测）：裸 `\x1c`、kitty `\x1b[92;5u`、modifyOtherKeys `\x1b[27;5;92~`。键名字符串 `"ctrl+\\"`（JS 源码双反斜杠）。
+- pi 本体 dist / 本仓 src·runner·test 无 `ctrl+\` 占用。
+- 集成点：`src/ui/pty-attach.ts` handleInput 的 `Key.ctrl("left")` 分支（当前 :290）**之前**插新分支；header（:343 附近 `"Ctrl+← detach"`）与 loading banner（:359 附近 `"Ctrl+← to detach"`）文案更新。
+- smoke harness：`test-support/detach-gate-smoke.ts` 现有场景驱动真组件；`connected=true` 显式模式；Ctrl+← 场景为 L/M/N（对照模板）。
+- README 按键段两处（:96 与 :195 附近），Phase 6 已改为 D1 契约文案，本次在其上补无条件键 + 已知代价（键盘布局限制、Ctrl+4 legacy 别名、child 抢键面）。
+- 全量测试命令是 `node --test test/*.test.mjs`（目录形式会异常失败）；CI 会跑同款。
+
+## Tasks
+
+### Task 1: Ctrl+\ 分支 + 四象限/三编码 smoke 场景（TDD）— covers A1, A2, A3
+
+**Files:**
+- Modify: `src/ui/pty-attach.ts`（handleInput 新分支）
+- Modify: `test-support/detach-gate-smoke.ts`（新增场景）
+- Modify: `test/pty-attach-detach-gate.test.mjs`（新断言接线）
+
+**Steps:**
+1. Red：smoke 新增场景组——四象限（editorEmpty=true/false/null × connected=true）+ disconnected 一条；每象限注入裸 `\x1c`，断言 `didDetach()` 为真（A1/A2）。另加编码形态场景：`\x1b[92;5u`（kitty）与 `\x1b[27;5;92~`（modifyOtherKeys）各一条 detach 断言；冲突隔离：`\x1b[1;5D` 仍 detach、`\x1b[D` 按 D1 门禁、可打印键 `q` 转发、`ctrl+]` 透传（A3）。先跑确认新场景红。
+2. Green：handleInput 在 `Key.ctrl("left")` 分支**之前**插入：
+
+```ts
+		if (matchesKey(data, "ctrl+\\")) {
+			// Unconditional, terminal-independent escape (issue #126): 0x1c is a
+			// single raw ASCII byte every terminal forwards unchanged in raw
+			// mode — no modifier-encoding dependency like Ctrl+Left (macOS
+			// Terminal.app never emits it, WezTerm consumes it for tab
+			// switching). Only caveat (documented in README): layouts where
+			// `\` sits on AltGr may never produce this byte; the escape ladder
+			// still covers those. matchesKey also covers the kitty CSI-u and
+			// modifyOtherKeys encodings of the same chord.
+			this.detach();
+			return;
+		}
+```
+
+3. 定向测试全绿：`node --test test/pty-attach-detach-gate.test.mjs`。
+
+### Task 2: 文案与 README 同步 — covers A4
+
+**Files:**
+- Modify: `src/ui/pty-attach.ts`（header + loading banner）
+- Modify: `test/pty-attach-detach-gate.test.mjs`（header 断言扩到 Ctrl+\）
+- Modify: `README.md`（两处按键段）
+
+**Steps:**
+1. header：`Ctrl+← detach` → `Ctrl+←/Ctrl+\\ detach`（注意渲染字符串里的反斜杠转义）；loading banner 同步。detach-gate 测试的 header 断言补 Ctrl+\ 出现（沿用 `headerMentions*` 模式）。
+2. README 两处按键段：补「`Ctrl+\` 是无条件退出键（终端无关）」+ 已知代价三条（键盘布局 AltGr 限制、Ctrl+4 legacy 别名、child 抢键面 = child 内 vim terminal-mode Ctrl+\ 前缀）。
+3. 定向测试绿；全量 `node --test test/*.test.mjs` + `npm run typecheck`。
+
+## Review discipline
+
+每 task 完成派 reviewer；final whole-branch review 后 PR；Zima CR 收敛后 merge。验收逐项对账（spec 矩阵）：A1-A4 自动化记录命令与结果；U1 mac 实测标 pending；U1b 列给用户执行。