dsh-plugin-wsl-env 0.7.5 → 0.9.0

package/CONTRIBUTING.md

@@ -10,35 +10,145 @@ the conventions this repository uses.
 | Windows 10 or 11 | the plugin targets Windows only |
 | WSL2 with at least one distro | `wsl.exe -l -v` lists the installed distros |
 | `bubblewrap` in the distro | `sudo apt install bubblewrap`. The sandbox fails closed without it. |
-| Node 20, 22, or 24 | the versions CI runs. `engines` requires `>=20`. |
+| Node 22.19+, or 24 | the versions CI runs. `engines` requires `^22.19.0 \|\| >=24.0.0`, the harness host's own floor. |
 
 ## Toolchain
 
-The package has no dependencies, so there is no install step. Run the scripts
-straight from a checkout.
-
-`npm` runs the scripts in this repository, and CI uses npm. Treat
-`npm run <script>` as the reference toolchain.
-
-Do not add a runtime dependency. The package ships an empty `dependencies` object
-on purpose, because it is loaded into the DSH process and everything it needs
-arrives as a peer package.
-
-Style tooling is kept out for the same reason. There is no ESLint, no Prettier, and
-no `devDependencies` at all. The checks that would normally need them are built
-from Node builtins instead. `test/style.mjs` verifies the rules `.editorconfig`
-states, and it checks that every `files` entry still matches tracked content and
-every `exports` target still exists. The syntax pass inside `npm test` uses Node's
-own parser.
+The runtime package ships no `dependencies` field at all, on purpose: it is
+loaded into the DSH process and everything it needs arrives as a peer package.
+Running the plugin from a checkout has no install step.
+
+Developing and running the gates do have dependencies. The tests import pinned
+`@deepseek-ai/*` packages — the composition test runs the loader's real patch
+algorithm, and the boot test starts a row through the real Loader — so a fresh
+checkout needs one `pnpm install` before the gates pass.
+
+Those pins are deliberate, and they move with the harness rather than on their
+own: the `@deepseek-ai/dsh-*` peers sit at `0.2.0-rc.2`, `@deepseek-ai/cordis`
+at `~4.0.4` and `@deepseek-ai/schemastery` at `~3.18.4`. The plugin subclasses
+peer classes and mirrors peer protocol, so raising one pin alone is how the
+seams drift: bump them in the commit that matches a harness release, re-run the
+comparison `docs/PEER-PARITY.md` describes, and let the gate chain and the
+probes confirm the result.
+
+pnpm runs the scripts in this repository, pinned through the `packageManager`
+field (corepack resolves it). Treat `pnpm run <script>` as the reference
+toolchain.
+
+Do not add a runtime dependency — see above. Style tooling is kept out for the
+same reason: there is no ESLint and no Prettier. The checks that would normally
+need them are built from Node builtins instead. `test/style.mjs` verifies the
+rules `.editorconfig` states, and it checks that every `files` entry still
+matches tracked content and every `exports` target still exists. The syntax pass
+inside `pnpm test` uses Node's own parser.
+
+Exactly three dependencies run install scripts (`@deepseek-ai/dsh-subprocess-local`,
+`koffi`, `node-pty` — the native pieces); they are allow-listed in
+`pnpm-workspace.yaml` and everything else builds nothing.
+
+## The type gate
+
+`lint:types` runs `tsc --noEmit` under `strict` with `checkJs` over what is NOT
+generated — `test/**` and the ambient types — and the types come from the peer
+packages' own `.d.ts`: nothing is invented twice. `types/dsh-services.d.ts`
+pulls in the `declare module '@deepseek-ai/cordis'` augmentations the service
+packages ship, so `ctx.fs`, `ctx.shell`, `ctx.sandboxPolicy` and friends are
+typed; it declares nothing itself and ships nowhere.
+
+The probe scripts under `test/probe/` are inside the gate as well. The sources
+under `src/` are checked by the build program itself (`strict`,
+`noEmitOnError`), which is strictly stronger than checking their emitted
+JavaScript. The shipped artifact was checked first because it is where protocol
+drift with the pinned peers hurts; the tests and probes came next, and the
+errors they surfaced were real — a test that pinned a raw number into an argv,
+a couple of hand-written JSDoc contracts wider than the code (`wslErrorCode`,
+`gitSpawnRewrite`) and narrower than their seams, and one
+accepted-but-never-enforced byte-window cap in the distro-routed file service,
+found because a fake hands the confinement seam an `"full"` enforcement the core
+itself never reports.
+
+Three patterns keep the check honest:
+
+- A subclass's own config keys are declared as a type mirroring its
+  `static Config` schema and read through one explicit cast — the schema and
+  the type can then only drift apart visibly.
+- A test double is typed as the slice of the seam it scripts (a duck
+  `@typedef`) and reaches the seam's declared type through one documented cast
+  at the injection point — the cast states which contract the double stands in
+  for, instead of silencing the mismatch with `any`.
+- `@ts-expect-error` is allowed exactly when the suppressed error names a real
+  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.
+
+## The build
+
+The plugin must be loadable from a bare checkout: the harness has no
+transpilation layer, the Windows runtime mirror is a copy of the tree, and the
+tests exercise `lib/*.js` — the published artifact — rather than the sources.
+Sources live in `src/`, built JavaScript and declarations in `lib/`, and the
+artifacts stay COMMITTED. `pnpm run build` (`scripts/build.mjs`) runs one pass —
+`tsc -p tsconfig.build.json` — emitting every `src/*.ts` as JavaScript plus its
+declaration under the same export paths as the hand-written modules it
+replaced. Imports name the artifact (`./x.js`); `nodenext` resolves that
+through the TypeScript source. The build then prunes declarations no source
+owns (a rename leftover), so `lib/` is exactly the artifacts of `src/`.
+
+Rules that keep this honest:
+
+- Never edit a generated file under `lib/` — its module doc names the source
+  to edit and `lint:build` fails the moment the two drift. Generated artifacts
+  keep tsc's canonical formatting (four-space, compacted); review `src/` for
+  every module.
+- `lint:build` (`test/build-freshness.mjs`) enforces that the corpus is closed
+  — every `lib/*.js` has its `src/<name>.ts`, every source has both artifacts —
+  then snapshots every generated file, runs the real build, byte-compares and
+  RESTORES the snapshot: a check, not a rebuild; the remedy for drift is
+  `pnpm run build` plus a commit. It is part of the gate chain after
+  `test:syntax`.
+- Generated files are not in the `checkJs` gate at all (`tsconfig.json` covers
+  `test/**` and the ambient types); their sources are type-checked by the build
+  program with `noEmitOnError`, so a broken build never overwrites `lib/`.
+- Every JavaScript export carries its `types` condition (enforced by
+  `lint:style`), so downstream resolves these declarations; there is no
+  second, hand-written type surface.
+- The protocol message union and friends are the single home now: consumers
+  import them (`@typedef {import("./agent-protocol.js").AgentMessage}
+  AgentMessage`) instead of restating them, which is how `lib/agent.js` and
+  the script-driven tests read them.
+
+### Adding a module
+
+1. Write `src/<name>.ts`; imports name the artifact (`./x.js`), which
+   `nodenext` resolves through the TypeScript source. Move every type into the
+   signature, keep the prose, and keep every exported NAME — types included,
+   since consumers import them (`import("./paths.js").DistroPath`). Close the
+   module doc with the note that names the generated artifact.
+2. `pnpm run build`, then `pnpm test`. There is no exclude list to maintain and
+   no registration step: the build and `lint:build` derive everything from
+   `src/`, and `lib/` is generated output — never edit it by hand.
+3. If the module gets a row of its own on the Plugins page, add its display
+   metadata as `locale/<name>/en.json` and `locale/<name>/zh.json` — a
+   `meta.title` / `meta.description` pair each — and expose both through
+   `exports` (`./<name>/locale/en.json`, `./<name>/locale/zh.json`), which is
+   what that page reads before falling back to the package `description`. The
+   bundle's own pair is `locale/en.json` / `locale/zh.json`, and `subprocess`,
+   `picker`, `shell-env` and `auto-preset` carry theirs; `files` already ships
+   `locale/**/*.json`, and `lint:style` fails an `exports` target that does not
+   exist.
 
 ## The development loop
 
 1. Clone the repository inside the distro. Most contributors develop there.
 2. Make the change.
 3. Run the gates below.
-4. Restart the DSH app before testing by hand, if you changed anything under
-   `lib/`. A running process caches ES modules, so it keeps the old code
-   otherwise.
+4. If you changed anything under `lib/`, run `pnpm run sync:windows` first and
+   then restart the DSH app. The app loads the Windows mirror (see below), so a
+   restart without the sync just reloads the old code; a running process also
+   caches ES modules.
 
 ### The runtime mirror
 
@@ -50,7 +160,7 @@ The Windows copy under `default-workspace/dsh-plugin-wsl` is a runtime mirror. S
 it before launching the app:
 
 ```bash
-npm run sync:windows
+pnpm run sync:windows
 ```
 
 The mirror destination sits outside a session workspace. An agent that runs the
@@ -62,28 +172,31 @@ terminal if you would rather not see the prompt.
 
 | Command | Covers | Needs a harness |
 |---|---|---|
-| `npm test` | style checks, syntax pass, and unit tests | no |
-| `npm run test:coverage` | unit tests with coverage | no |
-| `npm run lint:style` | style and lint rules | no |
-| `npm run probe` | filesystem behaviour against a real distro | yes |
-| `npm run probe:sandbox` | what bubblewrap confines and what it does not | no |
-| `npm run probe:sandbox-shell` | the confined executor through a real boot | yes |
-| `npm run probe:terminal` | the terminal provider | yes |
-| `npm run probe:substrate` | the agent filesystem substrate over a real `wsl.exe` transport | yes; inside the distro |
-| `npm run probe:watch` | the in-distro watcher over a real directory | yes; inside the distro |
-| `npm run probe:agent` | the resident-vs-one-shot fallback parity legs | yes; inside the distro |
-| `npm run probe:exec` | the agent-backed execution handle: timeout, kill, cwd failure | yes; inside the distro |
-| `npm run probe:missing-wsl` | how a `wslPath` that cannot start is reported | yes |
-| `npm run probe:picker` | the picker's root level, its refusals and its cap | yes |
-| `npm run probe:mode` | which POSIX-mode facts survive the share | no; Windows Node |
-| `npm run probe:sandbox-off` | the documented opt-out on both providers | yes |
-
-Every script above is wired in `package.json`. `npm test` runs `lint:style`,
-`test:syntax` and `test:unit` in that order. `prepublishOnly` runs `npm test` again
-at publish time, so a broken gate stops a release before the upload.
-
-CI runs `npm test` on Node 20, 22 and 24, on both `ubuntu-latest` and
-`windows-latest`, and `npm run test:coverage` on Node 24. The Windows runners are
+| `pnpm test` | style checks, syntax pass, build consistency, type check, and unit tests | no |
+| `pnpm run test:coverage` | unit tests with coverage | no |
+| `pnpm run lint:style` | style and lint rules | no |
+| `pnpm run lint:build` | the build-freshness check: every source has its artifacts and the committed bytes match a real build | no |
+| `pnpm run lint:types` | the TypeScript check over `test/**` and the ambient types (`tsc --noEmit`) | no |
+| `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: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 |
+| `pnpm run probe:agent` | the resident-vs-one-shot fallback parity legs | no; inside the distro |
+| `pnpm run probe:exec` | the agent-backed execution handle: timeout, kill, cwd failure | no; inside the distro |
+| `pnpm run probe:missing-wsl` | how a `wslPath` that cannot start is reported | yes |
+| `pnpm run probe:picker` | the picker's root level, its refusals and its cap | yes |
+| `pnpm run probe:mode` | which POSIX-mode facts survive the share | no; Windows Node |
+| `pnpm run probe:sandbox-off` | the documented opt-out on both providers | yes |
+
+Every script above is wired in `package.json`. `pnpm test` runs `lint:style`,
+`test:syntax`, `lint:build`, `lint:types` and `test:unit` in that order.
+`prepublishOnly` runs `pnpm test` again at publish time, so a broken gate stops a
+release before the upload.
+
+CI runs `pnpm test` on Node 22 and 24, on both `ubuntu-latest` and
+`windows-latest`, and `pnpm run test:coverage` on Node 24. The Windows runners are
 there because the plugin targets Windows; the coverage thresholds need Node 22.8 or
 newer, which is why that job runs on one version.
 
@@ -91,6 +204,19 @@ The probes marked "yes" need Windows, WSL2, a mounted harness profile and a link
 checkout, which a hosted runner does not have. Run them on your own machine and
 paste the output into the pull request.
 
+The rows marked "no; inside the distro" (`substrate`, `watch`, `agent`, `exec`)
+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.
+
 ## Adding a test
 
 Choose the layer by what the test needs.
@@ -100,44 +226,70 @@ Choose the layer by what the test needs.
 | Unit test | `test/*.test.mjs` | pure logic: path translation, listing, shell argument building, terminal helpers |
 | Probe | `test/probe/` | behaviour that needs a real distro, a real profile, or bubblewrap |
 
-Unit tests run under `node --test`. A test that imports only this repository goes in
-both the `test:unit` and the `test:coverage` lists in `package.json`, which name
-their files explicitly. A test that needs a DSH peer — `test/sandbox.test.mjs`
-imports `lib/sandbox.js`, which imports `@deepseek-ai/dsh-sandbox` — goes in
-`test:unit` only and must skip itself when the peer is missing, because CI installs
-nothing: try the import, print a `SKIP` line, exit 0.
-
-Probes are shell scripts that mount a throwaway profile, plus the small plugin
-files they load. Those plugin files are the `*-probe.mjs` and `*-probe.yml` files
-in the same directory. The setup steps for the throwaway profile are in the header
-of `test/probe/run.sh`. `terminal.sh` and `sandbox-shell.sh` reuse it.
+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).
+
+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 —
+`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.
+
+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`
+contract, which leaves only the one-line peer binding in `lib/sandbox.js`. That
+line is covered by the harness probes, which boot the plugin and so reach
+`WslSandbox` through `lib/index.js` — not by `probe:sandbox`, which reads only
+the argument builder out of `lib/bwrap.js`. A test that cannot run everywhere
+must skip itself — print a `SKIP` line and exit 0 — the way that file does on
+`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`, `missing-wsl.sh`,
+`sandbox-off.sh`) boot a throwaway profile whose setup steps are in the header of
+`test/probe/run.sh`; the five 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.
 
 Keep probe output idempotent. Several probes delete their scratch files at the
 start, because a leftover file from an earlier run changes the result.
 
 ## What has been verified
 
-`npm test` covers the pure modules and runs a `--check` pass over every shipped
-module. It cannot import the service modules, because those need DSH peer packages
-that a bare checkout does not have. Only booting the harness closes that gap, which
-is why the probes exist; the archived record's §15.4 documents the five rounds of
-misdiagnosis the gap once caused.
+`pnpm test` runs the whole unit suite once the one `pnpm install` above has
+fetched the pinned packages: the files that import them statically exercise the
+services through the loader and their declared types, and `test:syntax` keeps a
+`node --check` pass over every shipped module. What no test on a Linux leg can
+reach is the Windows-plus-WSL2 topology itself: a real `wsl.exe`, a real distro,
+a real harness boot. That is the gap the probes close; the archived record's
+§15.4 documents the five rounds of misdiagnosis it once caused.
 
 `test/probe/sandbox.sh` needs no harness: it uses the same arguments
 `lib/sandbox.js` builds and asserts what bubblewrap does and does not confine,
 recording the interop escape as `INFO` because a Linux sandbox cannot govern a
-Windows process. The other probes boot a throwaway profile bound to the distro:
+Windows process. The harness probes boot a throwaway profile bound to the distro:
 
 - the filesystem probe asserts the write path and the write checks — a write outside
   the policy root and a write in `read-only` mode both return `FS_SANDBOX_DENIED`,
-  while `danger-full-access` is not checked;
+  while `danger-full-access` is the approved escalation and its write is asserted
+  to land;
 - the shell probe drives all three modes through `ctx.shell` and checks the refusal
   classification the tool layer returns;
 - the terminal probe asserts the distro, the starting directory, and the `DSH_*`
   variables forwarded through `WSLENV`.
 
-The setup steps for the throwaway profile are in the header of `test/probe/run.sh`;
-`terminal.sh` and `sandbox-shell.sh` reuse it.
+The setup steps for that throwaway profile are in the header of
+`test/probe/run.sh`; the harness probes share the one profile it creates.
 
 On Windows 11 + WSL2 (Ubuntu 26.04) the following has been verified:
 
@@ -152,11 +304,12 @@ 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: 57 unit assertions on a bare checkout, plus 5 in `test/sandbox.test.mjs` which
-need the `dsh-sandbox` peer and skip themselves without it; 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.
+Counts: 28 unit test files under `test/` — 27 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.
 
 ## Commit and pull request conventions
 

package/README.md

@@ -26,25 +26,31 @@ dsh --profile wsl                                  # 4. run
 
 Step 3 should print a layer named `# == dsh-plugin-wsl-env`, and `- id: terminal-controller` should now carry `shell: { path: wsl.exe, name: WSL }`. The package is a DSH bundle, so step 2 applies [`cordis.patch.yml`](cordis.patch.yml) as a configuration layer; nothing is merged by hand.
 
-Then open a folder under `\\wsl.localhost\<distro>\...` in the GUI. The picker lists every installed distro at its root level, and **New terminal** opens a shell in the distro.
+**Before the first command, give the distro bubblewrap.** Every command runs confined by [bubblewrap](#sandbox), which most distros do not preinstall, and without it every command fails closed — by design, never unconfined:
+
+```powershell
+wsl.exe -d <distro> -u root -- apt-get install -y bubblewrap    # Debian/Ubuntu
+```
 
-You also need **bubblewrap inside the distro**: run `npm run bootstrap -- <distro> --install` (drop `--install` for a read-only check), or paste `wsl.exe -d <distro> -u root -- apt-get install -y bubblewrap`. Without it every command fails closed, see [Sandbox](#sandbox).
+From a checkout of this plugin, `pnpm run bootstrap -- <distro>` checks all four tools the plugin uses (bubblewrap, ripgrep, git, inotify-tools) and prints the install command for the distro's own package family; add `--install` to run it. A skipped step announces itself: when a distro session opens, the plugin probes bubblewrap and warns with the exact remedy — the first command never has to be the discovery moment.
+
+Then open a folder under `\\wsl.localhost\<distro>\...` in the GUI. The picker lists every installed distro at its root level, and **New terminal** opens a shell in the distro.
 
 Uninstall: `dsh plugin --profile wsl remove dsh-plugin-wsl-env`. Upgrade: run the same `add` command again.
 
-> **Changed anything under `lib/`? Restart the app.** A running process caches ES modules and keeps the old code otherwise.
+> **Changed anything under `lib/`? Sync the mirror, then restart the app.** The app loads the Windows-side runtime mirror, so run `pnpm run sync:windows` first — a restart without the sync just reloads the old code; a running process also caches ES modules. See [Development](#development).
 
 ## Using it
 
 Open `\\wsl.localhost\ubuntu\home\you\project` as the workspace, then ask the model "what kernel am I on, and what is in `/etc/os-release`?". It runs `uname -r` and reads that file inside the distro. Nothing goes through `/mnt/c`, and no files are copied.
 
 - **A distro folder gets the distro environment automatically.** The `wsl` preset is bound while the session is created, so the first tool call is already correct.
-- **Commands** run as `wsl.exe -d <distro> --cd <linux dir> --exec <your login shell> -lc <command>`, so your `PATH`, `nvm`, `cargo`, `pyenv` and rc files apply. The shell is not hardcoded to bash.
+- **Commands** run inside the distro in your login shell, so your `PATH`, `nvm`, `cargo`, `pyenv` and rc files apply; the shell is not hardcoded to bash. The default is the resident in-distro agent — one long-lived process per distro; while it is out (or with `agent: false`) the same command falls back to one `wsl.exe -d <distro> --cd <linux dir> --exec <your login shell> -lc <command>` process.
 - **Files are the distro's real files.** `/home/you/x` and `\\wsl.localhost\ubuntu\home\you\x` are the same file, and `/mnt/c/...` reaches the Windows disk.
 - **The terminal** (right sidebar, then *New terminal*) opens a shell inside the distro, in the session's folder.
 - **Port visibility.** The model sees which ports have a listener inside the distro (`DSH_WSL_PORTS`, refreshed about every 10 s), so it can hand you the exact URL of a dev server it just started; WSL2's localhost forwarding makes it reachable from Windows directly.
-- **The model sees its shell environment.** The plugin registers `DSH_WSL_DISTRO`, `DSH_WSL_SHELL` and `DSH_WSL_HOME` in the managed `DSH_*` namespace.
-- **Permissions work as on a Linux host.** The Permissions selector switches between `read-only`, `workspace-write` (the default) and `danger-full-access`. A refused command or write comes back with an offer to run it with wider permissions; if you approve, that one call runs without the sandbox.
+- **The model sees its shell environment.** The plugin registers `DSH_WSL_DISTRO`, `DSH_WSL_SHELL`, `DSH_WSL_HOME` and the port snapshot `DSH_WSL_PORTS` in the managed `DSH_*` namespace.
+- **Permissions work as on a Linux host.** The Permissions selector switches between `read-only`, `workspace-write` (the default) and `danger-full-access`. A refused command or write comes back with an offer to retry it once with the narrowest wider mode that suffices; if you approve, that one call runs in the approved mode — from `read-only` that is usually `workspace-write`, still inside the sandbox, and only an escalation to `danger-full-access` runs without one.
 
 ## Configure
 
@@ -61,19 +67,19 @@ Override a row by id in `$DSH_HOME/profiles/<name>/cordis.patch.yml`. The keys w
 | `directory-picker-wsl` | `includeHostHome` | `true` | also list the Windows home directory |
 | `subprocess-wsl` | `distro` | `''` | which distro the GUI terminal opens in |
 
+`wsl-shell` and `wsl-fs` are the two rows a by-id patch **cannot** reach: they are plugins of the `wsl` agent preset, nested inside the `preset-wsl` row's `config.plugins`, so `- id: wsl-shell` in your layer changes nothing — the loader only warns `patch: entry "wsl-shell" not found` and the shipped value stays in force. Override the `preset-wsl` row as a whole instead; [docs/CONFIGURATION.md](docs/CONFIGURATION.md#overriding-the-rows-inside-preset-wsl) has the recipe.
+
 [`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
 
 - **Git credential sharing**: let git inside the distro use the Windows-side Git
   Credential Manager — `git config --global credential.helper "/mnt/c/Program\ Files/Git/mingw64/bin/git-credential-manager.exe"`
-  (adjust the path to your Windows Git install; WSL2's localhost forwarding is
-  platform behaviour, so ports a dev server listens on inside the distro are
-  reachable from Windows directly).
+  (adjust the path to your Windows Git install).
 - **Paths and performance**: the model sees and operates on Linux paths
   (`/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
+  distro filesystem. `pnpm run bootstrap -- <distro>` also reports whether
   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
@@ -90,17 +96,20 @@ composition (app level, one per process)
 │                          WSL-folder session     → the distro shell, in the session's Linux directory
 │                          Windows-folder session → powershell.exe, in the session's Windows directory
 ├─ directory-picker-wsl  installed distros listed beside the Windows home
+├─ workspace-files-wsl   the GUI file tree and previews of a distro workspace, served from inside it
+├─ fs-routing            the root filesystem, routed by coordinate
+│                          distro UNC → the resident agent; a drive path → the host backend
 ├─ wsl-shell-env         the DSH_WSL_DISTRO / _SHELL / _HOME / _PORTS facts the model sees
 └─ auto-preset           binds the wsl preset when a session opens a distro folder
 
 preset-wsl (the wsl agent preset; its services run in isolate realms)
 ├─ wsl-shell   ctx.shell — wsl.exe --exec <login shell>, confined by bubblewrap inside the distro
-└─ wsl-fs      ctx.fs    — real distro files; agent substrate on ext4, or the 9p share
+└─ wsl-fs      ctx.fs    — real distro files on the resident agent substrate (ext4)
 ```
 
-**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.
+**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. `workspace-files-wsl` and `fs-routing` are composition-level for the mirror-image reason: the GUI file tree and the root `ctx.fs` are session-less, so they cannot be served from a preset. They replace the shipped `workspace-files` and root `fs-sandbox` rows outright; [docs/root-fs-routing.md](docs/root-fs-routing.md) is the design of the root-plane routing.
 
-**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.
+**Commands and files.** By default a command runs over the resident in-distro agent — one long-lived process per distro, which carries the cwd as part of the request instead of a per-command `--cd`. What it runs is the same `<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; while the agent is out, or with `agent: false`, the command falls back to one `wsl.exe -d <distro> --cd <linux dir> --exec <login shell> -lc <cmd>` process. 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
 
@@ -112,9 +121,9 @@ Commands are confined by `bubblewrap` inside the distro, and file writes are che
 | `workspace-write` | the above, plus the session workspace is writable and `/tmp` is a temporary mount |
 | `danger-full-access` | no sandbox; used for an approved wider-permission request |
 
-**`bubblewrap` is required, and it fails closed.** Without it every confined command reports `SANDBOX_UNAVAILABLE` instead of running unconfined. Set `sandbox: false` on either provider to opt out; the tool layer then tells the model these operations have no sandbox.
+**`bubblewrap` is required, and it fails closed.** Without it every confined command reports `SANDBOX_UNAVAILABLE` instead of running unconfined. To opt out, set `sandbox: false` on the row that owns the operation — `wsl-shell` for commands, `wsl-fs` for the write fence, and the top-level `fs-routing` row for its own copy. Note that the two preset rows are reached through `preset-wsl`, not by id (see [Configure](#configure)). The tool layer then tells the model these operations have no sandbox.
 
-**The reported enforcement is `partial`, not `full`.** A process inside the distro can still run a Windows program through WSL interop, for example `/mnt/c/.../*.exe`, and bubblewrap does not govern it. `npm run probe:sandbox` demonstrates the boundary on your machine.
+**The reported enforcement is `partial`, not `full`.** A process inside the distro can still run a Windows program through WSL interop, for example `/mnt/c/.../*.exe`, and bubblewrap does not govern it. `pnpm run probe:sandbox` demonstrates the boundary on your machine. `maskWindowsDrive: true` on the `wsl-shell`, `wsl-fs` and `fs-routing` rows narrows it — 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 — but does not close it: a command can still write an executable into the workspace and run it, so enforcement stays `partial`. The complete closure is distro-level, `[interop] enabled=false` in `wsl.conf` (see [docs/CONFIGURATION.md](docs/CONFIGURATION.md)).
 
 See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md#sandbox) for the design, and [docs/LIMITATIONS.md](docs/LIMITATIONS.md) for everything the plugin does not do.
 
@@ -122,39 +131,45 @@ See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md#sandbox) for the design, and [do
 
 | Symptom | Cause | Fix |
 |---|---|---|
-| every command reports `SANDBOX_UNAVAILABLE` | `bubblewrap` is not installed in the distro | run `npm run bootstrap -- <distro> --install`, or set `sandbox: false` on both providers |
+| every command reports `SANDBOX_UNAVAILABLE` | `bubblewrap` is missing from the distro, or present but unusable — the error text distinguishes the two and carries the matching remedy | follow the remedy in the error, or set `sandbox: false` on `wsl-shell` (commands) and `wsl-fs` (writes) — see [Configure](#configure) for how to reach those rows |
 | a command or write is refused outside the session folder | expected behaviour of `workspace-write` | accept the wider-permission offer, or open a session on the folder you need |
 | writes are refused even inside the workspace | the session is in `read-only` mode | switch the Permissions selector |
-| `dsh plugin add` warns that no layer was activated | the dependency was already installed, so `add` had nothing to record | run `dsh plugin --profile wsl remove dsh-plugin-wsl-env`, then add it again |
+| `dsh plugin add` prints no confirmation that a layer was added | the dependency is already installed and the bundle list is unchanged, so `add` reconciles to the same manifest without reporting anything — that is the success path, not a failure | nothing to do; the layer is already in place, and `dsh --profile wsl --dump-config` still shows `# == dsh-plugin-wsl-env` |
 | 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 |
+| changes to `lib/` have no effect | the app loads the Windows-side runtime mirror, and a running process also caches ES modules | run `pnpm run sync:windows` to bring the mirror up to date, then 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 | 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 |
+| `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 `pnpm 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
 
 ```bash
-npm test                     # style and packaging checks, syntax check, unit tests
-npm run test:coverage        # the unit tests with coverage thresholds (Node 22.8+)
-npm run probe:sandbox        # measure inside the distro what bubblewrap does and does not confine
-npm run probe                # filesystem probe against a real distro (Windows + WSL only)
-npm run probe:sandbox-shell  # boot a real harness and drive the confined executor
-npm run probe:terminal       # open a PTY through the terminal provider
-npm run probe:substrate      # drive the agent filesystem substrate over a real wsl.exe transport (from inside the distro)
-npm run probe:watch          # arm the in-distro watcher over a real directory (from inside the distro)
-npm run probe:agent          # the resident-vs-one-shot fallback parity legs (from inside the distro)
-npm run probe:exec           # the agent-backed execution handle: timeout, kill, cwd failure (from inside the distro)
-npm run probe:missing-wsl    # boot a profile whose wslPath cannot start (Windows + WSL only)
-npm run probe:picker         # list the picker's root level, refusals and its cap (Windows + WSL only)
-npm run probe:mode           # which POSIX-mode facts survive the share (Windows node only)
-npm run probe:sandbox-off    # prove sandbox: false unconfines both providers (Windows + WSL only)
+pnpm run build                # compile src/ into lib/ (the artifact is committed; rebuild after editing src/)
+pnpm test                     # style checks, syntax pass, build consistency, type check, and unit tests
+pnpm run sync:windows         # mirror the checkout onto the Windows-side copy the app loads (after any lib/ change, then restart the app)
+pnpm run test:coverage        # the unit tests with coverage thresholds (Node 22.8+)
+pnpm run diagnose             # read-only diagnostic report for a bug issue: versions, tools, bwrap probe
+pnpm run bootstrap -- <distro> # check the four distro tools; add --install to install what is missing
+pnpm run probe:sandbox        # measure inside the distro what bubblewrap does and does not confine
+pnpm run probe                # filesystem probe against a real distro (Windows + WSL only)
+pnpm run probe:sandbox-shell  # boot a real harness and drive the confined executor
+pnpm run probe:terminal       # open a PTY through the terminal provider
+pnpm run probe:substrate      # drive the agent filesystem substrate over a real wsl.exe transport (from inside the distro)
+pnpm run probe:watch          # arm the in-distro watcher over a real directory (from inside the distro)
+pnpm run probe:agent          # the resident-vs-one-shot fallback parity legs (from inside the distro)
+pnpm run probe:exec           # the agent-backed execution handle: timeout, kill, cwd failure (from inside the distro)
+pnpm run probe:missing-wsl    # boot a profile whose wslPath cannot start (Windows + WSL only)
+pnpm run probe:picker         # list the picker's root level, refusals and its cap (Windows + WSL only)
+pnpm run probe:mode           # which POSIX-mode facts survive the share (needs a Windows node and an installed harness; opens no profile)
+pnpm run probe:sandbox-off    # prove sandbox: false unconfines both providers (Windows + WSL only)
 ```
 
-There is nothing to install first: the package has no dependencies, and every module under test imports only Node builtins. CI runs `npm test` on Node 20, 22 and 24, on Linux and Windows, and `npm run test:coverage` on Node 24.
+The app loads the Windows-side runtime mirror, not the repository checkout: after changing anything under `lib/`, run `pnpm run sync:windows` before restarting the app — otherwise the restart just reloads the old code. `pnpm run build` regenerates `lib/` from `src/`; the artifact is committed, and the build-freshness check inside `pnpm test` verifies it.
+
+One `pnpm install` reproduces the pinned development dependencies before the first run: the tests import pinned `@deepseek-ai/*` packages (the composition and boot tests exercise the loader's real patch algorithm), while the runtime package itself still ships zero dependencies. pnpm is resolved through the `packageManager` field, so any corepack-enabled Node works. CI runs `pnpm test` on Node 22 and 24, on Linux and Windows, and `pnpm run test:coverage` on Node 24; `engines` matches the harness host's own floor (`^22.19.0 || >=24.0.0`).
 
-[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) has the file layout, the mounting, and the sandbox design. [CONTRIBUTING.md](CONTRIBUTING.md) has the development loop, the full gate list, and what has been verified.
+[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) has the file layout, the mounting, and the sandbox design. [CONTRIBUTING.md](CONTRIBUTING.md) has the development loop, the runtime mirror, the full gate list, and what has been verified.
 
 ## Documentation
 

package/SECURITY.md

@@ -45,6 +45,21 @@ These are targets, not a contract.
 
 If a report is out of scope, we will say so and explain why.
 
+## Disclosure
+
+A confirmed vulnerability is fixed and disclosed through the ordinary release
+process, not through a separate security track.
+
+- The fix ships in the next release of the package, which is the only version the
+  Supported versions table above covers.
+- That release records the fix in [`CHANGELOG.md`](CHANGELOG.md), and the GitHub
+  Release notes are taken from that section.
+- The advisory is published on this repository's Security tab, where the private
+  report was filed, once the release that carries the fix is out.
+
+A report that is out of scope, or that we cannot confirm as a vulnerability, is
+closed without a published advisory.
+
 ## Scope
 
 In scope:
@@ -69,8 +84,9 @@ process inside the distro can still start a Windows program through WSL interop,
 for example `/mnt/c/.../*.exe`. That program runs outside the Linux sandbox.
 
 This is a documented design boundary, not a vulnerability by itself. The command
-`npm run probe:sandbox` demonstrates it on your machine, and the README states it
-in its Sandbox section.
+`npm run probe:sandbox` demonstrates it on your machine when run from inside the
+distro, where `bubblewrap` and `node` must be installed; the README states it in
+its Sandbox section.
 
 A report is still welcome if you find an escape that does not depend on interop,
 or if the plugin ever reports `full` while interop is reachable.