dsh-plugin-wsl-env 0.1.10 → 0.2.0

package/lib/index.js

@@ -37,6 +37,7 @@
  */
 
 import { rename } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
 import z from "@deepseek-ai/schemastery";
 import { LocalBashExecutor } from "@deepseek-ai/dsh-bash-local";
 import { LocalFileSystem } from "@deepseek-ai/dsh-fs-local";
@@ -44,6 +45,12 @@ import { FsError } from "@deepseek-ai/dsh-fs";
 import { canonicalPath, classifyRunnerFailure, isRunnerSpawnFailure, matchesSignature, SandboxUnavailableError, writableRoots } from "@deepseek-ai/dsh-sandbox";
 import { isRelativeWorldPath, isWorldPathUnder, isWslUnc, isUnderDistro, posixToUnc, toDisplayPath, toLinuxPath, toWorldPath, uncToPosix } from "./paths.js";
 import { WslSandbox } from "./sandbox.js";
+import { armDistroWatcher } from "./watcher.js";
+import { WslAgent } from "./agent.js";
+import { AgentUnavailableError } from "./agent-errors.js";
+import { publicationArgv } from "./fs-publish.js";
+import { agentExecutionHandle } from "./agent-exec.js";
+import { sharedAgent } from "./agent-shared.js";
 // `runCapture` and distro discovery live in ./wsl.js so the directory picker
 // can use them without pulling this file's executor and filesystem peers in.
 import { canonicalLinuxPath, copyModeInDistro, defaultDistro, defaultShell, linuxHomePath, shellArgs, workdirFailure, wslErrorCode } from "./wsl.js";
@@ -180,6 +187,14 @@ export class WslShellExecutor extends LocalBashExecutor {
     maxOutputBytes: z.number().default(64e3).volatile(),
     maxSpillBytes: z.number().default(64 * 1024 * 1024).volatile(),
     graceMs: z.number().default(3e3).volatile(),
+    /**
+     * Run commands through the resident agent when it is up (one long-lived
+     * in-distro process; in-distro timeout semantics), falling back to the
+     * one-shot `wsl.exe` path whenever the agent is out. `false` never uses
+     * the agent. The confinement, the output budgets' shapes and the result
+     * decoration are identical on both paths.
+     */
+    agent: z.boolean().default(true),
   });
 
   constructor(ctx, config) {
@@ -249,6 +264,15 @@ export class WslShellExecutor extends LocalBashExecutor {
     return this.config.hostCwd.get() ?? process.env.SystemRoot ?? process.cwd();
   }
 
+  /**
+   * The shared resident agent serving this executor's distro.
+   * @param distro - the resolved distro name.
+   * @returns {WslAgent} the shared agent.
+   */
+  executionAgent(distro) {
+    return sharedAgent(distro);
+  }
+
   /**
    * The argv that runs INSIDE the distro for one spec: the resolved shell, its
    * login/command flags, and the command string. This is the argv a
@@ -492,6 +516,88 @@ export class WslShellExecutor extends LocalBashExecutor {
     const distro = await this.distro();
     const shell = await this.shell();
     const resolved = await this.withDefaultWorkdir(spec);
+    if (this.config.agent) {
+      try {
+        return await this.executeViaAgent(resolved, distro, shell);
+      } catch (error) {
+        // Only an out-of-service agent falls back; anything else (a cwd
+        // refusal, a sandbox refusal) is the command's own verdict.
+        if (!(error instanceof AgentUnavailableError)) throw error;
+      }
+    }
+    return this.executeOneShot(resolved, distro, shell);
+  }
+
+  /**
+   * The agent-backed execution path: one long-lived in-distro process, the
+   * confinement argv unchanged, the handle shape unchanged. Any
+   * {@link AgentUnavailableError} propagates for the caller's fallback.
+   * @param resolved - the resolved spec from {@link WslShellExecutor.execute}.
+   * @param distro - the resolved distro name.
+   * @param shell - the resolved distro shell.
+   * @returns the decorated execution result.
+   */
+  async executeViaAgent(resolved, distro, shell) {
+    const policy = resolved.sandboxPolicy;
+    const confined = this.sandbox !== undefined && policy !== undefined && policy.mode !== "danger-full-access"
+      ? await this.sandbox.confine(this.distroArgv(resolved, shell), { ...policy, mode: policy.mode }, { distro })
+      : undefined;
+    const mode = policy?.mode;
+    const execution = agentExecutionHandle({
+      agent: await this.executionAgent(distro),
+      // The one-shot path converts the spec's workdir into the distro's
+      // coordinate system inside argv(); the agent carries the cwd as a frame
+      // field, so the SAME conversion happens here — a raw UNC must never
+      // reach `chdir` (that is the bug this line fixes).
+      cwd: toLinuxPath(resolved.workdir, { distro }),
+      argv: confined !== undefined ? confined.argv : this.distroArgv(resolved, shell),
+      timeoutMs: resolved.timeoutMs,
+      signal: resolved.signal,
+      onStarted: confined !== undefined
+        ? (proc) => {
+            this.processFacts.set(proc, {
+              mode,
+              enforcement: confined.enforcement,
+              denialSignatures: confined.denialSignatures,
+              runnerFailureRules: confined.runnerFailureRules,
+              runnerProgram: confined.argv[0],
+              workdir: resolved.workdir,
+            });
+          }
+        : undefined,
+    });
+    return WslShellExecutor.decorateResult(execution, (result) => {
+      this.throwIfDistroUnavailable(result, distro);
+      this.throwIfWorkdirMissing(result, resolved.workdir);
+      if (this.sandbox === undefined) return result;
+      if (confined === undefined) return { ...result, sandbox: { mode, denied: false } };
+      const { enforcement, denialSignatures, runnerFailureRules } = confined;
+      const runnerFailure = classifyRunnerFailure(result.exitCode, result.stderr.text, runnerFailureRules);
+      if (runnerFailure !== undefined) throw new SandboxUnavailableError(mode, runnerFailure.detail);
+      return {
+        ...result,
+        sandbox: {
+          mode,
+          denied: matchesSignature(result.exitCode, result.stderr.text, denialSignatures),
+          enforcement,
+        },
+      };
+    }, (error) => {
+      if (resolved.signal?.aborted === true) resolved.signal.throwIfAborted();
+      throw error;
+    });
+  }
+
+  /**
+   * The pre-agent execution path, verbatim: one `wsl.exe` per command through
+   * the inherited `executeArgv` machinery. Kept as the permanent fallback for
+   * an out-of-service agent and as the `agent: false` behaviour.
+   * @param resolved - the resolved spec.
+   * @param distro - the resolved distro name.
+   * @param shell - the resolved distro shell.
+   * @returns the decorated execution result.
+   */
+  async executeOneShot(resolved, distro, shell) {
     const policy = resolved.sandboxPolicy;
     if (this.sandbox === undefined || policy === undefined || policy.mode === "danger-full-access") {
       // `executeArgv` resolves to the execution handle, so it has to be awaited
@@ -626,6 +732,15 @@ export class WslFileSystem extends LocalFileSystem {
      * distinct failing path, cached.
      */
     resolveSymlinks: z.boolean().default(true),
+    /**
+     * Run the in-distro side of publication (mode copy + atomic rename) through
+     * the resident agent (`agent/wsl-agent.sh`), one round trip instead of a
+     * `wsl.exe` chmod plus a 9p rename. Any agent failure falls back to the
+     * legacy two-step path for that call and, after the agent's own rebuild
+     * budget is spent, permanently — this flag never changes what is published,
+     * only how many round trips it costs.
+     */
+    agent: z.boolean().default(true),
   });
 
   constructor(ctx, config) {
@@ -692,11 +807,45 @@ export class WslFileSystem extends LocalFileSystem {
     const source = uncToPosix(replaced);
     const staged = uncToPosix(replacement);
     if (source !== undefined && staged !== undefined) {
+      if (this.config.agent) {
+        try {
+          // One in-distro round trip: mode copy + atomic rename. The staged
+          // temp is on the share, but the agent reaches it by its Linux path,
+          // where the kernel does the rename — no 9p publication involved.
+          const agent = await this.publicationAgent();
+          const result = await agent.exec({
+            cwd: "/",
+            argv: publicationArgv(source.linuxPath, staged.linuxPath),
+            timeoutMs: 30000,
+          });
+          if (result.exitCode === 0) return;
+          // A nonzero from the script is a real publication failure (chmod or
+          // rename); report it rather than retrying through the legacy path,
+          // which would fail the same way but slower.
+          throw new FsError(`publishing "${replaced}" failed inside the distro (exit ${result.exitCode})`, "FS_IO_ERROR");
+        } catch (error) {
+          // The agent being out is the ONLY thing the legacy path exists for.
+          if (!(error instanceof AgentUnavailableError)) throw error;
+        }
+      }
       await copyModeInDistro(source.distro, source.linuxPath, staged.linuxPath, { wslPath: this.config.wslPath });
     }
     await rename(replacement, replaced);
   }
 
+  /**
+   * The resident agent serving this filesystem's in-distro side work, created
+   * on first use and kept for the provider's lifetime (its own idle timer
+   * retires the process; a later call starts a fresh one).
+   * @returns {Promise<WslAgent>} the agent for the pinned distro.
+   */
+  async publicationAgent() {
+    if (this.agentInstance === undefined) {
+      this.agentInstance = sharedAgent(await this.distro());
+    }
+    return this.agentInstance;
+  }
+
   /**
    * The pinned distro, resolving WSL's default on first use.
    * @returns the distro name.
@@ -796,7 +945,23 @@ export class WslFileSystem extends LocalFileSystem {
     if (cached !== undefined) return cached;
     const parsed = uncToPosix(target.targetKey);
     if (parsed === undefined) return undefined;
-    const canonical = await canonicalLinuxPath(parsed.distro, parsed.linuxPath, { wslPath: this.config.wslPath, signal });
+    // The agent serves the canonical path when it is up (no extra `wsl.exe`
+    // per distinct failing path); the one-shot helper is the fallback and the
+    // `agent: false` path.
+    let canonical;
+    if (this.config.agent) {
+      try {
+        const agent = await this.publicationAgent();
+        const result = await agent.exec({ cwd: "/", argv: ["readlink", "-f", parsed.linuxPath], timeoutMs: 10000, signal });
+        const resolved = result.stdout.toString("utf8").trim();
+        canonical = resolved.startsWith("/") ? resolved : undefined;
+      } catch (error) {
+        if (!(error instanceof AgentUnavailableError)) throw error;
+      }
+    }
+    if (canonical === undefined) {
+      canonical = await canonicalLinuxPath(parsed.distro, parsed.linuxPath, { wslPath: this.config.wslPath, signal });
+    }
     if (canonical === undefined || canonical === parsed.linuxPath) return undefined;
     const replacement = { targetKey: posixToUnc(parsed.distro, canonical), displayPath: target.displayPath };
     this.canonicalTargets.set(target.targetKey, replacement);
@@ -885,13 +1050,33 @@ export class WslFileSystem extends LocalFileSystem {
   }
 
   /**
-   * Watching a 9p share is neither reliable nor cheap, so this provider refuses
-   * rather than arming a watcher that may never fire — the seam's documented
-   * failure mode for a provider that cannot watch.
-   * @returns a rejection carrying `FS_IO_ERROR`.
+   * Watch from inside the distro, where the kernel can actually report change:
+   * a long-lived `wsl.exe` poll loop (`lib/watcher.js`) fires the seam's
+   * invalidation callback. The seam asks for coarse invalidation, not events,
+   * so a poll is honest — and creations and deletions are both seen, because
+   * they bump the parent directory's mtime. Replaces the previous flat
+   * refusal (`FS_IO_ERROR`), which was the correct answer over 9p only.
+   *
+   * @param target - the resolved file or directory to observe.
+   * @param changed - the invalidation callback.
+   * @param signal - cancels initialization; the caller closes an armed watcher.
+   * @returns resolves once active, with the async close function.
    */
-  watch() {
-    return Promise.reject(new FsError("Filesystem watching is not supported over the WSL UNC share.", "FS_IO_ERROR"));
+  async watch(target, changed, signal) {
+    signal.throwIfAborted();
+    const parsed = uncToPosix(target.targetKey);
+    if (parsed === undefined) {
+      throw new FsError(`cannot watch "${target.displayPath}": not a path inside the distro`, "FS_IO_ERROR");
+    }
+    const distro = await this.distro();
+    return armDistroWatcher({
+      wslPath: this.config.wslPath,
+      distro,
+      linuxPath: parsed.linuxPath,
+      onChange: changed,
+      onError: (error) => changed(error),
+      signal,
+    });
   }
 
   /**

package/lib/ports.js

@@ -0,0 +1,61 @@
+/**
+ * Listening-port visibility for the distro, the Remote-WSL port-forwarding
+ * parity row's DSH-side half.
+ *
+ * There is no DSH channel that streams live facts to the model; the sanctioned
+ * one is the managed `DSH_*` namespace (`ctx.shellEnv`), whose `resolve` is
+ * SYNCHRONOUS. So the snapshot is refreshed on a timer and served stale-but-
+ * recent: `DSH_WSL_PORTS` names the ports with a listener inside the distro,
+ * at most `refreshMs` old. A dev server the model starts shows up on the next
+ * refresh, which is the granularity that matters at conversational pace.
+ *
+ * The scan reads `/proc/net/tcp` and `/proc/net/tcp6` directly — no `ss`, no
+ * `netstat`, nothing to install — and keeps sockets in state `0A` (LISTEN).
+ * Pure parser, unit-testable without a distro.
+ *
+ * @module dsh-plugin-wsl/ports
+ */
+
+/**
+ * Parse one `/proc/net/tcp{,6}` body into listening ports.
+ * @param {string} text - the file's content.
+ * @returns {number[]} deduplicated listening ports, ascending.
+ */
+export function parseListeningPorts(text) {
+  const ports = new Set();
+  for (const line of text.split("\n").slice(1)) {
+    const columns = line.trim().split(/\s+/);
+    // sl, local_address, rem_address, st, ... — st 0A is LISTEN.
+    if (columns.length < 4 || columns[3] !== "0A") continue;
+    const portHex = columns[1].split(":")[1];
+    if (portHex === undefined) continue;
+    const port = Number.parseInt(portHex, 16);
+    if (Number.isFinite(port) && port > 0) ports.add(port);
+  }
+  return [...ports].sort((a, b) => a - b);
+}
+
+/**
+ * The shell script that prints both proc files' contents.
+ * @returns {string} the `sh -c` body.
+ */
+export function procNetScript() {
+  return "cat /proc/net/tcp /proc/net/tcp6 2>/dev/null";
+}
+
+/**
+ * Snapshot the distro's listening ports through the agent.
+ * @param {object} runner - the {@link WslAgent}-like runner.
+ * @param {number} [timeoutMs] - the exec budget.
+ * @returns {Promise<number[]>} listening ports, ascending; [] on any failure —
+ *   a snapshot is a convenience, never an error the session should see.
+ */
+export async function listeningPorts(runner, timeoutMs = 10000) {
+  try {
+    const result = await runner.exec({ cwd: "/", argv: ["sh", "-c", procNetScript(), "ports"], timeoutMs });
+    if (result.exitCode !== 0) return [];
+    return parseListeningPorts(result.stdout.toString("utf8"));
+  } catch {
+    return [];
+  }
+}

package/lib/sandbox.js

@@ -146,7 +146,9 @@ export class WslSandbox {
     if (!(await this.usable(distro, signal))) {
       throw new SandboxUnavailableError(
         policy.mode,
-        `bwrap is not usable inside distro "${distro}" (install it: sudo apt install bubblewrap)`,
+        `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 });

package/lib/shell-env.js

@@ -26,6 +26,8 @@
 import z from "@deepseek-ai/schemastery";
 import { isWslUnc } from "./paths.js";
 import { defaultDistro, defaultShell, linuxHomePath } from "./wsl.js";
+import { sharedAgent } from "./agent-shared.js";
+import { listeningPorts } from "./ports.js";
 
 export const name = "wsl-shell-env";
 
@@ -34,6 +36,8 @@ export const inject = ["shellEnv"];
 export const Config = z.object({
   /** Distro these facts describe; empty means this machine's default distro. */
   distro: z.string().default(""),
+  /** How often the listening-port snapshot refreshes, in milliseconds. */
+  portsRefreshMs: z.number().default(10 * 1000),
 });
 
 export async function apply(ctx, config = {}) {
@@ -56,7 +60,21 @@ export async function apply(ctx, config = {}) {
     DSH_WSL_HOME: {
       description: `Home directory of the user model shell calls run as inside ${distro}.`,
     },
+    DSH_WSL_PORTS: {
+      description: `Ports with a listener inside ${distro} (comma-separated, ascending), as of the last snapshot — refreshed every ${Math.round(config.portsRefreshMs / 1000)}s, so a dev server started moments ago may not be listed yet. Empty means none were listening at the last scan.`,
+    },
+  };
+
+  // The port snapshot refreshes on a timer and is served synchronously: the
+  // registry's resolve is sync by contract, so live reads are impossible —
+  // the timer bounds staleness instead (see lib/ports.js).
+  let ports = [];
+  const refreshPorts = async () => {
+    ports = await listeningPorts(sharedAgent(distro), 8000);
   };
+  void refreshPorts();
+  const portsTimer = setInterval(() => void refreshPorts(), config.portsRefreshMs);
+  portsTimer.unref?.();
 
   const dispose = ctx.shellEnv.register({
     name: "dsh-plugin-wsl-env",
@@ -64,11 +82,19 @@ export async function apply(ctx, config = {}) {
     resolve: (execution) => {
       const cwd = execution?.agent?.session?.header?.cwd;
       if (!isWslUnc(cwd)) return {};
-      return { DSH_WSL_DISTRO: distro, DSH_WSL_SHELL: shell, DSH_WSL_HOME: home };
+      return {
+        DSH_WSL_DISTRO: distro,
+        DSH_WSL_SHELL: shell,
+        DSH_WSL_HOME: home,
+        DSH_WSL_PORTS: ports.join(","),
+      };
     },
   });
 
   // Disposing matters: a config hot-reload re-runs apply(), and the registry
   // rejects a second contributor claiming the same keys.
-  ctx.effect(() => dispose);
+  ctx.effect(() => {
+    clearInterval(portsTimer);
+    dispose();
+  });
 }

package/lib/subprocess.js

@@ -74,6 +74,7 @@ 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 { terminalRoute } from "./terminal-route.js";
 
 /**
  * Env names a terminal launch keeps for the distro. `TERM` rides along because
@@ -120,6 +121,13 @@ export class WslSubprocessRuntime extends LocalSubprocessRuntime {
     hostCwd: z.string().volatile(),
     /** Extra env names to forward into the distro through WSLENV. */
     forwardEnv: z.array(z.string()).default([]),
+    /**
+     * Give a session opened on a WINDOWS folder a host shell instead of the
+     * distro's shell started at `/mnt/<drive>/…`. WSL-folder sessions always
+     * get the distro shell — that is this provider's purpose. `false` restores
+     * the composition-owned terminal for every session.
+     */
+    hostSessions: z.boolean().default(true),
   });
 
   constructor(ctx, config) {
@@ -185,6 +193,13 @@ export class WslSubprocessRuntime extends LocalSubprocessRuntime {
    */
   async spawnTerminal(spec) {
     if (!this.launchesDistro(spec.argv)) return super.spawnTerminal(spec);
+    // A session on a Windows folder is a HOST session: it gets the host shell
+    // in its own directory, not the distro's shell at `/mnt/<drive>/…`. The
+    // wsl.exe argv still names this provider's launch, so the substitution
+    // stays inside the override — every other consumer is untouched.
+    if (this.config.hostSessions && terminalRoute(spec.cwd) === "host") {
+      return super.spawnTerminal({ ...spec, argv: ["powershell.exe", "-NoLogo"] });
+    }
     const target = await this.terminalTarget(spec.cwd);
     const argv = wslTerminalArgv({
       wslPath: this.config.wslPath,

package/lib/terminal-route.js

@@ -0,0 +1,31 @@
+/**
+ * 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.
+ *
+ * @module dsh-plugin-wsl/terminal-route
+ */
+
+import { isPosixAbsolute, uncToPosix, windowsToLinuxMount } from "./paths.js";
+
+/**
+ * @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";
+}

package/lib/watcher.js

@@ -0,0 +1,127 @@
+/**
+ * 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.
+ *
+ * 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.
+ *
+ * @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.
+ * @returns {string} the `sh -c` script body.
+ */
+export function watchLoopScript(intervalSeconds = 2) {
+  const seconds = Math.max(1, Math.floor(intervalSeconds));
+  // `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 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 [ -n "$(find "$D" -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); 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 {(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 }) {
+  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]);
+    let settled = false;
+    let closed = false;
+    const lines = createInterface({ input: child.stdout });
+    lines.on("line", (line) => {
+      if (line === "R") {
+        if (!settled && !signal?.aborted) {
+          settled = true;
+          resolve(close);
+        }
+        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) => {
+      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) => {
+      if (!closed) fail(new Error(`distro watcher exited unexpectedly (code=${code} signal=${signalName ?? "none"})`));
+    });
+
+  });
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-plugin-wsl-env",
-  "version": "0.1.10",
-  "description": "Run a DeepSeek Harness session against a WSL distro: commands and the model's file tools run inside it, the folder picker and the GUI terminal open there, and commands are confined by bubblewrap inside the distro",
+  "version": "0.2.0",
+  "description": "让 DeepSeek Harness 以 WSL 子系统作为会话的执行环境：shell、文件读写与命令执行均在子系统内完成，目录选择器与 GUI 终端同样定位到子系统路径，并通过子系统内的 bubblewrap 对命令进行沙箱隔离",
   "keywords": [
     "deepseek-harness",
     "dsh",
@@ -22,6 +22,7 @@
     "./shell-env": "./lib/shell-env.js",
     "./wsl": "./lib/wsl.js",
     "./paths": "./lib/paths.js",
+    "./agent": "./lib/agent.js",
     "./package.json": "./package.json"
   },
   "dsh": {
@@ -31,12 +32,14 @@
   },
   "files": [
     "lib/**/*.js",
+    "agent/*.sh",
     "cordis.patch.yml",
     "examples/**/*.yml",
     "README.md",
     "docs/README.zh.md",
     "docs/CONFIGURATION.md",
     "docs/LIMITATIONS.md",
+    "docs/PARITY.md",
     "docs/ARCHITECTURE.md",
     "CHANGELOG.md",
     "CONTRIBUTING.md",
@@ -48,7 +51,7 @@
     "test": "npm run lint:style && npm run test:syntax && npm run test:unit",
     "test:coverage": "node --test --experimental-test-coverage --test-coverage-lines=85 --test-coverage-branches=85 --test-coverage-functions=70 test/paths.test.mjs test/listing.test.mjs test/shell.test.mjs test/terminal.test.mjs test/probe-cache.test.mjs test/preset-choice.test.mjs",
     "test:syntax": "node test/syntax.mjs",
-    "test:unit": "node --test test/paths.test.mjs test/listing.test.mjs test/shell.test.mjs test/terminal.test.mjs test/probe-cache.test.mjs test/preset-choice.test.mjs test/sandbox.test.mjs",
+    "test:unit": "node --test test/paths.test.mjs test/listing.test.mjs test/shell.test.mjs test/terminal.test.mjs test/probe-cache.test.mjs test/preset-choice.test.mjs test/sandbox.test.mjs test/agent-protocol.test.mjs test/agent.test.mjs test/fs-publish.test.mjs test/agent-exec.test.mjs test/ports.test.mjs test/watcher.test.mjs",
     "lint:style": "node test/style.mjs",
     "prepublishOnly": "npm test",
     "probe": "bash test/probe/run.sh",
@@ -59,7 +62,10 @@
     "probe:terminal": "bash test/probe/terminal.sh",
     "probe:sandbox": "bash test/probe/sandbox.sh",
     "probe:sandbox-shell": "bash test/probe/sandbox-shell.sh",
-    "sync:windows": "bash test/probe/sync-to-windows.sh"
+    "sync:windows": "bash test/probe/sync-to-windows.sh",
+    "probe:watch": "bash test/probe/watch.sh",
+    "probe:exec": "bash test/probe/exec.sh",
+    "bootstrap": "bash scripts/bootstrap.sh"
   },
   "engines": {
     "node": ">=20"