dsh-plugin-wsl-env 0.7.2 → 0.7.3

package/CHANGELOG.md

@@ -12,6 +12,59 @@ reference below points at that record's numbering.
 
 ## [Unreleased]
 
+## [0.7.3] - 2026-10-05
+
+One theme: the resident agent stops taking its world on faith - the
+handshake now verifies the deployment's content, the agent's lifetime
+survives a wedged host only by lease, and the one 9P consumer no row
+replacement could reach ships its seam-ready traversal.
+
+### Added
+
+- **The resident agent verifies its own deployment, and outlives a wedged
+  host only by lease.** The agent script is read in place from the
+  distro-visible path - in the deployed layout a `/mnt/c` mirror - so a
+  stale or half-synced runtime copy used to pass the version handshake
+  while drifting in behavior. The HELLO line now carries the sha256 of the
+  file the distro actually read (protocol v4), and both resident factories
+  pin the hash of the copy the package shipped: a mismatch is refused like
+  a version mismatch, with the resync command in the message. The agent
+  also terminates itself when its host goes silent without ever delivering
+  EOF - the wedged-relay case stdin EOF cannot cover: the host forwards a
+  client lease (`idleMs` + grace) through the managed `DSH_` namespace, and
+  an in-distro watchdog polls an in-flight marker so a long command's
+  silence never counts against it (dash has no `read -t`; a marker file is
+  the portable form). A boot sweep removes sibling `wsl-agent.*` temp dirs
+  no request has touched for an hour - the residue of agents whose host
+  died before their exit trap could run.
+- **The `@` completion's distro traversal is built and waiting for its seam.**
+  The one 9P consumer the takeover series could not reach - the GUI's `@`
+  file completion - funnels all workspace traversal through three
+  module-internal functions of the upstream `file-reference-local` service,
+  so no row replacement can reach them. The plugin now ships the consumer
+  side of RFC addendum ① (`lib/file-reference-wsl.js`): a traversal strategy
+  that lists a distro workspace through the resident agent with
+  `find -printf '%y\t%f'` - keeping readdir's Dirent fidelity, where
+  symlinks report neither kind and are skipped instead of resolved through
+  like `ls -L` would - replaces the upstream per-segment lstat walk with one
+  agent exec, and returns absolutes in the root's own coordinate system,
+  which the upstream scan joins children with. Deliberately not wired into
+  the composition: with the seam absent, reaching the funnels would mean
+  re-implementing the fuzzy ranking engine, the behavior-regression path
+  the RFC rules out. The module ships tested; the takeover lands the day
+  upstream takes the ~10-line parameter. The RFC addendum now carries the
+  concrete interface proposal.
+
+### Fixed
+
+- **The Windows CI legs are green again.** The fs boot test's end-to-end
+  legs read `platform is win32` as `the real-distro topology exists`, but
+  the CI Windows runners ship wsl.exe with no distro installed - every
+  Windows leg since the boot test landed failed there, which kept the
+  release gates red through 0.7.0-0.7.2 even after the missing-module
+  fix. The guard now asks WSL for its distro list and skips unless the
+  test's distro is actually installed.
+
 ## [0.7.2] - 2026-10-05
 
 One theme: the root-plane routing lands - and the composition that

package/agent/wsl-agent.sh

@@ -12,7 +12,11 @@
 # one thing a distro is guaranteed to have is a shell.
 #
 # Handshake — the first line the agent writes:
-#   HELLO|wsl-agent|<protocol version>
+#   HELLO|wsl-agent|<protocol version>|<sha256 of this script file>
+# The digest lets the host verify that the script it is about to rely on is
+# byte-identical to the copy it shipped. The script is read in place — a
+# /mnt/c mirror in the deployed layout — so a stale or half-synced runtime
+# copy would otherwise pass the version handshake while drifting in behavior.
 # Requests the agent accepts, one per line on stdin:
 #   PING                          -> PONG
 #   SHUTDOWN                      -> exits 0
@@ -57,11 +61,55 @@
 
 set -u
 
-PROTO_VERSION=3
+PROTO_VERSION=4
 TMPDIR_AGENT=$(mktemp -d "${TMPDIR:-/tmp}/wsl-agent.XXXXXX")
 OUT_FILE="$TMPDIR_AGENT/out"
 ERR_FILE="$TMPDIR_AGENT/err"
-trap 'rm -rf "$TMPDIR_AGENT"; [ -z "${CURRENT_STAGING:-}" ] || rm -rf -- "$CURRENT_STAGING"; exit 0' EXIT
+trap 'rm -rf "$TMPDIR_AGENT"; [ -z "${CURRENT_STAGING:-}" ] || rm -rf -- "$CURRENT_STAGING"; [ -z "${WATCHDOG_PID:-}" ] || kill "$WATCHDOG_PID" 2>/dev/null; exit 0' EXIT
+
+# The content identity of this script file, reported in the handshake: the
+# host hashes its own shipped copy and refuses an agent whose file differs.
+# cut with an explicit space: sha256sum separates hash and file with spaces,
+# and the default tab delimiter would leave the whole line in the field.
+AGENT_DIGEST=$(sha256sum -- "$0" 2>/dev/null | cut -d' ' -f1)
+
+# Bounded cleanup: temp dirs from agents whose host died without giving them
+# an EXIT (a `wsl --shutdown`, a force-killed wsl.exe). Own pattern only, and
+# only when nothing inside moved for an hour — a live agent's dir mtime moves
+# on every request (the inflight marker in run_capture is created and
+# removed), so a sibling being served right now is never touched. A confined
+# agent's /tmp is a private tmpfs: its own dir vanishes with it and it sees
+# no siblings, so the sweep is a no-op there.
+for stale in "${TMPDIR:-/tmp}"/wsl-agent.*; do
+  [ -d "$stale" ] || continue
+  [ "$stale" = "$TMPDIR_AGENT" ] && continue
+  [ -z "$(find "$stale" -maxdepth 1 -mmin -60 -print -quit 2>/dev/null)" ] && rm -rf -- "$stale" 2>/dev/null
+done
+
+# The client lease: when the host goes silent without closing the pipe (a
+# wedged relay, not a dead one — EOF exits the read loop), the agent
+# terminates itself after the lease window instead of lingering with its
+# temp dir. The window rides DSH_AGENT_LEASE_MS from the host's pinned
+# environment, set above the host's own idle shutdown, so the lease only
+# fires when the host is gone in every way that matters. A request in
+# flight pauses the lease (the inflight marker) — a long command with no
+# traffic is silence, not absence. Unset (an older host, a manual run)
+# disables the lease: the host keeps the lifetime it always had.
+LEASE_S=0
+case ${DSH_AGENT_LEASE_MS:-} in
+  ''|*[!0-9]*) ;;
+  *) if [ "$DSH_AGENT_LEASE_MS" -gt 0 ]; then
+       LEASE_S=$(( (DSH_AGENT_LEASE_MS + 999) / 1000 ))
+       (
+         while :; do
+           sleep "$LEASE_S" || exit 0
+           kill -0 "$$" 2>/dev/null || exit 0
+           [ -f "$TMPDIR_AGENT/inflight" ] || kill -s TERM "$$"
+         done
+       ) &
+       WATCHDOG_PID=$!
+     fi ;;
+esac
 
 # The request currently in flight, for KILL and for the exit trap.
 CURRENT_PID=
@@ -150,6 +198,10 @@ run_capture() {
   : >"$OUT_FILE"
   : >"$ERR_FILE"
   CURRENT_ID=$req_id
+  # The inflight marker pauses the lease watchdog for this request and
+  # refreshes the temp dir's mtime for the boot sweep; removing it after the
+  # answer re-arms both.
+  : >"$TMPDIR_AGENT/inflight"
   if [ "$mode" = subshell ]; then
     ( "$@" ) >"$OUT_FILE" 2>"$ERR_FILE" &
   elif [ -n "$SETSID" ]; then
@@ -192,6 +244,7 @@ run_capture() {
     printf 'RES|%s|%s|%s|%s|%s|%s\n' "$req_id" "$rc" \
       "$(b64enc_file "$OUT_FILE")" "$(b64enc_file "$ERR_FILE")" 0 0
   fi
+  rm -f "$TMPDIR_AGENT/inflight"
 }
 
 # --- filesystem substrate (FS frames) -------------------------------------
@@ -488,7 +541,7 @@ fs_dispatch() {
   esac
 }
 
-printf 'HELLO|wsl-agent|%s\n' "$PROTO_VERSION"
+printf 'HELLO|wsl-agent|%s|%s\n' "$PROTO_VERSION" "$AGENT_DIGEST"
 
 while IFS= read -r line; do
   case $line in

package/lib/agent-confined.js

@@ -27,12 +27,11 @@
  *
  * @module dsh-plugin-wsl/agent-confined
  */
-import { fileURLToPath } from "node:url";
 import { bwrapArgvPrefix } from "./bwrap.js";
 import { toLinuxPath } from "./paths.js";
+import { agentScriptDigest, agentScriptPath } from "./agent-shared.js";
 import { WslAgent } from "./agent.js";
 
-const AGENT_SCRIPT_PATH = fileURLToPath(new URL("../agent/wsl-agent.sh", import.meta.url));
 const confinedAgents = new Map();
 
 /**
@@ -63,7 +62,8 @@ export function confinedAgent({ distro, wslPath = "wsl.exe", policy, maskWindows
     agent = new WslAgent({
       distro,
       wslPath,
-      scriptPath: toLinuxPath(AGENT_SCRIPT_PATH),
+      scriptPath: toLinuxPath(agentScriptPath),
+      expectedDigest: agentScriptDigest,
       // The prefix is a whole command from the distro's point of view — program,
       // profile, `--` — because the transport inserts it between
       // `wsl.exe --exec` and the `sh <script>` pair (`lib/agent.js`'s

package/lib/agent-protocol.js

@@ -11,7 +11,7 @@
  */
 
 /** The protocol version this host side speaks; the agent must match. */
-export const PROTOCOL_VERSION = 3;
+export const PROTOCOL_VERSION = 4;
 
 /**
  * Upper bound on one `read` op's payload, set by the HOST looping over windowed
@@ -133,7 +133,9 @@ export function encodeFsFrame({ id, op, args, timeoutMs = 0 }) {
  * Parse one line of the agent's stdout.
  * @param {string} line - a line without its terminator.
  * @returns {object} one of:
- *   - `{ type: "hello", name, version }`
+ *   - `{ type: "hello", name, version, digest }` — `digest` is the sha256 of
+ *     the script file the agent is executing (empty when it could not hash
+ *     it); the host compares it against its own shipped copy
  *   - `{ type: "pong" }`
  *   - `{ type: "ack", id }` — the agent dequeued the request for execution;
  *     the host arms its stuck-request watchdog here, so queue time never
@@ -148,8 +150,8 @@ export function encodeFsFrame({ id, op, args, timeoutMs = 0 }) {
  */
 export function parseAgentLine(line) {
   if (line.startsWith("HELLO|")) {
-    const [, name, version] = line.split("|");
-    return { type: "hello", name, version: Number(version) };
+    const [, name, version, digest] = line.split("|");
+    return { type: "hello", name, version: Number(version), digest: digest ?? "" };
   }
   if (line === "PONG") return { type: "pong" };
   if (line.startsWith("ACK|")) return { type: "ack", id: line.slice(4) };

package/lib/agent-shared.js

@@ -10,13 +10,26 @@
  * @module dsh-plugin-wsl/agent-shared
  */
 
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { toLinuxPath } from "./paths.js";
 import { WslAgent } from "./agent.js";
 
 const AGENT_SCRIPT_PATH = fileURLToPath(new URL("../agent/wsl-agent.sh", import.meta.url));
+// The script the distro reads must be byte-identical to the copy this
+// package shipped: the deployed layout reads it from the /mnt/c mirror, and
+// the handshake digest is what catches a stale or half-synced runtime copy.
+// Both resident factories (plain and confined) pin it.
+const AGENT_SCRIPT_DIGEST = createHash("sha256").update(readFileSync(AGENT_SCRIPT_PATH)).digest("hex");
 const sharedAgents = new Map();
 
+/** The agent script as a host-side path, for factories that need both spellings. */
+export const agentScriptPath = AGENT_SCRIPT_PATH;
+
+/** The sha256 of the shipped agent script; every resident verifies its HELLO against it. */
+export const agentScriptDigest = AGENT_SCRIPT_DIGEST;
+
 /**
  * The shared agent for one distro, created on first use.
  * @param distro - the distro name.
@@ -25,7 +38,7 @@ const sharedAgents = new Map();
 export function sharedAgent(distro) {
   let agent = sharedAgents.get(distro);
   if (agent === undefined) {
-    agent = new WslAgent({ distro, scriptPath: toLinuxPath(AGENT_SCRIPT_PATH) });
+    agent = new WslAgent({ distro, scriptPath: toLinuxPath(AGENT_SCRIPT_PATH), expectedDigest: AGENT_SCRIPT_DIGEST });
     sharedAgents.set(distro, agent);
   }
   return agent;

package/lib/agent.js

@@ -44,6 +44,11 @@ const HANDSHAKE_TIMEOUT_MS = 15000;
 /** Extra time the host watchdog waits past the request's own in-distro timeout. */
 const WATCHDOG_GRACE_MS = 13000;
 
+/** How far past its host's idle shutdown the agent's own lease runs. The
+ * lease fires only when the host is gone in every way that matters (a wedged
+ * relay that never delivers EOF); the host's close() normally wins the race. */
+const LEASE_GRACE_MS = 120000;
+
 /** The Windows essentials `wsl.exe` itself needs to start and report cleanly. */
 const WINDOWS_ESSENTIALS = /^(systemroot|systemdrive|windir|path|pathext|comspec|os|computername)$/i;
 
@@ -95,11 +100,34 @@ export function pinnedWindowsEnv(parent) {
  * @param {string} options.scriptPath - the agent script as a Linux path inside
  *   the distro (a `/mnt/<drive>/...` translation of the package's
  *   `agent/wsl-agent.sh`).
+ * @param {number} [options.leaseMs] - the agent's own client lease, forwarded
+ *   through the managed `DSH_` namespace so the script can self-terminate
+ *   when a wedged relay stops carrying traffic without ever delivering EOF.
  * @returns {import("node:child_process").ChildProcess} the spawned process.
  */
-function spawnDefault({ wslPath, distro, scriptPath, argvPrefix = [] }) {
+/**
+ * The spawn environment for one resident, with the client lease folded in.
+ * The pinned environment forwards only the managed `DSH_` namespace, and it
+ * forwards exactly the names the parent `WSLENV` lists — so the lease rides
+ * both: the value on the variable, the name on `WSLENV`. A non-positive
+ * lease leaves the environment as the pin built it (the script treats an
+ * unset variable as no lease).
+ * @param {Record<string, string>} env - the pinned environment.
+ * @param {number} leaseMs - the agent's client lease in ms; 0 disables.
+ * @returns {Record<string, string>} the environment to spawn with.
+ */
+export function agentLeaseEnv(env, leaseMs) {
+  if (!(leaseMs > 0)) return env;
+  return {
+    ...env,
+    DSH_AGENT_LEASE_MS: String(leaseMs),
+    WSLENV: [env.WSLENV, "DSH_AGENT_LEASE_MS"].filter(Boolean).join(":"),
+  };
+}
+
+function spawnDefault({ wslPath, distro, scriptPath, argvPrefix = [], leaseMs = 0 }) {
   return spawn(wslPath, ["-d", distro, "--exec", ...argvPrefix, "sh", scriptPath], {
-    env: pinnedWindowsEnv(process.env),
+    env: agentLeaseEnv(pinnedWindowsEnv(process.env), leaseMs),
     stdio: ["pipe", "pipe", "pipe"],
     windowsHide: true,
   });
@@ -114,9 +142,13 @@ export class WslAgent {
    * @param {string} config.distro - the distro this agent serves.
    * @param {string} config.scriptPath - the agent script as a Linux path
    *   inside the distro (see {@link spawnDefault}).
-   * @param {string} [config.wslPath] - the `wsl.exe` path.
-   * @param {number} [config.idleMs] - idle shutdown delay; 0 disables.
-   * @param {string[]} [config.argvPrefix] - arguments inserted between
+ * @param {string} [config.wslPath] - the `wsl.exe` path.
+ * @param {number} [config.idleMs] - idle shutdown delay; 0 disables.
+ * @param {string} [config.expectedDigest] - the sha256 of the agent script
+ *   as this package shipped it; a HELLO whose digest differs is refused the
+ *   same way a version mismatch is (the script is read in place, so a stale
+ *   or half-synced runtime copy is the failure this catches).
+ * @param {string[]} [config.argvPrefix] - arguments inserted between
    *   `wsl.exe --exec` and the `sh script` pair — the confinement wrapper
    *   (`bwrap … --`) a confined agent runs its whole lifetime under, so every
    *   filesystem op it performs is kernel-enforced. Empty for the plain agent.
@@ -129,6 +161,7 @@ export class WslAgent {
     this.wslPath = config.wslPath ?? "wsl.exe";
     this.argvPrefix = config.argvPrefix ?? [];
     this.idleMs = config.idleMs ?? 600000;
+    this.expectedDigest = config.expectedDigest;
     /** Hard ceiling on one stdout protocol line; a longer line is a broken or
      * hostile agent, not data to hold — readline used to accumulate it all. */
     this.frameCapBytes = config.frameCapBytes ?? MAX_FRAME_BYTES;
@@ -179,6 +212,7 @@ export class WslAgent {
         distro: this.distro,
         scriptPath: this.scriptPath,
         argvPrefix: this.argvPrefix,
+        leaseMs: this.idleMs > 0 ? this.idleMs + LEASE_GRACE_MS : 0,
       }));
       const handshakeTimer = setTimeout(() => {
         this.lastError = `agent handshake timed out after ${HANDSHAKE_TIMEOUT_MS}ms`;
@@ -252,9 +286,22 @@ export class WslAgent {
     switch (message.type) {
       case "hello": {
         if (message.name !== AGENT_NAME || message.version !== PROTOCOL_VERSION) {
+          // Settle BEFORE killing: the exit event must not overwrite the real
+          // reason with the generic handshake message (the fake transports
+          // emit exit synchronously inside kill(); a real wsl.exe races it).
           this.lastError = `agent handshake mismatch: got ${message.name}@${message.version}, want ${AGENT_NAME}@${PROTOCOL_VERSION}`;
+          settleStart(new Error(this.lastError));
           this.process?.kill();
+          return;
+        }
+        if (this.expectedDigest !== undefined && message.digest !== this.expectedDigest) {
+          // The script is read in place from the distro-visible path — in the
+          // deployed layout a /mnt/c mirror — so a digest that differs from
+          // the copy this package shipped means the runtime copy is stale,
+          // half-synced, or edited. Fail closed with the fix in the message.
+          this.lastError = `agent script digest mismatch: the file the distro read at ${this.scriptPath} hashes to ${message.digest || "(nothing)"}, but this package shipped ${this.expectedDigest} — resync the runtime copy (npm run sync:windows) or reinstall the plugin`;
           settleStart(new Error(this.lastError));
+          this.process?.kill();
           return;
         }
         clearTimeout(handshakeTimer);

package/lib/file-reference-wsl.js

@@ -0,0 +1,284 @@
+/**
+ * The distro-side traversal strategy for `@` completion — the plugin's
+ * ready answer to RFC addendum ① (docs/upstream/rfc-wsl-workspaces.md).
+ *
+ * ## The seam this consumes
+ *
+ * `@deepseek-ai/dsh-file-reference-local` funnels every workspace traversal
+ * through three module-internal functions: `readWorkspaceRoot` and
+ * `readDirectory` (both `node:fs/promises` readdir with `withFileTypes`) and
+ * `resolveDisplayDirectory` (a lexical resolve plus a per-segment `lstat`
+ * walk that refuses symlink and non-directory components). Everything else —
+ * the fuzzy ranking, the bounded index, the generation/invalidation dance,
+ * the excluded-directory list — is pure logic over the entries those three
+ * return. Addendum ① proposes exposing the three as an injectable strategy
+ * with the current implementations as defaults; this module is the consumer
+ * side, built and tested against that interface so the takeover lands the
+ * day the seam does.
+ *
+ * It is deliberately NOT wired into cordis.patch.yml yet: with the seam
+ * absent, reaching the funnels would mean subclassing past module-internal
+ * functions or re-implementing the ranking engine — the behavior-regression
+ * path the RFC rules out. The module ships, tested, until upstream speaks.
+ *
+ * ## Semantics, held faithful where the seam allows
+ *
+ * - Entries keep upstream's Dirent shape: `{name, isDirectory(), isFile()}`.
+ *   The distro listing uses `find -printf '%y\t%f'` rather than `ls -1ALp`
+ *   precisely for this: `%y` reports `l` for symlinks, which the parse skips
+ *   the way a readdir Dirent is neither file nor directory. `ls -1ALp` would
+ *   resolve links through and change which candidates exist.
+ * - `resolveDisplayDirectory` refuses a symlink or non-directory component
+ *   with one agent exec that walks the (lexically normalized) segments —
+ *   the same verdict upstream reaches with N sequential lstats, and unlike
+ *   `realpath`, refusing is the point, not resolving.
+ * - A directory the traversal cannot read yields `[]` (upstream's readdir
+ *   catch); an aborted caller propagates the abort instead.
+ * - The returned absolutes stay in the root's own coordinate system (UNC for
+ *   a distro workspace), because upstream joins children with the host
+ *   `node:path` — a POSIX path from this layer would be mangled by it.
+ *
+ * @module dsh-plugin-wsl/file-reference-wsl
+ */
+
+import { isWslUnc, posixToUnc, uncToPosix } from "./paths.js";
+
+/** Upstream's default cap on one workspace index; the per-directory listing
+ * rides the same bound, since one level can't usefully exceed the budget. */
+const DEFAULT_MAX_ENTRIES = 50000;
+
+/**
+ * Lexically normalize a `/`-separated display directory against its root.
+ * Upstream resolves `resolve(root, displayDirectory)` and refuses a result
+ * outside the root, so `a/../b` lands on `b` while `..` past the root is
+ * refused outright — the walk below never sees a `..` segment.
+ *
+ * @param {string} displayDirectory - the query text before the fragment, possibly "".
+ * @returns {string[] | undefined} the normalized segments, or undefined when
+ *   the display directory escapes the root.
+ */
+export function normalizeDisplaySegments(displayDirectory) {
+  const segments = [];
+  for (const segment of String(displayDirectory).split("/")) {
+    if (segment === "" || segment === ".") continue;
+    if (segment === "..") {
+      if (segments.length === 0) return undefined;
+      segments.pop();
+      continue;
+    }
+    segments.push(segment);
+  }
+  return segments;
+}
+
+/**
+ * The distro argv for one directory listing: `find -printf '%y\t%f'` over the
+ * contained directory. The containment guard is the same shape the picker and
+ * workspace-files use — `realpath` the requested directory, refuse anything
+ * the root does not contain — and the `%y` type char is what keeps symlink
+ * semantics identical to a readdir Dirent (skipped, not followed).
+ *
+ * @param {string} linuxRoot - the workspace root, POSIX spelling.
+ * @param {string} linuxDir - the directory to list, POSIX spelling.
+ * @param {number} maxEntries - the listing cap (head -n bound).
+ * @returns {string[]} the agent exec argv.
+ */
+export function traversalArgv(linuxRoot, linuxDir, maxEntries) {
+  const script = [
+    "root=$1 dir=$2 max=$3",
+    'real=$(realpath -L -- "$dir") || exit 2',
+    'case "$real" in "$root") ;; "$root"/*) ;; *) echo "OUTSIDE:$real" >&2; exit 3;; esac',
+    '[ -d "$real" ] || { echo "NOTDIR:$real" >&2; exit 4; }',
+    'find "$real" -mindepth 1 -maxdepth 1 -printf \'%y\\t%f\\n\' | head -n "$max"',
+  ].join("\n");
+  return ["sh", "-c", script, "sh", linuxRoot, linuxDir, maxEntries];
+}
+
+/**
+ * Parse one `%y\t%f` listing into upstream's Dirent-like entries.
+ * `d` is a directory and `f` a file; every other type char — `l` for
+ * symlinks, devices, sockets — is skipped, matching a readdir Dirent.
+ *
+ * @param {string} stdout - the raw listing.
+ * @returns {{name: string, isDirectory: () => boolean, isFile: () => boolean}[]}
+ */
+export function parseTraversalListing(stdout) {
+  const entries = [];
+  for (const line of String(stdout).split("\n")) {
+    const tab = line.indexOf("\t");
+    if (tab <= 0) continue;
+    const kind = line.slice(0, tab);
+    const name = line.slice(tab + 1);
+    if (name.length === 0) continue;
+    if (kind !== "d" && kind !== "f") continue;
+    entries.push({
+      name,
+      isDirectory: () => kind === "d",
+      isFile: () => kind === "f",
+    });
+  }
+  return entries;
+}
+
+/**
+ * The argv for the per-segment walk behind `resolveDisplayDirectory`: each
+ * segment must exist, be a directory, and not be a symlink — upstream's
+ * lstat verdicts, checked in one exec. Segments ride as argv elements, never
+ * interpolated into the script.
+ *
+ * @param {string} linuxRoot - the workspace root, POSIX spelling.
+ * @param {string[]} segments - the normalized display segments below the root.
+ * @returns {string[]} the agent exec argv.
+ */
+export function resolveDirectoryArgv(linuxRoot, segments) {
+  const script = [
+    "root=$1",
+    'cur="$root"',
+    'for seg in "${@:2}"; do',
+    '  cur="$cur/$seg"',
+    '  if [ -L "$cur" ]; then echo "SYMLINK:$cur" >&2; exit 5; fi',
+    '  [ -d "$cur" ] || { echo "NOTDIR:$cur" >&2; exit 4; }',
+    "done",
+    'printf \'%s\\n\' "$cur"',
+  ].join("\n");
+  return ["sh", "-c", script, "sh", linuxRoot, ...segments];
+}
+
+/**
+ * The host-default traversal — the node:fs implementations the seam keeps
+ * as upstream's defaults, replicated here so the prototype answers host
+ * workspaces without the seam and so tests can inject substitutes for it.
+ * (Upstream owns the real defaults; this copy exists only until the takeover.)
+ *
+ * @param {object} deps - the node:fs/promises functions, injectable for tests.
+ * @returns the strategy object with the upstream default semantics.
+ */
+export function hostFileReferenceTraversal(deps) {
+  const read = async (absolute, signal) => {
+    signal.throwIfAborted();
+    try {
+      const entries = await deps.readdir(absolute, { withFileTypes: true });
+      signal.throwIfAborted();
+      return entries;
+    } catch (error) {
+      signal.throwIfAborted();
+      throw error;
+    }
+  };
+  return {
+    readWorkspaceRoot: read,
+    readDirectory: async (absolute, signal) => {
+      signal.throwIfAborted();
+      try {
+        const entries = await deps.readdir(absolute, { withFileTypes: true });
+        signal.throwIfAborted();
+        return entries;
+      } catch {
+        signal.throwIfAborted();
+        return [];
+      }
+    },
+    resolveDisplayDirectory: async (root, displayDirectory, signal) => {
+      const segments = normalizeDisplaySegments(displayDirectory);
+      if (segments === undefined) return undefined;
+      let current = root;
+      for (const segment of segments) {
+        signal.throwIfAborted();
+        current = `${current}${current.endsWith("/") ? "" : "/"}${segment}`;
+        try {
+          const status = await deps.lstat(current);
+          signal.throwIfAborted();
+          if (status.isSymbolicLink() || !status.isDirectory()) return undefined;
+        } catch (error) {
+          signal.throwIfAborted();
+          return undefined;
+        }
+      }
+      return current;
+    },
+  };
+}
+
+/**
+ * The distro-routed traversal strategy. Each method routes by coordinate:
+ * a `\\wsl.localhost\<distro>` UNC rides the resident agent (the search
+ * root and every absolute upstream passes stay in the UNC form it joined
+ * them with); anything else defers to the default traversal. The search
+ * root doubles as the containment root for the distro listings' guard, so
+ * the seam wires one strategy per `WorkspaceFileSearch` — exactly where
+ * `WorkspaceFileSearch(root, config, traversal)` would take it.
+ *
+ * @param {object} options
+ * @param {string} options.root - the search root, the UNC form upstream passes.
+ * @param {(distro: string) => object} options.runnerFor - the agent runner
+ *   for one distro; tests substitute a fake (a real wiring passes sharedAgent).
+ * @param {object} options.defaultTraversal - the host-default strategy.
+ * @param {number} [options.maxEntries] - the listing cap, upstream's index budget.
+ * @returns the strategy object the seam's `WorkspaceFileSearch` would take.
+ */
+export function wslFileReferenceTraversal({ root, runnerFor, defaultTraversal, maxEntries = DEFAULT_MAX_ENTRIES }) {
+  if (!isWslUnc(root)) return defaultTraversal;
+  const rootCoords = uncToPosix(root);
+  const rootLinux = rootCoords.linuxPath;
+
+  const listDistro = async (absolute, signal, onRefusal) => {
+    signal.throwIfAborted();
+    const { linuxPath } = uncToPosix(absolute);
+    try {
+      const result = await runnerFor(rootCoords.distro).exec({
+        cwd: "/",
+        argv: traversalArgv(rootLinux, linuxPath, maxEntries),
+        maxOutputBytes: 4_000_000,
+        timeoutMs: 30_000,
+        signal,
+      });
+      signal.throwIfAborted();
+      if (result.exitCode !== 0) {
+        return onRefusal(new Error(`listing "${linuxPath}" failed: ${String(result.stderr).trim() || `exit ${result.exitCode}`}`));
+      }
+      return parseTraversalListing(result.stdout);
+    } catch (error) {
+      signal.throwIfAborted();
+      return onRefusal(error);
+    }
+  };
+
+  return {
+    readWorkspaceRoot(absolute, signal) {
+      if (!isWslUnc(absolute)) return defaultTraversal.readWorkspaceRoot(absolute, signal);
+      return listDistro(absolute, signal, (error) => {
+        throw error;
+      });
+    },
+
+    readDirectory(absolute, signal) {
+      if (!isWslUnc(absolute)) return defaultTraversal.readDirectory(absolute, signal);
+      return listDistro(absolute, signal, () => []);
+    },
+
+    async resolveDisplayDirectory(rootOf, displayDirectory, signal) {
+      signal.throwIfAborted();
+      if (!isWslUnc(rootOf)) return defaultTraversal.resolveDisplayDirectory(rootOf, displayDirectory, signal);
+      const segments = normalizeDisplaySegments(displayDirectory);
+      if (segments === undefined) return undefined;
+      if (segments.length === 0) return root;
+      try {
+        const result = await runnerFor(rootCoords.distro).exec({
+          cwd: "/",
+          argv: resolveDirectoryArgv(rootLinux, segments),
+          maxOutputBytes: 4_000_000,
+          timeoutMs: 30_000,
+          signal,
+        });
+        signal.throwIfAborted();
+        if (result.exitCode !== 0) return undefined;
+        return posixToUnc(rootCoords.distro, result.stdout.trim());
+      } catch {
+        signal.throwIfAborted();
+        return undefined;
+      }
+    },
+  };
+}
+
+export default wslFileReferenceTraversal;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-plugin-wsl-env",
-  "version": "0.7.2",
+  "version": "0.7.3",
   "description": "让 DeepSeek Harness 以 WSL 子系统作为会话的执行环境：shell、文件读写与命令执行均在子系统内完成，目录选择器与 GUI 终端同样定位到子系统路径，并通过子系统内的 bubblewrap 对命令进行沙箱隔离",
   "keywords": [
     "deepseek-harness",
@@ -14,28 +14,29 @@
   "main": "lib/shell.js",
   "exports": {
     ".": "./lib/shell.js",
-    "./shell": "./lib/shell.js",
+    "./agent": "./lib/agent.js",
+    "./auto-preset": "./lib/auto-preset.js",
+    "./auto-preset/locale/en.json": "./locale/auto-preset/en.json",
+    "./auto-preset/locale/zh.json": "./locale/auto-preset/zh.json",
+    "./file-reference-wsl": "./lib/file-reference-wsl.js",
     "./fs": "./lib/fs.js",
-    "./subprocess": "./lib/subprocess.js",
-    "./picker": "./lib/picker.js",
-    "./workspace-files-wsl": "./lib/workspace-files-wsl.js",
     "./fs-routing": "./lib/fs-routing.js",
-    "./auto-preset": "./lib/auto-preset.js",
-    "./shell-env": "./lib/shell-env.js",
-    "./wsl": "./lib/wsl.js",
-    "./paths": "./lib/paths.js",
-    "./agent": "./lib/agent.js",
-    "./package.json": "./package.json",
     "./locale/en.json": "./locale/en.json",
     "./locale/zh.json": "./locale/zh.json",
-    "./subprocess/locale/en.json": "./locale/subprocess/en.json",
-    "./subprocess/locale/zh.json": "./locale/subprocess/zh.json",
+    "./package.json": "./package.json",
+    "./paths": "./lib/paths.js",
+    "./picker": "./lib/picker.js",
     "./picker/locale/en.json": "./locale/picker/en.json",
     "./picker/locale/zh.json": "./locale/picker/zh.json",
+    "./shell": "./lib/shell.js",
+    "./shell-env": "./lib/shell-env.js",
     "./shell-env/locale/en.json": "./locale/shell-env/en.json",
     "./shell-env/locale/zh.json": "./locale/shell-env/zh.json",
-    "./auto-preset/locale/en.json": "./locale/auto-preset/en.json",
-    "./auto-preset/locale/zh.json": "./locale/auto-preset/zh.json"
+    "./subprocess": "./lib/subprocess.js",
+    "./subprocess/locale/en.json": "./locale/subprocess/en.json",
+    "./subprocess/locale/zh.json": "./locale/subprocess/zh.json",
+    "./workspace-files-wsl": "./lib/workspace-files-wsl.js",
+    "./wsl": "./lib/wsl.js"
   },
   "dsh": {
     "bundle": {
@@ -65,9 +66,9 @@
   ],
   "scripts": {
     "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/agent-exec.test.mjs test/agent-fs-script.test.mjs test/agent-protocol.test.mjs test/agent.test.mjs test/fs-substrate.test.mjs test/fs.boot.test.mjs test/workspace-files-wsl.test.mjs test/composition.test.mjs test/fsio-agent.test.mjs test/fsio-text.test.mjs test/git-route.test.mjs test/listing.test.mjs test/paths.test.mjs test/ports.test.mjs test/preset-choice.test.mjs test/probe-cache.test.mjs test/sandbox.test.mjs test/search-exec.test.mjs test/search-route.test.mjs test/fs.boot.test.mjs test/shell.test.mjs test/terminal-activity.test.mjs test/terminal.test.mjs test/watcher.test.mjs test/wsl.test.mjs test/fs-decisions.test.mjs",
+    "test:coverage": "node --test --experimental-test-coverage --test-coverage-lines=85 --test-coverage-branches=85 --test-coverage-functions=70 test/agent-exec.test.mjs test/agent-fs-script.test.mjs test/agent-protocol.test.mjs test/agent.test.mjs test/fs-substrate.test.mjs test/fs.boot.test.mjs test/workspace-files-wsl.test.mjs test/composition.test.mjs test/file-reference-wsl.test.mjs test/fsio-agent.test.mjs test/fsio-text.test.mjs test/git-route.test.mjs test/listing.test.mjs test/paths.test.mjs test/ports.test.mjs test/preset-choice.test.mjs test/probe-cache.test.mjs test/sandbox.test.mjs test/search-exec.test.mjs test/search-route.test.mjs test/fs.boot.test.mjs test/shell.test.mjs test/terminal-activity.test.mjs test/terminal.test.mjs test/watcher.test.mjs test/wsl.test.mjs test/fs-decisions.test.mjs",
     "test:syntax": "node test/syntax.mjs",
-    "test:unit": "node --test test/fs.boot.test.mjs test/fsio-text.test.mjs test/workspace-files-wsl.test.mjs test/composition.test.mjs 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/agent-fs-script.test.mjs test/fsio-agent.test.mjs test/fs-substrate.test.mjs test/agent-exec.test.mjs test/ports.test.mjs test/watcher.test.mjs test/wsl.test.mjs test/fs-decisions.test.mjs test/git-route.test.mjs test/fsio-text.test.mjs test/search-route.test.mjs test/search-exec.test.mjs test/terminal-activity.test.mjs",
+    "test:unit": "node --test test/fs.boot.test.mjs test/fsio-text.test.mjs test/workspace-files-wsl.test.mjs test/composition.test.mjs test/file-reference-wsl.test.mjs 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/agent-fs-script.test.mjs test/fsio-agent.test.mjs test/fs-substrate.test.mjs test/agent-exec.test.mjs test/ports.test.mjs test/watcher.test.mjs test/wsl.test.mjs test/fs-decisions.test.mjs test/git-route.test.mjs test/fsio-text.test.mjs test/search-route.test.mjs test/search-exec.test.mjs test/terminal-activity.test.mjs",
     "lint:style": "node test/style.mjs",
     "prepublishOnly": "npm test",
     "probe": "bash test/probe/run.sh",