dsh-plugin-wsl-env 0.1.3 → 0.1.5

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.3",
+  "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",
@@ -35,6 +35,9 @@
     "examples/**/*.yml",
     "README.md",
     "docs/README.zh.md",
+    "docs/CONFIGURATION.md",
+    "docs/LIMITATIONS.md",
+    "docs/ARCHITECTURE.md",
     "CHANGELOG.md",
     "CONTRIBUTING.md",
     "SECURITY.md",
@@ -43,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",