dsh-plugin-wsl-env 0.4.0 → 0.6.0

package/lib/index.js

@@ -580,7 +580,7 @@ export class WslShellExecutor extends LocalBashExecutor {
   async executeViaAgent(resolved, distro, shell) {
     const policy = resolved.sandboxPolicy;
     const confined = this.sandbox !== undefined && policy !== undefined && policy.mode !== "danger-full-access"
-      ? await this.sandbox.confine(this.distroArgv(resolved, shell), { ...policy, mode: policy.mode }, { distro })
+      ? await this.sandbox.confine(this.distroArgv(resolved, shell), { ...policy, mode: policy.mode }, { distro, signal: resolved.signal })
       : undefined;
     const mode = policy?.mode;
     const execution = agentExecutionHandle({
@@ -788,6 +788,15 @@ export class WslFileSystem extends LocalFileSystem {
      * distinct failing path, cached.
      */
     resolveSymlinks: z.boolean().default(true),
+    /**
+     * How deep the in-distro watch scan walks, `1` = the watched directory and
+     * its direct children. `0` — the default — walks the whole tree, which is
+     * what the invalidation contract asks for but a real cost every poll over
+     * a tree containing a `node_modules`; a bound trades that cost for a
+     * documented blind spot: a change below the bound is not seen until
+     * another change above it fires the same callback.
+     */
+    watchMaxDepth: z.natural().default(0),
     /**
      * Run the in-distro side of publication (mode copy + atomic rename) through
      * the resident agent (`agent/wsl-agent.sh`), one round trip instead of a
@@ -799,15 +808,17 @@ export class WslFileSystem extends LocalFileSystem {
     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.
+     * the resident in-distro agent (`lib/fs-substrate.js`): reads, writes and
+     * identities 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, and `watch()` rides the
+     * same in-distro poll loop for both (`lib/watcher.js`) — it never runs
+     * through either substrate. Neither substrate changes `sandboxMode`'s
+     * honesty.
      */
     substrate: z.union(["share", "agent"]).default("agent"),
   });
@@ -1283,6 +1294,10 @@ export class WslFileSystem extends LocalFileSystem {
    * they bump the parent directory's mtime. Replaces the previous flat
    * refusal (`FS_IO_ERROR`), which was the correct answer over 9p only.
    *
+   * A target that disappears mid-watch ends the loop with a report through
+   * `changed` — never the armed-but-never-fires silence a missing directory
+   * would otherwise produce. The scan's depth is `watchMaxDepth`.
+   *
    * @param target - the resolved file or directory to observe.
    * @param changed - the invalidation callback.
    * @param signal - cancels initialization; the caller closes an armed watcher.
@@ -1302,6 +1317,7 @@ export class WslFileSystem extends LocalFileSystem {
       onChange: changed,
       onError: (error) => changed(error),
       signal,
+      maxDepth: this.config.watchMaxDepth,
     });
   }
 

package/lib/sandbox-core.js

@@ -0,0 +1,157 @@
+/**
+ * The sandbox's probe and confinement logic, free of DSH peers.
+ *
+ * `lib/sandbox.js` binds this core to the peer's `SandboxUnavailableError` —
+ * the class identity `instanceof` consumers match — which is the ONLY thing
+ * that kept the whole policy out of unit tests: a checkout without the peers
+ * could not even import the module, so CI skipped every check of the probe
+ * caching policy and the argv composition. The core takes the error class as
+ * the one injected dependency; the tests inject a stand-in with the same
+ * contract (`code: "SANDBOX_UNAVAILABLE"`), and what CI runs is the code that
+ * ships.
+ *
+ * @module dsh-plugin-wsl/sandbox-core
+ */
+
+import { createProbeCache } from "./probe-cache.js";
+import { toLinuxPath } from "./paths.js";
+import { runCapture } from "./wsl.js";
+import { bwrapArgvPrefix } from "./bwrap.js";
+
+/**
+ * bwrap's denial dialect: a write outside the granted mounts fails with EROFS,
+ * whose message is "Read-only file system". Classified case-insensitively.
+ */
+const DENIAL_SIGNATURES = ["read-only file system"];
+
+/**
+ * Runner-side diagnostics. Bubblewrap reports its own failures with a `bwrap: `
+ * prefix and exits 1; exit status alone never proves runner failure (the
+ * upstream rule is signature-only for exactly that reason), so a confined
+ * command that merely prints the signature is not misread as "never ran".
+ */
+const RUNNER_FAILURE_RULES = [{ fatalSignatures: ["bwrap: "] }];
+
+/**
+ * Enforcement is **partial**, not `full` like upstream's Linux rung.
+ *
+ * `SandboxMode` governs file effects. A Linux process under bwrap is fully
+ * governed — but a WSL distro process can execute a *Windows* binary through
+ * interop (`/mnt/c/**\*.exe`), and that Windows process runs outside the Linux
+ * sandbox entirely, under the user's ordinary Windows token: it can write
+ * anywhere the user can. `npm run probe:sandbox` demonstrates it. Claiming
+ * `full` would advertise a boundary that does not hold, so the provider reports
+ * the honest `partial` and README states where the hole is.
+ */
+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`,
+ * where it is unit-testable without the peers this module needs.
+ */
+const probeVerdicts = createProbeCache();
+
+/**
+ * Build the sandbox class, bound to one unavailable-error implementation.
+ *
+ * @param {object} deps - the injected peer surface.
+ * @param {new (mode: string, detail: string) => Error} deps.SandboxUnavailableError
+ *   the failure type `confine` throws; production binds the peer's class so
+ *   `instanceof` consumers keep matching, tests bind a stand-in with the same
+ *   `code`.
+ * @returns {typeof WslSandboxCore} the sandbox class (see `lib/sandbox.js` for
+ *   the shipped binding).
+ */
+export function createSandboxCore({ SandboxUnavailableError }) {
+  return class WslSandboxCore {
+    /**
+     * @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;
+    }
+
+    /**
+     * Whether `bwrap` can create a profile inside this distro. The probe mirrors
+     * upstream's: apply the real read-only profile around `true`, and treat a zero
+     * exit as the kernel having accepted and enforced it. A missing `bwrap` fails the
+     * spawn and probes unusable, which is what makes the provider fail closed rather
+     * than silently run unconfined.
+     *
+     * A success is remembered for the process lifetime; a failure is not, so a
+     * `bubblewrap` installed while the app is running is believed on the next
+     * command.
+     *
+     * @param distro - the distro to probe.
+     * @param signal - optional cancellation.
+     * @returns true when a confined command can run there.
+     */
+    async usable(distro, signal) {
+      const key = `${this.wslPath}\u0000${distro}`;
+      return probeVerdicts.run(key, async () => {
+        const prefix = bwrapArgvPrefix({ mode: "read-only", workspaceRoot: "/" });
+        await runCapture([this.wslPath, "-d", distro, "--exec", ...prefix, "true"], signal);
+        return true;
+      });
+    }
+
+    /**
+     * Wrap one distro-side argv in the bwrap profile the policy asks for.
+     *
+     * The policy's `workspaceRoot` arrives in whichever coordinate system the
+     * caller speaks — a session workspace is a UNC path — and is translated into the
+     * Linux path `bwrap` must bind inside the distro.
+     *
+     * @param argv - the argv to run INSIDE the distro (shell, its flags, command).
+     * @param policy - the resolved confined policy (`mode` is never
+     *   `danger-full-access`; the caller does not confine that case at all).
+     * @param options - the distro to run in and optional cancellation.
+     * @returns the wrapped argv plus the settlement-classification facts, in the
+     *   seam's `ConfinedArgv` shape.
+     * @throws SandboxUnavailableError when the distro has no usable `bwrap`, so a
+     *   requested confinement never degrades into an unconfined run.
+     */
+    async confine(argv, policy, options) {
+      const { distro, signal } = options;
+      if (!(await this.usable(distro, signal))) {
+        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`,
+        );
+      }
+      const workspaceRoot = toLinuxPath(policy.workspaceRoot, { distro });
+      const prefix = bwrapArgvPrefix({ ...policy, workspaceRoot }, { maskWindowsDrive: this.maskWindowsDrive });
+      return {
+        argv: [...prefix, ...argv],
+        enforcement: ENFORCEMENT,
+        denialSignatures: DENIAL_SIGNATURES,
+        runnerFailureRules: RUNNER_FAILURE_RULES,
+        windowsDrive: this.maskWindowsDrive ? "masked" : "visible",
+      };
+    }
+  };
+}

package/lib/sandbox.js

@@ -23,148 +23,28 @@
  * The profile arguments, the denial dialect and the runner-failure rules mirror
  * `@deepseek-ai/dsh-sandbox-local`'s `bwrap` rung, so a denial reads the same to
  * the tool layer whether the command ran on a Linux host or inside a distro.
- * The one deliberate difference is {@link ENFORCEMENT}: see its doc.
+ * The one deliberate difference is the core's `partial` enforcement: see
+ * `lib/sandbox-core.js` for what it reports and why.
+ *
+ * The class itself lives in `lib/sandbox-core.js`, free of DSH peers — this
+ * module is the shipped binding that hands it the peer's `SandboxUnavailableError`,
+ * so `instanceof` consumers keep matching the class their composition knows.
  *
  * @module dsh-plugin-wsl/sandbox
  */
 
 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";
+import { createSandboxCore } from "./sandbox-core.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,
- * whose message is "Read-only file system". Classified case-insensitively.
- */
-const DENIAL_SIGNATURES = ["read-only file system"];
+export { bwrapProfileArgs } from "./bwrap.js";
 
 /**
- * Runner-side diagnostics. Bubblewrap reports its own failures with a `bwrap: `
- * prefix and exits 1; exit status alone never proves runner failure (the
- * upstream rule is signature-only for exactly that reason), so a confined
- * command that merely prints the signature is not misread as "never ran".
+ * The confinement over WSL: the probe-then-confine class bound to the peer's
+ * failure type. See the core module for the probe policy and the profile.
  */
-const RUNNER_FAILURE_RULES = [{ fatalSignatures: ["bwrap: "] }];
-
-/**
- * Enforcement is **partial**, not `full` like upstream's Linux rung.
- *
- * `SandboxMode` governs file effects. A Linux process under bwrap is fully
- * governed — but a WSL distro process can execute a *Windows* binary through
- * interop (`/mnt/c/**\*.exe`), and that Windows process runs outside the Linux
- * sandbox entirely, under the user's ordinary Windows token: it can write
- * anywhere the user can. `npm run probe:sandbox` demonstrates it. Claiming
- * `full` would advertise a boundary that does not hold, so the provider reports
- * the honest `partial` and README states where the hole is.
- */
-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`,
- * where it is unit-testable without the peers this module needs.
- */
-const probeVerdicts = createProbeCache();
-
-/**
- * Confine commands inside one distro with `bwrap`.
- *
- * The policy's `workspaceRoot` arrives in whichever coordinate system the
- * caller speaks — a session workspace is a UNC path — and is translated into the
- * Linux path `bwrap` must bind inside the distro.
- */
-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;
-  }
-
-  /**
-   * Whether `bwrap` can create a profile inside this distro. The probe mirrors
-   * upstream's: apply the real read-only profile around `true`, and treat a zero
-   * exit as the kernel having accepted and enforced it. A missing `bwrap` fails the
-   * spawn and probes unusable, which is what makes the provider fail closed rather
-   * than silently run unconfined.
-   *
-   * A success is remembered for the process lifetime; a failure is not, so a
-   * `bubblewrap` installed while the app is running is believed on the next
-   * command.
-   *
-   * @param distro - the distro to probe.
-   * @param signal - optional cancellation.
-   * @returns true when a confined command can run there.
-   */
-  async usable(distro, signal) {
-    const key = `${this.wslPath}\u0000${distro}`;
-    return probeVerdicts.run(key, async () => {
-      const prefix = bwrapArgvPrefix({ mode: "read-only", workspaceRoot: "/" });
-      await runCapture([this.wslPath, "-d", distro, "--exec", ...prefix, "true"], signal);
-      return true;
-    });
-  }
-
-  /**
-   * Wrap one distro-side argv in the bwrap profile the policy asks for.
-   *
-   * @param argv - the argv to run INSIDE the distro (shell, its flags, command).
-   * @param policy - the resolved confined policy (`mode` is never
-   *   `danger-full-access`; the caller does not confine that case at all).
-   * @param options - the distro to run in and optional cancellation.
-   * @returns the wrapped argv plus the settlement-classification facts, in the
-   *   seam's `ConfinedArgv` shape.
-   * @throws SandboxUnavailableError when the distro has no usable `bwrap`, so a
-   *   requested confinement never degrades into an unconfined run.
-   */
-  async confine(argv, policy, options) {
-    const { distro, signal } = options;
-    if (!(await this.usable(distro, signal))) {
-      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`,
-      );
-    }
-    const workspaceRoot = toLinuxPath(policy.workspaceRoot, { distro });
-    const prefix = bwrapArgvPrefix({ ...policy, workspaceRoot }, { maskWindowsDrive: this.maskWindowsDrive });
-    return {
-      argv: [...prefix, ...argv],
-      enforcement: ENFORCEMENT,
-      denialSignatures: DENIAL_SIGNATURES,
-      runnerFailureRules: RUNNER_FAILURE_RULES,
-      windowsDrive: this.maskWindowsDrive ? "masked" : "visible",
-    };
-  }
-}
+export const WslSandbox = createSandboxCore({ SandboxUnavailableError });
 
 export default WslSandbox;

package/lib/watcher.js

@@ -14,6 +14,16 @@
  * one `C` line per hit. No `inotifywait` dependency; the mtime walk is exact
  * for interactive-paced edits, which is the only pace a session watch serves.
  *
+ * The loop speaks three one-letter lines, the watcher protocol:
+ *
+ *   - `R` — READY: the activation barrier; the host resolves the watch promise
+ *     on it, never before.
+ *   - `C` — CHANGED: something under the target may have changed.
+ *   - `E` — ERROR: the watched directory no longer exists, and the loop has
+ *     exited. Without it a vanished target would sit armed forever — `find`
+ *     over a missing directory prints nothing, indistinguishable from "no
+ *     changes" — so the loop says so and the host reports it.
+ *
  * Known blind spot, accepted and documented: a file created with an mtime
  * older than the stamp (`cp -p`, `tar -x`) is not seen until something else
  * touches the tree.
@@ -29,29 +39,47 @@ import { createInterface } from "node:readline";
  * quoting: `$1` is the Linux directory, `$2` the poll interval in seconds.
  * Pure text, so it is unit-testable.
  * @param {number} [intervalSeconds] - poll cadence; must be >= 1.
+ * @param {number} [maxDepth] - bound the scan's depth, 1 = the directory
+ *   itself and its direct children; 0 (the default) scans the whole tree,
+ *   which is the contract's semantics but a real cost over a tree with a
+ *   `node_modules` in it.
  * @returns {string} the `sh -c` script body.
  */
-export function watchLoopScript(intervalSeconds = 2) {
+export function watchLoopScript(intervalSeconds = 2, maxDepth = 0) {
   const seconds = Math.max(1, Math.floor(intervalSeconds));
+  const depth = Number.isInteger(maxDepth) && maxDepth >= 1 ? maxDepth : 0;
+  // A bounded walk puts `-maxdepth` directly after the path, where every find
+  // that supports it (GNU, BusyBox, BSD) accepts it as a global option.
+  const depthArgs = depth > 0 ? ` -maxdepth ${depth}` : "";
   // `find` lists the directory itself first: a child's creation or deletion
   // bumps the parent's mtime, so both edges are seen, not just modifications.
   return [
     'D="$1"',
     'S="${TMPDIR:-/tmp}/wsl-watch.$$.stamp"',
     'touch "$S"',
+    // The stamp is the loop's private state, so every way out removes it. The
+    // EXIT trap covers plain exits; a signal alone would end the shell WITHOUT
+    // running it, so TERM/INT/HUP are trapped to a plain exit first.
+    "trap 'rm -f \"$S\"' EXIT",
+    "trap 'exit 0' TERM INT HUP",
     // The READY line is the activation barrier: everything changed BEFORE it
     // predates the stamp, so the host must not resolve the watch promise until
     // it arrives — otherwise a write racing the first tick is invisible forever.
-    'printf \'R\\n\'',
+    "printf 'R\\n'",
     // Check first, sleep second: a change made right after activation is seen
     // on the first cadence, not one cadence later.
-    'while :; do',
-    '  if [ -n "$(find "$D" -newer "$S" -print -quit 2>/dev/null)" ]; then',
+    "while :; do",
+    '  if [ ! -d "$D" ]; then',
+    // Say so and die: silence here is the armed-forever, fires-never trap.
+    "    printf 'E\\n'",
+    "    exit 1",
+    "  fi",
+    `  if [ -n "$(find "$D"${depthArgs} -newer "$S" -print -quit 2>/dev/null)" ]; then`,
     '    touch "$S"',
-    '    printf \'C\\n\'',
-    '  fi',
+    "    printf 'C\\n'",
+    "  fi",
     `  sleep ${seconds}`,
-    'done',
+    "done",
   ].join("\n");
 }
 
@@ -63,26 +91,42 @@ export function watchLoopScript(intervalSeconds = 2) {
  * @param {string} options.distro - the distro to watch inside.
  * @param {string} options.linuxPath - the absolute Linux path to observe.
  * @param {(error: Error) => void} [options.onError] - watcher-level failures
- *   (an exited loop); the seam reports these through its own channel.
+ *   (an exited loop, a vanished target); the seam reports these through its
+ *   own channel.
  * @param {() => void} options.onChange - the invalidation callback.
  * @param {AbortSignal} options.signal - cancels initialization; the CALLER
  *   invokes the returned close to stop an armed watcher.
  * @param {number} [options.intervalSeconds] - poll cadence, default 2.
+ * @param {number} [options.maxDepth] - scan depth bound, 0 = the whole tree.
  * @param {(wslPath: string, args: string[]) => import("node:child_process").ChildProcess} [options.spawn]
  *   injectable process factory for tests.
  * @returns {Promise<() => Promise<void>>} resolves once observation is active,
  *   with the async close function the seam's contract asks for.
  */
-export function armDistroWatcher({ wslPath, distro, linuxPath, onChange, onError, signal, intervalSeconds = 2, spawn: spawnProcess }) {
+export function armDistroWatcher({ wslPath, distro, linuxPath, onChange, onError, signal, intervalSeconds = 2, maxDepth = 0, spawn: spawnProcess }) {
   const doSpawn = spawnProcess ?? ((path, args) => spawn(path, args, { stdio: ["ignore", "pipe", "pipe"], windowsHide: true }));
   return new Promise((resolve, reject) => {
     if (signal?.aborted) {
       reject(signal.reason instanceof Error ? signal.reason : new Error("aborted"));
       return;
     }
-    const child = doSpawn(wslPath, ["-d", distro, "--exec", "sh", "-c", watchLoopScript(intervalSeconds), "wsl-watch", linuxPath]);
+    const child = doSpawn(wslPath, ["-d", distro, "--exec", "sh", "-c", watchLoopScript(intervalSeconds, maxDepth), "wsl-watch", linuxPath]);
     let settled = false;
     let closed = false;
+    let reported = false;
+    // The loop itself writes nothing to stderr, but `sh` can (a syntax slip in
+    // a future edit) — and an undrained pipe stalls the child at the 64KB
+    // buffer limit, which would look exactly like a silently-dead watch. So
+    // the pipe is drained continuously and the tail kept for error context.
+    let stderrTail = "";
+    child.stderr?.setEncoding("utf8");
+    child.stderr?.on("data", (chunk) => {
+      stderrTail = `${stderrTail}${chunk}`.slice(-4096);
+    });
+    const describe = (message) => {
+      const detail = stderrTail.trim();
+      return detail.length > 0 ? `${message}: ${detail}` : message;
+    };
     const lines = createInterface({ input: child.stdout });
     lines.on("line", (line) => {
       if (line === "R") {
@@ -92,6 +136,10 @@ export function armDistroWatcher({ wslPath, distro, linuxPath, onChange, onError
         }
         return;
       }
+      if (line === "E") {
+        fail(new Error(describe(`the watched directory "${linuxPath}" no longer exists inside "${distro}", so the watch has ended`)));
+        return;
+      }
       if (line === "C") {
         onChange();
       }
@@ -109,6 +157,10 @@ export function armDistroWatcher({ wslPath, distro, linuxPath, onChange, onError
       });
     };
     const fail = (error) => {
+      // One report per watcher lifetime: the loop's E line is followed by its
+      // own exit, and both must not reach the seam's error channel.
+      if (reported || closed) return;
+      reported = true;
       if (settled) {
         onError?.(error);
         return;
@@ -120,8 +172,7 @@ export function armDistroWatcher({ wslPath, distro, linuxPath, onChange, onError
     signal?.addEventListener("abort", () => fail(signal.reason instanceof Error ? signal.reason : new Error("aborted")), { once: true });
     child.on("error", fail);
     child.on("exit", (code, signalName) => {
-      if (!closed) fail(new Error(`distro watcher exited unexpectedly (code=${code} signal=${signalName ?? "none"})`));
+      fail(new Error(`distro watcher exited unexpectedly (code=${code} signal=${signalName ?? "none"})`));
     });
-
   });
 }

package/lib/wsl.js

@@ -15,6 +15,18 @@ import { posixToUnc } from "./paths.js";
 /** Default executable name; resolution is left to PATH. */
 export const DEFAULT_WSL_PATH = "wsl.exe";
 
+/**
+ * The deadline every `wsl.exe` call runs under, when the caller names none.
+ *
+ * A resolution call that never returns is worse than a failed one: `wsl.exe`
+ * talks to the vmcompute service, and a wedged service would hang the tool
+ * call forever — no timeout, no error, a silent dead session. Every call now
+ * dies loudly instead. The bound is deliberately generous (a cold distro boot
+ * on a slow disk is tens of seconds), and `0` disables it for a caller that
+ * genuinely wants to wait forever.
+ */
+export const DEFAULT_WSL_DEADLINE_MS = 60_000;
+
 /**
  * Run one host command and capture UTF-8 output.
  *
@@ -24,16 +36,18 @@ export const DEFAULT_WSL_PATH = "wsl.exe";
  *
  * @param argv - executable plus arguments, spawned without a shell.
  * @param signal - optional cancellation.
+ * @param deadlineMs - kill the call after this many milliseconds; the default
+ *   is {@link DEFAULT_WSL_DEADLINE_MS}, and `0` waits forever.
  * @returns captured stdout.
  * @throws the execFile error, with a hint attached when the cause is the sandbox.
  */
-export function runCapture(argv, signal) {
+export function runCapture(argv, signal, deadlineMs = DEFAULT_WSL_DEADLINE_MS) {
   const [file, ...args] = argv;
   return new Promise((resolve, reject) => {
     execFile(
       file,
       args,
-      { env: { ...process.env, WSL_UTF8: "1" }, windowsHide: true, signal, encoding: "utf8" },
+      { env: { ...process.env, WSL_UTF8: "1" }, windowsHide: true, signal, encoding: "utf8", timeout: deadlineMs },
       (error, stdout, stderr) => {
         if (error) {
           // A denied WSL call is the likeliest failure here and its own message
@@ -41,6 +55,10 @@ export function runCapture(argv, signal) {
           const detail = `${stdout ?? ""}${stderr ?? ""}`.replace(/\u0000/g, "").trim();
           const denied = /E_ACCESSDENIED/i.test(detail) || error.code === "EACCES";
           const missing = error.code === "ENOENT";
+          // The deadline kill arrives as a SIGTERM with no WSL diagnostic, so
+          // it must be named for what it is — not left looking like WSL's own
+          // failure. An abort is cancellation, not a deadline.
+          const stuck = error.killed === true && error.name !== "AbortError";
           error.message = `${file} failed: ${detail || error.message}${
             denied
               ? " (WSL is unreachable from a sandboxed process: DSH's Windows ACL sandbox runs commands under a restricted low-integrity token. Compose the non-sandboxing providers.)"
@@ -49,6 +67,10 @@ export function runCapture(argv, signal) {
             missing
               ? ` (the executable "${file}" could not be started: check \`wslPath\` in this row, and that WSL is installed)`
               : ""
+          }${
+            stuck
+              ? ` (no completion within ${deadlineMs}ms — the WSL service may be wedged; retry once, then \`wsl.exe --shutdown\` and reopen)`
+              : ""
           }`;
           reject(error);
           return;

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."
+  }
+}