dsh-plugin-wsl-env 0.6.0 → 0.7.2

package/lib/picker.js

@@ -31,8 +31,11 @@
  *     the entry point rather than something you must know a UNC path for;
  *   - the breadcrumb "WSL" row jumps back to that distro list;
  *   - the dialog's Home affordance targets the preferred distro's Linux `$HOME`;
- *   - every other level is an ordinary directory listing, which the host
- *     performs over the distro's UNC share.
+ *   - every other level inside a distro is listed BY THE DISTRO — the resident
+ *     agent's `ls` when it is up, a one-shot `wsl.exe --exec ls` when it is
+ *     out — because the host's own listing used to walk the 9p share in its
+ *     slow direction, one metadata round trip per entry; a Windows path keeps
+ *     the host's own walk, which is native there.
  *
  * Because the client surface is unchanged, this row composes with the **shipped**
  * `@deepseek-ai/dsh-client-ui-directory-picker-browse` dialog: no client code,
@@ -46,9 +49,11 @@ import { homedir } from "node:os";
 import { join, resolve } from "node:path";
 import z from "@deepseek-ai/schemastery";
 import { DirectoryPicker, DirectoryPickerError } from "@deepseek-ai/dsh-host-directory-picker";
-import { UNC_PROVIDER_ROOT, distroRoot, isProviderRoot } from "./paths.js";
-import { breadcrumbs, boundedInsert, fullyQualified } from "./listing.js";
-import { listDistros, linuxHome } from "./wsl.js";
+import { UNC_PROVIDER_ROOT, distroRoot, isProviderRoot, isWslUnc, uncToPosix } from "./paths.js";
+import { breadcrumbs, boundedInsert, fullyQualified, lsListingArgv, parseLsListing } from "./listing.js";
+import { listDistros, linuxHome, runCapture } from "./wsl.js";
+import { sharedAgent } from "./agent-shared.js";
+import { AgentUnavailableError } from "./agent-errors.js";
 
 /** How long a resolved distro list stays fresh before it is queried again. */
 const DEFAULT_DISTRO_CACHE_MS = 5_000;
@@ -269,6 +274,74 @@ export class WslDirectoryPicker extends DirectoryPicker {
       throw new DirectoryPickerError("directory-unreadable", path, `cannot list "${path}": not a fully qualified path`);
     }
     const target = resolve(path);
+    const preferred = await this.preferredDistro(signal);
+    const level = isWslUnc(target) ? await this.listDistroLevel(target, signal) : await this.listHostLevel(target, signal);
+    return {
+      path: target,
+      home: preferred.length > 0 ? await this.homeOf(preferred, signal) : homedir(),
+      crumbs: this.crumbsFor(target),
+      entries: level.rows,
+      truncated: level.truncated,
+    };
+  }
+
+  /**
+   * List one level inside the distro, where the files live.
+   *
+   * The resident agent answers in one round trip; when it is out — distro
+   * stopped, or the resident's rebuild budget spent — the same `ls` runs
+   * through a one-shot `wsl.exe`. Neither path touches the 9p share, which is
+   * what the host walk it replaces used: one metadata round trip per entry,
+   * in the share's slow direction, plus one more per symlink.
+   *
+   * @param target - the absolute UNC directory to list.
+   * @param signal - caller lifetime.
+   * @returns the level's rows and truncation flag.
+   * @throws DirectoryPickerError with code `directory-unreadable`.
+   */
+  async listDistroLevel(target, signal) {
+    const parsed = uncToPosix(target);
+    const linuxDir = parsed.linuxPath.length > 0 ? parsed.linuxPath : "/";
+    let stdout;
+    try {
+      const result = await sharedAgent(parsed.distro).exec({
+        cwd: linuxDir,
+        argv: lsListingArgv(linuxDir),
+        timeoutMs: 15_000,
+        signal,
+      });
+      if (result.exitCode !== 0) {
+        const detail = result.stderr.toString("utf8").trim();
+        throw new DirectoryPickerError(
+          "directory-unreadable",
+          target,
+          `cannot list ${target}: ${detail.length > 0 ? detail : `ls exited ${result.exitCode}`}`,
+        );
+      }
+      stdout = result.stdout;
+    } catch (error) {
+      if (!(error instanceof AgentUnavailableError)) throw error;
+      try {
+        stdout = await runCapture(
+          [this.config.wslPath, "-d", parsed.distro, "--cd", linuxDir, "--exec", ...lsListingArgv(linuxDir)],
+          signal,
+        );
+      } catch (fallbackError) {
+        throw new DirectoryPickerError("directory-unreadable", target, `cannot list ${target}: ${messageOf(fallbackError)}`);
+      }
+    }
+    return parseLsListing(stdout, target, this.config.maxEntries);
+  }
+
+  /**
+   * List one Windows level with the host's own walk — native I/O on a native
+   * filesystem, unchanged from the shipped browse behaviour.
+   * @param target - the absolute Windows directory to list.
+   * @param signal - caller lifetime.
+   * @returns the level's rows and truncation flag.
+   * @throws DirectoryPickerError with code `directory-unreadable`.
+   */
+  async listHostLevel(target, signal) {
     const maxEntries = this.config.maxEntries;
     const keep = maxEntries + 1;
     const window = [];
@@ -295,27 +368,19 @@ export class WslDirectoryPicker extends DirectoryPicker {
       if (level !== undefined) await level.close().catch(() => {});
     }
 
-    const entries = [];
+    const rows = [];
     let truncated = evicted;
     for (const candidate of window) {
       signal?.throwIfAborted();
       const row = await directoryRow(target, candidate.name, candidate.isDirectory, candidate.isSymbolicLink, signal);
       if (row === null) continue;
-      if (entries.length === maxEntries) {
+      if (rows.length === maxEntries) {
         truncated = true;
         break;
       }
-      entries.push(row);
+      rows.push(row);
     }
-
-    const preferred = await this.preferredDistro(signal);
-    return {
-      path: target,
-      home: preferred.length > 0 ? await this.homeOf(preferred, signal) : homedir(),
-      crumbs: this.crumbsFor(target),
-      entries,
-      truncated,
-    };
+    return { rows, truncated };
   }
 
   /**
@@ -334,6 +399,7 @@ export class WslDirectoryPicker extends DirectoryPicker {
       throw new DirectoryPickerError("directory-create-failed", join(parent, name), `"${name}" is not a single path segment`);
     }
     const target = join(parent, name);
+    if (isWslUnc(parent)) return this.createDistroDirectory(parent, name, target);
     try {
       await mkdir(target);
       return target;
@@ -344,6 +410,44 @@ export class WslDirectoryPicker extends DirectoryPicker {
       throw new DirectoryPickerError("directory-create-failed", target, `cannot create ${target}: ${messageOf(error)}`);
     }
   }
+
+  /**
+   * Create one child directory inside the distro — the resident agent's
+   * `mkdir` when it is up, a one-shot `wsl.exe --exec mkdir` when it is out;
+   * the host's `mkdir` over the 9p share is what this replaces.
+   *
+   * @param parent - the absolute UNC parent directory.
+   * @param name - the validated single path segment to create.
+   * @param target - the UNC path the caller receives on success.
+   * @returns the created directory's absolute path.
+   * @throws DirectoryPickerError with code `directory-exists` or `directory-create-failed`.
+   */
+  async createDistroDirectory(parent, name, target) {
+    const parsed = uncToPosix(parent);
+    const linuxParent = parsed.linuxPath.length > 0 ? parsed.linuxPath : "/";
+    try {
+      const result = await sharedAgent(parsed.distro).exec({ cwd: linuxParent, argv: ["mkdir", "--", name], timeoutMs: 10_000 });
+      if (result.exitCode === 0) return target;
+      const detail = result.stderr.toString("utf8");
+      if (/File exists/i.test(detail)) throw new DirectoryPickerError("directory-exists", target, `${target} already exists`);
+      throw new DirectoryPickerError(
+        "directory-create-failed",
+        target,
+        `cannot create ${target}: ${detail.trim().length > 0 ? detail.trim() : `mkdir exited ${result.exitCode}`}`,
+      );
+    } catch (error) {
+      if (error instanceof DirectoryPickerError) throw error;
+      if (!(error instanceof AgentUnavailableError)) throw error;
+      try {
+        await runCapture([this.config.wslPath, "-d", parsed.distro, "--cd", linuxParent, "--exec", "mkdir", "--", name]);
+        return target;
+      } catch (fallbackError) {
+        const message = messageOf(fallbackError);
+        if (/File exists/i.test(message)) throw new DirectoryPickerError("directory-exists", target, `${target} already exists`);
+        throw new DirectoryPickerError("directory-create-failed", target, `cannot create ${target}: ${message}`);
+      }
+    }
+  }
 }
 
 export default WslDirectoryPicker;

package/lib/search-exec.js

@@ -0,0 +1,114 @@
+/**
+ * The agent-backed execution handle for the file-search spawn.
+ *
+ * `dsh-tool-fs-search` consumes a deliberately small slice of the subprocess
+ * handle: it awaits `handle.done` for `{exitCode, signal}`, then reads
+ * `handle.collected.stdout/stderr.readFrom(0)` — nothing else. This module
+ * builds exactly that surface around one resident-agent `exec`, so a distro
+ * search pays one round trip on the warm agent (~10 ms) instead of a one-shot
+ * `wsl.exe` spawn (~400 ms of process startup for a few ms of rg).
+ *
+ * The agent being out is not an error condition here — it is the fallback
+ * cue. `spawnFallback` (the shipped one-shot handle the caller builds) is
+ * consulted lazily inside `done`; from that point the facade proxies the
+ * delegate's `collected` and `done` verbatim. Neither transport ever touches
+ * the 9p share.
+ *
+ * Cancellation shares one channel: the caller's `signal` and `kill()` abort
+ * the agent exec, which settles `done` as killed (`{exitCode: null, signal:
+ * "SIGTERM"}`) — the same shape the one-shot path reports for a killed search.
+ * A genuine agent failure (anything but unavailability) propagates through
+ * `done` as a rejection, which the tool classifies as a search failure.
+ *
+ * Pure shaping over injected collaborators, so the handle semantics are
+ * unit-testable without a distro.
+ *
+ * @module dsh-plugin-wsl/search-exec
+ */
+
+import { AgentUnavailableError } from "./agent-errors.js";
+
+/**
+ * The output-stream reader the search tool consumes: `handle.collected.stdout`
+ * / `stderr` expose `readFrom(offset)` with the seam's standard shape.
+ *
+ * @typedef {Object} SearchCollectedReader
+ * @property {(from: number) => {text: string, lossy: boolean, nextOffset: number}} readFrom
+ */
+
+/**
+ * The slice of the subprocess handle the file-search tool consumes
+ * (`dsh-tool-fs-search` `runRipgrep`): settle on `done`, then read the
+ * collected streams. Nothing else of the handle is contract.
+ *
+ * @typedef {Object} SearchExecutionHandle
+ * @property {Promise<{exitCode: number|null, signal: string|null}>} done
+ * @property {{stdout: SearchCollectedReader, stderr: SearchCollectedReader}} collected
+ * @property {() => boolean|void} [kill] - optional cooperative kill; the tool
+ *   relies on its `signal` for cancellation instead.
+ */
+
+/**
+ * Run one search command through the agent and present it as a search handle.
+ *
+ * @param object - the handle's collaborators.
+ * @param {object} object.agent - the {@link WslAgent}-like runner: `exec`
+ *   accepting `{cwd, argv, maxOutputBytes, signal}` and resolving
+ *   `{exitCode, stdout, stderr}`; throws `AgentUnavailableError` when out.
+ * @param {string} object.cwd - the Linux working directory to search from.
+ * @param {string[]} object.argv - the distro-side argv (`rg` and its arguments).
+ * @param {number} [object.maxOutputBytes] - per-stream capture ceiling the
+ *   agent enforces; the tool's own raw-output budget rides here.
+ * @param {AbortSignal} [object.signal] - the caller's cancellation.
+ * @param {() => object} object.spawnFallback - builds the one-shot handle the
+ *   facade delegates to when the agent is out; called at most once, lazily.
+ * @returns {object} the search handle (`done`, `collected`, `kill`).
+ */
+export function searchExecutionHandle({ agent, cwd, argv, maxOutputBytes = 0, signal, spawnFallback }) {
+  const state = { delegate: undefined, stdout: undefined, stderr: undefined };
+  const controller = new AbortController();
+  if (signal?.aborted) controller.abort(signal.reason);
+  else signal?.addEventListener("abort", () => controller.abort(signal.reason), { once: true });
+
+  const reader = (slot) => ({
+    readFrom(from) {
+      const buffer = state[slot] ?? Buffer.alloc(0);
+      const start = Math.min(from, buffer.length);
+      return { text: buffer.subarray(start).toString("utf8"), lossy: false, nextOffset: buffer.length };
+    },
+  });
+
+  /** @type {object} */
+  const handle = {
+    get collected() {
+      if (state.delegate !== undefined) return state.delegate.collected;
+      return { stdout: reader("stdout"), stderr: reader("stderr") };
+    },
+    done: (async () => {
+      let result;
+      try {
+        result = await agent.exec({ cwd, argv, maxOutputBytes, signal: controller.signal });
+        state.stdout = result.stdout;
+        state.stderr = result.stderr;
+      } catch (error) {
+        if (!(error instanceof AgentUnavailableError)) {
+          if (controller.signal.aborted) {
+            // Our kill() or the caller's cancellation: the killed outcome the
+            // one-shot path reports, not a failure.
+            return { exitCode: null, signal: "SIGTERM" };
+          }
+          throw error;
+        }
+        const delegate = spawnFallback();
+        state.delegate = delegate;
+        return delegate.done;
+      }
+      return { exitCode: result.exitCode, signal: null };
+    })(),
+    kill() {
+      controller.abort(new Error("killed"));
+      state.delegate?.kill?.();
+    },
+  };
+  return handle;
+}

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;
   }
 
   /**