dsh-plugin-wsl-env 0.7.2 → 0.7.4

package/CHANGELOG.md

@@ -12,6 +12,93 @@ reference below points at that record's numbering.
 
 ## [Unreleased]
 
+## [0.7.4] - 2026-10-05
+
+One theme: the 0.2.0 review's engineering debt closes out - the five
+open groups land with tests, the bootstrap remedy ships with the
+package, and the real-distro probes re-run green on the protocol v4
+stack.
+
+### Fixed
+
+- **The bootstrap remedy is shipped with the package.** The refused-write
+  and sandbox messages point at `scripts/bootstrap.sh <distro> --install`,
+  which the `files` list never packaged - on an npm install the advice was
+  a dead end. The script rides in the tarball now (the other two files in
+  `scripts/` are CI-only and stay unpackaged). The real-distro probes were
+  re-run against the protocol v4 stack: agent 11/11, substrate 8/8, exec
+  5/5, watch 6/6.
+
+- **The review's remaining engineering items close out.** A `SETENV` key
+  that is not a POSIX identifier is refused with a protocol error instead
+  of exporting silently into every later request; an EXEC frame whose argv
+  payload fails to decode refuses the request instead of running the
+  command with a silent empty word where the host sent text, and a frame
+  that ends before its declared argument count exits instead of running
+  the op on a partial list; a non-numeric exit code reads as the sentinel
+  `-1` (a value no `wait` can produce) instead of `NaN`; an unknown FS op
+  maps to `FS_IO_ERROR` - naming the contract breach - instead of posing
+  as `FS_NOT_FOUND`; `editText` on a file that never existed reads as
+  `FS_NOT_FOUND` (the read path's dialect) while an edit that *lost* its
+  file after a read stays `FS_STALE_VERSION`; a symlinked directory as a
+  list target answers with the target's children (`find` used to skip its
+  starting point and answer empty, exit 0); and the Linux-filename
+  backslash identity limit is documented in LIMITATIONS instead of
+  waiting as an undocumented wrong answer.
+
+## [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,12 +12,18 @@
 # 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
 #   KILL|<id>                     -> SIGTERM the in-flight request with that id
-#   SETENV|<key>|<b64 value>      -> export the variable for later requests
+#   SETENV|<key>|<b64 value>      -> export the variable for later requests;
+#                                    <key> must be a POSIX identifier, else
+#                                    ERR|protocol
 #   EXEC|<id>|<b64 cwd>|<timeout seconds|0>|<n args>|<output cap bytes|0>
 #       followed by <n args> lines of base64, one argv word each
 #       -> ACK|<id> the moment the request is dequeued for execution — the host
@@ -57,11 +63,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=
@@ -76,6 +126,16 @@ b64dec() {
   printf '%s' "$1" | base64 -d 2>/dev/null || printf '%s' "$1" | base64 --decode 2>/dev/null || :
 }
 
+# Strict decode for payloads whose emptiness would LIE: an argv word that
+# fails to decode must refuse the request, not run the command with a silent
+# empty word where the host sent text (an empty payload is legitimate and
+# decodes fine — only malformed base64 lands here). Sets DEC on success.
+b64dec_strict() {
+  DEC=$(printf '%s' "$1" | base64 -d 2>/dev/null) && return 0
+  DEC=$(printf '%s' "$1" | base64 --decode 2>/dev/null) && return 0
+  return 1
+}
+
 b64enc_file() {
   # `tr` strips the 76-column wraps GNU and BusyBox base64 both emit; the
   # protocol is one line per payload, so a wrapped encode would tear a large
@@ -150,6 +210,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 +256,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) -------------------------------------
@@ -254,6 +319,15 @@ fs_list() {
   # records (records split on NUL, names taken after the 6th TAB).
   local d err
   d=$(b64dec "$1")
+  # The LIST TARGET follows symlinks, like every read path: `find` does not
+  # traverse its starting point, so a symlink-to-directory used to list EMPTY
+  # with exit 0 - a silent wrong answer where the peer's readdir answers with
+  # the target's children. Resolve first, then enumerate; the entries keep
+  # their own (lstat) types.
+  d=$(realpath -L -- "$d" 2>"$ERR_FILE") || {
+    err=$(cat "$ERR_FILE")
+    fs_fail "$(fs_classify "$err")" "$err"
+  }
   find "$d" -mindepth 1 -maxdepth 1 -printf '%y\t%s\t%D\t%i\t%T@\t%C@\t%p\0' 2>"$ERR_FILE" || {
     err=$(cat "$ERR_FILE")
     fs_fail "$(fs_classify "$err")" "$err"
@@ -484,11 +558,13 @@ fs_dispatch() {
     realpath) fs_realpath "$1" ;;
     read)     fs_read "$1" "$2" "$3" ;;
     write)    fs_write "$1" "$2" "$3" "$4" "$5" ;;
-    *)        fs_fail notfound "unknown fs op" ;;
+    # A host/agent contract breach is an I/O-class failure, not a file that
+    # was not found: the mapped reason reads FS_IO_ERROR host-side.
+    *)        fs_fail protocol "unknown fs op" ;;
   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
@@ -508,6 +584,15 @@ while IFS= read -r line; do
       rest=${line#SETENV|}
       key=${rest%%|*}
       b64=${rest#*|}
+      # The key exports into EVERY later request's environment, so it must be
+      # a POSIX identifier: anything else would be a silent no-op for the
+      # command (or a name collision with a shell special). Refused loudly.
+      case $key in
+        ""|[0-9]*|*[!A-Za-z0-9_]*)
+          printf 'ERR||protocol|%s\n' "$(printf '%s' "SETENV key is not a POSIX identifier" | base64 | tr -d '\n')"
+          continue
+          ;;
+      esac
       # Command substitution strips trailing newlines from the decoded value;
       # acceptable for environment values, documented in the protocol.
       decoded=$(b64dec "$b64")
@@ -528,15 +613,29 @@ while IFS= read -r line; do
         printf 'ERR|%s|cwd|%s\n' "$req_id" "$(printf '%s' "$cwd" | base64 | tr -d '\n')"
         continue
       fi
-      # Build the argv from the following base64 lines.
+      # Build the argv from the following base64 lines. Two refusal paths
+      # before anything runs: a payload that does not decode (it would
+      # silently become an EMPTY argv word — a different command than the
+      # host sent), and a frame that ends before its declared argument count
+      # (a truncated frame must never execute; EOF also means the host is
+      # gone, and the exit trap cleans up).
       # shellcheck disable=SC2086
       set --
       n=0
+      bad_decode=0
       while [ "$n" -lt "$nargs" ]; do
-        IFS= read -r arg_b64 || break
+        IFS= read -r arg_b64 || exit 0
         n=$((n + 1))
-        set -- "$@" "$(b64dec "$arg_b64")"
+        if ! b64dec_strict "$arg_b64"; then
+          bad_decode=1
+          continue
+        fi
+        set -- "$@" "$DEC"
       done
+      if [ "$bad_decode" -ne 0 ]; then
+        printf 'ERR|%s|protocol|%s\n' "$req_id" "$(printf '%s' "an argv payload failed to decode" | base64 | tr -d '\n')"
+        continue
+      fi
       # Dispatched: tell the host now, so its watchdog measures execution and
       # not the queue wait this request just went through.
       printf 'ACK|%s\n' "$req_id"
@@ -552,10 +651,12 @@ while IFS= read -r line; do
       nargs=${rest#*|}
       # Arguments stay base64 (write's content must never become a shell
       # variable of raw bytes); handlers decode what they treat as a path.
+      # A frame that ends before its declared argument count must never run
+      # its op on a partial argument list — and EOF means the host is gone.
       set --
       n=0
       while [ "$n" -lt "$nargs" ]; do
-        IFS= read -r arg_b64 || break
+        IFS= read -r arg_b64 || exit 0
         n=$((n + 1))
         set -- "$@" "$arg_b64"
       done

package/docs/LIMITATIONS.md

@@ -29,6 +29,13 @@ crosses the 9p share. What to know about the one substrate there is:
   syscall before the rename: a concurrent writer wins and the stale write
   refuses with `FS_STALE_VERSION`. The residual stat-then-rename pair is the
   same sliver a Linux-host session's own rename has.
+- **A Linux filename containing a backslash cannot be addressed.** The UNC
+  display form (`\\wsl.localhost\<distro>\...`) is the file's identity
+  everywhere - the session header, the GUI, the caches - and the backslash is
+  the UNC's separator, so `a\b.ts` in the distro round-trips to `a/b.ts`: the
+  tools would silently address a different path. This is the coordinate
+  system's own limit (the peer's UNC provider has it too), not a defect of
+  the substrate; a rename away from backslash names is the workaround.
 - **Stage two routes mutations through a confined resident.** A write or edit
   under a confined policy runs on its own long-lived agent, spawned inside the
   bwrap profile that binds exactly what the mode grants — so the kernel, not

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,17 +150,20 @@ 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) };
   if (line.startsWith("RES|")) {
     const [, id, exitCode, stdout, stderr, outTruncated, errTruncated] = line.split("|");
+    // A non-numeric code is protocol garbage, not a success: -1 is a value
+    // no `wait` can produce, so a caller can tell it from every real code.
+    const code = Number(exitCode);
     return {
       type: "result",
       id,
-      exitCode: Number(exitCode),
+      exitCode: Number.isSafeInteger(code) ? code : -1,
       stdout: decodeB64(stdout ?? ""),
       stderr: decodeB64(stderr ?? ""),
       // The capture-cap flags the agent appends when the EXEC frame carried a

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/lib/fs-substrate.js

@@ -261,7 +261,16 @@ export class AgentSubstrate {
     return this.lock(target.targetKey, async () => {
       const linuxPath = this.linuxOf(target);
       const existing = await this.fs.stat(linuxPath, { signal });
-      if (!existing) throw new FsCodedError(`cannot edit "${target.displayPath}": file changed since it was read`, "FS_STALE_VERSION");
+      if (!existing) {
+        // A file that is not there NOW splits by evidence: an edit grounded
+        // in a read (it carries the expected version) lost its file, so the
+        // guard is stale; an edit with no read behind it names a file that
+        // never answered the stat - the read path's missing-file dialect.
+        if (expected) {
+          throw new FsCodedError(`cannot edit "${target.displayPath}": file no longer exists`, "FS_STALE_VERSION");
+        }
+        throw new FsCodedError(`cannot edit "${target.displayPath}": file does not exist`, "FS_NOT_FOUND");
+      }
       if (existing.type !== "f") {
         throw new FsCodedError(`cannot edit "${target.displayPath}": not a regular file`, "FS_NOT_REGULAR_FILE");
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-plugin-wsl-env",
-  "version": "0.7.2",
+  "version": "0.7.4",
   "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": {
@@ -61,13 +62,14 @@
     "CONTRIBUTING.md",
     "SECURITY.md",
     "SUPPORT.md",
-    "LICENSE"
+    "LICENSE",
+    "scripts/bootstrap.sh"
   ],
   "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",

package/scripts/bootstrap.sh

@@ -0,0 +1,113 @@
+#!/usr/bin/env bash
+# Prepare a distro for this plugin: bubblewrap (required, commands fail closed
+# without it) plus the optional tools later phases use — ripgrep for in-distro
+# search, git for workspace-changes snapshots, inotifywait for the watcher's
+# primary backend.
+#
+#   scripts/bootstrap.sh [distro]            detect, print what is missing
+#   scripts/bootstrap.sh [distro] --install  ALSO run the install commands
+#
+# The install runs as the distro's root through `wsl.exe -d <distro> -u root --`,
+# so it never touches the Windows side and never needs a sudo prompt inside the
+# distro. Without --install the script is strictly read-only: it reports and
+# prints the exact commands, runnable as-is.
+#
+# Exit status: 0 when everything REQUIRED is present (or was installed), 1 when
+# bubblewrap is still missing.
+
+set -euo pipefail
+
+DISTRO="${1:-}"
+INSTALL="no"
+for arg in "$@"; do
+  case $arg in
+    --install) INSTALL="yes" ;;
+  esac
+done
+# A leading distro argument is positional; strip it from a re-scan. (The loop
+# above only looks for the flag.)
+if [ "${1:-}" = "--install" ]; then
+  DISTRO="${WSL_DISTRO_NAME:-}"
+fi
+
+if [ -z "$DISTRO" ]; then
+  DISTRO="${WSL_DISTRO_NAME:-}"
+fi
+if [ -z "$DISTRO" ]; then
+  echo "bootstrap: no distro named and WSL_DISTRO_NAME is unset" >&2
+  exit 1
+fi
+
+run_in_distro() {
+  wsl.exe -d "$DISTRO" --exec sh -c "$1" sh "$2"
+}
+
+# The package family decides the install command; a distro with none reported
+# gets the apt spelling, which covers the default Ubuntu images.
+family() {
+  run_in_distro 'for f in apt-get dnf pacman zypper; do command -v "$f" >/dev/null 2>&1 && { echo "$f"; exit 0; }; done; echo unknown' ""
+}
+
+install_command() {
+  case "$(family)" in
+    apt-get) echo 'apt-get install -y bubblewrap git ripgrep inotify-tools' ;;
+    dnf) echo 'dnf install -y bubblewrap git ripgrep inotify-tools' ;;
+    pacman) echo 'pacman -Sy --noconfirm bubblewrap git ripgrep inotify-tools' ;;
+    zypper) echo 'zypper --non-interactive install bubblewrap git ripgrep inotify-tools' ;;
+    *) echo 'apt-get install -y bubblewrap git ripgrep inotify-tools' ;;
+  esac
+}
+
+present() {
+  run_in_distro 'for t in "$@"; do command -v "$t" >/dev/null 2>&1 || exit 1; done' "$1"
+}
+
+report() {
+  local label="$1" tool="$2"
+  if run_in_distro "command -v $tool >/dev/null 2>&1" ""; then
+    echo "ok        $label ($tool)"
+  else
+    echo "MISSING   $label ($tool)"
+  fi
+}
+
+echo "distro: $DISTRO"
+
+BW_OK="yes"
+if present "bwrap"; then
+  report "bubblewrap (required; commands fail closed without it)" "bwrap"
+else
+  BW_OK="no"
+  echo "MISSING   bubblewrap (REQUIRED; every command fails closed without it)"
+fi
+report "ripgrep (in-distro search backend)" "rg"
+  report "git (workspace-changes snapshot backend)" "git"
+report "inotifywait (watcher primary backend)" "inotifywait"
+
+CMD="$(install_command)"
+echo
+echo "install command:"
+echo "  wsl.exe -d $DISTRO -u root -- $CMD"
+
+if [ "$BW_OK" = "yes" ]; then
+  echo
+  echo "bubblewrap is present; nothing required is missing."
+  exit 0
+fi
+
+if [ "$INSTALL" != "yes" ]; then
+  echo
+  echo "bubblewrap is missing. Re-run with --install to run the command above, or paste it yourself." >&2
+  exit 1
+fi
+
+echo
+echo "installing..."
+wsl.exe -d "$DISTRO" -u root -- $CMD
+
+if present "bwrap"; then
+  echo "bubblewrap installed successfully."
+  exit 0
+fi
+echo "bootstrap: bubblewrap is still missing after the install; check the output above" >&2
+exit 1