dsh-plugin-wsl-env 0.13.2 → 0.15.0

package/CHANGELOG.md

@@ -16,6 +16,148 @@ were part of the record.
 
 ## [Unreleased]
 
+## [0.15.0] - 2026-10-27
+
+The compatibility-matrix release: the support table and its evidence, the
+container and nightly legs that keep it current, two fresh-distro first-run
+fixes the run surfaced, and the interop stance in one configuration key.
+
+### Changed
+
+- **WSL-310: `scripts/bootstrap-import.sh` — a rootfs tarball becomes a
+  plugin-ready distro in one pass.** The command automates the import traps
+  the compatibility-matrix run documented: ELF-header architecture detection
+  (walking bin/ candidates, tolerant of the SIGPIPE an early-exiting dd
+  causes), `wsl --import` with an idempotent already-exists branch, the OOBE
+  wedge unstick, `/etc/wsl.conf` with `[boot] systemd` and `[user] default`
+  (an imported default-root distro makes the agent run as root), per-family
+  package-manager install including `systemd-sysv` — docker-export tarballs
+  strip `/sbin/init`, which is what broke the systemd boot chain — Linger as
+  root, and a final doctor pass. Verified on Debian 13.5 (systemd family:
+  every check green after the one mandated `wsl --shutdown`) and the Alpine
+  minirootfs (OpenRC: the non-systemd profile per WSL-201, systemd checks
+  reported as the declared degradation).
+
+### Fixed
+
+- **WSL-307: the confined resident's spawn preparation is now a named
+  self-heal checklist.** WSL-305 fixed the missing workspace root; the same
+  fresh-distro class has more members (no `sh`, no `base64`, no `sha256sum` —
+  minirootfs ships almost none of this). The confined factory's `prepare` now
+  runs one `sh -c` round trip whose first failing step names itself
+  (`workspace-root`, `interpreter`, `base64`, `sha256sum`), and the failure
+  reaches the caller as `spawn checklist step '<name>' failed in <distro>`
+  instead of a bare handshake code. The root rides as `$1`, never
+  interpolated into the script body. Verified end to end on Debian with an
+  absent workspace root: the checklist creates it and the first confined
+  write lands.
+
+### Fixed
+
+- **WSL-306: a directory name containing a newline lists as one exact row in
+  the picker.** The picker's distro-side listing was `ls -1ALp` line-parsed —
+  a newline in a name split into two rows or dropped out entirely. The
+  listing is now `find -L <dir> -maxdepth 1 -mindepth 1 -type d -print0`
+  (NUL-separated, `-type d` filtering in the distro where `-L` resolves
+  symlinks), sorted host-side. Busybox find supports every flag — verified on
+  alpine:3, debian:stable-slim and fedora:latest with a newline-named
+  fixture, and the picker probe now carries that fixture against the real
+  composition. The LIMITATIONS entry retires.
+
+### Changed
+
+- **The doctor gains a cross-distro sessions view (WSL-309) and marks live
+  residents (WSL-313's observable half).** A new survey after the runtime
+  checks lists every running distro with its `dsh-wsl-*.scope`, the scope
+  state and the resident pids the distro's own cgroup attests — the
+  concurrent-sessions coordinate routing made possible, made visible. The
+  agent.handshake check now notes when a live resident is already running in
+  the surveyed distro (and that its fresh probe cannot read that resident's
+  last error). The scope report records resident pids alongside the stale
+  verdict. Idle countdowns and lastError stay host-side — no IPC exists, and
+  the boundary is documented in LIMITATIONS.
+
+- **The real-machine probes now run nightly on the self-hosted runner.** A
+  schedule trigger (21:30 UTC) fires only the `probes` job — every hosted job
+  skips the event — so the Tier 1 "probe suite 100%, nightly" metric collects
+  its evidence on its own instead of waiting for a manual dispatch. A
+  dedicated concurrency group folds a backlog of missed nights (runner
+  offline) into the newest run. The probes still require the harness app to
+  be closed; a night where it was open reports honestly red.
+
+- **The shell agent now runs in CI inside the non-Ubuntu containers it
+  claims to support.** `test/agent-container.mjs` drives the real
+  `wsl-agent.sh` over the v5 frames inside `docker run` for
+  `debian:stable-slim`, `alpine:3`, `fedora:latest`, `opensuse/tumbleweed`
+  and `archlinux` — seven checks each: the HELLO handshake with the
+  in-place script digest, PING, EXEC with exit code and both streams, SETENV
+  reaching later commands, and the presence of `sha256sum`/`base64` where
+  the families actually differ (busybox on Alpine, coreutils elsewhere). The
+  `agent-containers` CI job runs one container per matrix leg. 35/35 on
+  first execution; this closes the container leg of WSL-202's acceptance.
+
+## [0.14.0] - 2026-10-27
+
+This release fixes the first-run trap the compatibility-matrix run found on a
+freshly imported distro, and ships the measured support table the run produced.
+
+### Fixed
+
+- **WSL-305: the confined resident now creates the workspace root before its
+  first spawn.** The bwrap profile binds the workspace root and bwrap refuses
+  a missing bind source, so on a freshly imported distro the first confined
+  write failed with a bare `FS_IO_ERROR: agent exited during handshake
+  (code=1)` and a misleading remedy. `agent-confined.js` gained a `prepare`
+  hook (workspace-write only — the only mode that binds the root) that runs
+  `mkdir -p` on the Linux-spelled root before bwrap runs, idempotently and
+  ignoring its own outcome: bwrap stays the authority, and a refusal still
+  reaches the caller. That refusal now carries evidence: the handshake
+  failure's message includes a bounded tail of the resident's stderr (the
+  half-day of diagnosis this cost came from it being swallowed). Three new
+  checks cover the prepare hook, its argv, and the stderr ride-on; a
+  fresh-root leg in `substrate.sh` exercises the absent-root spawn end to
+  end on a real distro.
+
+### Changed
+
+- **Debian is verified end to end, and the run found a first-run trap.**
+  The four harness-level probes pass against a `wslfs-debian` profile on a
+  freshly imported Debian 13.5, completing the full stack on top of the
+  distro-internal suite (`docs/COMPATIBILITY.md`). Getting there surfaced one
+  real finding: the confined resident refuses to start when the workspace
+  root does not exist yet — the bwrap profile binds the root, bwrap requires
+  the bind source to exist, and a fresh distro has nothing to bind. Creating
+  the root first turns all ten failing steps green; prior Ubuntu runs had it
+  left over from earlier probes. The finding is documented in the matrix page
+  with the suggested spawn-preparation fix.
+
+- **The compatibility matrix moves from prose to a measured page.**
+  `docs/COMPATIBILITY.md` records the WSL-202 evidence: six real WSL2 distros
+  (Ubuntu, Debian 13.5, Fedora 44, openSUSE Tumbleweed, Arch, Alpine 3.22)
+  executed the distro-internal probe suite on one machine on 2026-10-26, and
+  the page explains the two observed differences instead of hiding them — the
+  `session-sandbox` background-survival leg races WSL session teardown on
+  three systemd distros (probe artifact, not a plugin claim), and on Alpine
+  the same leg fails by declaration, because non-systemd distros get the
+  narrower `sessionSandbox: auto` scope exactly as P1.1/WSL-201 promises. The
+  page also records the per-distro import traps (Debian OOBE wedge, Alpine
+  minirootfs defaulting to root, busybox mktemp, zypper's interactive prompt)
+  and the reproduction commands. Not yet measured: real aarch64 hardware, the
+  container-image matrix.
+
+- **The aarch64 native agent is executed in CI, not only built.** The
+  `native packages` job installs qemu's user-mode emulator and binfmt
+  registration (`qemu-user` + `qemu-user-binfmt`; noble has no real
+  `qemu-user-static` package) and runs the full
+  18-check spike suite under qemu-user against both the freshly built aarch64
+  musl binary and the committed `agent/native/linux-aarch64/dsh-wsl-agent` —
+  the binary a Windows-on-ARM session would load. User-mode emulation
+  exercises every check (the static musl binary and the v5 frames are
+  host-OS-free), verified locally first: 18/18 under `qemu-aarch64`, with
+  `/proc/self/exe` resolving to the target so the HELLO digest binding holds
+  unchanged. This closes the "build-tested only" gap on WSL-202; a run on
+  real aarch64 hardware remains open.
+
 ## [0.13.2] - 2026-10-26
 
 This release tracks DeepSeek Harness `0.2.1-rc.3`: the peer declarations become

package/docs/CONFIGURATION.md

@@ -29,6 +29,7 @@ has its own table at the end of this page.
 | | `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) |
+| | `interopVisibility` | `visible` | the stance in one key (WSL-314): `visible` / `masked` / `disabled` — see the stance table below. Set at all, the stance takes precedence over the legacy `maskWindowsDrive` boolean (unset lets it answer); `disabled` masks in-session and the doctor's remedy prints the distro-level `[interop] line for the full closure (a config key does not write distro config) |
 | | `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 |

package/docs/LIMITATIONS.md

@@ -214,6 +214,17 @@ crosses the 9p share. What to know about the one substrate there is:
   the user scopes once; a scope created or stopped a moment later is not
   reflected. `--fix` runs the same sweep the session preflight uses.
 
+## The doctor's sessions table
+
+- **The sessions table shows distro-side facts only.** The cross-distro view
+  (`distro → scope → state → resident pids`) attests what the distro can see:
+  which scopes exist and which pids inside them are agent processes. A
+  resident's idle countdown and its `lastError` live in the host process that
+  owns it — there is no IPC channel from a plugin script to the app, so the
+  table cannot show them (`WSL-313`'s upstream ask). The agent.handshake
+  check notes a live resident's presence when the scope survey sees one, and
+  says that its own probe starts a fresh one.
+
 ## Session-start advisories
 
 - **There is no session-UI notice seam in DSH 0.2.1.** When a distro session
@@ -246,15 +257,12 @@ crosses the 9p share. What to know about the one substrate there is:
 ## The directory picker
 
 - The directory picker lists distro levels from inside the distro — the
-  resident's `ls -1ALp` in one round trip, a one-shot `wsl.exe --exec ls` when
-  it is out, never the 9p walk the host used to pay per entry. The listing is
-  line-parsed and only a line that ends in `/` becomes a row, so a directory
-  name containing a newline cannot be listed correctly: `ls` emits `a\nb` as
-  the two lines `a` and `b/`, and the picker offers the single row `b` at
-  `<parent>/b` — the part after the newline, a different directory or none at
-  all. A name that ends in a newline yields no row at all: the split leaves one
-  segment without a trailing `/` and one empty name, and the parser keeps
-  neither. `/` cannot appear in a name, so nothing else can split one.
+  resident's `find -L <dir> -maxdepth 1 -mindepth 1 -type d -print0` in one
+  round trip, a one-shot `wsl.exe --exec find` when it is out, never the 9p
+  walk the host used to pay per entry. Entries arrive NUL-separated, so a
+  directory name containing a newline lists as one exact row (WSL-306 retired
+  the `ls -1ALp` line parse that used to split such a name into two rows or
+  drop it).
 
 ## Terminals
 

package/docs/QUICKSTART.md

@@ -37,6 +37,17 @@ or an UNC path directly. The session's commands, file tools, terminal and previe
 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.
 
+![The directory picker listing a WSL distro's folders](screenshots/picker.png)
+
+The terminal panel runs in the same distro — `uname -a` answers with the
+distro's kernel, not Windows':
+
+![The GUI terminal running inside the distro](screenshots/terminal.png)
+
+And the Sidebar's preview renders WSL files in place:
+
+![The GUI preview rendering a WSL file](screenshots/preview.png)
+
 ## 4. Verify
 
 Ask for a command, e.g. `pwd && uname -a`. Expected: the Linux path and the
@@ -44,6 +55,13 @@ 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.
 
+The sandbox is enforced by the kernel, not a promise: the probe below runs the
+shipped bwrap profiles live — writes inside the workspace land, writes outside
+are refused with `EROFS`, and the strict profile hides `/mnt` entirely
+([`test/probe/sandbox.sh`](../test/probe/sandbox.sh)):
+
+![The sandbox probe: every expectation holds, the kernel refuses what the profile does not grant](screenshots/sandbox.png)
+
 ## Recipes
 
 Commands run in the model's session, inside the distro, from the workspace root.

package/lib/agent-confined.d.ts

@@ -1,4 +1,42 @@
 import { WslAgent } from "./agent.js";
+/**
+ * The resident's spawn checklist, as one `sh -c` body run in the distro.
+ *
+ * Steps, in order — the first failing step names itself on stderr and exits 1:
+ *
+ * - `workspace-root`: the bwrap profile binds the root (`--bind <root>
+ *   <root>`) and bwrap refuses a missing bind source, so `mkdir -p` it — on a
+ *   freshly imported distro the first write's workspace may not exist yet
+ *   (WSL-305).
+ * - `interpreter`: the resident runs as `sh <script>`; a distro without `sh`
+ *   is not a distro this plugin can serve.
+ * - `base64` and `sha256sum`: the agent script's frames and its HELLO digest
+ *   read through them; coreutils provides both on the glibc families and
+ *   busybox applets on Alpine (verified in the container matrix).
+ *
+ * The root rides as `$1`, so the body carries no interpolated path — the
+ * same body is safe for any (distro, root) pair.
+ *
+ * @param root - the Linux-spelled workspace root.
+ * @returns the `sh -c` body.
+ */
+export declare function spawnChecklistScript(root: string): string;
+/**
+ * Run the spawn checklist in the distro: one `wsl.exe --exec sh -c` round
+ * trip, the workspace root as `$1`. Resolves when every step passes;
+ * rejects with the named failing step when one does not — the resident
+ * would exit during its handshake with a bare code 1 and no hint (WSL-305),
+ * and a name beats a code.
+ *
+ * @param options - the transport, distro, root, and an injectable run.
+ * @returns resolves when the checklist passes.
+ */
+export declare function runSpawnChecklist({ wslPath, distro, root, runFn }: {
+    wslPath: string;
+    distro: string;
+    root: string;
+    runFn?: (argv: string[]) => Promise<unknown>;
+}): Promise<void>;
 /** One confinement request. */
 export interface ConfinedAgentRequest {
     /** The distro to run in. */

package/lib/agent-confined.js

@@ -36,6 +36,67 @@ import { toLinuxPath } from "./paths.js";
 import { agentScriptDigest, agentScriptPath } from "./agent-shared.js";
 import { WslAgent } from "./agent.js";
 const confinedAgents = new Map();
+/**
+ * The resident's spawn checklist, as one `sh -c` body run in the distro.
+ *
+ * Steps, in order — the first failing step names itself on stderr and exits 1:
+ *
+ * - `workspace-root`: the bwrap profile binds the root (`--bind <root>
+ *   <root>`) and bwrap refuses a missing bind source, so `mkdir -p` it — on a
+ *   freshly imported distro the first write's workspace may not exist yet
+ *   (WSL-305).
+ * - `interpreter`: the resident runs as `sh <script>`; a distro without `sh`
+ *   is not a distro this plugin can serve.
+ * - `base64` and `sha256sum`: the agent script's frames and its HELLO digest
+ *   read through them; coreutils provides both on the glibc families and
+ *   busybox applets on Alpine (verified in the container matrix).
+ *
+ * The root rides as `$1`, so the body carries no interpolated path — the
+ * same body is safe for any (distro, root) pair.
+ *
+ * @param root - the Linux-spelled workspace root.
+ * @returns the `sh -c` body.
+ */
+export function spawnChecklistScript(root) {
+    return [
+        'mkdir -p -- "$1" || { echo workspace-root >&2; exit 1; }',
+        "command -v sh >/dev/null || { echo interpreter >&2; exit 1; }",
+        "command -v base64 >/dev/null || { echo base64 >&2; exit 1; }",
+        "command -v sha256sum >/dev/null || { echo sha256sum >&2; exit 1; }",
+    ].join("\n");
+}
+/**
+ * Run the spawn checklist in the distro: one `wsl.exe --exec sh -c` round
+ * trip, the workspace root as `$1`. Resolves when every step passes;
+ * rejects with the named failing step when one does not — the resident
+ * would exit during its handshake with a bare code 1 and no hint (WSL-305),
+ * and a name beats a code.
+ *
+ * @param options - the transport, distro, root, and an injectable run.
+ * @returns resolves when the checklist passes.
+ */
+export async function runSpawnChecklist({ wslPath, distro, root, runFn }) {
+    const run = runFn ?? (async (argv) => {
+        const { runCapture } = await import("./wsl.js");
+        return runCapture([wslPath, "-d", distro, ...argv]);
+    });
+    let detail = "";
+    try {
+        await run(["--exec", "sh", "-c", spawnChecklistScript(root), "sh", root]);
+    }
+    catch (error) {
+        // runCapture rejects on the checklist's non-zero exit with the stderr
+        // folded into the message — where the failing step named itself.
+        detail = String(error).trim();
+    }
+    const named = /workspace-root|interpreter|base64|sha256sum/.exec(detail)?.[0];
+    if (named !== undefined) {
+        throw new Error(`spawn checklist step '${named}' failed in ${distro}`);
+    }
+    if (detail !== "") {
+        throw new Error(`spawn checklist could not run in ${distro}: ${detail.slice(0, 200)}`);
+    }
+}
 /**
  * The confined agent for one distro and one resolved policy, created on first
  * use and shared for the process lifetime. A success is remembered; a failed
@@ -48,6 +109,7 @@ export function confinedAgent({ distro, wslPath = "wsl.exe", policy, maskWindows
     const key = `${wslPath}\0${distro}\0${policy.mode}\0${policy.workspaceRoot}\0${maskWindowsDrive ? "masked" : "visible"}\0${realTmp ? "real" : "ephemeral"}`;
     let agent = confinedAgents.get(key);
     if (agent === undefined) {
+        const linuxRoot = toLinuxPath(policy.workspaceRoot, { distro });
         agent = new WslAgent({
             distro,
             wslPath,
@@ -58,7 +120,15 @@ export function confinedAgent({ distro, wslPath = "wsl.exe", policy, maskWindows
             // `wsl.exe --exec` and the `sh <script>` pair (`lib/agent.js`'s
             // `spawnDefault`). Both confinement sites share that assembly in
             // `lib/bwrap.js`, whose module doc records what happened when they did not.
-            argvPrefix: bwrapArgvPrefix({ mode: policy.mode, workspaceRoot: toLinuxPath(policy.workspaceRoot, { distro }) }, { maskWindowsDrive, realTmp }),
+            argvPrefix: bwrapArgvPrefix({ mode: policy.mode, workspaceRoot: linuxRoot }, { maskWindowsDrive, realTmp }),
+            // workspace-write is the only mode that binds the workspace root, and
+            // bwrap refuses a missing bind source (WSL-305): on a freshly imported
+            // distro the first write's workspace may not exist yet, and the resident
+            // used to exit during its handshake with a bare code 1. Create the root
+            // before the first spawn; every later start re-runs it harmlessly.
+            prepare: policy.mode === "workspace-write"
+                ? () => runSpawnChecklist({ wslPath, distro, root: linuxRoot }).then(() => undefined)
+                : undefined,
         });
         confinedAgents.set(key, agent);
     }

package/lib/agent.js

@@ -352,6 +352,14 @@ export class WslAgent {
             // reflected in the state/pending requests; an unhandled stream error
             // would crash the host process instead.
             child.stdin?.on("error", () => { });
+            // The resident's own stderr is the only diagnostic a handshake failure
+            // carries (bwrap's refusal names the missing bind source, a libc
+            // mismatch names itself); surface a bounded tail on the lastError
+            // instead of leaving the caller a bare exit code.
+            let hsErr = "";
+            child.stderr?.on("data", (chunk) => {
+                hsErr += String(chunk);
+            });
             child.on("exit", (code, signalName) => {
                 if (!current()) {
                     // A stale child's exit: release its pipes, but never touch the
@@ -360,7 +368,7 @@ export class WslAgent {
                     return;
                 }
                 if (this.state === "starting") {
-                    this.lastError = `agent exited during handshake (code=${code} signal=${signalName ?? "none"})`;
+                    this.lastError = `agent exited during handshake (code=${code} signal=${signalName ?? "none"})${hsErr ? ` stderr=${hsErr.trim().slice(-400)}` : ""}`;
                     settleStart(new Error(this.lastError));
                 }
                 this.handleProcessExit(child, code, signalName);

package/lib/index.d.ts

@@ -83,6 +83,21 @@ export type WslExecSpec = ShellExecSpec & {
  * wrappers, so they are spelled as their `.get()` shape (the reading
  * {@link configuredCwd} and `hostCwd` perform).
  */
+/**
+ * The effective `/mnt` mask for a config: `interopVisibility` is the stance
+ * key (WSL-314) and takes precedence whenever it names a stance; the legacy
+ * `maskWindowsDrive` boolean answers only when the stance key is left at its
+ * `visible` default. `disabled` masks in-session — the belt — while the
+ * distro-level closure (`[interop] enabled=false` + `wsl --shutdown`)
+ * remains a documented, user-applied step a config key must not perform.
+ *
+ * @param config - anything carrying the two keys.
+ * @returns whether confined profiles shadow `/mnt`.
+ */
+export declare function effectiveMaskWindowsDrive(config: {
+    interopVisibility?: "visible" | "masked" | "disabled";
+    maskWindowsDrive?: boolean;
+}): boolean;
 export interface WslShellExecutorConfig {
     /** The pinned distro; empty means WSL's default. */
     distro: string;
@@ -96,6 +111,8 @@ export interface WslShellExecutorConfig {
     sandbox: boolean;
     /** Whether confined profiles mask `/mnt`. */
     maskWindowsDrive: boolean;
+    /** The interop stance; set at all, it takes precedence over `maskWindowsDrive`. */
+    interopVisibility?: "visible" | "masked" | "disabled";
     /** The volatile default workdir. */
     cwd: {
         get(): string | undefined;
@@ -218,6 +235,26 @@ export declare class WslShellExecutor extends LocalBashExecutor {
          * complete closure is distro-level: `[interop] enabled=false` in
          * `wsl.conf`.
          */
+        /**
+         * The interop stance in one key (WSL-314), expanding to the per-key
+         * values the measured matrix documents:
+         *
+         * - `visible` (default) — nothing masked; a confined command can read
+         *   `/mnt` and launch Windows executables through interop, which escapes
+         *   the Linux sandbox entirely.
+         * - `masked` — `maskWindowsDrive: true`: `/mnt` is shadowed with an empty
+         *   tmpfs; the drive's files and executables are unreachable (binfmt can
+         *   still run a workspace-written .exe, so enforcement stays `partial`).
+         * - `disabled` — `masked`, plus the distro-level closure: `[interop]
+         *   enabled=false` in `/etc/wsl.conf` + `wsl --shutdown`, which the
+         *   doctor's remedy prints as copy-paste (a config key does not write
+         *   distro config; enforcement is the kernel's, not the schema's).
+         *
+         * When set at all it takes precedence over the legacy
+         * `maskWindowsDrive` boolean below (unset — the default — lets that
+         * boolean answer); the boolean remains for existing profiles.
+         */
+        interopVisibility: z<"masked" | "visible" | "disabled", "masked" | "visible" | "disabled", "plain">;
         maskWindowsDrive: z<boolean, boolean, "defined">;
         /**
          * Default workdir for a request that names none; accepts `/home/andy/proj`,
@@ -296,6 +333,26 @@ export declare class WslShellExecutor extends LocalBashExecutor {
          * complete closure is distro-level: `[interop] enabled=false` in
          * `wsl.conf`.
          */
+        /**
+         * The interop stance in one key (WSL-314), expanding to the per-key
+         * values the measured matrix documents:
+         *
+         * - `visible` (default) — nothing masked; a confined command can read
+         *   `/mnt` and launch Windows executables through interop, which escapes
+         *   the Linux sandbox entirely.
+         * - `masked` — `maskWindowsDrive: true`: `/mnt` is shadowed with an empty
+         *   tmpfs; the drive's files and executables are unreachable (binfmt can
+         *   still run a workspace-written .exe, so enforcement stays `partial`).
+         * - `disabled` — `masked`, plus the distro-level closure: `[interop]
+         *   enabled=false` in `/etc/wsl.conf` + `wsl --shutdown`, which the
+         *   doctor's remedy prints as copy-paste (a config key does not write
+         *   distro config; enforcement is the kernel's, not the schema's).
+         *
+         * When set at all it takes precedence over the legacy
+         * `maskWindowsDrive` boolean below (unset — the default — lets that
+         * boolean answer); the boolean remains for existing profiles.
+         */
+        interopVisibility: z<"masked" | "visible" | "disabled", "masked" | "visible" | "disabled", "plain">;
         maskWindowsDrive: z<boolean, boolean, "defined">;
         /**
          * Default workdir for a request that names none; accepts `/home/andy/proj`,

package/lib/index.js

@@ -159,6 +159,29 @@ function wslWritableRoots(policy, distro) {
     }
     return [...roots];
 }
+/**
+ * The WSL shell executor's validated config — the keys of
+ * {@link WslShellExecutor.Config}, which the upstream `LocalBashExecutor`
+ * config type does not know. The seven volatile fields arrive as live
+ * wrappers, so they are spelled as their `.get()` shape (the reading
+ * {@link configuredCwd} and `hostCwd` perform).
+ */
+/**
+ * The effective `/mnt` mask for a config: `interopVisibility` is the stance
+ * key (WSL-314) and takes precedence whenever it names a stance; the legacy
+ * `maskWindowsDrive` boolean answers only when the stance key is left at its
+ * `visible` default. `disabled` masks in-session — the belt — while the
+ * distro-level closure (`[interop] enabled=false` + `wsl --shutdown`)
+ * remains a documented, user-applied step a config key must not perform.
+ *
+ * @param config - anything carrying the two keys.
+ * @returns whether confined profiles shadow `/mnt`.
+ */
+export function effectiveMaskWindowsDrive(config) {
+    if (config.interopVisibility !== undefined)
+        return config.interopVisibility !== "visible";
+    return config.maskWindowsDrive === true;
+}
 const inheritedSpawnSpec = LocalBashExecutor.prototype.spawnSpec;
 /**
  * How long an `auto` distro that could not host a session runtime stays
@@ -257,6 +280,26 @@ export class WslShellExecutor extends LocalBashExecutor {
          * complete closure is distro-level: `[interop] enabled=false` in
          * `wsl.conf`.
          */
+        /**
+         * The interop stance in one key (WSL-314), expanding to the per-key
+         * values the measured matrix documents:
+         *
+         * - `visible` (default) — nothing masked; a confined command can read
+         *   `/mnt` and launch Windows executables through interop, which escapes
+         *   the Linux sandbox entirely.
+         * - `masked` — `maskWindowsDrive: true`: `/mnt` is shadowed with an empty
+         *   tmpfs; the drive's files and executables are unreachable (binfmt can
+         *   still run a workspace-written .exe, so enforcement stays `partial`).
+         * - `disabled` — `masked`, plus the distro-level closure: `[interop]
+         *   enabled=false` in `/etc/wsl.conf` + `wsl --shutdown`, which the
+         *   doctor's remedy prints as copy-paste (a config key does not write
+         *   distro config; enforcement is the kernel's, not the schema's).
+         *
+         * When set at all it takes precedence over the legacy
+         * `maskWindowsDrive` boolean below (unset — the default — lets that
+         * boolean answer); the boolean remains for existing profiles.
+         */
+        interopVisibility: z.union(["visible", "masked", "disabled"]),
         maskWindowsDrive: z.boolean().default(false),
         /**
          * Default workdir for a request that names none; accepts `/home/andy/proj`,
@@ -307,7 +350,7 @@ export class WslShellExecutor extends LocalBashExecutor {
         this.resolvedHomes = new Map();
         this.mode = config.sandbox ? ctx.sandboxPolicy.defaultMode : undefined;
         this.sandbox = config.sandbox
-            ? new WslSandbox({ wslPath: config.wslPath, maskWindowsDrive: config.maskWindowsDrive })
+            ? new WslSandbox({ wslPath: config.wslPath, maskWindowsDrive: effectiveMaskWindowsDrive(config) })
             : undefined;
         this.processFacts = new Map();
         this.sessionRuntimes = sessionRuntimes;
@@ -456,7 +499,7 @@ export class WslShellExecutor extends LocalBashExecutor {
             return undefined;
         const mode = policy?.mode ?? "danger-full-access";
         const workspaceRoot = policy?.workspaceRoot ?? (configuredCwd(this.config) || resolved.workdir);
-        const key = SessionRuntimes.key({ distro, workspaceRoot, mode, maskWindowsDrive: config.maskWindowsDrive });
+        const key = SessionRuntimes.key({ distro, workspaceRoot, mode, maskWindowsDrive: effectiveMaskWindowsDrive(config) });
         const held = this.sessionRuntimeEntries.get(key);
         if (held !== undefined)
             return held;
@@ -465,7 +508,7 @@ export class WslShellExecutor extends LocalBashExecutor {
             wslPath: config.wslPath,
             workspaceRoot,
             mode,
-            maskWindowsDrive: config.maskWindowsDrive,
+            maskWindowsDrive: effectiveMaskWindowsDrive(config),
         });
         this.sessionRuntimeEntries.set(key, entry);
         return entry;

package/lib/listing.d.ts

@@ -83,32 +83,39 @@ export declare function boundedInsert<T extends {
 /**
  * The distro-side argv one picker level is listed with.
  *
- * `-1` is one entry per line, `-A` keeps dot-entries but drops `.` and `..`,
  * `-L` follows symlinks so a link to a directory reports as a directory and a
  * broken link drops out (exactly what the per-entry `stat` the host path used
- * to pay one 9p round trip for), and `-p` marks directories with the trailing
- * `/` the parser keys on.
+ * to pay one 9p round trip for); `-maxdepth 1` keeps the listing to one level;
+ * `-mindepth 1` drops the start point the way `ls -A` dropped `.` and `..`;
+ * `-type d` keeps only enterable rows; `-print0` separates entries with NUL —
+ * a filename containing a newline arrives whole instead of splitting into two
+ * rows, which is the bug that retired the `ls -1ALp` line parse (WSL-306).
+ * `find` is unsorted; the parser sorts.
+ *
+ * Busybox find (Alpine) supports every flag here — verified on alpine:3,
+ * debian:stable-slim and fedora:latest with a newline-named fixture.
  *
  * @param linuxDir - the absolute Linux directory to list.
  * @returns the argv for the agent or a `wsl.exe --exec` launch.
  */
-export declare function lsListingArgv(linuxDir: string): string[];
+export declare function dirListingArgv(linuxDir: string): string[];
 /**
- * Parse one `ls -1ALp` listing into the picker's rows.
+ * Parse one `find -print0` listing into the picker's rows.
  *
- * A line is a row when it ends with `/` — a directory, or a symlink `-L`
- * resolved to one; files and dangling links are skipped, matching the host
- * path's behaviour. The parse reads the listing as UTF-8 lines, so a filename
- * containing a newline would split into two rows — the same limitation class
- * the one-shot transport has always had, accepted here with the 9p walk it
- * replaces.
+ * Entries arrive NUL-separated as `<linuxDir>/<name>`; the linuxDir prefix is
+ * stripped to recover the bare name (the root listing's `/name` form
+ * included). `find` is unsorted, so the names are sorted host-side — a
+ * deterministic code-point order, which is what the picker shows. The first
+ * `maxEntries` names become rows; a level with more is flagged truncated.
  *
  * @param stdout - the listing's raw stdout.
+ * @param linuxDir - the absolute Linux directory that was listed (the argv's
+ * own spelling — the prefix stripped from every entry).
  * @param parent - the listed directory, in the UNC form the rows carry.
  * @param maxEntries - the row bound; a level with more is flagged truncated.
  * @returns the first `maxEntries` rows and whether the level had more.
  */
-export declare function parseLsListing(stdout: string | Buffer, parent: string, maxEntries: number): {
+export declare function parseDirListing(stdout: string | Buffer, linuxDir: string, parent: string, maxEntries: number): {
     rows: ListingRow[];
     truncated: boolean;
 };

package/lib/listing.js

@@ -126,42 +126,57 @@ export function boundedInsert(window, candidate, keep) {
 /**
  * The distro-side argv one picker level is listed with.
  *
- * `-1` is one entry per line, `-A` keeps dot-entries but drops `.` and `..`,
  * `-L` follows symlinks so a link to a directory reports as a directory and a
  * broken link drops out (exactly what the per-entry `stat` the host path used
- * to pay one 9p round trip for), and `-p` marks directories with the trailing
- * `/` the parser keys on.
+ * to pay one 9p round trip for); `-maxdepth 1` keeps the listing to one level;
+ * `-mindepth 1` drops the start point the way `ls -A` dropped `.` and `..`;
+ * `-type d` keeps only enterable rows; `-print0` separates entries with NUL —
+ * a filename containing a newline arrives whole instead of splitting into two
+ * rows, which is the bug that retired the `ls -1ALp` line parse (WSL-306).
+ * `find` is unsorted; the parser sorts.
+ *
+ * Busybox find (Alpine) supports every flag here — verified on alpine:3,
+ * debian:stable-slim and fedora:latest with a newline-named fixture.
  *
  * @param linuxDir - the absolute Linux directory to list.
  * @returns the argv for the agent or a `wsl.exe --exec` launch.
  */
-export function lsListingArgv(linuxDir) {
-    return ["ls", "-1ALp", "--", linuxDir];
+export function dirListingArgv(linuxDir) {
+    return ["find", "-L", linuxDir, "-maxdepth", "1", "-mindepth", "1", "-type", "d", "-print0"];
 }
 /**
- * Parse one `ls -1ALp` listing into the picker's rows.
+ * Parse one `find -print0` listing into the picker's rows.
  *
- * A line is a row when it ends with `/` — a directory, or a symlink `-L`
- * resolved to one; files and dangling links are skipped, matching the host
- * path's behaviour. The parse reads the listing as UTF-8 lines, so a filename
- * containing a newline would split into two rows — the same limitation class
- * the one-shot transport has always had, accepted here with the 9p walk it
- * replaces.
+ * Entries arrive NUL-separated as `<linuxDir>/<name>`; the linuxDir prefix is
+ * stripped to recover the bare name (the root listing's `/name` form
+ * included). `find` is unsorted, so the names are sorted host-side — a
+ * deterministic code-point order, which is what the picker shows. The first
+ * `maxEntries` names become rows; a level with more is flagged truncated.
  *
  * @param stdout - the listing's raw stdout.
+ * @param linuxDir - the absolute Linux directory that was listed (the argv's
+ * own spelling — the prefix stripped from every entry).
  * @param parent - the listed directory, in the UNC form the rows carry.
  * @param maxEntries - the row bound; a level with more is flagged truncated.
  * @returns the first `maxEntries` rows and whether the level had more.
  */
-export function parseLsListing(stdout, parent, maxEntries) {
-    const rows = [];
-    let truncated = false;
-    for (const line of String(stdout).split("\n")) {
-        if (!line.endsWith("/"))
+export function parseDirListing(stdout, linuxDir, parent, maxEntries) {
+    const prefix = linuxDir === "/" ? "/" : `${linuxDir}/`;
+    const names = [];
+    for (const entry of String(stdout).split("\0")) {
+        if (entry.length === 0)
             continue;
-        const name = line.slice(0, -1);
-        if (name.length === 0)
+        const name = entry.startsWith(prefix) ? entry.slice(prefix.length) : entry;
+        // A defensive guard, not an expected shape: `-maxdepth 1` output is
+        // always `<dir>/<name>`, so a stray separator means a broken listing.
+        if (name.length === 0 || name.includes("/"))
             continue;
+        names.push(name);
+    }
+    names.sort();
+    const rows = [];
+    let truncated = false;
+    for (const name of names) {
         if (rows.length === maxEntries) {
             truncated = true;
             break;

package/lib/picker.js

@@ -53,7 +53,7 @@ import { join, resolve } from "node:path";
 import z from "@deepseek-ai/schemastery";
 import { DirectoryPicker, DirectoryPickerError } from "@deepseek-ai/dsh-host-directory-picker";
 import { UNC_PROVIDER_ROOT, distroRoot, isProviderRoot, isWslUnc, uncToPosix } from "./paths.js";
-import { breadcrumbs, boundedInsert, fullyQualified, lsListingArgv, parseLsListing } from "./listing.js";
+import { breadcrumbs, boundedInsert, dirListingArgv, fullyQualified, parseDirListing } from "./listing.js";
 import { listDistros, linuxHome, runCapture } from "./wsl.js";
 import { sharedAgent } from "./agent-shared.js";
 import { AgentUnavailableError } from "./agent-errors.js";
@@ -321,7 +321,7 @@ export class WslDirectoryPicker extends DirectoryPicker {
         try {
             const result = await sharedAgent(parsed.distro).exec({
                 cwd: linuxDir,
-                argv: lsListingArgv(linuxDir),
+                argv: dirListingArgv(linuxDir),
                 timeoutMs: 15_000,
                 signal,
             });
@@ -335,13 +335,13 @@ export class WslDirectoryPicker extends DirectoryPicker {
             if (!(error instanceof AgentUnavailableError))
                 throw error;
             try {
-                stdout = await runCapture([this.config.wslPath, "-d", parsed.distro, "--cd", linuxDir, "--exec", ...lsListingArgv(linuxDir)], signal);
+                stdout = await runCapture([this.config.wslPath, "-d", parsed.distro, "--cd", linuxDir, "--exec", ...dirListingArgv(linuxDir)], signal);
             }
             catch (fallbackError) {
                 throw new DirectoryPickerError("directory-unreadable", target, `cannot list ${target}: ${messageOf(fallbackError)}`);
             }
         }
-        return parseLsListing(stdout, target, this.config.maxEntries);
+        return parseDirListing(stdout, linuxDir, target, this.config.maxEntries);
     }
     /**
      * List one Windows level with the host's own walk — native I/O on a native

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-plugin-wsl-env",
-  "version": "0.13.2",
+  "version": "0.15.0",
   "description": "让 DeepSeek Harness 以 WSL 子系统作为会话的执行环境：shell、文件读写与命令执行均在子系统内完成，目录选择器与 GUI 终端同样定位到子系统路径，并通过子系统内的 bubblewrap 对命令进行沙箱隔离",
   "keywords": [
     "deepseek-harness",

package/scripts/doctor.mjs

@@ -36,6 +36,7 @@ import { fileURLToPath } from "node:url";
 import { parseDistroList } from "../lib/wsl.js";
 import { AGENT_NAME, PROTOCOL_VERSION } from "../lib/agent-protocol.js";
 import { sessionScopeSweepScript } from "../lib/session-scope.js";
+import { parseListeningPorts, procNetScript } from "../lib/ports.js";
 
 const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 const WSL = "wsl.exe";
@@ -63,10 +64,10 @@ const STALE_SCOPE_REPORT = [
   '  if [ -n "$cg" ] && [ -r "/sys/fs/cgroup$cg/cgroup.procs" ]; then',
   '    while read -r pid; do',
   '      [ -n "$pid" ] || continue',
-  "      if tr '\\0' ' ' < \"/proc/$pid/cmdline\" 2>/dev/null | grep -q -e 'wsl-agent.sh' -e 'dsh-wsl-agent'; then alive=1; break; fi",
+  "      if tr '\\0' ' ' < \"/proc/$pid/cmdline\" 2>/dev/null | grep -q -e 'wsl-agent.sh' -e 'dsh-wsl-agent'; then alive=1; pids=\"$pids $pid\"; fi",
   '    done < "/sys/fs/cgroup$cg/cgroup.procs"',
   "  fi",
-  '  echo "$unit $([ "$alive" -eq 1 ] && echo active || echo stale)"',
+  '  echo "$unit $([ "$alive" -eq 1 ] && echo active || echo stale) pids:${pids:-none}"',
   "done",
 ].join("\n");
 /** The agent-cache inventory: one `state digest` line per cached binary. */
@@ -385,6 +386,14 @@ async function main(options) {
     check("agent.cache", bad > 0 ? "warn" : "ok", "Agent cache", `${entries.length} cached binary(ies)${bad > 0 ? `, ${bad} not executable` : ""}`, bad > 0 ? `rm -rf ~/.cache/dsh-wsl/agent inside "${distro}"; the next command repopulates it` : undefined);
   }
 
+  const scopes = (await inDistro(distro, STALE_SCOPE_REPORT)).stdout.trim();
+  const scopeLines = scopes === "none" || scopes.length === 0 ? [] : scopes.split(/\r?\n/);
+  const stale = scopeLines.filter((line) => /\sstale(\s|$)/.test(line)).length;
+  const livePids = scopeLines.flatMap((line) => {
+    const m = /\spids:([0-9 ]+)$/.exec(line);
+    if (m === null) return [];
+    return (m[1] ?? "").trim().split(/\s+/).filter((p) => p.length > 0);
+  });
   // ---- resident handshake --------------------------------------------------
   const agentScript = join(ROOT, "agent", "wsl-agent.sh");
   if (!agentScript.startsWith("/")) {
@@ -394,8 +403,11 @@ async function main(options) {
   } else {
     const handshake = await probeResident(distro, agentScript);
     if (handshake.ok) {
+      const live = livePids.length > 0
+        ? `; a live resident (pid${livePids.length > 1 ? "s" : ""} ${livePids.join(", ")}) is already running in this distro — this check starts a fresh one, which cannot read its last error`
+        : "";
       check("agent.handshake", handshake.digestMatches ? "ok" : "fail", "Agent handshake",
-        `pid ${handshake.pid}, protocol ${PROTOCOL_VERSION}, digest ${handshake.digestMatches ? "matches" : "MISMATCH — the distro reads a different script than this package"}`,
+        `pid ${handshake.pid}, protocol ${PROTOCOL_VERSION}, digest ${handshake.digestMatches ? "matches" : "MISMATCH — the distro reads a different script than this package"}${live}`,
         handshake.digestMatches ? undefined : "resync the runtime copy (pnpm run sync:windows), then restart the app");
     } else {
       check("agent.handshake", "fail", "Agent handshake", handshake.detail, "restart the DSH app; if it persists, delete ~/.cache/dsh-wsl/agent inside the distro and rerun the doctor");
@@ -403,13 +415,75 @@ async function main(options) {
   }
 
   // ---- stale session scopes ------------------------------------------------
-  const scopes = (await inDistro(distro, STALE_SCOPE_REPORT)).stdout.trim();
-  const scopeLines = scopes === "none" || scopes.length === 0 ? [] : scopes.split(/\r?\n/);
-  const stale = scopeLines.filter((line) => line.endsWith(" stale")).length;
   if (scopeLines.length === 0) check("runtime.scopes", "info", "Session scopes", "none (no user manager, or none left behind)");
   else if (stale === 0) check("runtime.scopes", "ok", "Session scopes", `${scopeLines.length} live, none stale`);
   else check("runtime.scopes", "warn", "Session scopes", `${stale} stale of ${scopeLines.length}`, "--fix stops them (the same sweep the session preflight runs); they are safe to stop when no agent process is inside");
 
+  // ---- sessions across running distros (WSL-309) ----------------------------
+  // The single-distro checks above answer "is this distro healthy?"; this
+  // survey answers "what is running right now, everywhere?" — the concurrent
+  // sessions coordinate routing makes possible, made visible. Idle timers are
+  // the host process's private state and stay out: a scope's presence and its
+  // resident pids are the facts the distro side can attest.
+  // The distro lists both surveys share: `run` settles an object
+  // ({ ok, stdout, code }); `-q` prints plain names, and the running list's
+  // header is dropped by the intersection with them. The default distro
+  // carries a localized marker ("ubuntu (默认值)" / "ubuntu (default)") —
+  // strip a trailing parenthesized note before the intersection.
+  const distroNames = ((await run([WSL, "--list", "-q"])).stdout ?? "").split(/\r?\n/).map((line) => line.trim()).filter((line) => line.length > 0);
+  const running = ((await run([WSL, "--list", "--running"])).stdout ?? "").split(/\r?\n/).map((line) => line.trim().replace(/\s+\([^)]*\)$/, "")).filter((line) => distroNames.includes(line));
+  if (!options.json) {
+    console.log("");
+    console.log("sessions across running distros");
+    if (running.length === 0) {
+      console.log("  (none)");
+    } else {
+      for (const d of running) {
+        const report = (await inDistro(d, STALE_SCOPE_REPORT)).stdout.trim();
+        const lines = report === "none" || report.length === 0 ? [] : report.split(/\r?\n/);
+        if (report === "none") {
+          console.log(`  ${d}  no user manager — scopes unavailable`);
+          continue;
+        }
+        if (lines.length === 0) {
+          console.log(`  ${d}  no session scopes`);
+          continue;
+        }
+        for (const line of lines) {
+          const m = /^(\S+) (active|stale) pids:(.*)$/.exec(line);
+          if (m === null) { console.log(`  ${d}  ${line}`); continue; }
+          const scope = m[1] ?? line;
+          const state = m[2] ?? "";
+          const pidNote = m[3] === "none" ? "" : `  resident pids:${(m[3] ?? "").trim()}`;
+          console.log(`  ${d}  ${scope}  ${state}${pidNote}`);
+        }
+      }
+    }
+  }
+
+  // ---- listening ports across running distros (WSL-308) ----------------------
+  // The port poller serves the model's session (DSH_WSL_PORTS); this survey
+  // serves the human, with the two actions the facts imply: the localhost URL
+  // WSL2's forwarding already makes reachable, and the netsh line that would
+  // extend reach beyond the host (printed, never applied).
+  if (!options.json) {
+    const portScript = procNetScript();
+    let anyPorts = false;
+    for (const d of running) {
+      const answer = await inDistro(d, portScript);
+      const ports = parseListeningPorts(answer.stdout);
+      if (ports.length === 0) continue;
+      anyPorts = true;
+      const ip = ((await inDistro(d, "hostname -I")).stdout ?? "").trim().split(/\s+/)[0] ?? "";
+      console.log("");
+      console.log(`listening ports in ${d}`);
+      for (const port of ports) {
+        console.log(`  :${port}  http://localhost:${port}   (LAN: netsh interface portproxy add v4tov4 listenport=${port} listenaddress=0.0.0.0 connectport=${port} connectaddress=${ip})`);
+      }
+    }
+    if (!anyPorts && running.length > 0) console.log("\nno listening ports in the running distros");
+  }
+
   // ---- peers ---------------------------------------------------------------
   const manifest = /** @type {{ peerDependencies?: Record<string, string> }} */ (JSON.parse(readFileSync(join(ROOT, "package.json"), "utf8")));
   const peers = Object.entries(manifest.peerDependencies ?? {});