dsh-wsl-desktop 0.3.7 → 0.5.0

package/README.en.md

@@ -20,16 +20,16 @@ Turns a WSL distribution into a **first-class execution world** inside DSH Deskt
 
 ## Target capabilities
 
-**Honest state after live acceptance** (`verify-post-restart.mjs` all green + 19 offline suites; each item below notes its evidence strength):
+**Honest state after live acceptance** (`verify-post-restart.mjs`, latest real run: **58 PASS / 0 FAIL**, tail `NO AUTOMATED FAILURES; 3 manual step(s) pending`, `EXIT=0` — including the two live search rows and the persistent-shell rows; **3 browser-only manual steps remain**, listed in [The persistent shell](docs/PERSISTENT-SHELL.en.md#manual-verification-checklist-browser-only-not-automatable) — plus 20 offline suites; each item below notes its evidence strength):
 
 | # | Capability | Status |
 |---|---|---|
 | ① | The workspace can pick a Linux directory inside a WSL distro | Dialog and host calls implemented and live-verified (listDir/checkPath/resolveHome/workspace registration and cleanup); **in-browser interaction manually confirmed by the operator** (gating flow, directory browsing, and terminal panel all normal) |
-| ② | shell / file tools / subprocess / terminal inside that workspace work in WSL, and host commands can be invoked from WSL | **Live acceptance PASS**: binding (the create request names the preset), shell inside the distro, fs tools addressing Linux paths, out-of-bounds write rejection, subprocess POSIX environment, bash tool, tool-layer constraints; terminal transport covered by the PTY suite |
+| ② | shell / file tools / subprocess / terminal inside that workspace work in WSL, and host commands can be invoked from WSL | **Live acceptance PASS**: binding (the create request names the preset), shell inside the distro, fs tools addressing Linux paths, out-of-bounds write rejection, subprocess POSIX environment, bash tool, tool-layer constraints; terminal transport covered by the PTY suite. **The model's `bash` is a persistent PTY shell inside the distribution, keeping cwd and environment variables across calls** (live-verified: two calls read back the same state; the gap list is in [The persistent shell](docs/PERSISTENT-SHELL.en.md)) |
 | ③ | Windows and WSL workspaces coexist in the same instance | **Live acceptance PASS**: Windows workspaces stay on the host preset (PowerShell available, no bash); WSL sessions run the confined realm in parallel |
 | ④ | Linux-side sandbox constraints on the WSL side | **Shell side fixed and live-verified**: at runtime, all `rw` mounts are enumerated and remounted read-only one by one (observed `/mnt/c`, `/dev/shm`, `/run/user/<uid>` going WRITABLE → READONLY); any failure rejects (exit code 97 preserved); `enforcement` honestly reports `partial`. **fs-side fence implemented and live-verified** (out-of-bounds write rejected, PASS — see [The fs tool fence](docs/FS-FENCE.md)) |
 
-**Which capabilities are qualified**: the evidence strength is the wording of the status column above. The `grep` / `glob` tools do not exist in a WSL session and the terminal has no `stdio.control` — both are stated under "Known limitations" rather than left out.
+**Which capabilities are qualified**: the evidence strength is the wording of the status column above. The terminal has no `stdio.control` — it is stated under "Known limitations" rather than left out. The persistent shell's gaps are stated there too, with the authoritative list in [The persistent shell](docs/PERSISTENT-SHELL.en.md).
 
 ## Install / Update / Uninstall
 
@@ -69,10 +69,12 @@ After every DSH Desktop update, the plugin may break because of harness internal
 
 ## Known limitations
 
-**The grep / glob tools do not exist in a WSL session.** `tool-fs-search` is launched via `ctx.subprocess.spawn()` (`search-core.ts:238`), but its argv[0] is the **bundled Windows rg.exe** from `@vscode/ripgrep` (`search-core.ts:174-178`) — it does not exist inside the distro and cannot work with Linux arguments. So the WSL preset removes it from the execution world, and the model in a WSL session can only use bash's `grep` / `find` (both present in the distro). This is a capability regression, not an omission — making it equivalent would require giving the WSL world its own search implementation.
+**The grep / glob tools are available in a WSL session, backed by the distribution's own `grep` / `find`.** The host's two rows are still removed, for the two measured facts: `tool-fs-search` is launched via `ctx.subprocess.spawn()` (`search-core.ts:238`), but its `argv[0]` is the **bundled Windows rg.exe** from `@vscode/ripgrep` (`search-core.ts:174-178`) — it does not exist inside the distro and cannot work with Linux arguments; the distro, meanwhile, ships `/usr/bin/grep` and `/usr/bin/find` (measured: `command -v rg` inside the distro answers nothing). So the `wsl-world` group mounts the two names back onto this plugin's own implementation (`lib/wsl/search-tool.js`), and the model calls `grep` / `glob` in a WSL session as usual — **with the distribution's semantics**: POSIX ERE (no `\d`, no `(?i)`) · `.gitignore` not parsed (only the six VCS directories are skipped) · dotted directories searched · `include` matching the base name only and without brace expansion · patterns interpreted relative to the search root, with `*` and `**/` crossing `/` · a record whose path contains `:` possibly dropped or silently mis-attributed · binary files never matched · a capped result not saved anywhere. **That list is a summary; the document is authoritative for the eight gaps** (gaps 5 and 6 are merged into one item here, and the last item, "a capped result not saved anywhere", is a limit rather than a gap). The eight gaps, the limits, what was not measured and how to verify it yourself are in [Search inside the distribution](docs/SEARCH.en.md).
 
 **The terminal goes through the PTY bridge, and PTC's `stdio.control` (fd channel) stays explicitly rejected** — `wsl.exe` cannot forward arbitrary descriptors. How the bridge is driven, and its measured preconditions, are in [docs/PTY-BRIDGE.md](docs/PTY-BRIDGE.md).
 
+**The persistent shell's gap summary**: the model's `bash` is a persistent PTY shell inside the distribution, but it carries two load-bearing boundaries — **(1) the host's `ctx.sandbox` wraps the `wsl.exe` argv**, and this repository's own judgement is that the host sandbox **cannot confine** it (measured: it still runs after the wrapping, which is why the realm provides its own `sandbox` provider and turns that layer into an in-distro fence); **(2) the terminal path has no PID namespace**, and the GUI's web terminal is **unfenced by design** — what is confined is the model's `bash`, not what the user types in the terminal panel. **That list is a summary; the document is authoritative for the gaps**: the nine gaps, the limits, what was not measured, the 3-step manual checklist and how to verify it yourself are in [The persistent shell](docs/PERSISTENT-SHELL.en.md).
+
 **Confinement does not cover `/dev`, `/proc`, `/sys` or interop**, which is reported honestly in `enforcement: 'partial'`; and the session user's retained passwordless sudo grant can bypass the file fence — see [SECURITY.md](SECURITY.md).
 
 **File-change tracking inside a WSL workspace polls; it is not event-driven.** `fs.watch` throws `EISDIR` on the distribution's 9P share (for a file target as well as a directory one), so the host backend's chokidar watcher cannot initialize for any WSL target. The plugin polls on the host side instead: a directory compares its entry set (one `readdir` per 300ms; measured 0ms CPU per 3s and 2-3ms latency in this process) and a file — or a path that does not exist yet — watches its stat (`fs.watchFile`, measured 0ms CPU per 3s and 52ms). **A directory target is invalidated by entry-set changes only**: adds, removes and renames are seen; the CONTENT change of a file inside it is not — watch that file's own path to follow it. Mechanisms, measurements and what was not measured are in [WSL file watching](docs/WATCH.en.md).
@@ -80,7 +82,7 @@ After every DSH Desktop update, the plugin may break because of harness internal
 ## Verification
 
 ```powershell
-node scripts/verify-all.mjs          # all offline suites (19)
+node scripts/verify-all.mjs          # all offline suites (20)
 node scripts/verify-all.mjs --live   # additionally the suites needing the installed plugin + a running host
 ```
 

package/README.md

@@ -18,16 +18,16 @@
 
 ## 目标能力
 
-**活体验收通过后的诚实状态**（`verify-post-restart.mjs` 全绿 + 离线 19 套件；下面每条都注明证据强度）：
+**活体验收通过后的诚实状态**（`verify-post-restart.mjs` 最近一次实跑：**58 PASS / 0 FAIL**、尾部 `NO AUTOMATED FAILURES; 3 manual step(s) pending`、`EXIT=0`——包括搜索的两条活体行与常驻 shell 的那几条；**剩 3 条浏览器专属的人工项**，清单见 [常驻 shell](docs/PERSISTENT-SHELL.md#人工核验清单浏览器专属不可自动化)，加离线 20 套件；下面每条都注明证据强度）：
 
 | # | 能力 | 状态 |
 |---|---|---|
 | ① | 工作区可选择 WSL 发行版里的 Linux 目录 | 对话框与宿主调用已实现并活体通过（listDir/checkPath/resolveHome/工作区注册与清理）；**浏览器内交互已由操作者人工确认**（门控流、目录浏览、终端面板均正常） |
-| ② | 该工作区内的 shell / 文件工具 / subprocess / 终端 在 WSL 里工作，且可从 WSL 调用宿主机命令 | **活体验收 PASS**：绑定（创建请求命名 preset）、shell 进发行版、fs 工具 Linux 寻址、越界写拒绝、subprocess POSIX 环境、bash 工具、工具层约束；终端传输由 PTY 套件覆盖 |
+| ② | 该工作区内的 shell / 文件工具 / subprocess / 终端 在 WSL 里工作，且可从 WSL 调用宿主机命令 | **活体验收 PASS**：绑定（创建请求命名 preset）、shell 进发行版、fs 工具 Linux 寻址、越界写拒绝、subprocess POSIX 环境、bash 工具、工具层约束；终端传输由 PTY 套件覆盖。**模型侧的 `bash` 是发行版内的常驻 PTY shell，cwd 与环境变量跨调用保留**（活体验证：两次调用读数一致；缺口清单见 [常驻 shell](docs/PERSISTENT-SHELL.md)） |
 | ③ | 同一实例里 Windows 与 WSL 工作区并存 | **活体验收 PASS**：Windows 工作区停留在宿主 preset（PowerShell 可用、无 bash），WSL 会话并行运行 confined realm |
 | ④ | WSL 侧的 Linux 沙箱约束 | **shell 侧已修并活体验证**：运行时枚举所有 `rw` 挂载逐个改只读（实测 `/mnt/c`、`/dev/shm`、`/run/user/<uid>` 从 WRITABLE 变 READONLY）、失败即拒（保留退出码 97）、`enforcement` 如实报 `partial`。**fs 侧围栏已实现并活体验证**（越界写拒绝 PASS，见 [fs 工具的围栏](docs/FS-FENCE.md)）|
 
-**哪些能力有保留**（证据强度就是上表状态列的措辞）：`grep` / `glob` 工具在 WSL 会话里不存在，终端不支持 `stdio.control`——两条都写在「已知限制」里，不藏。
+**哪些能力有保留**（证据强度就是上表状态列的措辞）：终端不支持 `stdio.control`——写在「已知限制」里，不藏。常驻 shell 的缺口同样写在「已知限制」里，权威清单在 [常驻 shell](docs/PERSISTENT-SHELL.md)。
 
 ## 安装 / 更新 / 卸载
 
@@ -67,10 +67,12 @@
 
 ## 已知限制
 
-**grep / glob 工具在 WSL 会话里不可用。** `tool-fs-search` 虽然通过 `ctx.subprocess.spawn()` 启动（`search-core.ts:238`），但它的 argv[0] 是 `@vscode/ripgrep` 提供的**打包 Windows rg.exe**（`search-core.ts:174-178`），在发行版里既不存在、也无法用 Linux 参数工作。所以 WSL 预设会把它从执行世界里移除，WSL 会话的模型只能用 bash 的 `grep` / `find`（两者在发行版里都在）。这算是一个能力回退，不是遗漏——要做成对等的，需要给 WSL 世界提供自己的搜索实现。
+**grep / glob 工具在 WSL 会话里可用，后端是发行版自己的 `grep` / `find`。** 宿主那两行依然被移除，理由是实测的两件事：`tool-fs-search` 虽然通过 `ctx.subprocess.spawn()` 启动（`search-core.ts:238`），但它的 `argv[0]` 是 `@vscode/ripgrep` 提供的**打包 Windows rg.exe**（`search-core.ts:174-178`）——在发行版里既不存在、也无法用 Linux 参数工作；而发行版自带 `/usr/bin/grep` 与 `/usr/bin/find`（实测：发行版里 `command -v rg` 回答为空）。所以 `wsl-world` 组把这两个名字挂回本插件自己的实现（`lib/wsl/search-tool.js`），模型在 WSL 会话里照常调用 `grep` / `glob`——**但语义是发行版工具的**：POSIX ERE（没有 `\d`、`(?i)`）· 不解析 `.gitignore`（只排除六个 VCS 目录）· 点目录会被搜到 · `include` 只匹配 basename 且没有花括号 · 模式按搜索根相对解释、`*` 与 `**/` 跨 `/` · 路径含 `:` 的记录可能被丢弃或被静默错配 · 二进制文件永不被匹配 · 达到上限的截断不落盘。**这串要点是摘要，缺口的权威清单在文档里**（文档八条中第 5、6 条在这里并成了一条；末条「截断不落盘」是限额，不是缺口）。八条缺口、限额、未测项与怎么自己验，见 [发行版内搜索](docs/SEARCH.md)。
 
 **终端走 PTY 桥，PTC 的 `stdio.control`（fd 通道）明确拒绝**——`wsl.exe` 无法转发任意描述符。桥的驱动方式与实测前提见 [docs/PTY-BRIDGE.md](docs/PTY-BRIDGE.md)。
 
+**常驻 shell 的缺口摘要**：模型侧的 `bash` 是发行版内的常驻 PTY shell，但它有两条要命的边界——**（1）宿主 `ctx.sandbox` 会包一层 `wsl.exe` 的 argv**，而本仓自己判定宿主沙箱对它**无法约束**（实测：包装之后仍然跑得起来，所以 realm 里自建了 `sandbox` 提供者，把这一层变成发行版内的约束）；**（2）终端这条路没有 PID namespace**，而 GUI 的网页终端按设计**不受 fence 约束**——受约束的是模型的 `bash`，不是用户在终端面板里敲的那条。**这串只是摘要，缺口的权威清单在文档里**：九条缺口、限额、未测项、3 条人工核验清单与怎么自己验，见 [常驻 shell](docs/PERSISTENT-SHELL.md)。
+
 **约束覆盖不到 `/dev`、`/proc`、`/sys` 与 interop**，如实报在 `enforcement: 'partial'` 里；而会话用户保留的免密 sudo 授权可绕过文件围栏，闭合路径见 [SECURITY.md](SECURITY.md)。
 
 **WSL 工作区里的文件变更跟踪是轮询的，不是事件驱动的。** 发行版的 9P 共享上 `fs.watch` 会抛 `EISDIR`（文件与目录目标都抛），宿主后端的 chokidar 监听因此在 WSL 目标上根本无法初始化；插件改为在宿主侧轮询——目录看条目集合（每 300ms 一次 `readdir`，实测本进程 0ms CPU/3s、延迟 2–3ms），文件与尚不存在的路径走 `fs.watchFile`（每 300ms 一次 `stat`，实测 0ms CPU/3s、延迟 52ms）。**目录目标只对条目集合变化失效**：新增、删除、改名可见，目录内某个文件的**内容**变化不可见——要盯着某个文件，就按文件路径监听它。机制、实测与未测项见 [WSL 文件变更监听](docs/WATCH.md)。
@@ -78,7 +80,7 @@
 ## 校验
 
 ```powershell
-node scripts/verify-all.mjs          # 全部离线套件（19 个）
+node scripts/verify-all.mjs          # 全部离线套件（20 个）
 node scripts/verify-all.mjs --live   # 追加需要已安装插件 + 运行中宿主的套件
 ```
 

package/lib/index.js

@@ -26,7 +26,8 @@ import {
 import { buildVariantPlugins } from './wsl/preset.js'
 import { setLocalSubprocess } from './wsl/host-refs.js'
 import { checkLinuxPath, defaultDistro, defaultWorkspaceUnc, listDistros, listLinuxDir, resolveDistroHome, runWslShell } from './wsl/world.js'
-import { joinWslUnc, parseWslUnc, windowsToMntPath } from './wsl/paths.js'
+import { joinWslUnc, parseWslUnc, shellQuote, windowsToMntPath } from './wsl/paths.js'
+import { sweepOrphanFifos } from './wsl/pty.js'
 import { WATCH_INTERVAL_MS } from './wsl/watch.js'
 
 /** Loader row identity, also used in diagnostics. */
@@ -107,6 +108,24 @@ function variantIdFor(preset) {
 const SUBPROCESS_MODULE = pathToFileURL(join(HERE, 'wsl', 'subprocess.js')).href
 const SHELL_MODULE = pathToFileURL(join(HERE, 'wsl', 'shell.js')).href
 const FS_MODULE = pathToFileURL(join(HERE, 'wsl', 'fs.js')).href
+/**
+ * The realm's own confinement provider. It exists so the realm's `sandbox` service — the
+ * one `terminal-bash` resolves for every mode but `danger-full-access` — is answered from
+ * inside the distribution instead of by the host's `sandbox-local`, whose Windows rung
+ * grants an ACL on the policy's workspace root and fails on this realm's 9P UNC spelling
+ * (`GetNamedSecurityInfoW`, Win32 1). The row that mounts it is the one that makes the
+ * group's `sandbox: true` isolation load-bearing.
+ */
+const SANDBOX_MODULE = pathToFileURL(join(HERE, 'wsl', 'sandbox.js')).href
+/**
+ * The realm's own `grep`/`glob` module. Named here, beside the three providers, for the same
+ * reason they are: a row must name a module the LOADER can import, and a `file://` URL is the
+ * one spelling that survives every generation. The two search rows both name this module (the
+ * row's `config.tool` picks which of the two tools it registers), because the search names the
+ * model already knows have to be re-mounted by something this plugin owns — the host's search
+ * package is removed inside a WSL realm, not reused.
+ */
+const SEARCH_MODULE = pathToFileURL(join(HERE, 'wsl', 'search-tool.js')).href
 
 /** Last preset materialization outcome, reported through the route. */
 let presetState = { status: 'pending' }
@@ -300,6 +319,8 @@ async function materializePresets(ctx, distro, generation, previous) {
         subprocessPath: SUBPROCESS_MODULE,
         shellPath: SHELL_MODULE,
         fsPath: FS_MODULE,
+        sandboxPath: SANDBOX_MODULE,
+        searchPath: SEARCH_MODULE,
         ...(distro !== undefined ? { distro } : {}),
         ...(sourceDir !== undefined ? { sourceDir } : {}),
       })
@@ -517,6 +538,10 @@ const METHODS = {
      * @param {object} value - observed facts.
      */
     const record = (name, value) => steps.push({ name, ...value })
+    // Declared OUTSIDE the try so the `finally` can release it: the disposal capability lives on
+    // the handle (`dispose()`), not on the agent, and a binding scoped to the try made that
+    // capability unreachable from the one block whose job is to release it.
+    let handle
     let agent
     try {
       const agents = hostCtx.get('agents')
@@ -534,7 +559,7 @@ const METHODS = {
       // path passes cwd. The default is now exercised by verify-world/check-2.
       const workspaceCwd = cwd ?? (await defaultWorkspaceUnc({ wslPath: routeWslPath })).uncPath
       const sessionId = `wsl-selftest-${Date.now()}`
-      const handle = await agents.create({ sessionId, meta: { cwd: workspaceCwd, agentPreset: preset } })
+      handle = await agents.create({ sessionId, meta: { cwd: workspaceCwd, agentPreset: preset } })
       agent = handle?.agent ?? handle
       record('create', {
         ok: true,
@@ -823,10 +848,102 @@ const METHODS = {
           text: JSON.stringify(pwshTool.result ?? null).slice(0, 200),
         })
 
+        // The realm's own `grep`/`glob`: the host removes both names from a WSL world
+        // (their argv[0] is a packaged Windows ripgrep) and this plugin mounts them back
+        // on the distribution's own grep/find. NO offline suite can drive them — the row
+        // module imports harness packages — so these two rows are the only observation of
+        // the chain end to end, and `scripts/verify-post-restart.mjs` reads them.
+        //
+        // The step names are `tool.search.*` (singular `tool`, as the plan spells them),
+        // NOT the `tools.*` the sibling rows use: the suite pairs with these exact strings,
+        // and both files are the only two places they appear.
+        //
+        // The fixture names, the token and the line number are spelled AGAIN in
+        // `scripts/verify-post-restart.mjs`, which asserts on their Linux paths — the same
+        // pairing `dsh-wsl-selftest.txt` already has between the two files. Three fixture
+        // facts, each one earning its place:
+        //
+        //   - the probe carries the token on LINE 3, so a hit pins the line NUMBER rather
+        //     than merely "some line of the right file";
+        //   - `.git/x/hidden.ts` carries the same token and sits where the glob pattern
+        //     reaches, so a search that stopped excluding the six VCS names prints an extra
+        //     path (the shape Task 1's measurement removed) instead of passing quietly;
+        //   - `src/a/b/deep.ts` is TWO directories below the pattern's own prefix, which is
+        //     what pins "the pattern is anchored to the search root": an unanchored
+        //     `src/*.ts` matches NOTHING (measured), so this file either appears or the
+        //     anchoring broke.
+        //
+        // Written through the shell executor, not `fs`, and that is deliberate: the
+        // fixtures must exist in the world the search PROCESS runs in. A file written
+        // through the Windows-side share and a `grep` started through wsl.exe are only
+        // guaranteed to agree while the share serves the same running distribution —
+        // measured on this machine, after a host restart the share kept serving a stale
+        // view that the distribution could not see at all.
+        let searchFixtureError = null
+        const searchToken = 'dsh-wsl-search-needle'
+        if (shell === undefined || typeof workspaceCwd !== 'string' || !workspaceCwd.startsWith('\\\\wsl.localhost\\')) {
+          // A host (Windows) session has no distribution shell and no search tools; the
+          // rows still record, so the suite's WSL run can tell "no fixture" from "no row".
+          searchFixtureError = 'the WSL shell executor is unavailable, so the search fixtures were not created'
+        } else {
+          const searchFixtureCommand = [
+            'mkdir -p src/a/b src/.git/x',
+            `printf '%s\\n' 'the search probe, written by the selftest' 'second line, so the match is not on line one' '${searchToken}' > src/dsh-wsl-search-probe.ts`,
+            `printf '%s\\n' '${searchToken}' > src/.git/x/hidden.ts`,
+            `printf '%s\\n' 'the nested file a root-relative pattern must find' > src/a/b/deep.ts`,
+          ].join(' && ')
+          // The policy is mandatory, not decorative: a `shell.resolve` with none gets the
+          // session-less default root, which does NOT contain this scratch workspace —
+          // measured, every write then failed EROFS. Same object the watch mutations and
+          // the fs roundtrip above stamp, for the same reason.
+          const searchFixturePolicy = { mode: 'workspace-write', workspaceRoot: workspaceCwd }
+          const searchFixture = await runShellSpec(shell, shell.resolve({
+            command: searchFixtureCommand,
+            workdir: workspaceCwd,
+            sandboxPolicy: searchFixturePolicy,
+          }))
+            .then((execution) => execution.result())
+            .catch((error) => ({ exitCode: null, stderr: { text: String(error?.message ?? error) } }))
+          if (searchFixture.exitCode !== 0) {
+            searchFixtureError = `the search fixtures could not be written: exit ${searchFixture.exitCode ?? 'null'} ${(searchFixture.stderr?.text ?? '').slice(0, 200)}`.trim()
+          }
+        }
+        // Both rows fold the fixture outcome into `ok`: a row that could not be given its
+        // fixture must not read as a passing observation of the tool.
+        //
+        // Both also record at 800 bytes, where their siblings use 400: this page carries
+        // the probe AND the nested path (each an absolute path under the scratch) plus the
+        // value those paths came from, and a cut that removed the `lineNumber` would red
+        // the assertion for a reason that is not the tool's. Measured on the real
+        // distribution output with a real scratch spelling: 309 (grep) and 356 (glob)
+        // bytes — 444 bytes of headroom, which is the point of the larger budget.
+        const grepSearch = await invoke('grep', { pattern: searchToken })
+        record('tool.search.grep', {
+          ok: grepSearch.ok && searchFixtureError === null,
+          error: grepSearch.error ?? searchFixtureError,
+          text: JSON.stringify(grepSearch.result ?? null).slice(0, 800),
+        })
+        const globSearch = await invoke('glob', { pattern: 'src/**/*.ts' })
+        record('tool.search.glob', {
+          ok: globSearch.ok && searchFixtureError === null,
+          error: globSearch.error ?? searchFixtureError,
+          text: JSON.stringify(globSearch.result ?? null).slice(0, 800),
+        })
+
         // A tool resolves its policy from the session's logged permission state
         // (`tool-bash/src/index.ts:199`), which a programmatically created
         // session does not have. Recording one is what makes the tool layer's
         // confinement observable here.
+        //
+        // Do NOT delete this append, and do not move it below the persistent calls: it is
+        // LOAD-BEARING for the fence row (`tools.persistFence`) further down, in a way that is
+        // invisible from there. The backend's guard only refuses a mode CHANGE, so if the
+        // logged mode were left at `danger-full-access` the later append would be a no-op and
+        // be accepted — and the fence row would redden on a guard that is working perfectly.
+        // This append is what makes that change a transition. `tools.bashConfined` itself has
+        // no reader in `scripts/verify-post-restart.mjs` any more (the two rows that read it
+        // were replaced when the realm's `bash` became the persistent tool), so it stays as the
+        // observation of the confined path plus the owner of this append, not as an assertion.
         try {
           agent.session.append('sandbox/mode', { mode: 'workspace-write' })
           const confinedTool = await invoke('bash', {
@@ -843,6 +960,197 @@ const METHODS = {
         } catch (error) {
           record('tools.bashConfined', { ok: false, error: error instanceof Error ? error.message : String(error) })
         }
+
+        // The persistent shell, measured on the TWO calls that distinguish it from a
+        // one-shot `bash`: the first establishes a cwd and exports a variable, the second
+        // reads both back. A one-shot tool answers the second call with a fresh process, so
+        // this pair is what makes "state survives" observable instead of asserted. The third
+        // observation rides in the second call: a write OUTSIDE the workspace ($HOME is one
+        // level above this scratch), which the confined path refuses — if the file appears,
+        // whatever answered `bash` is not confined inside the distribution.
+        //
+        // It sits AFTER the `sandbox/mode` append above on purpose: the backend refuses a
+        // mode change while a persistent terminal session is open
+        // (`terminal-bash/src/index.ts:52-62`), so a probe placed earlier would turn that
+        // append into a refusal and redden the two confinement rows for the wrong reason.
+        //
+        // The step names are spelled AGAIN in scripts/verify-post-restart.mjs — the same
+        // two-file pairing `dsh-wsl-selftest.txt` and `tool.search.*` already have.
+        const persistToken = 'dsh-wsl-persist-probe'
+        const persistA = await invoke('bash', {
+          command: `mkdir -p .dsh-wsl-persist-cwd && cd .dsh-wsl-persist-cwd && export DSH_WSL_PERSIST_PROBE=${persistToken}`,
+          description: 'selftest: establish a state a persistent shell must keep',
+        })
+        record('tools.bashPersist.a', {
+          ok: persistA.ok,
+          error: persistA.error ?? null,
+          text: JSON.stringify(persistA.result ?? null).slice(0, 400),
+        })
+        const persistB = await invoke('bash', {
+          command: `pwd; echo "$DSH_WSL_PERSIST_PROBE"; echo probe > "$HOME/.dsh-wsl-persist-outside"; echo write-exit=$?`,
+          description: 'selftest: read the state back and try a write outside the workspace',
+        })
+        record('tools.bashPersist.b', {
+          ok: persistB.ok,
+          error: persistB.error ?? null,
+          text: JSON.stringify(persistB.result ?? null).slice(0, 800),
+        })
+
+        // F8's guard, observed from the realm: once a persistent terminal session exists, a
+        // `sandbox/mode` change must be REFUSED with the backend's own sentence. It runs after
+        // the persistent calls on purpose — before them there is no owner activity to guard.
+        //
+        // Wrapped in its own try, and the catch records rather than rethrows: the backend
+        // refuses by THROWING, and `session.append` throws before committing
+        // (`packages/core/session/src/index.ts:876-902`, pinned by its own suite), so an
+        // unguarded append here would leave the session's logged mode untouched AND escape
+        // into the outer catch, where it would kill every row below and report one `error`
+        // step instead. The refusal is the OBSERVATION, so it is recorded as a step.
+        try {
+          agent.session.append('sandbox/mode', { mode: 'danger-full-access' })
+          record('tools.persistFence', { refused: false, reason: 'the mode change was accepted while a persistent terminal session was open' })
+        } catch (error) {
+          record('tools.persistFence', { refused: true, reason: error instanceof Error ? error.message : String(error) })
+        }
+
+        // The clock-domain row the controller added to this task (R47): the orphan sweep's age
+        // decision must be made entirely INSIDE the distribution.
+        //
+        // Why this exists at all: the sweep was changed to one command with two answers
+        // (`find … -print`, a marker, `find … -mmin +2 -print`) precisely so the age
+        // comparison never crosses a clock domain (`lib/wsl/pty.js:417-489`). The offline pin
+        // for that change is a SOURCE-SHAPE pin (`scripts/verify-pty-handle.mjs`), because no
+        // fixture can make two clocks disagree — `touch -t` sets the time explicitly, and
+        // skewing a distribution's clock is out of bounds. R41 accepted the shape pin on the
+        // condition that the BEHAVIOURAL evidence lands here. Without it, a future "fix" that
+        // reintroduced a second clock source (`stat -c %Y` in the distro, compared against
+        // `Date.now()` on the host) would redden nothing.
+        //
+        // What it does NOT do: it does not FAKE skew. It proves the host's clock is not an
+        // input — the strongest honest evidence available here — by planting two LEGACY names
+        // in the distro (one fresh, one backdated), running the real sweep, and then running it
+        // again with this process's `Date.now()` shifted by 45 days. A sweep that consulted the
+        // host clock at all would change a verdict across that shift.
+        //
+        // Cleanup is unconditional and one command: the probe's own names carry this host's
+        // pid, so a crashed run's residue is collectable by the next generation's sweep too.
+        const sweepNames = { young: `/tmp/dsh-pty-${process.pid}-t3sweepyoung.fifo`, aged: `/tmp/dsh-pty-${process.pid}-t3sweepaged.fifo` }
+        // The distribution comes from the workspace this session runs in — the same source
+        // `shell.run` and the search fixtures use — not from a config default: on a host whose
+        // default distribution differs from the workspace's, the probe would then plant its
+        // names in one distribution and sweep another, and read `youngKept` off a directory
+        // where nothing was ever planted. A host (Windows) session has no distribution at all,
+        // and says so instead of reporting four absent rows.
+        const sweepTarget = typeof workspaceCwd === 'string' ? parseWslUnc(workspaceCwd) : null
+        const sweepDistro = sweepTarget?.distro
+        // ONE runner for the probe's distribution calls, with the configured `wsl.exe` path
+        // threaded through the same named select the rest of this file uses. FOUR source sites
+        // (`sweepList`, `sweepPlant`, the clock read and the cleanup) issuing EIGHT invocations
+        // per run — three listings, two plants, the clock read, the bridge probe below and the
+        // cleanup — not four calls. `scripts/verify-world.mjs` pins this file's probe SITES by
+        // count, and the `...sweepSelect` spread above is what carries the configured path
+        // through this runner; that pin now covers THIS form structurally as well
+        // (`insideCall` + `carrier` in the structural row beside the count table), so dropping
+        // the spread reddens it instead of silently reverting to the default `wsl.exe`.
+        const sweepSelect = { wslPath: routeWslPath }
+        const sweepShell = (command) => runWslShell({ distro: sweepDistro, linuxCwd: '/', loginShell: false, command, ...sweepSelect })
+        const sweepList = async () => String((await sweepShell('ls -1 /tmp/dsh-pty-*.fifo 2>/dev/null; echo END')).stdout ?? '')
+          .split('\n').map((line) => line.trim()).filter((line) => line.startsWith('/tmp/dsh-pty-'))
+        const sweepPlant = () => sweepShell(
+          `rm -f ${shellQuote(sweepNames.young)} ${shellQuote(sweepNames.aged)}`
+          + ` && mkfifo ${shellQuote(sweepNames.young)}`
+          + ` && mkfifo ${shellQuote(sweepNames.aged)}`
+          // 2020-01-01: older than any creation window, by six years.
+          + ` && touch -t 202001010000 ${shellQuote(sweepNames.aged)}`,
+        )
+        // THE POSITIVE CONTROL for criterion 2's bridge half (R49(d), M4). It is read HERE,
+        // while this selftest's own persistent PTY is still open — the session is disposed in
+        // the outer `finally`, so this is the last point at which a bridge of this run is
+        // guaranteed to exist. Without it the suite's "this run added no bridge" clause passes
+        // by construction on an empty baseline: a pgrep that matches nothing is
+        // indistinguishable from a bridge that was never created, and a broken pattern would
+        // read as a clean run forever. Recorder discipline is the same as every other probe:
+        // a host-world session records the REASON it could not observe, never an empty row.
+        let bridgeProbe
+        try {
+          if (sweepDistro === undefined) throw new Error('this session runs in the host world, so there is no bridge to observe')
+          const listing = await sweepShell(`pgrep -f -- '[P]TY bridge for the WSL execution world' || true`)
+          const pids = String(listing.stdout ?? '')
+            .split('\n').map((line) => line.trim()).filter((line) => /^\d+$/.test(line)).sort()
+          bridgeProbe = { ok: true, distro: sweepDistro, pids, count: pids.length }
+        } catch (error) {
+          bridgeProbe = { ok: false, error: error instanceof Error ? error.message : String(error) }
+        }
+        record('tools.persistBridge', bridgeProbe)
+        let sweepProbe
+        try {
+          // A Windows session cannot host this probe: the sweep is a distribution-side
+          // operation and there is no distribution to sweep. Recorded as the REASON, never as
+          // an empty row — the suite's row has to be able to tell "no distribution" from
+          // "the probe did not run".
+          if (sweepDistro === undefined) throw new Error('this session runs in the host world, so there is no distribution to sweep')
+          // The measurement (not an assertion): how far apart the two clocks actually are on
+          // THIS machine. Recorded so the report can state it instead of assuming agreement.
+          const hostMs = Date.now()
+          const clock = await sweepShell('date +%s; date -u +%Y-%m-%dT%H:%M:%SZ')
+          const [distroSecondsText, distroIso] = String(clock.stdout ?? '').trim().split('\n')
+          await sweepPlant()
+          const planted = await sweepList()
+          const removedFirst = await sweepOrphanFifos({ distro: sweepDistro }, { wslPath: routeWslPath })
+          const afterFirst = await sweepList()
+          // The host-side shift. `Date.now` is the only host clock this process offers the
+          // sweep, so patching it is the whole of "the host's reading changed".
+          //
+          // DECLARED AS A SHARED-INPUT MUTATION, because that is what it is: `Date.now` is
+          // PROCESS-GLOBAL on a live host, and anything else in this process that reads
+          // `Date.now()` inside the patched window would be stamped 45 days into the future —
+          // `session.append`'s event timestamps (`packages/core/session/src/index.ts:820`) are
+          // the concrete example. Two things keep that exposure small and are the reason this
+          // shape is acceptable at all: the window holds ONE await (the sweep), and it is
+          // restored in `finally` on every path. The reading that follows the sweep is taken
+          // OUTSIDE the window on purpose, so the window cannot grow back by an edit that
+          // slides a line.
+          await sweepPlant()
+          const realNow = Date.now
+          const HOST_SHIFT_MS = 45 * 24 * 3600 * 1000
+          let removedShifted
+          try {
+            Date.now = () => realNow() + HOST_SHIFT_MS
+            removedShifted = await sweepOrphanFifos({ distro: sweepDistro }, { wslPath: routeWslPath })
+          } finally {
+            Date.now = realNow
+          }
+          // Unpatched by construction: this is the observation of what the patched sweep left,
+          // and it must not itself run under a fake clock.
+          const afterShift = await sweepList()
+          sweepProbe = {
+            distro: sweepDistro,
+            distroSeconds: Number(distroSecondsText),
+            hostSeconds: hostMs / 1000,
+            deltaSeconds: Math.round((hostMs / 1000 - Number(distroSecondsText)) * 1000) / 1000,
+            distroIso: distroIso ?? null,
+            planted,
+            youngKept: afterFirst.includes(sweepNames.young),
+            agedSwept: !afterFirst.includes(sweepNames.aged),
+            removedFirst,
+            afterFirst,
+            hostShiftMs: HOST_SHIFT_MS,
+            youngKeptAfterShift: afterShift.includes(sweepNames.young),
+            agedSweptAfterShift: !afterShift.includes(sweepNames.aged),
+            removedShifted,
+            afterShift,
+          }
+        } catch (error) {
+          sweepProbe = { error: error instanceof Error ? error.message : String(error) }
+        } finally {
+          // Unconditional: the fixtures are this host's, and a throw above must not leave them
+          // for the operator to find. Best-effort by design — a cleanup fault must not mask
+          // the observation, and each name is collectable by a later sweep regardless.
+          if (sweepDistro !== undefined) {
+            await sweepShell(`rm -f ${shellQuote(sweepNames.young)} ${shellQuote(sweepNames.aged)}`).catch(() => {})
+          }
+        }
+        record('tools.persistSweep', sweepProbe)
       }
       return { steps }
     } catch (error) {
@@ -853,11 +1161,43 @@ const METHODS = {
       return { steps }
     } finally {
       // A selftest session is a live agent in the registry; release it.
+      //
+      // THE RELEASE WAS A NO-OP, and that is what the live gate measured (root cause A of the
+      // 2026-10-19 17:23 run). `agent?.dispose?.()` is an OPTIONAL call on the AGENT, and the
+      // harness's agent surface has no `dispose` — `dispose()` belongs to the HANDLE
+      // (`AgentHandle`, `packages/core/agent/src/index.ts:160-163`), which is the capability that
+      // stops and drains the loop, unregisters the agent and unwinds its scope. So the await
+      // resolved immediately having done nothing, the session's PTY was never torn down, and the
+      // suite that read the bridge/FIFO delta right after this returned was reading a session
+      // that had never been released. (The optional call is WHY it failed silently: `?.` turned a
+      // missing method into a no-op instead of a TypeError.)
+      //
+      // `?? fallback` is kept for hosts whose create() answers a bare agent (the same
+      // dual-dispatch the create step above documents); on those the disposal is still
+      // best-effort, and the recorded step says which shape ran so a reader can tell.
+      let teardown
+      const startedAt = Date.now()
       try {
-        await agent?.dispose?.()
-      } catch {
-        // Disposal failure does not change what the checks observed.
+        const target = handle ?? agent
+        const method = target?.dispose
+        if (typeof method !== 'function') {
+          teardown = { ok: false, error: 'the created value exposes no dispose() — nothing was released' }
+        } else {
+          await method.call(target)
+          teardown = { ok: true, via: target === handle ? 'handle' : 'agent', elapsedMs: Date.now() - startedAt }
+        }
+      } catch (error) {
+        // Disposal failure does not change what the checks observed, but it MUST be visible:
+        // a throw here is the difference between "the session was released" and "the suite is
+        // about to read the residue of a session that is still alive".
+        teardown = { ok: false, error: error instanceof Error ? error.message : String(error), elapsedMs: Date.now() - startedAt }
       }
+      // RECORDED AFTER the await, which is the whole point: this step is the suite's permission
+      // to read the bridge/FIFO delta. A row that reads without it is reading mid-teardown, and
+      // measured on the 17:23 run that produced a bridge and a FIFO belonging to a session whose
+      // disposal had not run at all (root cause A). It is recorded even when disposal FAILED —
+      // `ok: false` is the suite's signal that the residue it finds is real, not a timing artefact.
+      record('tools.persistTeardown', teardown)
     }
   },
 

package/lib/wsl/confined-argv.js

@@ -0,0 +1,63 @@
+/**
+ * The argv a PTY-attached spawn gets when the realm's sandbox confines it.
+ *
+ * This module builds NO fence of its own. The fence — mount namespace, workspace bind,
+ * private tmpfs, read-only sweep, postconditions, setpriv drop — is
+ * `buildConfinedCommand` (`./confinement.js`), the ONE builder the realm's shell
+ * executor also runs (`./shell.js`), and the runner it selects is the distribution's
+ * own (`sudo -n <dsh-wsl-confine> …` or `sudo -n unshare …`). What is added here is the
+ * presentation: the terminal spawn needs an ARGV, the builder produces the shell COMMAND
+ * that establishes the fence, so the command is handed to `bash -lc` and the caller's own
+ * program travels into the fence as `exec`'d argv.
+ *
+ * Why the caller's argv is re-quoted instead of passed through: both runners take the
+ * command as ONE shell word and hand it to the distribution's shell after their own
+ * privilege drop (`shell.js` passes its caller's shell source the same way). Re-quoting
+ * each element with `shellQuote` and prefixing `exec` makes the distribution run exactly
+ * the program and arguments the caller named — none of them can be re-split, globbed or
+ * re-read as syntax by the intervening shells — and `exec` keeps the interactive process
+ * as the PTY's direct child, so terminal signals and the foreground group reach it
+ * instead of stopping at a wrapper shell.
+ *
+ * The login flag matches the shell executor's own translation of a confined command into
+ * argv (`buildLinuxShellArgv` with `loginShell: true`). The inner command is `exec`'d, so
+ * no SECOND login shell is started: profiles run once, for the fence wrapper.
+ * @module dsh-wsl-desktop/wsl/confined-argv
+ */
+
+import { buildConfinedCommand } from './confinement.js'
+import { shellQuote } from './paths.js'
+
+/**
+ * Wrap one terminal spawn's argv in the distribution's in-distro confinement.
+ *
+ * Pure: every policy fact it needs is an argument, and the fence text comes from
+ * `buildConfinedCommand` unchanged. It refuses exactly what that builder refuses (a
+ * `workspace-write` fence for a root under the private `/tmp`, a control character in the
+ * workspace spelling) and throws its errors as they are — the caller classifies them, and
+ * swallowing one would run a terminal that is not fenced while reporting a fence.
+ * @param {object} options - the spawn's argv and its resolved confinement inputs.
+ * @param {readonly string[]} options.argv - the program and arguments the terminal must run.
+ * @param {string} options.linuxCwd - absolute Linux working directory for the fence.
+ * @param {'read-only' | 'workspace-write'} options.mode - the confined mode.
+ * @param {string | undefined} options.workspaceLinuxRoot - writable root for `workspace-write`.
+ * @param {{ uid: string, gid: string, home: string, name?: string }} options.identity - the drop identity.
+ * @param {boolean | undefined} options.noNewPrivs - whether the direct runner may set NO_NEW_PRIVS.
+ * @param {'helper' | 'sudo-unshare'} options.runner - the resolved runner.
+ * @param {boolean} [options.isolateProcesses] - add a PID namespace (never for an interactive PTY).
+ * @returns {string[]} the argv to spawn on the PTY.
+ * @throws Error when `argv` is empty, and whatever `buildConfinedCommand` refuses.
+ */
+export function buildConfinedTerminalArgv({ argv, linuxCwd, mode, workspaceLinuxRoot, identity, noNewPrivs, runner, isolateProcesses }) {
+  if (!Array.isArray(argv) || argv.length === 0) {
+    throw new Error('wsl-sandbox: 需要一个非空的 argv')
+  }
+  const program = argv.map((element) => shellQuote(element)).join(' ')
+  return [
+    'bash',
+    '-lc',
+    buildConfinedCommand({ command: `exec ${program}`, linuxCwd, mode, workspaceLinuxRoot, identity, noNewPrivs, runner, isolateProcesses }),
+  ]
+}
+
+export default buildConfinedTerminalArgv