dsh-plugin-wsl-env 0.1.4 → 0.1.5

package/CHANGELOG.md

@@ -12,6 +12,68 @@ reference below points at that record's numbering.
 
 ## [Unreleased]
 
+## [0.1.5] - 2026-10-02
+
+Three defects from a design-closure review. Two are cases where a documented remedy
+could not work, and one where the cause of a failure was invisible.
+
+### Fixed
+
+- A failed sandbox probe was remembered for the process lifetime, so installing
+  `bubblewrap` after the app had started changed nothing until a restart — while the
+  error told the user to install exactly that. Only a success is cached now; a failure
+  is re-probed on the next command, and concurrent first commands share one probe. The
+  policy lives in [`lib/probe-cache.js`](lib/probe-cache.js), which is pure, so the
+  regression is pinned on every platform including CI
+  ([`test/probe-cache.test.mjs`](test/probe-cache.test.mjs)).
+- `restrictToDistro` refused another distro's share with `FS_SANDBOX_DENIED`. The
+  file-tool layer turns that code into a denial marker plus an escalation offer
+  (`mapError` in `dsh-tool-fs`), and no wider permission can lift this fence: it is a
+  configuration choice, not a sandbox decision. It now reports `FS_OUTSIDE_DISTRO`,
+  which the tool layer passes through unchanged, and the message says what to do.
+- A command that never started because the distro was missing, stopped or
+  unregistered reached the model as a bare non-zero exit. `wsl.exe` writes
+  `Wsl/Service/WSL_E_DISTRO_NOT_FOUND` to **stdout** — UTF-16LE on some builds — with
+  an empty stderr, so every signature in the plugin missed it. `WslShellExecutor` now
+  reads that code (NUL-stripped, so either encoding is found), pins `WSL_UTF8` on its
+  own spawn so the text is readable, and fails with the distro name and the remedy.
+  Deliberately not a sandbox code: a wider permission cannot create a distro.
+
+### Documentation
+
+- Two statements were wrong and are corrected against measurement. `read-only` does
+  not leave `/dev/null` as the only writable path: `bwrap --dev /dev` mounts a fresh
+  `/dev`, so `/dev/shm` is writable scratch and only `/tmp` stays read-only. And
+  `restrictToDistro` does not refuse `/mnt/c`, which is a directory *inside* the
+  distro — it refuses another distro's share.
+- The shell row's inherited output budgets (`maxOutputBytes`, `maxSpillBytes`,
+  `graceMs`) are listed in [`docs/CONFIGURATION.md`](docs/CONFIGURATION.md); the
+  fail-closed bullet in [`docs/LIMITATIONS.md`](docs/LIMITATIONS.md) matches the
+  re-probing behaviour, and what the file tools do when a distro stops mid-session is
+  stated there too.
+
+### Changed
+
+- `test:unit` gained `test/probe-cache.test.mjs` and `test/sandbox.test.mjs`;
+  `test:coverage` gained the pure one. The sandbox test skips itself where the
+  `dsh-sandbox` peer is absent, which is the CI case, and
+  [`CONTRIBUTING.md`](CONTRIBUTING.md) explains when a test belongs in which list.
+
+
+### Fixed
+
+- A shell request that names its workdir only **relatively** now lands on the
+  distro user's home, joined under it, when no `cwd` is configured — instead of
+  riding on the parent's `process.cwd()` fallback, a Windows directory no
+  `wsl.exe --cd` accepts. The empty-workdir case already defaulted to the home;
+  the relative tail was the one shape the marker missed. Absolute workdirs in
+  any coordinate system are unchanged.
+- A Windows UNC path outside the WSL share (`\\server\share\...`) is now
+  treated as the world path it already is, instead of being joined onto the
+  default workdir as if it were relative — which named a file that existed
+  nowhere. It also no longer triggers a `wsl.exe` home query it can never need:
+  `isRelativeWorldPath` now reports every UNC form, WSL or not, as absolute.
+
 ## [0.1.4] - 2026-10-02
 
 Documentation only: a shorter README, and the reference documents it links to.

package/CONTRIBUTING.md

@@ -92,9 +92,12 @@ Choose the layer by what the test needs.
 | Unit test | `test/*.test.mjs` | pure logic: path translation, listing, shell argument building, terminal helpers |
 | Probe | `test/probe/` | behaviour that needs a real distro, a real profile, or bubblewrap |
 
-Unit tests run under `node --test` and import only Node builtins. Add a file named
-`<area>.test.mjs`, then add it to both the `test:unit` and the `test:coverage`
-scripts in `package.json`. Both scripts list their files explicitly.
+Unit tests run under `node --test`. A test that imports only this repository goes in
+both the `test:unit` and the `test:coverage` lists in `package.json`, which name
+their files explicitly. A test that needs a DSH peer — `test/sandbox.test.mjs`
+imports `lib/sandbox.js`, which imports `@deepseek-ai/dsh-sandbox` — goes in
+`test:unit` only and must skip itself when the peer is missing, because CI installs
+nothing: try the import, print a `SKIP` line, exit 0.
 
 Probes are shell scripts that mount a throwaway profile, plus the small plugin
 files they load. Those plugin files are the `*-probe.mjs` and `*-probe.yml` files
@@ -141,8 +144,10 @@ On Windows 11 + WSL2 (Ubuntu 26.04) the following has been verified:
   outside the session workspace is refused inside the distro and the following
   wider-permission request succeeds.
 
-Counts: 42 unit assertions, 18 filesystem-probe assertions, 10 shell-probe checks, 10
-sandbox expectations plus the recorded escape, and 3 terminal assertions.
+Counts: 50 unit assertions on a bare checkout, plus 5 in `test/sandbox.test.mjs`
+which need the `dsh-sandbox` peer and skip themselves without it; 19
+filesystem-probe assertions; 12 shell-probe checks; 10 sandbox expectations plus
+the recorded escape; and 3 terminal assertions.
 
 ## Commit and pull request conventions
 

package/README.md

@@ -54,7 +54,7 @@ Override a row by id in `$DSH_HOME/profiles/<name>/cordis.patch.yml`. The keys w
 | `wsl-shell` | `distro` | `''` | distro name; empty means WSL's default distro |
 | | `sandbox` | `true` | confine commands with `bubblewrap`; `false` disables the sandbox |
 | `wsl-fs` | `distro` | `''` | as above |
-| | `restrictToDistro` | `true` | refuse paths outside the pinned distro, including `/mnt/c` |
+| | `restrictToDistro` | `true` | refuse a path in **another distro**'s share; `/mnt/c` is inside this distro and is not affected. Refused with `FS_OUTSIDE_DISTRO`, which is not a sandbox denial and cannot be lifted by wider permissions |
 | | `sandbox` | `true` | check `writeText` and `editText` against the policy |
 | `directory-picker-wsl` | `includeHostHome` | `true` | also list the Windows home directory |
 | `subprocess-wsl` | `distro` | `''` | which distro the GUI terminal opens in |
@@ -67,7 +67,7 @@ Commands are confined by `bubblewrap` inside the distro, and file writes are che
 
 | Mode | What a command inside the distro can do |
 |---|---|
-| `read-only` | read the whole distro; only `/dev/null` is writable |
+| `read-only` | read the whole distro; a fresh `/dev` is mounted writable, so `/dev/null` and `/dev/shm` work, and nothing else does |
 | `workspace-write` | the above, plus the session workspace is writable and `/tmp` is a temporary mount |
 | `danger-full-access` | no sandbox; used for an approved wider-permission request |
 

package/docs/ARCHITECTURE.md

@@ -120,14 +120,17 @@ behaviour and the error messages match a Linux host. The function
 
 | Mode | What a command inside the distro can do |
 |---|---|
-| `read-only` | read the whole distro; only `/dev/null` is writable |
+| `read-only` | read the whole distro; a fresh `/dev` is mounted writable, so `/dev/null` and `/dev/shm` work, and nothing else does |
 | `workspace-write` | the above, plus the session workspace is writable and `/tmp` is a temporary mount |
 | `danger-full-access` | no sandbox; used for an approved wider-permission request |
 
 `WslFileSystem` checks writes against the same policy and the same writable list.
 That avoids a mismatch where `bash` could write `/tmp` but the write tool could
-not. Both providers report their mode through `sandboxMode`. The tool layer and the
-Permissions selector read that value.
+not. The fence is complete for the model's reach: `writeText` and `editText` are
+the only mutation calls the model-facing file tools make on the filesystem seam,
+so checking those two checks everything the model can mutate. Both providers
+report their mode through `sandboxMode`. The tool layer and the Permissions
+selector read that value.
 
 ### Reported enforcement
 
@@ -146,6 +149,16 @@ throws `SandboxUnavailableError`, and every confined command reports
 `read-only file system` is classified as a denial, so the tool layer can offer the
 wider-permission path.
 
+A failed probe is **not** remembered: only a success is cached for the process
+lifetime, so a `bubblewrap` installed while the app runs is believed on the next
+command. See [`lib/probe-cache.js`](../lib/probe-cache.js).
+
+A command that never started because the distro itself is missing, stopped or
+unregistered is reported separately: `wsl.exe` puts a `WSL_E_*` code on stdout with
+an empty stderr, and `WslShellExecutor` turns that into an error naming the distro
+and the remedy instead of a bare non-zero exit. It is deliberately not a sandbox
+code, because a wider permission cannot create a distro.
+
 Set `sandbox: false` on either provider to opt out. Commands then run unconfined,
 and `sandboxMode` returns `undefined`.
 

package/docs/CONFIGURATION.md

@@ -18,7 +18,7 @@ are schema defaults, listed because they are the ones worth knowing.
 | | `cwd` | `''` | default working directory; empty means the distro user's home |
 | | `timeoutMs` / `maxTimeoutMs` | `120000` / `600000` *(shipped)* | per-call time limit, and the ceiling a call may ask for |
 | `wsl-fs` | `distro` | `''` *(shipped)* | as above |
-| | `restrictToDistro` | `true` *(shipped)* | refuse paths outside the pinned distro, including `/mnt/c` |
+| | `restrictToDistro` | `true` *(shipped)* | refuse a path in **another distro**'s share. `/mnt/c` is a directory *inside* the pinned distro, so it is not affected. The refusal carries `FS_OUTSIDE_DISTRO`; that is not a sandbox decision, so the file tools do not offer a wider permission for it. Set `false` to allow another distro's share |
 | | `sandbox` | `true` | check `writeText` and `editText` against the policy |
 | | `resolveSymlinks` | `true` | follow Linux symlinks that the share cannot traverse, such as `/etc/os-release` and `/bin` |
 | | `cwd` | `''` | base directory for relative paths; empty means the distro user's home |
@@ -31,7 +31,11 @@ are schema defaults, listed because they are the ones worth knowing.
 
 You can override the other keys in the same way; they keep their defaults. Those are
 `wslPath`, `hostCwd` and `forwardEnv` on the shell and terminal rows,
-`diffBasisMaxBytes` on `wsl-fs`, and `distroCacheMs` on the picker.
+`diffBasisMaxBytes` on `wsl-fs`, and `distroCacheMs` on the picker. The shell row
+also inherits the shipped output budgets — `maxOutputBytes` (64000 bytes per
+stream before the rest spills to a temporary file), `maxSpillBytes` (67108864) and
+`graceMs` (3000, the SIGTERM-to-SIGKILL grace) — from `dsh-bash-local`, which
+documents them in full.
 
 ## Which distro is used
 

package/docs/LIMITATIONS.md

@@ -6,7 +6,13 @@ boundary; one that is not is a bug report waiting to happen.
 - **The sandbox does not govern WSL interop.** A confined command can still run a
   Windows program, which escapes the Linux-side boundary. The plugin reports this as
   `enforcement: partial`. See [ARCHITECTURE.md](ARCHITECTURE.md#reported-enforcement).
-- **`bubblewrap` must be installed**, or both providers fail immediately.
+- **`bubblewrap` must be installed**, or both providers fail immediately. The
+  usability probe re-runs after a failure, so installing bubblewrap while the app
+  runs is believed on the next command; only a success is cached.
+- A distro that is stopped or unregistered while the app runs leaves the UNC share
+  unreachable: the shell tools report `wsl.exe`'s `WSL_E_*` code with the reason, but
+  the file tools can only report a file-level error, because the share itself is
+  gone.
 - `workspace-write` binds the workspace root as writable, and bubblewrap refuses a
   bind whose source directory does not exist. If a session's workspace directory is
   deleted, commands fail with a runner error; the plugin does not recreate the

package/docs/README.zh.md

@@ -54,7 +54,7 @@ dsh --profile wsl                                  # 4. 启动
 | `wsl-shell` | `distro` | `''` | 发行版名；空表示用 WSL 的默认发行版 |
 | | `sandbox` | `true` | 用 `bubblewrap` 约束命令；`false` 表示不用沙箱 |
 | `wsl-fs` | `distro` | `''` | 同上 |
-| | `restrictToDistro` | `true` | 拒绝发行版之外的路径（包括 `/mnt/c`） |
+| | `restrictToDistro` | `true` | 拒绝指向**其它发行版**共享的路径；`/mnt/c` 属于本发行版内部，不受影响。拒绝码为 `FS_OUTSIDE_DISTRO`，它不是沙箱拒绝，放宽权限也无法解除 |
 | | `sandbox` | `true` | 写入时按策略检查 `writeText` 和 `editText` |
 | `directory-picker-wsl` | `includeHostHome` | `true` | 同时列出 Windows 家目录 |
 | `subprocess-wsl` | `distro` | `''` | GUI 终端开在哪个发行版 |
@@ -67,7 +67,7 @@ dsh --profile wsl                                  # 4. 启动
 
 | 模式 | 发行版里的命令可以做什么 |
 |---|---|
-| `read-only` | 整个发行版只读，只有 `/dev/null` 可写 |
+| `read-only` | 整个发行版只读；`/dev` 是新建的可写挂载（`/dev/null` 与 `/dev/shm` 可用），其余不可写 |
 | `workspace-write` | 在上一行基础上，把会话工作区绑定为可写，并把 `/tmp` 挂成临时目录 |
 | `danger-full-access` | 不加沙箱；用于批准后的放宽权限请求 |
 

package/lib/index.js

@@ -46,7 +46,7 @@ import { isRelativeWorldPath, isWorldPathUnder, isWslUnc, isUnderDistro, posixTo
 import { WslSandbox } from "./sandbox.js";
 // `runCapture` and distro discovery live in ./wsl.js so the directory picker
 // can use them without pulling this file's executor and filesystem peers in.
-import { canonicalLinuxPath, copyModeInDistro, defaultDistro, defaultShell, linuxHomePath, shellArgs } from "./wsl.js";
+import { canonicalLinuxPath, copyModeInDistro, defaultDistro, defaultShell, linuxHomePath, shellArgs, wslErrorCode } from "./wsl.js";
 
 /**
  * Every model shell call gets a rebuilt managed `DSH_*` namespace (see
@@ -319,6 +319,11 @@ export class WslShellExecutor extends LocalBashExecutor {
       cwd: this.hostCwd(),
       env: {
         ...base.env,
+        // wsl.exe writes its own diagnostics as UTF-16LE unless this is set, and a
+        // UTF-16 message read as UTF-8 is mojibake — including the `WSL_E_*` codes
+        // that say why a command could not start. The distro-missing check below
+        // reads those codes, so the encoding has to be pinned here.
+        WSL_UTF8: "1",
         // WSL imports only the names listed in WSLENV. The managed DSH_* facts are
         // included by prefix so every contributed variable rides along. PATH is deliberately
         // never listed: putting it here would replace the distro's PATH with
@@ -336,9 +341,14 @@ export class WslShellExecutor extends LocalBashExecutor {
    *
    * The seam requires this step to be synchronous — the tool layer calls
    * `ctx.shell.execute(ctx.shell.resolve(…))` with no `await` between them — so
-   * neither the home nor a confinement decision can be made here. An empty
-   * `workdir` is the home marker, filled in {@link withDefaultWorkdir}, and the
-   * policy travels on the spec to {@link execute}, which awaits the wrap.
+   * neither the home nor a confinement decision can be made here. Two request
+   * shapes default to the home when no `cwd` is configured: one that names no
+   * `workdir` at all, and one that names it only RELATIVELY — the parent
+   * resolves the first against `process.cwd()` (a Windows directory) and has
+   * nothing of its own to join the second onto. Both are stamped as the empty
+   * marker, with a relative tail carried verbatim in `relativeWorkdir`;
+   * {@link withDefaultWorkdir} resolves the pair against the home. The policy
+   * travels on the spec to {@link execute}, which awaits the wrap.
    *
    * @param request - the caller's request.
    * @returns the fully-resolved spec.
@@ -346,27 +356,33 @@ export class WslShellExecutor extends LocalBashExecutor {
   resolve(request) {
     const spec = super.resolve(request);
     const sandboxPolicy = this.sandbox === undefined ? undefined : (request?.sandboxPolicy ?? this.ctx.sandboxPolicy.resolve());
-    const needsHome = request?.workdir === undefined && configuredCwd(this.config).length === 0;
+    const workdir = typeof request?.workdir === "string" ? request.workdir : undefined;
+    const needsHome =
+      configuredCwd(this.config).length === 0 && (workdir === undefined || isRelativeWorldPath(workdir));
     if (!needsHome && sandboxPolicy === undefined) return spec;
     return {
       ...spec,
-      ...(needsHome ? { workdir: "" } : {}),
+      ...(needsHome ? { workdir: "", relativeWorkdir: workdir } : {}),
       ...(sandboxPolicy === undefined ? {} : { sandboxPolicy }),
     };
   }
 
   /**
-   * The spec to execute, with an empty `workdir` filled from the distro user's
-   * home. That is one `sh -c 'printf %s "$HOME"'` per provider instance, cached,
-   * and it happens only for a request that named no directory and had no
-   * configured default.
+   * The spec to execute, with the home marker resolved against the distro
+   * user's home: `workdir: ""` becomes the home itself, and a relative tail
+   * carried by {@link WslShellExecutor.resolve} is joined under it. That is one
+   * `sh -c 'printf %s "$HOME"'` per provider instance, cached, and it happens
+   * only for a request that defaulted — an absolute workdir never reaches here.
    *
    * @param spec - the resolved spec.
    * @returns the spec to execute.
    */
   async withDefaultWorkdir(spec) {
-    if (String(spec?.workdir ?? "").trim().length > 0) return spec;
-    return { ...spec, workdir: await distroHome(this) };
+    const tail = typeof spec?.relativeWorkdir === "string" ? spec.relativeWorkdir : undefined;
+    if (String(spec?.workdir ?? "").trim().length > 0 && tail === undefined) return spec;
+    const home = await distroHome(this);
+    if (tail === undefined || tail.length === 0) return { ...spec, workdir: home };
+    return { ...spec, workdir: toLinuxPath(tail, { distro: await this.distro(), cwd: home }) };
   }
 
   /**
@@ -426,13 +442,50 @@ export class WslShellExecutor extends LocalBashExecutor {
    * @param spec - resolved execution settings.
    * @returns the live shell process handle.
    */
+  /**
+   * Reject a settled command that failed because the distro itself is missing,
+   * stopped or unregistered.
+   *
+   * `wsl.exe` exits non-zero for that with an EMPTY stderr and its diagnostic on
+   * stdout, so nothing else here can see it: the denial signatures read stderr, and
+   * the result would otherwise reach the model as a bare non-zero code with no
+   * cause. The message names the remedy and says plainly that a wider permission
+   * cannot help — a sandbox flag does not create a distro.
+   *
+   * @param result - the settled shell result.
+   * @param distro - the distro the command asked for.
+   * @throws Error carrying the `WSL_E_*` code and the remedy.
+   */
+  throwIfDistroUnavailable(result, distro) {
+    if (result?.exitCode === 0) return;
+    const code = wslErrorCode(result?.stdout?.text, result?.stderr?.text);
+    if (code === undefined) return;
+    throw new Error(
+      `wsl.exe reported ${code} for distro "${distro}": it is not installed, or not running. ` +
+        `Start it with \`wsl.exe -d ${distro}\`, check \`wsl.exe -l -v\`, or point \`distro\` at another one. ` +
+        `This is not a sandbox denial, so running with wider permissions will not help.`,
+    );
+  }
+
   async execute(spec) {
     const distro = await this.distro();
     const shell = await this.shell();
     const resolved = await this.withDefaultWorkdir(spec);
     const policy = resolved.sandboxPolicy;
     if (this.sandbox === undefined || policy === undefined || policy.mode === "danger-full-access") {
-      return this.executeArgv(resolved, () => this.argv(resolved, distro, shell));
+      // `executeArgv` resolves to the execution handle, so it has to be awaited
+      // before it can be decorated — the confined branch below does the same.
+      const execution = await this.executeArgv(resolved, () => this.argv(resolved, distro, shell));
+      return WslShellExecutor.decorateResult(
+        execution,
+        (result) => {
+          this.throwIfDistroUnavailable(result, distro);
+          return result;
+        },
+        (error) => {
+          throw error;
+        },
+      );
     }
     const mode = policy.mode;
     let confined;
@@ -458,6 +511,7 @@ export class WslShellExecutor extends LocalBashExecutor {
       },
     );
     return WslShellExecutor.decorateResult(execution, (result) => {
+      this.throwIfDistroUnavailable(result, distro);
       if (confined === undefined) return { ...result, sandbox: { mode, denied: false } };
       const { enforcement, denialSignatures, runnerFailureRules } = confined;
       // Runner failure outranks denial because the command did not run at all.
@@ -646,7 +700,14 @@ export class WslFileSystem extends LocalFileSystem {
     }
     const world = toWorldPath(path, { distro, cwd: base });
     if (this.config.restrictToDistro && isWslUnc(world) && !isUnderDistro(world, distro)) {
-      throw new FsError(`"${path}" is outside distro "${distro}"`, "FS_SANDBOX_DENIED");
+      // Deliberately NOT `FS_SANDBOX_DENIED`. The file-tool layer turns that code
+      // into a denial marker plus an escalation offer, and no wider permission can
+      // lift this fence: it is a configuration choice, not a sandbox decision.
+      throw new FsError(
+        `"${path}" names a path in another WSL distro, and this profile pins its filesystem to "${distro}" ` +
+          `(restrictToDistro: true). Open a session in that distro, or set restrictToDistro: false.`,
+        "FS_OUTSIDE_DISTRO",
+      );
     }
     return world;
   }

package/lib/paths.js

@@ -46,16 +46,17 @@ export function isPosixAbsolute(value) {
 }
 
 /**
- * Whether a path is relative — the only input for which {@link toWorldPath} and
- * {@link toLinuxPath} consult their `cwd` fallback. A provider uses this to skip
- * resolving a default workdir for input that can never need one.
+ * Whether a path names a location only relative to a base. The fs provider
+ * consults its default workdir exactly for this input; every absolute form —
+ * POSIX, drive, WSL UNC, or any other UNC share — is a location in its own
+ * right and short-circuits before a base is ever needed.
  * @param value - candidate path.
  * @returns true when the path names no absolute location.
  */
 export function isRelativeWorldPath(value) {
   const text = String(value ?? "");
   if (text.length === 0) return false;
-  return !isWslUnc(text) && !isPosixAbsolute(text) && !DRIVE_RE.test(text);
+  return !isWslUnc(text) && !isPosixAbsolute(text) && !DRIVE_RE.test(text) && !text.startsWith("\\");
 }
 
 /** Drop trailing separators, keeping a bare root (`C:\`, `\\wsl.localhost\x\`) meaningful. */
@@ -215,6 +216,10 @@ export function toWorldPath(value, options) {
   if (isWslUnc(text)) return toWindowsSlashes(text);
   if (isPosixAbsolute(text)) return posixToUnc(options?.distro ?? "Ubuntu", text);
   if (DRIVE_RE.test(text)) return toWindowsSlashes(text);
+  // Any other UNC share is already a world path in its own right — the host
+  // can open it directly, and joining it onto a base would name a file that
+  // exists nowhere.
+  if (text.startsWith("\\")) return toWindowsSlashes(text);
   const base = options?.cwd ?? process.cwd();
   const baseWorld = toWorldPath(base, { distro: options?.distro });
   return `${baseWorld.replace(/[\\/]+$/, "")}\\${toWindowsSlashes(text).replace(/^\.\\/, "")}`;

package/lib/probe-cache.js

@@ -0,0 +1,48 @@
+/**
+ * The caching policy for a functional probe: which verdicts may be remembered.
+ *
+ * A SUCCESS is durable — if `bwrap` created a profile a minute ago it will create
+ * one now. A FAILURE is not: it describes the machine as it is at that moment, and
+ * the common case is a package that is not installed *yet*. Remembering a failure
+ * would make the documented remedy (`sudo apt install bubblewrap`) silently
+ * ineffective until the app restarts, while the error message tells the user to
+ * install exactly that. So a failure is dropped and the next call probes again.
+ *
+ * Probes are I/O, and concurrent first calls would otherwise each pay for one.
+ * Storing the in-flight promise makes them share a single probe.
+ *
+ * Pure by construction — no Node API, no clock — so the policy is unit-testable
+ * without the peers `lib/sandbox.js` needs.
+ *
+ * @param {() => Promise<boolean>|boolean} probe - the probe to run on a miss. A
+ *   throw is a failed probe, never a propagated error.
+ * @returns {{ run: (key: string, probe: () => Promise<boolean>|boolean) => Promise<boolean>, size: number }}
+ */
+export function createProbeCache() {
+  /** @type {Map<string, true|Promise<boolean>>} */
+  const verdicts = new Map();
+  return {
+    async run(key, probe) {
+      const cached = verdicts.get(key);
+      if (cached !== undefined) return cached;
+
+      const pending = (async () => {
+        try {
+          return await probe();
+        } catch {
+          return false;
+        }
+      })();
+      verdicts.set(key, pending);
+
+      const verdict = await pending;
+      if (verdict) verdicts.set(key, true);
+      else verdicts.delete(key);
+      return verdict;
+    },
+    /** Remembered successes, for tests and diagnostics. */
+    get size() {
+      return verdicts.size;
+    },
+  };
+}

package/lib/sandbox.js

@@ -29,6 +29,7 @@
  */
 
 import { SandboxUnavailableError } from "@deepseek-ai/dsh-sandbox";
+import { createProbeCache } from "./probe-cache.js";
 import { toLinuxPath } from "./paths.js";
 import { runCapture } from "./wsl.js";
 
@@ -59,8 +60,12 @@ const RUNNER_FAILURE_RULES = [{ fatalSignatures: ["bwrap: "] }];
  */
 const ENFORCEMENT = "partial";
 
-/** Probe verdicts, keyed by `wslPath\0distro`; the probe spawns once per pair. */
-const probeVerdicts = new Map();
+/**
+ * Probe verdicts, keyed by `wslPath\0distro`. The policy — a success is durable, a
+ * failure is re-probed, concurrent probes are shared — lives in `probe-cache.js`,
+ * where it is unit-testable without the peers this module needs.
+ */
+const probeVerdicts = createProbeCache();
 
 /**
  * Build the bwrap profile arguments for one file-effect policy, exactly as
@@ -101,12 +106,15 @@ export class WslSandbox {
   }
 
   /**
-   * Whether `bwrap` can create a profile inside this distro, probed once per
-   * (`wslPath`, distro) pair. The probe mirrors upstream's: apply the real
-   * read-only profile around `true`, and treat a zero exit as the kernel having
-   * accepted and enforced it. A missing `bwrap` fails the spawn and probes
-   * unusable, which is what makes the provider fail closed rather than silently
-   * run unconfined.
+   * Whether `bwrap` can create a profile inside this distro. The probe mirrors
+   * upstream's: apply the real read-only profile around `true`, and treat a zero
+   * exit as the kernel having accepted and enforced it. A missing `bwrap` fails the
+   * spawn and probes unusable, which is what makes the provider fail closed rather
+   * than silently run unconfined.
+   *
+   * A success is remembered for the process lifetime; a failure is not, so a
+   * `bubblewrap` installed while the app is running is believed on the next
+   * command.
    *
    * @param distro - the distro to probe.
    * @param signal - optional cancellation.
@@ -114,18 +122,11 @@ export class WslSandbox {
    */
   async usable(distro, signal) {
     const key = `${this.wslPath}\u0000${distro}`;
-    const cached = probeVerdicts.get(key);
-    if (cached !== undefined) return cached;
-    let verdict = false;
-    try {
+    return probeVerdicts.run(key, async () => {
       const profile = bwrapProfileArgs({ mode: "read-only", workspaceRoot: "/" });
       await runCapture([this.wslPath, "-d", distro, "--exec", "bwrap", ...profile, "--", "true"], signal);
-      verdict = true;
-    } catch {
-      verdict = false;
-    }
-    probeVerdicts.set(key, verdict);
-    return verdict;
+      return true;
+    });
   }
 
   /**

package/lib/wsl.js

@@ -285,6 +285,25 @@ export function wslEnvValue(names) {
  * @param options - the `wsl.exe` path and optional cancellation.
  * @returns an absolute path to the shell inside the distro.
  */
+/**
+ * The `WSL_E_*` code inside `wsl.exe`'s own output, when it reported one.
+ *
+ * wsl.exe writes these diagnostics to STDOUT, and a build may encode them as
+ * UTF-16LE — a NUL byte between every ASCII character. Read as UTF-8 that leaves
+ * the code spelled with NULs in the middle, so the search strips them first and
+ * finds the code under either encoding. Verified against a missing distro:
+ * `wsl.exe -d nosuchdistro --exec …` exits 255 with an empty stderr and
+ * `Wsl/Service/WSL_E_DISTRO_NOT_FOUND` on stdout.
+ *
+ * @param stdout - a command's captured stdout.
+ * @param stderr - its captured stderr.
+ * @returns the code, for example `WSL_E_DISTRO_NOT_FOUND`, or undefined.
+ */
+export function wslErrorCode(stdout, stderr) {
+  const text = `${stdout ?? ""}\n${stderr ?? ""}`.replace(/\0/g, "");
+  return /WSL_E_[A-Z0-9_]+/.exec(text)?.[0];
+}
+
 export async function defaultShell(distro, options = {}) {
   const wslPath = options.wslPath ?? DEFAULT_WSL_PATH;
   const ask = async (script) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-plugin-wsl-env",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "description": "Run a DeepSeek Harness session against a WSL distro: a ctx.shell executor that runs commands inside the distro and a ctx.fs backend over its UNC share",
   "keywords": [
     "deepseek-harness",
@@ -46,9 +46,9 @@
   ],
   "scripts": {
     "test": "npm run lint:style && npm run test:syntax && npm run test:unit",
-    "test:coverage": "node --test --experimental-test-coverage --test-coverage-lines=85 --test-coverage-branches=85 --test-coverage-functions=70 test/paths.test.mjs test/listing.test.mjs test/shell.test.mjs test/terminal.test.mjs",
+    "test:coverage": "node --test --experimental-test-coverage --test-coverage-lines=85 --test-coverage-branches=85 --test-coverage-functions=70 test/paths.test.mjs test/listing.test.mjs test/shell.test.mjs test/terminal.test.mjs test/probe-cache.test.mjs",
     "test:syntax": "node test/syntax.mjs",
-    "test:unit": "node --test test/paths.test.mjs test/listing.test.mjs test/shell.test.mjs test/terminal.test.mjs",
+    "test:unit": "node --test test/paths.test.mjs test/listing.test.mjs test/shell.test.mjs test/terminal.test.mjs test/probe-cache.test.mjs test/sandbox.test.mjs",
     "lint:style": "node test/style.mjs",
     "prepublishOnly": "npm test",
     "probe": "bash test/probe/run.sh",