dsh-plugin-wsl-env 0.6.0 → 0.7.3

package/CHANGELOG.md

@@ -12,6 +12,235 @@ reference below points at that record's numbering.
 
 ## [Unreleased]
 
+## [0.7.3] - 2026-10-05
+
+One theme: the resident agent stops taking its world on faith - the
+handshake now verifies the deployment's content, the agent's lifetime
+survives a wedged host only by lease, and the one 9P consumer no row
+replacement could reach ships its seam-ready traversal.
+
+### Added
+
+- **The resident agent verifies its own deployment, and outlives a wedged
+  host only by lease.** The agent script is read in place from the
+  distro-visible path - in the deployed layout a `/mnt/c` mirror - so a
+  stale or half-synced runtime copy used to pass the version handshake
+  while drifting in behavior. The HELLO line now carries the sha256 of the
+  file the distro actually read (protocol v4), and both resident factories
+  pin the hash of the copy the package shipped: a mismatch is refused like
+  a version mismatch, with the resync command in the message. The agent
+  also terminates itself when its host goes silent without ever delivering
+  EOF - the wedged-relay case stdin EOF cannot cover: the host forwards a
+  client lease (`idleMs` + grace) through the managed `DSH_` namespace, and
+  an in-distro watchdog polls an in-flight marker so a long command's
+  silence never counts against it (dash has no `read -t`; a marker file is
+  the portable form). A boot sweep removes sibling `wsl-agent.*` temp dirs
+  no request has touched for an hour - the residue of agents whose host
+  died before their exit trap could run.
+- **The `@` completion's distro traversal is built and waiting for its seam.**
+  The one 9P consumer the takeover series could not reach - the GUI's `@`
+  file completion - funnels all workspace traversal through three
+  module-internal functions of the upstream `file-reference-local` service,
+  so no row replacement can reach them. The plugin now ships the consumer
+  side of RFC addendum ① (`lib/file-reference-wsl.js`): a traversal strategy
+  that lists a distro workspace through the resident agent with
+  `find -printf '%y\t%f'` - keeping readdir's Dirent fidelity, where
+  symlinks report neither kind and are skipped instead of resolved through
+  like `ls -L` would - replaces the upstream per-segment lstat walk with one
+  agent exec, and returns absolutes in the root's own coordinate system,
+  which the upstream scan joins children with. Deliberately not wired into
+  the composition: with the seam absent, reaching the funnels would mean
+  re-implementing the fuzzy ranking engine, the behavior-regression path
+  the RFC rules out. The module ships tested; the takeover lands the day
+  upstream takes the ~10-line parameter. The RFC addendum now carries the
+  concrete interface proposal.
+
+### Fixed
+
+- **The Windows CI legs are green again.** The fs boot test's end-to-end
+  legs read `platform is win32` as `the real-distro topology exists`, but
+  the CI Windows runners ship wsl.exe with no distro installed - every
+  Windows leg since the boot test landed failed there, which kept the
+  release gates red through 0.7.0-0.7.2 even after the missing-module
+  fix. The guard now asks WSL for its distro list and skips unless the
+  test's distro is actually installed.
+
+## [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/agent/wsl-agent.sh

@@ -12,7 +12,11 @@
 # one thing a distro is guaranteed to have is a shell.
 #
 # Handshake — the first line the agent writes:
-#   HELLO|wsl-agent|<protocol version>
+#   HELLO|wsl-agent|<protocol version>|<sha256 of this script file>
+# The digest lets the host verify that the script it is about to rely on is
+# byte-identical to the copy it shipped. The script is read in place — a
+# /mnt/c mirror in the deployed layout — so a stale or half-synced runtime
+# copy would otherwise pass the version handshake while drifting in behavior.
 # Requests the agent accepts, one per line on stdin:
 #   PING                          -> PONG
 #   SHUTDOWN                      -> exits 0
@@ -57,11 +61,55 @@
 
 set -u
 
-PROTO_VERSION=3
+PROTO_VERSION=4
 TMPDIR_AGENT=$(mktemp -d "${TMPDIR:-/tmp}/wsl-agent.XXXXXX")
 OUT_FILE="$TMPDIR_AGENT/out"
 ERR_FILE="$TMPDIR_AGENT/err"
-trap 'rm -rf "$TMPDIR_AGENT"; [ -z "${CURRENT_STAGING:-}" ] || rm -rf -- "$CURRENT_STAGING"; exit 0' EXIT
+trap 'rm -rf "$TMPDIR_AGENT"; [ -z "${CURRENT_STAGING:-}" ] || rm -rf -- "$CURRENT_STAGING"; [ -z "${WATCHDOG_PID:-}" ] || kill "$WATCHDOG_PID" 2>/dev/null; exit 0' EXIT
+
+# The content identity of this script file, reported in the handshake: the
+# host hashes its own shipped copy and refuses an agent whose file differs.
+# cut with an explicit space: sha256sum separates hash and file with spaces,
+# and the default tab delimiter would leave the whole line in the field.
+AGENT_DIGEST=$(sha256sum -- "$0" 2>/dev/null | cut -d' ' -f1)
+
+# Bounded cleanup: temp dirs from agents whose host died without giving them
+# an EXIT (a `wsl --shutdown`, a force-killed wsl.exe). Own pattern only, and
+# only when nothing inside moved for an hour — a live agent's dir mtime moves
+# on every request (the inflight marker in run_capture is created and
+# removed), so a sibling being served right now is never touched. A confined
+# agent's /tmp is a private tmpfs: its own dir vanishes with it and it sees
+# no siblings, so the sweep is a no-op there.
+for stale in "${TMPDIR:-/tmp}"/wsl-agent.*; do
+  [ -d "$stale" ] || continue
+  [ "$stale" = "$TMPDIR_AGENT" ] && continue
+  [ -z "$(find "$stale" -maxdepth 1 -mmin -60 -print -quit 2>/dev/null)" ] && rm -rf -- "$stale" 2>/dev/null
+done
+
+# The client lease: when the host goes silent without closing the pipe (a
+# wedged relay, not a dead one — EOF exits the read loop), the agent
+# terminates itself after the lease window instead of lingering with its
+# temp dir. The window rides DSH_AGENT_LEASE_MS from the host's pinned
+# environment, set above the host's own idle shutdown, so the lease only
+# fires when the host is gone in every way that matters. A request in
+# flight pauses the lease (the inflight marker) — a long command with no
+# traffic is silence, not absence. Unset (an older host, a manual run)
+# disables the lease: the host keeps the lifetime it always had.
+LEASE_S=0
+case ${DSH_AGENT_LEASE_MS:-} in
+  ''|*[!0-9]*) ;;
+  *) if [ "$DSH_AGENT_LEASE_MS" -gt 0 ]; then
+       LEASE_S=$(( (DSH_AGENT_LEASE_MS + 999) / 1000 ))
+       (
+         while :; do
+           sleep "$LEASE_S" || exit 0
+           kill -0 "$$" 2>/dev/null || exit 0
+           [ -f "$TMPDIR_AGENT/inflight" ] || kill -s TERM "$$"
+         done
+       ) &
+       WATCHDOG_PID=$!
+     fi ;;
+esac
 
 # The request currently in flight, for KILL and for the exit trap.
 CURRENT_PID=
@@ -150,6 +198,10 @@ run_capture() {
   : >"$OUT_FILE"
   : >"$ERR_FILE"
   CURRENT_ID=$req_id
+  # The inflight marker pauses the lease watchdog for this request and
+  # refreshes the temp dir's mtime for the boot sweep; removing it after the
+  # answer re-arms both.
+  : >"$TMPDIR_AGENT/inflight"
   if [ "$mode" = subshell ]; then
     ( "$@" ) >"$OUT_FILE" 2>"$ERR_FILE" &
   elif [ -n "$SETSID" ]; then
@@ -192,6 +244,7 @@ run_capture() {
     printf 'RES|%s|%s|%s|%s|%s|%s\n' "$req_id" "$rc" \
       "$(b64enc_file "$OUT_FILE")" "$(b64enc_file "$ERR_FILE")" 0 0
   fi
+  rm -f "$TMPDIR_AGENT/inflight"
 }
 
 # --- filesystem substrate (FS frames) -------------------------------------
@@ -488,7 +541,7 @@ fs_dispatch() {
   esac
 }
 
-printf 'HELLO|wsl-agent|%s\n' "$PROTO_VERSION"
+printf 'HELLO|wsl-agent|%s|%s\n' "$PROTO_VERSION" "$AGENT_DIGEST"
 
 while IFS= read -r line; do
   case $line in

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,