@zhuxixi/pi-agent-board 0.8.0 → 0.9.0

package/CHANGELOG.md

@@ -5,6 +5,26 @@ conventional commits by `scripts/release_helper.mjs`. Entries are
 forward-only: they begin with the first release after this file landed —
 for earlier history, see the git log and the pull-request list.
 
+## [0.9.0] - 2026-09-25
+
+### Features
+
+- **attach**: forward terminal queries to the real terminal — automatic theme works in attach sessions (issue #128) (#138)
+- **attach**: unconditional Ctrl+\ detach key, terminal-independent (issue #126) (#137)
+
+### Fixes
+
+- **runner**: probes leave attachedClients at hello (issue #130) (#142)
+- browse-mode Tab completes and drills down directories in cwd picker (issue #127) (#141)
+
+### Changes
+
+- **release**: orchestrate releases and publish from CI (#144)
+- control-reconcile flaky assertions — windowed recorder + invariant realignment (issue #140) (#143)
+- **attach**: scope A5 mid-stream seq assertion to post-snapshot window (issue #132) (#139)
+
+[0.9.0]: https://github.com/zhuxixi/pi-agent-board/compare/v0.8.0...v0.9.0
+
 ## [0.8.0] - 2026-09-23
 
 ### Features

package/README.md

@@ -93,7 +93,7 @@ From the board:
 - In Peek, press `r` to reply without attaching.
 - Press `v` for a read-only transcript, or `e` for evidence and diagnostics.
 - Press `Enter`, `Right`, or `>` to attach to the real Pi session.
-- In PTY attach mode, press `Ctrl+Left` to return to the board at any time (even mid-draft). `Left` detaches only while the child Pi reports an empty editor; otherwise (draft, or unknown editor state) it is forwarded to the child. `Ctrl+]` is not a detach key — it is passed through to the child Pi editor. When the host is disconnected, `Left` always exits.
+- In PTY attach mode, press `Ctrl+Left` to return to the board at any time (even mid-draft), or `Ctrl+\` — the unconditional escape: it detaches regardless of editor state on any terminal that forwards the raw 0x1c byte (raw, kitty, and modifyOtherKeys keyboard modes all work). `Left` detaches only while the child Pi reports an empty editor; otherwise (draft, or unknown editor state) it is forwarded to the child. `Ctrl+]` is not a detach key — it is passed through to the child Pi editor. When the host is disconnected, `Left` always exits. `Ctrl+\` caveats: on keyboard layouts where `\` sits on AltGr (e.g. German) the chord may never produce the byte — use `Ctrl+Left` there; in legacy keyboard modes `Ctrl+4` emits the same byte and also detaches; and the key is captured from the child while attached, so the child's own `Ctrl+\` binding (e.g. the vim terminal-mode prefix) is unavailable. Automatic themes also resolve correctly in attach sessions: the child's background probe (OSC 11) and color-scheme change notifications are forwarded to your real terminal, replies flow back to the child when your terminal answers, and attach re-probes the background once when it settles so the theme is right from the first frame. Set `AGENT_BOARD_FORWARD_TERMINAL_QUERIES=0` to disable this (default on); keyboard-protocol negotiation (kitty/DA) is not forwarded — it happens once at child spawn, before attach exists.
 
 ## Dashboard Workflow
 
@@ -192,7 +192,9 @@ The `e` view shows durable session evidence, including changed files, commands a
 
 ### PTY attach
 
-PTY attach opens the real interactive Pi session. `Ctrl+Left` detaches and returns to the board regardless of editor state. `Left` detaches only while the child Pi reports an empty editor; while you are editing text — or when the child's editor state is unknown (e.g. the child extension is missing) — `Left` is forwarded to the Pi editor. A disconnected host can always be exited with `Left`. `Ctrl+]` is not a detach key — it is passed through to the child Pi editor. While attached, `PageUp`, `PageDown`, `Home`, `End`, and the mouse wheel scroll local scrollback. Mouse drag or double-click selects and copies text, clicks open detected links, and middle-click paste is available on systems with the required X11 tooling.
+PTY attach opens the real interactive Pi session. `Ctrl+Left` detaches and returns to the board regardless of editor state, and `Ctrl+\` is the unconditional escape — a single raw ASCII byte (0x1c) that terminals forward unchanged in raw mode (kitty CSI-u and modifyOtherKeys encodings included), honored no matter what the child editor reports. `Left` detaches only while the child Pi reports an empty editor; while you are editing text — or when the child's editor state is unknown (e.g. the child extension is missing) — `Left` is forwarded to the Pi editor. A disconnected host can always be exited with `Left`. `Ctrl+]` is not a detach key — it is passed through to the child Pi editor. `Ctrl+\` caveats: on keyboard layouts where `\` sits on AltGr (e.g. German) the chord may never produce the byte — use `Ctrl+Left` there; in legacy keyboard modes `Ctrl+4` emits the same byte and also detaches; and the key is captured from the child while attached, so the child's own `Ctrl+\` binding (e.g. the vim terminal-mode prefix) is unavailable. While attached, `PageUp`, `PageDown`, `Home`, `End`, and the mouse wheel scroll local scrollback. Mouse drag or double-click selects and copies text, clicks open detected links, and middle-click paste is available on systems with the required X11 tooling.
+
+Automatic light/dark themes work in attach sessions too. The child Pi's background-color probe (OSC 11) and its color-scheme change notification switch are forwarded to your real terminal; replies and notifications flow back to the child when your terminal answers — a terminal that never answers keeps the dark fallback. Attach also re-probes the background once when it settles, so the theme is correct from the first frame without re-selecting it in `/settings`. All of this is on by default; set `AGENT_BOARD_FORWARD_TERMINAL_QUERIES=0` to disable it. Not covered: keyboard-protocol negotiation (kitty flags / DA1) is not forwarded — the child negotiates once at spawn, before any attach client exists, and forwarding it would retune the shared real-terminal keyboard stack — so modifier-key encoding can still differ from a directly-run Pi (the modifyOtherKeys fallback applies).
 
 The attach surface can forward terminal clipboard and image/file passthrough sequences. These behaviors can be disabled individually in [Configuration](#configuration). Cold hosts may briefly show a loading/reconnect surface while their PTY becomes ready.
 
@@ -383,19 +385,17 @@ npm run verify
 
 ## Publishing
 
-Before publishing a release, verify the package, generate the changelog, then bump, and publish — the changelog must be generated **before** `npm version`, because `npm version` commits and tags the bump, which would empty the generation range:
+Releases run through `scripts/release.mjs` and are published by CI when a GitHub Release is created. The flow checks the parts that are easy to get wrong — the changelog range, tag ancestry against `main`, and drift from a late merge — instead of assuming them. See [docs/RELEASE.md](docs/RELEASE.md) for the full process, the one-time npm trusted-publisher setup, and failure recovery.
 
 ```bash
-npm run verify
-npm run changelog -- --dry-run     # preview the next section (version = current + patch)
-npm run changelog -- patch         # inserts the section into CHANGELOG.md
-node scripts/release_helper.mjs verify   # must exit 0: no functional PR missing from the top section
-git add CHANGELOG.md && git commit -m "docs(changelog): <version>"
-npm version patch                  # bumps package.json, commits, and tags vX.Y.Z
-npm publish
+node scripts/release.mjs precheck          # gate: clean main, nothing in flight
+node scripts/release.mjs prepare minor     # changelog + verify + bump + tag + release branch
+node scripts/release.mjs open-pr 0.9.0     # push the branch and tag, open the release PR
+# merge the PR with a merge commit, then:
+node scripts/release.mjs finish 0.9.0      # GitHub Release → CI publishes to npm
 ```
 
-Use `minor`/`major` in both the changelog and `npm version` steps when appropriate. The changelog is generated from conventional commits since the last `vX.Y.Z` tag (`scripts/release_helper.mjs`, ported from the jfox release flow); review the preview before committing. The `verify` step guards against PRs merged after the changelog was generated — rerun it after any late merge and, after removing the stale top section, re-run `npm run changelog -- <bump>` if it reports missing PRs (apply refuses when the section already exists — remove the stale section first). Release notes for the GitHub Release are the top CHANGELOG section. After publishing, users install the scoped package with:
+After publishing, users install the scoped package with:
 
 ```bash
 pi install npm:@zhuxixi/pi-agent-board
@@ -406,6 +406,7 @@ The Pi package gallery uses the `pi.video` and `pi.image` URLs from `package.jso
 ## Further Reading
 
 - [Manual verification](VERIFY.md) — static checks, Pi loading, provider authentication, persistence, and dashboard flows.
+- [Release process](docs/RELEASE.md) — release commands, trusted publishing setup, and failure recovery.
 - [Product requirements](PRD.md) — original product scope and design context.
 - [Progress log](PROGRESS.md) — implementation checkpoints and known environment notes.
 - [Exploration notes](docs/EXPLORATION.md) — Pi API and integration research.

package/docs/RELEASE.md

@@ -0,0 +1,148 @@
+# Release process
+
+Releases are driven by `scripts/release.mjs` and published by CI when a GitHub
+Release is created. Four commands and one merge:
+
+```
+precheck  →  prepare <bump>  →  open-pr <version>  →  merge (merge commit!)
+          →  finish <version>  →  .github/workflows/publish.yml publishes to npm
+```
+
+`main` is protected, so a release lands as a pull request — but the npm publish
+is not tied to that PR: it is tied to the GitHub Release, which is created only
+after the PR is merged and the tag is confirmed to be on `main`.
+
+## One-time setup: the npm trusted publisher
+
+`publish.yml` publishes with **trusted publishing** (OIDC), so no `NPM_TOKEN`
+secret is stored in the repository. npm has to be told which workflow may
+publish the package — this is a one-time, per-package web step:
+
+1. Open <https://www.npmjs.com/package/@zhuxixi/pi-agent-board> and sign in as
+   the package owner.
+2. Go to **Settings** → **Trusted Publisher** → **GitHub Actions**.
+3. Fill in: organization `zhuxixi`, repository `pi-agent-board`, workflow
+   filename `publish.yml`, environment left empty.
+4. Save.
+
+Until this is configured, the CI publish step fails with an authentication
+error. Publishing locally (the pre-2026-09 flow, see "Local publish fallback"
+below) still works, because the npm account keeps its normal credentials.
+
+## Commands
+
+### `node scripts/release.mjs precheck`
+
+Read-only gate. Run it before anything else; it fails closed when the tree is
+dirty, `main` is not in sync with `origin/main`, a `release/*` PR is still open,
+the last tag is not an ancestor of `origin/main` (an orphan tag from a past
+squash merge), or there is nothing functional to release.
+
+### `node scripts/release.mjs prepare <patch|minor|major|X.Y.Z> [--dry-run]`
+
+Runs the gate, then:
+
+1. renders the new CHANGELOG section from the conventional commits since the
+   last `v*` tag,
+2. commits it as `docs(changelog): add <version> section`,
+3. runs `npm version <bump>` — one commit plus the annotated `v<version>` tag,
+4. switches to `release/v<version>`.
+
+Nothing leaves the machine. `--dry-run` prints the section and the plan without
+writing anything; review the preview before running it for real. Pick the bump
+the same way as before: features are a `minor`, fixes alone are a `patch`.
+
+### `node scripts/release.mjs open-pr <version> [--dry-run]`
+
+Pushes the release branch and the tag, then opens the PR with the CHANGELOG
+section as its body. The tag is pushed separately because tags are not covered
+by the branch protection rule.
+
+### Merge the PR with a merge commit
+
+**Do not squash the release PR.** `npm version` created the tag on a commit that
+only exists on the release branch; a merge commit brings that commit into
+`main`, a squash does not, and the tag becomes unreachable from `main`
+(`git describe` then misreads the changelog range of the next release). Use the
+**Merge pull request** button, or `gh pr merge --merge`.
+
+### `node scripts/release.mjs finish <version> [--dry-run] [--sync-main]`
+
+Run it after the merge. It fetches, verifies that `v<version>` is an ancestor of
+`origin/main`, re-checks the CHANGELOG against any functional PR merged after the
+bump, and then creates the GitHub Release with the CHANGELOG section as its
+notes. That release is the publish trigger. `--sync-main` also resets a clean
+local `main` to `origin/main`, dropping the local copy of the two release
+commits (they are content-equal to what the merge brought in).
+
+To publish without the orchestration, the underlying commands are
+`gh release create v<version> --title v<version> --notes-file <notes>` where the
+notes are `node scripts/release.mjs notes <version>`.
+
+## What CI does
+
+`.github/workflows/publish.yml` runs on `release: published`, checks out the
+tag, and:
+
+1. asserts npm is at least 11.5.1 (trusted publishing needs it; Node 24 ships
+   a newer one),
+2. asserts the tag equals `package.json`'s version,
+3. runs `npm run typecheck` and `npm test`,
+4. skips the publish when that version is already on npm, and otherwise
+5. runs `npm publish --provenance --access public`.
+
+Provenance means npm records which repository, workflow, and commit built the
+tarball, and shows it on the package page.
+
+## Recovering from a broken release
+
+**Orphan tag** (`finish` refuses with "not an ancestor of origin/main"). The
+release PR was squash-merged. Re-point the tag at the content-equivalent commit
+on `main`, then retry:
+
+```bash
+git fetch origin
+git tag -f v0.9.0 <sha on origin/main with the same content>
+git push origin v0.9.0 --force
+node scripts/release.mjs finish 0.9.0 --sync-main
+```
+
+**CHANGELOG drift** (`finish` refuses with missing PR numbers, or
+`node scripts/release_helper.mjs verify` exits 1). A functional PR merged after
+the changelog section was generated. Add the missing entries to the top section
+in a `docs(changelog)` PR, merge it, then retry — the release notes are read
+again at that point, so the fix is picked up.
+
+**The publish failed** (npm outage, trusted publisher not configured yet).
+Re-run the same tag without recreating the release: Actions → **Publish to
+npm** → **Run workflow** → enter the tag.
+
+**`npm view <package>` returns 404 right after a successful publish.** That is
+the registry's view index lagging, not a failed publish. Compare endpoints: the
+tarball, `/<package>/latest`, and `/-/package/<package>/dist-tags` answer
+immediately while the root document 404s for a few minutes. Wait; re-publishing
+the same version is rejected with a 403 and is never the fix.
+
+**Local publish fallback.** When the trusted publisher is not configured and a
+release cannot wait:
+
+```bash
+npm run verify
+npm publish --registry=https://registry.npmjs.org --access public
+```
+
+The registry must be passed explicitly: this machine defaults to
+`registry.npmmirror.com`. This path skips provenance and the CI checks, so
+prefer fixing the CI path.
+
+## CHANGELOG conventions
+
+`scripts/release_helper.mjs` renders the section from conventional commits in
+the range `<last v* tag>..HEAD`. `feat`/`fix`/`perf` become Features / Fixes /
+Performance, everything else (including `test` and `docs`) lands under Changes,
+merges and `npm version` squash subjects are skipped, and `docs(changelog):`
+subjects are ignored so changelog fixes do not feed back into the verify check.
+
+Every entry carries the PR number parsed from the trailing `(#N)`. `verify`
+fails when a functional commit's PR is missing from the top section — that is
+what keeps a late merge from shipping without release notes.

package/docs/superpowers/plans/2026-09-23-a5-mid-stream-assertion.md

@@ -0,0 +1,25 @@
+# Plan: A5 mid-stream 断言窗口修正（issue #132）
+
+Spec: `docs/superpowers/specs/2026-09-23-a5-mid-stream-assertion-design.md`（commit 5b6ec00）
+Base: main 1e832a1
+
+## Task 1: 断言修正 + stress 验证（A1, A2, A3, A4）
+
+**Files:** `test/terminal-snapshot.integration.test.mjs`（唯一，A5 mid-stream test case 体内，不动 helper/其它用例）
+
+**Changes:**
+1. **D1（A1）**: `:241` 附近——`seqsB` 构造改为窗口限定：`messagesB.filter((m) => m.type === "output" && m.seq >= endB.nextSeq).map((m) => m.seq)`；断言注释补一句为什么（订阅前 legacy 行 seq ≤ snapshotSeq < nextSeq，被过滤——引用 runner/pty-runner.mjs 广播分支行号）
+2. **D2（A2）**: `:227` 的 clientA waitFor 之后，加 `await waitFor(() => messagesB.filter((m) => m.type === "output" && m.seq >= endB.nextSeq).length >= ticks)`——显式等 socket B 追平再断言（沿用文件既有 waitFor 默认——15s，:29；A5-burst 的显式 30s 参数不在本 case）
+3. 断言本体不变（严格连续形态保留——窗口限定后就是纯协议流）
+4. **A3 stress 验证**：在 worktree 里跑 3 轮并行全量 `node --test test/*.test.mjs`（背靠背，高争用）——记录每轮 A5 mid-stream 结果；**若任何一轮 A5 mid-stream 仍失败且错误为 "strictly contiguous"** → 立即回炉报告，不许带病交付；账本 flake（subscribe_terminal / stop-finalize / A5-burst）照常隔离复跑不算回炉条件
+5. **A4**：全量其余断言绿
+
+**Verify:** `node --test test/terminal-snapshot.integration.test.mjs`（定向）+ 3 轮并行全量 + `npm run typecheck`
+
+**Commit:** `test(attach): scope A5 mid-stream seq assertion to post-snapshot window, wait for socket B catch-up explicitly (issue #132)`
+
+## Review 焦点预设
+
+- 窗口下限为什么是 `endB.nextSeq` 而非 `beginB.snapshotSeq + 1`（二者相等，用 nextSeq 更贴近协议游标语义）
+- D2 等待的 30s 天花板来源（文件 waitFor 默认），与 A5-burst 的显式 30s 参数区分
+- stress 3 轮的统计学诚实度（概率验证非根除证明，报告如实记录）

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**（待用户执行）