dsh-plugin-wsl-env 0.5.0 → 0.7.2

package/lib/index.js

@@ -36,20 +36,18 @@
  * @module dsh-plugin-wsl
  */
 
-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 { isAnotherDistrosUnc, isRelativeWorldPath, isWorldPathUnder, isWslUnc, isUnderDistro, posixToUnc, toDisplayPath, toLinuxPath, toWorldPath, uncToPosix, windowsToLinuxMount } from "./paths.js";
-import { guardRefusal, isConfinedMutation, mutationModeRefusal, outsideDistroRefusal, substrateFailure, workspaceWriteDenial } from "./fs-decisions.js";
+import { isAnotherDistrosUnc, isRelativeWorldPath, isWorldPathUnder, isWslUnc, isUnderDistro, posixToUnc, toLinuxPath, toWorldPath, uncToPosix, windowsToLinuxMount } from "./paths.js";
+import { isConfinedMutation, mutationModeRefusal, outsideDistroRefusal, shareSubstrateRefusal, substrateFailure, workspaceWriteDenial } from "./fs-decisions.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";
@@ -57,7 +55,7 @@ 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";
+import { defaultDistro, defaultShell, linuxHomePath, shellArgs, workdirFailure, wslErrorCode } from "./wsl.js";
 
 /**
  * Every model shell call gets a rebuilt managed `DSH_*` namespace (see
@@ -580,7 +578,7 @@ export class WslShellExecutor extends LocalBashExecutor {
   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 })
+      ? await this.sandbox.confine(this.distroArgv(resolved, shell), { ...policy, mode: policy.mode }, { distro, signal: resolved.signal })
       : undefined;
     const mode = policy?.mode;
     const execution = agentExecutionHandle({
@@ -780,75 +778,48 @@ export class WslFileSystem extends LocalFileSystem {
      */
     restrictToDistro: z.boolean().default(true),
     /**
-     * When a read-side operation reports `FS_NOT_FOUND` on a Linux path, ask the
-     * distro for that path's canonical form and retry once. This is what makes
-     * symlinked paths usable at all: the UNC share cannot traverse Linux
-     * symlinks, so `/etc/os-release`, `/bin` and `/lib` would otherwise be
-     * unreachable from the model's read tools. Costs one `wsl.exe` call per
-     * distinct failing path, cached.
+     * How deep the in-distro watch scan walks, `1` = the watched directory and
+     * its direct children. `0` — the default — walks the whole tree, which is
+     * what the invalidation contract asks for but a real cost every poll over
+     * a tree containing a `node_modules`; a bound trades that cost for a
+     * documented blind spot: a change below the bound is not seen until
+     * another change above it fires the same callback.
      */
-    resolveSymlinks: z.boolean().default(true),
+    watchMaxDepth: z.natural().default(0),
     /**
-     * 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
+     * Which I/O substrate serves the file tools. Only `"agent"` exists — the
+     * resident in-distro agent (`lib/fs-substrate.js`): reads, writes and
+     * identities 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.
+     * The former `"share"` opt-out — the Windows-side host filesystem stack
+     * over the distro's 9p share — is retired: it was the one model-facing
+     * I/O path that still crossed the share, and the agent has no fallback
+     * that needs it. A profile carrying `"share"` is refused at construction
+     * with the migration (`shareSubstrateRefusal`). `watch()` rides the
+     * in-distro poll loop for the substrate regardless (`lib/watcher.js`) —
+     * it never ran through either substrate. The substrate never changes
      * `sandboxMode`'s honesty.
      */
     substrate: z.union(["share", "agent"]).default("agent"),
   });
 
   constructor(ctx, config) {
+    // The share substrate is refused before any peer work: a profile still
+    // carrying the retired value must fail loudly, with the migration, not
+    // silently serve the one I/O path this provider exists to close.
+    const refusal = shareSubstrateRefusal(config.substrate);
+    if (refusal !== null) throw new Error(refusal.message);
     super(ctx, config);
     this.resolvedDistro = config.distro;
     /** Cached distro-user home, the base for relative input when `cwd` is empty. */
     this.resolvedHome = undefined;
     /** The deployment default mode — the capability fact the tool layer reads. */
     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:
-    //
-    //   * it reads that descriptor with `GetFileSecurityW` and applies it to the
-    //     staged temp. A 9p share carries no Windows security descriptor, so the
-    //     call fails with `EIO (Win32 1)` and takes the whole write with it —
-    //     `edit` and every overwrite, not just an exotic path.
-    //   * it publishes with `ReplaceFileW`, which is not a 9p primitive.
-    //
-    // Both are replaced with their POSIX equivalents: the staged temp gets the
-    // target's real mode from inside the distro (see `copyModeInDistro` — the
-    // share ignores a host-side chmod), and publication is the plain atomic
-    // rename the share does support.
-    //
-    // Trade-off worth knowing: those two hooks are the only DACL handling in the
-    // inherited backend, so a *Windows* path served by this provider loses its
-    // descriptor preservation. This provider exists to serve distro paths, where
-    // no DACL can exist in the first place.
-    this.internals = {
-      ...this.internals,
-      copyFileDacl: async () => {},
-      replaceFile: (replaced, replacement) => this.publish(replaced, replacement),
-    };
   }
 
   /**
@@ -862,50 +833,6 @@ export class WslFileSystem extends LocalFileSystem {
     return this.config.sandbox ? this.defaultMode : undefined;
   }
 
-  /**
-   * Publish a staged temp file over its target the way a 9p share supports:
-   * give the temp the target's POSIX mode inside the distro, then rename it into
-   * place.
-   *
-   * The mode is applied before the rename on purpose. The share drops a mode set
-   * from the Windows side, but a rename preserves the inode's mode — so setting
-   * it on the staged temp is what makes the published file keep the bits it had,
-   * without a second in-distro call after publication and without the version
-   * the write returns going stale behind a late `chmod`.
-   *
-   * @param replaced - the existing file being replaced (a UNC path).
-   * @param replacement - the staged temp file holding the new content.
-   */
-  async publish(replaced, replacement) {
-    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
@@ -920,13 +847,11 @@ export class WslFileSystem extends LocalFileSystem {
   }
 
   /**
-   * 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.
+   * The agent-backed substrate, built on first use over the same resident
+   * agent every other distro side work shares.
+   * @returns {Promise<AgentSubstrate>} the substrate.
    */
   async agentSubstrate() {
-    if (this.config.substrate !== "agent") return undefined;
     if (this.agentSubstrateInstance === undefined) {
       this.agentSubstrateInstance = new AgentSubstrate({
         agent: await this.publicationAgent(),
@@ -1035,19 +960,13 @@ export class WslFileSystem extends LocalFileSystem {
    */
   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 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 (await this.agentSubstrate()).resolve(linux, opts?.signal);
+    } catch (error) {
+      throw this.peerError(error);
     }
-    const distro = await this.distro();
-    const target = await super.resolve(world, opts);
-    return { targetKey: target.targetKey, displayPath: toDisplayPath(target.targetKey, distro) };
   }
 
   /**
@@ -1084,185 +1003,78 @@ export class WslFileSystem extends LocalFileSystem {
     throw new FsError(denial.message, denial.code);
   }
 
-  /**
-   * The canonical replacement target for a Linux symlink this share cannot
-   * traverse, or undefined when the path is not one.
-   * @param target - the resolved target that failed a read-side operation.
-   * @param signal - optional cancellation.
-   * @returns the replacement target, or undefined.
-   */
-  async canonicalTarget(target, signal) {
-    if (!this.config.resolveSymlinks) return undefined;
-    const cached = this.canonicalTargets.get(target.targetKey);
-    if (cached !== undefined) return cached;
-    const parsed = uncToPosix(target.targetKey);
-    if (parsed === undefined) return undefined;
-    // 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);
-    return replacement;
-  }
-
-  /**
-   * Run one read-side operation, retrying once through the distro's canonical
-   * path when the share cannot follow a symlink. `displayPath` is preserved, so
-   * the model still sees the path it asked for while `targetKey` names the file
-   * the host can actually open.
-   *
-   * @param target - the resolved target.
-   * @param signal - optional cancellation.
-   * @param operation - the inherited operation to attempt.
-   * @returns the operation's result.
-   */
-  async withCanonicalRetry(target, signal, operation) {
-    let value;
+  async stat(target, signal) {
     try {
-      value = await operation(target);
+      return await (await this.agentSubstrate()).stat(target, signal);
     } catch (error) {
-      if (!(error instanceof FsError) || error.code !== "FS_NOT_FOUND") throw error;
-      const canonical = await this.canonicalTarget(target, signal);
-      if (canonical === undefined) throw error;
-      return operation(canonical);
-    }
-    // `stat` reports an absent file by RETURNING undefined rather than throwing,
-    // and an untraversable symlink takes exactly that path over this share. The
-    // model-facing read tool branches on precisely that undefined — it resolves,
-    // stats, and renders "not found" itself — so retrying only the throw is not
-    // enough: the silent miss has to be retried here too.
-    if (value === undefined) {
-      const canonical = await this.canonicalTarget(target, signal);
-      if (canonical !== undefined) return operation(canonical);
+      throw this.peerError(error);
     }
-    return value;
-  }
-
-  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.
+   * where a symlink is a first-class entry.
    * @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);
-      }
+    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 (await this.agentSubstrate()).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);
-      }
+    try {
+      return await (await this.agentSubstrate()).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);
-      }
+    try {
+      return await (await this.agentSubstrate()).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);
-      }
+    try {
+      return await (await this.agentSubstrate()).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);
-      }
+    try {
+      return await (await this.agentSubstrate()).readByteRange(target, range, signal);
+    } catch (error) {
+      throw this.peerError(error);
     }
-    return this.withCanonicalRetry(target, signal, (t) => super.readByteRange(t, range, signal));
   }
 
   /**
-   * List one level, rewriting each child's display path into the distro's
-   * coordinate system — the host backend reports children with UNC display paths,
-   * which would leak `\\wsl.localhost\...` into model-facing output.
-   *
+   * List one directory level. The substrate's rows already carry Linux display
+   * paths and canonical identities — nothing to rewrite.
    * @param target - the resolved directory.
    * @param signal - optional cancellation.
    * @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);
-      }
+    try {
+      return await (await this.agentSubstrate()).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) => ({
-      ...entry,
-      target: { targetKey: entry.target.targetKey, displayPath: toDisplayPath(entry.target.targetKey, distro) },
-    }));
   }
 
   /**
@@ -1283,6 +1095,10 @@ export class WslFileSystem extends LocalFileSystem {
    * they bump the parent directory's mtime. Replaces the previous flat
    * refusal (`FS_IO_ERROR`), which was the correct answer over 9p only.
    *
+   * A target that disappears mid-watch ends the loop with a report through
+   * `changed` — never the armed-but-never-fires silence a missing directory
+   * would otherwise produce. The scan's depth is `watchMaxDepth`.
+   *
    * @param target - the resolved file or directory to observe.
    * @param changed - the invalidation callback.
    * @param signal - cancels initialization; the caller closes an armed watcher.
@@ -1302,26 +1118,17 @@ export class WslFileSystem extends LocalFileSystem {
       onChange: changed,
       onError: (error) => changed(error),
       signal,
+      maxDepth: this.config.watchMaxDepth,
     });
   }
 
   /**
-   * Check the caller's mutation guard immediately before publication.
-   * @param target - the resolved target.
-   * @param expected - the write intent, or undefined for an unconditional write.
-   * @param signal - optional cancellation.
-   * @throws FsError with the same codes the host backend raises.
-   */
-  async assertGuard(target, expected, signal) {
-    if (expected === undefined) return;
-    const existing = await this.stat(target, signal);
-    const refusal = guardRefusal(expected, existing, target.displayPath);
-    if (refusal !== null) throw new FsError(refusal.message, refusal.code);
-  }
-
-  /**
-   * Fence the write by the per-call policy, then keep the guard's observable
-   * behaviour.
+   * Fence the write by the per-call policy, then publish through the
+   * substrate. The fence's fresh target is the one checked and written, so a
+   * refusal costs no I/O and cannot be raced by a swapped symlink; the guard
+   * rides the write op, where the agent re-verifies it one syscall before the
+   * rename and the confined resident enforces it in the kernel.
+   *
    * @param target - the resolved target.
    * @param content - the full new file content.
    * @param expected - the write intent.
@@ -1331,35 +1138,19 @@ 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, 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);
-      }
+    try {
+      return await (await this.agentSubstrate()).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
-    // past the guard, publication is the overridden `publish` (see the
-    // constructor), not the inherited Windows one.
-    return super.writeText(fenced, content, undefined, signal);
   }
 
   /**
-   * Fence the edit by the same policy, keeping the guard's observable behaviour.
+   * Fence the edit by the same policy, keeping the guard's observable
+   * behaviour.
+   *
    * @param target - the resolved target.
    * @param edit - the literal search/replace request.
    * @param expected - the version guard.
@@ -1371,15 +1162,10 @@ export class WslFileSystem extends LocalFileSystem {
   async editText(target, edit, expected, signal, 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);
-      }
+    try {
+      return await (await this.agentSubstrate()).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/listing.js

@@ -110,3 +110,50 @@ export function boundedInsert(window, candidate, keep) {
   window.pop();
   return true;
 }
+
+/**
+ * The distro-side argv one picker level is listed with.
+ *
+ * `-1` is one entry per line, `-A` keeps dot-entries but drops `.` and `..`,
+ * `-L` follows symlinks so a link to a directory reports as a directory and a
+ * broken link drops out (exactly what the per-entry `stat` the host path used
+ * to pay one 9p round trip for), and `-p` marks directories with the trailing
+ * `/` the parser keys on.
+ *
+ * @param linuxDir - the absolute Linux directory to list.
+ * @returns the argv for the agent or a `wsl.exe --exec` launch.
+ */
+export function lsListingArgv(linuxDir) {
+  return ["ls", "-1ALp", "--", linuxDir];
+}
+
+/**
+ * Parse one `ls -1ALp` listing into the picker's rows.
+ *
+ * A line is a row when it ends with `/` — a directory, or a symlink `-L`
+ * resolved to one; files and dangling links are skipped, matching the host
+ * path's behaviour. The parse reads the listing as UTF-8 lines, so a filename
+ * containing a newline would split into two rows — the same limitation class
+ * the one-shot transport has always had, accepted here with the 9p walk it
+ * replaces.
+ *
+ * @param stdout - the listing's raw stdout.
+ * @param parent - the listed directory, in the UNC form the rows carry.
+ * @param maxEntries - the row bound; a level with more is flagged truncated.
+ * @returns the first `maxEntries` rows and whether the level had more.
+ */
+export function parseLsListing(stdout, parent, maxEntries) {
+  const rows = [];
+  let truncated = false;
+  for (const line of String(stdout).split("\n")) {
+    if (!line.endsWith("/")) continue;
+    const name = line.slice(0, -1);
+    if (name.length === 0) continue;
+    if (rows.length === maxEntries) {
+      truncated = true;
+      break;
+    }
+    rows.push({ name, path: win32.join(parent, name), hidden: name.startsWith(".") });
+  }
+  return { rows, truncated };
+}