dsh-plugin-wsl-env 0.5.0 → 0.7.2

package/CHANGELOG.md

@@ -12,6 +12,262 @@ 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
+evidence bar as its P0/P1 — every fix carries a check that fails without it,
+and the real-distro probes run green over the changed paths — plus the
+import-time regression that backlog carried, caught at the first
+sync-and-restart: `watchMaxDepth` was written `z.number().int()`, a member the
+pinned schemastery does not publish, which took `wsl-shell` and `wsl-fs` down
+in every distro workspace session. The key now uses `z.natural()`, and
+`test/syntax.mjs` reads the chained half of the schemastery surface so the
+next such member dies in CI instead of in the app.
+
+### Fixed
+
+- **The in-distro watcher no longer fails silently (review M10).** Four defects
+  in `lib/watcher.js`, fixed together because they share one loop:
+  the stamp file is removed on every way out (EXIT trap; TERM/INT/HUP routed
+  through a plain exit so the trap runs); a target that vanishes mid-watch now
+  ends the loop with a report through the error channel instead of arming
+  forever (`E` protocol line, unit- and probe-tested); the scan's depth is
+  boundable through the new `wsl-fs.watchMaxDepth` key (`0`, the default,
+  keeps the whole-tree walk); and the loop's stderr is drained continuously
+  with its tail kept for error context, so a chatty `sh` can no longer stall
+  the watch at the 64 KiB pipe limit.
+- **`watchMaxDepth` no longer takes both preset rows down at import (a
+  regression the M10 entry above introduced, caught after the first
+  sync-and-restart).** The key was written `z.number().int().min(0)`, but the
+  pinned schemastery publishes no `int` on any schema instance, and a Config
+  schema is a class field — so `lib/index.js` threw
+  `TypeError: z.number(...).int is not a function` while it was still being
+  imported, the loader left `wsl-shell` and `wsl-fs` fiber-less, and the preset
+  audit reported exactly those two rows as `never started`: every session in a
+  distro workspace, new or historical, failed at the first message. The key is
+  now `z.natural().default(0)` — the pinned spelling of "integer >= 0", the
+  idiom `picker` and `auto-preset` already use — and `test/syntax.mjs` now
+  reads the chained half of the schemastery surface (a balanced walk that
+  survives nested call arguments, string literals and template
+  interpolations), so a member the peer does not publish fails the suite
+  instead of waiting for the Desktop app. Reproduced and verified in a
+  peer-stub harness: the `lib/index.js` import went from the `TypeError` to
+  clean with the fix, and the new check fails on the old line.
+- **A wedged WSL service can no longer hang a tool call forever (review M11).**
+  Every `wsl.exe` resolution call in `lib/wsl.js` now runs under a deadline
+  (`DEFAULT_WSL_DEADLINE_MS`, 60 s — generous on purpose for cold boots, `0`
+  waits forever), and the deadline kill is named for what it is in the error,
+  with the `wsl.exe --shutdown` remedy. Separately, the agent execution path's
+  `confine()` now receives the request's abort signal, the same one the
+  one-shot path always passed.
+- **A timed-out command can no longer leave descendants running (review M12).**
+  EXEC requests run as their own session and process group (`setsid`, detected
+  at startup with a documented fallback), and the in-distro timeout and KILL
+  frames signal the whole group — TERM, then KILL after the grace, descendants
+  included. Proven by a new real-script check: a command that backgrounds a
+  marked shell and outlives its budget leaves zero survivors.
+- **Documentation drift cluster (review M9).** ARCHITECTURE.md's service table
+  claimed the share substrate was the default (it is `agent`), pointed at
+  `lib/sandbox.js` for `bwrapProfileArgs` (built in `lib/bwrap.js`), and kept
+  the long-gone `watch()` refusal in the error-code table; the `substrate`
+  schema docstring claimed watches run through the substrate (both substrates
+  ride the same `lib/watcher.js` poll loop); PARITY.md now records the rg
+  interception as designed-but-never-implemented instead of leaving it
+  implied; and the probe checklists (both READMEs, CONTRIBUTING, RELEASING,
+  the PR template, CI's comment) list the agent, watch, substrate and exec
+  probes that had shipped without being listed anywhere.
+
+### Changed
+
+- **Test structure (review M15).** The sandbox checks run everywhere now:
+  the probe-and-confine logic moved to the peer-free `lib/sandbox-core.js`
+  (one implementation, still shipped), `lib/sandbox.js` binds it to the peer's
+  `SandboxUnavailableError`, and the tests inject a stand-in with the same
+  `code` — CI no longer skips them. `FS_SANDBOX_DENIED`'s write-only
+  classification carries three unit checks (write denial classified, the same
+  signature ignored off the write path, ordinary permission failures keep
+  theirs). The probes stopped carrying inline bwrap profiles: `exec.sh` and
+  `sandbox.sh` derive their profiles from `lib/bwrap.js` itself, so a profile
+  change fails the probe instead of hiding behind a copy. `lib/wsl.js`'s
+  spawning half — previously probe-only — gained `test/wsl.test.mjs`.
+  `test/probe/agent.sh` is wired as `npm run probe:agent` like its siblings.
+
 ## [0.5.0] - 2026-10-04
 
 One theme: telling the truth, in the reader's language. The Plugins page now

package/CONTRIBUTING.md

@@ -69,6 +69,10 @@ terminal if you would rather not see the prompt.
 | `npm run probe:sandbox` | what bubblewrap confines and what it does not | no |
 | `npm run probe:sandbox-shell` | the confined executor through a real boot | yes |
 | `npm run probe:terminal` | the terminal provider | yes |
+| `npm run probe:substrate` | the agent filesystem substrate over a real `wsl.exe` transport | yes; inside the distro |
+| `npm run probe:watch` | the in-distro watcher over a real directory | yes; inside the distro |
+| `npm run probe:agent` | the resident-vs-one-shot fallback parity legs | yes; inside the distro |
+| `npm run probe:exec` | the agent-backed execution handle: timeout, kill, cwd failure | yes; inside the distro |
 | `npm run probe:missing-wsl` | how a `wslPath` that cannot start is reported | yes |
 | `npm run probe:picker` | the picker's root level, its refusals and its cap | yes |
 | `npm run probe:mode` | which POSIX-mode facts survive the share | no; Windows Node |

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
@@ -143,6 +143,9 @@ npm run probe                # filesystem probe against a real distro (Windows +
 npm run probe:sandbox-shell  # boot a real harness and drive the confined executor
 npm run probe:terminal       # open a PTY through the terminal provider
 npm run probe:substrate      # drive the agent filesystem substrate over a real wsl.exe transport (from inside the distro)
+npm run probe:watch          # arm the in-distro watcher over a real directory (from inside the distro)
+npm run probe:agent          # the resident-vs-one-shot fallback parity legs (from inside the distro)
+npm run probe:exec           # the agent-backed execution handle: timeout, kill, cwd failure (from inside the distro)
 npm run probe:missing-wsl    # boot a profile whose wslPath cannot start (Windows + WSL only)
 npm run probe:picker         # list the picker's root level, refusals and its cap (Windows + WSL only)
 npm run probe:mode           # which POSIX-mode facts survive the share (Windows node only)

package/agent/wsl-agent.sh

@@ -27,6 +27,10 @@
 #          With a cap, stdout and stderr are each cut at that many bytes and
 #          the flags say which streams were cut; 0 means the whole capture.
 #          or ERR|<id>|<reason>|<b64 message>   (reason: cwd)
+#       An EXEC request runs as its own session and process group (`setsid`),
+#       so a timeout or a KILL frame takes the whole descendant tree — not
+#       just the direct child, which is how a build tool's daemonized
+#       grandchild outlives the kill.
 #   FS|<id>|<op>|<timeout seconds|0>|<n args>
 #       followed by <n args> lines of base64, one argument each — arguments
 #       arrive still base64 so a write's content never passes through a shell
@@ -81,31 +85,58 @@ b64enc_file() {
 
 kill_current() {
   if [ -n "$CURRENT_PID" ]; then
-    kill -TERM "$CURRENT_PID" 2>/dev/null
+    kill_request TERM "$CURRENT_PID"
   fi
 }
 
+# Signal one in-flight request, descendants included. With `setsid` (EXEC
+# requests, below) the request is its own process-group leader, so the
+# negative PID signals the WHOLE group — every descendant that did not make
+# its own session. Without it the group does not exist, the negative-PID kill
+# fails with ESRCH, and the direct kill keeps the old guarantee. A shell whose
+# `kill` builtin cannot parse `-- -PID` at all also lands here.
+kill_request() {
+  # $1 = signal name, $2 = request PID.
+  kill -s "$1" -- "-$2" 2>/dev/null || kill -s "$1" "$2" 2>/dev/null || :
+}
+
 shutdown() {
   kill_current
   exit 0
 }
 trap shutdown TERM INT HUP
 
+# Whether EXEC requests can run as their own session. `setsid` makes the
+# request process a session AND process-group leader (pid = pgid), which is
+# what lets kill_request signal the whole descendant tree; the agent's own
+# shell cannot do this portably — `set -m` in a non-interactive dash has been
+# observed skipping the setpgid entirely, and a kill against a PID that is
+# not a group leader is a no-op. A distro without `setsid` keeps working:
+# requests then run in the agent's own group and the direct-child kill of the
+# pre-setsid behaviour applies.
+SETSID=
+if command -v setsid >/dev/null 2>&1; then
+  SETSID=setsid
+fi
+
 timeout_watcher() {
-  # $1 = seconds, $2 = pid, $3 = grace seconds. TERM first; a process that
-  # ignores TERM gets KILLed after the grace, so a stuck command cannot hang
-  # the request forever.
+  # $1 = seconds, $2 = pid, $3 = grace seconds. TERM first — the whole group,
+  # so a command that ignores TERM takes its descendants with it when the
+  # KILL lands; a process that ignores TERM gets KILLed after the grace, so a
+  # stuck command cannot hang the request forever.
   sleep "$1"
-  kill -TERM "$2" 2>/dev/null
+  kill_request TERM "$2"
   sleep "${3:-3}"
-  kill -KILL "$2" 2>/dev/null
+  kill_request KILL "$2"
 }
 
 # Capture one request's output and answer with RES. $1 = request id, $2 =
 # timeout seconds ('' or 0 = none), $3 = per-stream output cap in bytes (0 or
 # empty = unlimited), $4 = launch mode: `exec` runs "$@" (argv words) as the
-# request process; `subshell` runs ( "$@" ) in a forked subshell, which is how
-# the FS handlers — shell functions, not executables — run.
+# request process, in its own session via `setsid` when the distro has it —
+# the timeout and KILL then signal the whole descendant group; `subshell` runs
+# ( "$@" ) in a forked subshell, which is how the FS handlers — shell
+# functions, not executables — run.
 run_capture() {
   local req_id timeout_s maxout mode rc watcher_pid out_cut err_cut
   req_id=$1
@@ -121,6 +152,8 @@ run_capture() {
   CURRENT_ID=$req_id
   if [ "$mode" = subshell ]; then
     ( "$@" ) >"$OUT_FILE" 2>"$ERR_FILE" &
+  elif [ -n "$SETSID" ]; then
+    ( exec setsid "$@" ) >"$OUT_FILE" 2>"$ERR_FILE" &
   else
     "$@" >"$OUT_FILE" 2>"$ERR_FILE" &
   fi

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 Windows-side host stack over the distro's UNC share (default), or the resident in-distro agent on ext4. |
-| `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
@@ -146,7 +159,8 @@ wsl.exe -d <distro> --cd <linux dir> --exec bwrap \
 
 These are the same arguments DSH's Linux runner uses (`dsh-sandbox-local`), so the
 behaviour and the error messages match a Linux host. The function
-`bwrapProfileArgs` in [`lib/sandbox.js`](../lib/sandbox.js) builds them.
+`bwrapProfileArgs` in [`lib/bwrap.js`](../lib/bwrap.js) builds them — the
+peer-free builder every confinement site composes from.
 
 | Mode | What a command inside the distro can do |
 |---|---|
@@ -208,7 +222,7 @@ finds it here.
 | `FS_OUTSIDE_DISTRO` | `WslFileSystem.worldPath` | `restrictToDistro` is on and the path names **another distro**'s share — a configuration fence, not a sandbox decision | open a session in that distro, or set `restrictToDistro: false`. A wider permission does **not** lift it |
 | `FS_NOT_OBSERVED` | `WslFileSystem.assertGuard` | a guarded create (`createIfAbsent`) targeted a file that exists and had not been read first | read the file, then overwrite with the version guard or edit it |
 | `FS_STALE_VERSION` | `WslFileSystem.assertGuard` | the version the caller holds no longer matches: the file changed, or is gone | read it again and retry with the fresh version |
-| `FS_IO_ERROR` | `WslFileSystem.watch` | `watch()` is refused, because a 9p share cannot be watched reliably | poll, or watch from inside the distro |
+| `FS_IO_ERROR` | `WslFileSystem.watch` | the watch target is not a path inside the pinned distro, so there is nothing the in-distro poll loop can observe | watch a distro path; the watch itself runs where the files live (`lib/watcher.js`) |
 | `FS_NOT_FOUND` | the host filesystem stack | the path does not exist — the ordinary answer, passed through | — |
 
 Two failures come from `wsl.exe` itself rather than from a code of ours, and both used

package/docs/CONFIGURATION.md

@@ -23,9 +23,9 @@ 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 |
 | | `includeHostHome` | `true` *(shipped)* | also list the Windows home directory |
 | | `maxEntries` | `1000` *(shipped)* | maximum entries listed per directory |
@@ -33,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,