dsh-wsl-desktop 0.3.6 → 0.4.0

package/README.en.md

@@ -14,13 +14,13 @@ Turns a WSL distribution into a **first-class execution world** inside DSH Deskt
 ## Contents
 
 - **This page**: [Target capabilities](#target-capabilities) · [Install / Update / Uninstall](#install--update--uninstall) · [Quick start](#quick-start) · [Desktop update discipline](#desktop-update-discipline-mandatory) · [Security and trust boundaries](#security-and-trust-boundaries) · [Known limitations](#known-limitations) · [Verification](#verification) · [Development](#development) · [Release](#release)
-- **In-depth material**: [Security and trust boundaries](SECURITY.md) · [Architecture and the execution world](docs/ARCHITECTURE.en.md) · [Confinement (Linux side)](docs/CONFINEMENT.en.md) · [The fs fence](docs/FS-FENCE.en.md) · [Terminal (PTY bridge)](docs/PTY-BRIDGE.en.md) · [Verification and the SKIP ruling](docs/VERIFICATION.en.md) · [Engineering notes](docs/ENGINEERING-NOTES.en.md) · [Distro support matrix](docs/DISTRO-SUPPORT.md) · [Upstream API proposals](docs/UPSTREAM-PROPOSALS.md) · [Architecture and flow diagrams](docs/diagrams.md)
+- **In-depth material**: [Security and trust boundaries](SECURITY.md) · [Architecture and the execution world](docs/ARCHITECTURE.en.md) · [Confinement (Linux side)](docs/CONFINEMENT.en.md) · [The fs fence](docs/FS-FENCE.en.md) · [Terminal (PTY bridge)](docs/PTY-BRIDGE.en.md) · [WSL file watching](docs/WATCH.en.md) · [Verification and the SKIP ruling](docs/VERIFICATION.en.md) · [Engineering notes](docs/ENGINEERING-NOTES.en.md) · [Distro support matrix](docs/DISTRO-SUPPORT.md) · [Upstream API proposals](docs/UPSTREAM-PROPOSALS.md) · [Architecture and flow diagrams](docs/diagrams.md)
 
-> The six documents this restructure created have an English edition (linked above; the file names carry an `.en` marker) and the pair is enforced rather than trusted. The three older documents — the distro support matrix, the upstream proposals and the diagram index — are **Chinese-only**, because no English text for them exists: translating them is a separate piece of work, not a rename.
+> The bilingual documents linked above (their file names carry an `.en` marker) are enforced as pairs rather than trusted. The three older documents — the distro support matrix, the upstream proposals and the diagram index — are **Chinese-only**, because no English text for them exists: translating them is a separate piece of work, not a rename.
 
 ## Target capabilities
 
-**Honest state after live acceptance** (`verify-post-restart.mjs` all green + 18 offline suites; each item below notes its evidence strength):
+**Honest state after live acceptance** (`verify-post-restart.mjs`: its rows that have run are green, but **the two live search rows have not run yet** and await the operator's live acceptance this round, plus 20 offline suites; each item below notes its evidence strength):
 
 | # | Capability | Status |
 |---|---|---|
@@ -29,7 +29,7 @@ Turns a WSL distribution into a **first-class execution world** inside DSH Deskt
 | ③ | 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.
 
 ## Install / Update / Uninstall
 
@@ -69,16 +69,18 @@ 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).
 
 **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).
+
 ## Verification
 
 ```powershell
-node scripts/verify-all.mjs          # all offline suites (18)
+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
 ```
 
@@ -106,6 +108,7 @@ lib/wsl/world.js        Distro discovery, the wsl.exe execution core, directory
 lib/wsl/shell.js        ShellExecutor implementation (WSL bash + confinement hookup)
 lib/wsl/fs.js           LocalFileSystem subclass (9P backend + path dialects)
 lib/wsl/publish.js      The overwrite publication's wait bound (retry + measured tail; pure module, independently testable)
+lib/wsl/watch.js        Polling strategies for file watching (pure module, independently testable)
 lib/wsl/subprocess.js   SubprocessRuntime implementation (pipes + terminal; delegates to the host subprocess)
 lib/wsl/pty.js          Terminal handle: two processes driving the in-distro PTY bridge
 lib/wsl/terminal-bridge.py  The PTY bridge running inside the distro (python3 stdlib, zero install)

package/README.md

@@ -14,11 +14,11 @@
 ## 目录
 
 - **本页**：[目标能力](#目标能力) · [安装 / 更新 / 卸载](#安装--更新--卸载) · [快速开始](#快速开始) · [桌面更新纪律](#桌面更新纪律强制) · [安全与信任边界](#安全与信任边界) · [已知限制](#已知限制) · [校验](#校验) · [开发](#开发) · [发版](#发版)
-- **深入材料**：[安全与信任边界](SECURITY.md) · [架构与执行世界](docs/ARCHITECTURE.md) · [Linux 侧约束](docs/CONFINEMENT.md) · [fs 工具的围栏](docs/FS-FENCE.md) · [终端 PTY 桥](docs/PTY-BRIDGE.md) · [校验与 SKIP 裁定](docs/VERIFICATION.md) · [工程笔记](docs/ENGINEERING-NOTES.md) · [发行版支持矩阵](docs/DISTRO-SUPPORT.md) · [上游 API 提案](docs/UPSTREAM-PROPOSALS.md) · [架构与流程图](docs/diagrams.md)
+- **深入材料**：[安全与信任边界](SECURITY.md) · [架构与执行世界](docs/ARCHITECTURE.md) · [Linux 侧约束](docs/CONFINEMENT.md) · [fs 工具的围栏](docs/FS-FENCE.md) · [终端 PTY 桥](docs/PTY-BRIDGE.md) · [WSL 文件变更监听](docs/WATCH.md) · [校验与 SKIP 裁定](docs/VERIFICATION.md) · [工程笔记](docs/ENGINEERING-NOTES.md) · [发行版支持矩阵](docs/DISTRO-SUPPORT.md) · [上游 API 提案](docs/UPSTREAM-PROPOSALS.md) · [架构与流程图](docs/diagrams.md)
 
 ## 目标能力
 
-**活体验收通过后的诚实状态**（`verify-post-restart.mjs` 全绿 + 离线 18 套件；下面每条都注明证据强度）：
+**活体验收通过后的诚实状态**（`verify-post-restart.mjs` 已跑过的行全绿，但**搜索的两条活体行尚未运行**、待操作者本轮活体验收，加离线 20 套件；下面每条都注明证据强度）：
 
 | # | 能力 | 状态 |
 |---|---|---|
@@ -27,7 +27,7 @@
 | ③ | 同一实例里 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`——写在「已知限制」里，不藏。
 
 ## 安装 / 更新 / 卸载
 
@@ -67,16 +67,18 @@
 
 ## 已知限制
 
-**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)。
 
 **约束覆盖不到 `/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)。
+
 ## 校验
 
 ```powershell
-node scripts/verify-all.mjs          # 全部离线套件（18 个）
+node scripts/verify-all.mjs          # 全部离线套件（20 个）
 node scripts/verify-all.mjs --live   # 追加需要已安装插件 + 运行中宿主的套件
 ```
 
@@ -104,6 +106,7 @@ lib/wsl/world.js        发行版发现、wsl.exe 执行核、目录事实
 lib/wsl/shell.js        ShellExecutor 实现（WSL bash + 约束接入）
 lib/wsl/fs.js           LocalFileSystem 子类（9P 后端 + 路径方言）
 lib/wsl/publish.js      覆盖发布的等待边界（重试 + 实测尾部；纯模块，可独立测试）
+lib/wsl/watch.js        文件变更监听的轮询策略（纯模块，可独立测试）
 lib/wsl/subprocess.js  SubprocessRuntime 实现（管道 + 终端；委托宿主 subprocess）
 lib/wsl/pty.js         终端句柄：两个进程驱动发行版内的 PTY 桥
 lib/wsl/terminal-bridge.py 发行版内运行的 PTY 桥（python3 标准库，零安装）

package/lib/index.js

@@ -14,7 +14,7 @@
  */
 
 import { randomBytes, timingSafeEqual } from 'node:crypto'
-import { existsSync } from 'node:fs'
+import { existsSync, watch as nativeFsWatch } from 'node:fs'
 import { mkdir, readFile, writeFile } from 'node:fs/promises'
 import { homedir } from 'node:os'
 import { dirname, join } from 'node:path'
@@ -27,6 +27,7 @@ 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 { WATCH_INTERVAL_MS } from './wsl/watch.js'
 
 /** Loader row identity, also used in diagnostics. */
 export const name = 'wsl-desktop'
@@ -106,6 +107,15 @@ 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 `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' }
@@ -299,6 +309,7 @@ async function materializePresets(ctx, distro, generation, previous) {
         subprocessPath: SUBPROCESS_MODULE,
         shellPath: SHELL_MODULE,
         fsPath: FS_MODULE,
+        searchPath: SEARCH_MODULE,
         ...(distro !== undefined ? { distro } : {}),
         ...(sourceDir !== undefined ? { sourceDir } : {}),
       })
@@ -634,6 +645,108 @@ const METHODS = {
         } catch (error) {
           record('fs.roundtrip', { error: error instanceof Error ? error.message : String(error) })
         }
+
+        // Watch rows: the strategy the provider installs, driven the way a consumer
+        // drives it, and mutated from INSIDE the distribution — the case the rows are
+        // about. No model-facing tool reaches `fs.watch`, so the provider's own entry
+        // is the only place this can be observed.
+        if (fs !== undefined && shell !== undefined && typeof workspaceCwd === 'string' && workspaceCwd.startsWith('\\\\wsl.localhost\\')) {
+          /**
+           * The policy every mutation below carries. A request that omits `sandboxPolicy`
+           * makes `bash-sandbox`'s `resolve()` substitute the session-less default, and the
+           * confinement then binds a root that does NOT contain this scratch workspace —
+           * measured: every mutation failed EROFS ("Read-only file system"). The fallback is
+           * not a MISSING root: `lib/wsl/confinement.js` binds the command's cwd when a policy
+           * carries none. It is a root from the deployment's own world, which
+           * `lib/wsl/paths.js` maps to `/mnt/<drive>/…`. The tool layer never meets this
+           * because `tool-bash` stamps the resolved policy into its request; a direct
+           * provider call has to stamp it itself.
+           */
+          const workspaceWritePolicy = { mode: 'workspace-write', workspaceRoot: workspaceCwd }
+
+          /**
+           * Arm one watch, mutate the target from the distribution, report what arrived.
+           * @param {{ targetKey: string }} target - the resolved watch target.
+           * @param {string} command - the shell command that changes it.
+           * @returns {Promise<object>} the observation row.
+           */
+          const observeWatch = async (target, command) => {
+            const controller = new AbortController()
+            const linuxPath = fs.processPath(target)
+            let notified = 0
+            let watchError = null
+            let unwatch
+            try {
+              unwatch = await fs.watch(target, (error) => {
+                if (error === undefined) notified += 1
+                else watchError = String(error?.message ?? error)
+              }, controller.signal)
+              const execution = await runShellSpec(shell, shell.resolve({ command, workdir: workspaceCwd, sandboxPolicy: workspaceWritePolicy }))
+              // The mutation's outcome is REPORTED, not assumed. A refused write otherwise
+              // leaves `notified: 0` with a null `watchError`, which reads exactly like a
+              // watcher that armed and observed nothing — two different facts this row must
+              // not conflate.
+              const result = await execution.result()
+              if (result.exitCode !== 0) {
+                const failure = `the mutation failed: exit ${result.exitCode ?? 'null'} ${(result.stderr?.text ?? '').slice(0, 200)}`.trim()
+                // Both facts survive: a watcher error and a failed mutation can coexist, and
+                // reporting only one of them drops the other from the row.
+                watchError = watchError === null ? failure : `${watchError}; ${failure}`
+              }
+              // The window is 5 polling periods: measured latency is 2-52ms, so 1500ms is
+              // ~29x the slowest measured case, and a poll that never runs still reddens.
+              await new Promise((resolve) => setTimeout(resolve, 5 * WATCH_INTERVAL_MS))
+            } catch (error) {
+              watchError = error instanceof Error ? error.message : String(error)
+            } finally {
+              controller.abort()
+              if (unwatch !== undefined) await unwatch().catch(() => {})
+            }
+            return { notified, watchError, linuxPath }
+          }
+
+          // The probe file EXISTS before the watch is armed — that is the point of the row.
+          // `fs.watchFile` on an ABSENT path notifies once immediately at arming (measured
+          // Node semantics, pinned offline in scripts/verify-watch.mjs, because an injected
+          // io can never fire by itself: only the default seam shows the baseline is real).
+          // With the file absent, `notified > 0` would be satisfied by that arming baseline
+          // alone — even if the in-distribution append below were never observed. An
+          // existing file is silent until it changes, so a notification here can only be
+          // the append.
+          const fileTarget = await fs.resolve('dsh-wsl-watch-probe.txt', { cwd: workspaceCwd })
+          // Created through the shell this block already runs its mutations with. A create
+          // that FAILED must not read as a false green, so its outcome is reported in the
+          // row: an absent path would notify from its arming baseline and pass on nothing.
+          const probeCreated = await runShellSpec(shell, shell.resolve({ command: `printf 'x\\n' > '${fs.processPath(fileTarget)}'`, workdir: workspaceCwd, sandboxPolicy: workspaceWritePolicy }))
+            .then((execution) => execution.result())
+            .catch((error) => ({ exitCode: null, stderr: { text: String(error?.message ?? error) } }))
+          record('fs.watch.file', probeCreated.exitCode === 0
+            ? await observeWatch(fileTarget, `printf 'x\\n' >> '${fs.processPath(fileTarget)}'`)
+            : {
+              notified: 0,
+              watchError: `the probe file could not be created: exit ${probeCreated.exitCode ?? 'null'} ${probeCreated.stderr?.text?.slice(0, 200) ?? ''}`.trim(),
+              linuxPath: fs.processPath(fileTarget),
+            })
+
+          const dirTarget = await fs.resolve('.', { cwd: workspaceCwd })
+          const dirCommand = `printf 'x\\n' > '${fs.processPath(dirTarget)}/dsh-wsl-watch-entry.txt'`
+          record('fs.watch.dir', await observeWatch(dirTarget, dirCommand))
+          await runShellSpec(shell, shell.resolve({ command: `rm -f '${fs.processPath(dirTarget)}/dsh-wsl-watch-entry.txt'`, workdir: workspaceCwd, sandboxPolicy: workspaceWritePolicy }))
+            .then((execution) => execution.result()).catch(() => {})
+
+          // Why the override exists, recorded rather than assumed: if a future host or
+          // WSL release makes this work, this row says so and the override can go.
+          let nativeThrew = false
+          let nativeCode = null
+          try {
+            const probe = nativeFsWatch(fileTarget.targetKey, () => {})
+            probe.close()
+          } catch (error) {
+            nativeThrew = true
+            nativeCode = error?.code ?? null
+          }
+          record('fs.watch.native', { threw: nativeThrew, code: nativeCode, path: fileTarget.targetKey })
+        }
       }
 
       const subprocess = realmService('subprocess')
@@ -720,6 +833,88 @@ 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

package/lib/wsl/confinement.js

@@ -176,10 +176,11 @@ function helperGateScript(helperPath) {
     'ok=yes',
     // TYPE FIRST, and by an explicit test rather than by 'test -x': a root:root
     // 0755 DIRECTORY satisfies -x, uid 0, no write bits and every ancestor test,
-    // so the ownership predicate answered yes for a directory — measured, as
-    // zcluo, with /opt/.../dir-helper (drwxr-xr-x root root). Only the version
-    // half refused it, and only because sudo cannot exec a directory. The gate
-    // claims to require an executable FILE; this is where it measures that.
+    // so the ownership predicate answered yes for a directory — measured, as an
+    // ordinary (non-root) user, with /opt/.../dir-helper (drwxr-xr-x root root).
+    // Only the version half refused it, and only because sudo cannot exec a
+    // directory. The gate claims to require an executable FILE; this is where it
+    // measures that.
     '[ -f "$f" ] || ok=no',
     // A symlink is REFUSED, not resolved. The grant names a PATH, so the link
     // and its target are both part of the trust decision: resolving would have

package/lib/wsl/fs.js

@@ -26,6 +26,7 @@ import z from '@deepseek-ai/schemastery'
 import { crossDistroUnc, isUnderHost, writableHostRootsFor } from './fence.js'
 import { isWindowsPathShaped, joinWslUnc, mntToWindowsPath, parseWslUnc, windowsToMntPath } from './paths.js'
 import { publishReplace } from './publish.js'
+import { startWatch, watchStrategyFor } from './watch.js'
 
 /** Share-level errors that mean "this primitive is unavailable", not "the operation failed". */
 const PRIMITIVE_UNAVAILABLE = new Set(['ENOTSUP', 'EOPNOTSUPP', 'EPERM', 'EINVAL'])
@@ -233,6 +234,33 @@ export class WslFileSystem extends LocalFileSystem {
     throw new FsError(`cannot write "${target.displayPath}": file access denied under ${deniedUnder}`, 'FS_SANDBOX_DENIED')
   }
 
+  /**
+   * Observe one target through a strategy this share supports.
+   *
+   * Overridden because the inherited implementation cannot initialize here: it
+   * watches a DIRECTORY in both branches (the target, or a file target's `dirname`)
+   * and its primitive, `fs.watch`, throws `EISDIR` on `\\wsl.localhost\…` — for a
+   * file target as well as a directory one (measured; docs/WATCH.md). Unoverridden,
+   * `ctx.fs.watch` rejects for every WSL target and the workspace file tree keeps
+   * only manual refresh.
+   *
+   * The host path comes from the TARGET KEY, never from `processPath`: that returns
+   * the LINUX spelling for the model and for subprocesses, so resolving it on this
+   * side would put a watcher on `E:\home\…` for `/home/…` — observing something else
+   * entirely, and silently, since the wrong path usually does not exist.
+   * @param {{ targetKey: string }} target - the resolved target.
+   * @param {(error?: Error) => void} changed - invalidation callback.
+   * @param {AbortSignal} signal - cancels watcher initialization.
+   * @returns {Promise<() => Promise<void>>} the disposer once observation is active.
+   */
+  async watch(target, changed, signal) {
+    signal.throwIfAborted()
+    const info = await this.stat(target, signal)
+    signal.throwIfAborted()
+    const kind = info?.type === 'directory' ? 'directory' : info === undefined ? 'absent' : 'file'
+    return startWatch({ hostPath: target.targetKey, strategy: watchStrategyFor(kind), changed, signal })
+  }
+
   /**
    * Fence the write by the per-call policy, then delegate to the inherited
    * atomic write with the checked target.

package/lib/wsl/preset.js

@@ -202,12 +202,13 @@ export function hasClassifierVerdict(name) {
  * @param {string} options.subprocessPath - module specifier of the WSL subprocess provider.
  * @param {string} options.shellPath - module specifier of the WSL shell executor.
  * @param {string} options.fsPath - module specifier of the WSL filesystem provider.
+ * @param {string} options.searchPath - module specifier of this plugin's WSL search tools.
  * @param {string | undefined} options.distro - distribution for paths that do not name one.
  * @param {boolean} options.includeEditor - whether the source preset mounted the string-replace editor.
  * @param {Map<string, object>} [options.toolConfig] - config the pruned host-world rows carried, keyed by row id.
  * @returns {object} the group entry.
  */
-export function buildWorldGroup({ subprocessPath, shellPath, fsPath, distro, includeEditor, toolConfig }) {
+export function buildWorldGroup({ subprocessPath, shellPath, fsPath, searchPath, distro, includeEditor, toolConfig }) {
   // The pin belongs under `config`, NOT as a sibling row key. The loader hands a
   // plugin ONLY `options.config` (`registry.plugin(plugin, this.options.config, …)`),
   // and nothing relocates row keys into it — so as a bare `distro` key every
@@ -236,6 +237,19 @@ export function buildWorldGroup({ subprocessPath, shellPath, fsPath, distro, inc
     toolRow('tool-bash', '@deepseek-ai/dsh-tool-bash'),
     toolRow('tool-fs', '@deepseek-ai/dsh-tool-fs'),
     ...(includeEditor ? [toolRow('str-replace-editor', '@deepseek-ai/dsh-tool-str-replace-editor')] : []),
+    // Searching is re-mounted the same way bash and fs are: the two NAMES the model already
+    // knows, over a module of THIS plugin. It cannot be a carried host row — the host's
+    // search package is removed by WORLD_MODULE_NAMES, so naming it back would recreate the
+    // row the transform exists to drop (its argv[0] is a packaged Windows ripgrep binary).
+    //
+    // Both rows name ONE module, so the row's config is what tells that instance which tool
+    // to register: toolRow() is deliberately NOT used here — it would reapply the pruned
+    // host search row's config (a `sampleOverCapGlobResults`/caps shape this module does not
+    // read, and whose `tool` field would be absent), failing the row at mount time instead of
+    // mounting it. The tool name is also exactly `grep`/`glob`: callers invoke tools by name,
+    // and the row id is a separate thing that happens to spell the same.
+    { id: 'grep', name: searchPath, config: { tool: 'grep' } },
+    { id: 'glob', name: searchPath, config: { tool: 'glob' } },
   ]
   return {
     id: 'wsl-world',
@@ -306,11 +320,12 @@ function cloneRow(row) {
  * @param {string} options.subprocessPath - module specifier of the WSL subprocess provider.
  * @param {string} options.shellPath - module specifier of the WSL shell executor.
  * @param {string} options.fsPath - module specifier of the WSL filesystem provider.
+ * @param {string} options.searchPath - module specifier of this plugin's WSL search tools.
  * @param {string | undefined} options.distro - distribution for paths that do not name one.
  * @param {string | undefined} options.sourceDir - directory the source preset lives in.
  * @returns {{ plugins: object[], removed: string[], unclassified: { id: string | null, name: unknown }[] }} the variant rows, what was dropped, and the rows kept without a classifier verdict — an unreadable specifier, or a tool-family module that is neither removed nor verdicted-kept.
  */
-export function buildVariantPlugins(basePlugins, { subprocessPath, shellPath, fsPath, distro, sourceDir }) {
+export function buildVariantPlugins(basePlugins, { subprocessPath, shellPath, fsPath, searchPath, distro, sourceDir }) {
   const kept = []
   const removed = []
   /** Rows kept without a classifier verdict — both shapes the prune() branches record. */
@@ -392,6 +407,6 @@ export function buildVariantPlugins(basePlugins, { subprocessPath, shellPath, fs
     const pruned = prune(row)
     if (pruned !== null) kept.push(pruned)
   }
-  kept.push(buildWorldGroup({ subprocessPath, shellPath, fsPath, distro, includeEditor, toolConfig }))
+  kept.push(buildWorldGroup({ subprocessPath, shellPath, fsPath, searchPath, distro, includeEditor, toolConfig }))
   return { plugins: kept, removed, unclassified }
 }