dsh-plugin-wsl-env 0.6.0 → 0.7.2

package/CHANGELOG.md

@@ -12,6 +12,182 @@ reference below points at that record's numbering.
 
 ## [Unreleased]
 
+## [0.7.2] - 2026-10-05
+
+One theme: the root-plane routing lands - and the composition that
+silently dropped it and the workspace-files takeover is repaired and
+pinned by a test that runs the plugin's real patch file through the
+loader's real patch algorithm.
+
+### Added
+
+- **The root-plane filesystem routes by coordinate.** The root `ctx.fs`
+  (behind the GUI's change feed and every un-mounted root consumer) is
+  replaced by a coordinate-routing variant (`lib/fs-routing.js`): distro UNC
+  identities are served by the resident agent - ext4 reads, and real watch
+  events for the change feed, which previously never fired on a 9p share -
+  while drive paths stay host-native. The root write fence retires with this
+  round: the root plane has no write consumers (the model's writes ride the
+  preset filesystems, which enforce their own containment). Design note:
+  `docs/root-fs-routing.md`.
+
+### Fixed
+
+- **The 0.7.1 composition never mounted what it announced.** The
+  `workspace-files` disable, the `fs-sandbox` disable, and both replacement
+  rows were written inside a bare `insert:` list — but a patch layer is a
+  flat list: an `insert` list is data to append, never nested patches. The
+  loader therefore mounted the two disable rows as duplicate-id anonymous
+  entries that *shadowed the real upstream rows* (`EntryGroup.update` keys
+  rows by id, last occurrence wins): the running app had no root `ctx.fs`
+  and no GUI file-tree service at all, while `fs-routing` and
+  `workspace-files-wsl` - trapped inside nested `insert:` lists - never
+  started. Opening a distro workspace failed accordingly. Both takeovers are
+  now top-level entries: disable by id, then append the replacement with a
+  bare insert. `test/composition.test.mjs` runs the plugin's actual patch
+  file through the loader's actual `applyEntryPatches` over stand-in
+  upstream rows, asserting every composed row is a real named entry, ids
+  stay unique, the shipped rows are disabled under their own names, and
+  both replacements mount - the shape cannot regress silently again.
+- The terminal-activity live check marked its shell with a runtime
+  `export`, which `/proc/<pid>/environ` never shows (it reflects the
+  exec-time block only), so the probe could never count past one and the
+  busy assertion failed deterministically. The marker now rides the spawn
+  environment - what `wsl.exe` does when it imports `DSH_TERMINAL_ID`
+  before `--exec`.
+
+## [0.7.1] - 2026-10-04
+
+One theme: the remaining root-plane 9P consumers move inside the distro -
+the GUI file tree and previews, and the workspace-changes git snapshots -
+plus the test-infrastructure maturity (a REAL-composition boot test and
+the pure text-mechanics refusals under direct unit test) that the
+promotion work was built on.
+
+### Added
+
+- **git snapshot commands run the distro's git.** `workspace-changes`
+  snapshots a workspace by spawning the host git through
+  `ctx.subprocess.spawn` — on a distro workspace that was Windows git
+  scanning the full work tree across the 9p share, the most
+  metadata-heavy operation there is. Spawns whose working directory names
+  a distro and whose argv carries none of the absolute-output discovery
+  flags are rewritten into `wsl.exe -d <distro> --cd <linux dir> --exec
+  git …` (`lib/git-route.js`). The snapshot is safe to route because it
+  already runs in a fully isolated git environment (`GIT_INDEX_FILE` /
+  `GIT_OBJECT_DIRECTORY` / `GIT_ALTERNATE_OBJECT_DIRECTORIES` in the
+  tool's private scratch — the repository's index, object store, work
+  tree, and refs stay unchanged); the route translates those path-shaped
+  env values into distro coordinates and forwards them through `WSLENV`.
+  Verified against a live distro: the snapshot sequence completes with the
+  user's index, object store, and refs untouched.
+- **The GUI file tree and previews are served from inside the distro.**
+  `workspace-files` - the root-plane consumer behind the GUI's file tree
+  and previews - read UNC workspaces through the 9p share. The plugin
+  replaces the composition row with a distro-routed variant
+  (`lib/workspace-files-wsl.js`): listings, stats, line-paged reads and
+  byte windows for a \\wsl.localhost\\<distro> workspace run through the
+  resident agent, with the upstream refusals mirrored (not-found,
+  outside-workspace, not-directory, not-regular-file, too-large,
+  not-text) and `absolutePath` synthesized in the UNC display form so
+  the GUI is unchanged. Windows-folder sessions keep the shipped
+  host-backed service; the watch stream delegates unchanged.
+  (`lib/workspace-files-route.js` holds the pure builders/parsers;
+  `test/workspace-files-wsl.test.mjs` covers every wire shape and refusal
+  over a fake agent runner.)
+- **bootstrap installs and reports git.** The git snapshot routing needs
+  git inside the distro; `bootstrap --install` includes it in every
+  package manager's list and the report names it alongside ripgrep (the
+  snapshot backend for workspace-changes).
+- **A REAL-composition boot test.** The plugin's fs row is booted through
+  the cordis Loader from a test-only yml composition and asserted against
+  a live distro read (`test/fs.boot.test.mjs`), alongside direct unit
+  tests for the pure text mechanics' refusal edges
+  (`test/fsio-text.test.mjs`).
+
+## [0.7.0] - 2026-10-04
+
+One theme: the 9p share is out of the model's reach. Two changes land together
+because they close the same measured gap — the file-search spawn was the one
+model-facing I/O path that still crossed the share, in its slow direction
+(~2 s per search where the distro's own rg answers in single-digit
+milliseconds; `\\wsl.localhost` metadata round trips at ~17 ms per file), and
+the share substrate was the configured way back onto that path.
+
+### Added
+
+- **The directory picker lists distro levels from inside the distro.** A level
+  under `\\wsl.localhost\<distro>` is served by the resident agent's
+  `ls -1ALp` in one round trip — a one-shot `wsl.exe --exec ls` when the
+  resident is out, never the host's 9p walk, which paid one metadata round
+  trip per entry plus one more per symlink, in the share's slow direction.
+  `-L` folds the per-entry symlink stat the host walk used to pay; `-p`'s
+  trailing `/` is what the row parser keys on, and a broken link drops out
+  exactly as the old per-entry `stat` dropped it. `createDirectory` follows
+  the same route (`mkdir` through the agent, one-shot otherwise). The parse
+  is the pure `parseLsListing`/`lsListingArgv` pair in `lib/listing.js`
+  (`test/listing.test.mjs`); the accepted limitation — a filename containing
+  a newline would split into two rows — is documented in LIMITATIONS.md.
+- **The file search runs the distro's own rg.** `WslSubprocessRuntime` now
+  overrides `spawn` beside `spawnTerminal`: a spawn of the packaged ripgrep
+  binary whose working directory names a distro (a `\\wsl.localhost\<distro>`
+  UNC — the form every distro workspace search carries) is rewritten into
+  `wsl.exe -d <distro> --cd <linux dir> --exec rg …` with every argument
+  forwarded verbatim, so the tool reads the distro rg's output format and exit
+  codes unchanged. The decision is the peer-free `lib/search-route.js`
+  (mirroring `terminal-route.js`), and the rewrite delegates to the shipped
+  spawn — the handle still wraps a real host process, so the consumer's output
+  budget, spill machinery and teardown all work unchanged. One guard rides
+  the rewrite: when the tool named no search path (its pattern rides
+  `--regexp=`; a bare `--` is how it spells a path), the rewrite appends
+  `-- .` — because `wsl.exe --exec` hands distro-side rg a relay fifo on
+  stdin, and rg's readable-stdin heuristic then searches stdin instead of the
+  directory. The packaged binary saw a non-readable NUL stdin under the old
+  path, which is why the heuristic never fired there. A drive-path
+  directory keeps the host binary, which is native there; a distro without rg
+  surfaces rg's own "command not found" (exit 127) instead of a silent fall
+  back to the share — `npm run bootstrap -- <distro> --install` installs it.
+  There is no 9p path left to fall back to, by design. (`test/search-route.test.mjs`.)
+- **The search rides the warm resident, not a one-shot spawn.** The rewrite's
+  distro command is exec'd by the resident agent — one round trip (~10 ms)
+  instead of a `wsl.exe` process startup (~400 ms) per search. The tool's
+  handle surface is small (`done` plus `collected`), and `lib/search-exec.js`
+  builds exactly that facade: the agent's out state is the lazy fallback cue,
+  delegating to the one-shot `wsl.exe --exec` handle inside `done` — never an
+  error, never the share. The tool's output budget rides the agent's
+  per-stream capture cap; cancellation and `kill()` abort the agent exec and
+  settle as the killed outcome the one-shot path reports.
+  (`test/search-exec.test.mjs`.)
+- **Idle distro terminals are reclaimed.** The controller reclaims an
+  unattended terminal after 2 h of observed idleness, but its observation is
+  host-side and a distro terminal can never answer it: the shipped
+  shell-activity integration is gated to interactive `bash`/`zsh` launched
+  directly on a POSIX host, every branch of `inspectActivity` settles on
+  `unknown` for a `wsl.exe` terminal, and `unknown` never accumulates idle —
+  so distro terminals had to be closed by hand. The terminal is now marked at
+  launch (a per-terminal `DSH_TERMINAL_ID` through the existing `WSLENV`
+  forwarding) and its `inspectActivity` counts the marked processes through
+  the resident agent: exactly one (the shell at its prompt) is idle, more
+  than one (a running command or a nested shell) is busy, and the agent
+  being out answers `unknown` — reclamation pauses, because a probe that
+  cannot answer must not authorize a close. A nested shell keeps the
+  terminal busy by design, as does anything a shell's startup files spawn
+  with the inherited marker. `terminalIdleReclaim: false` restores
+  close-by-hand. (`lib/terminal-activity.js`, `test/terminal-activity.test.mjs`.)
+
+### Breaking changes
+
+- **`substrate: "share"` is refused at construction.** The Windows-side share
+  backend was the file tools' opt-out onto the 9p share; the resident agent
+  serves every distro read and write, and no file tool crosses the share any
+  more. A profile still carrying the value fails to boot with the migration
+  (`shareSubstrateRefusal`): delete the `substrate` line or set it to
+  `"agent"`. The failure message for an agent that is out
+  (`substrateFailure`) no longer offers the share as a way out and names the
+  recovery path instead. The share-only plumbing (the symlink retry, the 9p
+  publication hooks, and the `agent` and `resolveSymlinks` keys that gated
+  them) is removed with this change — `lib/fs-publish.js` with it.
+
 ## [0.6.0] - 2026-10-04
 
 One theme: the P2 backlog from the 2026-10-03 review, closed with the same

package/README.md

@@ -57,11 +57,11 @@ Override a row by id in `$DSH_HOME/profiles/<name>/cordis.patch.yml`. The keys w
 | `wsl-fs` | `distro` | `''` | as above |
 | | `restrictToDistro` | `true` | refuse a path in **another distro**'s share; `/mnt/c` is inside this distro and is not affected. Refused with `FS_OUTSIDE_DISTRO`, which is not a sandbox denial and cannot be lifted by wider permissions |
 | | `sandbox` | `true` | check `writeText` and `editText` against the policy |
-| | `substrate` | `agent` | which I/O substrate serves the file tools: `agent` — the resident in-distro agent, where reads, writes and identities run on ext4 (native symlinks and mode bits; the write guard survives to publication, kernel-enforced under a confined policy); `share` — the opt-out: the Windows-side host stack over the 9p share. Both fence writes with the same policy; see [LIMITATIONS.md](docs/LIMITATIONS.md) for what changes |
+| | `substrate` | `agent` | which I/O substrate serves the file tools. Only the resident in-distro agent remains: reads, writes and identities run on ext4 (native symlinks and mode bits; the write guard survives to publication, kernel-enforced under a confined policy). The former `"share"` opt-out — the Windows-side host stack over the 9p share — is refused at boot; no file tool crosses the share |
 | `directory-picker-wsl` | `includeHostHome` | `true` | also list the Windows home directory |
 | `subprocess-wsl` | `distro` | `''` | which distro the GUI terminal opens in |
 
-[`cordis.patch.yml`](cordis.patch.yml) is the commented reference for every shipped value. [docs/CONFIGURATION.md](docs/CONFIGURATION.md) lists the rest, including `shell`, `loginShell`, `cwd`, `timeoutMs`, `resolveSymlinks`, `preferredDistro` and `maxEntries`; [examples/profile.cordis.patch.yml](examples/profile.cordis.patch.yml) is a machine-local layer to copy from.
+[`cordis.patch.yml`](cordis.patch.yml) is the commented reference for every shipped value. [docs/CONFIGURATION.md](docs/CONFIGURATION.md) lists the rest, including `shell`, `loginShell`, `cwd`, `timeoutMs`, `preferredDistro` and `maxEntries`; [examples/profile.cordis.patch.yml](examples/profile.cordis.patch.yml) is a machine-local layer to copy from.
 
 ## Recipes
 
@@ -74,7 +74,7 @@ Override a row by id in `$DSH_HOME/profiles/<name>/cordis.patch.yml`. The keys w
   (`/home/...`) on the distro's own ext4. `/mnt/c` reaches the Windows disk over
   9p — noticeably slow for many small files; keep heavy-IO projects on the
   distro filesystem. `npm run bootstrap -- <distro>` also reports whether
-  ripgrep and inotifywait (the search and watch backends) are in place.
+  ripgrep, git and inotifywait (the search, snapshot and watch backends) are in place.
 - **WSLENV passthrough**: WSL imports only the variables listed in `WSLENV`.
   This plugin admits the managed `DSH_*` namespace by prefix, translating the
   two Windows-path ones (`DSH_HOME`, `DSH_PROFILE_DIR`) with `/p`. `PATH` is
@@ -100,7 +100,7 @@ preset-wsl (the wsl agent preset; its services run in isolate realms)
 
 **Why two levels.** `wsl-shell` and `wsl-fs` live inside the `wsl` agent preset, which `auto-preset` binds whenever a session's workspace is inside the distro: a Windows-folder session keeps the stock providers, a distro session gets the WSL ones — the environment is a property of the session, not of the process. The terminal controller is the exception: it resolves its execution world through the root context, which never sees a preset's isolate realms, so `subprocess-wsl` sits at the composition level instead.
 
-**Commands and files.** A command runs as `wsl.exe -d <distro> --cd <linux dir> --exec <login shell> -lc <cmd>` inside a distro-side bubblewrap profile assembled with the same arguments as DSH's own Linux runner, so confinement semantics and error messages match a Linux host. The file tools read and write real distro files on one of two substrates: the default `agent` — a resident in-distro process, where reads, writes and identities run on ext4 with native symlinks and mode bits — or `share`, the opt-out: the Windows-side host stack over the 9p share. Both check writes against the same policy the command sandbox enforces.
+**Commands and files.** A command runs as `wsl.exe -d <distro> --cd <linux dir> --exec <login shell> -lc <cmd>` inside a distro-side bubblewrap profile assembled with the same arguments as DSH's own Linux runner, so confinement semantics and error messages match a Linux host. The file tools read and write real distro files on the resident in-distro agent — reads, writes and identities run on ext4 with native symlinks and mode bits — and the file-search spawn is rewritten the same way: a search over a distro workspace runs the distro's own `rg` (`wsl.exe --exec`), never the Windows binary over the 9p share. Writes are checked against the same policy the command sandbox enforces.
 
 ## Sandbox
 
@@ -129,8 +129,8 @@ See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md#sandbox) for the design, and [do
 | the terminal still opens `cmd.exe` | the `terminal-controller` row from the layer did not apply | check that `dsh --profile wsl --dump-config` shows `shell: { path: wsl.exe, name: WSL }` |
 | changes to `lib/` have no effect | ES module cache | restart the app |
 | `link:\\wsl.localhost\...` leaves a broken symlink | pnpm cannot link a UNC path | link a Windows path instead; developing inside the distro needs the runtime mirror, see [Development](#development) |
-| `glob` and `grep` are slow | the Windows-side ripgrep walks the 9p share | expected; narrow the path, or use `bash` to call tools inside the distro |
-| the terminal reports `unknown` activity | shell integration only covers `bash`/`zsh` started directly on a POSIX host | close the tab to release the process; idle reclamation does not run for these terminals |
+| `glob` and `grep` are slow | a distro search without rg inside the distro falls back to rg's own "command not found"; a Windows-folder search is native and unaffected | run `npm run bootstrap -- <distro> --install` (installs ripgrep); distro searches always run the distro's rg — they never walk the 9p share |
+| the terminal reports `unknown` activity | only while the resident agent is out — distro terminals are observed from inside the distro (a `DSH_TERMINAL_ID` marker scanned in `/proc`: a shell alone is `idle`, a shell running anything is `busy`) | check the distro is running; idle terminals are reclaimed automatically after the controller's unattended timeout (2 h by default), and `terminalIdleReclaim: false` restores the close-by-hand posture |
 | a result names an `FS_*` code | the code says what refused it, and what clears it | see the error-code table in [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md#error-codes) |
 
 ## Development

package/cordis.patch.yml

@@ -102,6 +102,54 @@
 
     - id: directory-picker-browse-surface
       name: '@deepseek-ai/dsh-client-ui-directory-picker-browse'
+
+# ═════════════════════════════════════════════════════════════════════════════
+# The distro-side takeovers of the two root-plane services.
+#
+# A patch layer is a flat list: an `id:` entry patches the shipped row, and a
+# bare `insert:` list appends new rows as data. A disable written INSIDE an
+# insert list is not a patch — it becomes a duplicate-id data row that shadows
+# the real service row (the loader keys rows by id, last occurrence wins), and
+# a nested `insert:` list is never interpreted at all. Both takeovers are
+# therefore two top-level entries: disable the shipped row by id, then append
+# the replacement with a bare insert. test/composition.test.mjs runs this file
+# through the real patch algorithm to keep the shape honest.
+# ═════════════════════════════════════════════════════════════════════════════
+
+# The GUI file tree and previews for a distro workspace are served from inside
+# the distro (resident agent) instead of Windows-side 9P walks. The variant
+# extends the shipped service — a distro UNC routes distro-side, a drive path
+# calls super (host native), the watch stream delegates unchanged — so
+# replacing the row is safe for Windows-folder sessions too.
+- id: workspace-files
+  disabled: true
+
+# The root-plane filesystem routes by coordinate: distro UNC identities are
+# served by the resident agent (real watch events, ext4 reads), drive paths
+# stay host-native. Replaces the root fs-sandbox row, whose write fence has no
+# root-plane consumers (the model's writes ride the preset filesystems; see
+# docs/root-fs-routing.md).
+- id: fs-sandbox
+  disabled: true
+
+- insert:
+    - id: workspace-files-wsl
+      name: 'dsh-plugin-wsl-env/workspace-files-wsl'
+      config:
+        maxBytes: 2097152
+        maxFileBytes: 33554432
+        maxLines: 5000
+        maxEntries: 2000
+
+    - id: fs-routing
+      name: 'dsh-plugin-wsl-env/fs-routing'
+      config:
+        distro: ''
+        wslPath: wsl.exe
+        sandbox: true
+        maskWindowsDrive: false
+        restrictToDistro: true
+        watchMaxDepth: 0
     # Contributes the WSL environment's facts (distro / real shell / home) to the
     # managed DSH_* namespace that dsh-shell-env injects into every model shell
     # call. That is DSH's sanctioned channel for shell-environment facts.

package/docs/ARCHITECTURE.md

@@ -19,8 +19,8 @@ smaller integrations.
 | Service | Class | File | What it does |
 |---|---|---|---|
 | `ctx.shell` | `WslShellExecutor` | [`lib/index.js`](../lib/index.js) | Runs each command as `wsl.exe -d <distro> --cd <linux dir> --exec <login shell> -lc <cmd>`, wrapped in a distro-side `bwrap` sandbox. |
-| `ctx.fs` | `WslFileSystem` | [`lib/index.js`](../lib/index.js) | Serves the file tools from real distro files, on one of two I/O substrates (see below): the resident in-distro agent on ext4 (default), or the Windows-side host stack over the distro's UNC share. |
-| `ctx.subprocess` | `WslSubprocessRuntime` | [`lib/subprocess.js`](../lib/subprocess.js) | Opens the GUI terminal inside the distro, in the session workspace. |
+| `ctx.fs` | `WslFileSystem` | [`lib/index.js`](../lib/index.js) | Serves the file tools from real distro files on the resident in-distro agent, on ext4 — the former Windows-side share substrate is retired (see below). |
+| `ctx.subprocess` | `WslSubprocessRuntime` | [`lib/subprocess.js`](../lib/subprocess.js) | Opens the GUI terminal inside the distro, in the session workspace, and rewrites the file-search spawn into the distro's own rg (see below). |
 
 `WslShellExecutor` extends the shipped `LocalBashExecutor`, and `WslFileSystem`
 extends the shipped `LocalFileSystem`. Only the parts that need a distro are
@@ -30,7 +30,7 @@ overridden.
 
 | Subpath | Class or name | File | What it does |
 |---|---|---|---|
-| `dsh-plugin-wsl-env/picker` | `WslDirectoryPicker` | [`lib/picker.js`](../lib/picker.js) | Adds the installed distros to the folder picker, next to the Windows home directory. |
+| `dsh-plugin-wsl-env/picker` | `WslDirectoryPicker` | [`lib/picker.js`](../lib/picker.js) | Adds the installed distros to the folder picker, next to the Windows home directory, and lists distro levels from inside the distro (the resident's `ls`, one-shot `wsl.exe` when it is out). |
 | `dsh-plugin-wsl-env/auto-preset` | `auto-preset` | [`lib/auto-preset.js`](../lib/auto-preset.js) | Binds the `wsl` agent preset when a new session's workspace is inside a distro. |
 | `dsh-plugin-wsl-env/shell-env` | `wsl-shell-env` | [`lib/shell-env.js`](../lib/shell-env.js) | Contributes `DSH_WSL_DISTRO`, `DSH_WSL_SHELL`, and `DSH_WSL_HOME` to the managed `DSH_*` namespace. |
 
@@ -89,7 +89,7 @@ Three coordinate systems appear in the code:
 | System | Example | Used by |
 |---|---|---|
 | Linux inside the distro | `/home/you/proj/a.ts` | commands, `ctx.shell` |
-| The distro's UNC share | `\\wsl.localhost\ubuntu\home\you\proj\a.ts` | the host filesystem stack, `ctx.fs` |
+| The distro's UNC share | `\\wsl.localhost\ubuntu\home\you\proj\a.ts` | the harness's path identities (`ctx.fs` target keys), the picker and terminal routing — a coordinate, not an I/O path: no file tool reads or writes through the share |
 | The Windows filesystem | `C:\Users\you\...`, or `/mnt/c/Users/you/...` from inside | sessions opened on a Windows folder |
 
 [`lib/paths.js`](../lib/paths.js) converts between them. It is pure: it imports no
@@ -98,22 +98,35 @@ path sits under a writable root. The filesystem fence uses them.
 
 ## The filesystem substrate
 
-`wsl-fs` serves `ctx.fs` on one of two I/O substrates, chosen by
-`substrate: share | agent` (default `agent`):
-
-| | `agent` (default) | `share` (opt-out) |
-|---|---|---|
-| Reads, writes, identities | the resident in-distro agent, on ext4 | the Windows-side host stack (`dsh-fs-local`) over the distro's 9p share |
-| Symlinks | native; every identity is a distro-side `realpath` | the share cannot traverse them, so a missing read is retried once through the distro's canonical path |
-| Mode bits | native; the publication rename is the kernel's | the share drops a host-side chmod, so publication re-applies the mode from inside the distro before an atomic rename |
-| Guarded creates | the guard is forwarded; publication is a no-replace link, closing the check-then-write window for creates. An overwrite or edit carries its version into the write op and the agent re-verifies it one syscall before the rename — a concurrent writer wins, the stale write refuses with `FS_STALE_VERSION` | checked, then published without a guard (the share has no hard links) |
-| Kernel enforcement | stage two: a mutation runs on a confined resident — one long-lived agent per (distro, policy), whose bwrap profile binds exactly what the mode grants — so the kernel refuses what the check would have, and a check bug cannot become a write outside the workspace. Escalated writes (`danger-full-access`) ride the plain resident. A kernel refusal carries `FS_SANDBOX_DENIED`, the same dialect as the command path. | none: the fence is the host-side check |
-| New files | 0600 — the host backend's own POSIX publication semantics, as on a Linux host | the distro's umask default (0644) |
-| Agent outage | `FS_IO_ERROR` naming the substrate; no silent fallback to the share. A distro without usable bwrap refuses confined mutations with the bootstrap command, the same closed failure the command path has | not applicable |
-
-Both substrates fence writes with the same host-side policy check
-(`checkedTarget`), and neither changes what `sandboxMode` reports. The wire
-protocol the agent substrate speaks is documented in
+`wsl-fs` serves `ctx.fs` on one I/O substrate: the resident in-distro agent.
+The former Windows-side share backend (`substrate: "share"`) is retired — a
+profile carrying the value is refused at boot, and no file tool crosses the
+9p share. The substrate's facts:
+
+- **Reads, writes, identities** run on ext4 through the resident; symlinks and
+  mode bits are native (every identity is a distro-side `realpath`; the
+  publication rename is the kernel's).
+- **Guarded writes** carry their intent to the publication: a `createIfAbsent`
+  publishes with a no-replace link, closing the check-then-write window for
+  creates outright; an overwrite or edit carries its version into the write op
+  and the agent re-verifies it one syscall before the rename — a concurrent
+  writer wins, the stale write refuses with `FS_STALE_VERSION`.
+- **Kernel enforcement** is stage two: a mutation runs on a confined resident —
+  one long-lived agent per (distro, policy), whose bwrap profile binds exactly
+  what the mode grants — so the kernel refuses what the check would have, and a
+  check bug cannot become a write outside the workspace. Escalated writes
+  (`danger-full-access`) ride the plain resident. A kernel refusal carries
+  `FS_SANDBOX_DENIED`, the same dialect as the command path.
+- **New files** publish 0600 — the host backend's own POSIX publication
+  semantics, as on a Linux host.
+- **Agent outage** fails closed: `FS_IO_ERROR` naming the substrate and the
+  recovery path. There is no fallback I/O; a distro without usable bwrap
+  refuses confined mutations with the bootstrap command, the same closed
+  failure the command path has.
+
+Writes fence with the same host-side policy check (`checkedTarget`) the
+command path uses, and the substrate does not change what `sandboxMode`
+reports. The wire protocol the substrate speaks is documented in
 [`agent/wsl-agent.sh`](../agent/wsl-agent.sh); the orchestration layers are
 [`lib/fsio-agent.js`](../lib/fsio-agent.js) (fsio's mechanics over the FS
 frames), [`lib/fs-substrate.js`](../lib/fs-substrate.js) (the provider-shaped

package/docs/CONFIGURATION.md

@@ -23,8 +23,7 @@ are schema defaults, listed because they are the ones worth knowing.
 | | `restrictToDistro` | `true` *(shipped)* | refuse a path in **another distro**'s share. `/mnt/c` is a directory *inside* the pinned distro, so it is not affected. The refusal carries `FS_OUTSIDE_DISTRO`; that is not a sandbox decision, so the file tools do not offer a wider permission for it. Set `false` to allow another distro's share |
 | | `sandbox` | `true` | check `writeText` and `editText` against the policy |
 | | `maskWindowsDrive` | `false` | as on `wsl-shell`: confined fs mutations publish through a resident whose profile shadows `/mnt` (same honest limits) |
-| | `substrate` | `agent` *(shipped)* | which I/O substrate serves the file tools: `agent` — the resident in-distro agent (`lib/fs-substrate.js`), where reads, writes and identities run on ext4: native symlinks, native mode bits, and the mutation guard survives to the write's atomic publication, kernel-enforced by the confined resident when the policy is confined. `share` — the opt-out: the Windows-side host stack over the 9p share, with the symlink-retry and publication hooks. Both substrates fence writes with the same host-side policy check. See [LIMITATIONS.md](LIMITATIONS.md) for what changes between them |
-| | `resolveSymlinks` | `true` | *(share substrate only)* follow Linux symlinks that the share cannot traverse, such as `/etc/os-release` and `/bin` — the agent substrate follows them natively |
+| | `substrate` | `agent` *(shipped)* | which I/O substrate serves the file tools. Only the resident in-distro agent (`lib/fs-substrate.js`) exists: reads, writes and identities run on ext4 — native symlinks, native mode bits, and the mutation guard survives to the write's atomic publication, kernel-enforced by the confined resident when the policy is confined. The former `share` opt-out (the Windows-side host stack over the 9p share) is refused at boot; delete the line |
 | | `cwd` | `''` | base directory for relative paths; empty means the distro user's home |
 | | `watchMaxDepth` | `0` | how deep the in-distro watch scan walks; `0` walks the whole tree. Bound it (e.g. `4`) when the watched tree holds a `node_modules` — a change below the bound is seen only when another change above it fires the same callback |
 | `directory-picker-wsl` | `preferredDistro` | `''` *(shipped)* | the distro listed first in the picker |
@@ -34,6 +33,7 @@ are schema defaults, listed because they are the ones worth knowing.
 | | `shell` | `''` | pin a shell; empty lets `wsl.exe` decide |
 | | `loginShell` | `true` | whether a pinned shell uses login semantics |
 | | `hostSessions` | `true` | give a session opened on a Windows folder a host `powershell.exe` in its own directory instead of the distro shell at `/mnt/<drive>/…`; `false` restores the composition-owned distro terminal for every session |
+| | `terminalIdleReclaim` | `true` | let the controller reclaim an idle distro terminal: the launch is marked with a per-terminal `DSH_TERMINAL_ID`, and the handle's `inspectActivity` counts the marked processes through the resident agent — one (the shell at its prompt) is idle, more than one (a running command or a nested shell) is busy, `unknown` (agent out) pauses reclamation. `false` restores close-by-hand |
 
 You can override the other keys in the same way; they keep their defaults. Those are
 `wslPath`, `hostCwd` and `forwardEnv` on the shell and terminal rows,

package/docs/LIMITATIONS.md

@@ -3,35 +3,31 @@
 What the plugin does not do, and why. A limitation that is documented is a design
 boundary; one that is not is a bug report waiting to happen.
 
-## The filesystem substrate (`wsl-fs` `substrate`)
+## The filesystem substrate (`wsl-fs`)
 
-`substrate: "agent"` (the default) serves the file tools through the resident
-in-distro agent, on ext4. `substrate: "share"` is the opt-out: the Windows-side
-host stack over the distro's 9p share. What differs:
+The file tools run on one substrate: the resident in-distro agent, on ext4 —
+reads, writes and identities happen where the files live. The former
+Windows-side share backend (`substrate: "share"`) is retired: a profile still
+carrying the value is refused at boot with the migration, and no file tool
+crosses the 9p share. What to know about the one substrate there is:
 
-- **A new file publishes with mode 0600 on the agent substrate.** That is the
-  host backend's own POSIX publication semantics (a private 0600 staging file,
-  renamed into place), which a Linux-host DSH session has always had. The share
-  substrate was the outlier: the share drops mode sets, so new files took the
-  distro's umask default (0644). Overwrites and edits keep the original bits on
-  both substrates. Run `chmod` (or ask the model to) when a new file must be
-  executable.
-- **There is no silent fallback to the share.** When the agent substrate's
-  resident process is out — the distro stopped, or the agent crashed past its
-  one rebuild — file operations fail with `FS_IO_ERROR` naming the substrate,
-  rather than quietly degrading to share semantics that cannot follow symlinks
-  or keep mode bits. The share substrate dies with the distro anyway; the
-  agent only adds its own failure mode, which is the one honest way to fail.
-  The failure message names the opt-out: set `substrate: "share"` in the
-  provider config to keep working on the Windows-side share while the agent
-  is out.
+- **A new file publishes with mode 0600.** That is the host backend's own POSIX
+  publication semantics (a private 0600 staging file, renamed into place), which
+  a Linux-host DSH session has always had; the share dropped mode sets and took
+  the umask default instead, and that behaviour is gone with the share.
+  Overwrites and edits keep the original bits. Run `chmod` (or ask the model to)
+  when a new file must be executable.
+- **When the agent is out, file operations fail closed.** The distro stopped, or
+  the resident crashed past its one rebuild: `FS_IO_ERROR` naming the substrate,
+  with the recovery path in the message. There is no fallback I/O to degrade
+  into — deliberately; the old failure message pointed at the share, and the
+  share is what this plugin exists to keep the model off.
 - **The mutation guard survives to the write.** `createIfAbsent` publishes with
   a no-replace link inside the distro, which closes the check-then-write window
   for creates outright. An overwrite or edit carries the version it was based
   on into the write op, and the agent re-verifies it against a fresh stat one
   syscall before the rename: a concurrent writer wins and the stale write
-  refuses with `FS_STALE_VERSION`. That narrows the share's window from a host
-  round trip to kernel-adjacent — the residual stat-then-rename pair is the
+  refuses with `FS_STALE_VERSION`. The residual stat-then-rename pair is the
   same sliver a Linux-host session's own rename has.
 - **Stage two routes mutations through a confined resident.** A write or edit
   under a confined policy runs on its own long-lived agent, spawned inside the
@@ -45,19 +41,15 @@ host stack over the distro's 9p share. What differs:
   the distro's `/tmp` lands in the confined mount's tmpfs, not the real `/tmp`
   — the same hand-off rule as the commands' `/tmp`: pass files through the
   session workspace.
-- **`resolveSymlinks` is not consulted.** The share cannot traverse Linux
-  symlinks, so the share substrate retries missing reads through the distro's
-  canonical path; the agent substrate never misses them, so the config key has
-  no effect there.
-- **`glob` and `grep` are unchanged on both substrates.** They are tool-layer
-  searches running the packaged Windows ripgrep against the share — correct
-  results, slow, and `.gitignore` interpreted with Windows rules. Bringing them
-  in-distro is future work, not part of the substrate switch.
-- **`watch()` is the same poll loop on both substrates** (a `find -newer` scan
-  inside the distro), so the coarse-invalidation caveats below apply equally.
-  An inotify backend is planned, not shipped.
-
-Everything below applies to the share substrate unless it says otherwise.
+- **`glob` and `grep` run the distro's own rg** (`lib/search-route.js`): the
+  tool's arguments are forwarded verbatim, so results, output format and exit
+  codes are rg's own — at ext4 speed, with the distro's `.gitignore` rules.
+  A distro without rg surfaces rg's own "command not found" (exit 127);
+  `npm run bootstrap -- <distro> --install` installs it. A search whose
+  directory is a Windows folder keeps the host binary, which is native there.
+- **`watch()` is one poll loop** (a `find -newer` scan inside the distro), so
+  the coarse-invalidation caveats below apply. An inotify backend is planned,
+  not shipped.
 
 - **The sandbox does not govern WSL interop.** A confined command can still run a
   Windows program, which escapes the Linux-side boundary. The plugin reports this as
@@ -77,35 +69,27 @@ Everything below applies to the share substrate unless it says otherwise.
   while the file tools' fence grants the distro's *real* `/tmp`. Both are writable, so
   neither side is refused, but a file the write tool puts in `/tmp` is invisible to
   `bash` and vice versa. Hand a file between them through the session workspace.
-- A distro that is stopped or unregistered while the app runs leaves the UNC share
-  unreachable: the shell tools report `wsl.exe`'s `WSL_E_*` code with the reason, but
-  the file tools can only report a file-level error, because the share itself is
-  gone.
+- A distro that is stopped or unregistered while the app runs takes the file
+  tools' substrate with it: reads and writes report the substrate-unavailable
+  error naming the cause, and recover on the next call once the distro starts.
 - `workspace-write` binds the workspace root as writable, and bubblewrap refuses a
   bind whose source directory does not exist, so a session whose workspace directory was
   deleted fails with a runner error; the plugin does not recreate it. A workdir that
   does not exist — a configured `cwd` pointing at a deleted directory, for instance — is
   a separate case and is now reported as an error naming that directory, because
   `wsl.exe` would otherwise run the command in `/` and exit 0.
-- New files get the distro's umask default (0644). A `chmod` from the Windows side on
-  a share path is silently ignored; overwrites and edits keep the original permission
-  bits. Run `chmod +x` inside the distro when you need an executable.
-- The check before a write is "check, then write", which is not atomic. This backend
-  checks the caller's guard itself, because the Windows backend publishes a guarded
-  new file with a hard link, and the share does not support hard links. This is the
-  race that `dsh-fs-sandbox` already documents — and one reason the share substrate
-  is the documented FALLBACK rather than the main path: its publication rides the
-  unconfined agent, so it never receives the confined resident's kernel-enforced
-  containment. The agent substrate does.
 - `watch()` observes from inside the distro (a `find -newer` poll loop, see
   `lib/watcher.js`), so events are coarse invalidation, not per-file notifications,
   and they arrive on the poll cadence, not instantly. A file created with an mtime
   older than the watcher's stamp (`cp -p`, `tar -x`) is not seen until something
   else touches the tree. Watching a 9p share from the Windows side remains
   unsupported — the loop runs where the kernel can actually report change.
-- `glob` and `grep` use the Windows-side ripgrep over the share: correct results, but
-  not fast, and `.gitignore` is interpreted with Windows rules. `editText` reads the
-  whole file into memory before writing it back.
+- `editText` reads the whole file into memory before writing it back.
+- The directory picker lists distro levels from inside the distro — the
+  resident's `ls -1ALp` in one round trip, a one-shot `wsl.exe --exec ls` when
+  it is out, never the 9p walk the host used to pay per entry. The listing is
+  line-parsed, so a filename containing a newline would render as two rows;
+  `/` cannot appear in a name, so nothing else can split one.
 - Terminal routing is per-session by workspace coordinates (`subprocess-wsl.hostSessions`,
   default on): a WSL-folder session gets the distro shell, a Windows-folder session gets
   `powershell.exe` in its own directory. The shell MENU remains the single configured
@@ -120,5 +104,19 @@ Everything below applies to the share substrate unless it says otherwise.
   Meanwhile, double-click a tab's title to rename it, or add `shellCandidates`
   to the `terminal-controller` row in your own profile layer — a manually
   selected shell is titled after itself.
-- Terminal activity reporting stops at `wsl.exe`, so the controller never reclaims
-  these terminals when they are idle.
+- Distro terminals ARE reclaimed when idle — the observation is distro-side:
+  each terminal is launched with a `DSH_TERMINAL_ID` marker, and the handle's
+  `inspectActivity` counts the marked processes through the resident agent
+  (`lib/terminal-activity.js`). Exactly one (the shell at its prompt) is
+  `idle`; more than one (a command, a pipeline, a nested shell) is `busy`;
+  `unknown` — the agent out, the distro stopped — pauses reclamation, because
+  a probe that cannot answer must not authorize a close. Consequences to
+  know: a nested shell keeps the terminal busy by design (closing it would
+  lose that shell), so does any process the shell's startup files spawn with
+  the inherited marker (an `ssh-agent` launched in `.bashrc` reads as busy);
+  the idle threshold is the controller's `unattendedTimeoutMs` (2 h by
+  default); and the host-side shell-activity integration is still not armed
+  for these launches — `wsl.exe` on win32 fails its gate — which is why the
+  observation is a scan rather than shell cooperation.
+- Windows-folder host terminals (the `powershell.exe` branch) keep the shipped
+  behaviour: `unknown` activity, no reclamation.

package/docs/PARITY.md

@@ -21,6 +21,13 @@ Not applicable, recorded so the gap is a decision and not an omission:
 - Settings Sync, Remote-SSH tunnel chaining, Codespaces: composition-layer
   responsibilities, not this plugin's.
 
+> **Update (2026-10-04).** The plan's transitional invariant — `wsl.agent:
+> false` must equal the pre-agent share-backed behaviour — is superseded: the
+> share substrate is refused at construction, and the search spawn rides the
+> distro's rg. The share is no longer a fallback path of this plugin; the
+> only fallbacks left are transport-level (one-shot `wsl.exe` where the
+> resident agent is out), never share I/O.
+
 ## Contract audit (Phase 0)
 
 Findings from reading the harness packages inside the app bundle; each one
@@ -40,10 +47,17 @@ shaped a phase of the plan.
    distro's share, rewrite the spawn to run a distro-side `rg` (falling back
    to `grep -rE` + `find` when absent) with identical stdout conventions.
    Under the agent, that exec rides the agent's `exec` capability.
-   **Not implemented, and recorded so the gap is a decision, not an
-   omission:** search still runs the packaged Windows rg over the share. The
-   interception was designed (above) but never landed; nothing in the phase
-   table below delivers it, and no phase claims it.
+   **LANDED (2026-10-04), as the design above has it:** `WslSubprocessRuntime`
+   .`spawn` performs the rewrite, the decision living in `lib/search-route.js`,
+   and the exec rides the agent's `exec` capability — Phase 1's resident —
+   through the minimal handle facade of `lib/search-exec.js` (the spawn seam
+   returns its handle synchronously, so the facade degrades inside `done`),
+   with the one-shot `wsl.exe --exec` handle as the fallback when the agent is
+   out. The `grep -rE` fallback is NOT implemented — grep does not read
+   `.gitignore`, so it is not an rg substitute; a missing distro rg surfaces
+   rg's own exit 127 with a bootstrap pointer instead. With the share
+   substrate retired the same day, no model-facing search crosses the 9p
+   share at all.
 3. **`dsh-fs-local` watches with chokidar over the share** — the behaviour
    this plugin replaces: chokidar on 9p is the unreliability that made
    `WslFileSystem.watch` refuse. The in-distro watcher replaces it wholesale.