dsh-plugin-wsl-env 0.1.5 → 0.1.6

package/CHANGELOG.md

@@ -12,6 +12,48 @@ 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

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
@@ -144,10 +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: 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.
+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

@@ -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

@@ -124,9 +124,12 @@ behaviour and the error messages match a Linux host. The function
 | `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. The fence is complete for the model's reach: `writeText` and `editText` are
+`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
@@ -181,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/LIMITATIONS.md

@@ -9,6 +9,11 @@ boundary; one that is not is a bug report waiting to happen.
 - **`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

package/docs/README.zh.md

@@ -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/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/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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-plugin-wsl-env",
-  "version": "0.1.5",
+  "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/probe-cache.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/probe-cache.test.mjs test/sandbox.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",