dsh-plugin-wsl-env 0.2.0 → 0.4.0

package/agent/wsl-agent.sh

@@ -18,10 +18,31 @@
 #   SHUTDOWN                      -> exits 0
 #   KILL|<id>                     -> SIGTERM the in-flight request with that id
 #   SETENV|<key>|<b64 value>      -> export the variable for later requests
-#   EXEC|<id>|<b64 cwd>|<timeout seconds|0>|<n args>
+#   EXEC|<id>|<b64 cwd>|<timeout seconds|0>|<n args>|<output cap bytes|0>
 #       followed by <n args> lines of base64, one argv word each
-#       -> RES|<id>|<exit code>|<b64 stdout>|<b64 stderr>
+#       -> ACK|<id> the moment the request is dequeued for execution — the host
+#          arms its stuck-request watchdog on this line, so time spent queued
+#          behind an earlier request never counts against a budget
+#       -> RES|<id>|<exit code>|<b64 stdout>|<b64 stderr>|<stdout cut?1:0>|<stderr cut?1:0>
+#          With a cap, stdout and stderr are each cut at that many bytes and
+#          the flags say which streams were cut; 0 means the whole capture.
 #          or ERR|<id>|<reason>|<b64 message>   (reason: cwd)
+#   FS|<id>|<op>|<timeout seconds|0>|<n args>
+#       followed by <n args> lines of base64, one argument each — arguments
+#       arrive still base64 so a write's content never passes through a shell
+#       variable as bytes
+#       ops:  stat <path> · lstat <path> · list <dir> · realpath <path>
+#             read <path> <offset> <maxbytes> · write <path> <mode|->
+#                  <replace|no-replace> <expected version|-> <content-b64>
+#       -> ACK|<id> at dequeue, then the same RES|<id>|<exit code>|<b64
+#          stdout>|<b64 stderr> line as EXEC.
+#          A failed op writes `dsh-fs|<reason>|<b64 message>` as the FIRST line
+#          of its stderr (reason: notfound notdir perm loop exists stale io),
+#          which the host's adapter maps onto the FsError codes the tool layer
+#          knows. A `replace` write carrying an expected version re-verifies it
+#          against a fresh stat one syscall before the rename and refuses with
+#          `stale` on a mismatch — the concurrent writer wins, the model's
+#          stale write does not land.
 #
 # Confinement is NOT this script's business: the host wraps argv in the bwrap
 # profile (lib/sandbox.js) before the frame is sent, so the agent executes
@@ -32,15 +53,19 @@
 
 set -u
 
-PROTO_VERSION=1
+PROTO_VERSION=3
 TMPDIR_AGENT=$(mktemp -d "${TMPDIR:-/tmp}/wsl-agent.XXXXXX")
 OUT_FILE="$TMPDIR_AGENT/out"
 ERR_FILE="$TMPDIR_AGENT/err"
-trap 'rm -rf "$TMPDIR_AGENT"; exit 0' EXIT
+trap 'rm -rf "$TMPDIR_AGENT"; [ -z "${CURRENT_STAGING:-}" ] || rm -rf -- "$CURRENT_STAGING"; exit 0' EXIT
 
 # The request currently in flight, for KILL and for the exit trap.
 CURRENT_PID=
 CURRENT_ID=
+# The staged-publication directory of an in-flight FS write. TERM/INT would
+# otherwise orphan it inside the target's own directory; a KILL cannot be
+# trapped, which is what the sweep in fs_write is for.
+CURRENT_STAGING=
 
 b64dec() {
   # `base64 -d` with GNU and BusyBox spellings; a decode failure yields empty.
@@ -76,6 +101,360 @@ timeout_watcher() {
   kill -KILL "$2" 2>/dev/null
 }
 
+# Capture one request's output and answer with RES. $1 = request id, $2 =
+# timeout seconds ('' or 0 = none), $3 = per-stream output cap in bytes (0 or
+# empty = unlimited), $4 = launch mode: `exec` runs "$@" (argv words) as the
+# request process; `subshell` runs ( "$@" ) in a forked subshell, which is how
+# the FS handlers — shell functions, not executables — run.
+run_capture() {
+  local req_id timeout_s maxout mode rc watcher_pid out_cut err_cut
+  req_id=$1
+  timeout_s=$2
+  maxout=$3
+  mode=$4
+  shift 4
+  case $maxout in
+    ''|*[!0-9]*) maxout=0 ;;
+  esac
+  : >"$OUT_FILE"
+  : >"$ERR_FILE"
+  CURRENT_ID=$req_id
+  if [ "$mode" = subshell ]; then
+    ( "$@" ) >"$OUT_FILE" 2>"$ERR_FILE" &
+  else
+    "$@" >"$OUT_FILE" 2>"$ERR_FILE" &
+  fi
+  CURRENT_PID=$!
+  watcher_pid=
+  case $timeout_s in
+    ''|0) ;;
+    *)
+      timeout_watcher "$timeout_s" "$CURRENT_PID" 3 &
+      watcher_pid=$!
+      ;;
+  esac
+  wait "$CURRENT_PID"
+  rc=$?
+  CURRENT_PID=
+  CURRENT_ID=
+  if [ -n "$watcher_pid" ]; then
+    kill "$watcher_pid" 2>/dev/null
+    wait "$watcher_pid" 2>/dev/null
+  fi
+  # The cap is what keeps a chatty command from becoming a multi-gigabyte
+  # base64 blob inside THIS shell's command substitution: only the first
+  # $maxout bytes of each stream are encoded, and the flags tell the host
+  # which streams were cut. FS frames pass 0 — their payloads are the host's
+  # own read windows, already bounded by the protocol.
+  out_cut=0
+  err_cut=0
+  if [ "$maxout" -gt 0 ]; then
+    [ "$(wc -c <"$OUT_FILE" 2>/dev/null || printf 0)" -gt "$maxout" ] && out_cut=1
+    [ "$(wc -c <"$ERR_FILE" 2>/dev/null || printf 0)" -gt "$maxout" ] && err_cut=1
+    printf 'RES|%s|%s|%s|%s|%s|%s\n' "$req_id" "$rc" \
+      "$(head -c "$maxout" -- "$OUT_FILE" | base64 | tr -d '\n')" \
+      "$(head -c "$maxout" -- "$ERR_FILE" | base64 | tr -d '\n')" \
+      "$out_cut" "$err_cut"
+  else
+    printf 'RES|%s|%s|%s|%s|%s|%s\n' "$req_id" "$rc" \
+      "$(b64enc_file "$OUT_FILE")" "$(b64enc_file "$ERR_FILE")" 0 0
+  fi
+}
+
+# --- filesystem substrate (FS frames) -------------------------------------
+#
+# The model's file tools run HERE, against ext4, instead of through the 9p
+# share. Every handler reports failure as `dsh-fs|<reason>|<b64 message>` on
+# stderr with a nonzero exit; reasons classify the coreutils error text, which
+# is why the handlers pin LC_ALL=C.
+
+fs_fail() {
+  # $1 = reason token, $2 = message. Exits 1 (the caller's RES carries it).
+  # Stderr is the op's error channel; stdout stays pure payload.
+  printf 'dsh-fs|%s|%s\n' "$1" "$(printf '%s' "$2" | base64 | tr -d '\n')" >&2
+  exit 1
+}
+
+fs_classify() {
+  # $1 = captured command stderr -> one reason token on stdout. Message
+  # matching across coreutils vintages: newer gettext says "Already exists"
+  # where older said "File exists".
+  case $1 in
+    *"No such file"*|*"not found"*) printf 'notfound' ;;
+    *"Not a directory"*) printf 'notdir' ;;
+    *"Permission denied"*) printf 'perm' ;;
+    *"Too many levels"*|*"Too many symbolic links"*) printf 'loop' ;;
+    *"File exists"*|*"Already exists"*) printf 'exists' ;;
+    *) printf 'io' ;;
+  esac
+}
+
+fs_stat() {
+  # $1 = `-L` (follow) or empty (lstat), $2 = base64 path. Emits one
+  # TAB-separated record: type mode size dev ino mtime ctime, produced by the
+  # SAME `find -printf` directives the list walk uses — `stat`'s own %.9Y
+  # rounds timestamps to microseconds where find is ns-exact, and one file
+  # then carried TWO different version strings depending on which op answered
+  # (a uutils distro). The host normalizes them into the version string.
+  local p out ftype
+  p=$(b64dec "$2")
+  out=$(find $1 "$p" -maxdepth 0 -printf '%y\t%m\t%s\t%D\t%i\t%T@\t%C@' 2>"$ERR_FILE") || {
+    fs_fail "$(fs_classify "$(cat "$ERR_FILE")")" "$(cat "$ERR_FILE")"
+  }
+  if [ "$1" = "-L" ]; then
+    # `find -L` reports a link it cannot resolve (dangling) as the link
+    # itself; the `stat -L` this op replaces failed on it with ENOENT, and
+    # the peer's probe is null for exactly that — so refuse the same way.
+    if [ "$(printf '%s' "$out" | cut -f1)" = l ]; then
+      fs_fail notfound "cannot stat \"$p\": the link does not resolve"
+    fi
+  fi
+  printf '%s\n' "$out"
+}
+
+fs_list() {
+  # $1 = base64 directory. One `find` pass, NUL-delimited records of
+  # `type size dev ino mtime ctime path`. No `-L`: the type is the entry's own
+  # (lstat), so a symlink is VISIBLE as `l` and the host resolves its target's
+  # stat and identity with one follow-up per link — the peer lists follow-stats
+  # but has to know which entries are links all the same. Names are safe inside
+  # records (records split on NUL, names taken after the 6th TAB).
+  local d err
+  d=$(b64dec "$1")
+  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"
+  }
+}
+
+fs_realpath() {
+  # $1 = base64 path. The distro-side identity: the strict realpath, and on
+  # ENOENT the nearest existing ancestor with the missing suffix appended —
+  # fsio's `resolveLocalTarget` walk, run where the symlinks actually live.
+  local p anc r suffix err
+  p=$(b64dec "$1")
+  if r=$(realpath -e -- "$p" 2>/dev/null); then
+    printf '%s' "$r"
+    return 0
+  fi
+  anc=$(dirname -- "$p")
+  while : ; do
+    if r=$(realpath -e -- "$anc" 2>/dev/null); then
+      suffix=${p#"$anc"}
+      case $suffix in
+        # Mirrors fsio's substring check, ".." inside the missing suffix is a
+        # traversal across a missing directory, refused rather than joined.
+        *..*) fs_fail notfound "cannot resolve \"$p\": parent traversal crosses a missing directory" ;;
+      esac
+      printf '%s' "$r$suffix"
+      return 0
+    fi
+    err=$(dirname -- "$anc")
+    [ "$err" = "$anc" ] && break
+    anc=$err
+  done
+  err=$(realpath -e -- "$p" 2>&1)
+  fs_fail "$(fs_classify "$err")" "$err"
+}
+
+fs_read() {
+  # $1 = base64 path, $2 = base64 byte offset, $3 = base64 max bytes. The
+  # window is the bound: at most $3 bytes leave the distro per request; the
+  # host loops. The remainder is STREAMED through the pipe, never staged —
+  # staging copied the whole tail to a temp file once per window, which made
+  # a full read of a large file quadratic in the file's own size. tail's
+  # stderr lands in ERR_FILE (its SIGPIPE death once `head` has had its fill
+  # writes nothing there), so a real read failure is still classified.
+  local p offset max err
+  p=$(b64dec "$1")
+  offset=$(b64dec "$2")
+  max=$(b64dec "$3")
+  [ "$max" -gt 0 ] || return 0
+  : >"$ERR_FILE"
+  tail -c +"$(( offset + 1 ))" -- "$p" 2>"$ERR_FILE" | head -c "$max" -- 2>/dev/null
+  if [ -s "$ERR_FILE" ]; then
+    err=$(cat "$ERR_FILE")
+    fs_fail "$(fs_classify "$err")" "$err"
+  fi
+}
+
+norm_time() {
+  # `seconds.fraction` in the host's 19-digit spelling: the fraction padded to
+  # nine digits (truncated beyond), whole seconds padded when the distro's
+  # stat has no fraction at all. This is what the host's `nanoseconds()`
+  # produces from fs_stat's directives, so the strings compare equal.
+  local s=${1%%.*} f=${1#*.}
+  if [ "$f" = "$1" ]; then
+    f=""
+  fi
+  while [ ${#f} -lt 9 ]; do
+    f="${f}0"
+  done
+  printf '%s%.9s' "$s" "$f"
+}
+
+fs_version() {
+  # One path's version string from the SAME producer the stat and list ops
+  # use (`find -printf`), joined the way the host joins a stat record's five
+  # ingredients. Empty output (non-zero) means the path is gone.
+  local out dev ino size mtime ctime
+  out=$(find "$1" -maxdepth 0 -printf '%D\t%i\t%s\t%T@\t%C@' 2>/dev/null) || return 1
+  dev=$(printf '%s' "$out" | cut -f1)
+  ino=$(printf '%s' "$out" | cut -f2)
+  size=$(printf '%s' "$out" | cut -f3)
+  mtime=$(printf '%s' "$out" | cut -f4)
+  ctime=$(printf '%s' "$out" | cut -f5)
+  printf '%s:%s:%s:%s:%s' "$dev" "$ino" "$size" "$(norm_time "$mtime")" "$(norm_time "$ctime")"
+}
+
+drop_staging() {
+  # Remove the current write's staging dir and forget it, so the EXIT trap
+  # never re-removes (or, worse, removes a newer write's staging) after it.
+  rm -rf -- "$staging"
+  CURRENT_STAGING=
+}
+
+sweep_staging() {
+  # $1 = directory, $2 = base name. Remove this directory's leftover staging
+  # dirs whose creating agent is gone — the PID rides the name, and a process
+  # that is not running cannot clean up after its own KILL. A live PID keeps
+  # its dir (the safe direction, PID reuse included).
+  local d pid
+  for d in "$1/.$2."*.*.tmpdir; do
+    [ -d "$d" ] || continue
+    pid=${d#"$1/.$2."}
+    pid=${pid%%.*}
+    case $pid in
+      ''|*[!0-9]*) continue ;;
+    esac
+    kill -0 "$pid" 2>/dev/null || rm -rf -- "$d"
+  done
+}
+
+fs_write() {
+  # $1 = base64 path, $2 = base64 mode (`-` keeps none), $3 = base64
+  # `replace` or `no-replace`, $4 = expected version (`-` for none) — the
+  # version string this write was based on, re-verified one syscall before the
+  # rename so a concurrent writer wins instead of being clobbered — and $5 =
+  # content STILL base64. Mirrors fsio's POSIX publication: a private 0700
+  # sibling staging dir, a 0600 temp, fsync, chmod, then an atomic rename — or
+  # a hard link that refuses to replace for guarded creates.
+  local path mode publish expected dir base staging tmp u err version
+  path=$(b64dec "$1")
+  mode=$(b64dec "$2")
+  publish=$(b64dec "$3")
+  expected=$(b64dec "$4")
+  dir=$(dirname -- "$path")
+  base=$(basename -- "$path")
+  [ -n "$base" ] && [ "$base" != "/" ] || fs_fail notfound "empty file name"
+  # Leftover staging dirs from a KILLed write (a KILL cannot be trapped) would
+  # sit in the target's directory forever and show up in listings. The creating
+  # agent's PID rides the name: one whose process is gone is an orphan, so
+  # sweep it before staging this write.
+  sweep_staging "$dir" "$base"
+  if [ ! -d "$dir" ]; then
+    # Deliberately NO `mkdir -p`: a typo'd parent chain must refuse (the peer's
+    # Node-fs publication fails ENOENT there), not materialize silently. An
+    # existing directory after a failed mkdir is a concurrent creator, not an
+    # error.
+    mkdir -- "$dir" 2>"$ERR_FILE" || {
+      err=$(cat "$ERR_FILE")
+      [ -d "$dir" ] || fs_fail "$(fs_classify "$err")" "$err"
+    }
+  fi
+  u=$(head -c 8 /dev/urandom 2>/dev/null | od -An -tx1 | tr -d ' \n')
+  staging="$dir/.$base.$$.${u:-0}.tmpdir"
+  mkdir -- "$staging" 2>"$ERR_FILE" || {
+    # A read-only bind names itself here — the kernel refusing what the policy
+    # granted — so the real stderr travels, not a paraphrase of it.
+    err=$(cat "$ERR_FILE")
+    fs_fail "$(fs_classify "$err")" "$err"
+  }
+  CURRENT_STAGING=$staging
+  chmod 700 -- "$staging" 2>/dev/null
+  tmp="$staging/$base.tmp"
+  # Decode straight to the file: the base64 text is the one form that crosses
+  # a shell variable without a NUL-byte or quoting hazard.
+  printf '%s' "$5" | base64 -d >"$tmp" 2>/dev/null || {
+    drop_staging
+    fs_fail io "cannot stage content"
+  }
+  chmod 600 -- "$tmp"
+  sync -f -- "$tmp" 2>/dev/null || :
+  if [ "$mode" != "-" ]; then
+    chmod "$mode" -- "$tmp" 2>"$ERR_FILE" || {
+      err=$(cat "$ERR_FILE")
+      drop_staging
+      fs_fail io "$err"
+    }
+  fi
+  if [ "$publish" = "replace" ] && [ -n "$expected" ] && [ "$expected" != "-" ]; then
+    # The version the overwrite/edit was based on is re-verified HERE — one
+    # syscall before the rename, where the host's round-trip-wide window was.
+    # The producer is fs_stat's own stat directives, so this comparison never
+    # trips the stat/find skew a list-derived version would.
+    version=$(fs_version "$path")
+    if [ "$version" != "$expected" ]; then
+      drop_staging
+      if [ -n "$version" ]; then
+        fs_fail stale "cannot write \"$path\": file changed since it was read"
+      fi
+      fs_fail stale "cannot write \"$path\": file no longer exists"
+    fi
+  fi
+  if [ "$publish" = "no-replace" ]; then
+    # Coreutils `ln` resolves an existing DIRECTORY destination (linking beside
+    # it) where the peer's link(2) refuses any existing path, so the existence
+    # guard is checked before the call and the landing spot verified after it.
+    if [ -e "$path" ] || [ -L "$path" ]; then
+      drop_staging
+      fs_fail exists "cannot write \"$path\": it already exists"
+    fi
+    ln -- "$tmp" "$path" 2>"$ERR_FILE" || {
+      err=$(cat "$ERR_FILE")
+      drop_staging
+      # A concurrent creator wins the race; classify by what is on disk now.
+      if [ -e "$path" ] || [ -L "$path" ]; then
+        fs_fail exists "$err"
+      fi
+      fs_fail "$(fs_classify "$err")" "$err"
+    }
+    if ! [ "$tmp" -ef "$path" ]; then
+      # ln linked BESIDE the target (a directory appeared under us): undo the
+      # stray link and refuse, the guarded create did not publish.
+      rm -f -- "$path/${base}.tmp"
+      drop_staging
+      fs_fail exists "cannot write \"$path\": it was created concurrently"
+    fi
+  else
+    mv -f -- "$tmp" "$path" 2>"$ERR_FILE" || {
+      err=$(cat "$ERR_FILE")
+      drop_staging
+      fs_fail "$(fs_classify "$err")" "$err"
+    }
+  fi
+  drop_staging
+}
+
+fs_dispatch() {
+  # $1 = op, $2.. = raw base64 arguments (handlers decode what they need to
+  # treat as a path; write's content stays base64 until it hits the file).
+  local op
+  op=$1
+  shift
+  LC_ALL=C
+  export LC_ALL=C
+  case $op in
+    stat)     fs_stat -L "$1" ;;
+    lstat)    fs_stat "" "$1" ;;
+    list)     fs_list "$1" ;;
+    realpath) fs_realpath "$1" ;;
+    read)     fs_read "$1" "$2" "$3" ;;
+    write)    fs_write "$1" "$2" "$3" "$4" "$5" ;;
+    *)        fs_fail notfound "unknown fs op" ;;
+  esac
+}
+
 printf 'HELLO|wsl-agent|%s\n' "$PROTO_VERSION"
 
 while IFS= read -r line; do
@@ -108,7 +487,9 @@ while IFS= read -r line; do
       cwd_b64=${rest%%|*}
       rest=${rest#*|}
       timeout_s=${rest%%|*}
-      nargs=${rest#*|}
+      rest=${rest#*|}
+      nargs=${rest%%|*}
+      maxout=${rest#*|}
       cwd=$(b64dec "$cwd_b64")
       if ! cd "$cwd" 2>/dev/null; then
         printf 'ERR|%s|cwd|%s\n' "$req_id" "$(printf '%s' "$cwd" | base64 | tr -d '\n')"
@@ -123,28 +504,33 @@ while IFS= read -r line; do
         n=$((n + 1))
         set -- "$@" "$(b64dec "$arg_b64")"
       done
-      : >"$OUT_FILE"
-      : >"$ERR_FILE"
-      CURRENT_ID=$req_id
-      "$@" >"$OUT_FILE" 2>"$ERR_FILE" &
-      CURRENT_PID=$!
-      watcher_pid=
-      case $timeout_s in
-        ''|0) ;;
-        *)
-          timeout_watcher "$timeout_s" "$CURRENT_PID" 3 &
-          watcher_pid=$!
-          ;;
-      esac
-      wait "$CURRENT_PID"
-      rc=$?
-      CURRENT_PID=
-      CURRENT_ID=
-      if [ -n "$watcher_pid" ]; then
-        kill "$watcher_pid" 2>/dev/null
-        wait "$watcher_pid" 2>/dev/null
-      fi
-      printf 'RES|%s|%s|%s|%s\n' "$req_id" "$rc" "$(b64enc_file "$OUT_FILE")" "$(b64enc_file "$ERR_FILE")"
+      # 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"
+      run_capture "$req_id" "$timeout_s" "$maxout" exec "$@"
+      ;;
+    FS\|*)
+      header=${line#FS|}
+      req_id=${header%%|*}
+      rest=${header#*|}
+      op=${rest%%|*}
+      rest=${rest#*|}
+      timeout_s=${rest%%|*}
+      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.
+      set --
+      n=0
+      while [ "$n" -lt "$nargs" ]; do
+        IFS= read -r arg_b64 || break
+        n=$((n + 1))
+        set -- "$@" "$arg_b64"
+      done
+      # Same dispatch signal as EXEC: the FS budget starts at the op, not at
+      # the queue position. No capture cap — the payloads are the host's own
+      # read windows, bounded by the protocol.
+      printf 'ACK|%s\n' "$req_id"
+      run_capture "$req_id" "$timeout_s" 0 subshell fs_dispatch "$op" "$@"
       ;;
     *)
       printf 'ERR||protocol|%s\n' "$(printf '%s' "unrecognized request" | base64 | tr -d '\n')"

package/cordis.patch.yml

@@ -168,6 +168,13 @@
                 config:
                   distro: ''
                   restrictToDistro: true
+                  # agent (the default): reads/writes/identities run inside the
+                  # distro over the resident agent (lib/fs-substrate.js) —
+                  # native symlinks and mode bits, the write guard survives to
+                  # publication, and confined mutations are kernel-enforced.
+                  # share: the opt-out — the Windows-side host fs stack over
+                  # the 9p share.
+                  substrate: agent
               - id: persona
                 name: '@deepseek-ai/dsh-persona'
                 config:

package/docs/ARCHITECTURE.md

@@ -19,7 +19,7 @@ smaller integrations.
 | Service | Class | File | What it does |
 |---|---|---|---|
 | `ctx.shell` | `WslShellExecutor` | [`lib/index.js`](../lib/index.js) | Runs each command as `wsl.exe -d <distro> --cd <linux dir> --exec <login shell> -lc <cmd>`, wrapped in a distro-side `bwrap` sandbox. |
-| `ctx.fs` | `WslFileSystem` | [`lib/index.js`](../lib/index.js) | Maps Linux paths onto the distro's UNC share, so the host filesystem stack and the packaged ripgrep work on real distro files. |
+| `ctx.fs` | `WslFileSystem` | [`lib/index.js`](../lib/index.js) | Serves the file tools from real distro files, on one of two I/O substrates (see below): the Windows-side host stack over the distro's UNC share (default), or the resident in-distro agent on ext4. |
 | `ctx.subprocess` | `WslSubprocessRuntime` | [`lib/subprocess.js`](../lib/subprocess.js) | Opens the GUI terminal inside the distro, in the session workspace. |
 
 `WslShellExecutor` extends the shipped `LocalBashExecutor`, and `WslFileSystem`
@@ -92,6 +92,32 @@ Three coordinate systems appear in the code:
 DSH package and performs no I/O. Its containment helpers decide whether a target
 path sits under a writable root. The filesystem fence uses them.
 
+## The filesystem substrate
+
+`wsl-fs` serves `ctx.fs` on one of two I/O substrates, chosen by
+`substrate: share | agent` (default `agent`):
+
+| | `agent` (default) | `share` (opt-out) |
+|---|---|---|
+| Reads, writes, identities | the resident in-distro agent, on ext4 | the Windows-side host stack (`dsh-fs-local`) over the distro's 9p share |
+| Symlinks | native; every identity is a distro-side `realpath` | the share cannot traverse them, so a missing read is retried once through the distro's canonical path |
+| Mode bits | native; the publication rename is the kernel's | the share drops a host-side chmod, so publication re-applies the mode from inside the distro before an atomic rename |
+| Guarded creates | the guard is forwarded; publication is a no-replace link, closing the check-then-write window for creates. An overwrite or edit carries its version into the write op and the agent re-verifies it one syscall before the rename — a concurrent writer wins, the stale write refuses with `FS_STALE_VERSION` | checked, then published without a guard (the share has no hard links) |
+| Kernel enforcement | stage two: a mutation runs on a confined resident — one long-lived agent per (distro, policy), whose bwrap profile binds exactly what the mode grants — so the kernel refuses what the check would have, and a check bug cannot become a write outside the workspace. Escalated writes (`danger-full-access`) ride the plain resident. A kernel refusal carries `FS_SANDBOX_DENIED`, the same dialect as the command path. | none: the fence is the host-side check |
+| New files | 0600 — the host backend's own POSIX publication semantics, as on a Linux host | the distro's umask default (0644) |
+| Agent outage | `FS_IO_ERROR` naming the substrate; no silent fallback to the share. A distro without usable bwrap refuses confined mutations with the bootstrap command, the same closed failure the command path has | not applicable |
+
+Both substrates fence writes with the same host-side policy check
+(`checkedTarget`), and neither changes what `sandboxMode` reports. The wire
+protocol the agent substrate speaks is documented in
+[`agent/wsl-agent.sh`](../agent/wsl-agent.sh); the orchestration layers are
+[`lib/fsio-agent.js`](../lib/fsio-agent.js) (fsio's mechanics over the FS
+frames), [`lib/fs-substrate.js`](../lib/fs-substrate.js) (the provider-shaped
+operations, including the write/edit guard orchestration), and
+[`lib/fsio-text.js`](../lib/fsio-text.js) (the pure text mechanics, replicated
+from upstream pending the export proposed in
+[UPSTREAM-FSIO-EXPORT.md](UPSTREAM-FSIO-EXPORT.md)).
+
 ## Sandbox
 
 ### Why the Windows runner cannot be used
@@ -238,6 +264,16 @@ lib/wsl.js          wsl.exe interop primitives (no DSH imports)
 lib/listing.js      pure directory listing and breadcrumb helpers (no DSH imports)
 lib/index.js        WslShellExecutor (ctx.shell) and WslFileSystem (ctx.fs)
 lib/sandbox.js      the distro-side bwrap confinement shared by both providers
+lib/bwrap.js        the bwrap command line both confinement sites assemble
+                    (no imports, so a bare checkout can assert it)
+lib/fsio-text.js    the peer's pure text mechanics, replicated pending the
+                    upstream fsio export (see UPSTREAM-FSIO-EXPORT.md)
+lib/fsio-agent.js   fsio's mechanics over the agent's FS frames
+lib/fs-substrate.js the agent substrate's provider-shaped operations
+lib/agent.js        the resident in-distro agent's host side
+lib/agent-confined.js the confined residents' factory (one per policy)
+lib/agent-protocol.js the wire protocol codecs (pure)
+agent/wsl-agent.sh  the resident in-distro agent (POSIX sh, coreutils only)
 lib/picker.js       WslDirectoryPicker (ctx.directoryPicker)
 lib/subprocess.js   WslSubprocessRuntime (ctx.subprocess), the terminal window
 lib/auto-preset.js  per-session environment selection

package/docs/CONFIGURATION.md

@@ -16,12 +16,15 @@ are schema defaults, listed because they are the ones worth knowing.
 | | `loginShell` | `true` *(shipped)* | use `<shell> -lc`, which sources your profile, instead of a bare `-c` |
 | | `agent` | `true` | run commands over the resident in-distro agent (one long-lived process; in-distro timeout); any agent failure falls back to the one-shot `wsl.exe` path |
 | | `sandbox` | `true` | confine commands with `bubblewrap`; `false` disables the sandbox |
+| | `maskWindowsDrive` | `false` | shadow `/mnt` with an empty tmpfs in every confined profile: the Windows drive's files cannot be read or exfiltrated and its executables cannot be launched through interop — the hole that lets a "sandboxed" command reach your full Windows token. A narrowing, not a closure (a command can still write an executable into the workspace and run it — binfmt dispatches on content, not location), so enforcement stays `partial` and the result's sandbox fact reports `windowsDrive: "masked"`. The complete closure is distro-level: `[interop] enabled=false` in `wsl.conf` |
 | | `cwd` | `''` | default working directory; empty means the distro user's home |
 | | `timeoutMs` / `maxTimeoutMs` | `120000` / `600000` *(shipped)* | per-call time limit, and the ceiling a call may ask for |
 | `wsl-fs` | `distro` | `''` *(shipped)* | as above |
 | | `restrictToDistro` | `true` *(shipped)* | refuse a path in **another distro**'s share. `/mnt/c` is a directory *inside* the pinned distro, so it is not affected. The refusal carries `FS_OUTSIDE_DISTRO`; that is not a sandbox decision, so the file tools do not offer a wider permission for it. Set `false` to allow another distro's share |
 | | `sandbox` | `true` | check `writeText` and `editText` against the policy |
-| | `resolveSymlinks` | `true` | follow Linux symlinks that the share cannot traverse, such as `/etc/os-release` and `/bin` |
+| | `maskWindowsDrive` | `false` | as on `wsl-shell`: confined fs mutations publish through a resident whose profile shadows `/mnt` (same honest limits) |
+| | `substrate` | `agent` *(shipped)* | which I/O substrate serves the file tools: `agent` — the resident in-distro agent (`lib/fs-substrate.js`), where reads, writes and identities run on ext4: native symlinks, native mode bits, and the mutation guard survives to the write's atomic publication, kernel-enforced by the confined resident when the policy is confined. `share` — the opt-out: the Windows-side host stack over the 9p share, with the symlink-retry and publication hooks. Both substrates fence writes with the same host-side policy check. See [LIMITATIONS.md](LIMITATIONS.md) for what changes between them |
+| | `resolveSymlinks` | `true` | *(share substrate only)* follow Linux symlinks that the share cannot traverse, such as `/etc/os-release` and `/bin` — the agent substrate follows them natively |
 | | `cwd` | `''` | base directory for relative paths; empty means the distro user's home |
 | `directory-picker-wsl` | `preferredDistro` | `''` *(shipped)* | the distro listed first in the picker |
 | | `includeHostHome` | `true` *(shipped)* | also list the Windows home directory |

package/docs/LIMITATIONS.md

@@ -3,9 +3,72 @@
 What the plugin does not do, and why. A limitation that is documented is a design
 boundary; one that is not is a bug report waiting to happen.
 
+## The filesystem substrate (`wsl-fs` `substrate`)
+
+`substrate: "agent"` (the default) serves the file tools through the resident
+in-distro agent, on ext4. `substrate: "share"` is the opt-out: the Windows-side
+host stack over the distro's 9p share. What differs:
+
+- **A new file publishes with mode 0600 on the agent substrate.** That is the
+  host backend's own POSIX publication semantics (a private 0600 staging file,
+  renamed into place), which a Linux-host DSH session has always had. The share
+  substrate was the outlier: the share drops mode sets, so new files took the
+  distro's umask default (0644). Overwrites and edits keep the original bits on
+  both substrates. Run `chmod` (or ask the model to) when a new file must be
+  executable.
+- **There is no silent fallback to the share.** When the agent substrate's
+  resident process is out — the distro stopped, or the agent crashed past its
+  one rebuild — file operations fail with `FS_IO_ERROR` naming the substrate,
+  rather than quietly degrading to share semantics that cannot follow symlinks
+  or keep mode bits. The share substrate dies with the distro anyway; the
+  agent only adds its own failure mode, which is the one honest way to fail.
+  The failure message names the opt-out: set `substrate: "share"` in the
+  provider config to keep working on the Windows-side share while the agent
+  is out.
+- **The mutation guard survives to the write.** `createIfAbsent` publishes with
+  a no-replace link inside the distro, which closes the check-then-write window
+  for creates outright. An overwrite or edit carries the version it was based
+  on into the write op, and the agent re-verifies it against a fresh stat one
+  syscall before the rename: a concurrent writer wins and the stale write
+  refuses with `FS_STALE_VERSION`. That narrows the share's window from a host
+  round trip to kernel-adjacent — the residual stat-then-rename pair is the
+  same sliver a Linux-host session's own rename has.
+- **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
+  just the host-side check, refuses a write outside the workspace, and the
+  refusal carries `FS_SANDBOX_DENIED` (the command path's dialect). Costs to
+  know: `bubblewrap` becomes required for confined writes (a distro without it
+  refuses them with the bootstrap command, rather than downgrading); a policy
+  change addresses a different resident, so the first write after switching the
+  Permissions selector pays one agent startup; and a write the policy grants to
+  the distro's `/tmp` lands in the confined mount's tmpfs, not the real `/tmp`
+  — the same hand-off rule as the commands' `/tmp`: pass files through the
+  session workspace.
+- **`resolveSymlinks` is not consulted.** The share cannot traverse Linux
+  symlinks, so the share substrate retries missing reads through the distro's
+  canonical path; the agent substrate never misses them, so the config key has
+  no effect there.
+- **`glob` and `grep` are unchanged on both substrates.** They are tool-layer
+  searches running the packaged Windows ripgrep against the share — correct
+  results, slow, and `.gitignore` interpreted with Windows rules. Bringing them
+  in-distro is future work, not part of the substrate switch.
+- **`watch()` is the same poll loop on both substrates** (a `find -newer` scan
+  inside the distro), so the coarse-invalidation caveats below apply equally.
+  An inotify backend is planned, not shipped.
+
+Everything below applies to the share substrate unless it says otherwise.
+
 - **The sandbox does not govern WSL interop.** A confined command can still run a
   Windows program, which escapes the Linux-side boundary. The plugin reports this as
   `enforcement: partial`. See [ARCHITECTURE.md](ARCHITECTURE.md#reported-enforcement).
+  The `maskWindowsDrive` key on `wsl-shell` and `wsl-fs` narrows the hole: the
+  confined profile shadows `/mnt` with an empty tmpfs, so the drive's files cannot be
+  read or exfiltrated and its executables cannot be launched. It is not a closure — a
+  command that can write the workspace can write an executable there and run it
+  (binfmt interop dispatches on file content, not location) — so enforcement stays
+  `partial`, the result's sandbox fact reports `windowsDrive: "masked"`, and the only
+  complete closure remains distro-level (`[interop] enabled=false` in `wsl.conf`).
 - **`bubblewrap` must be installed**, or both providers fail immediately. The
   usability probe re-runs after a failure, so installing bubblewrap while the app
   runs is believed on the next command; only a success is cached.
@@ -30,7 +93,10 @@ boundary; one that is not is a bug report waiting to happen.
 - The check before a write is "check, then write", which is not atomic. This backend
   checks the caller's guard itself, because the Windows backend publishes a guarded
   new file with a hard link, and the share does not support hard links. This is the
-  race that `dsh-fs-sandbox` already documents.
+  race that `dsh-fs-sandbox` already documents — and one reason the share substrate
+  is the documented FALLBACK rather than the main path: its publication rides the
+  unconfined agent, so it never receives the confined resident's kernel-enforced
+  containment. The agent substrate does.
 - `watch()` observes from inside the distro (a `find -newer` poll loop, see
   `lib/watcher.js`), so events are coarse invalidation, not per-file notifications,
   and they arrive on the poll cadence, not instantly. A file created with an mtime