dsh-plugin-wsl-env 0.15.0 → 0.17.0

package/CHANGELOG.md

@@ -6,15 +6,106 @@ All notable changes to this project are documented here. The format follows
 
 The reasoning and the measurements behind each entry are in the archived
 engineering record,
-[docs/archive/engineering-record.zh.md](docs/archive/engineering-record.zh.md)
+[docs/archive/engineering-record.zh.md](https://github.com/Big-Dao/dsh-plugin-wsl-env/blob/main/docs/archive/engineering-record.zh.md)
 (Chinese, repository only — it is history, never a second README). A `§`
 reference below points at that record's numbering unless it names another
 document: the 0.1.0 entry's `design-history §` references are to
-[docs/archive/design-history.zh.md](docs/archive/design-history.zh.md), which
+[docs/archive/design-history.zh.md](https://github.com/Big-Dao/dsh-plugin-wsl-env/blob/main/docs/archive/design-history.zh.md), which
 keeps the superseded designs under the section numbers they had while they
 were part of the record.
 
-## [Unreleased]
+## [0.17.0] - 2026-11-01
+
+### Changed
+
+- **Git snapshot spawns are now agent-first with a one-shot fallback.**
+  Protocol v6 adds a stdin payload to the EXEC frame (a seventh header field
+  flagging one trailing base64 line), which is what lets `workspace-changes`'
+  snapshot calls — including `check-ignore -z --stdin` — run on the warm
+  resident agent instead of a one-shot `wsl.exe`. Measured on `ubuntu`
+  (2026-11-01): ~232 ms per one-shot git call (nearly all `wsl.exe` process
+  startup) against ~1.6 ms on the resident — a 6-8 call snapshot saves well
+  over a second. The per-stream caps map onto the agent's single wire cap with
+  a client-side per-stream slice (`lib/git-exec.js`), and the environment
+  rides the agent's per-request `env` (`env --` argv prefix, no `SETENV`
+  pollution) carrying only the translated `GIT_*` names. Both agents speak v6
+  (the shell agent decodes the payload through command substitution, which
+  strips trailing newlines — NUL separators survive; the native binary
+  delivers bytes verbatim), so host library and shipped binaries upgrade
+  together; the doctor's handshake reports any mismatch.
+
+- **WSL change review no longer requires Windows git.** When
+  `resolveExecutable('git')` fails on the host, the provider answers with a
+  distro sentinel (`/usr/bin/git`); every workspace-changes spawn — the
+  `rev-parse` discovery included — then routes into the distro, and the
+  snapshot facade translates the discovery call's absolute-path output lines
+  into UNC form (`translateDiscoveryOutput`). A machine with Windows git is
+  unchanged (host discovery + `safe.directory` whitelist). The
+  `resolveExecutable` override is scoped to the one name and only fires on
+  the super's failure.
+
+- **The doctor probes the Windows git trust.** A new `git.win-safe` check
+  reports the `safe.directory` whitelist state through interop `git.exe`:
+  `ok` when the `\\wsl.localhost` share is whitelisted, a warn with the
+  copy-paste remedy when Windows git does not trust it, and an info (nothing
+  to do) when there is no Windows git — the distro fallback covers WSL change
+  review entirely.
+
+### Documentation
+
+- The architecture and upstream-promotion documents reflect the v6 protocol
+  and the shell-menu candidates; the promotion map records the measurement
+  that superseded the git one-shot decision.
+- The full real-machine suite re-ran 15/0 on 2026-11-01 after the protocol
+  change landed, and again after the documentation refresh. The safe.directory
+  prerequisite for WSL change review is now documented with its one-time
+  remedy.
+
+- **The shell menu now offers host shells instead of a single entry.**
+  `terminal-controller`'s `shellCandidates` grows from `[]` to
+  `[wsl.exe, powershell, cmd]` while the default profile stays
+  `shell: { path: wsl.exe, name: WSL }`. `wsl.exe` dedupes into the default's
+  `wsl` kind; `powershell` and `cmd` are launches this terminal really starts —
+  host sessions already run PowerShell outright (`hostSessions`), and a manually
+  selected shell is titled after itself, which moves the tab-title workaround
+  from a user-layer edit into the plugin's own composition
+  ([#8769](https://github.com/deepseek-ai/deepseek-harness/discussions/8769)
+  remains the real fix for the default entry's title).
+
+## [0.16.0] - 2026-10-31
+
+The schema-validated routing row: the root-plane router stops silently
+ignoring a mistyped or wrong-typed distro key, and the first pass of the
+community-optimization plan stamps the routing documentation and the 1.0
+roadmap with dated, current evidence.
+
+### Changed
+
+- **`fs-routing` row config is now validated at load time.**
+  `WslRoutingFileSystem.Config` no longer blindly reuses
+  `LocalFileSystem.Config`: it is a `z.intersect` of the host row's schema and
+  the distro-side keys (`distro`, `wslPath`, `distroCwd`, `sandbox`,
+  `maskWindowsDrive`, `restrictToDistro`, `watchMaxDepth`). The Loader now
+  refuses to mount the row when a key fails its schema — previously a typo or
+  a wrong type was silently ignored and the distro side ran on defaults. A
+  `null` field value still falls back to the schema default, which matches how
+  the Loader treats optional keys. Composition tests mount the row through the
+  real Loader to assert both the accepted defaults and the rejected values.
+
+### Fixed
+
+- `docs/root-fs-routing.md` claimed a 12-probe suite with no routing probe, a
+  unit file outside the test lists, and a 10/10 composition test. All three
+  had drifted: the suite is 15 probes with `--include-fs` and includes
+  `fs-routing.sh`, `test/fs-routing.test.mjs` entered both test lists on
+  2026-10-19 (OI-7), and the composition test is 12/12. A header note stamps
+  the 2026-10-31 review.
+- `docs/ROADMAP-1.0.md` still described WSL-101 as implemented in the working
+  tree; it shipped in 0.13.0, and the status now records which acceptance leg
+  has real-machine evidence and which leg (concurrent two-distro) is still
+  missing. WSL-104's "routing probe has never been executed" claim is replaced
+  by the dated 2026-10-31 single-machine 15/0 result; the metrics row's probe
+  count moves to the current 15-with-fs breakdown.
 
 ## [0.15.0] - 2026-10-27
 
@@ -64,6 +155,44 @@ fixes the run surfaced, and the interop stance in one configuration key.
   fixture, and the picker probe now carries that fixture against the real
   composition. The LIMITATIONS entry retires.
 
+### Fixed
+
+- **The nightly sandbox probe no longer crashes when the runner workspace sits
+  outside the C: drive.** The probe's bwrap-profile builder imported
+  `lib/bwrap.js` by a raw Windows path; on a self-hosted runner whose
+  workspace is on another drive the ESM loader rejects the `d:` scheme and
+  the first nightly run failed. The import now goes through
+  `pathToFileURL` (same hardening applied to the watcher probe).
+
+- **The nightly probes job now tests the WSL topology, not the presence of
+  the binary.** The scheduled runs land on GitHub-hosted `windows-latest`
+  runners — no self-hosted runner carries that label, so the hosted fleet
+  picks the job up — and a hosted Windows image ships `wsl.exe` on PATH with
+  no distro behind it. The old `command -v wsl.exe` guard therefore always
+  passed, and the sandbox leg died inside wsl.exe itself: the last run
+  aborted on the `wslpath` translation with wsl.exe's own UTF-16 "no
+  installed distributions" surfacing as null bytes and exit 127 under the
+  step's `-e -o pipefail`. The guard now requires the default distro to
+  actually launch (`WSL_UTF8=1 wsl.exe -e true`); where it does not, the job
+  reports `skip all` — the honest no-op CONTRIBUTING now states. Where a
+  default distro does launch, the sandbox probe runs inside it through
+  `wsl.exe -e`, which is where the script's header and CONTRIBUTING already
+  place it: bubblewrap exists only there, so the leg could never pass from
+  Git Bash. The leg also picks up the `USER` resolution its sibling got in
+  the preceding fix (that hardening claimed `sandbox.sh` but changed only
+  `session-sandbox.sh`; a non-login `wsl.exe -e` shell needs it too). The
+  probe holds all 14 expectations under `env -u USER` in a distro.
+
+### Added
+
+- **`scripts/open-wsl-vscode.ps1` — open a WSL folder in VS Code through
+  Remote-WSL.** Opening the UNC share in VS Code is the degraded mode: files
+  cross 9p, the terminal is PowerShell, extensions run on Windows. The
+  helper translates a WSL UNC path (or a Linux path + distro) into the
+  `vscode-remote://wsl+<distro>` folder URI, so VS Code's server runs inside
+  the distro — local ext4, distro shell, distro extensions. The quickstart
+  documents it next to the workspace-opening step.
+
 ### Changed
 
 - **The doctor gains a cross-distro sessions view (WSL-309) and marks live
@@ -281,7 +410,7 @@ entry points.
   complete `preset-wsl` block, applies `distro`/`sessionSandbox`/`sandbox`/
   `maskWindowsDrive`/`agentBackend`, and `--check` fails loudly with the exact
   block to paste when a layer carries the nested id patch. See
-  [docs/CONFIGURATION.md](docs/CONFIGURATION.md#overriding-the-rows-inside-preset-wsl).
+  [docs/CONFIGURATION.md](docs/CONFIGURATION.md#configure-wsl-shell-and-wsl-fs).
 
 - **Session-notice upstream payload ready.** The exact title, body and `gh`
   command for the session-visible notice proposal are in
@@ -582,7 +711,7 @@ from it.
   longer the mechanism. The three deliberate deviations from the shipped copy
   — the `wsl-env` realm wrapping every row, the fixed shell-tool choice, and
   the preset's identity — are unchanged, and the transformation is now
-  [scripts/build-preset-wsl.mjs](scripts/build-preset-wsl.mjs) rather than the
+  [scripts/build-preset-wsl.mjs](https://github.com/Big-Dao/dsh-plugin-wsl-env/blob/main/scripts/build-preset-wsl.mjs) rather than the
   machine-local generator the block used to name: it takes the shipped file and
   prints the row, and its output is the committed block byte for byte.
 - `docs/UPSTREAM-TERMINAL-FONT.md` closes: the `0.2.1-rc.2` line made the
@@ -2184,7 +2313,7 @@ could not work, and one where the cause of a failure was invisible.
   is re-probed on the next command, and concurrent first commands share one probe. The
   policy lives in [`lib/probe-cache.js`](lib/probe-cache.js), which is pure, so the
   regression is pinned on every platform including CI
-  ([`test/probe-cache.test.mjs`](test/probe-cache.test.mjs)).
+  ([`test/probe-cache.test.mjs`](https://github.com/Big-Dao/dsh-plugin-wsl-env/blob/main/test/probe-cache.test.mjs)).
 - `restrictToDistro` refused another distro's share with `FS_SANDBOX_DENIED`. The
   file-tool layer turns that code into a denial marker plus an escalation offer
   (`mapError` in `dsh-tool-fs`), and no wider permission can lift this fence: it is a
@@ -2259,7 +2388,7 @@ Repository and release engineering. No runtime behaviour changed.
 
 ### Added
 
-- `npm run lint:style` ([`test/style.mjs`](test/style.mjs)): a dependency-free gate
+- `npm run lint:style` ([`test/style.mjs`](https://github.com/Big-Dao/dsh-plugin-wsl-env/blob/main/test/style.mjs)): a dependency-free gate
   over the rules `.editorconfig` states, plus three packaging checks — every `files`
   entry still matches tracked content, every `exports` target exists, and exactly one
   readme candidate sits at the package root. That last one is the regression guard
@@ -2269,14 +2398,14 @@ Repository and release engineering. No runtime behaviour changed.
   spawning half of `lib/wsl.js` and the four service modules are covered by the
   probes instead, which is why the function threshold is lower than the others.
 - `.github/workflows/release.yml`: a `v*` tag is checked against `package.json`
-  ([`scripts/check-release-tag.mjs`](scripts/check-release-tag.mjs)), gated, then
+  ([`scripts/check-release-tag.mjs`](https://github.com/Big-Dao/dsh-plugin-wsl-env/blob/main/scripts/check-release-tag.mjs)), gated, then
   published with `--provenance` through npm trusted publishing, and the GitHub
   Release is created from the changelog section
-  ([`scripts/changelog-section.mjs`](scripts/changelog-section.mjs)). No npm token is
+  ([`scripts/changelog-section.mjs`](https://github.com/Big-Dao/dsh-plugin-wsl-env/blob/main/scripts/changelog-section.mjs)). No npm token is
   stored in the repository.
 - The governance files a public repository is expected to carry:
   [`SECURITY.md`](SECURITY.md), [`CONTRIBUTING.md`](CONTRIBUTING.md),
-  [`SUPPORT.md`](SUPPORT.md), [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md),
+  [`SUPPORT.md`](SUPPORT.md), [`CODE_OF_CONDUCT.md`](https://github.com/Big-Dao/dsh-plugin-wsl-env/blob/main/CODE_OF_CONDUCT.md),
   `CODEOWNERS`, a pull-request template, bug-report and contact-link issue templates,
   and a Dependabot configuration for the pinned workflow actions.
 - [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) describes the plugin as it is
@@ -2285,16 +2414,16 @@ Repository and release engineering. No runtime behaviour changed.
   has to be reconstructed from a changelog and a historical record.
 - [`docs/RELEASING.md`](docs/RELEASING.md): the release checklist, including the
   operational facts that cost time to learn.
-- [`docs/archive/README.en.md`](docs/archive/README.en.md): an English index of the
+- [`docs/archive/README.en.md`](https://github.com/Big-Dao/dsh-plugin-wsl-env/blob/main/docs/archive/README.en.md): an English index of the
   Chinese archive.
 - `.nvmrc` names the Node version the coverage job uses.
 
 ### Changed
 
 - The probes no longer carry a user name, a home directory or a distro name.
-  [`test/probe/env.sh`](test/probe/env.sh) derives them from the machine
+  [`test/probe/env.sh`](https://github.com/Big-Dao/dsh-plugin-wsl-env/blob/main/test/probe/env.sh) derives them from the machine
   (`%USERPROFILE%`, `%LOCALAPPDATA%`, `WSL_DISTRO_NAME`) and
-  [`test/probe/env.mjs`](test/probe/env.mjs) does the same for the Node-side probes,
+  [`test/probe/env.mjs`](https://github.com/Big-Dao/dsh-plugin-wsl-env/blob/main/test/probe/env.mjs) does the same for the Node-side probes,
   which learn their own location from `import.meta.url`. The YAML overlays are now
   templates with `@NAME@` placeholders, and the scripts substitute real values into
   generated copies that `.gitignore` keeps out of the tree. The two profile layers
@@ -2516,7 +2645,7 @@ and the package installs as a bundle that contributes its own profile layer.
 - The README is now **current state only**. The five sections describing designs
   that this one replaced — the per-process `DSH_WSL` switch and the three
   abandoned tool-naming routes — moved to
-  [docs/archive/design-history.zh.md](docs/archive/design-history.zh.md), which
+  [docs/archive/design-history.zh.md](https://github.com/Big-Dao/dsh-plugin-wsl-env/blob/main/docs/archive/design-history.zh.md), which
   keeps their original numbering and records where each conclusion lives now.
   The README renumbered accordingly; its §0.1 explains the split. The one part of
   the old desktop section that is still current (regenerating the generated
@@ -2593,7 +2722,7 @@ Documentation that a reader would have acted on, and that was no longer true:
   current description of the plugin while its conclusions had been superseded
   three times over — most sharply by the sandbox work below — which is exactly
   the ambiguity a second README creates. It is now
-  [docs/archive/engineering-record.zh.md](docs/archive/engineering-record.zh.md):
+  [docs/archive/engineering-record.zh.md](https://github.com/Big-Dao/dsh-plugin-wsl-env/blob/main/docs/archive/engineering-record.zh.md):
   the same content, renamed out of the README slot and banner-headed as history,
   with README.md the single statement of current state. Nothing was deleted from
   the record; §0.1 names the conclusions that are now historical.

package/CONTRIBUTING.md

@@ -91,9 +91,8 @@ Three patterns keep the check honest:
   upstream seam gap, carries the reason inline, and the gap is written up — in a
   `docs/UPSTREAM-*.md` tracking doc when the fix is an upstream ask (the
   `LocalBashExecutor.spawnSpec` seam has one), or in the source comment itself
-  when the honest fix needs a protocol decision this package owns (the exit-4
-  relay's unknown entry kind is the other site, deliberately left visible). It
-  is a published finding, not a silencer.
+  when the honest fix needs a protocol decision this package owns. The current
+  exception is the `spawnSpec` seam; it is a published finding, not a silencer.
 
 ## The build
 
@@ -194,6 +193,7 @@ terminal if you would rather not see the prompt.
 | `pnpm run probe` | filesystem behaviour against a real distro | yes |
 | `pnpm run probe:sandbox` | what bubblewrap confines and what it does not | no |
 | `pnpm run probe:sandbox-shell` | the confined executor through a real boot | yes |
+| `pnpm run probe:interop-shell` | resident and one-shot interop for drive and copied executables, with and without the `/mnt` mask | yes |
 | `pnpm run probe:terminal` | the terminal provider | yes |
 | `pnpm run probe:substrate` | the agent filesystem substrate over a real `wsl.exe` transport | no; inside the distro |
 | `pnpm run probe:watch` | the in-distro watcher over a real directory | no; inside the distro |
@@ -226,13 +226,15 @@ still need Windows and WSL2, but no harness boot and no profile: run them from a
 distro terminal with Node available, and they reach `wsl.exe` through interop.
 
 Two conveniences for the real-machine set. `test/probe/run-all-when-closed.sh
---include-fs` runs all twelve probes once the app has exited. And `ci.yml` has a
-`probes` job you dispatch by hand: `sandbox` runs whenever WSL is present, then
-`mode`, `terminal`, `picker` and `missing-wsl` where the harness app is
-installed. It is named for a self-hosted Windows runner although its `runs-on`
-carries the hosted `windows-latest` label, and it is not a green no-op on a
-hosted runner — the `sandbox` leg fails, not skips, where the default distro has
-no bubblewrap.
+--include-fs` runs all fifteen probes once the app has exited. The interop shell
+matrix uses the `wslfs` profile, systemd and a lingering user manager; it fails
+when Windows interop or its temporary marker cannot be verified. And `ci.yml` has a
+scheduled and manually dispatched `probes` job: `sandbox` runs whenever a default distro
+actually launches, then `mode`, `terminal`, `picker` and `missing-wsl` where the
+harness app is installed. It is named for a self-hosted Windows runner although
+its `runs-on` carries the GitHub-hosted `windows-latest` label; when the hosted
+runner has no usable distro the job is a green no-op (`skip all`). Where a default
+distro launches without bubblewrap, the `sandbox` leg fails, not skips.
 
 ## Adding a test
 
@@ -245,19 +247,13 @@ Choose the layer by what the test needs.
 
 Unit tests run under `node --test`. The `test:unit` and the `test:coverage` lists
 in `package.json` name their files explicitly; a test that only touches this
-repository belongs in both. Two lags in those lists today are hygiene to fix in
-passing, not a pattern to copy: each names one file twice
-(`test/fsio-text.test.mjs` in `test:unit`, `test/fs.boot.test.mjs` in
-`test:coverage`), and `test/fs-routing.test.mjs` is in neither
-(`docs/REQUIREMENTS.zh.md` tracks that as OI-7).
+repository belongs in both. Keep the lists synchronized without duplicate entries.
 
 A test that imports a pinned `@deepseek-ai/*` package goes in the same lists and
 needs no guarding — CI runs `pnpm install --frozen-lockfile` over the locked tree
-before `pnpm test`. Five files import such packages at runtime today —
+before `pnpm test`. For example,
 `test/provider.test.mjs` is what covers the assembled service rows, and
-`test/composition.test.mjs` runs the loader's real patch algorithm — and a sixth
-(`test/terminal-activity.test.mjs`) reaches a peer only through a JSDoc type
-import, which `checkJs` still resolves.
+`test/composition.test.mjs` runs the loader's real patch algorithm.
 
 Where a peer-free seam exists, prefer it. `test/sandbox.test.mjs` runs against
 `lib/sandbox-core.js`, with a stand-in for the peer's `SandboxUnavailableError`
@@ -269,14 +265,13 @@ must skip itself — print a `SKIP` line and exit 0 — the way that file does o
 `win32`, where its fake `wsl.exe` (a POSIX script) cannot execute.
 
 Probes are shell scripts, plus the small plugin files they load: the `*-probe.mjs`
-and `*-probe.yml` files in the same directory. Two shapes. The harness probes
-(`run.sh`, `terminal.sh`, `sandbox-shell.sh`, `picker.sh`, `fs-routing.sh`,
-`missing-wsl.sh`, `sandbox-off.sh`) boot a throwaway profile whose setup steps
-are in the header of `test/probe/run.sh`; the six others reuse the profile
-`run.sh` creates rather than making their own. The distro probes (`substrate.sh`, `watch.sh`, `agent.sh`,
-`exec.sh`) boot nothing: they run from a distro terminal and drive the resident
-agent through the `wsl.exe` interop transport. `sandbox.sh` and `mode.sh` sit
-outside both groups — no harness boot, no profile.
+and `*-probe.yml` files in the same directory. Harness probes including `run.sh`,
+`terminal.sh`, `sandbox-shell.sh`, `interop-shell.sh`, `picker.sh`,
+`fs-routing.sh`, `missing-wsl.sh` and `sandbox-off.sh` use the throwaway profile
+whose setup is documented in the header of `test/probe/run.sh`. The distro probes
+(`substrate.sh`, `watch.sh`, `agent.sh`, `exec.sh`) boot no harness: they run
+from a distro terminal and drive the resident agent through the `wsl.exe` interop
+transport. `sandbox.sh` and `mode.sh` need neither a harness boot nor a profile.
 
 Keep probe output idempotent. Several probes delete their scratch files at the
 start, because a leftover file from an earlier run changes the result.
@@ -321,12 +316,9 @@ On Windows 11 + WSL2 (Ubuntu 26.04) the following has been verified:
   outside the session workspace is refused inside the distro and the following
   wider-permission request succeeds.
 
-Counts: 33 unit test files under `test/` — 32 of them registered in the
-`test:unit` list, see the OI-7 note above — which need the pinned packages
-installed, and over 1000 `assert` call sites across them; 19 filesystem-probe
-assertions; 15 shell-probe checks; 9 picker checks; 6 missing-executable checks;
-5 mode checks; 5 opt-out checks and 10 sandbox expectations plus the recorded
-escape; and 3 terminal assertions.
+The current unit and coverage test lists are in `package.json`; probe assertions
+and prerequisites are in the individual scripts. Verification results describe
+the tested environment and are not a substitute for rerunning the applicable gates.
 
 ## Good first issues and the contributor path
 

package/README.md

@@ -6,19 +6,19 @@
 [![npm](https://img.shields.io/npm/v/dsh-plugin-wsl-env)](https://www.npmjs.com/package/dsh-plugin-wsl-env)
 [![license](https://img.shields.io/npm/l/dsh-plugin-wsl-env)](LICENSE)
 
-A [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) plugin that runs a session inside a WSL 2 distribution on Windows.
+A [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) plugin that opens the project workspace inside a WSL 2 distribution on Windows.
 
-The harness process stays on Windows. Commands, file operations, the folder picker and the GUI terminal use the distro. No helper service or daemon is installed, no port is opened, and confined commands run under `bubblewrap`.
+The harness process stays on Windows. Command execution, shell scripts and file access all run in the distro's Linux environment for the full Linux shell toolchain. No helper service or daemon is installed, no port is opened, and confined commands run under `bubblewrap`.
 
 Windows + WSL 2 only.
 
-**New here?** Start with [docs/QUICKSTART.md](docs/QUICKSTART.md) — five minutes, prerequisites, recipes and the honest compatibility table.
+**New here?** Start with [docs/QUICKSTART.md](docs/QUICKSTART.md) — prerequisites, recipes and the compatibility table.
 
 ## Why this plugin
 
 A Windows coding tool that works on WSL projects has three options: run the whole tool inside the distro, connect to a helper server inside the distro, or let the plugin provide the distro environment. This plugin is the third option. One workflow covers both kinds of session, with the distro's real tools and the command sandbox intact.
 
-- **Real Linux environment.** Commands run in the distro's own login shell. Its `PATH`, `nvm`, `cargo`, `pyenv` and rc files apply. File tools read and write the distro's real files on ext4.
+- **Real Linux environment.** Commands run in the distro's own login shell. Its `PATH`, `nvm`, `cargo`, `pyenv` and rc files apply. File tools access distro paths through an in-distro agent; the backing filesystem depends on the path.
 - **No service in the distro.** There is no helper server, no daemon and no listening port. The only persisted artifact is a content-addressed copy of the native agent in `~/.cache/dsh-wsl/agent/`.
 - **Sandboxed by default.** Confined commands run under `bubblewrap` inside the distro. If `bubblewrap` is missing, the command fails; it does not run unconfined.
 - **Per-session.** A session opened on a distro folder gets the distro environment. A session opened on a Windows folder keeps the normal Windows tools. Both can run in one harness process.
@@ -74,7 +74,7 @@ Install `bubblewrap` before the first command:
 wsl.exe -d <distro> -u root -- apt-get install -y bubblewrap
 ```
 
-From a checkout, `pnpm run doctor` is the one-command environment check: Windows/WSL versions, the distro and its shell, bubblewrap usability, systemd / the user manager / Linger, the optional tools, peer versions, the agent cache, a fresh-agent handshake, stale session scopes and the known profile-patch trap. Each failure prints one copy-paste remedy; `--json` is for scripts, and `--fix` sweeps stale scopes (package installation needs `--fix --install` and an explicit confirmation). `pnpm run diagnose` is its read-only alias. `pnpm run bootstrap -- <distro>` remains the narrower tool-install helper.
+From a checkout, `pnpm run doctor` is the one-command environment check: Windows/WSL versions, the distro and its shell, bubblewrap usability, systemd / the user manager / Linger, the optional tools, peer versions, the agent cache, a fresh-agent handshake, stale session scopes and the known profile-patch trap. Each failure prints one copy-paste remedy; `--json` is for scripts, and `--fix` sweeps stale scopes (package installation needs `--fix --install` and an explicit confirmation). `pnpm run diagnose` is its read-only alias. `pnpm run bootstrap <distro>` remains the narrower tool-install helper.
 
 Upgrade by running the `add` command again. Uninstall with `dsh plugin --profile wsl remove dsh-plugin-wsl-env`; the agent cache under `~/.cache/dsh-wsl` can then be deleted. If you added a local `workspace-files-wsl` workaround to your profile to restore previews, remove it after upgrading: the plugin no longer mounts that row.
 
@@ -137,11 +137,11 @@ wsl preset (per session)
 | `workspace-write` | the above, plus the session workspace; `/tmp` is the distro's real `/tmp` with the session runtime |
 | `danger-full-access` | no sandbox |
 
-With `sessionSandbox: false`, each command gets a private `/tmp` instead of the distro's real one.
+With `sessionSandbox: false`, a `workspace-write` command gets a private `/tmp` instead of the distro's real one. `read-only` does not mount a writable `/tmp`.
 
 `bubblewrap` is required. If it is missing or broken, confined commands report `SANDBOX_UNAVAILABLE` and do not run. Setting `sandbox: false` on the owning row disables confinement; the model is told that the operation is unsandboxed.
 
-Enforcement is reported as `partial`. A command inside the distro can still start a Windows executable through `/mnt/c`, and `bubblewrap` cannot control Windows processes. `maskWindowsDrive: true` hides `/mnt` from the confined view, which narrows the hole but does not close it. The complete fix is distro-level: set `[interop] enabled=false` in `/etc/wsl.conf`. See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md#sandbox) and [SECURITY.md](SECURITY.md).
+Enforcement is reported as `partial`. A command inside the distro can still start a Windows executable through `/mnt/c`, and `bubblewrap` cannot control Windows processes. `maskWindowsDrive: true` hides `/mnt` from the confined view unless overridden by `interopVisibility: visible`; this narrows the hole but does not close it. Disabling WSL interop requires a separate distro-level change: set `[interop] enabled=false` in `/etc/wsl.conf`. See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md#sandbox) and [SECURITY.md](SECURITY.md).
 
 ## Troubleshooting
 
@@ -149,9 +149,9 @@ Enforcement is reported as `partial`. A command inside the distro can still star
 |---|---|
 | every command reports `SANDBOX_UNAVAILABLE` | install `bubblewrap` in the distro, or set `sandbox: false` |
 | the session refuses before the first command | run `pnpm run doctor`; enable systemd and linger, or set `sessionSandbox: false` on `wsl-shell` and `wsl-fs` |
-| `glob` and `grep` are slow in the distro | install `ripgrep` with `pnpm run bootstrap -- <distro> --install` |
+| `glob` and `grep` are slow in the distro | run `pnpm run bootstrap <distro>` and use its printed install command to install `ripgrep` |
 | `dsh plugin add` prints nothing | the plugin is already installed; this is success |
-| a profile patch for `wsl-shell`/`wsl-fs` changes nothing | those rows are nested inside `preset-wsl`. Run `pnpm run preset -- --check <patch>`; it fails with the complete block to paste |
+| a profile patch for `wsl-shell`/`wsl-fs` changes nothing | those rows are nested inside `preset-wsl`. Run `pnpm run preset --check <patch>`; it fails with the complete block to paste |
 | changes under `lib/` have no effect | run `pnpm run sync:windows`, then restart the app |
 
 More error codes and refusals are in [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md#error-codes). Everything the plugin does not do is in [docs/LIMITATIONS.md](docs/LIMITATIONS.md).
@@ -174,7 +174,7 @@ Real-machine probes run on Windows + WSL only. See [CONTRIBUTING.md](CONTRIBUTIN
 
 | Document | Content |
 |---|---|
-| [docs/QUICKSTART.md](docs/QUICKSTART.md) | five-minute first run, recipes, compatibility |
+| [docs/QUICKSTART.md](docs/QUICKSTART.md) | first run, recipes, compatibility |
 | [docs/PERFORMANCE.md](docs/PERFORMANCE.md) | ext4 agent vs 9p, measured latency, how to reproduce |
 | [docs/CONFIGURATION.md](docs/CONFIGURATION.md) | every configuration key and how to override it |
 | [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | services, path routing, sandbox, error codes |

package/SECURITY.md

@@ -88,14 +88,16 @@ This is a documented design boundary, not a vulnerability by itself. The command
 distro, where `bubblewrap` and `node` must be installed; the README states it in
 its Sandbox section.
 
-The strict profile (`maskWindowsDrive: true` with `sandbox: true`) narrows this:
-confined profiles shadow `/mnt` with an empty tmpfs, so the Windows executables
-cannot be launched from there. It does not close the hole — a Windows executable
+The strict profile (`maskWindowsDrive: true` with `sandbox: true`, without an
+overriding `interopVisibility: visible`) narrows this:
+confined profiles shadow `/mnt` with an empty tmpfs, so executables at paths
+under `/mnt` cannot be launched from there. Other mounts and unrestricted file
+reads are not covered. It does not close the hole — a Windows executable
 written into the workspace still runs, because WSL's `binfmt_misc` dispatches on
 content, not location — so the reported enforcement stays `partial`. The complete
 closure is distro-level (`[interop] enabled=false` in `/etc/wsl.conf`). The three
 states and their evidence are tabulated in
-[docs/CONFIGURATION.md](docs/CONFIGURATION.md#the-strict-profile).
+[docs/CONFIGURATION.md](docs/CONFIGURATION.md#windows-interop).
 
 A report is still welcome if you find an escape that does not depend on interop,
 if the masked profile is bypassable from `/mnt`, or if the plugin ever reports

package/SUPPORT.md

@@ -6,15 +6,15 @@
 |---|---|
 | Operating system | Windows 10 and Windows 11 |
 | Linux side | WSL2 with at least one distro, and systemd as PID 1 with a lingering user manager (`loginctl enable-linger`) for the shipped session runtime. Set `sessionSandbox: false` on the preset's `wsl-shell` to keep the per-command sandbox instead |
-| DSH packages | the `0.2.1-rc.3`-or-newer packages the `peerDependencies` floors declare; an app on a newer harness installs unchanged |
+| DSH packages | `peerDependencies` declares a `0.2.1-rc.3` floor; newer versions require compatibility validation |
+| Plugin version | the latest published version only |
+| Node | 22.19+ (`^22.19.0`), or 24 and later (`>=24.0.0`) |
 
 The DSH row is checked weekly: `.github/workflows/peer-canary.yml` resolves the
 `next` dist-tag of every pinned peer, installs that line into a scratch copy and
 runs `pnpm test` plus the composition boot test. A successful run prints the
 exact version delta in its summary; update the row above from that summary. A
 red run means the plugin has not been validated against the new line yet.
-| Plugin version | the latest published version only |
-| Node | 22.19+ (`^22.19.0`), or 24 and later (`>=24.0.0`) |
 
 Node 20 is outside the range on purpose: the floor is the harness host's own, and
 CI covers 22 and 24. `engines` in `package.json` is the authoritative statement,
@@ -60,10 +60,10 @@ issue for one.
 
 ## Compatibility expectations
 
-The upstream packages are a release candidate, so the peer versions are pinned
-exactly. One example is `@deepseek-ai/dsh-fs: 0.2.1-rc.2`. An upstream change can
-require a new release of this plugin. The exact pins are what make that break
-loudly instead of quietly.
+The DSH peer ranges start at `0.2.1-rc.3`; development dependencies pin that
+version exactly for testing. Cordis and Schemastery use caret peer ranges.
+The accepted range does not guarantee compatibility with every newer release:
+an upstream change can require a new release of this plugin.
 
 There is no long-term support branch. Fixes go to the latest version.
 
@@ -93,7 +93,7 @@ what it cannot see:
 
 | Item | How to get it |
 |---|---|
-| The diagnose report | `pnpm run diagnose -- <distro>` (read-only; safe to paste) |
+| The diagnose report | `pnpm run diagnose <distro>` (read-only; review and redact before sharing) |
 | Plugin version | `npm ls dsh-plugin-wsl-env`, or the git tag you built from |
 | DSH version | the version of the harness you run |
 | The composed configuration | `dsh --profile <name> --dump-config`, in particular the `dsh-plugin-wsl-env` layer and the rows it patches |

package/agent/wsl-agent.sh

@@ -24,8 +24,12 @@
 #   SETENV|<key>|<b64 value>      -> export the variable for later requests;
 #                                    <key> must be a POSIX identifier, else
 #                                    ERR|protocol
-#   EXEC|<id>|<b64 cwd>|<timeout seconds|0>|<n args>|<output cap bytes|0>
-#       followed by <n args> lines of base64, one argv word each
+#   EXEC|<id>|<b64 cwd>|<timeout seconds|0>|<n args>|<output cap bytes|0>|<stdin flag|0>
+#       followed by <n args> lines of base64, one argv word each, and — when
+#       the stdin flag is 1 — one more base64 line: the child's entire stdin.
+#       The agent feeds those bytes to the child and closes its stdin, so the
+#       child sees EOF at the payload's end. Absent or 0 means the child reads
+#       an empty stdin and immediate EOF (the v5 shape).
 #       -> ACK|<id> the moment the request is dequeued for execution — the host
 #          arms its stuck-request watchdog on this line, so time spent queued
 #          behind an earlier request never counts against a budget
@@ -50,9 +54,8 @@
 #          of its stderr (reason: notfound notdir perm loop exists stale io),
 #          which the host's adapter maps onto the FsError codes the tool layer
 #          knows. A `replace` write carrying an expected version re-verifies it
-#          against a fresh stat one syscall before the rename and refuses with
-#          `stale` on a mismatch — the concurrent writer wins, the model's
-#          stale write does not land.
+#          against a fresh stat before the rename and refuses with `stale` on
+#          a mismatch; a later concurrent write can still be overwritten.
 #
 # Confinement is NOT this script's business: the host wraps argv in the bwrap
 # profile (lib/sandbox.js) before the frame is sent, so the agent executes
@@ -63,7 +66,14 @@
 
 set -u
 
-PROTO_VERSION=5
+# v6: EXEC gains an optional seventh header field flagging one stdin payload
+# line after the argv words. One documented limitation, the same one SETENV
+# and every argv word already carry: command substitution strips TRAILING
+# NEWLINES from the decoded payload, so a stdin feed ending in `\n` reaches
+# the child without it (NUL bytes — `check-ignore -z` separators — survive).
+# Every known consumer parses line-oriented stdin that tolerates a missing
+# final newline.
+PROTO_VERSION=6
 TMPDIR_AGENT=$(mktemp -d "${TMPDIR:-/tmp}/wsl-agent.XXXXXX")
 OUT_FILE="$TMPDIR_AGENT/out"
 ERR_FILE="$TMPDIR_AGENT/err"
@@ -255,16 +265,23 @@ run_capture() {
     fi
   fi
   CURRENT_ID=$req_id
+  # Protocol v6 stdin: when the EXEC dispatch staged a payload file, the child
+  # reads its bytes and sees EOF at the file's end; otherwise /dev/null keeps
+  # the child off the agent's own stdin (the host pipe).
+  spawn_in=/dev/null
+  if [ -n "${EXEC_STDIN:-}" ]; then
+    spawn_in=$EXEC_STDIN
+  fi
   # 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
-    ( "$@" ) >"$spawn_out" 2>"$spawn_err" &
+    ( "$@" ) >"$spawn_out" 2>"$spawn_err" <"$spawn_in" &
   elif [ -n "$SETSID" ]; then
-    ( exec setsid "$@" ) >"$spawn_out" 2>"$spawn_err" &
+    ( exec setsid "$@" ) >"$spawn_out" 2>"$spawn_err" <"$spawn_in" &
   else
-    "$@" >"$spawn_out" 2>"$spawn_err" &
+    "$@" >"$spawn_out" 2>"$spawn_err" <"$spawn_in" &
   fi
   CURRENT_PID=$!
   # Dispatched: the child exists now, so the host may arm its execution
@@ -510,8 +527,8 @@ sweep_staging() {
 fs_write() {
   # $1 = base64 path, $2 = base64 mode (`-` keeps none), $3 = base64
   # `replace` or `no-replace`, $4 = expected version (`-` for none) — the
-  # version string this write was based on, re-verified one syscall before the
-  # rename so a concurrent writer wins instead of being clobbered — and $5 =
+  # version string this write was based on, re-verified before the rename;
+  # a later concurrent write can still be overwritten — and $5 =
   # content STILL base64. Mirrors fsio's POSIX publication: a private 0700
   # sibling staging dir, a 0600 temp, fsync, chmod, then an atomic rename — or
   # a hard link that refuses to replace for guarded creates.
@@ -676,7 +693,18 @@ while IFS= read -r line; do
       timeout_s=${rest%%|*}
       rest=${rest#*|}
       nargs=${rest%%|*}
-      maxout=${rest#*|}
+      rest=${rest#*|}
+      maxout=${rest%%|*}
+      # Protocol v6: an optional seventh field flags one stdin payload line
+      # after the argv words. Absent (a stale peer) or 0 keeps the v5 shape —
+      # the child reads an empty stdin and immediate EOF.
+      stdin_flag=0
+      case $rest in
+        *\|*) stdin_flag=${rest#*|} ;;
+        *) stdin_flag=0 ;;
+      esac
+      case $stdin_flag in ''|*[!01]*) stdin_flag=0 ;; esac
+      EXEC_STDIN=
       cwd=$(b64dec "$cwd_b64")
       if ! cd "$cwd" 2>/dev/null; then
         printf 'ERR|%s|cwd|%s\n' "$req_id" "$(printf '%s' "$cwd" | base64 | tr -d '\n')"
@@ -705,9 +733,20 @@ while IFS= read -r line; do
         printf 'ERR|%s|protocol|%s\n' "$req_id" "$(printf '%s' "an argv payload failed to decode" | base64 | tr -d '\n')"
         continue
       fi
+      if [ "$stdin_flag" = 1 ]; then
+        IFS= read -r stdin_b64 || exit 0
+        if ! b64dec_strict "$stdin_b64"; then
+          printf 'ERR|%s|protocol|%s\n' "$req_id" "$(printf '%s' "the stdin payload failed to decode" | base64 | tr -d '\n')"
+          continue
+        fi
+        EXEC_STDIN="$TMPDIR_AGENT/stdin.$req_id"
+        printf '%s' "$DEC" >"$EXEC_STDIN"
+      fi
       # Dispatched: run_capture prints the ACK once the child exists, so the
       # host's watchdog and USR1 cancel both target a real process.
       run_capture "$req_id" "$timeout_s" "$maxout" exec "$@"
+      [ -n "$EXEC_STDIN" ] && rm -f -- "$EXEC_STDIN"
+      EXEC_STDIN=
       ;;
     FS\|*)
       header=${line#FS|}