dsh-plugin-wsl-env 0.1.4 → 0.1.6

package/CHANGELOG.md

@@ -12,6 +12,110 @@ reference below points at that record's numbering.
 
 ## [Unreleased]
 
+## [0.1.6] - 2026-10-02
+
+Three probes that close coverage gaps a closure review named, the documentation of a
+`/tmp` asymmetry, and one clearer error message. No behaviour changed otherwise.
+
+### Added
+
+- `npm run probe:picker` drives the directory picker in a throwaway boot: the root
+  level's crumbs, the Windows home, every installed distro, the documented
+  `directory-unreadable` refusal for a relative path and for a directory that does not
+  exist, and `maxEntries` with its `truncated` flag. Nothing ran `lib/picker.js` before
+  this — the unit tests import only `lib/listing.js`.
+- `npm run probe:missing-wsl` boots a profile whose `wslPath` cannot start and pins how
+  that is reported: the executable is named, `wslPath` is suggested, the failure is not
+  dressed up as a sandbox refusal, and no sandbox facts are claimed for a command that
+  never ran. The other fail-closed state — `wsl.exe` works but the distro has no
+  `bubblewrap` — is asserted in `test/sandbox.test.mjs`, which drives
+  `WslSandbox.confine` against a failing probe, because driving that end to end needs a
+  distro without `bubblewrap`.
+- `npm run probe:mode` runs `test/probe/mode-probe.mjs`, which measures which POSIX-mode
+  facts survive the share. The file was cited by `docs/LIMITATIONS.md` and wired into
+  no script at all.
+- `test/preset-choice.test.mjs` covers the session-preset decision, now that the rule
+  is the pure `lib/preset-choice.js`. The frame timing that applies the decision still
+  needs the harness, and the test says so.
+
+### Changed
+
+- `runCapture` names the cause when the executable itself cannot start: the message now
+  points at `wslPath` and at WSL being installed, the same way it already did for a
+  token denied by the Windows sandbox. `npm run probe:missing-wsl` asserts it.
+
+### Documentation
+
+- `docs/LIMITATIONS.md` states the `/tmp` split: a confined command's `/tmp` is a fresh
+  tmpfs while the file tools' fence grants the distro's *real* `/tmp`, so both sides can
+  write but neither sees the other's files. Hand a file between them through the session
+  workspace. `docs/ARCHITECTURE.md` describes the same distinction where it explains the
+  fence, including why the Windows temp directory is deliberately not granted to a
+  distro session.
+
+
+## [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

@@ -69,6 +69,9 @@ terminal if you would rather not see the prompt.
 | `npm run probe:sandbox` | what bubblewrap confines and what it does not | no |
 | `npm run probe:sandbox-shell` | the confined executor through a real boot | yes |
 | `npm run probe:terminal` | the terminal provider | yes |
+| `npm run probe:missing-wsl` | how a `wslPath` that cannot start is reported | yes |
+| `npm run probe:picker` | the picker's root level, its refusals and its cap | yes |
+| `npm run probe:mode` | which POSIX-mode facts survive the share | no; Windows Node | 
 
 Every script above is wired in `package.json`. `npm test` runs `lint:style`,
 `test:syntax` and `test:unit` in that order. `prepublishOnly` runs `npm test` again
@@ -92,9 +95,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 +147,11 @@ 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: 55 unit assertions on a bare checkout (50 plus the 5 preset-decision
+checks), 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; 9 picker
+checks; 6 missing-executable checks; 5 mode checks and 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 |
 
@@ -100,6 +100,9 @@ npm run probe:sandbox        # measure inside the distro what bubblewrap does an
 npm run probe                # filesystem probe against a real distro (Windows + WSL only)
 npm run probe:sandbox-shell  # boot a real harness and drive the confined executor
 npm run probe:terminal       # open a PTY through the terminal provider
+npm run probe:missing-wsl    # boot a profile whose wslPath cannot start (Windows + WSL only)
+npm run probe:picker         # list the picker's root level, refusals and its cap (Windows + WSL only)
+npm run probe:mode           # which POSIX-mode facts survive the share (Windows node only)
 ```
 
 There is nothing to install first: the package has no dependencies, and every module under test imports only Node builtins. CI runs `npm test` on Node 20, 22 and 24, on Linux and Windows, and `npm run test:coverage` on Node 24.

package/docs/ARCHITECTURE.md

@@ -120,14 +120,20 @@ 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.
+`WslFileSystem` checks writes against the same policy and the same writable list,
+with one deliberate translation: for a session inside a distro the temp root is the
+distro's own `/tmp`, and the Windows temp directory is *not* granted, because it lies
+outside the execution world the policy describes. That avoids a mismatch where `bash`
+could write `/tmp` but the write tool could not. The two `/tmp`s are still different
+directories — the command's is a fresh tmpfs — see [LIMITATIONS.md](LIMITATIONS.md). 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 +152,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`.
 
@@ -168,7 +184,8 @@ step with the checkout, and `npm run sync:windows` runs that script.
 | Syntax pass | [`test/syntax.mjs`](../test/syntax.mjs) | 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` | yes: Windows, WSL2, a mounted profile, and a linked checkout |
+| Harness probes | [`test/probe/run.sh`](../test/probe/run.sh), `terminal.sh`, `sandbox-shell.sh`, `picker.sh`, `missing-wsl.sh` | yes: Windows, WSL2, a mounted profile, and a linked checkout |
+| Host probes | [`test/probe/mode.sh`](../test/probe/mode.sh) | Windows Node, no harness |
 | Probe plugins | the `*-probe.mjs` and `*-probe.yml` files in `test/probe/` | loaded by the scripts above |
 
 The unit tests import only Node builtins, so they run on any platform. CI runs them

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,18 @@ 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 confined command's `/tmp` is not the write tool's `/tmp`.** `workspace-write`
+  mounts a fresh tmpfs at `/tmp` for the command — that is what makes it ephemeral —
+  while the file tools' fence grants the distro's *real* `/tmp`. Both are writable, so
+  neither side is refused, but a file the write tool puts in `/tmp` is invisible to
+  `bash` and vice versa. Hand a file between them through the session workspace.
+- 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` | 不加沙箱；用于批准后的放宽权限请求 |
 
@@ -100,6 +100,9 @@ npm run probe:sandbox        # 在发行版里实测 bubblewrap 能约束什么
 npm run probe                # 文件系统探针，需要真实发行版（仅 Windows + WSL）
 npm run probe:sandbox-shell  # 启动真实 harness，驱动受限执行器
 npm run probe:terminal       # 通过终端 provider 打开一个 PTY
+npm run probe:missing-wsl    # 启动一个 wslPath 无法启动的 profile（仅 Windows + WSL）
+npm run probe:picker         # 列出选择器的根级、拒绝路径与上限（仅 Windows + WSL）
+npm run probe:mode           # 哪些 POSIX 权限事实能穿过共享层（仅需 Windows node）
 ```
 
 这个包没有依赖，被测模块只 import Node 内置模块，所以不需要先安装任何东西。CI 在 Linux 和 Windows 上用 Node 20、22、24 运行 `npm test`，并在 Node 24 上运行 `npm run test:coverage`。

package/lib/auto-preset.js

@@ -33,6 +33,7 @@
 import { appendFileSync } from "node:fs";
 import z from "@deepseek-ai/schemastery";
 import { isWslUnc } from "./paths.js";
+import { shouldAdoptWslPreset } from "./preset-choice.js";
 
 /**
  * Set `DSH_WSL_TRACE` to a file path to record every decision this plugin makes.
@@ -106,14 +107,13 @@ export async function apply(ctx, config = {}) {
     // registry default (i.e. the operator did not ask for one). `undefined` means
     // the creating caller mounted nothing at all — the headless runner does this
     // — which is likewise "no explicit choice".
-    if (!isWslUnc(cwd)) return;
     let fallback;
     try {
       fallback = ctx.agentPresets.defaultId;
     } catch {
       fallback = void 0;
     }
-    if (current !== fallback && current !== void 0) return;
+    if (!shouldAdoptWslPreset({ cwd, current, fallback })) return;
     trace(`  -> acting: fallback=${String(fallback)} isWsl=${isWslUnc(cwd)}`);
 
     // Deferred on purpose — see the module comment.

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/preset-choice.js

@@ -0,0 +1,28 @@
+/**
+ * Whether a newly created session should adopt the WSL preset.
+ *
+ * The rule is deliberately narrow, and it is the whole of "a session whose workspace
+ * is inside a distro gets the distro environment automatically":
+ *
+ *   - the workspace must be a WSL UNC path, so a Windows folder keeps its own
+ *     environment;
+ *   - the session must not already carry an explicit choice. `undefined` counts as
+ *     "no choice", because a caller that mounts nothing at all (the headless runner)
+ *     is not asking for the host environment either; anything else must equal the
+ *     registry's default id, which is what "the operator did not pick one" looks like
+ *     after composition.
+ *
+ * Pure, so the decision is unit-testable without a boot — the frame timing that
+ * applies it still needs the harness.
+ *
+ * @param {{ cwd?: string, current?: string, fallback?: string }} input - the new
+ *   session's workspace, the preset it currently has, and the registry default.
+ * @returns true when the WSL preset should be selected for this session.
+ */
+import { isWslUnc } from "./paths.js";
+
+export function shouldAdoptWslPreset({ cwd, current, fallback } = {}) {
+  if (!isWslUnc(cwd)) return false;
+  if (current === void 0) return true;
+  return current === fallback;
+}

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

@@ -40,10 +40,15 @@ export function runCapture(argv, signal) {
           // is unhelpful, so name the cause when it is recognisable.
           const detail = `${stdout ?? ""}${stderr ?? ""}`.replace(/\u0000/g, "").trim();
           const denied = /E_ACCESSDENIED/i.test(detail) || error.code === "EACCES";
+          const missing = error.code === "ENOENT";
           error.message = `${file} failed: ${detail || error.message}${
             denied
               ? " (WSL is unreachable from a sandboxed process: DSH's Windows ACL sandbox runs commands under a restricted low-integrity token. Compose the non-sandboxing providers.)"
               : ""
+          }${
+            missing
+              ? ` (the executable "${file}" could not be started: check \`wslPath\` in this row, and that WSL is installed)`
+              : ""
           }`;
           reject(error);
           return;
@@ -285,6 +290,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.6",
   "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,12 +46,15 @@
   ],
   "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/preset-choice.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/preset-choice.test.mjs test/sandbox.test.mjs",
     "lint:style": "node test/style.mjs",
     "prepublishOnly": "npm test",
     "probe": "bash test/probe/run.sh",
+    "probe:missing-wsl": "bash test/probe/missing-wsl.sh",
+    "probe:mode": "bash test/probe/mode.sh",
+    "probe:picker": "bash test/probe/picker.sh",
     "probe:terminal": "bash test/probe/terminal.sh",
     "probe:sandbox": "bash test/probe/sandbox.sh",
     "probe:sandbox-shell": "bash test/probe/sandbox-shell.sh",