dsh-wsl-desktop 0.3.7 → 0.4.0

package/README.en.md

@@ -20,7 +20,7 @@ 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`: 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,7 +69,7 @@ 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).
 
@@ -80,7 +80,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,7 +18,7 @@
 
 ## 目标能力
 
-**活体验收通过后的诚实状态**（`verify-post-restart.mjs` 全绿 + 离线 19 套件；下面每条都注明证据强度）：
+**活体验收通过后的诚实状态**（`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,7 +67,7 @@
 
 ## 已知限制
 
-**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)。
 
@@ -78,7 +78,7 @@
 ## 校验
 
 ```powershell
-node scripts/verify-all.mjs          # 全部离线套件（19 个）
+node scripts/verify-all.mjs          # 全部离线套件（20 个）
 node scripts/verify-all.mjs --live   # 追加需要已安装插件 + 运行中宿主的套件
 ```
 

package/lib/index.js

@@ -107,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' }
@@ -300,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 } : {}),
       })
@@ -823,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/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 }
 }

package/lib/wsl/search-tool.js

@@ -0,0 +1,436 @@
+/**
+ * The realm's `grep` and `glob`: the host's two names, run by the distribution's own tools.
+ *
+ * A WSL realm removes the host's search tools ON PURPOSE (their `argv[0]` is a packaged
+ * WINDOWS ripgrep binary), and this module is what puts the two NAMES back — one row per
+ * tool inside the `wsl-world` group, exactly the way `bash` and `fs` are re-mounted there.
+ * Both rows name this ONE module, and `config.tool` is what says which of the two tools
+ * that instance registers: two rows naming one module would otherwise register the same
+ * tool twice, and a row that names neither is refused at mount time rather than mounting
+ * nothing in silence.
+ *
+ * What is deliberately NOT the host's, and each one is declared in the tool's own
+ * description as well (the wording lives THERE, where the model reads it before calling —
+ * repeating the list here would be a second contract to keep in sync):
+ *
+ *  - **the backend**: `/usr/bin/grep -E` and `/usr/bin/find` as the distribution ships them;
+ *  - **the pattern dialect**: POSIX extended for `grep`; for `find` the search root anchors
+ *    the glob and `*` crosses `/` (measured, findutils 4.10.0);
+ *  - **the ignore behaviour**: `.gitignore` is not read, only the six VCS directories are
+ *    skipped, and — unlike the host, whose ripgrep skips every hidden entry — dotted
+ *    directories ARE searched;
+ *  - **`include`**: fnmatch over each file's BASE NAME, so braces and directory parts never
+ *    match anything (`grep --include` semantics, measured in the distribution);
+ *  - **the cap**: a result at the limit is TRUNCATED and says so, and nothing is spilled to
+ *    a file (the host reports where it saved the complete result; this world keeps none).
+ *
+ * The VALUE of each tool is the host's own shape (`{matches:[{path,lineNumber,line}]}`,
+ * `{root,paths}`) — the parsers' `text` field is mapped to `line` here, and `truncated` is
+ * NOT a field: it is a fact about what the text withheld, so it is stated in the text, which
+ * is where the host states it too.
+ *
+ * Failures are classified by `searchFailure` (the host's two names) and raised as a
+ * {@link HarnessError} subclass, so the registry exposes `{ name, code }` on the result the
+ * same way it does for the host's own `SearchError`.
+ * @module dsh-wsl-desktop/wsl/search-tool
+ */
+
+import { HarnessError } from '@deepseek-ai/dsh-llm'
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import { cutToBytes, globArgv, grepArgv, parseGlobOutput, parseGrepOutput, searchFailure } from './search.js'
+
+/** Cordis plugin name used by loader diagnostics. */
+export const name = 'wsl-search'
+
+/**
+ * Services these tools use. `fs` is the REALM's filesystem provider — the `wsl-world`
+ * group isolates `fs` — which is what turns the model's path into the Linux absolute one
+ * the distribution's own tools can open; `workingDirectory` is the session workspace that
+ * a relative path resolves against.
+ */
+export const inject = ['tools', 'systemPrompt', 'subprocess', 'fs', 'workingDirectory']
+
+/**
+ * The caps, mirroring `@deepseek-ai/dsh-tool-fs-search`'s defaults field for field, so the
+ * two worlds' searches are the same SIZE even though their engines differ. They are module
+ * constants rather than a plugin config because this module is mounted twice in one group
+ * (one instance per tool) and a config that had to be repeated on both rows would be a
+ * second place to drift; a deployment that needs different numbers adds a config then.
+ */
+const MAX_MATCHES = 250
+const MAX_LINE_BYTES = 2000
+const MAX_RESULTS = 100
+const RAW_OUTPUT_MAX_BYTES = 20_000_000
+const GRACE_MS = 3_000
+const STDERR_MAX_BYTES = 64 * 1024
+const TIMEOUT_MS = 30_000
+
+/**
+ * The parsers are asked to RETAIN EVERYTHING; the cap is applied where the model's text is
+ * written ({@link renderGrep} / {@link renderGlob}).
+ *
+ * That split is forced, not preferred: `output.render(args, value)` is the only place a tool
+ * writes the text, the `value` it receives is the frozen snapshot the registry validated, and
+ * a cap applied any earlier would leave the text unable to tell "exactly at the cap" from
+ * "the cap withheld the rest" — the silent-cut shape this whole capability refuses. The host
+ * splits it in exactly the same place (its parsers return every record and its
+ * `retainGrepMatches`/`globCardPage` cut inside `render`).
+ *
+ * What bounds "keep everything" is therefore the stdout budget at the spawn seam
+ * ({@link RAW_OUTPUT_MAX_BYTES}): a run that produced more than that is refused loudly below
+ * rather than parsed partially, so "all the records" is always a number the seam retained.
+ */
+const RETAIN_ALL_MATCHES = { maxMatches: Number.POSITIVE_INFINITY, maxLineBytes: Number.POSITIVE_INFINITY }
+const RETAIN_ALL_PATHS = { maxResults: Number.POSITIVE_INFINITY }
+
+/** One failed search, carrying the host's classification code on the result. */
+class SearchError extends HarnessError {}
+
+/**
+ * Raise the classified failure for a failed run, a failed launch, or a print that could not
+ * be read. `searchFailure` owns WHICH class this is; this function only carries it.
+ * @param {unknown} error - the failure, with `exitCode` attached when the run exited.
+ * @param {string} toolName - `'grep'` or `'glob'`.
+ */
+function raise(error, toolName) {
+  const { code, message } = searchFailure(error, toolName)
+  throw new SearchError(message, code)
+}
+
+/**
+ * Raise for a run that COMPLETED with an exit code neither tool accepts, handing the code
+ * and the diagnostic tail to {@link searchFailure} — the exit code is what tells a rejected
+ * grep pattern apart from every other failure.
+ * @param {string} toolName - `'grep'` or `'glob'`.
+ * @param {number} exitCode - the process's exit code.
+ * @param {string} stderr - the retained stderr tail.
+ */
+function raiseExit(toolName, exitCode, stderr) {
+  const detail = stderr.trim()
+  const error = new Error(detail.length === 0 ? `${toolName} exited ${exitCode}` : detail)
+  error.exitCode = exitCode
+  raise(error, toolName)
+}
+
+/**
+ * Resolve the model's path to the search root both tools run against.
+ *
+ * The root is a LINUX ABSOLUTE path, and this is the site where that happens — the reason
+ * the vectors never meet a dash-leading path. MEASURED (findutils 4.10.0): `find -- -dashdir`
+ * reports "unknown predicate `-dashdir'" and exits 1, a LOUD failure, which is why the vector
+ * layer accepts such a path instead of guarding against it; and it cannot arrive here, because
+ * the resolution below turns the model's path into an absolute one and an absolute path never
+ * begins with `-`. (Task 2 left those two facts in `globArgv`'s comment and named this site —
+ * this is that site.)
+ *
+ * The resolution is the realm's OWN filesystem provider rather than a second path grammar
+ * grown here: `ctx.fs` is the service the `fs` row mounts into this group, and it is what
+ * knows the Windows/UNC spellings of the distribution's files.
+ * @param {object} ctx - the realm's plugin context.
+ * @param {object} exec - the tool-execution context (owner agent and abort signal).
+ * @param {{ path?: string }} input - the model's arguments.
+ * @returns {Promise<{ workdir: string, root: string }>} the session workspace (the spawn cwd)
+ *   and the absolute Linux search root.
+ */
+async function resolveRoot(ctx, exec, input) {
+  const workdir = await ctx.workingDirectory.ensure(exec.agent, exec.signal)
+  const target = await ctx.fs.resolve(input.path ?? '.', { cwd: workdir, signal: exec.signal })
+  return { workdir, root: ctx.fs.processPath(target) }
+}
+
+/**
+ * Run one search command inside the distribution and return what it printed.
+ *
+ * Only the TRANSPORT failures are raised here (a launch that never happened, a kill, a print
+ * the seam could not retain whole): which exit codes are acceptable is the calling tool's own
+ * business, because `grep` and `find` disagree about it. A nonzero exit is returned to the
+ * caller, which raises it with its code attached — that code is the whole classification.
+ * @param {object} ctx - the realm's plugin context.
+ * @param {object} exec - the tool-execution context (abort signal).
+ * @param {string} toolName - `'grep'` or `'glob'`; named in every failure message.
+ * @param {string[]} argv - the vector from `grepArgv`/`globArgv`.
+ * @param {string} workdir - the session workspace, as the subprocess provider maps it.
+ * @returns {Promise<{ stdout: string, stderr: string, exitCode: number }>} the run's output.
+ */
+async function runCommand(ctx, exec, toolName, argv, workdir) {
+  let handle
+  try {
+    handle = ctx.subprocess.spawn({
+      argv,
+      cwd: workdir,
+      stdio: {
+        stdin: 'ignore',
+        stdout: { maxBytes: RAW_OUTPUT_MAX_BYTES },
+        stderr: { maxBytes: STDERR_MAX_BYTES },
+      },
+      graceMs: GRACE_MS,
+      signal: exec.signal,
+    })
+  } catch (error) {
+    // A launch that never happened (a NUL in argv, a signal already aborted, a provider that
+    // refused) is reported without claiming execution began — and it is SEARCH_FAILED, the
+    // same class as the `ENOENT` of a distribution without grep/find.
+    raise(error, toolName)
+  }
+  let outcome
+  try {
+    outcome = await handle.done
+  } catch (error) {
+    raise(error, toolName)
+  }
+  const stdout = handle.collected.stdout?.readFrom(0)
+  const stderr = handle.collected.stderr?.readFrom(0)
+  if (stdout === undefined || stderr === undefined) raise(new Error('the run produced no collected output streams'), toolName)
+  if (stdout.lossy) {
+    // The seam retained less than the tool printed, and a partial print parses into a short
+    // answer that reads exactly like a complete one — the one outcome a search must never
+    // report quietly.
+    raise(new Error(`it printed more than the ${RAW_OUTPUT_MAX_BYTES}-byte output budget; narrow pattern, path, or include and retry`), toolName)
+  }
+  if (outcome.signal !== null || outcome.exitCode === null) {
+    raise(new Error(`it was killed by signal ${outcome.signal ?? '(unknown)'}`), toolName)
+  }
+  return { stdout: stdout.text, stderr: stderr.text, exitCode: outcome.exitCode }
+}
+
+/**
+ * Bound one matched line to {@link MAX_LINE_BYTES} and mark the cut.
+ *
+ * The marker is the host's own (` (line truncated)`, `search-core.ts:325-330`), and it is
+ * exact rather than a guess because the VALUE keeps the complete line: a cut line is a strict
+ * prefix of what the search read, so "was anything cut" is answered by comparing the two, not
+ * by comparing a length against a cap that a line may meet without being cut.
+ * @param {string} line - the complete matched line.
+ * @returns {string} the preview, suffixed when bytes were cut.
+ */
+function previewLine(line) {
+  const kept = cutToBytes(line, MAX_LINE_BYTES)
+  return kept === line ? kept : `${kept} (line truncated)`
+}
+
+/**
+ * The model-facing `grep` page: a found-count header, the retained matches grouped by file,
+ * and — when the cap cut the list — a footer that says so AND says the rest was not saved.
+ * The host's footer carries a recovery locator there; this world has no spill file, so the
+ * honest footer is the one that says so instead of pointing at a file that does not exist.
+ * @param {{ matches: Array<{path: string, lineNumber: number, line: string}> }} value - the tool's value.
+ * @returns {{ type: 'text', text: string }[]} the content blocks.
+ */
+function renderGrep(value) {
+  const seen = value.matches.length
+  if (seen === 0) return [{ type: 'text', text: 'No matches found' }]
+  const kept = value.matches.slice(0, MAX_MATCHES)
+  const truncated = seen > MAX_MATCHES
+  const header = truncated
+    ? `Found ${kept.length} of ${seen} matches`
+    : `Found ${seen} ${seen === 1 ? 'match' : 'matches'}`
+  const byFile = new Map()
+  for (const match of kept) {
+    const group = byFile.get(match.path)
+    if (group !== undefined) group.push(match)
+    else byFile.set(match.path, [match])
+  }
+  const sections = [...byFile].map(([path, group]) => (
+    `${path}\n${group.map((match) => `Line ${match.lineNumber}: ${previewLine(match.line)}`).join('\n')}`
+  ))
+  const footer = truncated
+    ? '\n\n(The complete result was not saved; narrow pattern, path, or include to see more.)'
+    : ''
+  return [{ type: 'text', text: `${header}\n\n${sections.join('\n\n')}${footer}` }]
+}
+
+/**
+ * The model-facing `glob` page: the paths themselves when they fit, and the first page plus a
+ * footer that says how many were withheld and that the rest was not saved.
+ * @param {{ root: string, paths: string[] }} value - the tool's value.
+ * @returns {{ type: 'text', text: string }[]} the content blocks.
+ */
+function renderGlob(value) {
+  if (value.paths.length === 0) return [{ type: 'text', text: 'No files found' }]
+  if (value.paths.length <= MAX_RESULTS) return [{ type: 'text', text: value.paths.join('\n') }]
+  const page = value.paths.slice(0, MAX_RESULTS).join('\n')
+  return [{
+    type: 'text',
+    text: `${page}\n\n(Showing ${MAX_RESULTS} of ${value.paths.length} paths, oldest first. The complete list was not saved; narrow pattern or path to see more.)`,
+  }]
+}
+
+/**
+ * The `grep` tool: which line of which file matches, with line numbers, grouped by file.
+ * @param {object} ctx - the realm's plugin context (the services `execute` reaches).
+ * @returns {object} the registry-ready tool definition.
+ */
+function grepTool(ctx) {
+  return defineTool({
+    name: 'grep',
+    description: 'Search file contents inside the WSL distribution, with the distribution\'s own grep. '
+      + 'Returns matching lines with line numbers, grouped by file, each path exactly as grep printed it (absolute). '
+      + '.gitignore is not read — only the six VCS directories are skipped — and dotted directories ARE searched. '
+      + 'Binary files are never matched: the distribution\'s grep treats a binary file as non-matching, so its bytes never enter a result line — the host\'s rg reports a match for the same file. '
+      + 'A path containing a colon can make a match wrong or missing: `path:line:text` is printed with no escaping, so a colon inside a path can be taken for a field separator, and the match then names the wrong file and line number with nothing in the result to mark it wrong — or the record is dropped. Narrow the path, or use `read`, when a name contains one. '
+      + `Up to ${MAX_MATCHES} matches; a capped result says how many were withheld, and the complete list is not saved anywhere.`,
+    parameters: {
+      pattern: {
+        type: 'string',
+        required: true,
+        description: 'Regular expression to search for, in POSIX extended form — not ripgrep\'s: \\d and (?i) are not available (write [0-9], or spell out the case alternation). '
+          + 'A pattern that matches nothing returns no matches, not an error.',
+      },
+      path: {
+        type: 'string',
+        description: 'File or directory to search. Defaults to the session workspace; a relative path resolves against it.',
+      },
+      include: {
+        type: 'string',
+        description: 'One glob filter for which files to search (e.g. "*.ts"). It is matched against each file\'s BASE NAME, so a glob carrying a directory ("src/*.ts") matches nothing — narrow with path instead — '
+          + 'and there is no brace expansion, so "*.{ts,tsx}" matches nothing either. Not a list; negation is not supported.',
+      },
+    },
+    timeoutMs: TIMEOUT_MS,
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          matches: {
+            type: 'array',
+            required: true,
+            items: {
+              type: 'object',
+              additionalProperties: false,
+              properties: {
+                path: { type: 'string', required: true },
+                lineNumber: { type: 'integer', required: true },
+                line: { type: 'string', required: true },
+              },
+            },
+          },
+        },
+      },
+      render: (_args, value) => renderGrep(value),
+    },
+    async execute(args, exec) {
+      if (args.pattern.length === 0) throw new Error('pattern must be a non-empty string')
+      if (args.path !== undefined && args.path.trim().length === 0) throw new Error('path must be a non-empty string when given')
+      const { workdir, root } = await resolveRoot(ctx, exec, args)
+      const argv = grepArgv(
+        { pattern: args.pattern, path: root, ...args.include !== undefined ? { include: args.include } : {} },
+        { maxMatches: MAX_MATCHES },
+      )
+      const run = await runCommand(ctx, exec, 'grep', argv, workdir)
+      if (run.exitCode === 1) return { matches: [] }
+      if (run.exitCode !== 0) raiseExit('grep', run.exitCode, run.stderr)
+      const parsed = parseGrepOutput(run.stdout, RETAIN_ALL_MATCHES)
+      // grep prints `path:line:text` for every match, so output that parses to NOTHING is
+      // output the print reader could not read at all — a colon inside a path is the known
+      // cause. That must not answer as "No matches found", which is what a silent drop would
+      // look like: the two are distinguishable precisely because a genuine empty result
+      // prints not a single byte.
+      //
+      // That premise leans on `--binary-files=without-match` in `grepArgv` (`search.js`), and
+      // this coupling is the part no assertion can see. The flag's VALUE is the gap the tool
+      // description declares — a binary file is treated as non-matching, so its bytes never
+      // enter a line — and the measurement below is what makes this guard's premise provable:
+      // WITH the flag a binary file's match yields no line, no stdout byte and exit 1
+      // (measured, GNU grep 3.11), so a non-empty print here really is unreadable output.
+      // Measured without it: exit 0, an EMPTY stdout, and the `Binary file … matches` notice
+      // on STDERR — this guard reads stdout, so it would not fire; the call would answer
+      // "No matches found" and drop the notice, and the loud failure this guard exists for
+      // would need a grep that put that notice on stdout. The flag's presence is pinned
+      // byte-for-byte by the golden vector in `scripts/verify-search.mjs`; the reason it must
+      // stay is here. (Carried ruling 38, task 4; its wording states the result first under
+      // ruling 47's minor, alongside the declared gap.)
+      if (run.stdout.length > 0 && parsed.matches.length === 0) {
+        raise(new Error(`its output could not be read as match records (${run.stdout.length} bytes; a path containing a colon is the known cause) — narrow the path and retry`), 'grep')
+      }
+      return { matches: parsed.matches.map((match) => ({ path: match.path, lineNumber: match.lineNumber, line: match.text })) }
+    },
+  })
+}
+
+/**
+ * The `glob` tool: files, not directories, whose paths match a glob pattern.
+ * @param {object} ctx - the realm's plugin context (the services `execute` reaches).
+ * @returns {object} the registry-ready tool definition.
+ */
+function globTool(ctx) {
+  return defineTool({
+    name: 'glob',
+    description: 'Find files (not directories) inside the WSL distribution, with the distribution\'s own find. '
+      + 'Returns absolute paths exactly as find printed them, in modification-time order. '
+      + '.gitignore is not read — only the six VCS directories are skipped — and dotted directories ARE searched. '
+      + `Up to ${MAX_RESULTS} paths; a capped result says how many were withheld, and the complete list is not saved anywhere.`,
+    parameters: {
+      pattern: {
+        type: 'string',
+        required: true,
+        description: 'Glob pattern to match file paths against (e.g. "**/*.ts", "src/**/*.test.js"). Interpreted relative to the search root, and "*" crosses "/" as "*" and "**/" alike, '
+          + 'so "src/*.ts" also matches files deeper than one level, while a pattern with no "/" matches at any depth and a leading "/" means the same as none. '
+          + 'A pattern that matches nothing returns an empty list, not an error.',
+      },
+      path: {
+        type: 'string',
+        description: 'Directory to search in. Defaults to the session workspace; a relative path resolves against it.',
+      },
+    },
+    timeoutMs: TIMEOUT_MS,
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          root: { type: 'string', required: true },
+          paths: { type: 'array', required: true, items: { type: 'string' } },
+        },
+      },
+      render: (_args, value) => renderGlob(value),
+    },
+    async execute(args, exec) {
+      if (args.pattern.trim().length === 0) throw new Error('pattern must be a non-empty string')
+      if (args.path !== undefined && args.path.trim().length === 0) throw new Error('path must be a non-empty string when given')
+      const { workdir, root } = await resolveRoot(ctx, exec, args)
+      const argv = globArgv({ pattern: args.pattern, path: root }, { maxResults: MAX_RESULTS })
+      const run = await runCommand(ctx, exec, 'glob', argv, workdir)
+      if (run.exitCode !== 0) raiseExit('glob', run.exitCode, run.stderr)
+      const parsed = parseGlobOutput(run.stdout, RETAIN_ALL_PATHS)
+      // The `-printf` emits one `%T@ %p` record per hit, so a non-empty print that parsed to
+      // NO path is damaged output (the reader drops a record it cannot read, silently by
+      // design) — and silence here would be indistinguishable from "no files match", which
+      // find prints as nothing at all.
+      if (run.stdout.length > 0 && parsed.paths.length === 0) {
+        raise(new Error(`its output could not be read as path records (${run.stdout.length} bytes)`), 'glob')
+      }
+      return { root, paths: parsed.paths }
+    },
+  })
+}
+
+/** The sentence each tool adds to the system prompt while that tool exists in the scope. */
+const PROMPTS = {
+  grep: 'Use the grep tool — not shell grep — to search file contents in this WSL session; it is the distribution\'s own grep.',
+  glob: 'Use the glob tool — not shell find — to discover files by path pattern in this WSL session; it is the distribution\'s own find.',
+}
+
+/**
+ * Register the ONE tool this row names, plus its scope-aware prompt guidance.
+ *
+ * The section is registered the way the host registers its own (`grep.ts:275-282`): its text
+ * is a function of the scope and is EMPTY while the tool is not resolvable there, so the
+ * guidance cannot outlive the tool it describes. The section name is `wsl:`-prefixed rather
+ * than the host's `tool:` — a composition that mounted both would otherwise have two
+ * sections claiming one name.
+ * @param {object} ctx - the realm's plugin context; registrations are effects scoped to it.
+ * @param {{ tool?: string } | undefined} config - the row's config: which tool this is.
+ */
+export function apply(ctx, config) {
+  const tool = config?.tool
+  if (tool !== 'grep' && tool !== 'glob') {
+    throw new Error(`wsl-search: this row must name the tool it registers as config.tool ("grep" or "glob"), got ${JSON.stringify(tool ?? null)}`)
+  }
+  ctx.systemPrompt.section({
+    name: `wsl:${tool}`,
+    order: ctx.systemPrompt.getSectionOrder(tool === 'grep' ? 'TOOL_GREP' : 'TOOL_GLOB'),
+    text: ({ scope }) => ctx.tools.get(tool, scope) === undefined ? '' : PROMPTS[tool],
+  })
+  ctx.tools.register(tool === 'grep' ? grepTool(ctx) : globTool(ctx))
+}

package/lib/wsl/search.js

@@ -0,0 +1,288 @@
+/**
+ * The realm's own search: the argv vectors for the distribution's grep and find.
+ *
+ * The host's grep/glob are removed inside a WSL realm on purpose — their argv[0] is a
+ * packaged WINDOWS ripgrep binary — so without this module the realm has no search tool
+ * at all. The distribution carries its own `/usr/bin/grep` and `/usr/bin/find`, and what
+ * this module decides is only ever the ARGV VECTOR that runs them.
+ *
+ * No shell exists on that path, by construction: `sh -c`, a pipe, a redirect and a glob
+ * expanded by a shell are all impossible here, because every model value (pattern, path,
+ * include) is pushed as exactly ONE element. A value that reads like shell syntax is
+ * therefore inert — `a b; rm -rf /` is one argument and nothing else. Sorting and
+ * filtering happen in Node, on the parsed output.
+ *
+ * The other half of the job is what comes BACK. The distribution's tools print formats of
+ * their own (`path:line:text` with no escaping, `%T@ %p` NUL-separated), and the parsers
+ * below turn that print into the host tool's shape, applying the caps there — in Node,
+ * because the vectors ask for everything and only the consumer can stop. The sort is Node's
+ * too: a realm has no shell to pipe into `sort`.
+ *
+ * What a FAILED run means is decided here as well (`searchFailure`), in the host's own two
+ * names, so the tool that raises the failure does not get to invent a vocabulary of its
+ * own — and so that the two classes stay apart in an offline row rather than in a `catch`
+ * block nobody can test.
+ *
+ * The glob translation is MEASURED rather than assumed. GNU find's `-path` matches the
+ * WHOLE printed path and its `*` crosses `/` (findutils 4.10.0, measured in the distribution),
+ * so a leading `**` + `/` in a glob is exactly `*`: the translation COLLAPSES that prefix, it
+ * does not expand it into a repeated segment, and the caller anchors the result to the
+ * search root — an unanchored tail matches NOTHING, because `-path` sees the printed
+ * absolute path and never the root-relative one the model wrote (also measured).
+ * @module dsh-wsl-desktop/wsl/search
+ */
+
+/** VCS directories the listing must never descend into (host parity: glob.ts:37). */
+export const VCS_EXCLUDES = ['.git', '.svn', '.hg', '.bzr', '.jj', '.sl']
+
+/**
+ * Translate a model-facing path glob into the tail of a `find -path` pattern.
+ *
+ * MEASURED: GNU find's `-path` matches the WHOLE printed path and its `*` crosses `/`, so a
+ * `**` + `/` prefix is exactly `*` — a collapse, not an expansion. The caller anchors the
+ * result to the search root: an unanchored tail matches nothing (measured).
+ *
+ * A leading `/` is ripgrep's ANCHORED glob form; EVERY leading slash is therefore stripped, so
+ * that `/**` + `/x.ts`, `**` + `/x.ts` and `//**` + `/*.ts` all mean the same thing here. One
+ * slash is not enough: a doubled one would leave `/*.ts`, and the anchor would then build a
+ * `//`-bearing -path pattern, which matches NOTHING (measured: the same fixture answers 2
+ * records for the single-slash form and 0 for the doubled one — and the doubled-leading-slash
+ * input family was found in review, after the first two were fixed).
+ * @param {string} pattern - the model's glob.
+ * @returns {string} the tail of the `-path` pattern; globArgv anchors it to the root.
+ */
+export function translateGlob(pattern) {
+  return pattern.replace(/^\/+/, '').replace(/\*\*\//g, '').replace(/^\.\//, '')
+}
+
+/**
+ * One `grep -E` argv vector. Every model value is ONE element; no shell exists.
+ *
+ * The VCS exclusion is not optional here: `grep -r` has no prune concept, and the host's
+ * grep skips those directories because ripgrep does. Without the exclusions this vector
+ * answers with `.git`'s own files (measured — see task-1-report.md).
+ * @param {{ pattern: string, path: string, include?: string }} input - the model's request.
+ * @param {{ maxMatches: number }} caps - the caller's cap; not consumed by the vector
+ *   (the cap is applied where the output is parsed, not on the command line).
+ * @returns {string[]} the argv, ready for the distribution's grep.
+ */
+export function grepArgv(input, caps) {
+  void caps
+  const argv = ['/usr/bin/grep', '-r', '-n', '-H', '-E', '--binary-files=without-match']
+  // Measured: without these, the vector returns .git/x/hidden.ts — grep has no prune concept,
+  // so the VCS exclusion rides on --exclude-dir (still one inert element per name). They are
+  // OPTIONS, so they stand before --include= and before the `--`: after that separator grep
+  // would read one of them as just another path operand.
+  for (const name of VCS_EXCLUDES) argv.push(`--exclude-dir=${name}`)
+  if (input.include !== undefined) argv.push(`--include=${input.include}`)
+  argv.push('--regexp', input.pattern, '--', input.path)
+  return argv
+}
+
+/**
+ * One `find` argv vector: VCS pruned by -prune, the pattern anchored to the root, mtime
+ * printed for the sort in Node.
+ * @param {{ pattern: string, path: string }} input - the model's request.
+ * @param {{ maxResults: number }} caps - the caller's cap; not consumed by the vector
+ *   (the cap is applied where the output is parsed, not on the command line).
+ * @returns {string[]} the argv, ready for the distribution's find.
+ */
+export function globArgv(input, caps) {
+  void caps
+  // Strip ONLY the trailing slashes: the formula is <path-without-trailing-slashes>/<tail>, so a
+  // root path '/' deliberately yields '' and the anchored pattern keeps exactly ONE leading slash.
+  // MEASURED, twice in the distribution: a '//'-prefixed -path pattern matches NOTHING, so
+  // special-casing the root back to '/' would make a full-root search silently return empty.
+  const root = input.path.replace(/\/+$/, '')
+  // The separator is MEASURED, not assumed (findutils 4.10.0): the vector answers the SAME records
+  // with and without it (exit 0 both ways), and a `--` in the expression position is rejected as
+  // an unknown predicate — so all it ends is find's OWN option parsing, and nothing else moves.
+  // It is NOT a licence to pass a path that begins with `-`; measured, `find -- -dashdir …`
+  // reports "unknown predicate `-dashdir'" and exits 1 — a LOUD failure, which is why it is
+  // accepted rather than guarded against here. Such a path cannot reach this vector anyway:
+  // Task 3's path resolution turns the model's relative path into an ABSOLUTE one, so the first
+  // dash-leading argument find could meet never is one. (Repeat these two facts where that
+  // resolution happens: Task 3 owns that site, and this comment cannot stand in for it.)
+  const argv = ['/usr/bin/find', '--', input.path]
+  for (const name of VCS_EXCLUDES) argv.push('-name', name, '-prune', '-o')
+  // -path matches the whole printed path, so the model's root-relative pattern is anchored here.
+  argv.push('-path', `${root}/${translateGlob(input.pattern)}`, '-type', 'f', '-printf', '%T@ %p\\0')
+  return argv
+}
+
+/**
+ * Cut one line to `maxBytes` UTF-8 BYTES without ever splitting a character.
+ *
+ * The cap's name is its contract, and a UTF-16 `length` is not that number: '中文中' is 3 units
+ * but 9 bytes (measured), so a unit-counted cap of 3 passed the WHOLE line through at three times
+ * the caller's number. This walks the string's CODE POINTS and adds each one's `Buffer.byteLength`
+ * until the next would cross the cap, so the cut always lands between characters — a byte-wise slice
+ * of the buffer instead answers one whole character plus the first byte of the next, printed as a
+ * replacement character. (Code points, not grapheme clusters: a combining mark is a code point of
+ * its own, which is as far as this cap's name claims to go.)
+ *
+ * It is exported because the parser is not the only place the cut happens: a tool that keeps the
+ * complete records in its VALUE and cuts the model-facing text at the render boundary (the host's
+ * split — its `previewLine` cuts there) must make the same cut, and a second implementation of a
+ * byte-correct cut is how the two would come to disagree.
+ * @param {string} text - the line to cut.
+ * @param {number} maxBytes - the cap, in UTF-8 bytes.
+ * @returns {string} the longest prefix that fits, ending on a character boundary.
+ */
+export function cutToBytes(text, maxBytes) {
+  let bytes = 0
+  let end = 0
+  for (const ch of text) {
+    const size = Buffer.byteLength(ch, 'utf8')
+    if (bytes + size > maxBytes) break
+    bytes += size
+    end += ch.length
+  }
+  return text.slice(0, end)
+}
+
+/**
+ * Parse `grep -H -n` output into the host's match shape.
+ *
+ * grep prints `path:line:text` with NO escaping, so the split is the fragile part and it is
+ * fixed to the FIRST two colons: the path ends at the first, the number runs to the second,
+ * and everything after the second is text — which is what lets a matching line carry colons
+ * of its own. A line without a second colon is not a record and is skipped.
+ *
+ * A colon inside the PATH is the same ambiguity read the other way, and the print cannot settle
+ * it: the field boundaries are gone before this function is ever called. What is left to choose
+ * is which failure to take, and this function takes the recoverable one. The line-number field is
+ * the test — it is a COUNT, so a field that is not a finite integer (`/ws/a:b.ts:7:x` leaves
+ * `b.ts` where the number belongs) means the split landed inside the damage, and the record is
+ * SKIPPED, exactly as an unreadable find record is. Skipping costs one RECOVERABLE false negative:
+ * the model can re-run with `read`, a narrower path, or bash. Keeping it costs the whole CALL —
+ * NaN is not lossless JSON, so the host's value snapshot rejects the value (packages/util/values/
+ * src/index.ts:128-129), its schema declares this field an INTEGER (tool-fs-search/src/grep.ts:307),
+ * and the tool answers with a ToolOutputError that takes every other match in the batch down with
+ * it, behind an error that never mentions a colon.
+ *
+ * That guard is NOT a solution to the ambiguity and must not be read as one: it covers only the
+ * fields that do not read as a line number at all (NaN, Infinity, a fraction like `9.30`), and it
+ * cannot cover the ones that do. `/ws/2024:12:00.log:7:needle` mis-reads to a FINITE
+ * `{path: '/ws/2024', lineNumber: 12, text: '00.log:7:needle'}` (measured) — a number no guard can
+ * tell from a real one — and `''` or `' 7'` read as 0 and 7 just as silently, so a colon-bearing
+ * path may be DROPPED or silently MIS-ATTRIBUTED, and only the print format could settle which.
+ * The gap is listed with the realm's other differences from the host (Task 5, docs/SEARCH.md).
+ *
+ * The caps are applied HERE, in Node: the vector asks the tool for everything, so this is the
+ * only place a limit can be applied — and a cap that reported nothing would make a cut answer
+ * read as a complete one. A line over `maxLineBytes` is cut to the cap but is NOT a truncated
+ * answer: the record survives, shortened, so `truncated` stays about what the CAP left out. That
+ * cap is in BYTES, because that is the name's promise — see `cutToBytes` for the unit that makes
+ * it so.
+ * @param {string} stdout - grep's stdout, one `path:line:text` record per line.
+ * @param {{ maxMatches: number, maxLineBytes: number }} caps - the caller's caps.
+ * @returns {{ matches: Array<{path: string, lineNumber: number, text: string}>, truncated: boolean }}
+ *   the records, and whether the CAP left at least one further record out. (A record skipped for
+ *   being unreadable is not a truncation: the flag is about the cap, not about damage.)
+ */
+export function parseGrepOutput(stdout, caps) {
+  const matches = []
+  let truncated = false
+  for (const rawLine of stdout.split('\n')) {
+    if (rawLine === '') continue
+    const first = rawLine.indexOf(':')
+    const second = first === -1 ? -1 : rawLine.indexOf(':', first + 1)
+    if (second === -1) continue
+    // A line number is a COUNT, so anything else here means the split landed in the damage (the
+    // docblock has the reason this is a SKIP rather than a `NaN` handed to the caller). It is
+    // skipped BEFORE the cap is consulted, so an unreadable record neither fills the cap nor sets
+    // `truncated` (which is about the cap), and with `continue`, never `break` — a broken record
+    // must not end the scan and quietly shorten the answer.
+    const lineNumber = Number(rawLine.slice(first + 1, second))
+    if (!Number.isInteger(lineNumber)) continue
+    if (matches.length >= caps.maxMatches) { truncated = true; break }
+    const text = rawLine.slice(second + 1).replace(/\r$/, '')
+    matches.push({
+      path: rawLine.slice(0, first),
+      lineNumber,
+      text: cutToBytes(text, caps.maxLineBytes),
+    })
+  }
+  return { matches, truncated }
+}
+
+/**
+ * Parse `find -printf '%T@ %p\0'` and order by mtime ASCENDING, in Node (no shell sort).
+ *
+ * The record format is the vector's, and both halves of it are load-bearing: the mtime ends at
+ * the FIRST space (a path may contain one), and the NUL is the separator because a path may
+ * contain a newline — a line-based record would split one path in two. The order is the host's
+ * MEASURED one rather than the natural-looking one: the host sorts by mtime ascending (oldest
+ * first), so a descender here would be a silent disagreement with it. The cap is applied AFTER
+ * the sort, which is what makes "the first N" mean the N oldest rather than whichever N find
+ * happened to print first.
+ *
+ * A record that cannot be read at all is DROPPED, symmetrically with the grep side (which drops a
+ * line without a second colon, and one whose line-number field is not a finite integer — the two
+ * tests differ only because the fields do: a count, an mtime). The vector's own `-printf` always
+ * emits the space, so a record without one means the print was cut short, and a non-finite mtime
+ * means a value this parser cannot order by — a phantom path, or an order that depends on where a
+ * NaN landed in V8's sort, would be an answer nobody decided. The drop is deliberately silent
+ * (`truncated` is about the CAP, not about damage): for a broken record, no path is the better
+ * answer.
+ * @param {string} stdout - find's stdout, `%T@ %p` records separated by NUL.
+ * @param {{ maxResults: number }} caps - the caller's cap.
+ * @returns {{ paths: string[], truncated: boolean }} the paths, oldest first, and whether the CAP
+ *   left at least one further record out. (The caller's `root` is the tool's own: it fills it
+ *   from the path the model asked for — this parser never guesses one.)
+ */
+export function parseGlobOutput(stdout, caps) {
+  const entries = stdout.split('\0').filter(entry => entry !== '')
+    .map((entry) => {
+      const space = entry.indexOf(' ')
+      // No space means this is not a record the vector could have printed: skip it (never a path
+      // built out of the damage). Not seen: a finite-looking prefix — a record cut before its space
+      // — would pass the mtime check below, so the space itself is what says the record is whole.
+      if (space === -1) return null
+      const mtime = Number(entry.slice(0, space))
+      return Number.isFinite(mtime) ? { mtime, path: entry.slice(space + 1) } : null
+    })
+    .filter(entry => entry !== null)
+    .sort((a, b) => a.mtime - b.mtime)
+  const truncated = entries.length > caps.maxResults
+  return { paths: entries.slice(0, caps.maxResults).map(entry => entry.path), truncated }
+}
+
+/**
+ * Classify ONE failed search into the host's failure vocabulary.
+ *
+ * Two names, because the model's next move differs: `SEARCH_INVALID_PATTERN` means rewrite the
+ * regex, `SEARCH_FAILED` means the search never ran as asked (a launch that never happened —
+ * including the `ENOENT` of a distribution without `grep`/`find` — a kill, a timeout, or a print
+ * that could not be read). The names are the host's own (`tool-fs-search/src/search-core.ts:67-97`).
+ *
+ * The rule is grep's EXIT CODE, and the honest boundary of that rule belongs here rather than in a
+ * comment nobody reads: GNU grep exits 2 for every error it has, not only for a bad pattern, and its
+ * stderr is the only thing that separates a rejected pattern from an unreadable target. What settles
+ * the mapping is the caller's action — and for an exit 2 the excerpt is what actually says which one
+ * happened — so the class is the exit code and the message carries the diagnostic verbatim. The
+ * class is grep's ALONE: find has no such exit, so an exit 2 from it is an ordinary failure.
+ *
+ * What this function deliberately does NOT do is decide the one combination a caller can detect
+ * better than it can: output that was printed but parsed to nothing. That is a failure of the PRINT
+ * reader, it is raised loudly by the tool that sees it (a silent drop of a malformed record must not
+ * become indistinguishable from a genuine "no matches"), and it arrives here as an ordinary error
+ * with no exit code — `SEARCH_FAILED`.
+ * @param {unknown} error - the failure as it surfaced: an `Error` (or Error-shaped value) whose
+ *   `exitCode` is the run's exit code when there was one.
+ * @param {string} toolName - `'grep'` or `'glob'`, the tool the failure is reported for.
+ * @returns {{ code: 'SEARCH_INVALID_PATTERN' | 'SEARCH_FAILED', message: string }} the class and the
+ *   model-facing message (the class name leads it: the message is what the model sees, and the code
+ *   rides beside it for the layers that route on it).
+ */
+export function searchFailure(error, toolName) {
+  const detail = error instanceof Error ? error.message : String(error?.message ?? error)
+  const exitCode = typeof error === 'object' && error !== null ? error.exitCode : undefined
+  const suffix = detail.length === 0 ? '' : `: ${detail}`
+  if (toolName === 'grep' && exitCode === 2) {
+    return { code: 'SEARCH_INVALID_PATTERN', message: `SEARCH_INVALID_PATTERN: grep rejected the pattern (exit 2)${suffix}` }
+  }
+  const where = typeof exitCode === 'number' ? ` (exit ${exitCode})` : ''
+  return { code: 'SEARCH_FAILED', message: `SEARCH_FAILED: ${toolName} search failed${where}${suffix}` }
+}

package/lib/wsl/watch.js

@@ -86,13 +86,21 @@ const NODE_IO = {
 }
 
 /**
- * Read one directory reading as a key, answering an absent directory with the empty set.
+ * The key an absent directory answers with.
+ *
+ * Unreachable by construction, not by convention: POSIX file names cannot contain NUL and
+ * `entrySetKey` only uses NUL BETWEEN names, so every real `readdir` reading produces a key
+ * that starts with a non-empty name. This one needs a name that is empty, which cannot exist.
+ */
+const ABSENT_KEY = '\0'
+
+/**
+ * Read one directory reading as a key, answering an absent directory with {@link ABSENT_KEY}.
  *
  * The contract observes a path for CREATION as well as for change, so a directory that
- * is not there is an empty entry set rather than a failure — its deletion and its
- * reappearance are both changes. One qualification: an EMPTY directory produces this same
- * key, so an empty directory being created or removed notifies nobody (the limitation
- * `docs/WATCH.md` states). Every other error belongs to the caller.
+ * is not there is a key of its own rather than a failure: its deletion and its
+ * reappearance are both changes, and so is an EMPTY directory's, because absence and an
+ * empty entry set are different keys. Every other error belongs to the caller.
  * @param {string} hostPath - the target's host path.
  * @param {object} io - the io seam.
  * @returns {Promise<string>} the entry-set key.
@@ -101,7 +109,7 @@ async function readEntryKey(hostPath, io) {
   try {
     return entrySetKey(await io.readdir(hostPath))
   } catch (error) {
-    if (error?.code === 'ENOENT') return ''
+    if (error?.code === 'ENOENT') return ABSENT_KEY
     throw error
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-wsl-desktop",
-  "version": "0.3.7",
+  "version": "0.4.0",
   "type": "module",
   "main": "lib/index.js",
   "icon": "./lib/icon.svg",