dsh-plugin-wsl-env 0.8.0 → 0.9.0

package/CHANGELOG.md

@@ -7,11 +7,36 @@ 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)
-(Chinese, repository only — it is history, never a second README). Every `§`
-reference below points at that record's numbering.
+(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
+keeps the superseded designs under the section numbers they had while they
+were part of the record.
 
 ## [Unreleased]
 
+## [0.9.0] - 2026-10-06
+
+A usability round over the sandbox failure path: the failure stops being a
+wall the first command walks into, and becomes a message that arrives early
+and says how to fix it.
+
+The bwrap refusal now classifies its cause — missing versus
+present-but-failing — and prints the direct install command in the distro's
+own package family (apt/dnf/pacman/zypper) instead of a hardcoded `apt-get`
+line; every consumer composes it from one place. A new `wsl-preflight`
+service runs the same shared probe when a distro session opens and surfaces
+an unusable bwrap as a warning with the full remedy, moving the discovery
+moment ahead of the first failed command — advisory only, never installing.
+`pnpm run diagnose` collects a read-only, paste-ready diagnostic report for
+issues, and the three bare wsl-probe failures (no distro, no `$HOME`, no
+shell) now carry their next steps. The agent probe's parity legs classify
+the nested-interop service timeout (`Wsl/Service/WSAETIMEDOUT`, observed on
+WSL 3.0.1.0) as SKIP with the evidence attached, so an environment failure
+that prevents the comparison reads as what it is instead of a parity
+violation.
+
 ## [0.8.0] - 2026-10-06
 
 The toolchain's TypeScript story completes (pnpm, a checkJs gate, and 36 of 36
@@ -31,10 +56,34 @@ host's own floor (`^22.19.0 || >=24.0.0`), so the Node 20 legs are gone, and
 the per-target lock test drops its unused `withResolvers` gate, a Node 22+ API
 that hung those legs on every push.
 
+The unit suite also takes on the integration layer. `test/provider.test.mjs`
+boots the REAL `WslShellExecutor` and `WslFileSystem` with substitutes only at
+the seams that would reach `wsl.exe` — the agent, the substrate, the
+confinement — so the guard chain, the mutation routing, the agent execution
+path with its result decoration, the one-shot fallback and the runner-failure
+remap are measured: `lib/index.js` goes from 60% lines / 9% functions covered
+to 97%/90% when it joins, and measures 97.49% lines / 95.16% functions in the
+released tree. The coverage gate's branch threshold moves with it, 85 to 84 —
+the newly measured layer's uncovered tail is the distro-resolution branches
+(`defaultDistro`'s no-distro throw, `linuxHomePath`'s refusals, the watcher's
+real spawn internals) that need a live `wsl.exe`, and RELEASING.md records
+the bar for raising it again: cover that tail on the Windows CI legs, or move
+the coverage job to `windows-latest`. And the probes join CI: a
+`workflow_dispatch` job — named for the self-hosted Windows runner, though it
+carries the hosted `windows-latest` label — runs five of them: `sandbox`
+unconditionally, since it needs only bubblewrap in the default distro, then
+`mode`, `terminal`, `picker` and `missing-wsl` where the harness app is
+present. The `sandbox` leg fails, not skips, where bubblewrap is absent, so a
+dispatch to a hosted runner is no green no-op. Separately,
+`test/probe/run-all-when-closed.sh`'s suite gains the four probes it was
+missing — `agent`, `watch`, `substrate`, `exec`.
+
 One more theme: the whole repository comes under a TypeScript check gate.
 `tsc --noEmit` under `strict`/`checkJs` now runs as part of `pnpm test` over
-`lib/**`, `test/**` and the probe scripts, with the types taken from the peer
-packages' own declarations and the service augmentations loaded through
+`lib/**`, `test/**` and the probe scripts — a scope that narrows to what is
+NOT generated once the migration completes, `lib/**` leaving the gate for the
+build program below — with the types taken from the peer packages' own
+declarations and the service augmentations loaded through
 `types/dsh-services.d.ts`. The gate's first pass surfaced the seam work this
 package already carries: the private `spawnSpec` the WSL spawn directory needs
 (`docs/UPSTREAM-SPAWN-SEAM.md` bridges it) and a synchronous-contract violation
@@ -90,7 +139,9 @@ keeps those names, so nothing downstream changes except that they now come
 from a checked source. CONTRIBUTING records the per-module checklist this
 settled into: write `src/<name>.ts`, add the generated JavaScript to the two
 `exclude` lists, build, and let the suite verify the artifact is
-behaviourally identical.
+behaviourally identical — the `exclude` step lasts only while the tree is
+mixed; the finished checklist ends at write, build and test, with no list to
+maintain.
 
 Three leaf modules then follow in one pass — `agent-errors` (the two error
 classes the executor switches on), `probe-cache` (the verdict policy that
@@ -221,7 +272,7 @@ The transitional scaffolding then retires, nothing left for it to do:
 declaration-only second pass (`tsconfig.dts.json`) existed to give the
 hand-written JavaScript its `.d.ts`. `pnpm run build` is one `tsc` pass
 emitting JavaScript and declarations straight into `lib/`, pruning
-declarations no source owns; the `checkJs` gate drops its 36-entry exclude
+declarations no source owns; the `checkJs` gate drops its 35-entry exclude
 list and states what is NOT generated — `test/**` and the ambient service
 types, with `src/` checked by the build program (`noEmitOnError`); and
 `lint:build` enforces the closed corpus (every `lib/*.js` has its
@@ -995,6 +1046,17 @@ overwrite guard that stopped at the host.
   app's own runtime, both entries import; `test/syntax.mjs` now checks every
   `z.<member>` in `lib/` against the pinned peer's surface, which fails on
   `z.enum` and passes on `z.union`.
+
+## [0.2.0] - 2026-10-03
+
+One theme: the Remote-WSL parity plan (`docs/PARITY.md`) lands, Phases 0–7 —
+a resident in-distro agent plus the shell-execution, watch, publication,
+ports, terminal-routing and bootstrap work that migrates the seams onto it.
+The release closes with the two agent-path breaks that took down every GUI
+shell call, both surfacing only through the GUI's wire protocol.
+
+### Fixed
+
 - **`truncated` missing from the agent path's output streams** — the bash tool's
   canonical result copies the field unconditionally (`canonicalBashResult`), so an
   `undefined` failed the wire's lossless-JSON snapshot and EVERY shell tool call
@@ -1077,9 +1139,6 @@ overwrite guard that stopped at the host.
   Probed end-to-end against a real distro: `test/probe/agent.sh` (8 checks, including
   binary-safe payloads, an in-distro timeout kill, and a 2 MB single-line response).
   Unit tests cover the codecs and the lifecycle state machine with a fake transport.
-
-### Added
-
 - `docs/PARITY.md`: the plan to reach VS Code Remote-WSL-grade experience — a resident
   in-distro agent as the core, with the `fs` and `shell` seams migrated onto it and the
   current 9p/one-shot paths kept as the documented fallback — plus the Phase-0 contract
@@ -1621,9 +1680,9 @@ freshly created files.
 - Three peer declarations this plugin neither imports nor injects:
   `@deepseek-ai/dsh-sandbox`, `@deepseek-ai/dsh-shell` and
   `@deepseek-ai/dsh-tools`. They were required by the abandoned tool-renaming
-  designs (archive §15/§18), which could only stub the sandbox symbols locally
-  (archive §15.5). The remaining set is checkable in one command —
-  `grep -rho 'from "@deepseek-ai/[^"]*"' lib/ | sort -u` — plus
+  designs (design-history §15/§18), which could only stub the sandbox symbols
+  locally (design-history §15.5). The remaining set is checkable in one
+  command — `grep -rho 'from "@deepseek-ai/[^"]*"' lib/ | sort -u` — plus
   `@deepseek-ai/dsh-subprocess` (the service `static inject` requires) and
   `@deepseek-ai/cordis`, which every DSH plugin declares.
   (`@deepseek-ai/dsh-sandbox` came back in this same release: the distro-side

package/CONTRIBUTING.md

@@ -14,14 +14,22 @@ the conventions this repository uses.
 
 ## Toolchain
 
-The runtime package ships an empty `dependencies` object on purpose: it is
+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 0.7.x tests import
-pinned `@deepseek-ai/*` packages — the composition and boot tests run the
-loader's real patch algorithm — so a fresh checkout needs one `pnpm install`
-before the gates pass.
+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
@@ -40,24 +48,24 @@ Exactly three dependencies run install scripts (`@deepseek-ai/dsh-subprocess-loc
 
 ## The type gate
 
-`lint:types` runs `tsc --noEmit` under `strict` with `checkJs`: the JavaScript
-in `lib/` is fully type-checked, 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 gate's scope is what is NOT generated: `test/**` (the probe scripts
-included) and the ambient service types the build shares. 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.
+`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:
 
@@ -69,9 +77,12 @@ Three patterns keep the check honest:
   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
-  `docs/UPSTREAM-*.md`. It is a published finding with a tracking doc, not a
-  silencer.
+  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
 
@@ -119,15 +130,25 @@ Rules that keep this honest:
 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
 
@@ -151,26 +172,28 @@ terminal if you would rather not see the prompt.
 
 | Command | Covers | Needs a harness |
 |---|---|---|
-| `pnpm test` | style checks, syntax pass, type check, and unit tests | no |
+| `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:types` | the TypeScript check over `lib/` (`tsc --noEmit`) | 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 | yes; inside the distro |
-| `pnpm run probe:watch` | the in-distro watcher over a real directory | yes; inside the distro |
-| `pnpm run probe:agent` | the resident-vs-one-shot fallback parity legs | yes; inside the distro |
-| `pnpm run probe:exec` | the agent-backed execution handle: timeout, kill, cwd failure | yes; inside the distro |
+| `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: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.
+`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
@@ -181,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.
@@ -190,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
 
-`pnpm 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:
 
@@ -242,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 `pnpm 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,15 +67,15 @@ 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
@@ -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. `pnpm 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,12 +131,12 @@ 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 `pnpm 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 `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 |
@@ -136,8 +145,12 @@ See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md#sandbox) for the design, and [do
 ## Development
 
 ```bash
-pnpm test                     # style and packaging checks, syntax check, unit tests
+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
@@ -148,13 +161,15 @@ pnpm run probe:agent          # the resident-vs-one-shot fallback parity legs (f
 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 (Windows node 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)
 ```
 
-One `pnpm install` reproduces the pinned development dependencies before the first run: the 0.7.x 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`).
+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