dsh-plugin-wsl-env 0.7.5 → 0.9.0

package/SUPPORT.md

@@ -8,7 +8,11 @@
 | Linux side | WSL2 with at least one distro |
 | DSH packages | the `0.2.0-rc.2`-era packages listed in `peerDependencies` |
 | Plugin version | the latest published version only |
-| Node | 20, 22, or 24 |
+| 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,
+not this table.
 
 Outside Windows there is nothing for the plugin to attach to. It runs `ctx.shell`
 inside the distro through `wsl.exe`. A Linux host, a macOS host, or WSL1 is not a
@@ -21,7 +25,10 @@ Open an issue in the repository:
 https://github.com/Big-Dao/dsh-plugin-wsl-env/issues
 
 Use it for bug reports and for questions about configuration. Search the open and
-the closed issues first.
+the closed issues first, and check whether the answer is already written down:
+[docs/LIMITATIONS.md](docs/LIMITATIONS.md) lists the known design boundaries, and
+the Troubleshooting table in [README.md](README.md#troubleshooting) covers the
+common failures (`SANDBOX_UNAVAILABLE`, a missing `rg`, and the rest).
 
 For a security issue, follow [SECURITY.md](SECURITY.md). Do not open a public
 issue for one.
@@ -31,8 +38,12 @@ issue for one.
 - macOS, and Linux hosts that are not WSL2.
 - Windows without WSL2.
 - A modified DSH build, or a fork of the harness packages.
-- A distro the plugin cannot recognize. Examples are a replaced `/bin/sh`, a
-  container-style root filesystem, and a missing `bwrap`.
+- A distro the plugin cannot recognize, which is what its probes report: no
+  distro from `wsl.exe -l -q`, a `$HOME` that is empty or not an absolute path,
+  or no absolute shell from the `getent passwd` / `$SHELL` probes. The detection
+  lives in `src/wsl.ts`.
+- A distro without `bwrap`. Commands there fail closed rather than run
+  unconfined.
 - The upstream `@deepseek-ai/*` packages. Report those to their own projects.
 - Third-party npm mirrors. Install from the registry the package was published to.
 
@@ -47,14 +58,19 @@ There is no long-term support branch. Fixes go to the latest version.
 
 ## What a good bug report contains
 
+The one-command path: `pnpm run diagnose` (from a checkout of the plugin, or
+`bash scripts/diagnose.sh`) collects most of the table below — Windows build,
+WSL status, distro, kernel, package family, the four tools with their versions,
+and a bwrap functional probe — as a paste-ready report. Run it first, then add
+what it cannot see:
+
 | Item | How to get it |
 |---|---|
+| The diagnose report | `pnpm run diagnose -- <distro>` (read-only; safe to paste) |
 | Plugin version | `npm ls dsh-plugin-wsl-env`, or the git tag you built from |
 | DSH version | the version of the harness you run |
-| Distro and kernel | `wsl.exe -l -v`, and `uname -r` inside the distro |
-| Windows build | `winver` |
 | The composed configuration | `dsh --profile <name> --dump-config`, in particular the `dsh-plugin-wsl-env` layer and the rows it patches |
-| Sandbox behaviour | the output of `npm run probe:sandbox`, when the sandbox is involved |
+| Sandbox behaviour, in depth | the output of `npm run probe:sandbox`, run from inside the distro (`wsl.exe -d <distro>` first) — the probe calls `bwrap` and reads `lib/bwrap.js` there, so it needs both in the distro |
 | What you expected and what happened | one paragraph each |
 | A reproduction | the exact command, or the exact sequence of clicks |
 

package/cordis.patch.yml

@@ -162,6 +162,15 @@
     - id: auto-preset
       name: 'dsh-plugin-wsl-env/auto-preset'
 
+    # Session-start sandbox preflight: when a distro session opens, run the
+    # providers' own bwrap usability probe (shared cache, so the first confined
+    # command pays nothing) and surface a missing or broken bubblewrap as a
+    # warning with the full remedy — instead of the first command's fail-closed
+    # error being the discovery moment. Advisory only: it never installs and
+    # never changes the providers' fail-closed semantics.
+    - id: wsl-preflight
+      name: 'dsh-plugin-wsl-env/preflight'
+
 - insert:
     # ═════════════════════════════════════════════════════════════════════════════
     # preset-wsl — the WSL environment, scoped to agents that select this preset.

package/docs/ARCHITECTURE.md

@@ -11,28 +11,56 @@ DSH exposes its capabilities as services. The model-facing tools (`bash`, `read`
 `write`, `edit`, `glob`, `grep`) consume those services. They never touch a
 filesystem or a shell directly.
 
-This plugin supplies WSL-backed implementations of three of them, plus three
-smaller integrations.
+This plugin supplies WSL-backed implementations of three of them, takes over two
+root-plane services, and adds three smaller integrations.
 
 ## The three service providers
 
 | Service | Class | File | What it does |
 |---|---|---|---|
-| `ctx.shell` | `WslShellExecutor` | [`lib/index.js`](../lib/index.js) | Runs each command as `wsl.exe -d <distro> --cd <linux dir> --exec <login shell> -lc <cmd>`, wrapped in a distro-side `bwrap` sandbox. |
+| `ctx.shell` | `WslShellExecutor` | [`lib/index.js`](../lib/index.js) | Runs each command in the distro's login shell over the resident in-distro agent (the default), wrapped in a distro-side `bwrap` sandbox; while the agent is out, or with `agent: false`, the same command falls back to one `wsl.exe -d <distro> --cd <linux dir> --exec <login shell> -lc <cmd>` process. |
 | `ctx.fs` | `WslFileSystem` | [`lib/index.js`](../lib/index.js) | Serves the file tools from real distro files on the resident in-distro agent, on ext4 — the former Windows-side share substrate is retired (see below). |
-| `ctx.subprocess` | `WslSubprocessRuntime` | [`lib/subprocess.js`](../lib/subprocess.js) | Opens the GUI terminal inside the distro, in the session workspace, and rewrites the file-search spawn into the distro's own rg (see below). |
+| `ctx.subprocess` | `WslSubprocessRuntime` | [`lib/subprocess.js`](../lib/subprocess.js) | Opens the GUI terminal inside the distro, in the session workspace, and rewrites the file-search and git-snapshot spawns into the distro (see below). |
 
 `WslShellExecutor` extends the shipped `LocalBashExecutor`, and `WslFileSystem`
 extends the shipped `LocalFileSystem`. Only the parts that need a distro are
 overridden.
 
+## The two root-plane takeovers
+
+Two of the shipped services are session-less — the GUI file tree and the root
+`ctx.fs` — so they cannot be served from an agent preset. The layer replaces
+their shipped rows outright, with subclasses that route by coordinate:
+
+| Service | Class | File | What it does |
+|---|---|---|---|
+| `ctx.workspaceFiles` | `WorkspaceFilesWsl` | [`lib/workspace-files-wsl.js`](../lib/workspace-files-wsl.js) | The GUI file tree and previews for a `\\wsl.localhost\<distro>` workspace, served from inside the distro over the resident agent instead of Windows-side 9P walks. Extends the shipped service: a distro UNC routes distro-side, a drive path calls `super`, and the watch stream delegates unchanged — so replacing the row is safe for Windows-folder sessions too. Replaces the shipped `workspace-files` row. |
+| `ctx.fs` (root plane) | `WslRoutingFileSystem` | [`lib/fs-routing.js`](../lib/fs-routing.js) | The root filesystem, routed by coordinate: a distro UNC identity is served by the resident agent (real watch events, ext4 reads), a drive path stays host-native. Replaces the shipped `fs-sandbox` row, whose write fence has no root-plane consumers — the model's writes ride the preset filesystems. [`root-fs-routing.md`](root-fs-routing.md) is the design. |
+
+Both routes are composition-level for the mirror-image reason the terminal is
+(see below): no session identity reaches them. Each takeover is a top-level
+`disabled:` entry targeting the shipped row plus a bare `insert:` list holding
+the replacement — because a `disabled` written *inside* an insert list is not a
+patch but a duplicate-id data row, and a nested `insert:` is never interpreted at
+all. [`cordis.patch.yml`](../cordis.patch.yml) carries the full row list, and
+`test/composition.test.mjs` runs the file through the real patch algorithm to
+keep the shape honest.
+
+One further module ships built but deliberately unwired:
+[`lib/file-reference-wsl.js`](../lib/file-reference-wsl.js), the distro-side
+traversal strategy for `@` completion. It is built and tested, but **not** wired
+into `cordis.patch.yml` — the seam it consumes is an upstream proposal
+([`upstream/rfc-wsl-workspaces.md`](upstream/rfc-wsl-workspaces.md)), and
+reaching the funnels without it would mean subclassing past module-internal
+functions.
+
 ## The three smaller integrations
 
 | Subpath | Class or name | File | What it does |
 |---|---|---|---|
 | `dsh-plugin-wsl-env/picker` | `WslDirectoryPicker` | [`lib/picker.js`](../lib/picker.js) | Adds the installed distros to the folder picker, next to the Windows home directory, and lists distro levels from inside the distro (the resident's `ls`, one-shot `wsl.exe` when it is out). |
 | `dsh-plugin-wsl-env/auto-preset` | `auto-preset` | [`lib/auto-preset.js`](../lib/auto-preset.js) | Binds the `wsl` agent preset when a new session's workspace is inside a distro. |
-| `dsh-plugin-wsl-env/shell-env` | `wsl-shell-env` | [`lib/shell-env.js`](../lib/shell-env.js) | Contributes `DSH_WSL_DISTRO`, `DSH_WSL_SHELL`, and `DSH_WSL_HOME` to the managed `DSH_*` namespace. |
+| `dsh-plugin-wsl-env/shell-env` | `wsl-shell-env` | [`lib/shell-env.js`](../lib/shell-env.js) | Contributes `DSH_WSL_DISTRO`, `DSH_WSL_SHELL`, `DSH_WSL_HOME` and `DSH_WSL_PORTS` to the managed `DSH_*` namespace. The port list is a snapshot, refreshed every `portsRefreshMs` (10000 by default), so a server started moments ago may not be listed yet. |
 
 Three modules support them and import no DSH package.
 [`lib/paths.js`](../lib/paths.js) translates paths.
@@ -50,7 +78,9 @@ The environment is per session, not per process:
 | Row | Mounted | Why there |
 |---|---|---|
 | `wsl-shell`, `wsl-fs` | inside `preset-wsl`, an agent preset with isolate realms | so one process can serve a Windows workspace and a distro workspace at the same time |
-| `subprocess-wsl` | at the app level, called the composition | because no session identity reaches the terminal controller, see below |
+| `subprocess-wsl` | at the app level, called the composition; the shipped `subprocess` row is disabled | because no session identity reaches the terminal controller, see below |
+| `workspace-files-wsl` | at the app level; the shipped `workspace-files` row is disabled | the GUI file tree is session-less, so it cannot be served from a preset |
+| `fs-routing` | at the app level; the shipped `fs-sandbox` row is disabled | the root `ctx.fs` is session-less, and its write fence has no root-plane consumers |
 | `directory-picker-wsl`, `wsl-shell-env`, `auto-preset` | at the app level | they answer questions that are not scoped to a session |
 
 The preset mount requires the isolate realms. Without them the registry rejects the
@@ -71,8 +101,15 @@ does not use it.
 
 So the layer disables the shipped `subprocess` row and inserts
 `dsh-plugin-wsl-env/subprocess` in its place at the app level. The subclass
-overrides `spawnTerminal` only. Ordinary `spawn()`, the host ripgrep search, the
-pwsh executor, and the LSP host reach the shipped implementation unchanged.
+overrides two methods: `spawnTerminal` rewrites a `wsl.exe` launch into
+`wsl.exe -d <distro> --cd <linux dir>`, and `spawn()` rewrites two kinds of
+launches into the distro — the file-search tool's packaged ripgrep (agent-first,
+with the one-shot `wsl.exe --exec` handle as the fallback when the agent is out)
+and git snapshot commands. Both spawn decisions are pure coordinate functions
+(`lib/search-route.js`, `lib/git-route.js`); every other `spawn()` — including
+the one-shot fallback's own `wsl.exe -lc <command>` (the default agent path
+carries the command over the resident instead of spawning) — reaches the shipped
+implementation untouched, as do the pwsh executor and the LSP host.
 
 The terminal's execution world follows the session (`hostSessions`, default on):
 a WSL-folder session runs the distro shell, a Windows-folder session runs
@@ -124,9 +161,11 @@ profile carrying the value is refused at boot, and no file tool crosses the
   refuses confined mutations with the bootstrap command, the same closed
   failure the command path has.
 
-Writes fence with the same host-side policy check (`checkedTarget`) the
-command path uses, and the substrate does not change what `sandboxMode`
-reports. The wire protocol the substrate speaks is documented in
+Writes fence with the same host-side policy the command path's sandbox
+describes — `WslFileSystem.checkedTarget`, over the same writable list; the
+command path itself is confined by the distro-side profile and never calls it —
+and the substrate does not change what `sandboxMode` reports. The wire protocol
+the substrate speaks is documented in
 [`agent/wsl-agent.sh`](../agent/wsl-agent.sh); the orchestration layers are
 [`lib/fsio-agent.js`](../lib/fsio-agent.js) (fsio's mechanics over the FS
 frames), [`lib/fs-substrate.js`](../lib/fs-substrate.js) (the provider-shaped
@@ -148,19 +187,26 @@ sandbox.
 
 ### What the plugin does instead
 
-The plugin builds a `bubblewrap` profile on the Windows side and passes it to
-`wsl.exe --exec`. The confinement is created inside the distro:
+The plugin builds a `bubblewrap` profile on the Windows side and hands the
+resulting argv to the distro — over the resident agent by default, or to
+`wsl.exe --exec` on the one-shot fallback. The confinement is created inside the
+distro, and the argv is the same either way:
 
 ```text
 wsl.exe -d <distro> --cd <linux dir> --exec bwrap \
   --ro-bind / / --dev /dev --unshare-pid --proc /proc --die-with-parent \
-  [--tmpfs /tmp --bind <workspace> <workspace>]  --  <shell> -lc <cmd>
+  [--tmpfs /tmp --bind <workspace> <workspace>]  [--tmpfs /mnt]  --  <shell> -lc <cmd>
 ```
 
 These are the same arguments DSH's Linux runner uses (`dsh-sandbox-local`), so the
 behaviour and the error messages match a Linux host. The function
 `bwrapProfileArgs` in [`lib/bwrap.js`](../lib/bwrap.js) builds them — the
-peer-free builder every confinement site composes from.
+peer-free builder every confinement site composes from. The trailing
+`[--tmpfs /mnt]` is the `maskWindowsDrive` option: when it is on, the Windows
+drive is shadowed by an empty tmpfs in every confined profile, so its files
+cannot be read or exfiltrated and its executables cannot be launched through
+interop. The option is off by default; [CONFIGURATION.md](CONFIGURATION.md) lists
+the row keys, and `lib/sandbox-core.js` states its honest ceiling.
 
 | Mode | What a command inside the distro can do |
 |---|---|
@@ -185,7 +231,19 @@ selector read that value.
 distro can still run a Windows program through WSL interop, for example
 `/mnt/c/.../*.exe`. Bubblewrap does not govern that process.
 
-`npm run probe:sandbox` demonstrates the boundary on your machine and records it as
+`maskWindowsDrive` is the one mitigation the profile can offer, and it is a
+narrowing rather than a closure: it takes the drive's data and its executables
+off the table, but `binfmt` interop dispatches on file *content*, so a command
+that can write the workspace can still write a PE there and have it launched as
+a Windows process. Either way the provider reports `partial` — the complete
+closure is distro-level (`[interop] enabled=false` in `wsl.conf`). The mask is
+reported on the result's sandbox fact as `windowsDrive: "masked"` (or
+`"visible"`), but that is this plugin's own extra field: the pinned harness's
+sandbox type and its model-facing notes carry `mode`, `denied`, `enforcement` and
+`runnerFailed` only, so the field reaches the result and the tests, not the
+model.
+
+`pnpm run probe:sandbox` demonstrates the boundary on your machine and records it as
 `INFO`.
 
 ### Failure mode
@@ -212,18 +270,37 @@ and `sandboxMode` returns `undefined`.
 ## Error codes
 
 The plugin raises `FsError`s with a code the tool layer maps, and `wsl.exe`'s own
-failures are named as well. A model sees the code; a reader asking what refused them
-finds it here.
+failures are named as well. Every `FsError` code the plugin itself raises appears
+below — a model sees the code, and a reader asking what refused them finds it here.
+Codes the shipped host stack raises behind a drive path pass through
+`lib/fs-routing.js` unchanged and are the peer's, not this table's; the GUI file
+tree's own wire refusals are a separate dialect, listed after the table.
 
 | Code | Raised by | Meaning | What clears it |
 |---|---|---|---|
 | `SANDBOX_UNAVAILABLE` | `WslSandbox.confine` | the requested mode cannot be enforced: no usable `bwrap` in the distro | install `bubblewrap` there (a failed probe is re-run, so no restart is needed), or set `sandbox: false` |
-| `FS_SANDBOX_DENIED` | `WslFileSystem.checkedTarget` | the file-effect policy refused the write: `read-only`, or a target outside the writable roots | a wider permission for that one call, or a session workspace that contains the target |
+| `FS_SANDBOX_DENIED` | `WslFileSystem.checkedTarget`, and `lib/fsio-agent.js` (a write the confined resident's mount table refused, classified from the kernel's `read-only file system`) | the file-effect policy refused the write: `read-only`, or a target outside the writable roots — or the kernel refused it at the resident's profile | a wider permission for that one call, or a session workspace that contains the target |
 | `FS_OUTSIDE_DISTRO` | `WslFileSystem.worldPath` | `restrictToDistro` is on and the path names **another distro**'s share — a configuration fence, not a sandbox decision | open a session in that distro, or set `restrictToDistro: false`. A wider permission does **not** lift it |
-| `FS_NOT_OBSERVED` | `WslFileSystem.assertGuard` | a guarded create (`createIfAbsent`) targeted a file that exists and had not been read first | read the file, then overwrite with the version guard or edit it |
-| `FS_STALE_VERSION` | `WslFileSystem.assertGuard` | the version the caller holds no longer matches: the file changed, or is gone | read it again and retry with the fresh version |
-| `FS_IO_ERROR` | `WslFileSystem.watch` | the watch target is not a path inside the pinned distro, so there is nothing the in-distro poll loop can observe | watch a distro path; the watch itself runs where the files live (`lib/watcher.js`) |
-| `FS_NOT_FOUND` | the host filesystem stack | the path does not exist — the ordinary answer, passed through | — |
+| `FS_NOT_OBSERVED` | `lib/fs-substrate.js` (`writeText`; the agent's `exists` conclusion, mapped in `lib/fsio-agent.js`) | a guarded create (`createIfAbsent`) targeted a file that exists and had not been read first | read the file, then overwrite with the version guard or edit it |
+| `FS_STALE_VERSION` | `lib/fs-substrate.js` (`writeText`, `editText`; the agent's `stale` conclusion, mapped in `lib/fsio-agent.js`) | the version the caller holds no longer matches: the file changed, or is gone | read it again and retry with the fresh version |
+| `FS_IO_ERROR` | the filesystem stack: `lib/fs-decisions.js` (the substrate is unavailable), `lib/fsio-agent.js` (a `perm`/`loop`/`io` reason or a malformed record), `lib/index.js` (a path that cannot be mapped, or a `SandboxUnavailableError`), and `WslFileSystem.watch` | the catch-all I/O failure — most often the resident agent is out or the distro returned an I/O error, the "agent outage fails closed" case above. A watch target outside the pinned distro is the narrow one | get the resident back (check `wsl.exe -l -v`, then restart the session); for a watch, aim it at a distro path — the watch itself runs where the files live (`lib/watcher.js`) |
+| `FS_NOT_FOUND` | `lib/fsio-agent.js` and `lib/fs-substrate.js` (the agent's `notfound`/`notdir` conclusion, an empty path, or a missing edit target), and the host filesystem stack behind a drive path | the path does not exist — the ordinary answer | — |
+| `FS_NOT_REGULAR_FILE` | `lib/fsio-agent.js`, `lib/fs-substrate.js` | the target is not a regular file where one is required: a directory, symlink or device on a read, or a non-file target on a write | point the call at a regular file |
+| `FS_NOT_DIRECTORY` | `lib/fsio-agent.js` (`listChildren`) | the target is not a directory, so there are no children to list | list a directory |
+| `FS_NOT_TEXT` | `lib/fsio-agent.js`, `lib/fsio-text.js` | the content is not UTF-8 text: a NUL sample (binary) or a decode failure | not a policy refusal — read text, or use a command for binary content |
+| `FS_TOO_LARGE` | `lib/fsio-agent.js` | the content exceeds the byte cap the caller's operation carries | read a byte range (`WslFileSystem.readByteRange`) instead of the whole file, or raise the cap |
+| `FS_ABORTED` | `lib/fsio-agent.js`, `lib/fsio-text.js` | the caller's signal was aborted before or during the operation | not a refusal — the caller cancelled; a fresh call clears it |
+| `FS_EDIT_NOT_FOUND` | `lib/fsio-text.js` (`applyLiteralEdit`) | `old_string` was empty, or matched nothing in the file | give an `old_string` the file actually contains |
+| `FS_AMBIGUOUS_EDIT` | `lib/fsio-text.js` (`applyLiteralEdit`) | `old_string` matched more than once and `replace_all` was not set | make `old_string` unique, or set `replace_all` |
+
+The GUI file tree speaks a second dialect. `WorkspaceFilesWsl` refuses through the
+typert wire's `RemoteError`s, not `FsError`s, so its codes are not in the table
+above: `workspace-file/not-found`, `workspace-file/outside-workspace`,
+`workspace-file/not-directory`, `workspace-file/not-regular-file`,
+`workspace-file/not-text`, and `workspace-file/too-large` (one code for both the
+full-file cap and the byte-window cap), plus `gateway/bad-request` for a malformed
+page request (a non-integer offset, or a limit above `maxLines`). A drive-path
+workspace calls the shipped service and gets the peer's own answers instead.
 
 Two failures come from `wsl.exe` itself rather than from a code of ours, and both used
 to be invisible:
@@ -250,7 +327,7 @@ distro checkout.
 
 The Windows copy at `default-workspace/dsh-plugin-wsl` is a runtime mirror.
 [`test/probe/sync-to-windows.sh`](../test/probe/sync-to-windows.sh) keeps it in
-step with the checkout, and `npm run sync:windows` runs that script.
+step with the checkout, and `pnpm run sync:windows` runs that script.
 
 ## Test layers
 
@@ -258,15 +335,35 @@ step with the checkout, and `npm run sync:windows` runs that script.
 |---|---|---|
 | Style and packaging checks | [`test/style.mjs`](../test/style.mjs) | no |
 | Syntax pass | [`test/syntax.mjs`](../test/syntax.mjs) | no |
+| Build consistency | [`test/build-freshness.mjs`](../test/build-freshness.mjs) | no; it re-runs the real build and byte-compares the committed `lib/`, so it also catches an orphan there |
+| Type check | `tsc --noEmit` over `test/**` and `types/*.d.ts` (`src/` is checked by the build itself) | no |
 | Unit tests | `test/*.test.mjs` | no |
 | Sandbox probe | [`test/probe/sandbox.sh`](../test/probe/sandbox.sh) | no; it applies the profile arguments directly |
 | Harness probes | [`test/probe/run.sh`](../test/probe/run.sh), `terminal.sh`, `sandbox-shell.sh`, `picker.sh`, `missing-wsl.sh`, `sandbox-off.sh` | yes: Windows, WSL2, a mounted profile, and a linked checkout |
-| Host probes | [`test/probe/mode.sh`](../test/probe/mode.sh) | Windows Node, no harness |
+| Distro probes | [`test/probe/substrate.sh`](../test/probe/substrate.sh), `watch.sh`, `agent.sh`, `exec.sh` | Windows and WSL2, but no harness boot and no profile: they run from a distro terminal with Node available, reaching `wsl.exe` through interop |
+| Host probe | [`test/probe/mode.sh`](../test/probe/mode.sh) | Windows Node, no harness |
 | Probe plugins | the `*-probe.mjs` and `*-probe.yml` files in `test/probe/` | loaded by the scripts above |
 
-The unit tests import only Node builtins, so they run on any platform. CI runs them
-on Linux and Windows, on Node 20, 22 and 24. The harness probes are a manual step,
-because a hosted runner has no WSL distro and no profile to mount.
+`pnpm test` runs the first five rows in order: `lint:style`, `test:syntax`,
+`lint:build`, `lint:types`, `test:unit`.
+[`test/probe/run-all-when-closed.sh`](../test/probe/run-all-when-closed.sh)
+waits for the app to exit and then runs the whole real-machine suite once —
+`--include-fs` prepends `run.sh`.
+
+The unit tests come in two kinds: most import only Node builtins, while
+[`test/composition.test.mjs`](../test/composition.test.mjs),
+[`test/fs.boot.test.mjs`](../test/fs.boot.test.mjs),
+[`test/fsio-agent.test.mjs`](../test/fsio-agent.test.mjs),
+[`test/provider.test.mjs`](../test/provider.test.mjs) and
+[`test/workspace-files-wsl.test.mjs`](../test/workspace-files-wsl.test.mjs) import
+pinned `@deepseek-ai/*` development dependencies (the composition and boot tests run
+the loader's real patch algorithm). One `pnpm install` reproduces that tree before
+the first run; the runtime package itself still ships zero dependencies. CI runs
+`pnpm test` on Linux and Windows, on Node 22 and 24, and `pnpm run test:coverage` on
+Node 24 only — the threshold flags need Node 22.8. Node 20 is absent on purpose:
+`engines` requires `^22.19.0 || >=24.0.0`, the harness host's own floor. The harness
+probes are a manual step, because a hosted runner has no WSL distro and no profile to
+mount.
 
 The probe scripts share [`test/probe/env.sh`](../test/probe/env.sh), which derives
 the Windows user, the distro name and the UNC spelling of the checkout from the
@@ -276,45 +373,91 @@ placeholders that the scripts substitute into generated copies.
 
 ## File layout
 
+`lib/` is generated output: every module's source is `src/<name>.ts`, and
+`pnpm run build` emits `lib/<name>.js` plus its `lib/<name>.d.ts`. Never edit
+`lib/` by hand — `lint:build` fails when the committed bytes drift from a real
+build, and it also fails on an orphan in either direction.
+
+```text
+src/<name>.ts         the sources — edit THESE; each builds to lib/<name>.{js,d.ts}
+agent/wsl-agent.sh    the resident in-distro agent (POSIX sh, coreutils only)
+cordis.patch.yml      the bundle configuration layer (dsh.bundle), commented
+examples/             one machine-local profile layer, for comparison
+locale/               the Plugins-page display metadata (title/description)
+scripts/              the build (build.mjs), the release helpers
+                      (check-release-tag.mjs, changelog-section.mjs), and the
+                      distro-side bootstrap installer (bootstrap.sh)
+test/                 unit tests, the style/build/type gates, and the probes
+docs/                 this file, the configuration and limitation references,
+                      the release checklist, and the archived designs
+```
+
+The modules, in alphabetical order:
+
 ```text
-lib/paths.js        pure conversion between the three path formats
-lib/wsl.js          wsl.exe interop primitives (no DSH imports)
-lib/listing.js      pure directory listing and breadcrumb helpers (no DSH imports)
-lib/index.js        WslShellExecutor (ctx.shell) and WslFileSystem (ctx.fs)
-lib/sandbox.js      the distro-side bwrap confinement shared by both providers
-lib/bwrap.js        the bwrap command line both confinement sites assemble
-                    (no imports, so a bare checkout can assert it)
-lib/fsio-text.js    the peer's pure text mechanics, replicated pending the
-                    upstream fsio export (see UPSTREAM-FSIO-EXPORT.md)
-lib/fsio-agent.js   fsio's mechanics over the agent's FS frames
-lib/fs-substrate.js the agent substrate's provider-shaped operations
-lib/agent.js        the resident in-distro agent's host side
-lib/agent-confined.js the confined residents' factory (one per policy)
-lib/agent-protocol.js the wire protocol codecs (pure)
-agent/wsl-agent.sh  the resident in-distro agent (POSIX sh, coreutils only)
-lib/picker.js       WslDirectoryPicker (ctx.directoryPicker)
-lib/subprocess.js   WslSubprocessRuntime (ctx.subprocess), the terminal window
-lib/auto-preset.js  per-session environment selection
-lib/shell-env.js    registers the DSH_WSL_* environment variables
-lib/{shell,fs}.js   one-line subpath entry points
-cordis.patch.yml    the bundle configuration layer (dsh.bundle), commented
-examples/           one machine-local profile layer, for comparison
-scripts/            release helpers, used by the release workflow
-test/               unit tests, the style gate, and the behaviour probes
-docs/               this file, the configuration and limitation references, the
-                    release checklist, and the archived designs
+src/agent-confined.ts        the confined residents' factory (one per policy)
+src/agent-errors.ts          the error a resident outage rejects with
+src/agent-exec.ts            the agent-backed shell execution handle
+src/agent-protocol.ts        the wire protocol codecs (pure)
+src/agent-shared.ts          the per-distro resident shared by every provider
+src/agent.ts                 the resident in-distro agent's host side
+src/auto-preset.ts           per-session environment selection
+src/bwrap.ts                 the bwrap command line every confinement site
+                             assembles (no imports, so a bare checkout can
+                             assert it)
+src/file-reference-wsl.ts    the distro-side `@`-completion traversal — built,
+                             tested, not yet wired (see above)
+src/fs.ts                    the ctx.fs subpath entry point
+src/fs-decisions.ts          the filesystem provider's policy decisions (pure,
+                             unit-testable in a bare checkout)
+src/fs-routing.ts            WslRoutingFileSystem, the root-plane ctx.fs
+src/fs-substrate.ts          the agent substrate's provider-shaped operations
+src/fsio-agent.ts            fsio's mechanics over the agent's FS frames
+src/fsio-text.ts             the peer's pure text mechanics, replicated pending
+                             the upstream fsio export (UPSTREAM-FSIO-EXPORT.md)
+src/git-route.ts             which git spawns belong inside the distro (pure)
+src/index.ts                 WslShellExecutor (ctx.shell) and WslFileSystem (ctx.fs)
+src/listing.ts               pure directory listing and breadcrumb helpers
+src/paths.ts                 pure conversion between the three path formats
+src/picker.ts                WslDirectoryPicker (ctx.directoryPicker)
+src/ports.ts                 the listening-port snapshot behind DSH_WSL_PORTS
+src/preset-choice.ts         whether a new session adopts the WSL preset (pure)
+src/probe-cache.ts           which probe verdicts may be remembered (pure)
+src/sandbox.ts               the distro-side bwrap confinement shared by both
+                             providers, bound to the peer's failure type
+src/sandbox-core.ts          the probe-and-confinement core, free of DSH peers
+src/search-exec.ts           the agent-backed execution handle for a search
+src/search-route.ts          which execution world a search spawn belongs to (pure)
+src/shell.ts                 the ctx.shell subpath entry point
+src/shell-env.ts             registers the DSH_WSL_* environment variables
+src/subprocess.ts            WslSubprocessRuntime (ctx.subprocess), the GUI
+                             terminal window
+src/terminal-activity.ts     the distro-side activity probe for idle terminal
+                             reclamation
+src/terminal-route.ts        which execution world a terminal launch belongs to (pure)
+src/watcher.ts               in-distro file watching for WslFileSystem.watch
+src/workspace-files-route.ts pure builders and parsers for the routed
+                             workspace-files service
+src/workspace-files-wsl.ts   WorkspaceFilesWsl (ctx.workspaceFiles), the GUI
+                             file tree and previews
+src/wsl.ts                   wsl.exe interop primitives (no DSH imports)
 ```
 
 `package.json` publishes a subset of this tree: the `files` list is the contract, and
-`npm run lint:style` fails if an entry stops matching tracked content.
+`pnpm run lint:style` fails if an entry stops matching tracked content.
 
 ## Where the reasoning lives
 
 - [`CHANGELOG.md`](../CHANGELOG.md) records what changed in each release. It also
   names the documentation a reader would have acted on that is no longer true.
+- [`REQUIREMENTS.zh.md`](REQUIREMENTS.zh.md) is the requirements register: every
+  documented behaviour commitment numbered, with where it is specified and what
+  verifies it, plus the open items (Chinese, maintainer-facing, not packaged).
 - [`archive/engineering-record.zh.md`](archive/engineering-record.zh.md) is the
   full engineering record, in Chinese: measured contracts, debugging rounds, and
   the conclusions as they stood then.
-- [`archive/README.md`](archive/README.md) indexes the archived material in
-  Chinese, and [`archive/README.en.md`](archive/README.en.md) is the English index.
+- [`archive/README.md`](archive/README.md) and
+  [`archive/README.en.md`](archive/README.en.md) are two English indexes of the
+  same three archived files, the second so a reader who does not read Chinese can
+  still tell what is there; the records themselves are Chinese.
 - [`README.md`](../README.md) is the only statement of current state.