dsh-plugin-wsl-env 0.15.0 → 0.17.0

package/cordis.patch.yml

@@ -36,17 +36,20 @@
 #      `wsl.exe -d <distro> --cd <linux dir>` for the directory the Session
 #      supplies. Ordinary `spawn()` — every command, the host ripgrep search,
 #      every other consumer — reaches the shipped implementation untouched;
-#   2. the controller is given the one shell profile it should resolve, so the
-#      window's default is a distro shell rather than `cmd.exe` inside a UNC
-#      workspace. Its shell menu is reduced to that single entry on purpose:
-#      shell discovery also runs against the root provider and receives no
-#      directory, so offering host executables there would advertise shells this
-#      terminal never starts.
+#   2. the controller is given the composition's default shell profile (the
+#      distro shell, so a directory-less launch lands in the distro rather than
+#      `cmd.exe` inside a UNC workspace) plus host candidates. The default must
+#      stay static — the controller resolves it without a Session — but the
+#      candidates make the shell menu honest: `wsl.exe` dedupes into the
+#      default's `wsl` kind, and `powershell`/`cmd` are launches this terminal
+#      really starts (host sessions run PowerShell outright, and a manually
+#      selected shell is titled after itself — the sanctioned bridge over the
+#      fixed tab title, see docs/UPSTREAM-TERMINAL-TITLE.md).
 #
 # Consequence: a terminal's EXECUTION WORLD follows the Session — a WSL-folder
 # session runs the distro's shell, a Windows-folder session runs PowerShell in
-# its own directory (`hostSessions` on `subprocess-wsl`) — while the shell menu
-# and the tab title stay the composition's single `WSL` profile, which no
+# its own directory (`hostSessions` on `subprocess-wsl`) — while the DEFAULT
+# entry and its title stay the composition's single `WSL` profile, which no
 # Session identity reaches. The title that implies is documented in
 # docs/LIMITATIONS.md and bridged upstream in docs/UPSTREAM-TERMINAL-TITLE.md.
 # ═════════════════════════════════════════════════════════════════════════════
@@ -60,7 +63,10 @@
       path: wsl.exe
       name: WSL
       args: []
-    shellCandidates: []
+    shellCandidates:
+      - wsl.exe
+      - powershell
+      - cmd
 
 - insert:
     - id: subprocess-wsl
@@ -191,7 +197,8 @@
     #      the distro's shell and fs (the realm is declared on the group);
     #   2. `tool-bash` is enabled and `tool-pwsh` disabled outright, where the
     #      shipped copy derives the choice from `process.platform`;
-    #   3. the identity: row `preset-wsl`, preset `wsl`, `order: 2`.
+    #   3. the identity and display metadata: row `preset-wsl`, preset `wsl`,
+    #      `name`/`description` for the mode selector, `order: 2`.
     # Regenerate it when an app update changes the preset: take
     # `packages/bundle/web-app/presets/standard.patch.yml` from the harness tree
     # the peer pins track and run `node scripts/build-preset-wsl.mjs <that
@@ -202,6 +209,12 @@
       name: '@deepseek-ai/dsh-agent-preset'
       config:
         id: wsl
+        # Display metadata: `wsl` is not a registry built-in id, so the mode
+        # selector falls back to the raw id and "no description" unless the
+        # declaration carries its own copy (registry policy: user-authored
+        # metadata is never localized — write it in the deployment language).
+        name: WSL 模式
+        description: 在 WSL 的 Linux 实例中打开项目工作区：命令执行、shell 脚本和文件访问均在 Linux 空间内完成，以获得全套 Linux shell 工具链，受限命令经 bubblewrap 沙箱隔离。
         order: 2
         plugins:
           - id: wsl-env

package/docs/ARCHITECTURE.md

@@ -3,7 +3,7 @@
 This file describes the plugin as it is today. It covers what the code does and
 where each piece lives. The reasoning behind the design, including the designs that
 were rejected, is recorded in [`CHANGELOG.md`](../CHANGELOG.md) and in
-[`archive/engineering-record.zh.md`](archive/engineering-record.zh.md).
+[`archive/engineering-record.zh.md`](https://github.com/Big-Dao/dsh-plugin-wsl-env/blob/main/docs/archive/engineering-record.zh.md).
 
 ## What "provider" means here
 
@@ -19,7 +19,7 @@ root-plane services, and adds three smaller integrations.
 | Service | Class | File | What it does |
 |---|---|---|---|
 | `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.fs` | `WslFileSystem` | [`lib/index.js`](../lib/index.js) | Serves WSL-routed file operations through the resident in-distro agent; 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 and git-snapshot spawns into the distro (see below). |
 
 `WslShellExecutor` extends the shipped `LocalBashExecutor`, and `WslFileSystem`
@@ -34,7 +34,7 @@ a subclass that routes by coordinate:
 
 | Service | Class | File | What it does |
 |---|---|---|---|
-| `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. |
+| `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 inside the distro (inotify where available, polling otherwise), 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. |
 
 The GUI file tree and previews keep the shipped `workspace-files` row. Its
 client half is the browser `file` resource provider the Sidebar previews need,
@@ -56,7 +56,7 @@ 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
+([`upstream/rfc-wsl-workspaces.md`](https://github.com/Big-Dao/dsh-plugin-wsl-env/blob/main/docs/upstream/rfc-wsl-workspaces.md)), and
 reaching the funnels without it would mean subclassing past module-internal
 functions.
 
@@ -64,7 +64,7 @@ functions.
 
 | 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/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 `find`, 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, 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. |
 
@@ -109,9 +109,15 @@ 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 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
+launches into the distro — the file-search tool's packaged ripgrep and git
+snapshot commands (each agent-first on the warm resident — protocol v6 carries
+a git call's stdin, and a one-shot call costs ~230 ms of `wsl.exe` startup
+against the resident's ~2 ms — with the one-shot `wsl.exe --exec` handle as
+the fallback when the agent is out). When the HOST has no git,
+`resolveExecutable` answers git with a distro sentinel path, and the snapshot
+command's discovery call (`rev-parse --show-toplevel ...`) routes too, its
+absolute-path output translated back into UNC form — so full WSL change review
+works without Windows git. 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
@@ -120,9 +126,11 @@ 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
 `powershell.exe` in its own directory. What still follows the app configuration
-is the shell menu and the tab title, both derived from the composition's single
-`WSL` shell profile — so a host session's tab reads `WSL` over a PowerShell
-process. See [LIMITATIONS.md](LIMITATIONS.md) and
+is the shell menu's DEFAULT entry and its title, both derived from the
+composition's single `WSL` shell profile — so a new tab reads `WSL` whatever it
+runs, including a host session's PowerShell. The menu also lists host
+candidates (`powershell`, `cmd`; `wsl.exe` dedupes into the default), and a
+manually selected shell is titled after itself. See [LIMITATIONS.md](LIMITATIONS.md) and
 [UPSTREAM-TERMINAL-TITLE.md](UPSTREAM-TERMINAL-TITLE.md).
 
 ## Path coordinates
@@ -146,14 +154,15 @@ The former Windows-side share backend (`substrate: "share"`) is retired — a
 profile carrying the value is refused at boot, and no file tool crosses the
 9p share. The substrate's facts:
 
-- **Reads, writes, identities** run on ext4 through the resident; symlinks and
-  mode bits are native (every identity is a distro-side `realpath`; the
-  publication rename is the kernel's).
+- **Reads, writes, identities** run through the resident on the filesystem
+  backing the distro path, typically ext4 for distro-owned files. Symlink and
+  mode behavior also depends on that filesystem; identities use distro-side
+  `realpath` and publication uses the kernel's rename or link.
 - **Guarded writes** carry their intent to the publication: a `createIfAbsent`
   publishes with a no-replace link, closing the check-then-write window for
   creates outright; an overwrite or edit carries its version into the write op
-  and the agent re-verifies it one syscall before the rename — a concurrent
-  writer wins, the stale write refuses with `FS_STALE_VERSION`.
+  and the agent re-verifies it before the rename. A mismatch returns
+  `FS_STALE_VERSION`, but a change after that check can still be overwritten.
 - **Kernel enforcement** is stage two: a mutation runs on a confined resident —
   one long-lived agent per (distro, policy), whose bwrap profile binds exactly
   what the mode grants — so the kernel refuses what the check would have, and a
@@ -245,12 +254,14 @@ 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.
 
-`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
+`maskWindowsDrive` or the `masked` and `disabled` `interopVisibility` stances
+shadow `/mnt` in confined commands, a narrowing rather than a closure. Other
+mounts and unrestricted file reads are not covered by the mask, and `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
+a Windows process. Either way the provider reports `partial`. Disabling WSL
+interop requires a separate distro-level change (`[interop] enabled=false` in
+`wsl.conf`); the `disabled` stance does not make that change. 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
@@ -338,35 +349,35 @@ and pnpm rewrites `link:\\wsl.localhost\...` into a broken
 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
+[`test/probe/sync-to-windows.sh`](https://github.com/Big-Dao/dsh-plugin-wsl-env/blob/main/test/probe/sync-to-windows.sh) keeps it in
 step with the checkout, and `pnpm run sync:windows` runs that script.
 
 ## Test layers
 
 | Layer | Location | Needs a harness |
 |---|---|---|
-| 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 |
+| Style and packaging checks | [`test/style.mjs`](https://github.com/Big-Dao/dsh-plugin-wsl-env/blob/main/test/style.mjs) | no |
+| Syntax pass | [`test/syntax.mjs`](https://github.com/Big-Dao/dsh-plugin-wsl-env/blob/main/test/syntax.mjs) | no |
+| Build consistency | [`test/build-freshness.mjs`](https://github.com/Big-Dao/dsh-plugin-wsl-env/blob/main/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`, `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 |
+| Sandbox probe | [`test/probe/sandbox.sh`](https://github.com/Big-Dao/dsh-plugin-wsl-env/blob/main/test/probe/sandbox.sh) | no; it applies the profile arguments directly |
+| Harness probes | [`test/probe/run.sh`](https://github.com/Big-Dao/dsh-plugin-wsl-env/blob/main/test/probe/run.sh), `terminal.sh`, `sandbox-shell.sh`, `interop-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`](https://github.com/Big-Dao/dsh-plugin-wsl-env/blob/main/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`](https://github.com/Big-Dao/dsh-plugin-wsl-env/blob/main/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 |
 
-`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)
+`pnpm test` runs `lint:style`, `lint:links`, `test:syntax`, `lint:build`,
+`lint:types` and `test:unit`, in that order.
+[`test/probe/run-all-when-closed.sh`](https://github.com/Big-Dao/dsh-plugin-wsl-env/blob/main/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) and
-[`test/provider.test.mjs`](../test/provider.test.mjs) import
+[`test/composition.test.mjs`](https://github.com/Big-Dao/dsh-plugin-wsl-env/blob/main/test/composition.test.mjs),
+[`test/fs.boot.test.mjs`](https://github.com/Big-Dao/dsh-plugin-wsl-env/blob/main/test/fs.boot.test.mjs),
+[`test/fsio-agent.test.mjs`](https://github.com/Big-Dao/dsh-plugin-wsl-env/blob/main/test/fsio-agent.test.mjs) and
+[`test/provider.test.mjs`](https://github.com/Big-Dao/dsh-plugin-wsl-env/blob/main/test/provider.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
@@ -376,9 +387,9 @@ Node 24 only — the threshold flags need Node 22.8. Node 20 is absent on purpos
 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 probe scripts share [`test/probe/env.sh`](https://github.com/Big-Dao/dsh-plugin-wsl-env/blob/main/test/probe/env.sh), which derives
 the Windows user, the distro name and the UNC spelling of the checkout from the
-machine, and [`test/probe/env.mjs`](../test/probe/env.mjs) for the Node-side probes.
+machine, and [`test/probe/env.mjs`](https://github.com/Big-Dao/dsh-plugin-wsl-env/blob/main/test/probe/env.mjs) for the Node-side probes.
 No probe carries a user name, and the YAML overlays are templates with `@NAME@`
 placeholders that the scripts substitute into generated copies.
 
@@ -431,9 +442,11 @@ src/fsio-text.ts             the peer's pure text mechanics, replicated pending
 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/native-agent.ts          native binary selection and preparation
 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/preflight.ts             session-start environment advisories
 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
@@ -441,6 +454,8 @@ src/sandbox.ts               the distro-side bwrap confinement shared by both
 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/session-runtime.ts       shared session runtime and agent lifecycle
+src/session-scope.ts         systemd scope creation and cleanup
 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
@@ -462,11 +477,11 @@ src/wsl.ts                   wsl.exe interop primitives (no DSH imports)
 - [`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
+- [`archive/engineering-record.zh.md`](https://github.com/Big-Dao/dsh-plugin-wsl-env/blob/main/docs/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) and
-  [`archive/README.en.md`](archive/README.en.md) are two English indexes of the
+- [`archive/README.md`](https://github.com/Big-Dao/dsh-plugin-wsl-env/blob/main/docs/archive/README.md) and
+  [`archive/README.en.md`](https://github.com/Big-Dao/dsh-plugin-wsl-env/blob/main/docs/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.

package/docs/COMPATIBILITY.md

@@ -0,0 +1,121 @@
+# Compatibility matrix
+
+Measured evidence for the support tiers in [`ROADMAP-1.0.md`](ROADMAP-1.0.md)
+(WSL-202). Every row below was executed on real WSL2 distros on one machine
+(x86_64, Windows 11, WSL 2, kernel 6.18) on **2026-10-26**, with the probe
+suite in [`test/probe/`](https://github.com/Big-Dao/dsh-plugin-wsl-env/tree/main/test/probe/) run from inside each distro against a
+fresh `--depth 1` clone. The aarch64 native agent is additionally executed per
+push under qemu in CI — see the `native packages` job in
+[`.github/workflows/ci.yml`](https://github.com/Big-Dao/dsh-plugin-wsl-env/blob/main/.github/workflows/ci.yml); VM-only by
+decision — see "Scope decisions" below.
+
+## The matrix
+
+| | Ubuntu (host, Tier 1) | Debian 13.5 | Fedora 44 | openSUSE Tumbleweed | Arch | Alpine 3.22 |
+|---|---|---|---|---|---|---|
+| init | systemd | systemd | systemd | systemd | systemd | busybox/OpenRC |
+| libc | glibc | glibc | glibc | glibc | glibc | musl |
+| bwrap | 0.12 | 0.12 | 0.12 | 0.13.1 | 0.13.1 | 0.12 |
+| node | 24 | 20.19 | 22.23 | 26.12 | 26.12 | 22.23 |
+| `sandbox.sh` | 14/14 | 14/14 | 14/14 | 14/14 | 14/14 | 15/15 |
+| `agent.sh` | 11/11 | 11/11 | 11/11 | 11/11 | 11/11 | 11/11 |
+| `exec.sh` | 5/5 | 5/5 | 5/5 | 5/5 | 5/5 | 5/5 |
+| `substrate.sh` | 8/8 | 8/8 | 8/8 | 8/8 | 8/8 | 8/8 |
+| `watch.sh` | 7/7 | 7/7 | 7/7 | 7/7 | 7/7 | 5/5 |
+| `session-sandbox.sh` | 10p 1s | 10p 1s | 3p 1r 1s | 3p 1r 1s | 3p 1r 1s | 3p 1d 1s |
+
+`p` = passed, `s` = skipped, `r` = race, `d` = declared limitation. Verdicts
+per row follow [`ROADMAP-1.0.md`](ROADMAP-1.0.md): Ubuntu, Debian, Fedora,
+openSUSE and Arch are **supported**; Alpine is **supported** for everything
+the non-systemd scope claims, with the narrower `sessionSandbox: auto` scope.
+
+**Debian is verified end to end**: the four harness-level probes
+(`run.sh`, `terminal.sh`, `picker.sh`, `fs-routing.sh`) also pass against a
+`wslfs-debian` profile (2026-10-26), on top of the distro-internal suite —
+the full stack, not just the in-distro half.
+
+## The found first-run trap: missing workspace root
+
+The Debian harness-level runs surfaced one real finding: **the confined
+resident refuses to start when the workspace root does not exist yet**. The
+bwrap profile binds the workspace root (`--bind <root> <root>`), bwrap
+requires the bind source to exist, and on a freshly imported distro the
+probe's workspace (`~/.dsh-fsprobe`) did not. `mkdir -p` of the root turns
+all ten failing steps green. Every prior Ubuntu run had the directory left
+over from earlier probes, which is why the trap never fired there. Any
+workspace whose directory is created lazily by its first write hits the same
+wall on a fresh distro. Fixed in aa12b49: the confined factory's prepare
+hook now creates the root (`mkdir -p`) before bwrap runs, the handshake
+failure carries the resident's stderr when one still occurs, and
+`substrate.sh` gained a fresh-root leg that spawns the resident against an
+absent workspace root on every run, verified on both Debian (glibc) and
+Alpine (musl).
+
+## The two explained differences
+
+- **`session-sandbox.sh`, background-survival leg (Fedora, openSUSE, Arch).**
+  The same systemd distros split on this check when driven through `wsl.exe`
+  (Debian passes, the other three do not): the probe allows a 0.5 s window and
+  the WSL session teardown races it. This is a probe-context artifact, not a
+  plugin claim — the plugin's background-process guarantee rides on systemd
+  transient scopes, whose legs the probe itself marks "run from a WSL
+  terminal". On Alpine the same leg fails **by declaration**: without systemd
+  the plugin does not promise background survival, and `sessionSandbox: auto`
+  reports the narrower per-command scope instead.
+
+- **`watch.sh` on Alpine (5/5).** Two checks exercised the inotify fast path
+  on the other distros and the polling fallback there; both behaviours are
+  shipped and both are asserted, so the lower count reflects fewer exercised
+  paths on that kernel/libc, not a weaker promise.
+
+## Tier 2 setup notes (the traps, so the next import does not rediscover them)
+
+| Distro | Setup that mattered |
+|---|---|
+| Debian | First launch can wedge before OOBE completes (`wsl.exe` exec and `--terminate` both hang). `wsl --terminate <distro>` once it is Stopped, then start as root to bypass OOBE. systemd is PID 1 out of the box. |
+| Alpine | Import the **minirootfs** tarball (`wsl --import`), not the standard/cloud images. Create a normal user and set `[user] default=…` in `/etc/wsl.conf` — the imported default is root, and a root agent writes 0600 files the probe user cannot read. Install `coreutils util-linux` (busybox `mktemp`/`ps` lack the used options) and `shadow` for `useradd`. |
+| Fedora / openSUSE / Arch | systemd PID 1 out of the box. openSUSE: `zypper --non-interactive` (the plain `-y` still prompts); Arch: `pacman -Sy --needed`. |
+
+Dependencies used everywhere: `bash bubblewrap git nodejs` (node 20–26 all
+pass; the plugin's `engines` floor applies to the harness host, not to probe
+nodes). The probe runner per distro, from inside the distro:
+
+```sh
+git clone --depth 1 https://github.com/Big-Dao/dsh-plugin-wsl-env.git
+cd dsh-plugin-wsl-env
+for p in sandbox session-sandbox agent exec substrate watch; do bash test/probe/$p.sh; done
+```
+
+The harness-level probes (`run.sh`, `terminal.sh`, `picker.sh`,
+`fs-routing.sh`) additionally need the app closed and the throwaway `wslfs`
+profile from `run.sh`'s header; on a second distro, copy that profile and set
+its `distro:` key.
+
+## Scope decisions
+
+- **aarch64 is verified in VM only; physical hardware is out of scope
+  (decided 2026-10-27).** The qemu-user CI leg executes the full 18-check
+  suite against the shipped binary on every push, which covers the agent's
+  own code paths; what only real hardware can add is exposure to aarch64
+  silicon's edge cases, which no Windows-on-ARM device in this project's
+  reach provides. The support table marks aarch64 "supported (executed in
+  CI)" and stays that way.
+
+- **Windows 10 is not separately verified (decided 2026-10-27).** The plugin's
+  entire surface is `wsl.exe`, the distro, and a UNC share; on WSL2 those are
+  the same components on Windows 10 as on Windows 11, and the version-specific
+  behaviour lives upstream in WSL itself, not in anything this plugin mounts.
+  Windows 11 is what the matrix above measures; a Win10 report is welcomed
+  through the support channels, but no separate verification is planned.
+
+## Not yet measured
+
+- Non-systemd session scopes driven by a real WSL terminal session (the
+  probe's skipped legs).
+- ~~Container images~~ — closed 2026-10-27: `test/agent-container.mjs` runs
+  the real shell agent inside `debian:stable-slim`, `alpine:3`, `fedora:latest`,
+  `opensuse/tumbleweed` and `archlinux` containers in CI (the
+  `agent-containers` job, one per image), 7 checks each — handshake with the
+  in-place digest, PING, EXEC with exit and both streams, SETENV, and the
+  presence of `sha256sum`/`base64` where the families actually differ
+  (busybox on Alpine vs coreutils elsewhere). 35/35 on first execution.