dsh-plugin-wsl-env 0.12.0 → 0.13.1

package/docs/CONFIGURATION.md

@@ -22,35 +22,35 @@ has its own table at the end of this page.
 
 | Row | Key | Default | Meaning |
 |---|---|---|---|
-| `wsl-shell` | `distro` | `''` *(shipped)* | distro name; empty means WSL's default distro |
+| `wsl-shell` | `distro` | `''` *(shipped)* | distro mode: empty/`auto` follows the request workdir, `default` forces WSL's default, and a name pins every command |
 | | `shell` | `''` | pin a shell inside the distro; empty means the user's login shell |
 | | `loginShell` | `true` *(shipped)* | use `<shell> -lc`, which sources your profile, instead of a bare `-c`. Applies only to the POSIX family; a non-POSIX shell (fish, csh) still gets a bare `-c` |
 | | `agent` | `true` | run commands over the resident in-distro agent (one long-lived process; in-distro timeout); the one-shot `wsl.exe` path is fallen back to only when the agent is out of service. Anything else — a cwd refusal, a sandbox refusal — is the command's own verdict and is raised, not retried on the other path |
-| | `sessionSandbox` | `true` *(shipped)* | run this session's commands in one persistent systemd user scope (ADR 0001): a background dev server survives the command that started it, `/tmp` is the distro's real `/tmp` under `workspace-write`, and `ps` sees the session. The executor holds the runtime for the session and stops the scope from the preset's disposer, which reaps the cgroup. Requires `agent: true`, systemd as PID 1, a reachable user manager and `Linger` (`loginctl enable-linger <user>`); the preflight refuses with the remedy when systemd, the user manager, `systemd-run` or `Linger` is missing (a success is cached; a failure is re-probed, so following the remedy needs no app restart). On in the shipped preset; set `false` for the per-command shape |
+| | `sessionSandbox` | `true` *(shipped)* | `true`, `false`, or `auto`. With `true`, run this session's commands in one persistent systemd user scope (ADR 0001): a background dev server survives the command that started it, `/tmp` is the distro's real `/tmp` under `workspace-write`, and `ps` sees the session. The executor holds the runtime for the session and stops the scope from the preset's disposer, which reaps the cgroup. Requires `agent: true`, systemd as PID 1, a reachable user manager and `Linger` (`loginctl enable-linger <user>`); the preflight refuses with the remedy when systemd, the user manager, `systemd-run` or `Linger` is missing (a success is cached; a failure is re-probed, so following the remedy needs no app restart). `auto` uses the scope when those prerequisites answer, and otherwise falls back to the per-command `bwrap` profile — still confined, never unconfined — reporting `sessionScope: "per-command"` in the result (`"session"` when the scope ran); a failed `auto` verdict is re-probed at most once a minute. `false` is the per-command shape. On in the shipped preset |
 | | `agentBackend` | `auto` | the session runtime's in-distro agent. `auto` uses the native agent when a verified source is available — the packaged per-arch static-musl binary at `agent/native/linux-<arch>/dsh-wsl-agent` (x86_64 and aarch64; runs on glibc and musl distros), or the `DSH_WSL_AGENT_NATIVE` development override — and otherwise the shipped shell agent; `native` fails the first command when it cannot prepare instead of silently falling back; `shell` forces the shell agent. Confined writes share the runtime, so they follow the same selection. The native backend is the default (static musl x86_64/aarch64); the shell agent is the fallback, and `native` refuses instead of falling back. This key covers the session runtime (commands and confined writes) and, since A7, the shared read agent (unconfined reads), which also follows this selection with the shell fallback |
 | | `sandbox` | `true` | confine commands with `bubblewrap`; `false` disables the sandbox. Needs a usable `bwrap` inside the distro and fails closed without one (`SANDBOX_UNAVAILABLE`, never an unconfined run) — see [Turning the sandbox off](#turning-the-sandbox-off) |
 | | `maskWindowsDrive` | `false` | shadow `/mnt` with an empty tmpfs in every confined profile: the Windows drive's files cannot be read or exfiltrated and its executables cannot be launched through interop — the hole that lets a "sandboxed" command reach your full Windows token. A narrowing, not a closure (a command can still write an executable into the workspace and run it — binfmt dispatches on content, not location), so enforcement stays `partial` and the result's sandbox fact reports `windowsDrive: "masked"`. The complete closure is distro-level: `[interop] enabled=false` in `wsl.conf` |
 | | `cwd` | `''` | default working directory; empty means the distro user's home |
 | | `timeoutMs` / `maxTimeoutMs` | `120000` / `600000` *(shipped)* | per-call time limit, and the ceiling a call may ask for |
-| `wsl-fs` | `distro` | `''` *(shipped)* | as above |
-| | `restrictToDistro` | `true` *(shipped)* | refuse a path in **another distro**'s share. `/mnt/c` is a directory *inside* the pinned distro, so it is not affected. The refusal carries `FS_OUTSIDE_DISTRO`; that is not a sandbox decision, so the file tools do not offer a wider permission for it. Set `false` to allow another distro's share |
+| `wsl-fs` | `distro` | `''` *(shipped)* | distro mode: empty/`auto` follows each target path, `default` forces WSL's default, and a name pins the filesystem |
+| | `restrictToDistro` | `true` *(shipped)* | under a fixed `distro` (`default` or a name), refuse a path in **another distro**'s share (`FS_OUTSIDE_DISTRO`). Under `auto`, a UNC target is served by its own distro, so the fence has nothing foreign to refuse. `/mnt/c` is a directory *inside* the selected distro and is not affected |
 | | `sandbox` | `true` | check `writeText` and `editText` against the policy. Needs a usable `bwrap` in the distro too, and fails closed the same way: a distro without one refuses confined mutations (`FS_IO_ERROR`, with the install guidance) rather than downgrading them |
 | | `maskWindowsDrive` | `false` | as on `wsl-shell`: confined fs mutations publish through a resident whose profile shadows `/mnt` (same honest limits) |
-| | `sessionSandbox` | `true` *(shipped)* | run confined mutations in the same session runtime the shell uses for the same `(distro, workspace, policy)` — one agent, one real `/tmp`, one workspace mount view; requires the same systemd/linger setup and the preflight refuses with the remedy. Set `false` for the per-policy confined resident. The app-level `fs-routing` backend is not session-owned and keeps this off |
+| | `sessionSandbox` | `true` *(shipped)* | `true`, `false`, or `auto`. With `true`, run confined mutations in the same session runtime the shell uses for the same `(distro, workspace, policy)` — one agent, one real `/tmp`, one workspace mount view; requires the same systemd/linger setup and the preflight refuses with the remedy. `auto` uses the runtime when the prerequisites answer and otherwise falls back to the per-policy confined resident (still kernel-confined). Set `false` for the per-policy confined resident. The app-level `fs-routing` backend is not session-owned and keeps this off |
 | | `substrate` | `agent` *(shipped)* | which I/O substrate serves the file tools. Only the resident in-distro agent (`lib/fs-substrate.js`) exists: reads, writes and identities run on ext4 — native symlinks, native mode bits, and the mutation guard survives to the write's atomic publication, kernel-enforced by the confined resident when the policy is confined. The former `share` opt-out (the Windows-side host stack over the 9p share) is refused at boot; delete the line. The comment shipped beside this key in `cordis.patch.yml` still calls `share` the opt-out — that comment is out of date, and the boot refusal is what runs |
 | | `cwd` | `''` | base directory for relative paths; empty means the distro user's home |
 | | `watchMaxDepth` | `0` | how deep the in-distro watch scan walks; `0` walks the whole tree and enables the inotify backend. A positive value keeps the polling scan (inotify cannot bound its walk); a change below the bound is seen only when another change above it fires the same callback |
-| `fs-routing` | `distro` | `''` *(shipped)* | which distro the root-plane filesystem routes to; empty resolves WSL's default. **A row of its own**, with its own copy of the distro knobs — changing `wsl-fs` does not change this one, nor the other way round |
+| `fs-routing` | `distro` | `''` *(shipped)* | distro mode for the root-plane filesystem: empty/`auto` follows each target's UNC distro, `default` forces WSL's default, and a name pins. **A row of its own**, with its own copy of the distro knobs — changing `wsl-fs` does not change this one, nor the other way round |
 | | `wslPath` | `wsl.exe` *(shipped)* | path to `wsl.exe`; used here only to resolve the default distro |
 | | `sandbox` | `true` *(shipped)* | fence routed mutations by `ctx.sandboxPolicy`; same `bwrap` requirement and fail-closed refusal as `wsl-fs`. The routing row reports no `sandboxMode` — `undefined` whether the fence is on or off |
 | | `maskWindowsDrive` | `false` *(shipped)* | as on `wsl-shell`, for routed mutations |
-| | `restrictToDistro` | `true` *(shipped)* | refuse a path in another distro's share (`FS_OUTSIDE_DISTRO`) |
+| | `restrictToDistro` | `true` *(shipped)* | under a fixed `distro` (`default` or a name), refuse a path in another distro's share (`FS_OUTSIDE_DISTRO`); under `auto`, each UNC target is served by its own distro |
 | | `watchMaxDepth` | `0` *(shipped)* | how deep the routed watch scan walks; `0` walks the whole tree and enables the inotify backend; a positive value keeps the polling scan |
 | | `distroCwd` | `''` | the routed backend's default workdir; empty means the distro user's home. `cwd` belongs to the host backend only — the distro side reads `distroCwd` — while `diffBasisMaxBytes` is shared: it bounds the overwrite diff on both sides |
 | `directory-picker-wsl` | `preferredDistro` | `''` *(shipped)* | the distro listed first in the picker |
 | | `includeHostHome` | `true` *(shipped)* | also list the Windows home directory |
 | | `maxEntries` | `1000` *(shipped)* | maximum entries listed per directory |
-| `subprocess-wsl` | `distro` | `''` *(shipped)* | which distro the GUI terminal opens in |
+| `subprocess-wsl` | `distro` | `''` *(shipped)* | distro mode for the GUI terminal: empty/`auto` follows the launch directory, `default` forces WSL's default, and a name pins |
 | | `shell` | `''` | pin a shell; empty lets `wsl.exe` decide |
 | | `loginShell` | `true` | whether a pinned shell uses login semantics |
 | | `hostSessions` | `true` | give a session opened on a Windows folder a host `powershell.exe` in its own directory instead of the distro shell at `/mnt/<drive>/…`; `false` restores the composition-owned distro terminal for every session |
@@ -83,6 +83,21 @@ changes nothing and does not fail: the log carries
 `patch: entry "wsl-shell" not found` and `patch: entry "wsl-fs" not found`, and the
 composed config keeps the shipped values.
 
+The helper does the extraction and the common edits for you:
+
+```bash
+pnpm run preset -- --distro Ubuntu --session-sandbox false \
+  --out "$DSH_HOME/profiles/<name>/cordis.patch.yml"
+```
+
+`--distro`, `--session-sandbox`, `--sandbox`, `--mask-windows-drive` and
+`--agent-backend` are the supported edits; without `--out` the helper prints the
+complete block instead of writing it. `pnpm run preset -- --check <file>` reads an
+existing layer and **fails with the exact block to paste** when it finds a
+top-level `- id: wsl-shell`/`wsl-fs` entry — the silent no-op is caught before
+boot. The generated block is byte-for-byte the shipped row plus your edits, so a
+plugin upgrade only needs a re-run.
+
 The route that works is to override the `preset-wsl` row as a whole. A row's
 `config` is replaced whole, never deep-merged, so the replacement has to carry
 `id`, `order` and the entire `plugins` list — every plugin, the `wsl-env` group
@@ -164,9 +179,43 @@ is out of service and the call rides the one-shot `wsl.exe` path.
 
 ## Which distro is used
 
-`distro: ''` means the distro `wsl.exe` treats as default, so an installation with a
-single distro needs no configuration. Name one when you have several, or when the
-default is not the one you want sessions in.
+`distro: ''` (or `distro: 'auto'`) follows the workspace: opening
+`\\wsl.localhost\Debian\...` runs there even when Ubuntu is WSL's default.
+`distro: 'default'` forces WSL's default instead, and a fixed distro (`default` or
+a name) pins every session to that distro — a foreign UNC then refuses with
+`FS_OUTSIDE_DISTRO` while `restrictToDistro` holds. A single-distro installation
+needs no configuration.
+
+## The strict profile
+
+`maskWindowsDrive: true` with `sandbox: true` is the strict profile: every
+confined profile shadows `/mnt` with an empty tmpfs, so a confined command can
+neither read the Windows drive nor launch a Windows executable from it. Write it
+into a profile with the preset helper (the rows are nested inside `preset-wsl`):
+
+```bash
+pnpm run preset -- --sandbox true --mask-windows-drive true \
+  --out "$DSH_HOME/profiles/<name>/cordis.patch.yml"
+```
+
+The trade-offs are real: confined commands lose `/mnt/c` entirely — no reading
+Windows files, no running Windows tools, no dev server that expects a Windows
+path. It is also a narrowing, not a closure: a command can still write a Windows
+executable into the workspace and run it there, because WSL's `binfmt_misc`
+dispatches on content, not location. Enforcement therefore stays `partial`, and
+the result reports `windowsDrive: "masked"`. The only complete closure is
+distro-level: `[interop] enabled=false` in `/etc/wsl.conf`, then
+`wsl.exe --shutdown`, which removes interop from the distro entirely.
+
+| Interop state | How | `/mnt` | Windows exe from `/mnt` | Workspace-written `.exe` | Evidence |
+|---|---|---|---|---|---|
+| visible (default) | — | readable | runs, and escapes the Linux sandbox | runs | `pnpm run probe:sandbox` — INFO "interop escape is open" |
+| masked (strict) | `maskWindowsDrive: true` | empty tmpfs | unreachable | still runs (binfmt) | `pnpm run probe:sandbox` — the strict-profile checks |
+| disabled | `[interop] enabled=false`, `wsl --shutdown` | no Windows mounts | n/a | fails (no binfmt) | documented; not probed automatically (needs a distro-level change) |
+
+The masked and visible legs are asserted on the real machine by
+`test/probe/sandbox.sh`; the disabled leg needs a distro configuration change and
+a WSL shutdown, so it stays a manual check recorded here.
 
 ## Turning the sandbox off
 
@@ -195,8 +244,18 @@ is missing.
 
 The same probe also runs when a session opens: the `wsl-preflight` row warns
 with the full remedy if `bwrap` is unusable, so the news arrives with the
-session rather than with the first failed command. It is advisory — it never
-installs anything and never changes the fail-closed semantics; drop the
+session rather than with the first failed command. It also checks the session
+runtime's prerequisites — systemd as PID 1, the user manager, `systemd-run` and
+Linger — when `sessionSandbox` on the preflight row is `true` (the default,
+matching the shipped preset). Set `sessionSandbox: false` on that row when the
+profile opts out of the session runtime, so it does not warn about a
+prerequisite the profile does not use.
+
+The advisory is logged and also published as a `wsl-preflight` runtime-context
+entry, so it reaches the session transcript; DSH 0.2.1 has no toast/banner seam
+for a plugin (see [UPSTREAM-SESSION-NOTICE.md](UPSTREAM-SESSION-NOTICE.md) and
+[LIMITATIONS.md](LIMITATIONS.md#session-start-advisories)). It is advisory — it
+never installs anything and never changes the fail-closed semantics; drop the
 `wsl-preflight` row from your layer (or set `sandbox: false` on it) to silence
 the warning.
 
@@ -218,8 +277,8 @@ When something refuses, the message names the row or the code:
 | a command never starts | a `WSL_E_*` code naming the distro | start it with `wsl.exe -d <distro>`, or point `distro` at another one — wider permissions do not help |
 | `wsl.exe` itself cannot be started | the error names the executable and says to check `wslPath` on this row | fix `wslPath`, and check WSL is installed |
 | WSL wedges mid-command | no completion within the deadline | retry once, then `wsl.exe --shutdown` and reopen |
-| a watched path never fires | `FS_IO_ERROR` from `watch` | watch a path inside the pinned distro |
-| a path in another distro is refused | `FS_OUTSIDE_DISTRO` | open a session in that distro, or set `restrictToDistro: false` |
+| a watched path never fires | `FS_IO_ERROR` from `watch` | watch a path inside the selected distro |
+| a path in another distro is refused | `FS_OUTSIDE_DISTRO` | only when `distro` is pinned; set `distro: ''`/`auto` to follow the workspace, or open a session in that distro |
 
 The full code table — what each code means and what clears it — is
 [ARCHITECTURE.md § Error codes](ARCHITECTURE.md#error-codes); the design boundaries
@@ -229,5 +288,5 @@ behind the fail-closed choices above are in [LIMITATIONS.md](LIMITATIONS.md).
 
 | Key | Default | Meaning |
 | --- | --- | --- |
-| `distro` | `''` | the distro the `DSH_WSL_*` facts describe |
+| `distro` | `''` | distro mode for the `DSH_WSL_*` facts: empty/`auto` follows each session's workspace, `default` forces WSL's default, and a name pins |
 | `portsRefreshMs` | `10000` | how often the `DSH_WSL_PORTS` listening-port snapshot refreshes through the resident agent. A failed scan keeps the last successful list (and a debug line), so a transient agent outage does not read as “no ports”; only a successful empty scan means none were listening |

package/docs/LIMITATIONS.md

@@ -18,8 +18,10 @@ crosses the 9p share. What to know about the one substrate there is:
   Overwrites and edits keep the original bits. Run `chmod` (or ask the model to)
   when a new file must be executable.
 - **When the agent is out, file operations fail closed.** The distro stopped, or
-  the resident crashed past its one rebuild: `FS_IO_ERROR` naming the substrate,
-  with the recovery path in the message. There is no fallback I/O to degrade
+  the resident crashed through its revive budget: `FS_IO_ERROR` naming the
+  substrate, with the recovery path in the message. A single crash rides the
+  one rebuild (read-only ops only); a spent rebuild enters the bounded revival
+  (2/4/8 s), and three deaths make the state permanent with the restart remedy. There is no fallback I/O to degrade
   into — deliberately; the old failure message pointed at the share, and the
   share is what this plugin exists to keep the model off.
 - **The mutation guard survives to the write.** `createIfAbsent` publishes with
@@ -125,7 +127,13 @@ crosses the 9p share. What to know about the one substrate there is:
   through the pipe before cutting. Expect the GUI file tree and previews to be
   slower than a direct agent call, especially on large files; the model's own
   file operations are unaffected — they use the preset filesystem and the
-  resident agent directly.
+  resident agent directly. Measured 2026-10-19 with
+  [`test/probe/gui-preview.sh`](../test/probe/gui-preview.sh) (20 iterations on
+  this machine): the routed backend's `stat` p95 2.7 ms, `listDir` p95 5.1 ms,
+  and a 1 MiB `readByteRange` p95 **63.5 ms/MiB** — the service's own round
+  trips sit on top of those, and the 1 s/MiB budget has a wide margin. No
+  optimization is justified by these numbers; revisit only with a measured
+  regression.
 
 - **`fs-routing` is the seam.** The shipped service depends on the routed root
   filesystem staying enabled and faithful to the `ctx.fs` contract (`resolve`,
@@ -193,15 +201,47 @@ crosses the 9p share. What to know about the one substrate there is:
   a separate case and is now reported as an error naming that directory, because
   `wsl.exe` would otherwise run the command in `/` and exit 0.
 
+## Agent diagnostics
+
+- **The doctor's `agent.handshake` check probes a fresh resident, not the live
+  one.** It starts `agent/wsl-agent.sh` in the distro, reads its HELLO (pid,
+  protocol, script digest) and stops it, so it proves that the agent path can
+  start and that the file the distro reads is the shipped one. It cannot read
+  the running app resident's last error — there is no IPC channel from a plugin
+  script to the app process — so that error stays in the app log. In-process,
+  `WslAgent.status()` exposes state, pid, lastError, deaths and pending.
+- **`dsh-wsl-*.scope` counts are point-in-time.** The doctor lists and inspects
+  the user scopes once; a scope created or stopped a moment later is not
+  reflected. `--fix` runs the same sweep the session preflight uses.
+
+## Session-start advisories
+
+- **There is no session-UI notice seam in DSH 0.2.1.** When a distro session
+  opens, `wsl-preflight` checks `bubblewrap`, systemd as PID 1, the user
+  manager, `systemd-run` and Linger. A failure is advisory: it never installs
+  anything, never cancels the session and never changes the fail-closed
+  behavior of the first command. The finding goes to the host log
+  (`logger.warn`) and into the session's runtime context as a `wsl-preflight`
+  entry — model-visible on the next assembly — but the GUI today has no
+  toast/banner service a plugin can publish to. `pnpm run doctor` is the
+  deterministic human-facing check; the exact upstream ask is
+  [UPSTREAM-SESSION-NOTICE.md](UPSTREAM-SESSION-NOTICE.md).
+- **The runtime-context entry is a repeated snapshot, not a dismissible
+  notification.** It appears in every assembly until the environment is fixed;
+  it has no severity decoration and no dismiss control. Removing the
+  `wsl-preflight` row (or setting `sandbox: false` on it) silences the probe
+  entirely.
+
 ## Ports
 
 - **The port poller keeps the resident agent permanently warm.** The
   `DSH_WSL_PORTS` snapshot refreshes through the shared resident agent every
   `portsRefreshMs` (10 s by default, well inside the agent's idle timeout), so
-  while the app runs the agent never idles out: one `wsl.exe` and one
-  in-distro agent process stay resident per pinned distro even with no command
-  in flight. Raising `portsRefreshMs` past the agent's idle timeout restores
-  idle shutdown, at the cost of staler port facts.
+  while a distro's session is active the agent never idles out: one `wsl.exe`
+  and one in-distro agent process stay resident per active distro even with no
+  command in flight. The poller starts only for a distro a session actually
+  uses; raising `portsRefreshMs` past the agent's idle timeout restores idle
+  shutdown, at the cost of staler port facts.
 
 ## The directory picker
 

package/docs/MIGRATION.md

@@ -0,0 +1,98 @@
+# Configuration stability and migration
+
+What a release may change, how a breaking configuration change is announced and
+carried, and which gates a release must clear. The version table in
+[RELEASING.md](RELEASING.md#1-decide-the-version) is the source for the bump; this
+page is the contract those bumps follow.
+
+## The freeze below 1.0
+
+The package is below `1.0.0`, so the on-disk profile format and the peer pins may
+still move in a **minor**. Within that freedom:
+
+- **Adding a configuration key is a minor.** The key must have a schema default
+  that preserves the previous behavior; a key that changes behavior by existing
+  is a major-shaped change and waits.
+- **Removing or renaming a key is a major** *or* a minor with a boot-time refusal
+  that names the migration (see below). Silent acceptance of a retired key is
+  never allowed: it is the failure the `preset-wsl` trap and the `substrate`
+  refusal exist to prevent.
+- **Changing a key's meaning is a minor with a migration note**, because a profile
+  written for the old meaning keeps booting. The note must say what changed, how
+  to keep the old posture, and where the behavior differs.
+- **Peer pins are exact.** A new upstream peer line is tested by the
+  [peer canary](../.github/workflows/peer-canary.yml) and lands as a minor with
+  the delta in the release note (or as a patch if the plugin code needs no
+  change).
+- **Tool names and error codes are API.** `FS_OUTSIDE_DISTRO`,
+  `SANDBOX_UNAVAILABLE`, `FS_STALE_VERSION` and the diagnostic scripts
+  (`doctor`, `diagnose`, `preset`, `bootstrap`) keep their names and contracts;
+  a rename follows the deprecation path below.
+
+## Deprecating a configuration value
+
+1. **Announce it in the release that introduces the deprecation**: a CHANGELOG
+   entry and the row in [CONFIGURATION.md](CONFIGURATION.md). The old value keeps
+   working for that release.
+2. **Keep the old spelling for one minor** when it is unambiguous. When keeping
+   it would silently change behavior, refuse it at boot instead and print the
+   migration — the `substrate: "share"` case: the value is refused with the
+   message that says to delete the line, because serving the share is exactly
+   what the plugin must not do.
+3. **Remove it in the next minor** with another CHANGELOG entry. The release note
+   names the version where the refusal appeared.
+
+### Case study: `distro: ''` (0.12.0)
+
+`distro: ''` used to mean "WSL's default distro". 0.12.0 made the empty value
+mean **auto**: follow the request workdir's UNC distro. A profile that relied on
+the old meaning keeps booting, but now behaves differently. The migration:
+
+```yaml
+# keep the old posture: every command in WSL's default distro
+- id: preset-wsl
+  config:
+    plugins:
+      # … full block; set on both rows …
+      - id: wsl-shell
+        config:
+          distro: default
+      - id: wsl-fs
+        config:
+          distro: default
+```
+
+`pnpm run preset -- --distro default --out …` writes that block. The CHANGELOG
+entry for 0.12.0 states the change; this page is the durable copy. `doctor`
+reports the effective distro mode in its host/distro rows, and `--dump-config`
+shows the composed value.
+
+## Gates a release must clear
+
+| Gate | How | Runs where |
+|---|---|---|
+| Config docs and CHANGELOG current | review the diff; `lint:links` covers cross-references | CI |
+| `pnpm test` | style, links, syntax, build freshness, tsc, 40 unit files | CI (Node 22/24, Ubuntu + Windows) |
+| `pnpm run test:coverage` | lines 85 / branches 84 / functions 70 | CI (Node 24, Ubuntu) |
+| Peer line tested | `peer-canary` workflow resolves `next` and runs the scratch upgrade | CI schedule/manual |
+| Packed install/upgrade/uninstall | `pnpm run e2e:install` (temp `DSH_HOME`, 0.11.0 → current, marker) | manual, this machine (10/10 on 2026-10-19) |
+| Real-machine probe suite | `test/probe/run-all-when-closed.sh` (needs the app closed) | manual; **not run in this environment** since the last batch's targeted probes |
+| Clean Win11 + Ubuntu first run ≤ 5 min | a clean machine, a stopwatch | **not run** (the project's machine is already configured) |
+| aarch64 executed | the native suite on aarch64 WSL or qemu | **not run** (CI builds the binary only) |
+| No open P0 bug for 30 days | issue tracker | time-based; cannot be asserted from a checkout |
+
+The last four rows are deliberately marked as unrun rather than assumed: a
+release note must not claim them, and [ROADMAP-1.0.md](ROADMAP-1.0.md#wsl-304--10-readiness)
+tracks them. A release that skips the manual rows still ships through the tag
+workflow, but its notes say which gates were executed.
+
+## Verifying a migration locally
+
+```bash
+pnpm run preset -- --distro default --check <profile>/cordis.patch.yml  # no nested-row trap
+pnpm run doctor -- --json                                               # effective environment facts
+dsh --profile <name> --dump-config                                      # composed rows
+```
+
+A profile that fails to boot after a migration should name the remedy in the
+error; if it does not, that is a bug — report it with the `doctor --json` output.

package/docs/PARITY.md

@@ -83,7 +83,7 @@ shaped a phase of the plan.
 | --- | --- | --- | --- |
 | 0 | landed | This document; contract audit above | baseline recorded |
 | 1 | landed | `lib/agent.js` (with `lib/agent-protocol.js`, `lib/agent-shared.js`) and `agent/wsl-agent.sh`: resident process speaking a line protocol (pipe-separated fields, single-line base64 payloads), version + script-digest handshake, lazy start, idle shutdown, crash-rebuild-once, one-shot `wsl.exe` fallback for execution | resident server |
-| 2 | landed | real `watch()` shipped (in-distro mtime poll, `lib/watcher.js`); the native-ext4 migration of the remaining fs operations finished with the share's retirement — every model-facing file operation now runs on the agent, and the share-era workarounds went with it | native file semantics, change invalidation — watch + publication done (a poll, not inotify; blind spots in LIMITATIONS and CONFIGURATION) |
+| 2 | landed | real `watch()` shipped: inotify for an unbounded directory since 0.10.0 (polling fallback for a file target, a bounded depth or a distro without `inotify-tools`); the native-ext4 migration of the remaining fs operations finished with the share's retirement — every model-facing file operation now runs on the agent, and the share-era workarounds went with it | native file semantics, change invalidation — inotify primary, polling fallback; blind spots in LIMITATIONS and CONFIGURATION |
 | 3 | landed (deviation: no streaming, no spill files) | `WslShellExecutor` exec via agent; in-distro TERM→KILL; handle shape preserved | native exec latency |
 | 4 | landed | `npm run bootstrap`, family-aware install command, `SANDBOX_UNAVAILABLE` names it; the handshake ships the protocol version plus the script digest | open-and-it-works |
 | 5 | landed | per-session routing by workspace coordinates (`terminal-route.js`, `hostSessions`); idle distro terminals are reclaimed by a distro-side scan (`lib/terminal-activity.js`) — the host-side shell-activity integration still does not arm for `wsl.exe`, which is why the observation is a scan | terminal per window/session |

package/docs/PERFORMANCE.md

@@ -0,0 +1,60 @@
+# Performance: ext4 agent vs the 9p share
+
+The plugin's reason to exist is not only correctness: a WSL workspace served
+through the Windows 9p share is measurably slower than the same files read on
+the distro's ext4 through the resident agent. This page records the measurements
+and how to reproduce them; it does not extrapolate beyond them.
+
+## The two substrates
+
+| | 9p share (`\\wsl.localhost\...`) | This plugin |
+|---|---|---|
+| File I/O | host stack crosses the VM boundary per operation | resident agent serves reads/writes on ext4 inside the distro |
+| Change feed | polling the share | inotify inside the distro (`watchMaxDepth: 0`) |
+| Commands | host process | distro login shell through `wsl.exe` |
+
+The plugin's root filesystem routes every WSL path to the distro backend
+(`fs-routing`), so the GUI file tree, previews and the model's file tools all
+use the agent path. The design and its trade-offs are in
+[root-fs-routing.md](root-fs-routing.md); the known limits are in
+[LIMITATIONS.md](LIMITATIONS.md).
+
+## Measured numbers
+
+Machine: Windows 11 + WSL 2, Ubuntu, x86_64, the project's development machine.
+Absolute numbers are machine-dependent; the ratio and the budgets are the point.
+
+| Scenario | 9p share | Agent (ext4) | Source |
+|---|---|---|---|
+| 16 concurrent shared reads | 342–614 ms (queue up to 583 ms) | **2.4–4.1 ms** after A7, first start ~70 ms once | [ADR 0002 fs queue](adr/0002-native-agent.md#fs-queue-measurement-a6-2026-10-18) |
+| Single FS op (host round trip) | — | p95 ≈ 22 ms | [ROADMAP-1.0.md](ROADMAP-1.0.md#7-metrics) |
+| GUI-preview backend: `stat` | — | p95 **2.7 ms** | `pnpm run probe:gui-preview` (20 iterations, 2026-10-19) |
+| GUI-preview backend: listing | — | p95 **5.1 ms** | same |
+| GUI-preview backend: 1 MiB page | — | p95 **63.5 ms/MiB** | same |
+
+The GUI-preview number covers the routed backend operations a preview pays.
+The shipped `workspace-files` service adds its own calls on top; that service
+shape stays qualitative in [LIMITATIONS.md](LIMITATIONS.md). The 1 s/MiB budget
+has a wide margin, so no further optimization (the deferred v6 FS concurrency)
+is justified by these measurements.
+
+## Reproduce
+
+Inside the distro, with the checkout:
+
+```bash
+pnpm run probe:gui-preview        # stat / listDir / 1 MiB page read, p50/p95
+node test/probe/fs-queue.mjs      # the agent queue, sequential vs concurrent, with per-op latency
+```
+
+Both need a working distro and Node; neither boots the harness. The probes print
+the raw samples' p50/p95/max and fail when a budget is exceeded, so a regression
+is a red probe rather than a claim in prose.
+
+## What is not measured
+
+- End-to-end GUI paint time (the browser and the service's own work are out of
+  scope for these probes).
+- 9p numbers for large files or many small files beyond the A6 sample above;
+  the A6 measurement is the recorded baseline, not a re-runnable benchmark.
+- aarch64; the binary is built but not executed in CI.

package/docs/QUICKSTART.md

@@ -0,0 +1,125 @@
+# Quickstart
+
+Five minutes from a clean Windows + WSL 2 machine to a working WSL session.
+This page is the entry point; every claim links to the document that owns it.
+
+## 1. Prerequisites
+
+| Need | How to check | If missing |
+|---|---|---|
+| Windows 10/11 with WSL 2 | `wsl.exe -l -v` shows `VERSION 2` | `wsl.exe --install` |
+| A distro | one line in the list above | `wsl.exe --install -d Ubuntu` |
+| `bubblewrap` | `wsl.exe -d <distro> -- which bwrap` | `wsl.exe -d <distro> -u root -- apt-get install -y bubblewrap` |
+| systemd + Linger (for the session runtime) | `node <plugin>/scripts/doctor.mjs` (installed) or `pnpm run doctor` (checkout) | `[boot] systemd=true` in `/etc/wsl.conf`, `wsl --shutdown`, then `loginctl enable-linger "$USER"`; or set `sessionSandbox: auto`/`false` |
+| Node 22.19+ or 24 | only needed for source/development work | not needed to use the published plugin |
+
+The doctor (`scripts/doctor.mjs`, or `pnpm run doctor` from a checkout) covers all
+of the above in one pass and prints a copy-paste remedy per failure. It is read-only unless you pass `--fix` (stale scopes) or
+`--fix --install` (packages, after a confirmation).
+
+## 2. Install
+
+From a Windows PowerShell where the DSH CLI is available:
+
+```powershell
+dsh plugin --profile <profile> add dsh-plugin-wsl-env
+dsh --profile <profile> --dump-config      # the plugin rows must be there
+```
+
+For a profile that already overrides the preset, keep the override as the full
+`preset-wsl` block — `pnpm run preset --check <patch>` fails loudly when a layer
+targets `wsl-shell`/`wsl-fs` by id.
+
+## 3. Open a WSL workspace
+
+In the GUI, open a folder through the picker (`\\wsl.localhost\<distro>\home\<you>\proj`)
+or an UNC path directly. The session's commands, file tools, terminal and previews
+all run in that distro; a Windows folder keeps the normal Windows environment.
+Two distros can be open at once, each with its own environment.
+
+## 4. Verify
+
+Ask for a command, e.g. `pwd && uname -a`. Expected: the Linux path and the
+distro kernel. If the first command fails, the error names the remedy; the
+[doctor](CONFIGURATION.md) and the [Troubleshooting table](../README.md#troubleshooting)
+cover the common cases.
+
+## Recipes
+
+Commands run in the model's session, inside the distro, from the workspace root.
+
+### Node / TypeScript
+
+```bash
+node -v && pnpm -v
+pnpm install
+pnpm test
+pnpm dev            # a dev server survives the command that started it with sessionSandbox: true
+```
+
+The server's port appears in `DSH_WSL_PORTS` on the next snapshot (10 s by
+default); open it from Windows at `http://localhost:<port>`.
+
+### Python
+
+```bash
+python3 -m venv .venv && . .venv/bin/activate
+pip install -r requirements.txt
+python -m pytest
+```
+
+Use the distro's interpreter, not a Windows one: the session's `python3` is the
+one on the distro `PATH` (pyenv/conda shims included).
+
+### Rust
+
+```bash
+cargo build --release
+cargo test
+```
+
+Targets are compiled natively for the distro's architecture (x86_64 or aarch64);
+do not reuse Windows `target/` directories.
+
+### Go
+
+```bash
+go build ./...
+go test ./...
+```
+
+The module cache lives in the distro's `$GOPATH`, so builds stay on ext4.
+
+### Monorepo
+
+Open the repository root as the workspace. Each package's commands run from the
+same distro; `pnpm -r`, `turbo`, `nx` and `make` see one Linux filesystem. The
+file watcher uses inotify inside the distro (`watchMaxDepth: 0`). If a change is
+missed, see the watcher bounds in [CONFIGURATION.md](CONFIGURATION.md).
+
+## Compatibility
+
+Honest status, not a promise. "Probed" means a real-machine run is recorded in
+this repository; "target" means the design supports it but the leg has not been
+executed here.
+
+| Tier | Configuration | Status |
+|---|---|---|
+| 1 | Ubuntu 24.04 or Debian 12, systemd, x86_64 | Probed on Ubuntu (the project's development machine; the real-machine suite is manual). Debian is a Tier 1 target, probe pending |
+| 2 | Other systemd distros, aarch64 | The aarch64 native binary is built by CI but not executed here; aarch64 WSL or qemu is the pending leg |
+| Unsupported | WSL 1, Linux/macOS hosts, Windows without WSL 2 | Not supported; the plugin attaches to `wsl.exe` |
+
+With `sessionSandbox: auto` a distro without systemd/Linger still gets the
+per-command `bubblewrap` sandbox and the result reports the narrower scope;
+`true` refuses. See [CONFIGURATION.md](CONFIGURATION.md#the-strict-profile) for
+the sandbox trade-offs and [PERFORMANCE.md](PERFORMANCE.md) for the measured
+latency.
+
+## Demo
+
+There is no GIF or screenshot in this repository yet: producing one needs a
+capture of the GUI, which this project has not recorded. The
+[Troubleshooting table](../README.md#troubleshooting) and the probe output
+(`pnpm run probe:sandbox`, `pnpm run probe:gui-preview`) are the reproducible
+evidence in the meantime; the absence is recorded in
+[ROADMAP-1.0.md](ROADMAP-1.0.md#wsl-302--discoverability-and-docs-entry).

package/docs/README.zh.md

@@ -80,6 +80,7 @@ wsl.exe -d <发行版> -u root -- apt-get install -y bubblewrap
 
 打开一个发行版文件夹作为工作区，例如 `\\wsl.localhost\ubuntu\home\you\project`。
 
+- 打开哪个发行版的文件夹，就在哪个发行版执行——即使它不是 WSL 的默认发行版。
 - 命令在发行版登录 shell 中运行。`/home/you/x` 与 `\\wsl.localhost\ubuntu\home\you\x` 是同一个文件。
 - **New terminal** 在同一发行版、同一目录打开 shell。
 - 模型能看到监听端口，并返回 dev server 的 URL。WSL 2 会把 localhost 转发到 Windows。
@@ -91,18 +92,18 @@ wsl.exe -d <发行版> -u root -- apt-get install -y bubblewrap
 
 | 行 | 键 | 默认值 | 作用 |
 |---|---|---|---|
-| `wsl-shell` | `distro` | `''` | 使用的发行版；空表示 WSL 默认 |
+| `wsl-shell` | `distro` | `''` | 发行版模式；空/`auto` 跟随工作区，`default` 强制 WSL 默认 |
 | | `sandbox` | `true` | 用 `bubblewrap` 约束命令 |
 | | `sessionSandbox` | `true` | 会话命令跑在同一个 systemd user scope 中 |
 | | `agentBackend` | `auto` | 发行版内 agent：`auto`、`native` 或 `shell` |
 | | `maskWindowsDrive` | `false` | 让受限命令看不到 `/mnt` |
-| `wsl-fs` | `distro` | `''` | 文件操作使用的发行版 |
-| | `restrictToDistro` | `true` | 拒绝属于其他发行版的路径 |
+| `wsl-fs` | `distro` | `''` | 发行版模式；空/`auto` 跟随每个目标路径 |
+| | `restrictToDistro` | `true` | 固定发行版（`default` 或名字）时拒绝属于其他发行版的路径 |
 | | `sandbox` | `true` | 按策略检查受限写入 |
 | | `sessionSandbox` | `true` | 受限写入跑在会话 runtime 中 |
 | | `substrate` | `agent` | 发行版内 agent；`share` 在启动时被拒绝 |
 | `directory-picker-wsl` | `includeHostHome` | `true` | 同时列出 Windows 家目录 |
-| `subprocess-wsl` | `distro` | `''` | GUI 终端使用的发行版 |
+| `subprocess-wsl` | `distro` | `''` | 发行版模式；空/`auto` 跟随启动目录 |
 
 `wsl-shell` 和 `wsl-fs` 位于随包的 `wsl` preset 中，按 id 覆盖无效。要改就覆盖整个 `preset-wsl` 行；配方和其余键见 [docs/CONFIGURATION.md](CONFIGURATION.md)。[`cordis.patch.yml`](../cordis.patch.yml) 是随包值的注释参考。
 
@@ -174,6 +175,7 @@ pnpm run sync:windows  # 更新应用加载的 Windows 侧副本
 | [docs/ARCHITECTURE.md](ARCHITECTURE.md) | 服务、路径路由、沙箱、错误码 |
 | [docs/LIMITATIONS.md](LIMITATIONS.md) | 插件不做的事 |
 | [docs/ROADMAP.md](ROADMAP.md) | 当前计划和推迟项 |
+| [docs/ROADMAP-1.0.md](ROADMAP-1.0.md) | 1.0 与生态优化计划 |
 | [docs/VALUE.zh.md](VALUE.zh.md) | 价值与取舍 |
 | [CONTRIBUTING.md](../CONTRIBUTING.md) | 开发循环、质量门、探针 |
 | [SECURITY.md](../SECURITY.md) | 私下上报漏洞 |