dsh-plugin-wsl-env 0.2.0 → 0.4.0

package/lib/index.js

@@ -43,7 +43,8 @@ import { LocalBashExecutor } from "@deepseek-ai/dsh-bash-local";
 import { LocalFileSystem } from "@deepseek-ai/dsh-fs-local";
 import { FsError } from "@deepseek-ai/dsh-fs";
 import { canonicalPath, classifyRunnerFailure, isRunnerSpawnFailure, matchesSignature, SandboxUnavailableError, writableRoots } from "@deepseek-ai/dsh-sandbox";
-import { isRelativeWorldPath, isWorldPathUnder, isWslUnc, isUnderDistro, posixToUnc, toDisplayPath, toLinuxPath, toWorldPath, uncToPosix } from "./paths.js";
+import { isAnotherDistrosUnc, isRelativeWorldPath, isWorldPathUnder, isWslUnc, isUnderDistro, posixToUnc, toDisplayPath, toLinuxPath, toWorldPath, uncToPosix, windowsToLinuxMount } from "./paths.js";
+import { guardRefusal, isConfinedMutation, mutationModeRefusal, outsideDistroRefusal, substrateFailure, workspaceWriteDenial } from "./fs-decisions.js";
 import { WslSandbox } from "./sandbox.js";
 import { armDistroWatcher } from "./watcher.js";
 import { WslAgent } from "./agent.js";
@@ -51,6 +52,9 @@ import { AgentUnavailableError } from "./agent-errors.js";
 import { publicationArgv } from "./fs-publish.js";
 import { agentExecutionHandle } from "./agent-exec.js";
 import { sharedAgent } from "./agent-shared.js";
+import { AgentSubstrate } from "./fs-substrate.js";
+import { FsCodedError } from "./fsio-text.js";
+import { confinedAgent } from "./agent-confined.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, workdirFailure, wslErrorCode } from "./wsl.js";
@@ -172,6 +176,20 @@ export class WslShellExecutor extends LocalBashExecutor {
      * unconfined and `sandboxMode` is `undefined`, so the model is told so.
      */
     sandbox: z.boolean().default(true),
+    /**
+     * Shadow `/mnt` with an empty tmpfs in every confined profile, hiding the
+     * Windows drive from confined commands: its files cannot be read or
+     * exfiltrated and its executables cannot be launched through interop —
+     * the hole that lets a "sandboxed" command reach your full Windows token.
+     * A narrowing, not a closure (a command can still write an executable
+     * into the workspace and run it — binfmt dispatches on content, not
+     * location), so enforcement stays `partial` and the sandbox fact reports
+     * `windowsDrive: "masked"`. Costs: confined commands cannot read or touch
+     * anything under `/mnt`, and tools that probe the drive degrade. The
+     * complete closure is distro-level: `[interop] enabled=false` in
+     * `wsl.conf`.
+     */
+    maskWindowsDrive: z.boolean().default(false),
     /**
      * Default workdir for a request that names none; accepts `/home/andy/proj`,
      * a UNC path, or `C:\...`. Empty — the default — means the distro user's
@@ -447,6 +465,7 @@ export class WslShellExecutor extends LocalBashExecutor {
         mode: facts.mode,
         denied: !runnerFailed && matchesSignature(proc.exitCode, stderr, facts.denialSignatures),
         enforcement: facts.enforcement,
+        ...(facts.windowsDrive ? { windowsDrive: facts.windowsDrive } : {}),
         ...(runnerFailed ? { runnerFailed } : {}),
       };
     }
@@ -516,6 +535,7 @@ export class WslShellExecutor extends LocalBashExecutor {
     const distro = await this.distro();
     const shell = await this.shell();
     const resolved = await this.withDefaultWorkdir(spec);
+    this.throwIfWorkdirInAnotherDistro(resolved.workdir, distro);
     if (this.config.agent) {
       try {
         return await this.executeViaAgent(resolved, distro, shell);
@@ -528,6 +548,26 @@ export class WslShellExecutor extends LocalBashExecutor {
     return this.executeOneShot(resolved, distro, shell);
   }
 
+  /**
+   * Refuse a workdir that names another WSL distro — the shell-side twin of
+   * the filesystem's `FS_OUTSIDE_DISTRO` fence. Left unguarded, `toLinuxPath`
+   * strips the UNC's distro name and the command runs inside THIS distro
+   * against whatever tree happens to share the path, silently, while the fs
+   * side refuses the same workspace outright. The wording mirrors the fs
+   * refusal (minus `restrictToDistro`, which is an fs-only key).
+   * @param workdir - the resolved workdir (UNC, Linux path, or Windows path).
+   * @param distro - the pinned distro name.
+   * @throws Error naming both distros and both ways out.
+   */
+  throwIfWorkdirInAnotherDistro(workdir, distro) {
+    if (!isAnotherDistrosUnc(workdir, distro)) return;
+    throw new Error(
+      `"${workdir}" names a workspace in another WSL distro, and this profile pins its commands to "${distro}" — ` +
+        `running them here would act on a different machine's tree. Open a session in that distro, ` +
+        `or point cwd/workdir at this distro.`,
+    );
+  }
+
   /**
    * The agent-backed execution path: one long-lived in-distro process, the
    * confinement argv unchanged, the handle shape unchanged. Any
@@ -552,6 +592,10 @@ export class WslShellExecutor extends LocalBashExecutor {
       cwd: toLinuxPath(resolved.workdir, { distro }),
       argv: confined !== undefined ? confined.argv : this.distroArgv(resolved, shell),
       timeoutMs: resolved.timeoutMs,
+      // The agent enforces the collect budget distro-side (the EXEC frame
+      // carries it); `maxSpillBytes` stays one-shot-only — the agent path has
+      // no spill files by design, its capture is bounded instead.
+      maxOutputBytes: this.config.maxOutputBytes,
       signal: resolved.signal,
       onStarted: confined !== undefined
         ? (proc) => {
@@ -562,6 +606,7 @@ export class WslShellExecutor extends LocalBashExecutor {
               runnerFailureRules: confined.runnerFailureRules,
               runnerProgram: confined.argv[0],
               workdir: resolved.workdir,
+              windowsDrive: confined.windowsDrive,
             });
           }
         : undefined,
@@ -571,7 +616,7 @@ export class WslShellExecutor extends LocalBashExecutor {
       this.throwIfWorkdirMissing(result, resolved.workdir);
       if (this.sandbox === undefined) return result;
       if (confined === undefined) return { ...result, sandbox: { mode, denied: false } };
-      const { enforcement, denialSignatures, runnerFailureRules } = confined;
+      const { enforcement, denialSignatures, runnerFailureRules, windowsDrive } = confined;
       const runnerFailure = classifyRunnerFailure(result.exitCode, result.stderr.text, runnerFailureRules);
       if (runnerFailure !== undefined) throw new SandboxUnavailableError(mode, runnerFailure.detail);
       return {
@@ -580,6 +625,7 @@ export class WslShellExecutor extends LocalBashExecutor {
           mode,
           denied: matchesSignature(result.exitCode, result.stderr.text, denialSignatures),
           enforcement,
+          windowsDrive,
         },
       };
     }, (error) => {
@@ -635,6 +681,7 @@ export class WslShellExecutor extends LocalBashExecutor {
           runnerFailureRules: confined.runnerFailureRules,
           runnerProgram: confined.argv[0],
           workdir: resolved.workdir,
+          windowsDrive: confined.windowsDrive,
         });
       },
     );
@@ -642,7 +689,7 @@ export class WslShellExecutor extends LocalBashExecutor {
       this.throwIfDistroUnavailable(result, distro);
       this.throwIfWorkdirMissing(result, resolved.workdir);
       if (confined === undefined) return { ...result, sandbox: { mode, denied: false } };
-      const { enforcement, denialSignatures, runnerFailureRules } = confined;
+      const { enforcement, denialSignatures, runnerFailureRules, windowsDrive } = confined;
       // Runner failure outranks denial because the command did not run at all.
       const runnerFailure = classifyRunnerFailure(result.exitCode, result.stderr.text, runnerFailureRules);
       if (runnerFailure !== undefined) throw new SandboxUnavailableError(mode, runnerFailure.detail);
@@ -652,6 +699,7 @@ export class WslShellExecutor extends LocalBashExecutor {
           mode,
           denied: matchesSignature(result.exitCode, result.stderr.text, denialSignatures),
           enforcement,
+          windowsDrive,
         },
       };
     }, (error) => {
@@ -716,6 +764,14 @@ export class WslFileSystem extends LocalFileSystem {
      * operations are unconfined.
      */
     sandbox: z.boolean().default(true),
+    /**
+     * Shadow `/mnt` with an empty tmpfs in every confined profile, hiding the
+     * Windows drive from confined commands — same meaning and same honest
+     * limits as the `wsl-shell` key of the same name (its doc carries the
+     * full story). Confined fs mutations publish through the masked resident;
+     * reads and the share substrate are unaffected.
+     */
+    maskWindowsDrive: z.boolean().default(false),
     /**
      * Refuse any path that leaves the pinned distro. A WSL filesystem is a
      * whole-Linux view whose `/mnt/c` also reaches the Windows disk, so without
@@ -741,6 +797,19 @@ export class WslFileSystem extends LocalFileSystem {
      * only how many round trips it costs.
      */
     agent: z.boolean().default(true),
+    /**
+     * Which I/O substrate serves the file tools. `"agent"` (the default) —
+     * the resident in-distro agent (`lib/fs-substrate.js`): reads, writes,
+     * identities and watches run where the files live, symlinks and mode bits
+     * are native, and the mutation guard survives to the write's no-replace
+     * publication, kernel-enforced by the confined resident when the policy is
+     * confined. `"share"` — the opt-out: the Windows-side host filesystem
+     * stack over the distro's 9p share, with the symlink-retry and publication
+     * hooks that compensate for what the share cannot do. Both substrates
+     * fence writes with the same host-side policy check; neither changes
+     * `sandboxMode`'s honesty.
+     */
+    substrate: z.union(["share", "agent"]).default("agent"),
   });
 
   constructor(ctx, config) {
@@ -752,6 +821,10 @@ export class WslFileSystem extends LocalFileSystem {
     this.defaultMode = ctx.sandboxPolicy.defaultMode;
     /** targetKey -> canonical replacement target, for symlinked paths. */
     this.canonicalTargets = new Map();
+    /** The lazy agent-backed substrate, built on first use (see `agentSubstrate`). */
+    this.agentSubstrateInstance = undefined;
+    /** The distro-side bwrap usability probe, shared with the confined agents. */
+    this.sandbox = new WslSandbox({ wslPath: config.wslPath, maskWindowsDrive: config.maskWindowsDrive });
     // `dsh-fs-local` takes a Windows branch whenever the destination already
     // exists — which is how it knows to preserve the replaced file's security
     // descriptor, and what makes every write to an existing file fail here:
@@ -846,6 +919,78 @@ export class WslFileSystem extends LocalFileSystem {
     return this.agentInstance;
   }
 
+  /**
+   * The agent-backed substrate for `substrate: "agent"`, built on first use
+   * over the same resident agent the publication path shares.
+   * @returns {Promise<AgentSubstrate|undefined>} the substrate, or undefined
+   *   when the share backend is configured.
+   */
+  async agentSubstrate() {
+    if (this.config.substrate !== "agent") return undefined;
+    if (this.agentSubstrateInstance === undefined) {
+      this.agentSubstrateInstance = new AgentSubstrate({
+        agent: await this.publicationAgent(),
+        distro: await this.distro(),
+        diffBasisMaxBytes: this.config.diffBasisMaxBytes,
+        agentFor: (policy) => this.mutationAgent(policy),
+      });
+    }
+    return this.agentSubstrateInstance;
+  }
+
+  /**
+   * The agent a MUTATION runs on under this resolved policy — stage-two
+   * routing. A confined policy addresses the confined resident whose bwrap
+   * profile binds exactly what the mode grants, so the kernel enforces what
+   * the check decided; an escalated write (`danger-full-access`) or a disabled
+   * sandbox addresses the plain resident, which is what those mean. A distro
+   * without a usable bwrap refuses confined mutations instead of downgrading
+   * them — the same closed failure the command path has.
+   * @param {{mode: string, workspaceRoot: string}|undefined} policy - the
+   *   resolved file-effect policy, or undefined when the caller pre-checked.
+   * @returns {Promise<WslAgent>} the agent to publish through.
+   */
+  async mutationAgent(policy) {
+    if (!isConfinedMutation({ policy, sandboxEnabled: this.config.sandbox })) {
+      return this.publicationAgent();
+    }
+    const distro = await this.distro();
+    if (!(await this.sandbox.usable(distro))) {
+      throw new SandboxUnavailableError(
+        policy.mode,
+        `bwrap is not usable inside distro "${distro}". Install it with ` +
+          `"scripts/bootstrap.sh ${distro} --install" (from the package), or directly: ` +
+          `wsl.exe -d ${distro} -u root -- apt-get install -y bubblewrap`,
+      );
+    }
+    return confinedAgent({ distro, wslPath: this.config.wslPath, policy, maskWindowsDrive: this.config.maskWindowsDrive });
+  }
+
+  /**
+   * Map a substrate error onto the peer's `FsError`, so the tool layer reads
+   * the same refusal dialect on both substrates. An agent that is out becomes
+   * an I/O error naming the cause — the share backend's "distro is gone" case
+   * is the same availability, but the message says which substrate failed.
+   * @param error - what the substrate raised.
+   * @returns {FsError} the error to surface.
+   */
+  peerError(error) {
+    if (error instanceof FsCodedError) return new FsError(error.message, error.code, { cause: error });
+    if (error instanceof SandboxUnavailableError) return new FsError(error.message, "FS_IO_ERROR", { cause: error });
+    const { message, code, cause } = substrateFailure(error);
+    return new FsError(message, code, cause === undefined ? {} : { cause });
+  }
+
+  /**
+   * One resolved target's Linux path — the substrate's coordinate — falling
+   * back to the display spelling when the identity is not a distro share path.
+   * @param target - the resolved target.
+   * @returns the absolute Linux path.
+   */
+  linuxOf(target) {
+    return uncToPosix(target.targetKey)?.linuxPath ?? target.displayPath;
+  }
+
   /**
    * The pinned distro, resolving WSL's default on first use.
    * @returns the distro name.
@@ -871,15 +1016,12 @@ export class WslFileSystem extends LocalFileSystem {
       base = await distroHome(this);
     }
     const world = toWorldPath(path, { distro, cwd: base });
-    if (this.config.restrictToDistro && isWslUnc(world) && !isUnderDistro(world, distro)) {
+    const refusal = outsideDistroRefusal({ path, world, distro, restrictToDistro: this.config.restrictToDistro });
+    if (refusal !== null) {
       // 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",
-      );
+      throw new FsError(refusal.message, refusal.code);
     }
     return world;
   }
@@ -892,8 +1034,19 @@ export class WslFileSystem extends LocalFileSystem {
    * @returns the resolved `FsTarget`.
    */
   async resolve(path, opts) {
+    const world = await this.worldPath(path, opts?.cwd);
+    const sub = await this.agentSubstrate();
+    if (sub !== undefined) {
+      const linux = uncToPosix(world)?.linuxPath ?? windowsToLinuxMount(world);
+      if (linux === undefined) throw new FsError(`cannot serve "${path}" from inside the distro`, "FS_IO_ERROR");
+      try {
+        return await sub.resolve(linux, opts?.signal);
+      } catch (error) {
+        throw this.peerError(error);
+      }
+    }
     const distro = await this.distro();
-    const target = await super.resolve(await this.worldPath(path, opts?.cwd), opts);
+    const target = await super.resolve(world, opts);
     return { targetKey: target.targetKey, displayPath: toDisplayPath(target.targetKey, distro) };
   }
 
@@ -919,17 +1072,16 @@ export class WslFileSystem extends LocalFileSystem {
   async checkedTarget(target, sandboxPolicy) {
     if (!this.config.sandbox) return target;
     const policy = sandboxPolicy ?? this.ctx.sandboxPolicy.resolve();
-    const { mode } = policy;
-    if (mode === "danger-full-access") return target;
-    if (mode === "read-only") {
-      throw new FsError(`cannot write "${target.displayPath}": file access denied under read-only mode`, "FS_SANDBOX_DENIED");
-    }
+    const modeRefusal = mutationModeRefusal(policy.mode, target.displayPath);
+    if (modeRefusal !== null) throw new FsError(modeRefusal.message, modeRefusal.code);
+    if (policy.mode !== "workspace-write") return target;
     const fresh = await this.resolve(target.displayPath);
     const distro = await this.distro();
     for (const root of wslWritableRoots(policy, distro)) {
       if (isWorldPathUnder(fresh.targetKey, root, { distro })) return fresh;
     }
-    throw new FsError(`cannot write "${target.displayPath}": file access denied under workspace-write mode`, "FS_SANDBOX_DENIED");
+    const denial = workspaceWriteDenial(target.displayPath);
+    throw new FsError(denial.message, denial.code);
   }
 
   /**
@@ -1002,22 +1154,86 @@ export class WslFileSystem extends LocalFileSystem {
   }
 
   async stat(target, signal) {
+    const sub = await this.agentSubstrate();
+    if (sub !== undefined) {
+      try {
+        return await sub.stat(target, signal);
+      } catch (error) {
+        throw this.peerError(error);
+      }
+    }
     return this.withCanonicalRetry(target, signal, (t) => super.stat(t, signal));
   }
 
+  /**
+   * No-follow stat one path. The agent substrate answers from the distro,
+   * where a symlink is a first-class entry; the share backend keeps the
+   * inherited host behaviour.
+   * @param path - a Linux, UNC or Windows path.
+   * @param opts - optional `cwd` override.
+   * @param signal - optional cancellation.
+   * @returns the path info, or undefined when absent.
+   */
+  async lstat(path, opts, signal) {
+    const sub = await this.agentSubstrate();
+    if (sub !== undefined) {
+      const world = await this.worldPath(path, opts?.cwd);
+      const linux = uncToPosix(world)?.linuxPath ?? windowsToLinuxMount(world);
+      if (linux === undefined) throw new FsError(`cannot inspect "${path}" from inside the distro`, "FS_IO_ERROR");
+      try {
+        return await sub.lstat(linux, signal);
+      } catch (error) {
+        throw this.peerError(error);
+      }
+    }
+    return super.lstat(path, opts, signal);
+  }
+
   async readText(target, signal) {
+    const sub = await this.agentSubstrate();
+    if (sub !== undefined) {
+      try {
+        return await sub.readText(target, signal);
+      } catch (error) {
+        throw this.peerError(error);
+      }
+    }
     return this.withCanonicalRetry(target, signal, (t) => super.readText(t, signal));
   }
 
   async streamText(target, signal) {
+    const sub = await this.agentSubstrate();
+    if (sub !== undefined) {
+      try {
+        return await sub.streamText(target, signal);
+      } catch (error) {
+        throw this.peerError(error);
+      }
+    }
     return this.withCanonicalRetry(target, signal, (t) => super.streamText(t, signal));
   }
 
   async readBytes(target, signal, maxBytes) {
+    const sub = await this.agentSubstrate();
+    if (sub !== undefined) {
+      try {
+        return await sub.readBytes(target, signal, maxBytes);
+      } catch (error) {
+        throw this.peerError(error);
+      }
+    }
     return this.withCanonicalRetry(target, signal, (t) => super.readBytes(t, signal, maxBytes));
   }
 
   async readByteRange(target, range, signal) {
+    const sub = await this.agentSubstrate();
+    if (sub !== undefined) {
+      try {
+        return await sub.readByteRange(target, range, signal);
+      } catch (error) {
+        throw this.peerError(error);
+      }
+    }
     return this.withCanonicalRetry(target, signal, (t) => super.readByteRange(t, range, signal));
   }
 
@@ -1031,6 +1247,16 @@ export class WslFileSystem extends LocalFileSystem {
    * @returns the directory rows.
    */
   async listDir(target, signal) {
+    const sub = await this.agentSubstrate();
+    if (sub !== undefined) {
+      // The substrate's rows already carry Linux display paths and canonical
+      // identities, so no share-side rewrite follows.
+      try {
+        return await sub.listDir(target, signal);
+      } catch (error) {
+        throw this.peerError(error);
+      }
+    }
     const entries = await this.withCanonicalRetry(target, signal, (t) => super.listDir(t, signal));
     const distro = await this.distro();
     return entries.map((entry) => ({
@@ -1089,14 +1315,8 @@ export class WslFileSystem extends LocalFileSystem {
   async assertGuard(target, expected, signal) {
     if (expected === undefined) return;
     const existing = await this.stat(target, signal);
-    if (expected.kind === "replaceIfVersion") {
-      if (existing === undefined) throw new FsError(`cannot write "${target.displayPath}": file no longer exists`, "FS_STALE_VERSION");
-      if (existing.version !== expected.version) throw new FsError(`cannot write "${target.displayPath}": file changed since it was read`, "FS_STALE_VERSION");
-      return;
-    }
-    if (expected.kind === "createIfAbsent" && existing !== undefined) {
-      throw new FsError(`cannot overwrite existing "${target.displayPath}" without reading it first`, "FS_NOT_OBSERVED");
-    }
+    const refusal = guardRefusal(expected, existing, target.displayPath);
+    if (refusal !== null) throw new FsError(refusal.message, refusal.code);
   }
 
   /**
@@ -1111,9 +1331,25 @@ export class WslFileSystem extends LocalFileSystem {
    * @returns the write outcome.
    */
   async writeText(target, content, expected, signal, sandboxPolicy) {
+    // The policy resolves once: the fence and the confined routing must see
+    // the same grant, or the kernel would enforce something other than what
+    // was checked.
+    const policy = sandboxPolicy ?? this.ctx.sandboxPolicy.resolve();
     // The fence runs first and its fresh target is the one checked and written,
     // so a refusal costs no I/O and cannot be raced by a swapped symlink.
-    const fenced = await this.checkedTarget(target, sandboxPolicy);
+    const fenced = await this.checkedTarget(target, policy);
+    const sub = await this.agentSubstrate();
+    if (sub !== undefined) {
+      // The agent substrate keeps the guard: the distro-side no-replace link
+      // is an atomic primitive, so the check-then-write window the share
+      // backend documents closes here, exactly as on a Linux host. The policy
+      // also selects the confined resident whose mount table matches it.
+      try {
+        return await sub.writeText(fenced, content, expected, signal, policy);
+      } catch (error) {
+        throw this.peerError(error);
+      }
+    }
     await this.assertGuard(fenced, expected, signal);
     // The guard is deliberately not forwarded: the host backend would publish a
     // guarded creation with a hard link, which this filesystem rejects. Once
@@ -1133,7 +1369,16 @@ export class WslFileSystem extends LocalFileSystem {
    * @returns the edit outcome.
    */
   async editText(target, edit, expected, signal, sandboxPolicy) {
-    const fenced = await this.checkedTarget(target, sandboxPolicy);
+    const policy = sandboxPolicy ?? this.ctx.sandboxPolicy.resolve();
+    const fenced = await this.checkedTarget(target, policy);
+    const sub = await this.agentSubstrate();
+    if (sub !== undefined) {
+      try {
+        return await sub.editText(fenced, edit, expected, signal, policy);
+      } catch (error) {
+        throw this.peerError(error);
+      }
+    }
     await this.assertGuard(fenced, expected, signal);
     return super.editText(fenced, edit, undefined, signal);
   }

package/lib/paths.js

@@ -165,6 +165,20 @@ export function isUnderDistro(uncPath, distro) {
   return parsed !== undefined && parsed.distro.toLowerCase() === String(distro).toLowerCase();
 }
 
+/**
+ * A WSL UNC that names a distro OTHER than the pinned one — the shape both
+ * shell seams refuse: the shell executor will not run commands in it (running
+ * there would mean silently switching distros on path similarity), and the
+ * shell-env facts describe only the pinned distro, so a foreign session gets
+ * no facts rather than another distro's home and shell.
+ * @param uncPath - the candidate path (any spelling; non-UNC values are not foreign).
+ * @param distro - the pinned distro name.
+ * @returns true when the value is a WSL UNC under a different distro.
+ */
+export function isAnotherDistrosUnc(value, distro) {
+  return isWslUnc(value) && !isUnderDistro(value, distro);
+}
+
 /**
  * Translate a Windows drive path into its WSL interop mount.
  * @param winPath - e.g. `C:\Users\andyz\Documents`.

package/lib/sandbox.js

@@ -32,6 +32,12 @@ import { SandboxUnavailableError } from "@deepseek-ai/dsh-sandbox";
 import { createProbeCache } from "./probe-cache.js";
 import { toLinuxPath } from "./paths.js";
 import { runCapture } from "./wsl.js";
+import { bwrapArgvPrefix, bwrapProfileArgs } from "./bwrap.js";
+
+// The profile and the argv prefix are also what `lib/agent-confined.js` builds
+// for its residents, so both live in the peer-free `lib/bwrap.js` and are
+// re-exported here, where the sandbox's callers have always found them.
+export { bwrapProfileArgs };
 
 /**
  * bwrap's denial dialect: a write outside the granted mounts fails with EROFS,
@@ -60,6 +66,22 @@ const RUNNER_FAILURE_RULES = [{ fatalSignatures: ["bwrap: "] }];
  */
 const ENFORCEMENT = "partial";
 
+/**
+ * The one mitigation the profile can offer, and its honest ceiling.
+ *
+ * `maskWindowsDrive` mounts an empty tmpfs over `/mnt`: the Windows drive's
+ * files vanish from the command's view, which takes the drive's data off the
+ * table and makes the on-drive executables unreachable. It does NOT make the
+ * run `full`: binfmt interop dispatches on file CONTENT, so a command that can
+ * write the workspace (which `workspace-write` grants) can write a PE there
+ * and execute it — binfmt launches it as a Windows process outside the Linux
+ * sandbox regardless of where the file sits. The only complete closures are
+ * distro-level (`[interop] enabled=false` in `wsl.conf`, which costs every
+ * legitimate interop user their tooling) — so the provider reports `partial`
+ * either way, and the mask is a decision an operator makes to shrink the hole,
+ * recorded as the `windowsDrive: "masked"` fact the model can see.
+ */
+
 /**
  * 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`,
@@ -67,29 +89,6 @@ const ENFORCEMENT = "partial";
  */
 const probeVerdicts = createProbeCache();
 
-/**
- * Build the bwrap profile arguments for one file-effect policy, exactly as
- * upstream's `bwrapProfileArgs` does.
- *
- * `--ro-bind / /` makes the whole distro read-only, `--dev /dev` supplies the
- * `/dev/null` sink a shell needs, `--unshare-pid` keeps the sandbox's process
- * view its own, and `--proc /proc` gives it a matching `/proc`. Under
- * `workspace-write` the workspace is bound read-write and `/tmp` becomes an
- * ephemeral tmpfs — the temp area the mode promises, without exposing the
- * distro's real `/tmp`.
- *
- * @param policy - the policy to express as bwrap mounts.
- * @returns profile arguments, before the `--` separator and the command argv.
- */
-export function bwrapProfileArgs(policy) {
-  const args = ["--ro-bind", "/", "/", "--dev", "/dev", "--unshare-pid", "--proc", "/proc", "--die-with-parent"];
-  if (policy.mode === "workspace-write") {
-    args.push("--tmpfs", "/tmp");
-    args.push("--bind", policy.workspaceRoot, policy.workspaceRoot);
-  }
-  return args;
-}
-
 /**
  * Confine commands inside one distro with `bwrap`.
  *
@@ -100,9 +99,14 @@ export function bwrapProfileArgs(policy) {
 export class WslSandbox {
   /**
    * @param config - the `wsl.exe` path, overridable for a non-standard install.
+   * @param config.maskWindowsDrive - shadow `/mnt` with an empty tmpfs in every
+   *   profile this sandbox builds, hiding the Windows drive from confined
+   *   commands (see the module doc above {@link ENFORCEMENT} for what that
+   *   does and does not close).
    */
   constructor(config = {}) {
     this.wslPath = config.wslPath ?? "wsl.exe";
+    this.maskWindowsDrive = config.maskWindowsDrive ?? false;
   }
 
   /**
@@ -123,8 +127,8 @@ export class WslSandbox {
   async usable(distro, signal) {
     const key = `${this.wslPath}\u0000${distro}`;
     return probeVerdicts.run(key, async () => {
-      const profile = bwrapProfileArgs({ mode: "read-only", workspaceRoot: "/" });
-      await runCapture([this.wslPath, "-d", distro, "--exec", "bwrap", ...profile, "--", "true"], signal);
+      const prefix = bwrapArgvPrefix({ mode: "read-only", workspaceRoot: "/" });
+      await runCapture([this.wslPath, "-d", distro, "--exec", ...prefix, "true"], signal);
       return true;
     });
   }
@@ -152,12 +156,13 @@ export class WslSandbox {
       );
     }
     const workspaceRoot = toLinuxPath(policy.workspaceRoot, { distro });
-    const profile = bwrapProfileArgs({ ...policy, workspaceRoot });
+    const prefix = bwrapArgvPrefix({ ...policy, workspaceRoot }, { maskWindowsDrive: this.maskWindowsDrive });
     return {
-      argv: ["bwrap", ...profile, "--", ...argv],
+      argv: [...prefix, ...argv],
       enforcement: ENFORCEMENT,
       denialSignatures: DENIAL_SIGNATURES,
       runnerFailureRules: RUNNER_FAILURE_RULES,
+      windowsDrive: this.maskWindowsDrive ? "masked" : "visible",
     };
   }
 }

package/lib/shell-env.js

@@ -24,7 +24,7 @@
  */
 
 import z from "@deepseek-ai/schemastery";
-import { isWslUnc } from "./paths.js";
+import { isAnotherDistrosUnc, isWslUnc } from "./paths.js";
 import { defaultDistro, defaultShell, linuxHomePath } from "./wsl.js";
 import { sharedAgent } from "./agent-shared.js";
 import { listeningPorts } from "./ports.js";
@@ -82,6 +82,11 @@ export async function apply(ctx, config = {}) {
     resolve: (execution) => {
       const cwd = execution?.agent?.session?.header?.cwd;
       if (!isWslUnc(cwd)) return {};
+      // The facts describe ONE distro. A workspace under another distro's UNC
+      // is not that distro — the shell refuses its commands outright (the
+      // cross-distro guard) — so the honest resolution is no facts at all,
+      // not another distro's home and shell presented as this session's.
+      if (isAnotherDistrosUnc(cwd, distro)) return {};
       return {
         DSH_WSL_DISTRO: distro,
         DSH_WSL_SHELL: shell,