dsh-plugin-wsl-env 0.3.0 → 0.5.0

package/docs/UPSTREAM-TERMINAL-TITLE.md

@@ -0,0 +1,81 @@
+# Upstream proposal: a terminal tab title that follows the session's shell
+
+Status: proposed upstream as
+[deepseek-ai/deepseek-harness#8769](https://github.com/deepseek-ai/deepseek-harness/discussions/8769)
+(targeting `packages/api/terminal-controller`, version line `0.2.0-rc.x`). This
+is the record of a gap this plugin worked around, could not work around, and
+now documents: the GUI terminal titles every tab from the composition's single
+shell profile, so a per-session shell choice is invisible in the title.
+
+## The gap
+
+`TerminalController.spawn` fixes a terminal's display title from the resolved
+shell profile before the provider is ever consulted:
+
+```ts
+const info: WebTerminalInfo = {
+  id: request.id, shell, title: shell.name, cwd: environment.cwd, ...
+}
+```
+
+`shell` is `resolveShell(subprocess, this.config.shell, signal)` — the
+composition's configured profile (`shell.name: WSL` in this plugin's layer),
+kept verbatim; `resolveExecutable` swaps only the `path`. Two properties of the
+seam make the title unable to follow a per-session shell:
+
+- `SubprocessTerminalSpawnSpec` carries no display-name field, so a provider
+  that rewrites the launch (this plugin routes a Windows-folder session's
+  `wsl.exe` launch to `powershell.exe` — `subprocess-wsl.hostSessions`) cannot
+  say what it actually started.
+- The controller never reads the effective program back from the
+  `SubprocessTerminalHandle`, so the rewrite is invisible to `info.title`.
+
+The result on this plugin's default configuration: a terminal that runs
+PowerShell under a tab that reads `WSL`.
+
+## Why a plugin cannot bridge it
+
+Three escape hatches were evaluated against `0.2.0-rc.2` and each is closed:
+
+1. **Replace the controller row's module with a subclass** that corrects the
+   title after `super.spawn` (the class exports itself; `BrowserTerminal.rename`
+   is public and lands before `create()` publishes the terminal). Closed by the
+   patch-layer contract: *"A truthy name asserts the existing plugin name
+   rather than renaming it"* (`packages/boot/app-boot/src/config-schema/document.ts`)
+   — an id-targeted patch can replace `config`, but not the module.
+2. **Disable the shipped row and insert the subclass under a new id.** Closed
+   by the web composition: the row id is load-bearing. The web-app bundle
+   inserts `terminal-controller`, and the client model that the
+   `dsh-client-ui-sidebar-terminal` entry waits for mounts with
+   `inject = ['remote', 'remote.terminal']` — the `terminal` namespace the host
+   controller registers in its constructor. Disabling the row fails web boot:
+   `1 entry did not activate: @deepseek-ai/dsh-client-ui-sidebar-terminal:
+   pending (waiting for service: webTerminals)`. Verified live against
+   `dsh-desktop 0.2.0-rc.2`.
+3. **Per-session config.** The `shell` profile is composition state; `!!js`
+   expressions evaluate once at config resolution and reach no Session
+   identity.
+
+## The proposal
+
+Any one of these closes the gap; the first is the smallest and keeps the
+profile name as the fallback:
+
+- `SubprocessTerminalSpawnSpec` gains an optional `displayTitle` (or the handle
+  exposes the launched `argv`), and `create()` uses it for `info.title` when
+  present — falling back to `shell.name`. A provider that rewrites a launch
+  states the program it started; every other launch keeps the profile name.
+- Alternatively, the controller derives the title from the effective program
+  itself: title `executableName(effectiveArgv[0])` when it differs from
+  `shell.path`, else `shell.name`.
+
+With either, this plugin deletes the limitation paragraph in
+[LIMITATIONS.md](LIMITATIONS.md) and the `WSL`-over-PowerShell title, for any
+provider that rewrites launches — not just WSL.
+
+## Workarounds until then
+
+- Double-click a tab's title to rename it (a shipped client feature; the
+  controller's `rename` Remote API accepts 1–120 characters).
+- Add `shellCandidates` to the `terminal-controller` row in a user layer: a
+  manually selected shell is titled after itself.

package/lib/agent-confined.js

@@ -48,10 +48,16 @@ const confinedAgents = new Map();
  * @param {boolean} [request.maskWindowsDrive] - shadow `/mnt` with an empty
  *   tmpfs in the resident's profile; part of the cache key, since it changes
  *   the mount table the resident lives under.
+ * @param {boolean} [request.realTmp] - default TRUE: workspace-write binds the
+ *   distro's real `/tmp` read-write into the resident's profile, so a write
+ *   the fence approved lands where every reader reads. `false` restores the
+ *   ephemeral tmpfs — for tests and probes, not production: a `/tmp` write
+ *   behind an ephemeral mount reports success into a directory no reader can
+ *   see, which is the bug this default exists to prevent.
  * @returns {WslAgent} the confined resident for this key.
  */
-export function confinedAgent({ distro, wslPath = "wsl.exe", policy, maskWindowsDrive = false }) {
-  const key = `${wslPath}\0${distro}\0${policy.mode}\0${policy.workspaceRoot}\0${maskWindowsDrive ? "masked" : "visible"}`;
+export function confinedAgent({ distro, wslPath = "wsl.exe", policy, maskWindowsDrive = false, realTmp = true }) {
+  const key = `${wslPath}\0${distro}\0${policy.mode}\0${policy.workspaceRoot}\0${maskWindowsDrive ? "masked" : "visible"}\0${realTmp ? "real" : "ephemeral"}`;
   let agent = confinedAgents.get(key);
   if (agent === undefined) {
     agent = new WslAgent({
@@ -65,7 +71,7 @@ export function confinedAgent({ distro, wslPath = "wsl.exe", policy, maskWindows
       // `lib/bwrap.js`, whose module doc records what happened when they did not.
       argvPrefix: bwrapArgvPrefix(
         { mode: policy.mode, workspaceRoot: toLinuxPath(policy.workspaceRoot, { distro }) },
-        { maskWindowsDrive },
+        { maskWindowsDrive, realTmp },
       ),
     });
     confinedAgents.set(key, agent);

package/lib/agent.js

@@ -44,6 +44,50 @@ const HANDSHAKE_TIMEOUT_MS = 15000;
 /** Extra time the host watchdog waits past the request's own in-distro timeout. */
 const WATCHDOG_GRACE_MS = 13000;
 
+/** The Windows essentials `wsl.exe` itself needs to start and report cleanly. */
+const WINDOWS_ESSENTIALS = /^(systemroot|systemdrive|windir|path|pathext|comspec|os|computername)$/i;
+
+/** The managed facts prefix whose names (and only theirs) may be forwarded. */
+const MANAGED_ENV_PREFIX = "DSH_";
+
+/**
+ * The Windows environment the transport starts from, pinned.
+ *
+ * Spawned bare, `wsl.exe` would inherit this process's whole environment — and
+ * the `WSLENV` variable riding along decides which of those names are
+ * FORWARDED into the distro, where every model command inherits them. Dev
+ * machines routinely route secrets that way (`WSLENV=GITHUB_TOKEN/u` is the
+ * documented example), so the resident's env is built from scratch instead:
+ * the Windows essentials `wsl.exe` itself needs, the managed `DSH_*` facts,
+ * and a `WSLENV` that names only those managed entries — preserving their
+ * original forwarding flags. Nothing else on the Windows side can reach a
+ * model command.
+ *
+ * Deliberately NOT here: the executor's `forwardEnv` names. They ride the
+ * one-shot path's WSLENV (`spawnSpec` builds it per call); the resident path
+ * has never forwarded them, and this pin keeps that posture instead of
+ * widening it silently.
+ *
+ * @param {Record<string, string|undefined>} parent - this process's environment.
+ * @returns {Record<string, string>} the pinned environment for `wsl.exe`.
+ */
+export function pinnedWindowsEnv(parent) {
+  const env = {};
+  for (const [name, value] of Object.entries(parent)) {
+    if (value === undefined) continue;
+    if (WINDOWS_ESSENTIALS.test(name) || name.startsWith(MANAGED_ENV_PREFIX)) env[name] = value;
+  }
+  env.WSLENV = String(parent.WSLENV ?? "")
+    .split(":")
+    .filter((entry) => entry.startsWith(MANAGED_ENV_PREFIX))
+    .join(":");
+  // wsl.exe writes its own diagnostics as UTF-16LE without this, and a UTF-16
+  // message read as UTF-8 is mojibake — including the `WSL_E_*` codes. Same
+  // pin the one-shot path applies to every spawn.
+  env.WSL_UTF8 = "1";
+  return env;
+}
+
 /**
  * @param {object} options - the spawn options.
  * @param {string} options.wslPath - the `wsl.exe` path.
@@ -55,6 +99,7 @@ const WATCHDOG_GRACE_MS = 13000;
  */
 function spawnDefault({ wslPath, distro, scriptPath, argvPrefix = [] }) {
   return spawn(wslPath, ["-d", distro, "--exec", ...argvPrefix, "sh", scriptPath], {
+    env: pinnedWindowsEnv(process.env),
     stdio: ["pipe", "pipe", "pipe"],
     windowsHide: true,
   });
@@ -309,7 +354,13 @@ export class WslAgent {
             const id = `r${this.nextRequestId++}`;
             pending.id = id;
             this.pending.set(id, pending);
-            this.writeLines(relabelFrame(pending.lines, id));
+            // The rebuilt transport can itself be gone by now; a frame that
+            // cannot be written must fail its caller, not strand the entry.
+            if (!this.writeLines(relabelFrame(pending.lines, id))) {
+              this.clearPending(pending);
+              this.pending.delete(id);
+              pending.reject(new AgentUnavailableError(`agent exited before request ${id} could be re-sent; its state is unknown`));
+            }
           }
         })
         .catch((error) => {
@@ -381,7 +432,16 @@ export class WslAgent {
       };
       signal.addEventListener("abort", pending.onAbort, { once: true });
     }
-    this.writeLines(lines);
+    // A frame that cannot be WRITTEN must fail its caller now. Silently
+    // dropping it used to strand the request: nothing would ever answer, the
+    // watchdog (armed on an ACK that will not come) had no process to kill,
+    // and with no timeout the caller waited forever.
+    if (!this.writeLines(lines)) {
+      this.clearPending(pending);
+      this.pending.delete(pending.id);
+      reject(new AgentUnavailableError("the agent exited before the request could be sent; it never ran"));
+      return;
+    }
     this.rearmIdleTimer();
   }
 
@@ -491,15 +551,20 @@ export class WslAgent {
   /** @private */
   writeLines(lines) {
     const child = this.process;
-    if (!child || !child.stdin.writable) return;
+    if (!child || !child.stdin.writable) return false;
     child.stdin.write(`${lines.join("\n")}\n`);
     this.rearmIdleTimer();
+    return true;
   }
 
   /** @private */
   writeLinesSafe(child, lines) {
+    // The writable check matters beyond politeness: a write to an ENDED stdin
+    // does not throw here — it emits an async 'error' event the caller never
+    // listens for, which crashes the process during its own shutdown.
+    if (!child.stdin || !child.stdin.writable) return;
     try {
-      child.stdin?.write(`${lines.join("\n")}\n`);
+      child.stdin.write(`${lines.join("\n")}\n`);
     } catch {
       // A dead pipe is what close() is cleaning up after.
     }

package/lib/bwrap.js

@@ -40,15 +40,32 @@
  * (binfmt interop dispatches on file content, not location), so `enforcement`
  * stays `partial` — see `lib/sandbox.js`.
  *
+ * `options.realTmp` changes what workspace-write does at `/tmp`. The default
+ * (`--tmpfs /tmp`) gives the sandbox an ephemeral, empty temp area — the right
+ * shape for a COMMAND: fresh per run, cannot touch the distro's real `/tmp`,
+ * cannot be poisoned by a previous run. `realTmp: true` binds the REAL `/tmp`
+ * read-write instead — the right shape for the FILE-WRITES resident: the
+ * fence grants `/tmp` as a writable root, so a write the fence approved must
+ * land where every reader (the plain agent, the user's own shell) reads — not
+ * inside a private tmpfs that reads cannot see and that dies with the
+ * resident. Read-only mode mounts no `/tmp` at all, so the option is inert
+ * there.
+ *
  * @param policy - the policy to express as bwrap mounts.
  * @param options - profile options.
  * @param options.maskWindowsDrive - shadow `/mnt` with an empty tmpfs.
+ * @param options.realTmp - workspace-write binds the real `/tmp` read-write
+ *   instead of mounting an ephemeral tmpfs over it.
  * @returns profile arguments, before the `--` separator and the command argv.
  */
 export function bwrapProfileArgs(policy, options = {}) {
   const args = ["--ro-bind", "/", "/", "--dev", "/dev", "--unshare-pid", "--proc", "/proc", "--die-with-parent"];
   if (policy.mode === "workspace-write") {
-    args.push("--tmpfs", "/tmp");
+    if (options.realTmp) {
+      args.push("--bind", "/tmp", "/tmp");
+    } else {
+      args.push("--tmpfs", "/tmp");
+    }
     args.push("--bind", policy.workspaceRoot, policy.workspaceRoot);
   }
   if (options.maskWindowsDrive) {

package/lib/fs-decisions.js

@@ -0,0 +1,132 @@
+/**
+ * The filesystem provider's POLICY DECISIONS, extracted from
+ * `lib/index.js` so they are unit-testable in a bare checkout: which paths are
+ * refused for naming another distro, which mode refuses a mutation outright,
+ * which write guards refuse which intents, and how a substrate failure maps
+ * onto the refusal the tool layer surfaces. Pure in, descriptor out — no I/O,
+ * no peers (the provider wraps these descriptors in `FsError` at one choke
+ * point, keeping the peer import out of this module and the decisions honest).
+ *
+ * Every message here is model-facing and must stay byte-identical to what the
+ * provider produced before the extraction — the tool layer and the model match
+ * on these strings.
+ *
+ * @module dsh-plugin-wsl/fs-decisions
+ */
+
+import { isAnotherDistrosUnc } from "./paths.js";
+
+/** A refusal descriptor the provider wraps in `FsError` at one choke point. */
+const refusal = (message, code) => ({ message, code });
+
+/**
+ * The worldPath decision: a path that resolves into another WSL distro is
+ * refused while `restrictToDistro` holds — deliberately NOT a sandbox denial,
+ * because no wider permission can lift a configuration choice.
+ * @param {object} input - the decision's inputs.
+ * @param {string} input.path - the path as the caller spelled it.
+ * @param {string} input.world - the resolved world path (a UNC for distro paths).
+ * @param {string} input.distro - the pinned distro name.
+ * @param {boolean} input.restrictToDistro - the configuration fence.
+ * @returns {{message: string, code: string}|null} the refusal, or null to proceed.
+ */
+export function outsideDistroRefusal({ path, world, distro, restrictToDistro }) {
+  if (!restrictToDistro || !isAnotherDistrosUnc(world, distro)) return null;
+  return refusal(
+    `"${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",
+  );
+}
+
+/**
+ * The mutationAgent decision: does THIS mutation route to the confined
+ * resident? An absent policy (caller pre-checked), a disabled sandbox, and an
+ * approved escalation all address the plain resident — which is what those
+ * mean.
+ * @param {object} input - the decision's inputs.
+ * @param {{mode: string, workspaceRoot: string}|undefined} input.policy - the
+ *   resolved file-effect policy.
+ * @param {boolean} input.sandboxEnabled - the provider's `sandbox` configuration.
+ * @returns {boolean} true when the mutation belongs to the confined resident.
+ */
+export function isConfinedMutation({ policy, sandboxEnabled }) {
+  return Boolean(policy) && Boolean(sandboxEnabled) && policy.mode !== "danger-full-access";
+}
+
+/**
+ * The mode-level mutation decision: `read-only` refuses every write outright;
+ * `danger-full-access` is the approved escalation and refuses nothing.
+ * `workspace-write` refuses nothing HERE — its containment check needs the
+ * fresh target and runs in the provider.
+ * @param {string} mode - the resolved policy mode.
+ * @param {string} displayPath - the caller-facing path for the message.
+ * @returns {{message: string, code: string}|null} the refusal, or null to proceed.
+ */
+export function mutationModeRefusal(mode, displayPath) {
+  if (mode !== "read-only") return null;
+  return refusal(`cannot write "${displayPath}": file access denied under read-only mode`, "FS_SANDBOX_DENIED");
+}
+
+/**
+ * The containment denial for a `workspace-write` mutation whose fresh target
+ * sat under no writable root.
+ * @param {string} displayPath - the caller-facing path for the message.
+ * @returns {{message: string, code: string}} the refusal descriptor.
+ */
+export function workspaceWriteDenial(displayPath) {
+  return refusal(`cannot write "${displayPath}": file access denied under workspace-write mode`, "FS_SANDBOX_DENIED");
+}
+
+/**
+ * The write/edit guard: compare the intent (`expected`) with what is on disk
+ * NOW (`existing`, a stat row or `undefined`) and refuse the stale or
+ * unobserved intent. The peer's dialect, byte for byte.
+ * @param {object|undefined} expected - the write intent (`replaceIfVersion`
+ *   with a `version`, or `createIfAbsent`), or `undefined` for an unguarded write.
+ * @param {{version: string}|undefined} existing - what stat found, or undefined.
+ * @param {string} displayPath - the caller-facing path for the message.
+ * @returns {{message: string, code: string}|null} the refusal, or null to proceed.
+ */
+export function guardRefusal(expected, existing, displayPath) {
+  if (expected === undefined) return null;
+  if (expected.kind === "replaceIfVersion") {
+    if (existing === undefined) return refusal(`cannot write "${displayPath}": file no longer exists`, "FS_STALE_VERSION");
+    if (existing.version !== expected.version) {
+      return refusal(`cannot write "${displayPath}": file changed since it was read`, "FS_STALE_VERSION");
+    }
+    return null;
+  }
+  if (expected.kind === "createIfAbsent" && existing !== undefined) {
+    return refusal(`cannot overwrite existing "${displayPath}" without reading it first`, "FS_NOT_OBSERVED");
+  }
+  return null;
+}
+
+/**
+ * The substrate failure mapping: what the tool layer should surface for an
+ * error that crossed the `ctx.fs` seam. A coded refusal keeps its code and
+ * message byte-for-byte; anything else is the substrate being UNAVAILABLE —
+ * the share backend's "distro is gone" case wearing the agent substrate's
+ * wording — and the message names the documented opt-out, so an operator hit
+ * by the fail-closed posture can reach the old behaviour without a doc trip.
+ * @param {unknown} error - what the substrate raised.
+ * @returns {{message: string, code: string, cause: unknown}} the refusal the
+ *   provider wraps in `FsError`.
+ */
+export function substrateFailure(error) {
+  if (isCoded(error)) return { message: error.message, code: error.code, cause: error };
+  const message = error instanceof Error ? error.message : String(error);
+  return {
+    message:
+      `the distro file substrate is unavailable: ${message}. ` +
+      `Set "substrate: \\"share\\"" in the provider config to work on the Windows-side share while the agent is out.`,
+    code: "FS_IO_ERROR",
+    cause: error instanceof Error ? error : undefined,
+  };
+}
+
+/** A coded refusal: our `FsCodedError` duck (a message, a string `FS_*` code). */
+function isCoded(error) {
+  return error instanceof Error && typeof error.code === "string" && error.code.startsWith("FS_");
+}

package/lib/fsio-agent.js

@@ -68,7 +68,7 @@ export function parseStatRecord(stdout) {
   const [type, mode, size, dev, ino, mtime, ctime] = stdout.toString("utf8").split("\t");
   return {
     type,
-    mode: Number.parseInt(mode, 8) & 0o777,
+    mode: Number.parseInt(mode, 8) & 0o7777,
     size: Number(size),
     dev,
     ino,
@@ -419,7 +419,7 @@ export class DistroFs {
       "write",
       [
         linuxPath,
-        mode === undefined ? "-" : (mode & 0o777).toString(8),
+        mode === undefined ? "-" : (mode & 0o7777).toString(8),
         createIfAbsent ? "no-replace" : "replace",
         expectedVersion ?? "-",
         content,

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, windowsToLinuxMount } 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";
@@ -534,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);
@@ -546,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
@@ -929,7 +951,7 @@ export class WslFileSystem extends LocalFileSystem {
    * @returns {Promise<WslAgent>} the agent to publish through.
    */
   async mutationAgent(policy) {
-    if (!policy || !this.config.sandbox || policy.mode === "danger-full-access") {
+    if (!isConfinedMutation({ policy, sandboxEnabled: this.config.sandbox })) {
       return this.publicationAgent();
     }
     const distro = await this.distro();
@@ -955,8 +977,8 @@ export class WslFileSystem extends LocalFileSystem {
   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 = error instanceof Error ? error.message : String(error);
-    return new FsError(`the distro file substrate is unavailable: ${message}`, "FS_IO_ERROR", { cause: error instanceof Error ? error : undefined });
+    const { message, code, cause } = substrateFailure(error);
+    return new FsError(message, code, cause === undefined ? {} : { cause });
   }
 
   /**
@@ -994,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;
   }
@@ -1053,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);
   }
 
   /**
@@ -1297,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);
   }
 
   /**

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/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,

package/locale/auto-preset/en.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "WSL preset auto-selection",
+    "description": "Binds the WSL preset to a new session whose workspace directory is inside a distro, and never overrides an explicit operator choice."
+  }
+}

package/locale/auto-preset/zh.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "WSL preset 自动选择",
+    "description": "当新会话的工作目录位于发行版内时，为它绑定 WSL preset；操作者的显式选择不会被覆盖。"
+  }
+}

package/locale/en.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "WSL execution environment",
+    "description": "Runs a DeepSeek Harness session against a WSL distro: shell, file reads/writes and command execution happen inside the distro, the directory picker and the GUI terminal target distro paths, and commands are confined by in-distro bubblewrap."
+  }
+}

package/locale/picker/en.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "WSL-aware directory picker",
+    "description": "The workspace picker for both worlds: its root level lists the Windows home directory and every installed distro, so host and WSL workspaces share one dialog. The directory it returns is what auto-preset reads to choose the environment."
+  }
+}

package/locale/picker/zh.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "WSL 目录选择器",
+    "description": "同时服务主机与 WSL 两个世界的工作区选择器：根层级列出 Windows 主目录和每个已安装的发行版，两类工作区共用同一个对话框。它返回的目录也是 auto-preset 选择执行环境的依据。"
+  }
+}

package/locale/shell-env/en.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "WSL shell environment facts",
+    "description": "Contributes the WSL environment's facts (distro, real login shell, home, listening ports) to the managed DSH_* namespace injected into every model shell call — for sessions whose workspace is inside a distro."
+  }
+}

package/locale/shell-env/zh.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "WSL shell 环境事实",
+    "description": "把 WSL 环境的事实（发行版、真实登录 shell、home、监听端口）贡献给注入每次模型 shell 调用的 DSH_* 托管命名空间——只对工作区位于发行版内的会话生效。"
+  }
+}

package/locale/subprocess/en.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "WSL subprocess provider",
+    "description": "The composition-level ctx.subprocess backend: rewrites the GUI terminal's wsl.exe launch into the pinned distro and Linux directory, so the right-hand terminal window opens inside WSL."
+  }
+}

package/locale/subprocess/zh.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "WSL 子进程提供者",
+    "description": "组合级的 ctx.subprocess 后端：把 GUI 终端的 wsl.exe 启动改写到指定发行版与 Linux 目录，让右侧终端窗口直接落在 WSL 里。"
+  }
+}

package/locale/zh.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "WSL 执行环境",
+    "description": "让 DeepSeek Harness 以 WSL 子系统作为会话的执行环境：shell、文件读写与命令执行均在子系统内完成，目录选择器与 GUI 终端同样定位到子系统路径，并通过子系统内的 bubblewrap 对命令进行沙箱隔离"
+  }
+}