dsh-plugin-wsl-env 0.5.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/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/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;
+}