dsh-plugin-wsl-env 0.7.5 → 0.8.0

package/lib/terminal-activity.d.ts

@@ -0,0 +1,98 @@
+/**
+ * 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.
+ *
+ * This is a TypeScript source built to `lib/terminal-activity.js`; edit THIS
+ * file and run `pnpm run build` — the artifact under `lib/` is generated, and
+ * `pnpm test` fails when it drifts.
+ *
+ * @module dsh-plugin-wsl/terminal-activity
+ */
+import type { SubprocessTerminalHandle } from "@deepseek-ai/dsh-subprocess";
+/** The env name that marks one terminal's process tree inside the distro. */
+export declare 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.
+ */
+export interface SubprocessTerminalActivity {
+    state: "idle" | "busy" | "unknown";
+    revision: number;
+}
+/**
+ * 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 declare function terminalActivityProbe(terminalId: string): {
+    cwd: string;
+    argv: string[];
+};
+/**
+ * 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 declare function parseTerminalActivity(stdout: string | Buffer): "busy" | "idle" | 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 declare function wrapTerminalHandle(handle: SubprocessTerminalHandle, inspectActivity: () => Promise<SubprocessTerminalActivity>): SubprocessTerminalHandle;

package/lib/terminal-activity.js

@@ -29,24 +29,14 @@
  * Pure builders and a transparent proxy here; the agent wiring lives in the
  * subprocess provider.
  *
+ * This is a TypeScript source built to `lib/terminal-activity.js`; edit THIS
+ * file and run `pnpm run build` — the artifact under `lib/` is generated, and
+ * `pnpm test` fails when it drifts.
+ *
  * @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.
  *
@@ -66,21 +56,20 @@ export const TERMINAL_ID_ENV = "DSH_TERMINAL_ID";
  * @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] };
+    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.
  *
@@ -89,11 +78,11 @@ export function terminalActivityProbe(terminalId) {
  *   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;
+    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.
  *
@@ -111,11 +100,12 @@ export function parseTerminalActivity(stdout) {
  * @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;
-    },
-  });
+    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/terminal-route.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Which execution world a terminal launch belongs to.
+ *
+ * The terminal controller hands this provider the request's directory, and the
+ * directory's coordinate system is the evidence of intent: a UNC path under a
+ * distro's share names a WSL session outright, a POSIX absolute path is a
+ * distro path by construction, and a Windows drive path is a session opened on
+ * a Windows folder — which deserves a HOST shell, not the distro's shell
+ * started at `/mnt/<drive>/…`. An empty directory carries no evidence either
+ * way and defaults to the distro, which is what a profile pins.
+ *
+ * Pure by construction.
+ *
+ * This is a TypeScript source built to `lib/terminal-route.js`; edit THIS file
+ * and run `pnpm run build` — the artifact under `lib/` is generated, and
+ * `pnpm test` fails when it drifts.
+ *
+ * @module dsh-plugin-wsl/terminal-route
+ */
+/**
+ * The route decision for one terminal launch.
+ *
+ * @param cwd - the terminal request's working directory, any coordinate system.
+ * @returns `"distro"` when the launch belongs inside the pinned distro,
+ *   `"host"` when it belongs to a Windows-folder session.
+ */
+export declare function terminalRoute(cwd: string | undefined): "distro" | "host";

package/lib/terminal-route.js

@@ -11,21 +11,29 @@
  *
  * Pure by construction.
  *
+ * This is a TypeScript source built to `lib/terminal-route.js`; edit THIS file
+ * and run `pnpm run build` — the artifact under `lib/` is generated, and
+ * `pnpm test` fails when it drifts.
+ *
  * @module dsh-plugin-wsl/terminal-route
  */
-
 import { isPosixAbsolute, uncToPosix, windowsToLinuxMount } from "./paths.js";
-
 /**
+ * The route decision for one terminal launch.
+ *
  * @param cwd - the terminal request's working directory, any coordinate system.
  * @returns `"distro"` when the launch belongs inside the pinned distro,
  *   `"host"` when it belongs to a Windows-folder session.
  */
 export function terminalRoute(cwd) {
-  const text = String(cwd ?? "").trim();
-  if (text.length === 0) return "distro";
-  if (uncToPosix(text) !== undefined) return "distro";
-  if (isPosixAbsolute(text)) return "distro";
-  if (windowsToLinuxMount(text) !== undefined) return "host";
-  return "distro";
+    const text = String(cwd ?? "").trim();
+    if (text.length === 0)
+        return "distro";
+    if (uncToPosix(text) !== undefined)
+        return "distro";
+    if (isPosixAbsolute(text))
+        return "distro";
+    if (windowsToLinuxMount(text) !== undefined)
+        return "host";
+    return "distro";
 }

package/lib/watcher.d.ts

@@ -0,0 +1,77 @@
+/**
+ * In-distro file watching for `WslFileSystem.watch`.
+ *
+ * A 9p share gives Node no usable change notification — chokidar over
+ * `\\wsl.localhost` is the unreliability that made this provider refuse to
+ * watch at all. The seam's contract, however, asks for far less than events:
+ * `watch(target, changed, signal)` wants ONE invalidation callback, invoked
+ * whenever something under `target` may have changed. That is cheap to honor
+ * from inside the distro, where the kernel does know.
+ *
+ * The watcher is a long-lived `wsl.exe` shell loop: periodically
+ * `find <dir> -newer <stamp>` — the directory itself is in the scan, so
+ * creations AND deletions (which bump the parent's mtime) are both seen — and
+ * 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.
+ *
+ * This is a TypeScript source built to `lib/watcher.js`; edit THIS file and
+ * run `pnpm run build` — the artifact under `lib/` is generated, and `pnpm test`
+ * fails when it drifts.
+ *
+ * @module dsh-plugin-wsl/watcher
+ */
+import type { ChildProcess } from "node:child_process";
+/**
+ * The shell loop the watcher runs, parameterised by argv so no path can break
+ * quoting: `$1` is the Linux directory, `$2` the poll interval in seconds.
+ * Pure text, so it is unit-testable.
+ *
+ * @param intervalSeconds - poll cadence; must be >= 1.
+ * @param 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 the `sh -c` script body.
+ */
+export declare function watchLoopScript(intervalSeconds?: number, maxDepth?: number): string;
+/**
+ * Arm one in-distro watcher over a Linux directory.
+ *
+ * @param options - the watch request.
+ * @returns resolves once observation is active, with the async close function
+ *   the seam's contract asks for.
+ */
+export declare function armDistroWatcher({ wslPath, distro, linuxPath, onChange, onError, signal, intervalSeconds, maxDepth, spawn: spawnProcess }: {
+    /** The `wsl.exe` path. */
+    wslPath: string;
+    /** The distro to watch inside. */
+    distro: string;
+    /** The absolute Linux path to observe. */
+    linuxPath: string;
+    /** Watcher-level failures (an exited loop, a vanished target); the seam reports these through its own channel. */
+    onError?: (error: Error) => void;
+    /** The invalidation callback. */
+    onChange: () => void;
+    /** Cancels initialization; the CALLER invokes the returned close to stop an armed watcher. */
+    signal: AbortSignal;
+    /** Poll cadence, default 2. */
+    intervalSeconds?: number;
+    /** Scan depth bound, 0 = the whole tree. */
+    maxDepth?: number;
+    /** Injectable process factory for tests. */
+    spawn?: (wslPath: string, args: string[]) => ChildProcess;
+}): Promise<() => Promise<void>>;

package/lib/watcher.js

@@ -28,151 +28,145 @@
  * older than the stamp (`cp -p`, `tar -x`) is not seen until something else
  * touches the tree.
  *
+ * This is a TypeScript source built to `lib/watcher.js`; edit THIS file and
+ * run `pnpm run build` — the artifact under `lib/` is generated, and `pnpm test`
+ * fails when it drifts.
+ *
  * @module dsh-plugin-wsl/watcher
  */
-
 import { spawn } from "node:child_process";
 import { createInterface } from "node:readline";
-
 /**
  * The shell loop the watcher runs, parameterised by argv so no path can break
  * 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
+ *
+ * @param intervalSeconds - poll cadence; must be >= 1.
+ * @param 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.
+ * @returns the `sh -c` script body.
  */
 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'",
-    // Check first, sleep second: a change made right after activation is seen
-    // on the first cadence, not one cadence later.
-    "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",
-    `  sleep ${seconds}`,
-    "done",
-  ].join("\n");
+    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'",
+        // Check first, sleep second: a change made right after activation is seen
+        // on the first cadence, not one cadence later.
+        "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",
+        `  sleep ${seconds}`,
+        "done",
+    ].join("\n");
 }
-
 /**
  * Arm one in-distro watcher over a Linux directory.
  *
- * @param {object} options - the watch request.
- * @param {string} options.wslPath - the `wsl.exe` path.
- * @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, 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.
+ * @param options - the watch request.
+ * @returns 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, 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, 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") {
-        if (!settled && !signal?.aborted) {
-          settled = true;
-          resolve(close);
+    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;
         }
-        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();
-      }
-    });
-    const close = async () => {
-      if (closed) return;
-      closed = true;
-      child.removeAllListeners("exit");
-      lines.close();
-      child.stdout.destroy();
-      child.kill();
-      await new Promise((resolveClose) => {
-        if (child.exitCode !== null || child.signalCode !== null) return resolveClose();
-        child.once("exit", resolveClose);
-      });
-    };
-    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;
-      }
-      settled = true;
-      void close();
-      reject(error);
-    };
-    signal?.addEventListener("abort", () => fail(signal.reason instanceof Error ? signal.reason : new Error("aborted")), { once: true });
-    child.on("error", fail);
-    child.on("exit", (code, signalName) => {
-      fail(new Error(`distro watcher exited unexpectedly (code=${code} signal=${signalName ?? "none"})`));
+        const child = doSpawn(wslPath, ["-d", distro, "--exec", "sh", "-c", watchLoopScript(intervalSeconds, maxDepth), "wsl-watch", linuxPath]);
+        if (child.stdout === null || child.stderr === null)
+            throw new Error("the watcher spawn did not provide piped stdio");
+        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") {
+                if (!settled && !signal?.aborted) {
+                    settled = true;
+                    resolve(close);
+                }
+                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();
+            }
+        });
+        const close = async () => {
+            if (closed)
+                return;
+            closed = true;
+            child.removeAllListeners("exit");
+            lines.close();
+            child.stdout?.destroy();
+            child.kill();
+            await new Promise((resolveClose) => {
+                if (child.exitCode !== null || child.signalCode !== null)
+                    return resolveClose();
+                child.once("exit", resolveClose);
+            });
+        };
+        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;
+            }
+            settled = true;
+            void close();
+            reject(error);
+        };
+        signal?.addEventListener("abort", () => fail(signal.reason instanceof Error ? signal.reason : new Error("aborted")), { once: true });
+        child.on("error", fail);
+        child.on("exit", (code, signalName) => {
+            fail(new Error(`distro watcher exited unexpectedly (code=${code} signal=${signalName ?? "none"})`));
+        });
     });
-  });
 }