dsh-plugin-wsl-env 0.7.3 → 0.7.4

package/CHANGELOG.md

@@ -12,6 +12,40 @@ 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

package/agent/wsl-agent.sh

@@ -21,7 +21,9 @@
 #   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
@@ -124,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
@@ -307,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"
@@ -537,7 +558,9 @@ 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
 }
 
@@ -561,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")
@@ -581,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"
@@ -605,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-protocol.js

@@ -157,10 +157,13 @@ export function parseAgentLine(line) {
   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/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.3",
+  "version": "0.7.4",
   "description": "让 DeepSeek Harness 以 WSL 子系统作为会话的执行环境：shell、文件读写与命令执行均在子系统内完成，目录选择器与 GUI 终端同样定位到子系统路径，并通过子系统内的 bubblewrap 对命令进行沙箱隔离",
   "keywords": [
     "deepseek-harness",
@@ -62,7 +62,8 @@
     "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",

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