dsh-plugin-wsl-env 0.7.5 → 0.9.0

package/docs/CONFIGURATION.md

@@ -6,26 +6,48 @@ profile layer: `$DSH_HOME/profiles/<name>/cordis.patch.yml`. Start from
 [`cordis.patch.yml`](../cordis.patch.yml) open beside it — that file is the commented
 reference for every value the plugin ships.
 
+Which rows a patch can reach depends on where they sit. `fs-routing`,
+`workspace-files-wsl`, `directory-picker-wsl`, `subprocess-wsl`, `wsl-shell-env`
+and `preset-wsl` are top-level rows, so `- id: <row>` in your layer patches them.
+`wsl-shell` and `wsl-fs` are not top-level: they are plugins of the `wsl` agent
+preset, nested inside the `preset-wsl` row's `config.plugins`. A patch that
+targets them by id matches nothing — the loader logs `patch: entry "wsl-shell"
+not found` (a warning, not an error), the profile boots anyway, and the value you
+wrote is not in force. See
+[Overriding the rows inside `preset-wsl`](#overriding-the-rows-inside-preset-wsl).
+
 In the table below, *(shipped)* marks the values set by `cordis.patch.yml`. The rest
-are schema defaults, listed because they are the ones worth knowing.
+are schema defaults, listed because they are the ones worth knowing. `wsl-shell-env`
+has its own table at the end of this page.
 
 | Row | Key | Default | Meaning |
 |---|---|---|---|
 | `wsl-shell` | `distro` | `''` *(shipped)* | distro name; empty means WSL's default distro |
 | | `shell` | `''` | pin a shell inside the distro; empty means the user's login shell |
-| | `loginShell` | `true` *(shipped)* | use `<shell> -lc`, which sources your profile, instead of a bare `-c` |
-| | `agent` | `true` | run commands over the resident in-distro agent (one long-lived process; in-distro timeout); any agent failure falls back to the one-shot `wsl.exe` path |
-| | `sandbox` | `true` | confine commands with `bubblewrap`; `false` disables the sandbox |
+| | `loginShell` | `true` *(shipped)* | use `<shell> -lc`, which sources your profile, instead of a bare `-c`. Applies only to the POSIX family; a non-POSIX shell (fish, csh) still gets a bare `-c` |
+| | `agent` | `true` | run commands over the resident in-distro agent (one long-lived process; in-distro timeout); the one-shot `wsl.exe` path is fallen back to only when the agent is out of service. Anything else — a cwd refusal, a sandbox refusal — is the command's own verdict and is raised, not retried on the other path |
+| | `sandbox` | `true` | confine commands with `bubblewrap`; `false` disables the sandbox. Needs a usable `bwrap` inside the distro and fails closed without one (`SANDBOX_UNAVAILABLE`, never an unconfined run) — see [Turning the sandbox off](#turning-the-sandbox-off) |
 | | `maskWindowsDrive` | `false` | shadow `/mnt` with an empty tmpfs in every confined profile: the Windows drive's files cannot be read or exfiltrated and its executables cannot be launched through interop — the hole that lets a "sandboxed" command reach your full Windows token. A narrowing, not a closure (a command can still write an executable into the workspace and run it — binfmt dispatches on content, not location), so enforcement stays `partial` and the result's sandbox fact reports `windowsDrive: "masked"`. The complete closure is distro-level: `[interop] enabled=false` in `wsl.conf` |
 | | `cwd` | `''` | default working directory; empty means the distro user's home |
 | | `timeoutMs` / `maxTimeoutMs` | `120000` / `600000` *(shipped)* | per-call time limit, and the ceiling a call may ask for |
 | `wsl-fs` | `distro` | `''` *(shipped)* | as above |
 | | `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 |
+| | `sandbox` | `true` | check `writeText` and `editText` against the policy. Needs a usable `bwrap` in the distro too, and fails closed the same way: a distro without one refuses confined mutations (`FS_IO_ERROR`, with the install guidance) rather than downgrading them |
 | | `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. 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 |
+| | `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. The comment shipped beside this key in `cordis.patch.yml` still calls `share` the opt-out — that comment is out of date, and the boot refusal is what runs |
 | | `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 |
+| `fs-routing` | `distro` | `''` *(shipped)* | which distro the root-plane filesystem routes to; empty resolves WSL's default. **A row of its own**, with its own copy of the distro knobs — changing `wsl-fs` does not change this one, nor the other way round |
+| | `wslPath` | `wsl.exe` *(shipped)* | path to `wsl.exe`; used here only to resolve the default distro |
+| | `sandbox` | `true` *(shipped)* | fence routed mutations by `ctx.sandboxPolicy`; same `bwrap` requirement and fail-closed refusal as `wsl-fs`. The routing row reports no `sandboxMode` — `undefined` whether the fence is on or off |
+| | `maskWindowsDrive` | `false` *(shipped)* | as on `wsl-shell`, for routed mutations |
+| | `restrictToDistro` | `true` *(shipped)* | refuse a path in another distro's share (`FS_OUTSIDE_DISTRO`) |
+| | `watchMaxDepth` | `0` *(shipped)* | how deep the routed watch scan walks; `0` walks the whole tree |
+| | `distroCwd` | `''` | the routed backend's default workdir; empty means the distro user's home. `cwd` belongs to the host backend only — the distro side reads `distroCwd` — while `diffBasisMaxBytes` is shared: it bounds the overwrite diff on both sides |
+| `workspace-files-wsl` | `maxBytes` | `2097152` *(shipped)* | byte cap on one page of a text read, and the default byte window of a byte read |
+| | `maxFileBytes` | `33554432` *(shipped)* | full-file byte cap for the byte reader |
+| | `maxLines` | `5000` *(shipped)* | line cap on one text read |
+| | `maxEntries` | `2000` *(shipped)* | directory entries listed per level before the listing is flagged truncated |
 | `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 |
@@ -35,13 +57,106 @@ are schema defaults, listed because they are the ones worth knowing.
 | | `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,
-`diffBasisMaxBytes` on `wsl-fs`, and `distroCacheMs` on the picker. The shell row
-also inherits the shipped output budgets — `maxOutputBytes` (64000 bytes per
-stream before the rest spills to a temporary file), `maxSpillBytes` (67108864) and
-`graceMs` (3000, the SIGTERM-to-SIGKILL grace) — from `dsh-bash-local`, which
-documents them in full.
+## Overriding the rows inside `preset-wsl`
+
+`wsl-shell` and `wsl-fs` are mounted as plugins of the `wsl` agent preset, inside
+the `preset-wsl` row's `config.plugins`. The loader indexes top-level entry ids —
+plus the plugin lists of rows that are themselves groups — and `preset-wsl` is a
+plain entry whose plugins sit inside its `config`, so those two ids are not
+addressable from a patch layer at all. A layer of
+
+```yaml
+- id: wsl-shell
+  config:
+    distro: Ubuntu
+
+- id: wsl-fs
+  config:
+    restrictToDistro: false
+```
+
+changes nothing and does not fail: the log carries
+`patch: entry "wsl-shell" not found` and `patch: entry "wsl-fs" not found`, and the
+composed config keeps the shipped values.
+
+The route that works is to override the `preset-wsl` row as a whole. A row's
+`config` is replaced whole, never deep-merged, so the replacement has to carry
+`id`, `order` and the entire `plugins` list — every plugin, the `wsl-env` group
+and everything after it. Copy the whole `- id: preset-wsl` block out of
+[`cordis.patch.yml`](../cordis.patch.yml) (or out of
+`dsh --profile <name> --dump-config`), paste it into your layer, and edit only the
+values you want:
+
+```yaml
+- id: preset-wsl
+  config:
+    id: wsl
+    order: 2
+    plugins:
+      - id: wsl-env
+        name: cordis:group
+        group: true
+        isolate:
+          shell: true
+          fs: true
+        config:
+          - id: wsl-shell
+            name: 'dsh-plugin-wsl-env'
+            config:
+              distro: Ubuntu          # ← the edit
+              loginShell: true
+              timeoutMs: 120000
+              maxTimeoutMs: 600000
+          - id: wsl-fs
+            name: 'dsh-plugin-wsl-env/fs'
+            config:
+              distro: ''
+              restrictToDistro: false # ← the edit
+              substrate: agent
+          # … and the rest of the group, verbatim — do not leave a plugin out …
+```
+
+Leaving a plugin out of the replacement drops it: the preset would mount only the
+plugins you listed. The keys described above are the only reason to rewrite this
+row, so treat the `preset-wsl` block as one unit and re-copy it after a plugin
+upgrade that changes it.
+
+For the root-plane filesystem — the row that serves `ctx.fs` outside any session,
+`fs-routing` — no rewrite is needed: it is a top-level row, and
+`restrictToDistro`, `sandbox` and `maskWindowsDrive` can be set on it directly.
+That governs different traffic from `wsl-fs`; see
+[`docs/root-fs-routing.md`](root-fs-routing.md).
+
+## Other keys
+
+You can override the other keys in the same way, with one split: every row in the
+table below except `wsl-shell` and `wsl-fs` is top-level, so `- id: <row>` in your
+own layer patches it — those two are inside `preset-wsl` and take the rewrite
+above. They all keep their defaults:
+
+| Row | Key | Default | Meaning |
+|---|---|---|---|
+| `wsl-shell` (in `preset-wsl`) | `wslPath` | `wsl.exe` | path to `wsl.exe`, for an installation that is not on `PATH` |
+| | `hostCwd` | unset → `%SystemRoot%` | the Windows directory the `wsl.exe` process itself starts in |
+| | `forwardEnv` | `[]` | extra host environment variable names to forward into the distro through `WSLENV`. This is the one key here that widens what crosses the boundary: `NO_COLOR`, `TERM`, `PAGER`, `GIT_PAGER`, `LANG`, `LC_ALL` and every managed `DSH_*` name ride along without it, and `PATH` is deliberately never forwarded |
+| `wsl-fs` (in `preset-wsl`) | `wslPath` | `wsl.exe` | as above; used only to resolve the default distro |
+| | `diffBasisMaxBytes` | `10485760` | UTF-8 byte limit per side of an overwrite diff; a larger file publishes without a diff |
+| `fs-routing` | `cwd`, `diffBasisMaxBytes` | `process.cwd()`, `10485760` | `cwd` configures the host side only (the distro side reads `distroCwd`); `diffBasisMaxBytes` is shared by both — it also bounds the routed backend's overwrite diff |
+| `directory-picker-wsl` | `wslPath` | `wsl.exe` | as above |
+| | `distroCacheMs` | `5000` | how long a resolved distro list stays fresh before `wsl.exe` is asked again |
+| `subprocess-wsl` | `wslPath` | `wsl.exe` | as above |
+| | `cwd` | `''` | fallback directory when a launch names none |
+| | `hostCwd` | unset → `%SystemRoot%` | as on `wsl-shell` |
+| | `forwardEnv` | `[]` | as on `wsl-shell`, for terminal launches |
+
+The shell row also inherits the shipped output budgets from `dsh-bash-local`,
+which documents them in full: `maxOutputBytes` (64000), `maxSpillBytes`
+(67108864) and `graceMs` (3000, the SIGTERM-to-SIGKILL grace). The spill keys
+belong to the one-shot path: with `agent: true` — the default — the capture is
+cut at `maxOutputBytes` per stream inside the distro, the result reports
+`truncated: true`, and no temporary file is written, so `maxSpillBytes` and
+`graceMs` have nothing to bound. They apply when `agent` is `false` or the agent
+is out of service and the call rides the one-shot `wsl.exe` path.
 
 ## Which distro is used
 
@@ -53,9 +168,58 @@ default is not the one you want sessions in.
 
 `sandbox: false` on `wsl-shell` and `wsl-fs` runs commands and writes without
 confinement. `sandboxMode` then reports `undefined`, and the tool layer tells the
-model that these operations have no sandbox. That is the documented opt-out; see
-[ARCHITECTURE.md](ARCHITECTURE.md#sandbox) for what the sandbox does and does not
-cover.
+model that these operations have no sandbox. `fs-routing` takes the same key and
+drops the fence on the root-plane filesystem the same way, but that service reports
+no `sandboxMode` either way — it inherits the base class's empty getter — so the
+key decides the fence, not a capability fact the model reads. That is the documented
+opt-out; see [ARCHITECTURE.md](ARCHITECTURE.md#sandbox) for what the sandbox does
+and does not cover.
+
+The default posture needs `bubblewrap` **inside the distro** and fails closed: a
+distro without a usable `bwrap` refuses the command (`SANDBOX_UNAVAILABLE`) or the
+write (`FS_IO_ERROR`, the message carrying the same guidance) instead of
+running it unconfined. The refusal distinguishes the two causes — `bwrap`
+missing (install it) from `bwrap` present but failing (usually the kernel's
+unprivileged user namespaces; reinstalling will not help) — and the direct
+install command it prints follows the distro's own package family
+(apt/dnf/pacman/zypper). A failed probe is re-run,
+so installing `bubblewrap` takes effect on the next command without a restart.
+Install it with `scripts/bootstrap.sh <distro> --install`, or directly:
+`wsl.exe -d <distro> -u root -- apt-get install -y bubblewrap`. Run without
+`--install`, `scripts/bootstrap.sh <distro>` is a read-only check that prints what
+is missing.
+
+The same probe also runs when a session opens: the `wsl-preflight` row warns
+with the full remedy if `bwrap` is unusable, so the news arrives with the
+session rather than with the first failed command. It is advisory — it never
+installs anything and never changes the fail-closed semantics; drop the
+`wsl-preflight` row from your layer (or set `sandbox: false` on it) to silence
+the warning.
+
+## Checking a change, and what refuses
+
+`dsh --profile <name> --dump-config` composes the profile and prints the result
+without booting. It is the fastest way to see whether a row you wrote landed —
+including the warning that says it did not — and for the rows inside `preset-wsl`
+the composed tree it prints carries the block to copy back into your layer.
+`scripts/bootstrap.sh <distro>` does the same for the distro-side prerequisites.
+
+When something refuses, the message names the row or the code:
+
+| Symptom | What you see | What clears it |
+|---|---|---|
+| commands fail with no usable sandbox | `SANDBOX_UNAVAILABLE` — the text says whether `bwrap` is missing or present but failing, with the matching remedy | missing: install `bubblewrap` (`scripts/bootstrap.sh <distro> --install`, or the printed family command); present-but-failing: check `bwrap --version` and the kernel's unprivileged user namespaces, or set `sandbox: false` on `wsl-shell` |
+| writes fail with no usable sandbox | `FS_IO_ERROR`, with the same `bwrap` remedy the commands carry | the same install, or `sandbox: false` on `wsl-fs` (`fs-routing` for root-plane writes) |
+| file tools fail while the distro is down | `FS_IO_ERROR`, "the distro file substrate is unavailable" | start the distro (`wsl.exe -l -v`), restart the session if it stays out |
+| a command never starts | a `WSL_E_*` code naming the distro | start it with `wsl.exe -d <distro>`, or point `distro` at another one — wider permissions do not help |
+| `wsl.exe` itself cannot be started | the error names the executable and says to check `wslPath` on this row | fix `wslPath`, and check WSL is installed |
+| WSL wedges mid-command | no completion within the deadline | retry once, then `wsl.exe --shutdown` and reopen |
+| a watched path never fires | `FS_IO_ERROR` from `watch` | watch a path inside the pinned distro |
+| a path in another distro is refused | `FS_OUTSIDE_DISTRO` | open a session in that distro, or set `restrictToDistro: false` |
+
+The full code table — what each code means and what clears it — is
+[ARCHITECTURE.md § Error codes](ARCHITECTURE.md#error-codes); the design boundaries
+behind the fail-closed choices above are in [LIMITATIONS.md](LIMITATIONS.md).
 
 ## `wsl-shell-env`
 

package/docs/LIMITATIONS.md

@@ -29,13 +29,21 @@ crosses the 9p share. What to know about the one substrate there is:
   syscall before the rename: a concurrent writer wins and the stale write
   refuses with `FS_STALE_VERSION`. The residual stat-then-rename pair is the
   same sliver a Linux-host session's own rename has.
+- **A write is durable against process death, not machine death.** The
+  publication fsyncs the staged file before its atomic rename, but the
+  containing directory is not fsynced afterwards: a kernel panic or power loss
+  immediately after a successful write can lose the rename, and the file
+  reverts to its pre-write content. The peer backend fsyncs its staged file the
+  same way, but neither fsyncs the containing directory — the exposure is the
+  peer's too, and it stays short of a crash-consistent store.
 - **A Linux filename containing a backslash cannot be addressed.** The UNC
   display form (`\\wsl.localhost\<distro>\...`) is the file's identity
   everywhere - the session header, the GUI, the caches - and the backslash is
   the UNC's separator, so `a\b.ts` in the distro round-trips to `a/b.ts`: the
   tools would silently address a different path. This is the coordinate
-  system's own limit (the peer's UNC provider has it too), not a defect of
-  the substrate; a rename away from backslash names is the workaround.
+  system's own limit — a backslash-delimited identity cannot spell a name
+  containing a backslash — not a defect of the substrate; a rename away from
+  backslash names is the workaround.
 - **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
   bwrap profile that binds exactly what the mode grants — so the kernel, not
@@ -45,32 +53,27 @@ crosses the 9p share. What to know about the one substrate there is:
   refuses them with the bootstrap command, rather than downgrading); a policy
   change addresses a different resident, so the first write after switching the
   Permissions selector pays one agent startup; and a write the policy grants to
-  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.
+  the distro's `/tmp` lands in the distro's real `/tmp`, because the
+  file-writes resident binds it read-write — where the read tools, the plain
+  resident and the user's own shell all see it. The ephemeral tmpfs belongs to
+  the command side alone, so a file handed over from a command still goes
+  through the session workspace.
 - **`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.
+  A distro without rg fails the search outright: exit 127, with the message
+  from the exec launcher and never from rg itself (which is the missing
+  program) — `setsid: failed to execute rg: No such file or directory` where
+  the distro has `setsid`, the script shell's `rg: not found` where it does
+  not. The install command `scripts/bootstrap.sh` prints — `wsl.exe -d <distro>
+  -u root -- apt-get install -y bubblewrap git ripgrep inotify-tools`, or the
+  detected family's spelling — installs it. `--install` runs that command only
+  when `bubblewrap` itself is missing, so a distro that has bwrap but not rg
+  needs the printed line run by hand. 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
-  `enforcement: partial`. See [ARCHITECTURE.md](ARCHITECTURE.md#reported-enforcement).
-  The `maskWindowsDrive` key on `wsl-shell` and `wsl-fs` narrows the hole: the
-  confined profile shadows `/mnt` with an empty tmpfs, so the drive's files cannot be
-  read or exfiltrated and its executables cannot be launched. It is not a closure — a
-  command that can write the workspace can write an executable there and run it
-  (binfmt interop dispatches on file content, not location) — so enforcement stays
-  `partial`, the result's sandbox fact reports `windowsDrive: "masked"`, and the only
-  complete closure remains distro-level (`[interop] enabled=false` in `wsl.conf`).
-- **`bubblewrap` must be installed**, or both providers fail immediately. The
-  usability probe re-runs after a failure, so installing bubblewrap while the app
-  runs is believed on the next command; only a success is cached.
 - **A confined command's `/tmp` is not the write tool's `/tmp`.** `workspace-write`
   mounts a fresh tmpfs at `/tmp` for the command — that is what makes it ephemeral —
   while the file tools' fence grants the distro's *real* `/tmp`. Both are writable, so
@@ -78,25 +81,77 @@ crosses the 9p share. What to know about the one substrate there is:
   `bash` and vice versa. Hand a file between them through the session workspace.
 - 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.
+  error naming the cause. A death with nothing in flight costs nothing — the
+  next call starts a fresh transport, so a distro that comes back is served
+  again. A death with a request in flight spends the resident's one permitted
+  rebuild, and when that rebuild cannot complete — the distro is still down, or
+  gone — the resident is permanently out: every later file operation fails the
+  same way until the app restarts.
+- `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 creation is seen even when
+  the new file's own mtime is old: creating it bumps the containing directory's
+  mtime, and the scan includes the watched directory itself (deletions are seen the
+  same way). What escapes the stamp is a change that leaves every scanned mtime
+  older than it — an in-place `cp -p` onto an existing file (new content, a
+  copied-back mtime), or a `tar -x` whose archive restores the containing
+  directory's own mtime. Watching a 9p share from the Windows side remains
+  unsupported — the loop runs where the kernel can actually report change.
+- `editText` reads the whole file into memory before writing it back.
+
+## The sandbox
+
+- **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
+  `enforcement: partial`. See [ARCHITECTURE.md](ARCHITECTURE.md#reported-enforcement).
+  The `maskWindowsDrive` key on `wsl-shell`, `wsl-fs` and `fs-routing` narrows the
+  hole: the confined profile shadows `/mnt` with an empty tmpfs, so the drive's files
+  cannot be read or exfiltrated and its executables cannot be launched. It is not a
+  closure — a command that can write the workspace can write an executable there and
+  run it (binfmt interop dispatches on file content, not location) — so enforcement
+  stays `partial`, the result's sandbox fact reports `windowsDrive: "masked"`, and
+  the only complete closure remains distro-level (`[interop] enabled=false` in
+  `wsl.conf`).
+- **`bubblewrap` must be installed**, or both providers fail immediately. The
+  usability probe re-runs after a failure, so installing bubblewrap while the app
+  runs is believed on the next command; only a success is cached. The refusal
+  classifies the probe's failure — missing versus present-but-failing — and the
+  direct install command follows the distro's package family; a probe failure
+  with no recognisable shape falls back to the install remedy with the raw
+  output quoted. A session-start preflight (`wsl-preflight`) surfaces the same
+  text as a warning; it is advisory and never installs.
 - `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.
-- `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.
-- `editText` reads the whole file into memory before writing it back.
+
+## Ports
+
+- **The port poller keeps the resident agent permanently warm.** The
+  `DSH_WSL_PORTS` snapshot refreshes through the shared resident agent every
+  `portsRefreshMs` (10 s by default, well inside the agent's idle timeout), so
+  while the app runs the agent never idles out: one `wsl.exe` and one
+  in-distro agent process stay resident per pinned distro even with no command
+  in flight. Raising `portsRefreshMs` past the agent's idle timeout restores
+  idle shutdown, at the cost of staler port facts.
+
+## The directory picker
+
 - 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.
+  line-parsed and only a line that ends in `/` becomes a row, so a directory
+  name containing a newline cannot be listed correctly: `ls` emits `a\nb` as
+  the two lines `a` and `b/`, and the picker offers the single row `b` at
+  `<parent>/b` — the part after the newline, a different directory or none at
+  all. A name that ends in a newline yields no row at all: the split leaves one
+  segment without a trailing `/` and one empty name, and the parser keeps
+  neither. `/` cannot appear in a name, so nothing else can split one.
+
+## Terminals
+
 - 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
@@ -124,6 +179,9 @@ crosses the 9p share. What to know about the one substrate there is:
   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.
+  observation is a scan rather than shell cooperation. `terminalIdleReclaim:
+  false` on the `subprocess-wsl` row restores close-by-hand: the launch then
+  carries no `DSH_TERMINAL_ID` marker, and the handle keeps the shipped
+  `unknown` activity, which never accumulates idle.
 - Windows-folder host terminals (the `powershell.exe` branch) keep the shipped
   behaviour: `unknown` activity, no reclamation.

package/docs/PARITY.md

@@ -1,18 +1,25 @@
 # Parity with VS Code Remote-WSL
 
 What parity means for this plugin, the seam contracts the plan was audited
-against, and the phase checklist. Every phase below ends with rows of this
-table ticked and this document updated in the same change.
+against, and the phase checklist with each phase's current status. The plan
+has landed; the rows below record where each phase ended up and what
+deviation, if any, still stands.
+
+Verified against: `dsh-plugin-wsl-env@0.8.0` / peer `0.2.0-rc.2` / agent
+protocol v4, 2026-10-06. Update this line when the peer pin or the agent
+protocol moves.
 
 ## What parity means here
 
 Remote-WSL's experience rests on one thing: a resident server inside the
 distro. Everything users love — native ext4 semantics, inotify, native
 `rg`, low latency — is a derivative. This plugin's 9p-UNC plus one-shot
-`wsl.exe` model can only approach it. The plan therefore lands a resident
-in-distro agent and migrates the `fs` and `shell` seams onto it, keeping the
-current paths as the documented fallback (`wsl.agent: false` must equal
-today's behaviour byte for byte).
+`wsl.exe` model can only approach it, so the plan landed a resident
+in-distro agent and moved the `fs` and `shell` seams onto it. The agent is
+now the only substrate for the file tools; the fallbacks left are at the
+transport level — the one-shot `wsl.exe` path that `wsl-shell.agent: false`
+pins for command execution, and that a search spawn drops to when the agent
+is out, never a share.
 
 Not applicable, recorded so the gap is a decision and not an omission:
 
@@ -21,12 +28,12 @@ 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.
+> **Update (2026-10-04).** The plan's transitional invariant — that
+> `wsl-shell.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)
 
@@ -47,17 +54,18 @@ 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.
-   **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.
+   **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 distro without one surfaces rg's own "command not found",
+   and `scripts/bootstrap.sh` reports whether the binary is installed. 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.
@@ -69,21 +77,41 @@ shaped a phase of the plan.
 
 ## Phase checklist
 
-| Phase | Deliverable | Parity row |
-| --- | --- | --- |
-| 0 | This document; contract audit above | baseline recorded |
-| 1 | `lib/agent/` + `wsl-agent` resident process: NDJSON-over-stdio protocol, capability handshake, lazy start, idle shutdown, crash-rebuild-once, permanent fallback | resident server |
-| 2 | real `watch()` SHIPPED (in-distro poll, `lib/watcher.js`); the native-ext4 migration of the remaining fs operations (and with it the workaround deletions) continues alongside Phase 3 | native file semantics, inotify — watch + publication done |
-| 3 | DONE — `WslShellExecutor` exec via agent; in-distro TERM→KILL; handle shape preserved (deviation: no streaming, no spill files) | native exec latency |
-| 4 | DONE (except the agent/plugin version handshake, which lands with the first agent-behaviour change after release) — `npm run bootstrap`, family-aware install command, `SANDBOX_UNAVAILABLE` names it | open-and-it-works |
-| 5 | DONE (routing half) — per-session routing by workspace coordinates (`terminal-route.js`, `hostSessions`); activity-based idle reclaim of distro terminals remains a documented limitation (PTY activity stops at `wsl.exe`) | terminal per window/session — routing done |
-| 6 | DONE — `DSH_WSL_PORTS` (agent-scanned `/proc/net/tcp{,6}`, timer-refreshed); localhost reachability (WSL2 localhost forwarding is platform behaviour) documented in README | port forwarding visibility |
-| 7 | DONE — recipes section in both READMEs: credential sharing, `/mnt/c` guidance, `WSLENV` policy | developer-loop odds and ends |
+| Phase | Status | Deliverable | Parity row |
+| --- | --- | --- | --- |
+| 0 | landed | This document; contract audit above | baseline recorded |
+| 1 | landed | `lib/agent.js` (with `lib/agent-protocol.js`, `lib/agent-shared.js`) and `agent/wsl-agent.sh`: resident process speaking a line protocol (pipe-separated fields, single-line base64 payloads), version + script-digest handshake, lazy start, idle shutdown, crash-rebuild-once, one-shot `wsl.exe` fallback for execution | resident server |
+| 2 | landed | real `watch()` shipped (in-distro mtime poll, `lib/watcher.js`); the native-ext4 migration of the remaining fs operations finished with the share's retirement — every model-facing file operation now runs on the agent, and the share-era workarounds went with it | native file semantics, change invalidation — watch + publication done (a poll, not inotify; blind spots in LIMITATIONS and CONFIGURATION) |
+| 3 | landed (deviation: no streaming, no spill files) | `WslShellExecutor` exec via agent; in-distro TERM→KILL; handle shape preserved | native exec latency |
+| 4 | landed | `npm run bootstrap`, family-aware install command, `SANDBOX_UNAVAILABLE` names it; the handshake ships the protocol version plus the script digest | open-and-it-works |
+| 5 | landed | per-session routing by workspace coordinates (`terminal-route.js`, `hostSessions`); idle distro terminals are reclaimed by a distro-side scan (`lib/terminal-activity.js`) — the host-side shell-activity integration still does not arm for `wsl.exe`, which is why the observation is a scan | terminal per window/session |
+| 6 | landed | `DSH_WSL_PORTS` (agent-scanned `/proc/net/tcp{,6}`, timer-refreshed); localhost reachability (WSL2 localhost forwarding is platform behaviour) documented in README | port forwarding visibility |
+| 7 | landed | recipes section in both READMEs: credential sharing, `/mnt/c` guidance, `WSLENV` policy | developer-loop odds and ends |
 
 ## Fallback invariant
 
-Every phase must keep `wsl.agent: false` (and, per capability, any runtime
-fallback) behaviourally identical to the pre-phase release. Probes assert
-this: `agent.sh` runs the same operations through the resident and through
-the one-shot `wsl.exe` path and compares outcomes — exit code, stdout bytes,
-stderr bytes, working directory — not internals.
+The plan's rule — every phase keeps the pre-phase behaviour byte for byte —
+is superseded by the Update above. What is still load-bearing is narrower,
+and no longer involves the share:
+
+- **Command execution.** `wsl-shell.agent: false`, and any agent failure at
+  runtime, run the command through the one-shot `wsl.exe` path, which is the
+  pre-agent `executeOneShot` verbatim; confinement and result decoration are
+  identical on both, and the budgets keep their shapes — the agent path cuts
+  each stream at `maxOutputBytes` inside the distro and reports
+  `truncated: true` with no spill file, where the one-shot path can spill
+  (`maxSpillBytes`, `graceMs`). The probe asserts this:
+  `pnpm run probe:agent` (`bash test/probe/agent.sh`, Windows + WSL only)
+  runs the same operations through the resident and through the one-shot path
+  and compares outcomes — exit code, stdout bytes, stderr bytes, working
+  directory — not internals.
+- **Search has no share fallback either.** The distro rewrite runs on the
+  resident agent — a distro-side `rg` must exist — and an agent that is out
+  drops the same spawn to the one-shot `wsl.exe --exec` handle
+  (`lib/search-exec.js`): a transport fallback, never the 9p share.
+- **File tools fail closed.** `wsl-fs.substrate` has one working value,
+  `agent`; a profile still carrying the retired `share` is refused at
+  construction. When the agent is out these operations fail closed with
+  `FS_IO_ERROR` naming the substrate — deliberately, there is no I/O to
+  degrade into, and with the share retired no model-facing file path crosses
+  9p.