dsh-plugin-wsl-env 0.12.0 → 0.13.0

package/CHANGELOG.md

@@ -16,6 +16,160 @@ were part of the record.
 
 ## [Unreleased]
 
+## [0.13.0] - 2026-10-19
+
+This release ships the P0/P1 hardening batch: session-scoped `auto`
+sandboxing, resident-agent recovery with doctor coverage, the packed-install
+E2E, measured GUI-preview and `@`-reference probes, and the docs/community
+entry points.
+
+### Added
+
+- **`pnpm run preset` — the `preset-wsl` override helper.** `wsl-shell` and
+  `wsl-fs` sit inside `preset-wsl`'s `config.plugins`, so a patch that targets
+  them by id is ignored with only a loader warning. The helper prints the
+  complete `preset-wsl` block, applies `distro`/`sessionSandbox`/`sandbox`/
+  `maskWindowsDrive`/`agentBackend`, and `--check` fails loudly with the exact
+  block to paste when a layer carries the nested id patch. See
+  [docs/CONFIGURATION.md](docs/CONFIGURATION.md#overriding-the-rows-inside-preset-wsl).
+
+- **Session-notice upstream payload ready.** The exact title, body and `gh`
+  command for the session-visible notice proposal are in
+  `docs/upstream/proposal-session-notice.md`; it remains unfiled (a maintainer
+  action).
+
+- **Configuration stability and migration policy.** `docs/MIGRATION.md` records
+  the below-1.0 freeze (new keys preserve behavior, removals refuse at boot with
+  a migration, meaning changes get a note), the deprecation path with the
+  `substrate: "share"` and `distro: ''` cases, and the release-gate table with
+  the manual legs (probe suite, clean machine, aarch64) marked unrun.
+  RELEASING and SUPPORT link it.
+
+- **Upstream promotion pack documented.** `docs/upstream/promotion-pack.md`
+  records the `packages/wsl/*` layout (ten capability packages plus an
+  integration package), the seam/RFC index, what the composition boot test
+  covers and its gaps, and the install proof. Promotion stays packaging and
+  proof, not a dependency.
+
+- **`@`-reference traversal cost measured; seam deferred.** The Windows walk
+  over the WSL share is ~56× the ext4 walk on a 520-entry tree (84.7 ms vs
+  1.5 ms) and is now reproducible with `pnpm run probe:file-reference`.
+  `docs/UPSTREAM-FILE-REFERENCE-SEAM.md` records the three-function seam, the
+  ready (unwired) plugin consumer, and the decision to keep the 9p walk until
+  upstream exposes the funnel.
+
+- **Community loop: issue forms, triage targets and a contributor path.**
+  Feature-request and setup-report forms (the setup form requires
+  `doctor --json`), a chooser that disables blank issues, SUPPORT's P1
+  three-business-day target and two-to-four-week cadence, and a
+  `good first issue` path in CONTRIBUTING.
+
+- **Quickstart and performance entry pages.** `docs/QUICKSTART.md` is the
+  five-minute path (prerequisites, install, first session, Node/Python/Rust/Go
+  and monorepo recipes, honest Tier 1/Tier 2 table); `docs/PERFORMANCE.md`
+  records the 9p-vs-agent numbers and the GUI-preview baseline with reproduction
+  commands. The visual demo is explicitly still missing.
+
+- **GUI-preview latency has a measured baseline.** `pnpm run probe:gui-preview`
+  drives the routed backend's `stat`, `listDir` and 1 MiB `readByteRange` with
+  p50/p95 budgets (stat 100 ms, listing 500 ms, page 1 s/MiB). On this machine:
+  p95 2.7 ms / 5.1 ms / 63.5 ms per MiB. No optimization follows; the
+  `workspace-files` row is untouched.
+
+- **LSP seam researched and deferred.** `docs/UPSTREAM-LSP-SEAM.md` records that
+  the harness ships `dsh-lsp`/`dsh-lsp-stdio`/`dsh-tool-lsp` but the 0.2.1-rc.2
+  base composition mounts none of them, and that a WSL provider needs a
+  preset-scoped subprocess provider plus URI translation. The prototype is
+  deferred behind an explicit trigger; no LSP claim is made in the README.
+
+- **Peer-upgrade canary.** A weekly workflow resolves the `next` dist-tag of
+  every pinned peer, tests that line in a scratch copy (`pnpm test` + the
+  composition boot test), and publishes the exact version delta in the run
+  summary; a moved line that fails fails the run. `pnpm run canary:peers`
+  performs the check locally.
+
+- **The strict profile is documented and probed.** `maskWindowsDrive: true` with
+  `sandbox: true` hides `/mnt` from confined profiles; CONFIGURATION describes
+  the trade-offs and the visible/masked/disabled interop matrix, and
+  `probe:sandbox` now asserts the masked leg (empty `/mnt`, unreachable Windows
+  binary, writable workspace). Enforcement stays `partial`; the binfmt content
+  escape and the distro-level closure are stated.
+
+- **Install/upgrade/uninstall E2E.** `pnpm run e2e:install` packs the tree,
+  installs it into a fresh `%TEMP%` `DSH_HOME`, composes `--dump-config`, removes
+  it, and upgrades from the previous minor with a marker proving the profile
+  layer survived. `test/packaging.test.mjs` keeps the packed file list honest in
+  `pnpm test`.
+
+- **The doctor probes the resident agent.** `agent.handshake` starts the
+  shipped shell agent in the distro, reads its HELLO (pid, protocol, script
+  digest) and stops it, so a missing or stale agent script is a named check
+  instead of a first-command failure. It also reports the agent cache and the
+  live/stale `dsh-wsl-*.scope` counts.
+
+- **`pnpm run doctor` — one command for the environment prerequisites.** Reports
+  Windows/WSL versions, the distro and its login shell, bubblewrap usability,
+  systemd / the user manager / `systemd-run` / Linger, the optional tools, peer
+  versions, the native-agent cache, stale `dsh-wsl-*.scope` units and the
+  profile-patch trap that silently ignores `wsl-shell`/`wsl-fs` overrides. Each
+  failure carries one copy-paste remedy; `--json` is the machine shape, and
+  `--fix` only sweeps stale scopes unless `--install` plus a confirmation allows
+  a package install. `diagnose` is now the read-only alias.
+
+### Changed
+
+- **`sessionSandbox: auto` — the session runtime is an optimization, not a
+  prerequisite.** `wsl-shell` and `wsl-fs` accept `true`, `false` or `"auto"`;
+  `auto` uses the systemd user scope when it is available and otherwise falls
+  back to the per-command `bwrap` profile — still confined, never unconfined —
+  reporting `sessionScope: "session" | "per-command"` in the command result.
+  A failed verdict is re-probed at most once a minute, so installing systemd or
+  enabling Linger upgrades without an app restart. `true` keeps refusing with
+  the existing remedy; `false` is unchanged.
+
+- **The session preflight also checks the session-runtime prerequisites.** It
+  now probes systemd as PID 1, the user manager, `systemd-run` and Linger —
+  not only `bubblewrap` — when a distro session opens, and publishes the same
+  advisory to the session's runtime context as well as the log. `sessionSandbox:
+  false` on the `wsl-preflight` row skips the session half. DSH 0.2.1 has no
+  session-notice seam; the ask is recorded in
+  [docs/UPSTREAM-SESSION-NOTICE.md](docs/UPSTREAM-SESSION-NOTICE.md) and the
+  boundary in [docs/LIMITATIONS.md](docs/LIMITATIONS.md#session-start-advisories).
+  Advisory only: nothing is installed and fail-closed behavior is unchanged.
+
+- **The distro follows the workspace.** `distro: ''`/`'auto'` now selects the
+  distro from the request workdir or target UNC; `'default'` forces WSL's
+  default, and an explicit name still pins. Shell, files, root-plane routing,
+  the GUI terminal and `shell-env` all use the same rule, and the shared agent,
+  substrate, home and session-runtime state are cached per distro. A pinned
+  profile still refuses a foreign UNC with `FS_OUTSIDE_DISTRO`. This changes the
+  previous meaning of `distro: ''` (WSL's default): set `'default'` to keep that
+  posture.
+
+### Fixed
+
+- **A dead resident revives with bounded backoff instead of staying dead for
+  the process lifetime.** A failure that spends the one permitted rebuild now
+  leaves the agent `dead` with a revival scheduled (2 s, 4 s, 8 s); the next
+  call after the delay gets a fresh transport and its own single rebuild, and
+  nothing from the dead generation is replayed. After three deaths the state is
+  permanent and the refusal names the restart remedy. `status()` exposes the
+  live state, pid, last error and pending count for diagnostics.
+
+- **A cancelled command's signal can no longer kill the next one.** The
+  out-of-band USR1 carries no request id: a signal meant for a timed-out
+  command could land after the agent had moved on, and the next command then
+  died with exit 138 but reported `completed`. A host timeout no longer sends
+  the signal at all (the in-distro watcher is the one that kills that
+  command), and an explicit cancel now waits briefly and is dropped once the
+  request answered or a newer request is running.
+
+- **A missing workdir is reported with its path on the native agent.** The
+  native agent reports the failed spawn as reason `spawn`, without naming the
+  directory; the executor now treats that as its own error class and retries
+  the command on the one-shot path, whose `chdir(<path>) failed` warning names
+  the directory.
+
 ## [0.12.0] - 2026-10-19
 
 The GUI file service keeps the shipped `workspace-files` row: its server-only

package/CONTRIBUTING.md

@@ -172,11 +172,14 @@ terminal if you would rather not see the prompt.
 
 | Command | Covers | Needs a harness |
 |---|---|---|
-| `pnpm test` | style checks, syntax pass, build consistency, type check, and unit tests | no |
+| `pnpm test` | style checks, relative links, syntax pass, build consistency, type check, and unit tests | no |
+| `pnpm run lint:links` | relative Markdown links in README, CONTRIBUTING, AGENTS and `docs/**` | no |
 | `pnpm run test:coverage` | unit tests with coverage | no |
 | `pnpm run lint:style` | style and lint rules | no |
 | `pnpm run lint:build` | the build-freshness check: every source has its artifacts and the committed bytes match a real build | no |
 | `pnpm run lint:types` | the TypeScript check over `test/**` and the ambient types (`tsc --noEmit`) | no |
+| `pnpm run e2e:install` | packed-tarball install/upgrade/uninstall into a temporary `DSH_HOME` | yes; Windows + WSL |
+| `pnpm run doctor` | the environment prerequisites, peers and caches (`--json` for scripts; `diagnose` is the read-only alias) | no; inside the distro |
 | `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 |
@@ -187,11 +190,14 @@ terminal if you would rather not see the prompt.
 | `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:gui-preview` | the routed backend's stat/listing/1 MiB page-read latency (p50/p95 budgets) | no; inside the distro |
+| `pnpm run probe:file-reference` | the `@`-reference traversal: 9p walk vs the distro's ext4 | no; inside the distro |
+| `pnpm run probe:fs-routing` | the root-plane router: distro coordinate, host plane, cross-distro fence | yes |
 | `pnpm run probe:mode` | which POSIX-mode facts survive the share | no; Windows Node |
 | `pnpm run probe:sandbox-off` | the documented opt-out on both providers | yes |
 
 Every script above is wired in `package.json`. `pnpm test` runs `lint:style`,
-`test:syntax`, `lint:build`, `lint:types` and `test:unit` in that order.
+`lint:links`, `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.
 
@@ -253,10 +259,10 @@ must skip itself — print a `SKIP` line and exit 0 — the way that file does o
 
 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`,
+(`run.sh`, `terminal.sh`, `sandbox-shell.sh`, `picker.sh`, `fs-routing.sh`,
+`missing-wsl.sh`, `sandbox-off.sh`) boot a throwaway profile whose setup steps
+are in the header of `test/probe/run.sh`; the six others reuse the profile
+`run.sh` creates rather than making their own. The distro probes (`substrate.sh`, `watch.sh`, `agent.sh`,
 `exec.sh`) boot nothing: they run from a distro terminal and drive the resident
 agent through the `wsl.exe` interop transport. `sandbox.sh` and `mode.sh` sit
 outside both groups — no harness boot, no profile.
@@ -311,6 +317,22 @@ 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.
 
+## Good first issues and the contributor path
+
+The repository labels self-contained changes `good first issue`. Typical shapes:
+
+- a recipe or troubleshooting row in `README.md` or `docs/QUICKSTART.md`
+  (the link check gates it; one commit);
+- a probe report fixture under `test/probe/` that follows an existing
+  `*-report.txt` shape;
+- an issue-template wording fix, a cross-reference, or a missing error-code row
+  in `docs/ARCHITECTURE.md`.
+
+To claim one, comment on the issue. Before opening a PR run `pnpm test` (and
+`pnpm run test:coverage` for a `lib/` change), then make one logical commit whose
+body records the check results — the conventions below. Probes need a real
+Windows + WSL machine; unit tests, docs and packaging changes do not.
+
 ## Commit and pull request conventions
 
 - Write an imperative subject line: `Fix the npm readme`, not `Fixed` or `Fixes`.

package/README.md

@@ -12,6 +12,8 @@ The harness process stays on Windows. Commands, file operations, the folder pick
 
 Windows + WSL 2 only.
 
+**New here?** Start with [docs/QUICKSTART.md](docs/QUICKSTART.md) — five minutes, prerequisites, recipes and the honest compatibility table.
+
 ## Why this plugin
 
 A Windows coding tool that works on WSL projects has three options: run the whole tool inside the distro, connect to a helper server inside the distro, or let the plugin provide the distro environment. This plugin is the third option. One workflow covers both kinds of session, with the distro's real tools and the command sandbox intact.
@@ -72,7 +74,7 @@ Install `bubblewrap` before the first command:
 wsl.exe -d <distro> -u root -- apt-get install -y bubblewrap
 ```
 
-From a checkout, `pnpm run bootstrap -- <distro>` checks the four distro tools and prints the install command for the distro's package manager. Add `--install` to run it.
+From a checkout, `pnpm run doctor` is the one-command environment check: Windows/WSL versions, the distro and its shell, bubblewrap usability, systemd / the user manager / Linger, the optional tools, peer versions, the agent cache, a fresh-agent handshake, stale session scopes and the known profile-patch trap. Each failure prints one copy-paste remedy; `--json` is for scripts, and `--fix` sweeps stale scopes (package installation needs `--fix --install` and an explicit confirmation). `pnpm run diagnose` is its read-only alias. `pnpm run bootstrap -- <distro>` remains the narrower tool-install helper.
 
 Upgrade by running the `add` command again. Uninstall with `dsh plugin --profile wsl remove dsh-plugin-wsl-env`; the agent cache under `~/.cache/dsh-wsl` can then be deleted. If you added a local `workspace-files-wsl` workaround to your profile to restore previews, remove it after upgrading: the plugin no longer mounts that row.
 
@@ -80,6 +82,7 @@ Upgrade by running the `add` command again. Uninstall with `dsh plugin --profile
 
 Open a distro folder as the workspace, for example `\\wsl.localhost\ubuntu\home\you\project`.
 
+- Opening a folder in any distro runs there, even when it is not WSL's default.
 - Commands run in the distro's login shell. `/home/you/x` and `\\wsl.localhost\ubuntu\home\you\x` are the same file.
 - **New terminal** opens a shell in the same distro and directory.
 - The model sees listening ports and can return the URL of a dev server. WSL 2 forwards localhost to Windows.
@@ -91,18 +94,18 @@ Settings live on named rows in `$DSH_HOME/profiles/<name>/cordis.patch.yml`. The
 
 | Row | Key | Default | Purpose |
 |---|---|---|---|
-| `wsl-shell` | `distro` | `''` | distro to use; empty means the WSL default |
+| `wsl-shell` | `distro` | `''` | distro mode; empty/`auto` follows the workspace, `default` forces WSL's default |
 | | `sandbox` | `true` | confine commands with `bubblewrap` |
 | | `sessionSandbox` | `true` | run the session's commands in one systemd user scope |
 | | `agentBackend` | `auto` | `auto`, `native` or `shell` for the in-distro agent |
 | | `maskWindowsDrive` | `false` | hide `/mnt` from confined commands |
-| `wsl-fs` | `distro` | `''` | distro for file operations |
-| | `restrictToDistro` | `true` | refuse paths that belong to another distro |
+| `wsl-fs` | `distro` | `''` | distro mode; empty/`auto` follows each target path |
+| | `restrictToDistro` | `true` | under a fixed distro, refuse paths that belong to another distro |
 | | `sandbox` | `true` | check confined writes against the policy |
 | | `sessionSandbox` | `true` | run confined writes in the session runtime |
 | | `substrate` | `agent` | in-distro agent; `share` is rejected at startup |
 | `directory-picker-wsl` | `includeHostHome` | `true` | also list the Windows home directory |
-| `subprocess-wsl` | `distro` | `''` | distro used by the GUI terminal |
+| `subprocess-wsl` | `distro` | `''` | distro mode; empty/`auto` follows the launch directory |
 
 `wsl-shell` and `wsl-fs` are inside the shipped `wsl` preset, so overriding them by id does not work. Override the whole `preset-wsl` row instead; [docs/CONFIGURATION.md](docs/CONFIGURATION.md) has the recipe and the remaining keys. [`cordis.patch.yml`](cordis.patch.yml) is the commented reference for every shipped value.
 
@@ -145,9 +148,10 @@ Enforcement is reported as `partial`. A command inside the distro can still star
 | Symptom | Fix |
 |---|---|
 | every command reports `SANDBOX_UNAVAILABLE` | install `bubblewrap` in the distro, or set `sandbox: false` |
-| the session refuses before the first command | enable systemd and linger, or set `sessionSandbox: false` on `wsl-shell` and `wsl-fs` |
+| the session refuses before the first command | run `pnpm run doctor`; enable systemd and linger, or set `sessionSandbox: false` on `wsl-shell` and `wsl-fs` |
 | `glob` and `grep` are slow in the distro | install `ripgrep` with `pnpm run bootstrap -- <distro> --install` |
 | `dsh plugin add` prints nothing | the plugin is already installed; this is success |
+| a profile patch for `wsl-shell`/`wsl-fs` changes nothing | those rows are nested inside `preset-wsl`. Run `pnpm run preset -- --check <patch>`; it fails with the complete block to paste |
 | changes under `lib/` have no effect | run `pnpm run sync:windows`, then restart the app |
 
 More error codes and refusals are in [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md#error-codes). Everything the plugin does not do is in [docs/LIMITATIONS.md](docs/LIMITATIONS.md).
@@ -170,10 +174,13 @@ Real-machine probes run on Windows + WSL only. See [CONTRIBUTING.md](CONTRIBUTIN
 
 | Document | Content |
 |---|---|
+| [docs/QUICKSTART.md](docs/QUICKSTART.md) | five-minute first run, recipes, compatibility |
+| [docs/PERFORMANCE.md](docs/PERFORMANCE.md) | ext4 agent vs 9p, measured latency, how to reproduce |
 | [docs/CONFIGURATION.md](docs/CONFIGURATION.md) | every configuration key and how to override it |
 | [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | services, path routing, sandbox, error codes |
 | [docs/LIMITATIONS.md](docs/LIMITATIONS.md) | what the plugin does not do |
 | [docs/ROADMAP.md](docs/ROADMAP.md) | current plan and deferred work |
+| [docs/ROADMAP-1.0.md](docs/ROADMAP-1.0.md) | the 1.0 and ecosystem plan |
 | [docs/VALUE.zh.md](docs/VALUE.zh.md) | value and trade-offs in Chinese |
 | [CONTRIBUTING.md](CONTRIBUTING.md) | development loop, gates, probes |
 | [SECURITY.md](SECURITY.md) | private vulnerability reporting |

package/SECURITY.md

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

package/SUPPORT.md

@@ -7,6 +7,12 @@
 | Operating system | Windows 10 and Windows 11 |
 | Linux side | WSL2 with at least one distro, and systemd as PID 1 with a lingering user manager (`loginctl enable-linger`) for the shipped session runtime. Set `sessionSandbox: false` on the preset's `wsl-shell` to keep the per-command sandbox instead |
 | DSH packages | the `0.2.1-rc.2`-era packages listed in `peerDependencies` |
+
+The DSH row is checked weekly: `.github/workflows/peer-canary.yml` resolves the
+`next` dist-tag of every pinned peer, installs that line into a scratch copy and
+runs `pnpm test` plus the composition boot test. A successful run prints the
+exact version delta in its summary; update the row above from that summary. A
+red run means the plugin has not been validated against the new line yet.
 | Plugin version | the latest published version only |
 | Node | 22.19+ (`^22.19.0`), or 24 and later (`>=24.0.0`) |
 
@@ -22,9 +28,14 @@ supported configuration.
 
 Open an issue in the repository:
 
-https://github.com/Big-Dao/dsh-plugin-wsl-env/issues
+https://github.com/Big-Dao/dsh-plugin-wsl-env/issues/new/choose
+
+The chooser offers a **feature request** and a **setup report**; the setup
+report requires the `doctor --json` output, which is what makes a first-run
+problem diagnosable without a round trip. For a security issue, use the private
+advisory link instead (see [SECURITY.md](SECURITY.md)).
 
-Use it for bug reports and for questions about configuration. Search the open and
+Use issues for bug reports and for questions about configuration. Search the open and
 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
@@ -56,6 +67,22 @@ loudly instead of quietly.
 
 There is no long-term support branch. Fixes go to the latest version.
 
+## Triage and release cadence
+
+- **Roadmap.** The public plan is [docs/ROADMAP-1.0.md](docs/ROADMAP-1.0.md);
+  the open issues #5–#22 map to its WSL-1xx/2xx/3xx blocks.
+- **Triage target.** A `priority:P1` report gets its first response within three
+  business days, best effort. Security reports follow the response targets in
+  [SECURITY.md](SECURITY.md).
+- **Cadence.** Releases ship when there is a change worth shipping, roughly every
+  two to four weeks; the tag workflow and its gates are in
+  [docs/RELEASING.md](docs/RELEASING.md), and the configuration-stability and
+  migration rules are in [docs/MIGRATION.md](docs/MIGRATION.md). There is no
+  long-term support branch.
+- **Good first issues.** The `good first issue` label marks changes that need no
+  prior context; [CONTRIBUTING.md](CONTRIBUTING.md#good-first-issues-and-the-contributor-path)
+  lists the usual shapes and how to claim one.
+
 ## What a good bug report contains
 
 The one-command path: `pnpm run diagnose` (from a checkout of the plugin, or

package/cordis.patch.yml

@@ -66,6 +66,8 @@
     - id: subprocess-wsl
       name: 'dsh-plugin-wsl-env/subprocess'
       config:
+        # auto: follow the launch directory's UNC distro; "default" forces WSL's
+        # default, and a name pins. Empty is auto.
         distro: ''
 
 # ═════════════════════════════════════════════════════════════════════════════
@@ -135,6 +137,8 @@
     - id: fs-routing
       name: 'dsh-plugin-wsl-env/fs-routing'
       config:
+        # auto: route each UNC target to its own distro; "default" forces WSL's
+        # default, and a name pins. Empty is auto.
         distro: ''
         wslPath: wsl.exe
         sandbox: true
@@ -223,6 +227,8 @@
               - id: wsl-shell
                 name: 'dsh-plugin-wsl-env'
                 config:
+                  # auto: follow the request workdir's UNC distro; "default"
+                  # forces WSL's default, and a name pins. Empty is auto.
                   distro: ''
                   loginShell: true
                   timeoutMs: 120000
@@ -237,14 +243,15 @@
               - id: wsl-fs
                 name: 'dsh-plugin-wsl-env/fs'
                 config:
+                  # auto: follow each target path's UNC distro; "default"
+                  # forces WSL's default, and a name pins. Empty is auto.
                   distro: ''
                   restrictToDistro: true
                   # agent (the default): reads/writes/identities run inside the
                   # distro over the resident agent (lib/fs-substrate.js) —
                   # native symlinks and mode bits, the write guard survives to
                   # publication, and confined mutations are kernel-enforced.
-                  # share: the opt-out — the Windows-side host fs stack over
-                  # the 9p share.
+                  # "share" is retired; a profile carrying it is refused at boot.
                   substrate: agent
                   # Confined writes ride the session runtime (ADR 0001), so they
                   # share the command's real /tmp and workspace mounts.

package/docs/ARCHITECTURE.md

@@ -66,7 +66,7 @@ functions.
 |---|---|---|---|
 | `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`, `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. |
+| `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, choosing the session workspace's distro (default/pinned facts are probed at mount; other distros are warmed when their session appears). The port list is a snapshot per active distro, 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.
@@ -87,7 +87,7 @@ The environment is per session, not per process:
 | `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` | shipped, not replaced | its client half is the browser `file` resource provider the Sidebar previews need; it reads WSL paths through the routed root filesystem |
 | `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 |
+| `directory-picker-wsl`, `wsl-shell-env`, `auto-preset` | at the app level | they answer questions that are not scoped to a single preset; `shell-env` resolves its facts per session workspace |
 
 The preset mount requires the isolate realms. Without them the registry rejects the
 providers with `Preset services require isolate realms: shell, fs`.
@@ -295,10 +295,10 @@ own dialect, described after the table.
 |---|---|---|---|
 | `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`, 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_OUTSIDE_DISTRO` | `WslFileSystem.worldPath` | `distro` is fixed (`default` or a name), `restrictToDistro` is on, and the path names **another distro**'s share — a configuration fence, not a sandbox decision. With `distro: ''`/`auto` a UNC target is served by its own distro, so the fence has nothing foreign to refuse | set `distro` to `''`/`auto` (the default), or open a session in that distro. A wider permission does **not** lift it |
 | `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_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 selected 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 |
@@ -351,7 +351,7 @@ step with the checkout, and `pnpm run sync:windows` runs that script.
 | 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 |
+| Harness probes | [`test/probe/run.sh`](../test/probe/run.sh), `terminal.sh`, `sandbox-shell.sh`, `picker.sh`, `fs-routing.sh`, `missing-wsl.sh`, `sandbox-off.sh` | yes: Windows, WSL2, a mounted profile, and a linked checkout |
 | 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 |
@@ -416,6 +416,8 @@ 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/distro-route.ts          the pure distro-mode selector (pinned / workspace /
+                             default) shared by shell, fs, preflight and env
 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