dsh-plugin-wsl-env 0.1.10 → 0.3.0

package/lib/index.js

@@ -37,13 +37,23 @@
  */
 
 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";
 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 { isRelativeWorldPath, isWorldPathUnder, isWslUnc, isUnderDistro, posixToUnc, toDisplayPath, toLinuxPath, toWorldPath, uncToPosix, windowsToLinuxMount } 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";
+import { AgentSubstrate } from "./fs-substrate.js";
+import { FsCodedError } from "./fsio-text.js";
+import { confinedAgent } from "./agent-confined.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";
@@ -165,6 +175,20 @@ export class WslShellExecutor extends LocalBashExecutor {
      * unconfined and `sandboxMode` is `undefined`, so the model is told so.
      */
     sandbox: z.boolean().default(true),
+    /**
+     * Shadow `/mnt` with an empty tmpfs in every confined profile, hiding the
+     * Windows drive from confined commands: its files cannot be read or
+     * exfiltrated and its executables cannot be launched through interop —
+     * the hole that lets a "sandboxed" command reach your full Windows token.
+     * A narrowing, not a closure (a command can still write an executable
+     * into the workspace and run it — binfmt dispatches on content, not
+     * location), so enforcement stays `partial` and the sandbox fact reports
+     * `windowsDrive: "masked"`. Costs: confined commands cannot read or touch
+     * anything under `/mnt`, and tools that probe the drive degrade. The
+     * complete closure is distro-level: `[interop] enabled=false` in
+     * `wsl.conf`.
+     */
+    maskWindowsDrive: z.boolean().default(false),
     /**
      * Default workdir for a request that names none; accepts `/home/andy/proj`,
      * a UNC path, or `C:\...`. Empty — the default — means the distro user's
@@ -180,6 +204,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 +281,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
@@ -423,6 +464,7 @@ export class WslShellExecutor extends LocalBashExecutor {
         mode: facts.mode,
         denied: !runnerFailed && matchesSignature(proc.exitCode, stderr, facts.denialSignatures),
         enforcement: facts.enforcement,
+        ...(facts.windowsDrive ? { windowsDrive: facts.windowsDrive } : {}),
         ...(runnerFailed ? { runnerFailed } : {}),
       };
     }
@@ -492,6 +534,94 @@ 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,
+      // The agent enforces the collect budget distro-side (the EXEC frame
+      // carries it); `maxSpillBytes` stays one-shot-only — the agent path has
+      // no spill files by design, its capture is bounded instead.
+      maxOutputBytes: this.config.maxOutputBytes,
+      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,
+              windowsDrive: confined.windowsDrive,
+            });
+          }
+        : 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, windowsDrive } = 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,
+          windowsDrive,
+        },
+      };
+    }, (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
@@ -529,6 +659,7 @@ export class WslShellExecutor extends LocalBashExecutor {
           runnerFailureRules: confined.runnerFailureRules,
           runnerProgram: confined.argv[0],
           workdir: resolved.workdir,
+          windowsDrive: confined.windowsDrive,
         });
       },
     );
@@ -536,7 +667,7 @@ export class WslShellExecutor extends LocalBashExecutor {
       this.throwIfDistroUnavailable(result, distro);
       this.throwIfWorkdirMissing(result, resolved.workdir);
       if (confined === undefined) return { ...result, sandbox: { mode, denied: false } };
-      const { enforcement, denialSignatures, runnerFailureRules } = confined;
+      const { enforcement, denialSignatures, runnerFailureRules, windowsDrive } = confined;
       // Runner failure outranks denial because the command did not run at all.
       const runnerFailure = classifyRunnerFailure(result.exitCode, result.stderr.text, runnerFailureRules);
       if (runnerFailure !== undefined) throw new SandboxUnavailableError(mode, runnerFailure.detail);
@@ -546,6 +677,7 @@ export class WslShellExecutor extends LocalBashExecutor {
           mode,
           denied: matchesSignature(result.exitCode, result.stderr.text, denialSignatures),
           enforcement,
+          windowsDrive,
         },
       };
     }, (error) => {
@@ -610,6 +742,14 @@ export class WslFileSystem extends LocalFileSystem {
      * operations are unconfined.
      */
     sandbox: z.boolean().default(true),
+    /**
+     * Shadow `/mnt` with an empty tmpfs in every confined profile, hiding the
+     * Windows drive from confined commands — same meaning and same honest
+     * limits as the `wsl-shell` key of the same name (its doc carries the
+     * full story). Confined fs mutations publish through the masked resident;
+     * reads and the share substrate are unaffected.
+     */
+    maskWindowsDrive: z.boolean().default(false),
     /**
      * Refuse any path that leaves the pinned distro. A WSL filesystem is a
      * whole-Linux view whose `/mnt/c` also reaches the Windows disk, so without
@@ -626,6 +766,28 @@ 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),
+    /**
+     * Which I/O substrate serves the file tools. `"agent"` (the default) —
+     * the resident in-distro agent (`lib/fs-substrate.js`): reads, writes,
+     * identities and watches run where the files live, symlinks and mode bits
+     * are native, and the mutation guard survives to the write's no-replace
+     * publication, kernel-enforced by the confined resident when the policy is
+     * confined. `"share"` — the opt-out: the Windows-side host filesystem
+     * stack over the distro's 9p share, with the symlink-retry and publication
+     * hooks that compensate for what the share cannot do. Both substrates
+     * fence writes with the same host-side policy check; neither changes
+     * `sandboxMode`'s honesty.
+     */
+    substrate: z.union(["share", "agent"]).default("agent"),
   });
 
   constructor(ctx, config) {
@@ -637,6 +799,10 @@ export class WslFileSystem extends LocalFileSystem {
     this.defaultMode = ctx.sandboxPolicy.defaultMode;
     /** targetKey -> canonical replacement target, for symlinked paths. */
     this.canonicalTargets = new Map();
+    /** The lazy agent-backed substrate, built on first use (see `agentSubstrate`). */
+    this.agentSubstrateInstance = undefined;
+    /** The distro-side bwrap usability probe, shared with the confined agents. */
+    this.sandbox = new WslSandbox({ wslPath: config.wslPath, maskWindowsDrive: config.maskWindowsDrive });
     // `dsh-fs-local` takes a Windows branch whenever the destination already
     // exists — which is how it knows to preserve the replaced file's security
     // descriptor, and what makes every write to an existing file fail here:
@@ -692,11 +858,117 @@ 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 agent-backed substrate for `substrate: "agent"`, built on first use
+   * over the same resident agent the publication path shares.
+   * @returns {Promise<AgentSubstrate|undefined>} the substrate, or undefined
+   *   when the share backend is configured.
+   */
+  async agentSubstrate() {
+    if (this.config.substrate !== "agent") return undefined;
+    if (this.agentSubstrateInstance === undefined) {
+      this.agentSubstrateInstance = new AgentSubstrate({
+        agent: await this.publicationAgent(),
+        distro: await this.distro(),
+        diffBasisMaxBytes: this.config.diffBasisMaxBytes,
+        agentFor: (policy) => this.mutationAgent(policy),
+      });
+    }
+    return this.agentSubstrateInstance;
+  }
+
+  /**
+   * The agent a MUTATION runs on under this resolved policy — stage-two
+   * routing. A confined policy addresses the confined resident whose bwrap
+   * profile binds exactly what the mode grants, so the kernel enforces what
+   * the check decided; an escalated write (`danger-full-access`) or a disabled
+   * sandbox addresses the plain resident, which is what those mean. A distro
+   * without a usable bwrap refuses confined mutations instead of downgrading
+   * them — the same closed failure the command path has.
+   * @param {{mode: string, workspaceRoot: string}|undefined} policy - the
+   *   resolved file-effect policy, or undefined when the caller pre-checked.
+   * @returns {Promise<WslAgent>} the agent to publish through.
+   */
+  async mutationAgent(policy) {
+    if (!policy || !this.config.sandbox || policy.mode === "danger-full-access") {
+      return this.publicationAgent();
+    }
+    const distro = await this.distro();
+    if (!(await this.sandbox.usable(distro))) {
+      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`,
+      );
+    }
+    return confinedAgent({ distro, wslPath: this.config.wslPath, policy, maskWindowsDrive: this.config.maskWindowsDrive });
+  }
+
+  /**
+   * Map a substrate error onto the peer's `FsError`, so the tool layer reads
+   * the same refusal dialect on both substrates. An agent that is out becomes
+   * an I/O error naming the cause — the share backend's "distro is gone" case
+   * is the same availability, but the message says which substrate failed.
+   * @param error - what the substrate raised.
+   * @returns {FsError} the error to surface.
+   */
+  peerError(error) {
+    if (error instanceof FsCodedError) return new FsError(error.message, error.code, { cause: error });
+    if (error instanceof SandboxUnavailableError) return new FsError(error.message, "FS_IO_ERROR", { cause: error });
+    const message = error instanceof Error ? error.message : String(error);
+    return new FsError(`the distro file substrate is unavailable: ${message}`, "FS_IO_ERROR", { cause: error instanceof Error ? error : undefined });
+  }
+
+  /**
+   * One resolved target's Linux path — the substrate's coordinate — falling
+   * back to the display spelling when the identity is not a distro share path.
+   * @param target - the resolved target.
+   * @returns the absolute Linux path.
+   */
+  linuxOf(target) {
+    return uncToPosix(target.targetKey)?.linuxPath ?? target.displayPath;
+  }
+
   /**
    * The pinned distro, resolving WSL's default on first use.
    * @returns the distro name.
@@ -743,8 +1015,19 @@ export class WslFileSystem extends LocalFileSystem {
    * @returns the resolved `FsTarget`.
    */
   async resolve(path, opts) {
+    const world = await this.worldPath(path, opts?.cwd);
+    const sub = await this.agentSubstrate();
+    if (sub !== undefined) {
+      const linux = uncToPosix(world)?.linuxPath ?? windowsToLinuxMount(world);
+      if (linux === undefined) throw new FsError(`cannot serve "${path}" from inside the distro`, "FS_IO_ERROR");
+      try {
+        return await sub.resolve(linux, opts?.signal);
+      } catch (error) {
+        throw this.peerError(error);
+      }
+    }
     const distro = await this.distro();
-    const target = await super.resolve(await this.worldPath(path, opts?.cwd), opts);
+    const target = await super.resolve(world, opts);
     return { targetKey: target.targetKey, displayPath: toDisplayPath(target.targetKey, distro) };
   }
 
@@ -796,7 +1079,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);
@@ -837,22 +1136,86 @@ export class WslFileSystem extends LocalFileSystem {
   }
 
   async stat(target, signal) {
+    const sub = await this.agentSubstrate();
+    if (sub !== undefined) {
+      try {
+        return await sub.stat(target, signal);
+      } catch (error) {
+        throw this.peerError(error);
+      }
+    }
     return this.withCanonicalRetry(target, signal, (t) => super.stat(t, signal));
   }
 
+  /**
+   * No-follow stat one path. The agent substrate answers from the distro,
+   * where a symlink is a first-class entry; the share backend keeps the
+   * inherited host behaviour.
+   * @param path - a Linux, UNC or Windows path.
+   * @param opts - optional `cwd` override.
+   * @param signal - optional cancellation.
+   * @returns the path info, or undefined when absent.
+   */
+  async lstat(path, opts, signal) {
+    const sub = await this.agentSubstrate();
+    if (sub !== undefined) {
+      const world = await this.worldPath(path, opts?.cwd);
+      const linux = uncToPosix(world)?.linuxPath ?? windowsToLinuxMount(world);
+      if (linux === undefined) throw new FsError(`cannot inspect "${path}" from inside the distro`, "FS_IO_ERROR");
+      try {
+        return await sub.lstat(linux, signal);
+      } catch (error) {
+        throw this.peerError(error);
+      }
+    }
+    return super.lstat(path, opts, signal);
+  }
+
   async readText(target, signal) {
+    const sub = await this.agentSubstrate();
+    if (sub !== undefined) {
+      try {
+        return await sub.readText(target, signal);
+      } catch (error) {
+        throw this.peerError(error);
+      }
+    }
     return this.withCanonicalRetry(target, signal, (t) => super.readText(t, signal));
   }
 
   async streamText(target, signal) {
+    const sub = await this.agentSubstrate();
+    if (sub !== undefined) {
+      try {
+        return await sub.streamText(target, signal);
+      } catch (error) {
+        throw this.peerError(error);
+      }
+    }
     return this.withCanonicalRetry(target, signal, (t) => super.streamText(t, signal));
   }
 
   async readBytes(target, signal, maxBytes) {
+    const sub = await this.agentSubstrate();
+    if (sub !== undefined) {
+      try {
+        return await sub.readBytes(target, signal, maxBytes);
+      } catch (error) {
+        throw this.peerError(error);
+      }
+    }
     return this.withCanonicalRetry(target, signal, (t) => super.readBytes(t, signal, maxBytes));
   }
 
   async readByteRange(target, range, signal) {
+    const sub = await this.agentSubstrate();
+    if (sub !== undefined) {
+      try {
+        return await sub.readByteRange(target, range, signal);
+      } catch (error) {
+        throw this.peerError(error);
+      }
+    }
     return this.withCanonicalRetry(target, signal, (t) => super.readByteRange(t, range, signal));
   }
 
@@ -866,6 +1229,16 @@ export class WslFileSystem extends LocalFileSystem {
    * @returns the directory rows.
    */
   async listDir(target, signal) {
+    const sub = await this.agentSubstrate();
+    if (sub !== undefined) {
+      // The substrate's rows already carry Linux display paths and canonical
+      // identities, so no share-side rewrite follows.
+      try {
+        return await sub.listDir(target, signal);
+      } catch (error) {
+        throw this.peerError(error);
+      }
+    }
     const entries = await this.withCanonicalRetry(target, signal, (t) => super.listDir(t, signal));
     const distro = await this.distro();
     return entries.map((entry) => ({
@@ -885,13 +1258,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,
+    });
   }
 
   /**
@@ -926,9 +1319,25 @@ export class WslFileSystem extends LocalFileSystem {
    * @returns the write outcome.
    */
   async writeText(target, content, expected, signal, sandboxPolicy) {
+    // The policy resolves once: the fence and the confined routing must see
+    // the same grant, or the kernel would enforce something other than what
+    // was checked.
+    const policy = sandboxPolicy ?? this.ctx.sandboxPolicy.resolve();
     // The fence runs first and its fresh target is the one checked and written,
     // so a refusal costs no I/O and cannot be raced by a swapped symlink.
-    const fenced = await this.checkedTarget(target, sandboxPolicy);
+    const fenced = await this.checkedTarget(target, policy);
+    const sub = await this.agentSubstrate();
+    if (sub !== undefined) {
+      // The agent substrate keeps the guard: the distro-side no-replace link
+      // is an atomic primitive, so the check-then-write window the share
+      // backend documents closes here, exactly as on a Linux host. The policy
+      // also selects the confined resident whose mount table matches it.
+      try {
+        return await sub.writeText(fenced, content, expected, signal, policy);
+      } catch (error) {
+        throw this.peerError(error);
+      }
+    }
     await this.assertGuard(fenced, expected, signal);
     // The guard is deliberately not forwarded: the host backend would publish a
     // guarded creation with a hard link, which this filesystem rejects. Once
@@ -948,7 +1357,16 @@ export class WslFileSystem extends LocalFileSystem {
    * @returns the edit outcome.
    */
   async editText(target, edit, expected, signal, sandboxPolicy) {
-    const fenced = await this.checkedTarget(target, sandboxPolicy);
+    const policy = sandboxPolicy ?? this.ctx.sandboxPolicy.resolve();
+    const fenced = await this.checkedTarget(target, policy);
+    const sub = await this.agentSubstrate();
+    if (sub !== undefined) {
+      try {
+        return await sub.editText(fenced, edit, expected, signal, policy);
+      } catch (error) {
+        throw this.peerError(error);
+      }
+    }
     await this.assertGuard(fenced, expected, signal);
     return super.editText(fenced, edit, undefined, 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 [];
+  }
+}