dsh-plugin-wsl-env 0.5.0 → 0.7.2

package/lib/search-route.js

@@ -0,0 +1,95 @@
+/**
+ * Which execution world a file-search spawn belongs to, and the `wsl.exe`
+ * argv it becomes there.
+ *
+ * `dsh-tool-fs-search` spawns the packaged ripgrep binary through
+ * `ctx.subprocess` with the session workspace as the working directory. Left
+ * alone, that spawn runs the Windows binary over the distro's 9p share — the
+ * one model-facing I/O path that still crossed the share, and in the slow
+ * direction: measured at ~17 ms per file of metadata round trips where the
+ * distro's own ext4 answers in microseconds. The interception point is the
+ * subprocess provider's `spawn`, and the decision lives here — pure,
+ * peer-free, and unit-testable, mirroring `terminal-route.js`.
+ *
+ * The rewrite is deliberately narrow. A spawn is intercepted only when the
+ * working directory NAMES the distro outright — a `\\wsl.localhost\<distro>`
+ * UNC — because that is the form a distro session's search carries and the
+ * only one that resolves without an async distro query: `spawn` hands back
+ * its handle synchronously, so the override must stay synchronous. A Windows
+ * drive directory keeps the host binary, which is native there and touches
+ * no share; anything else passes through untouched, exactly as before.
+ *
+ * The rewritten argv forwards every rg argument verbatim, so the tool reads
+ * the output format and exit codes of the distro's own rg. One addition is
+ * made: when the tool named no search path — its pattern rides `--regexp=`,
+ * and a bare `--` separator is exactly how it spells an explicit path — the
+ * rewrite appends `-- .`. Reason: `wsl.exe --exec` hands the distro-side rg a
+ * relay FIFO for stdin, and rg's readable-stdin heuristic then searches stdin
+ * (instantly empty) instead of walking the working directory; the packaged
+ * binary under the old path saw a non-readable NUL stdin and walked it. An
+ * explicit path makes the search deterministic on either transport.
+ *
+ * The distro-side binary must therefore exist — `scripts/bootstrap.sh` reports
+ * it — and a distro without one surfaces rg's own "command not found" instead
+ * of a silent fall-back to the share.
+ *
+ * @module dsh-plugin-wsl/search-route
+ */
+
+import { uncToPosix } from "./paths.js";
+
+/** The one program this rewrite passes through to the distro. */
+const SEARCH_PROGRAM = "rg";
+
+/**
+ * Whether a spawn's program is the ripgrep binary.
+ *
+ * A bare `argv[0]` is judged by its own name, so the packaged binary's
+ * absolute path and any other spelling of `rg` match alike.
+ *
+ * @param unknown - the spawn's `argv[0]`.
+ * @returns true when the spawn is a ripgrep launch.
+ */
+export function isSearchProgram(program) {
+  if (typeof program !== "string" || program.length === 0) return false;
+  const base = program.slice(Math.max(program.lastIndexOf("/"), program.lastIndexOf("\\")) + 1);
+  return base.toLowerCase().replace(/\.exe$/u, "") === SEARCH_PROGRAM;
+}
+
+/**
+ * The distro-side rewrite of one search spawn, when it belongs in the distro.
+ *
+ * Two argv forms come back for one decision. `rgArgv` is the distro command
+ * itself (`rg` and its arguments) — what the resident agent execs. `wslArgv`
+ * is the same command wrapped for a one-shot `wsl.exe --exec` launch — the
+ * fallback transport for when the agent is out. The working directory becomes
+ * the `--cd` the distro starts in; `wsl.exe` itself must start in a Windows
+ * directory, so the caller supplies its own host cwd when applying `wslArgv`.
+ *
+ * @param object - the spawn's inputs.
+ * @param {unknown[]} object.argv - the spawn's argv; `argv[0]` is the program.
+ * @param {unknown} object.cwd - the spawn's working directory, any coordinate system.
+ * @param {string} object.wslPath - path to `wsl.exe`.
+ * @returns {{distro: string, linuxCwd: string, rgArgv: string[], wslArgv: string[]}|undefined} the
+ *   rewrite, or undefined when the spawn is not a distro search and must run
+ *   exactly as the shipped implementation would run it.
+ */
+export function searchSpawnRewrite({ argv, cwd, wslPath }) {
+  if (!Array.isArray(argv) || !isSearchProgram(argv[0])) return undefined;
+  const named = uncToPosix(cwd);
+  if (named === undefined) return undefined;
+  const linuxCwd = named.linuxPath.length > 0 ? named.linuxPath : "/";
+  // No bare `--` means the tool named no search path; without one, distro-side
+  // rg reads the relay fifo on stdin (rg's readable-stdin heuristic) instead of
+  // walking the directory. `.` is the working directory — the same directory
+  // the packaged binary walked when the host spawned it directly.
+  const forwarded = argv.slice(1);
+  const tool = forwarded.includes("--") ? forwarded : [...forwarded, "--", "."];
+  const rgArgv = [SEARCH_PROGRAM, ...tool];
+  return {
+    distro: named.distro,
+    linuxCwd,
+    rgArgv,
+    wslArgv: [wslPath, "-d", named.distro, "--cd", linuxCwd, "--exec", ...rgArgv],
+  };
+}

package/lib/subprocess.js

@@ -42,16 +42,21 @@
  * ## What this provider therefore changes
  *
  * It replaces the shipped `subprocess` row at the composition level and
- * overrides one method: `spawnTerminal`. A `wsl.exe` launch is rewritten into a
+ * overrides two methods. `spawnTerminal` rewrites a `wsl.exe` launch into a
  * launch that actually names the distro and the Session workspace's Linux
- * directory; every other request — including every ordinary `spawn()`, which the
- * command path uses for `wsl.exe -lc <command>` — reaches the shipped
- * implementation untouched.
+ * directory. `spawn` rewrites one further launch — the file-search tool's
+ * packaged ripgrep binary, which a distro workspace's UNC working directory
+ * names outright — into the distro's own rg: agent-first, one round trip on
+ * the warm resident, with the one-shot `wsl.exe --exec` handle as the
+ * documented fallback when the agent is out (`lib/search-route.js` holds the
+ * decision, `lib/search-exec.js` the handle). Every other request —
+ * including every other `spawn()`, which the command path uses for
+ * `wsl.exe -lc <command>` — reaches the shipped implementation untouched.
  *
  * The interpreter, the PTY, output handling and process-tree teardown stay the
  * shipped implementation's, so the blast radius of replacing a root service
- * stays at the one thing that was wrong: the directory and distro a terminal
- * starts in.
+ * stays at the two things that were wrong: the directory and distro a terminal
+ * starts in, and the filesystem a search walks.
  *
  * ## What the operator must pair it with
  *
@@ -70,10 +75,16 @@
  * @module dsh-plugin-wsl/subprocess
  */
 
+import { randomUUID } from "node:crypto";
 import z from "@deepseek-ai/schemastery";
 import { LocalSubprocessRuntime } from "@deepseek-ai/dsh-subprocess-local";
 import { isPosixAbsolute, toLinuxPath, uncToPosix, windowsToLinuxMount } from "./paths.js";
 import { DEFAULT_WSL_PATH, defaultDistro, wslEnvValue, wslTerminalArgv } from "./wsl.js";
+import { searchSpawnRewrite } from "./search-route.js";
+import { searchExecutionHandle } from "./search-exec.js";
+import { sharedAgent } from "./agent-shared.js";
+import { parseTerminalActivity, TERMINAL_ID_ENV, terminalActivityProbe, wrapTerminalHandle } from "./terminal-activity.js";
+import { AgentUnavailableError } from "./agent-errors.js";
 import { terminalRoute } from "./terminal-route.js";
 
 /**
@@ -128,6 +139,19 @@ export class WslSubprocessRuntime extends LocalSubprocessRuntime {
      * the composition-owned terminal for every session.
      */
     hostSessions: z.boolean().default(true),
+    /**
+     * Let the controller reclaim an idle distro terminal. The terminal is
+     * marked at launch (`DSH_TERMINAL_ID` through the existing `WSLENV`
+     * forwarding) and its handle's `inspectActivity` is replaced with a
+     * distro-side observation: the resident agent scans `/proc` for the
+     * marker — a shell with live children is busy, a shell without children
+     * is idle. The shipped observation can only answer `unknown` for a distro
+     * terminal, and `unknown` never accumulates idle, which is why these
+     * terminals had to be closed by hand. When the agent is out the
+     * observation answers `unknown` (no reclaim) — a probe that cannot answer
+     * must not authorize a close. `false` restores that posture.
+     */
+    terminalIdleReclaim: z.boolean().default(true),
   });
 
   constructor(ctx, config) {
@@ -208,21 +232,134 @@ export class WslSubprocessRuntime extends LocalSubprocessRuntime {
       linuxCwd: target.linuxCwd,
       login: this.config.loginShell,
     });
-    const forward = new Set([...SAFE_FORWARD, ...this.config.forwardEnv]);
-    const imported = Object.keys(spec.env ?? {}).filter(
-      (name) => forward.has(name) || name.startsWith(DSH_ENV_PREFIX),
-    );
-    return super.spawnTerminal({
-      ...spec,
+    // The idle-reclaim mark: one env name per terminal, riding the WSLENV
+    // forwarding this launch already does. The distro shell and everything it
+    // spawns carry it in /proc/<pid>/environ — what the activity probe scans.
+    const terminalId = this.config.terminalIdleReclaim ? randomUUID() : undefined;
+    const specWithMark = terminalId === undefined ? spec : { ...spec, env: { ...spec.env, [TERMINAL_ID_ENV]: terminalId } };
+    const handle = await super.spawnTerminal({
+      ...specWithMark,
       argv,
       // A Windows CreateProcess cannot use a Linux path as its working
       // directory; the Linux directory rides on `--cd` instead.
       cwd: this.hostCwd(),
-      env: {
-        ...spec.env,
-        ...(imported.length > 0 ? { WSLENV: wslEnvValue(imported) } : {}),
-      },
+      env: this.forwardedEnv(specWithMark),
     });
+    if (terminalId === undefined) return handle;
+    return wrapTerminalHandle(handle, this.distroActivity(target.distro, terminalId));
+  }
+
+  /**
+   * The replacement `inspectActivity` for one distro terminal: ask the
+   * resident agent whether the marked shell is at its prompt.
+   *
+   * The revision increments only when the reported state changes, so the
+   * controller's retention accumulates idle across consecutive `idle`
+   * observations and restarts the clock on every transition. Any probe
+   * failure — the agent out, the distro stopped, a script error — answers
+   * `unknown`, which the retention reads as "not idle": the probe that cannot
+   * answer never authorizes a close. The first unexpected (non-availability)
+   * failure is logged once, so a broken probe is diagnosable without
+   * spamming the log every poll.
+   *
+   * @param distro - the distro the terminal lives in.
+   * @param terminalId - the launch's `DSH_TERMINAL_ID` mark.
+   * @returns the seam's activity observation.
+   */
+  distroActivity(distro, terminalId) {
+    let revision = 0;
+    let lastState = "";
+    let warned = false;
+    return async () => {
+      try {
+        const probe = terminalActivityProbe(terminalId);
+        const result = await sharedAgent(distro).exec({
+          cwd: probe.cwd,
+          argv: probe.argv,
+          maxOutputBytes: 256,
+          timeoutMs: 10_000,
+        });
+        const state = parseTerminalActivity(result.stdout) ?? "unknown";
+        if (state !== lastState) {
+          revision += 1;
+          lastState = state;
+        }
+        return { state, revision };
+      } catch (error) {
+        if (!(error instanceof AgentUnavailableError) && !warned) {
+          warned = true;
+          this.ctx.logger?.warn(`wsl-subprocess: the terminal activity probe failed and idle reclamation is paused (${String(error?.message ?? error)})`);
+        }
+        return { state: "unknown", revision };
+      }
+    };
+  }
+
+  /**
+   * Open one host-side process, rewriting two kinds of launches into the
+   * distro: the file-search tool's ripgrep (agent-first, one-shot fallback)
+   * and git snapshot commands (one-shot only — snapshot operations are not
+   * latency-sensitive, and their stdin relay and collected streams are the
+   * shipped handle's). Both decisions are pure coordinate functions
+   * (`search-route.js`, `git-route.js`); a spawn neither names (any other
+   * program, any drive or relative directory) reaches the shipped
+   * implementation verbatim.
+   *
+   * @param spec - the spawn request.
+   * @returns the live search handle.
+   */
+  spawn(spec) {
+    const gitRewrite = gitSpawnRewrite({ argv: spec.argv, cwd: spec.cwd, wslPath: this.config.wslPath });
+    if (gitRewrite !== undefined) {
+      // The snapshot environment (GIT_INDEX_FILE / GIT_OBJECT_DIRECTORY /
+      // GIT_ALTERNATE_OBJECT_DIRECTORIES and the git hygiene flags) is
+      // path-shaped in Windows form; the values are translated into distro
+      // paths and every forwarded name rides WSLENV. The user's real index,
+      // object store, work tree, and refs stay untouched by design — the
+      // snapshot runs in the tool's private scratch.
+      const { env, wslenv } = translateGitEnv(spec.env);
+      return super.spawn({
+        ...spec,
+        argv: gitRewrite.wslArgv,
+        cwd: this.hostCwd(),
+        env: wslenv.length > 0 ? { ...env, WSLENV: wslEnvValue(wslenv) } : env,
+      });
+    }
+    const rewrite = searchSpawnRewrite({ argv: spec.argv, cwd: spec.cwd, wslPath: this.config.wslPath });
+    if (rewrite === undefined) return super.spawn(spec);
+    return searchExecutionHandle({
+      agent: sharedAgent(rewrite.distro),
+      cwd: rewrite.linuxCwd,
+      argv: rewrite.rgArgv,
+      // One budget serves both streams; the stdout budget is the binding one,
+      // and a pathological stderr is still bounded by it.
+      maxOutputBytes: spec.stdio?.stdout?.maxBytes ?? 0,
+      signal: spec.signal,
+      spawnFallback: () =>
+        super.spawn({
+          ...spec,
+          argv: rewrite.wslArgv,
+          // `wsl.exe --cd` carries the Linux directory; the host process itself
+          // must start in a Windows directory, as with a terminal launch.
+          cwd: this.hostCwd(),
+          env: this.forwardedEnv(spec),
+        }),
+    });
+  }
+
+  /**
+   * The environment one `wsl.exe` launch forwards: the safe list plus every
+   * managed `DSH_*` name, admitted through `WSLENV` and never `PATH` — see the
+   * WSLENV note in the recipes.
+   * @param spec - the launch request whose env is forwarded.
+   * @returns the environment the host launch carries.
+   */
+  forwardedEnv(spec) {
+    const forward = new Set([...SAFE_FORWARD, ...this.config.forwardEnv]);
+    const imported = Object.keys(spec.env ?? {}).filter(
+      (name) => forward.has(name) || name.startsWith(DSH_ENV_PREFIX),
+    );
+    return imported.length > 0 ? { ...spec.env, WSLENV: wslEnvValue(imported) } : spec.env;
   }
 
   /**

package/lib/terminal-activity.js

@@ -0,0 +1,121 @@
+/**
+ * The distro-side activity observation for GUI distro terminals, and the
+ * handle wrapper that installs it.
+ *
+ * ## The gap this closes
+ *
+ * The terminal controller reclaims unattended terminals after
+ * `unattendedTimeoutMs` of observed idleness, but its observation is
+ * host-side: `dsh-subprocess-local`'s shell-activity integration is gated to
+ * interactive `bash`/`zsh` launched directly on a POSIX host, and a distro
+ * terminal is `wsl.exe` on win32. Every branch of the shipped
+ * `inspectActivity` therefore settles on `unknown` for these terminals, and
+ * `unknown` never accumulates idle — a distro terminal had to be closed by
+ * hand.
+ *
+ * ## The observation
+ *
+ * The terminal is MARKED at launch: a per-terminal `DSH_TERMINAL_ID` rides
+ * the `WSLENV` forwarding this provider already does, so the distro shell —
+ * and every process it spawns — carries it in `/proc/<pid>/environ`. The
+ * controller's 30 s retention poll then asks the resident agent to count the
+ * marked processes: exactly one (the shell alone, at its prompt) is IDLE;
+ * more than one (a command, a pipeline, a nested shell is running) is BUSY;
+ * none at all defers to the shipped handle (the shell has exited; its own
+ * exit bookkeeping is more precise than this scan). The agent being out
+ * yields `unknown` — the same never-reclaim posture as before, which is the
+ * safe direction: a probe that cannot answer must not authorize a close.
+ *
+ * Pure builders and a transparent proxy here; the agent wiring lives in the
+ * subprocess provider.
+ *
+ * @module dsh-plugin-wsl/terminal-activity
+ */
+
+/** The env name that marks one terminal's process tree inside the distro. */
+export const TERMINAL_ID_ENV = "DSH_TERMINAL_ID";
+
+/**
+ * The seam's activity observation — structurally the upstream
+ * `SubprocessTerminalActivity` (`subprocess-local/src/terminal.ts`): `state`
+ * is `'idle' | 'busy' | 'unknown'` and `revision` is a counter that changes
+ * when the reported state changes, which is what the controller's retention
+ * loop keys its idle accumulation on.
+ *
+ * @typedef {Object} SubprocessTerminalActivity
+ * @property {'idle' | 'busy' | 'unknown'} state
+ * @property {number} revision
+ */
+
+/**
+ * The probe: count the `/proc` processes carrying the terminal marker.
+ *
+ * POSIX sh on purpose (the distro's `sh` is the only guaranteed interpreter).
+ * The count is the whole decision: the terminal's login shell is exec'd WITH
+ * the marker (wsl.exe imports it into the session before `--exec`), so an
+ * idle-at-prompt shell is exactly one marked process, and anything the shell
+ * runs — a command, a pipeline, a nested shell — is exec'd with the marker
+ * inherited, pushing the count past one. `/proc/<pid>/environ` shows the
+ * exec-time environment, which is precisely why the count works: runtime
+ * exports would be invisible, and exec-time inheritance is the signal.
+ *
+ * The marker check reads the NUL-separated environ through `tr`, which is why
+ * the id is passed as `$1` rather than interpolated into the script.
+ *
+ * @param terminalId - the `DSH_TERMINAL_ID` value one terminal was launched with.
+ * @returns the agent `exec` target: the probe script with the id as `$1`.
+ */
+export function terminalActivityProbe(terminalId) {
+  const script = [
+    "id=$1",
+    "count=0",
+    'for d in /proc/[0-9]*; do',
+    '  [ -r "$d/environ" ] || continue',
+    '  if tr "\\000" "\\n" < "$d/environ" 2>/dev/null | grep -qx "DSH_TERMINAL_ID=$id"; then',
+    "    count=$((count+1))",
+    '    [ "$count" -gt 1 ] && { echo busy; exit 0; }',
+    "  fi",
+    "done",
+    "echo idle",
+  ].join("\n");
+  return { cwd: "/", argv: ["sh", "-c", script, "sh", terminalId] };
+}
+
+/**
+ * Parse the probe's stdout into an activity state.
+ *
+ * @param stdout - the probe's raw stdout.
+ * @returns `"busy"` or `"idle"` as the probe reported, or undefined when the
+ *   output is anything else (the caller answers `unknown`).
+ */
+export function parseTerminalActivity(stdout) {
+  const text = String(stdout).trim();
+  if (text === "busy" || text === "idle") return text;
+  return undefined;
+}
+
+/**
+ * Wrap a terminal handle so its activity is observed inside the distro.
+ *
+ * Everything except `inspectActivity` forwards to the wrapped handle
+ * transparently — methods stay bound to the real handle, so the controller's
+ * `write`/`resize`/`signalForeground`/stream access behave exactly as on the
+ * shipped object. `inspectActivity` is replaced wholesale: the shipped
+ * implementation can only answer `unknown` for a distro terminal, and the
+ * replacement answers from the marker scan (or `unknown` itself, when the
+ * probe cannot answer).
+ *
+ * @param handle - the handle `spawnTerminal` returned.
+ * @param inspectActivity - the replacement observation, matching the seam's
+ *   `() => Promise<SubprocessTerminalActivity>` shape.
+ * @returns the transparent proxy handle.
+ */
+export function wrapTerminalHandle(handle, inspectActivity) {
+  return new Proxy(handle, {
+    get(target, prop) {
+      if (prop === "inspectActivity") return inspectActivity;
+      const value = Reflect.get(target, prop);
+      return typeof value === "function" ? value.bind(target) : value;
+    },
+  });
+}

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"})`));
     });
-
   });
 }