dsh-plugin-wsl-env 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -12,6 +12,86 @@ reference below points at that record's numbering.
 
 ## [Unreleased]
 
+## [0.6.0] - 2026-10-04
+
+One theme: the P2 backlog from the 2026-10-03 review, closed with the same
+evidence bar as its P0/P1 — every fix carries a check that fails without it,
+and the real-distro probes run green over the changed paths — plus the
+import-time regression that backlog carried, caught at the first
+sync-and-restart: `watchMaxDepth` was written `z.number().int()`, a member the
+pinned schemastery does not publish, which took `wsl-shell` and `wsl-fs` down
+in every distro workspace session. The key now uses `z.natural()`, and
+`test/syntax.mjs` reads the chained half of the schemastery surface so the
+next such member dies in CI instead of in the app.
+
+### Fixed
+
+- **The in-distro watcher no longer fails silently (review M10).** Four defects
+  in `lib/watcher.js`, fixed together because they share one loop:
+  the stamp file is removed on every way out (EXIT trap; TERM/INT/HUP routed
+  through a plain exit so the trap runs); a target that vanishes mid-watch now
+  ends the loop with a report through the error channel instead of arming
+  forever (`E` protocol line, unit- and probe-tested); the scan's depth is
+  boundable through the new `wsl-fs.watchMaxDepth` key (`0`, the default,
+  keeps the whole-tree walk); and the loop's stderr is drained continuously
+  with its tail kept for error context, so a chatty `sh` can no longer stall
+  the watch at the 64 KiB pipe limit.
+- **`watchMaxDepth` no longer takes both preset rows down at import (a
+  regression the M10 entry above introduced, caught after the first
+  sync-and-restart).** The key was written `z.number().int().min(0)`, but the
+  pinned schemastery publishes no `int` on any schema instance, and a Config
+  schema is a class field — so `lib/index.js` threw
+  `TypeError: z.number(...).int is not a function` while it was still being
+  imported, the loader left `wsl-shell` and `wsl-fs` fiber-less, and the preset
+  audit reported exactly those two rows as `never started`: every session in a
+  distro workspace, new or historical, failed at the first message. The key is
+  now `z.natural().default(0)` — the pinned spelling of "integer >= 0", the
+  idiom `picker` and `auto-preset` already use — and `test/syntax.mjs` now
+  reads the chained half of the schemastery surface (a balanced walk that
+  survives nested call arguments, string literals and template
+  interpolations), so a member the peer does not publish fails the suite
+  instead of waiting for the Desktop app. Reproduced and verified in a
+  peer-stub harness: the `lib/index.js` import went from the `TypeError` to
+  clean with the fix, and the new check fails on the old line.
+- **A wedged WSL service can no longer hang a tool call forever (review M11).**
+  Every `wsl.exe` resolution call in `lib/wsl.js` now runs under a deadline
+  (`DEFAULT_WSL_DEADLINE_MS`, 60 s — generous on purpose for cold boots, `0`
+  waits forever), and the deadline kill is named for what it is in the error,
+  with the `wsl.exe --shutdown` remedy. Separately, the agent execution path's
+  `confine()` now receives the request's abort signal, the same one the
+  one-shot path always passed.
+- **A timed-out command can no longer leave descendants running (review M12).**
+  EXEC requests run as their own session and process group (`setsid`, detected
+  at startup with a documented fallback), and the in-distro timeout and KILL
+  frames signal the whole group — TERM, then KILL after the grace, descendants
+  included. Proven by a new real-script check: a command that backgrounds a
+  marked shell and outlives its budget leaves zero survivors.
+- **Documentation drift cluster (review M9).** ARCHITECTURE.md's service table
+  claimed the share substrate was the default (it is `agent`), pointed at
+  `lib/sandbox.js` for `bwrapProfileArgs` (built in `lib/bwrap.js`), and kept
+  the long-gone `watch()` refusal in the error-code table; the `substrate`
+  schema docstring claimed watches run through the substrate (both substrates
+  ride the same `lib/watcher.js` poll loop); PARITY.md now records the rg
+  interception as designed-but-never-implemented instead of leaving it
+  implied; and the probe checklists (both READMEs, CONTRIBUTING, RELEASING,
+  the PR template, CI's comment) list the agent, watch, substrate and exec
+  probes that had shipped without being listed anywhere.
+
+### Changed
+
+- **Test structure (review M15).** The sandbox checks run everywhere now:
+  the probe-and-confine logic moved to the peer-free `lib/sandbox-core.js`
+  (one implementation, still shipped), `lib/sandbox.js` binds it to the peer's
+  `SandboxUnavailableError`, and the tests inject a stand-in with the same
+  `code` — CI no longer skips them. `FS_SANDBOX_DENIED`'s write-only
+  classification carries three unit checks (write denial classified, the same
+  signature ignored off the write path, ordinary permission failures keep
+  theirs). The probes stopped carrying inline bwrap profiles: `exec.sh` and
+  `sandbox.sh` derive their profiles from `lib/bwrap.js` itself, so a profile
+  change fails the probe instead of hiding behind a copy. `lib/wsl.js`'s
+  spawning half — previously probe-only — gained `test/wsl.test.mjs`.
+  `test/probe/agent.sh` is wired as `npm run probe:agent` like its siblings.
+
 ## [0.5.0] - 2026-10-04
 
 One theme: telling the truth, in the reader's language. The Plugins page now

package/CONTRIBUTING.md

@@ -69,6 +69,10 @@ terminal if you would rather not see the prompt.
 | `npm run probe:sandbox` | what bubblewrap confines and what it does not | no |
 | `npm run probe:sandbox-shell` | the confined executor through a real boot | yes |
 | `npm run probe:terminal` | the terminal provider | yes |
+| `npm run probe:substrate` | the agent filesystem substrate over a real `wsl.exe` transport | yes; inside the distro |
+| `npm run probe:watch` | the in-distro watcher over a real directory | yes; inside the distro |
+| `npm run probe:agent` | the resident-vs-one-shot fallback parity legs | yes; inside the distro |
+| `npm run probe:exec` | the agent-backed execution handle: timeout, kill, cwd failure | yes; inside the distro |
 | `npm run probe:missing-wsl` | how a `wslPath` that cannot start is reported | yes |
 | `npm run probe:picker` | the picker's root level, its refusals and its cap | yes |
 | `npm run probe:mode` | which POSIX-mode facts survive the share | no; Windows Node |

package/README.md

@@ -143,6 +143,9 @@ npm run probe                # filesystem probe against a real distro (Windows +
 npm run probe:sandbox-shell  # boot a real harness and drive the confined executor
 npm run probe:terminal       # open a PTY through the terminal provider
 npm run probe:substrate      # drive the agent filesystem substrate over a real wsl.exe transport (from inside the distro)
+npm run probe:watch          # arm the in-distro watcher over a real directory (from inside the distro)
+npm run probe:agent          # the resident-vs-one-shot fallback parity legs (from inside the distro)
+npm run probe:exec           # the agent-backed execution handle: timeout, kill, cwd failure (from inside the distro)
 npm run probe:missing-wsl    # boot a profile whose wslPath cannot start (Windows + WSL only)
 npm run probe:picker         # list the picker's root level, refusals and its cap (Windows + WSL only)
 npm run probe:mode           # which POSIX-mode facts survive the share (Windows node only)

package/agent/wsl-agent.sh

@@ -27,6 +27,10 @@
 #          With a cap, stdout and stderr are each cut at that many bytes and
 #          the flags say which streams were cut; 0 means the whole capture.
 #          or ERR|<id>|<reason>|<b64 message>   (reason: cwd)
+#       An EXEC request runs as its own session and process group (`setsid`),
+#       so a timeout or a KILL frame takes the whole descendant tree — not
+#       just the direct child, which is how a build tool's daemonized
+#       grandchild outlives the kill.
 #   FS|<id>|<op>|<timeout seconds|0>|<n args>
 #       followed by <n args> lines of base64, one argument each — arguments
 #       arrive still base64 so a write's content never passes through a shell
@@ -81,31 +85,58 @@ b64enc_file() {
 
 kill_current() {
   if [ -n "$CURRENT_PID" ]; then
-    kill -TERM "$CURRENT_PID" 2>/dev/null
+    kill_request TERM "$CURRENT_PID"
   fi
 }
 
+# Signal one in-flight request, descendants included. With `setsid` (EXEC
+# requests, below) the request is its own process-group leader, so the
+# negative PID signals the WHOLE group — every descendant that did not make
+# its own session. Without it the group does not exist, the negative-PID kill
+# fails with ESRCH, and the direct kill keeps the old guarantee. A shell whose
+# `kill` builtin cannot parse `-- -PID` at all also lands here.
+kill_request() {
+  # $1 = signal name, $2 = request PID.
+  kill -s "$1" -- "-$2" 2>/dev/null || kill -s "$1" "$2" 2>/dev/null || :
+}
+
 shutdown() {
   kill_current
   exit 0
 }
 trap shutdown TERM INT HUP
 
+# Whether EXEC requests can run as their own session. `setsid` makes the
+# request process a session AND process-group leader (pid = pgid), which is
+# what lets kill_request signal the whole descendant tree; the agent's own
+# shell cannot do this portably — `set -m` in a non-interactive dash has been
+# observed skipping the setpgid entirely, and a kill against a PID that is
+# not a group leader is a no-op. A distro without `setsid` keeps working:
+# requests then run in the agent's own group and the direct-child kill of the
+# pre-setsid behaviour applies.
+SETSID=
+if command -v setsid >/dev/null 2>&1; then
+  SETSID=setsid
+fi
+
 timeout_watcher() {
-  # $1 = seconds, $2 = pid, $3 = grace seconds. TERM first; a process that
-  # ignores TERM gets KILLed after the grace, so a stuck command cannot hang
-  # the request forever.
+  # $1 = seconds, $2 = pid, $3 = grace seconds. TERM first — the whole group,
+  # so a command that ignores TERM takes its descendants with it when the
+  # KILL lands; a process that ignores TERM gets KILLed after the grace, so a
+  # stuck command cannot hang the request forever.
   sleep "$1"
-  kill -TERM "$2" 2>/dev/null
+  kill_request TERM "$2"
   sleep "${3:-3}"
-  kill -KILL "$2" 2>/dev/null
+  kill_request KILL "$2"
 }
 
 # Capture one request's output and answer with RES. $1 = request id, $2 =
 # timeout seconds ('' or 0 = none), $3 = per-stream output cap in bytes (0 or
 # empty = unlimited), $4 = launch mode: `exec` runs "$@" (argv words) as the
-# request process; `subshell` runs ( "$@" ) in a forked subshell, which is how
-# the FS handlers — shell functions, not executables — run.
+# request process, in its own session via `setsid` when the distro has it —
+# the timeout and KILL then signal the whole descendant group; `subshell` runs
+# ( "$@" ) in a forked subshell, which is how the FS handlers — shell
+# functions, not executables — run.
 run_capture() {
   local req_id timeout_s maxout mode rc watcher_pid out_cut err_cut
   req_id=$1
@@ -121,6 +152,8 @@ run_capture() {
   CURRENT_ID=$req_id
   if [ "$mode" = subshell ]; then
     ( "$@" ) >"$OUT_FILE" 2>"$ERR_FILE" &
+  elif [ -n "$SETSID" ]; then
+    ( exec setsid "$@" ) >"$OUT_FILE" 2>"$ERR_FILE" &
   else
     "$@" >"$OUT_FILE" 2>"$ERR_FILE" &
   fi

package/docs/ARCHITECTURE.md

@@ -19,7 +19,7 @@ smaller integrations.
 | Service | Class | File | What it does |
 |---|---|---|---|
 | `ctx.shell` | `WslShellExecutor` | [`lib/index.js`](../lib/index.js) | Runs each command as `wsl.exe -d <distro> --cd <linux dir> --exec <login shell> -lc <cmd>`, wrapped in a distro-side `bwrap` sandbox. |
-| `ctx.fs` | `WslFileSystem` | [`lib/index.js`](../lib/index.js) | Serves the file tools from real distro files, on one of two I/O substrates (see below): the Windows-side host stack over the distro's UNC share (default), or the resident in-distro agent on ext4. |
+| `ctx.fs` | `WslFileSystem` | [`lib/index.js`](../lib/index.js) | Serves the file tools from real distro files, on one of two I/O substrates (see below): the resident in-distro agent on ext4 (default), or the Windows-side host stack over the distro's UNC share. |
 | `ctx.subprocess` | `WslSubprocessRuntime` | [`lib/subprocess.js`](../lib/subprocess.js) | Opens the GUI terminal inside the distro, in the session workspace. |
 
 `WslShellExecutor` extends the shipped `LocalBashExecutor`, and `WslFileSystem`
@@ -146,7 +146,8 @@ wsl.exe -d <distro> --cd <linux dir> --exec bwrap \
 
 These are the same arguments DSH's Linux runner uses (`dsh-sandbox-local`), so the
 behaviour and the error messages match a Linux host. The function
-`bwrapProfileArgs` in [`lib/sandbox.js`](../lib/sandbox.js) builds them.
+`bwrapProfileArgs` in [`lib/bwrap.js`](../lib/bwrap.js) builds them — the
+peer-free builder every confinement site composes from.
 
 | Mode | What a command inside the distro can do |
 |---|---|
@@ -208,7 +209,7 @@ finds it here.
 | `FS_OUTSIDE_DISTRO` | `WslFileSystem.worldPath` | `restrictToDistro` is on and the path names **another distro**'s share — a configuration fence, not a sandbox decision | open a session in that distro, or set `restrictToDistro: false`. A wider permission does **not** lift it |
 | `FS_NOT_OBSERVED` | `WslFileSystem.assertGuard` | a guarded create (`createIfAbsent`) targeted a file that exists and had not been read first | read the file, then overwrite with the version guard or edit it |
 | `FS_STALE_VERSION` | `WslFileSystem.assertGuard` | the version the caller holds no longer matches: the file changed, or is gone | read it again and retry with the fresh version |
-| `FS_IO_ERROR` | `WslFileSystem.watch` | `watch()` is refused, because a 9p share cannot be watched reliably | poll, or watch from inside the distro |
+| `FS_IO_ERROR` | `WslFileSystem.watch` | the watch target is not a path inside the pinned distro, so there is nothing the in-distro poll loop can observe | watch a distro path; the watch itself runs where the files live (`lib/watcher.js`) |
 | `FS_NOT_FOUND` | the host filesystem stack | the path does not exist — the ordinary answer, passed through | — |
 
 Two failures come from `wsl.exe` itself rather than from a code of ours, and both used

package/docs/CONFIGURATION.md

@@ -26,6 +26,7 @@ are schema defaults, listed because they are the ones worth knowing.
 | | `substrate` | `agent` *(shipped)* | which I/O substrate serves the file tools: `agent` — the resident in-distro agent (`lib/fs-substrate.js`), where reads, writes and identities run on ext4: native symlinks, native mode bits, and the mutation guard survives to the write's atomic publication, kernel-enforced by the confined resident when the policy is confined. `share` — the opt-out: the Windows-side host stack over the 9p share, with the symlink-retry and publication hooks. Both substrates fence writes with the same host-side policy check. See [LIMITATIONS.md](LIMITATIONS.md) for what changes between them |
 | | `resolveSymlinks` | `true` | *(share substrate only)* follow Linux symlinks that the share cannot traverse, such as `/etc/os-release` and `/bin` — the agent substrate follows them natively |
 | | `cwd` | `''` | base directory for relative paths; empty means the distro user's home |
+| | `watchMaxDepth` | `0` | how deep the in-distro watch scan walks; `0` walks the whole tree. Bound it (e.g. `4`) when the watched tree holds a `node_modules` — a change below the bound is seen only when another change above it fires the same callback |
 | `directory-picker-wsl` | `preferredDistro` | `''` *(shipped)* | the distro listed first in the picker |
 | | `includeHostHome` | `true` *(shipped)* | also list the Windows home directory |
 | | `maxEntries` | `1000` *(shipped)* | maximum entries listed per directory |

package/docs/PARITY.md

@@ -40,6 +40,10 @@ shaped a phase of the plan.
    distro's share, rewrite the spawn to run a distro-side `rg` (falling back
    to `grep -rE` + `find` when absent) with identical stdout conventions.
    Under the agent, that exec rides the agent's `exec` capability.
+   **Not implemented, and recorded so the gap is a decision, not an
+   omission:** search still runs the packaged Windows rg over the share. The
+   interception was designed (above) but never landed; nothing in the phase
+   table below delivers it, and no phase claims it.
 3. **`dsh-fs-local` watches with chokidar over the share** — the behaviour
    this plugin replaces: chokidar on 9p is the unreliability that made
    `WslFileSystem.watch` refuse. The in-distro watcher replaces it wholesale.

package/docs/README.zh.md

@@ -134,6 +134,9 @@ npm run probe                # 文件系统探针，需要真实子系统（仅
 npm run probe:sandbox-shell  # 启动真实 harness，驱动受限执行器
 npm run probe:terminal       # 通过终端 provider 打开一个 PTY
 npm run probe:substrate      # 用真实 wsl.exe 传输驱动 agent 文件基座（在子系统内运行）
+npm run probe:watch          # 在真实目录上装上 distro 内轮询 watcher（在子系统内运行）
+npm run probe:agent          # resident 与 one-shot 的回退不变量对比腿（在子系统内运行）
+npm run probe:exec           # agent 执行句柄：超时、杀停、cwd 失败（在子系统内运行）
 npm run probe:missing-wsl    # 启动一个 wslPath 无法启动的 profile（仅 Windows + WSL）
 npm run probe:picker         # 列出选择器的根级、拒绝路径与上限（仅 Windows + WSL）
 npm run probe:mode           # 哪些 POSIX 权限事实能穿过共享层（仅需 Windows node）

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

@@ -1,6 +1,6 @@
 {
   "name": "dsh-plugin-wsl-env",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "让 DeepSeek Harness 以 WSL 子系统作为会话的执行环境：shell、文件读写与命令执行均在子系统内完成，目录选择器与 GUI 终端同样定位到子系统路径，并通过子系统内的 bubblewrap 对命令进行沙箱隔离",
   "keywords": [
     "deepseek-harness",
@@ -63,9 +63,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/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: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/wsl.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/fs-decisions.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/wsl.test.mjs test/fs-decisions.test.mjs",
     "lint:style": "node test/style.mjs",
     "prepublishOnly": "npm test",
     "probe": "bash test/probe/run.sh",
@@ -78,6 +78,7 @@
     "probe:sandbox-shell": "bash test/probe/sandbox-shell.sh",
     "sync:windows": "bash test/probe/sync-to-windows.sh",
     "probe:watch": "bash test/probe/watch.sh",
+    "probe:agent": "bash test/probe/agent.sh",
     "probe:substrate": "bash test/probe/substrate.sh",
     "probe:exec": "bash test/probe/exec.sh",
     "bootstrap": "bash scripts/bootstrap.sh"