dsh-plugin-wsl-env 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -12,6 +12,135 @@ reference below points at that record's numbering.
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-10-03
+
+One theme: the enterprise review's remediation cycle completes. The
+security-decision layer gains its own peer-free module and unit tests, the
+coverage gate measures every unit file again, the fallback invariant is probed
+for real, and the file tools pick up the audit's fixes — a killed write no
+longer strands state, large reads stream instead of staging, `/tmp` writes
+land where readers read, cross-distro workdirs are refused, the resident's
+Windows environment is pinned, and `maskWindowsDrive` offers the interop
+mitigation.
+
+### Added
+
+- **The filesystem provider's policy decisions are a peer-free module with
+  their own unit tests.** The security-decision layer — which paths are
+  refused for naming another distro, which mode denies a mutation outright,
+  which write guards refuse which intents, how a substrate failure maps onto
+  the surfaced refusal, and whether a mutation routes to the confined
+  resident — used to live inline in `lib/index.js`, a file no unit test can
+  import. It is now `lib/fs-decisions.js` (pure in, refusal descriptor out,
+  byte-identical messages), with `test/fs-decisions.test.mjs` covering every
+  branch, and `lib/index.js` delegating at one `FsError` choke point.
+
+### Fixed
+
+- **The fallback invariant is now probed, not just promised.** PARITY.md's
+  hard rule — "`agent: false` must behave like the pre-agent release" — cited
+  a probe leg that did not exist, and spelled the key as `wsl.agent: 'off'`
+  when it is a boolean. `test/probe/agent.sh` now runs the same operations
+  through the resident AND through the one-shot `wsl.exe` path and compares
+  outcomes: exit code and stdout bytes (including `$`-metacharacters), stderr
+  and working directory, and NUL/CRLF binary safety. All three legs pass
+  against a real distro; the doc now names the key correctly and describes
+  what the probe actually compares.
+
+- **The coverage gate measures every unit file again.** `test:coverage` listed
+  six of the sixteen test files — the thresholds (85/85/70) were met by the
+  narrowed set while the full suite sat at 82.45% branches, so branch
+  regressions anywhere outside the six were invisible to the gate that claimed
+  to guard them. The gate now runs the whole unit suite (95.83% lines / 85.95%
+  branches / 91.01% functions), which got there the honest way: new tests for
+  the seams the audit found dark — the deny-dialect classification,
+  aborted-signal mapping, the transport env pin, handshake mismatch, protocol
+  garbage, cwd rejections, pre-aborted signals, idle retirement, mid-flight
+  over-cap buffers, failed rebuilds, watcher teardown and error paths, the
+  cross-distro workdir predicate, staging sweeps, setuid publication, and the
+  real-`/tmp` consistency the file tools now have.
+
+- **Reading a large file no longer copies its remainder to a temp file for
+  every window.** `fs_read` staged `tail -c +offset` to disk before `head`
+  took the requested bytes — so a full read of a 1 GB file performed ~1000
+  window round trips AND ~500 GB of aggregate temp-file writes inside the
+  distro, and a window that took over 30 seconds died as an opaque
+  "distro I/O failure". The remainder now streams through a `tail | head`
+  pipe (the request's own bound is the only staging), read failures still
+  classify through the same stderr dialect, and windowed reads are verified
+  byte-exact including the final partial window.
+- **A request the transport cannot deliver now fails its caller instead of
+  stranding it.** `writeLines` used to drop a frame silently when the
+  `wsl.exe` process was gone (a thin race between exit handling and the next
+  request), leaving a pending entry nothing would ever answer — the caller
+  waited forever when it had no timeout, and the watchdog had no process
+  left to kill. An undeliverable frame now rejects with
+  `AgentUnavailableError` ("the agent exited before the request could be
+  sent; it never ran"), the rebuild relay fails undeliverable re-sends the
+  same way, and `close()` no longer writes `SHUTDOWN` into an ended stdin
+  (whose async write-after-end error could crash the process during its own
+  shutdown).
+
+- **A confined write to `/tmp` now lands in the distro's real `/tmp`, where
+  every reader reads.** The fence grants `/tmp` as a writable root, but the
+  confined resident's profile mounted an ephemeral tmpfs over it — so the
+  write reported success into a private tmpfs, the read tools (unconfined)
+  could not see it, the post-write stat produced a `missing:` version that
+  made the next edit fail with `FS_STALE_VERSION`, and the file evaporated
+  when the resident retired. The file-writes resident's profile now binds the
+  real `/tmp` read-write (`realTmp`, on by default for the confined factory):
+  the write lands where the fence said it would, reads and edits agree, and
+  user terminals see the file. Commands keep their ephemeral per-run tmpfs —
+  the fresh-temp-area property (and its anti-poisoning guarantee) is
+  unchanged, so a command still cannot see files the write tools placed in
+  `/tmp` — the documented command-vs-tools split, now safe in both
+  directions. Verified live: confined write → plain read returns the content;
+  a confined `cat` still reports it absent, as documented.
+
+- **A killed write no longer leaves its staging directory in your files.** A
+  `KILL`/`SIGTERM` mid-write could not be trapped, so the private 0700
+  staging dir (`.<name>.<pid>.<rand>.tmpdir`) sat in the target's own
+  directory forever — and listings showed the debris to the model. The EXIT
+  trap now removes the in-flight staging along with the agent's temp dir, and
+  each write sweeps the target directory's leftovers whose creating agent's
+  PID (it rides the name) is no longer running — a live agent's staging is
+  left alone, PID reuse included.
+- **A write to a typo'd path refuses instead of materializing the chain.**
+  The staging `mkdir -p` silently created every missing parent directory and
+  reported success, where the peer's Node-fs publication fails `ENOENT` —
+  masking model errors as wins. Parents are no longer created: the refusal is
+  `FS_NOT_FOUND`, an existing directory stays fine, and a concurrent creator
+  of the directory still wins.
+- **Setuid, setgid and sticky bits survive an overwrite or edit.** The mode
+  was masked to `0o777` at the stat parse and again at the write, so a
+  `4755` binary became `755` and a `1777` directory file lost its sticky bit
+  — while LIMITATIONS claimed the bits were kept. The full mode now rides
+  stat and write end-to-end (`0o7777`), matching the share substrate's
+  `chmod --reference` behaviour.
+
+- **A shell command whose workdir names another WSL distro is refused, where
+  it used to run in the pinned distro against whatever tree shares the path.**
+  `toLinuxPath` strips a `\\wsl.localhost\<name>\…` UNC's distro name, and the
+  shell executor never compared it — so a `debian` workspace's commands ran
+  inside the pinned `ubuntu`, silently, while the fs side refused the same
+  workspace with `FS_OUTSIDE_DISTRO` ("open a session in that distro" — which
+  the user had done). The shell now refuses with the fs side's wording, and
+  the shell-env facts stay silent for a foreign-distro session instead of
+  presenting another distro's home and shell as this session's.
+
+- **The resident agent no longer inherits the Windows environment's WSLENV
+  forwarding.** Spawned bare, `wsl.exe` carried this process's whole
+  environment with it, and whatever the user's `WSLENV` names — dev machines
+  routinely route secrets (`GITHUB_TOKEN/u` is the documented example) — was
+  forwarded into the distro, where every model command inherited it. The
+  transport's Windows env is now pinned: the essentials `wsl.exe` itself
+  needs, the managed `DSH_*` facts, `WSL_UTF8=1`, and a `WSLENV` that names
+  only the managed entries with their original flags. Verified live: a secret
+  injected on the Windows side with a forwarding flag appears zero times in
+  the distro environment. `forwardEnv` remains one-shot-only today — the
+  resident path never forwarded it, and the pin keeps that posture instead of
+  widening it silently.
+
 ### Added
 
 - **`maskWindowsDrive` on `wsl-shell` and `wsl-fs`** — the mitigation knob for

package/agent/wsl-agent.sh

@@ -57,11 +57,15 @@ PROTO_VERSION=3
 TMPDIR_AGENT=$(mktemp -d "${TMPDIR:-/tmp}/wsl-agent.XXXXXX")
 OUT_FILE="$TMPDIR_AGENT/out"
 ERR_FILE="$TMPDIR_AGENT/err"
-trap 'rm -rf "$TMPDIR_AGENT"; exit 0' EXIT
+trap 'rm -rf "$TMPDIR_AGENT"; [ -z "${CURRENT_STAGING:-}" ] || rm -rf -- "$CURRENT_STAGING"; exit 0' EXIT
 
 # The request currently in flight, for KILL and for the exit trap.
 CURRENT_PID=
 CURRENT_ID=
+# The staged-publication directory of an in-flight FS write. TERM/INT would
+# otherwise orphan it inside the target's own directory; a KILL cannot be
+# trapped, which is what the sweep in fs_write is for.
+CURRENT_STAGING=
 
 b64dec() {
   # `base64 -d` with GNU and BusyBox spellings; a decode failure yields empty.
@@ -256,18 +260,22 @@ fs_realpath() {
 fs_read() {
   # $1 = base64 path, $2 = base64 byte offset, $3 = base64 max bytes. The
   # window is the bound: at most $3 bytes leave the distro per request; the
-  # host loops.
-  local p offset max rd err
+  # host loops. The remainder is STREAMED through the pipe, never staged —
+  # staging copied the whole tail to a temp file once per window, which made
+  # a full read of a large file quadratic in the file's own size. tail's
+  # stderr lands in ERR_FILE (its SIGPIPE death once `head` has had its fill
+  # writes nothing there), so a real read failure is still classified.
+  local p offset max err
   p=$(b64dec "$1")
   offset=$(b64dec "$2")
   max=$(b64dec "$3")
   [ "$max" -gt 0 ] || return 0
-  rd="$TMPDIR_AGENT/read"
-  tail -c +"$(( offset + 1 ))" -- "$p" >"$rd" 2>"$ERR_FILE" || {
+  : >"$ERR_FILE"
+  tail -c +"$(( offset + 1 ))" -- "$p" 2>"$ERR_FILE" | head -c "$max" -- 2>/dev/null
+  if [ -s "$ERR_FILE" ]; then
     err=$(cat "$ERR_FILE")
     fs_fail "$(fs_classify "$err")" "$err"
-  }
-  head -c "$max" -- "$rd"
+  fi
 }
 
 norm_time() {
@@ -299,6 +307,30 @@ fs_version() {
   printf '%s:%s:%s:%s:%s' "$dev" "$ino" "$size" "$(norm_time "$mtime")" "$(norm_time "$ctime")"
 }
 
+drop_staging() {
+  # Remove the current write's staging dir and forget it, so the EXIT trap
+  # never re-removes (or, worse, removes a newer write's staging) after it.
+  rm -rf -- "$staging"
+  CURRENT_STAGING=
+}
+
+sweep_staging() {
+  # $1 = directory, $2 = base name. Remove this directory's leftover staging
+  # dirs whose creating agent is gone — the PID rides the name, and a process
+  # that is not running cannot clean up after its own KILL. A live PID keeps
+  # its dir (the safe direction, PID reuse included).
+  local d pid
+  for d in "$1/.$2."*.*.tmpdir; do
+    [ -d "$d" ] || continue
+    pid=${d#"$1/.$2."}
+    pid=${pid%%.*}
+    case $pid in
+      ''|*[!0-9]*) continue ;;
+    esac
+    kill -0 "$pid" 2>/dev/null || rm -rf -- "$d"
+  done
+}
+
 fs_write() {
   # $1 = base64 path, $2 = base64 mode (`-` keeps none), $3 = base64
   # `replace` or `no-replace`, $4 = expected version (`-` for none) — the
@@ -315,10 +347,21 @@ fs_write() {
   dir=$(dirname -- "$path")
   base=$(basename -- "$path")
   [ -n "$base" ] && [ "$base" != "/" ] || fs_fail notfound "empty file name"
-  mkdir -p -- "$dir" 2>"$ERR_FILE" || {
-    err=$(cat "$ERR_FILE")
-    fs_fail "$(fs_classify "$err")" "$err"
-  }
+  # Leftover staging dirs from a KILLed write (a KILL cannot be trapped) would
+  # sit in the target's directory forever and show up in listings. The creating
+  # agent's PID rides the name: one whose process is gone is an orphan, so
+  # sweep it before staging this write.
+  sweep_staging "$dir" "$base"
+  if [ ! -d "$dir" ]; then
+    # Deliberately NO `mkdir -p`: a typo'd parent chain must refuse (the peer's
+    # Node-fs publication fails ENOENT there), not materialize silently. An
+    # existing directory after a failed mkdir is a concurrent creator, not an
+    # error.
+    mkdir -- "$dir" 2>"$ERR_FILE" || {
+      err=$(cat "$ERR_FILE")
+      [ -d "$dir" ] || fs_fail "$(fs_classify "$err")" "$err"
+    }
+  fi
   u=$(head -c 8 /dev/urandom 2>/dev/null | od -An -tx1 | tr -d ' \n')
   staging="$dir/.$base.$$.${u:-0}.tmpdir"
   mkdir -- "$staging" 2>"$ERR_FILE" || {
@@ -327,12 +370,13 @@ fs_write() {
     err=$(cat "$ERR_FILE")
     fs_fail "$(fs_classify "$err")" "$err"
   }
+  CURRENT_STAGING=$staging
   chmod 700 -- "$staging" 2>/dev/null
   tmp="$staging/$base.tmp"
   # Decode straight to the file: the base64 text is the one form that crosses
   # a shell variable without a NUL-byte or quoting hazard.
   printf '%s' "$5" | base64 -d >"$tmp" 2>/dev/null || {
-    rm -rf -- "$staging"
+    drop_staging
     fs_fail io "cannot stage content"
   }
   chmod 600 -- "$tmp"
@@ -340,7 +384,7 @@ fs_write() {
   if [ "$mode" != "-" ]; then
     chmod "$mode" -- "$tmp" 2>"$ERR_FILE" || {
       err=$(cat "$ERR_FILE")
-      rm -rf -- "$staging"
+      drop_staging
       fs_fail io "$err"
     }
   fi
@@ -351,7 +395,7 @@ fs_write() {
     # trips the stat/find skew a list-derived version would.
     version=$(fs_version "$path")
     if [ "$version" != "$expected" ]; then
-      rm -rf -- "$staging"
+      drop_staging
       if [ -n "$version" ]; then
         fs_fail stale "cannot write \"$path\": file changed since it was read"
       fi
@@ -363,12 +407,12 @@ fs_write() {
     # it) where the peer's link(2) refuses any existing path, so the existence
     # guard is checked before the call and the landing spot verified after it.
     if [ -e "$path" ] || [ -L "$path" ]; then
-      rm -rf -- "$staging"
+      drop_staging
       fs_fail exists "cannot write \"$path\": it already exists"
     fi
     ln -- "$tmp" "$path" 2>"$ERR_FILE" || {
       err=$(cat "$ERR_FILE")
-      rm -rf -- "$staging"
+      drop_staging
       # A concurrent creator wins the race; classify by what is on disk now.
       if [ -e "$path" ] || [ -L "$path" ]; then
         fs_fail exists "$err"
@@ -379,17 +423,17 @@ fs_write() {
       # ln linked BESIDE the target (a directory appeared under us): undo the
       # stray link and refuse, the guarded create did not publish.
       rm -f -- "$path/${base}.tmp"
-      rm -rf -- "$staging"
+      drop_staging
       fs_fail exists "cannot write \"$path\": it was created concurrently"
     fi
   else
     mv -f -- "$tmp" "$path" 2>"$ERR_FILE" || {
       err=$(cat "$ERR_FILE")
-      rm -rf -- "$staging"
+      drop_staging
       fs_fail "$(fs_classify "$err")" "$err"
     }
   fi
-  rm -rf -- "$staging"
+  drop_staging
 }
 
 fs_dispatch() {

package/docs/LIMITATIONS.md

@@ -22,6 +22,9 @@ host stack over the distro's 9p share. What differs:
   rather than quietly degrading to share semantics that cannot follow symlinks
   or keep mode bits. The share substrate dies with the distro anyway; the
   agent only adds its own failure mode, which is the one honest way to fail.
+  The failure message names the opt-out: set `substrate: "share"` in the
+  provider config to keep working on the Windows-side share while the agent
+  is out.
 - **The mutation guard survives to the write.** `createIfAbsent` publishes with
   a no-replace link inside the distro, which closes the check-then-write window
   for creates outright. An overwrite or edit carries the version it was based
@@ -90,7 +93,10 @@ Everything below applies to the share substrate unless it says otherwise.
 - The check before a write is "check, then write", which is not atomic. This backend
   checks the caller's guard itself, because the Windows backend publishes a guarded
   new file with a hard link, and the share does not support hard links. This is the
-  race that `dsh-fs-sandbox` already documents.
+  race that `dsh-fs-sandbox` already documents — and one reason the share substrate
+  is the documented FALLBACK rather than the main path: its publication rides the
+  unconfined agent, so it never receives the confined resident's kernel-enforced
+  containment. The agent substrate does.
 - `watch()` observes from inside the distro (a `find -newer` poll loop, see
   `lib/watcher.js`), so events are coarse invalidation, not per-file notifications,
   and they arrive on the poll cadence, not instantly. A file created with an mtime

package/docs/PARITY.md

@@ -11,7 +11,7 @@ distro. Everything users love — native ext4 semantics, inotify, native
 `rg`, low latency — is a derivative. This plugin's 9p-UNC plus one-shot
 `wsl.exe` model can only approach it. The plan therefore lands a resident
 in-distro agent and migrates the `fs` and `shell` seams onto it, keeping the
-current paths as the documented fallback (`wsl.agent: 'off'` must equal
+current paths as the documented fallback (`wsl.agent: false` must equal
 today's behaviour byte for byte).
 
 Not applicable, recorded so the gap is a decision and not an omission:
@@ -64,7 +64,8 @@ shaped a phase of the plan.
 
 ## Fallback invariant
 
-Every phase must keep `wsl.agent: 'off'` (and, per capability, any runtime
+Every phase must keep `wsl.agent: false` (and, per capability, any runtime
 fallback) behaviourally identical to the pre-phase release. Probes assert
-this: `agent.sh` runs the same operation with the agent off and on and
-compares outcomes, not internals.
+this: `agent.sh` runs the same operations through the resident and through
+the one-shot `wsl.exe` path and compares outcomes — exit code, stdout bytes,
+stderr bytes, working directory — not internals.

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-plugin-wsl-env",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "让 DeepSeek Harness 以 WSL 子系统作为会话的执行环境：shell、文件读写与命令执行均在子系统内完成，目录选择器与 GUI 终端同样定位到子系统路径，并通过子系统内的 bubblewrap 对命令进行沙箱隔离",
   "keywords": [
     "deepseek-harness",
@@ -51,9 +51,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/probe-cache.test.mjs test/preset-choice.test.mjs",
+    "test:coverage": "node --test --experimental-test-coverage --test-coverage-lines=85 --test-coverage-branches=85 --test-coverage-functions=70 test/agent-exec.test.mjs test/agent-fs-script.test.mjs test/agent-protocol.test.mjs test/agent.test.mjs test/fs-publish.test.mjs test/fs-substrate.test.mjs test/fsio-agent.test.mjs test/listing.test.mjs test/paths.test.mjs test/ports.test.mjs test/preset-choice.test.mjs test/probe-cache.test.mjs test/sandbox.test.mjs test/shell.test.mjs test/terminal.test.mjs test/watcher.test.mjs test/fs-decisions.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/preset-choice.test.mjs test/sandbox.test.mjs test/agent-protocol.test.mjs test/agent.test.mjs test/agent-fs-script.test.mjs test/fsio-agent.test.mjs test/fs-substrate.test.mjs test/fs-publish.test.mjs test/agent-exec.test.mjs test/ports.test.mjs test/watcher.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 test/agent-protocol.test.mjs test/agent.test.mjs test/agent-fs-script.test.mjs test/fsio-agent.test.mjs test/fs-substrate.test.mjs test/fs-publish.test.mjs test/agent-exec.test.mjs test/ports.test.mjs test/watcher.test.mjs test/fs-decisions.test.mjs",
     "lint:style": "node test/style.mjs",
     "prepublishOnly": "npm test",
     "probe": "bash test/probe/run.sh",