dsh-plugin-wsl-env 0.1.9 → 0.2.0

package/CHANGELOG.md

@@ -12,6 +12,127 @@ reference below points at that record's numbering.
 
 ## [Unreleased]
 
+### Fixed
+
+- **`truncated` missing from the agent path's output streams** — the bash tool's
+  canonical result copies the field unconditionally (`canonicalBashResult`), so an
+  `undefined` failed the wire's lossless-JSON snapshot and EVERY shell tool call
+  returned "tool bash returned invalid output: value is not lossless JSON". The
+  agent path now always reports `truncated: false` (it never truncates; there are
+  no spill files). Regression assertion in `test/agent-exec.test.mjs`.
+- **The agent execution path failed every shell call whose request carried an
+  absolute UNC workdir** — which is every call a GUI session makes, so the
+  harness's own agent session lost its bash tool until the fix. The one-shot
+  path converts the spec's workdir inside `argv()` (`toLinuxPath`); the agent
+  path carried the workdir as a raw frame field, so the raw UNC reached the
+  in-distro `chdir`, the synthesized relay text fired `throwIfWorkdirMissing`,
+  and the call died with "could not enter the working directory". The conversion
+  now happens at the call site (regression test in `test/shell.test.mjs`).
+
+### Added
+
+- **Phase 5: per-session terminal routing.** `spawnTerminal` now routes on the
+  request's directory coordinates (`lib/terminal-route.js`, `subprocess-wsl.hostSessions`,
+  default on): a WSL-folder session gets the distro shell, a Windows-folder session gets
+  a host `powershell.exe` in its own directory — no more distro terminal at
+  `/mnt/<drive>/…` for host sessions. The shell menu stays the single configured profile,
+  and every non-`wsl.exe` consumer is untouched. Still limited (LIMITATIONS.md): the
+  shell menu is one entry, and directory-less launches land in the distro.
+- **Phase 7: developer-loop recipes.** Both READMEs gain a Recipes section: Git
+  credential sharing through the Windows Credential Manager, `/mnt/c` 9p
+  performance guidance, and the `WSLENV` passthrough policy (prefix-admitted
+  `DSH_*`, `/p` translation, `PATH` deliberately excluded).
+- **Phase 6: listening-port visibility.** `DSH_WSL_PORTS` joins the managed
+  `DSH_*` facts: the ports with a listener inside the distro, comma-separated,
+  refreshed every `portsRefreshMs` (default 10s) through the resident agent by
+  reading `/proc/net/tcp{,6}` directly — no `ss`, nothing to install. The
+  registry's resolve is synchronous by contract, so the snapshot is served
+  stale-but-recent; a dev server started moments ago appears on the next
+  refresh. Scoped as before: only sessions whose workspace is inside a distro
+  see it. Probed live: a real HTTP server appears in the next snapshot.
+- **Phase 4: bootstrap.** `npm run bootstrap -- [distro] [--install]` checks the
+  distro for bubblewrap (required) plus ripgrep and inotifywait (the optional
+  backends later phases prefer), prints the exact copy-paste install command for
+  the distro's package family (apt/dnf/pacman/zypper), and with `--install` runs
+  it as the distro's root through `wsl.exe -u root` — no sudo prompt inside the
+  distro, nothing touches the Windows side. The `SANDBOX_UNAVAILABLE` message now
+  names the same command instead of a bare `sudo apt install`. Probed live:
+  detect mode on a distro that already has bubblewrap.
+- **Phase 3: shell execution through the agent.** `WslShellExecutor` now runs commands
+  over the resident agent when it is up (`wsl-shell.agent`, default on): one long-lived
+  in-distro process instead of a `wsl.exe` per command, with the timeout enforced
+  INSIDE the distro (TERM, then KILL after the grace) instead of against the Windows
+  process tree. The confinement argv, the execution-handle shape, the result
+  decoration (runner failures, denials, `enforcement: partial`) and the workdir
+  failure are all identical to the one-shot path — an out-of-service agent falls back
+  to it per call, permanently after the agent's rebuild budget. Probed end-to-end:
+  `npm run probe:exec` (confined completion, verbatim shell parsing, in-distro
+  timeout, relay-shaped cwd failure, kill). Documented deviation: the agent path has
+  no live output streaming — reads after settlement carry the whole stream, and no
+  spill files (the protocol line already holds it in memory).
+- **Phase 2 (second half, first slice): in-distro publication through the agent.**
+  `WslFileSystem` now carries an optional resident agent (`wsl-fs.agent`, default on):
+  when available, publication — the replaced file's mode copied onto the staged temp,
+  then the atomic rename — is ONE `exec` inside the distro (`lib/fs-publish.js`)
+  instead of a `wsl.exe` chmod plus a 9p rename. Any agent failure falls back to the
+  legacy two-step path for that call; the flag changes round trips, never what is
+  published. Probed: the publication script's mode preservation and creation
+  behaviour run in `test/probe/agent.sh` (now 10 checks).
+- **Phase 2 (first half): real `watch()`.** `WslFileSystem.watch` now observes from
+  inside the distro — a long-lived `wsl.exe` `find -newer` poll loop (`lib/watcher.js`)
+  firing the seam's coarse invalidation callback — instead of refusing with
+  `FS_IO_ERROR`. Activates on a READY barrier from the loop (a write racing the first
+  tick is never invisible), sees creations and deletions (both bump the parent's
+  mtime), and cleans up on close. Documented blind spot: files created with an
+  mtime older than the stamp (`cp -p`, `tar -x`). Probed end-to-end:
+  `npm run probe:watch`. The native-ext4 migration of the remaining fs operations
+  stays with Phase 3 of the plan.
+- **Phase 1 of the Remote-WSL parity plan (`docs/PARITY.md`): the resident in-distro
+  agent.** `agent/wsl-agent.sh` is a dependency-free POSIX shell peer spawned once per
+  distro; `lib/agent.js` owns the lifecycle (handshake, lazy start, idle shutdown, one
+  rebuild, permanent fallback to the shipped one-shot `wsl.exe` path) and
+  `lib/agent-protocol.js` the line protocol (base64 payloads, NUL-safe argv). Not wired
+  into the seams yet — the executor and filesystem migrations are the next phases.
+  Probed end-to-end against a real distro: `test/probe/agent.sh` (8 checks, including
+  binary-safe payloads, an in-distro timeout kill, and a 2 MB single-line response).
+  Unit tests cover the codecs and the lifecycle state machine with a fake transport.
+
+### Added
+
+- `docs/PARITY.md`: the plan to reach VS Code Remote-WSL-grade experience — a resident
+  in-distro agent as the core, with the `fs` and `shell` seams migrated onto it and the
+  current 9p/one-shot paths kept as the documented fallback — plus the Phase-0 contract
+  audit that shaped it (watch is a coarse invalidation callback; search spawns the
+  packaged ripgrep through `ctx.subprocess`, so the interception point is the
+  `subprocess-wsl` subclass).
+
+### Changed
+
+- The package description is rewritten in Chinese to state what the plugin does first —
+  it makes a WSL distro the session's execution environment — then covers the execution,
+  UI, and sandbox aspects in one clause each.
+- Chinese text now says “WSL 子系统” instead of “WSL 发行版”, the phrasing Chinese readers
+  more commonly use for a WSL distro (`docs/README.zh.md` and the two archived Chinese
+  documents; 99 occurrences).
+
+## [0.1.10] - 2026-10-02
+
+Metadata and one documentation addition. No behaviour change.
+
+### Changed
+
+- The package description now covers all four capabilities — commands, the file tools,
+  the folder picker, the GUI terminal — and the confinement, instead of naming only two
+  of them. It is the line npm shows under the package name in search results.
+
+### Documentation
+
+- The error table in `docs/ARCHITECTURE.md` states exactly what the model sees on a
+  filesystem denial: the denial marker and the escalation hint, line for line. It also
+  records why that makes `FS_OUTSIDE_DISTRO` worth its own code — a code the tool layer
+  does not decorate with those lines.
+
+
 ## [0.1.9] - 2026-10-02
 
 The last test gap from the closure review: the documented opt-out. No runtime change.

package/README.md

@@ -28,7 +28,7 @@ Step 3 should print a layer named `# == dsh-plugin-wsl-env`, and `- id: terminal
 
 Then open a folder under `\\wsl.localhost\<distro>\...` in the GUI. The picker lists every installed distro at its root level, and **New terminal** opens a shell in the distro.
 
-You also need **bubblewrap inside the distro**: `sudo apt install bubblewrap`. Without it every command fails closed, see [Sandbox](#sandbox).
+You also need **bubblewrap inside the distro**: run `npm run bootstrap -- <distro> --install` (drop `--install` for a read-only check), or paste `wsl.exe -d <distro> -u root -- apt-get install -y bubblewrap`. Without it every command fails closed, see [Sandbox](#sandbox).
 
 Uninstall: `dsh plugin --profile wsl remove dsh-plugin-wsl-env`. Upgrade: run the same `add` command again.
 
@@ -77,11 +77,28 @@ Commands are confined by `bubblewrap` inside the distro, and file writes are che
 
 See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md#sandbox) for the design, and [docs/LIMITATIONS.md](docs/LIMITATIONS.md) for everything the plugin does not do.
 
+## Recipes
+
+- **Git credential sharing**: let git inside the distro use the Windows-side Git
+  Credential Manager — `git config --global credential.helper "/mnt/c/Program\ Files/Git/mingw64/bin/git-credential-manager.exe"`
+  (adjust the path to your Windows Git install; WSL2's localhost forwarding is
+  platform behaviour, so ports a dev server listens on inside the distro are
+  reachable from Windows directly).
+- **Paths and performance**: the model sees and operates on Linux paths
+  (`/home/...`) on the distro's own ext4. `/mnt/c` reaches the Windows disk over
+  9p — noticeably slow for many small files; keep heavy-IO projects on the
+  distro filesystem. `npm run bootstrap -- <distro>` also reports whether
+  ripgrep and inotifywait (the search and watch backends) are in place.
+- **WSLENV passthrough**: WSL imports only the variables listed in `WSLENV`.
+  This plugin admits the managed `DSH_*` namespace by prefix, translating the
+  two Windows-path ones (`DSH_HOME`, `DSH_PROFILE_DIR`) with `/p`. `PATH` is
+  deliberately never forwarded — it would shadow the distro's own PATH.
+
 ## Troubleshooting
 
 | Symptom | Cause | Fix |
 |---|---|---|
-| every command reports `SANDBOX_UNAVAILABLE` | `bubblewrap` is not installed in the distro | run `sudo apt install bubblewrap`, or set `sandbox: false` on both providers |
+| every command reports `SANDBOX_UNAVAILABLE` | `bubblewrap` is not installed in the distro | run `npm run bootstrap -- <distro> --install`, or set `sandbox: false` on both providers |
 | a command or write is refused outside the session folder | expected behaviour of `workspace-write` | accept the wider-permission offer, or open a session on the folder you need |
 | writes are refused even inside the workspace | the session is in `read-only` mode | switch the Permissions selector |
 | `dsh plugin add` warns that no layer was activated | the dependency was already installed, so `add` had nothing to record | run `dsh plugin --profile wsl remove dsh-plugin-wsl-env`, then add it again |

package/agent/wsl-agent.sh

@@ -0,0 +1,156 @@
+#!/bin/sh
+# wsl-agent — the resident in-distro peer of dsh-plugin-wsl-env.
+#
+# The plugin spawns one long-lived instance per distro:
+#
+#   wsl.exe -d <distro> --exec <login shell> <this script>
+#
+# and speaks a line protocol over stdio. Fields are separated by `|`; binary
+# payloads (cwd, argv words, env values, captured output) travel as single-line
+# base64. The protocol deliberately avoids JSON: the agent must run under a
+# bare POSIX sh with no dependencies beyond coreutils' `base64`, because the
+# one thing a distro is guaranteed to have is a shell.
+#
+# Handshake — the first line the agent writes:
+#   HELLO|wsl-agent|<protocol version>
+# 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
+#   EXEC|<id>|<b64 cwd>|<timeout seconds|0>|<n args>
+#       followed by <n args> lines of base64, one argv word each
+#       -> RES|<id>|<exit code>|<b64 stdout>|<b64 stderr>
+#          or ERR|<id>|<reason>|<b64 message>   (reason: cwd)
+#
+# 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
+# exactly what the host decided, sandbox included.
+#
+# Exit codes: 0 on SHUTDOWN or EOF; 130 on an interrupted read. A crash is the
+# host's signal to rebuild once and then fall back to one-shot `wsl.exe` mode.
+
+set -u
+
+PROTO_VERSION=1
+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
+
+# The request currently in flight, for KILL and for the exit trap.
+CURRENT_PID=
+CURRENT_ID=
+
+b64dec() {
+  # `base64 -d` with GNU and BusyBox spellings; a decode failure yields empty.
+  printf '%s' "$1" | base64 -d 2>/dev/null || printf '%s' "$1" | base64 --decode 2>/dev/null || :
+}
+
+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
+  # RES line into protocol garbage the host would read as unknown lines.
+  base64 "$1" 2>/dev/null | tr -d '\n' || base64 -- "$1" 2>/dev/null | tr -d '\n' || :
+}
+
+kill_current() {
+  if [ -n "$CURRENT_PID" ]; then
+    kill -TERM "$CURRENT_PID" 2>/dev/null
+  fi
+}
+
+shutdown() {
+  kill_current
+  exit 0
+}
+trap shutdown TERM INT HUP
+
+timeout_watcher() {
+  # $1 = seconds, $2 = pid, $3 = grace seconds. TERM first; a process that
+  # ignores TERM gets KILLed after the grace, so a stuck command cannot hang
+  # the request forever.
+  sleep "$1"
+  kill -TERM "$2" 2>/dev/null
+  sleep "${3:-3}"
+  kill -KILL "$2" 2>/dev/null
+}
+
+printf 'HELLO|wsl-agent|%s\n' "$PROTO_VERSION"
+
+while IFS= read -r line; do
+  case $line in
+    PING)
+      printf 'PONG\n'
+      ;;
+    SHUTDOWN)
+      shutdown
+      ;;
+    KILL\|*)
+      kill_id=${line#KILL|}
+      if [ "$kill_id" = "$CURRENT_ID" ]; then
+        kill_current
+      fi
+      ;;
+    SETENV\|*)
+      rest=${line#SETENV|}
+      key=${rest%%|*}
+      b64=${rest#*|}
+      # Command substitution strips trailing newlines from the decoded value;
+      # acceptable for environment values, documented in the protocol.
+      decoded=$(b64dec "$b64")
+      export "$key=$decoded"
+      ;;
+    EXEC\|*)
+      header=${line#EXEC|}
+      req_id=${header%%|*}
+      rest=${header#*|}
+      cwd_b64=${rest%%|*}
+      rest=${rest#*|}
+      timeout_s=${rest%%|*}
+      nargs=${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')"
+        continue
+      fi
+      # Build the argv from the following base64 lines.
+      # shellcheck disable=SC2086
+      set --
+      n=0
+      while [ "$n" -lt "$nargs" ]; do
+        IFS= read -r arg_b64 || break
+        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")"
+      ;;
+    *)
+      printf 'ERR||protocol|%s\n' "$(printf '%s' "unrecognized request" | base64 | tr -d '\n')"
+      ;;
+  esac
+done
+
+# EOF on stdin: the host is gone. The EXIT trap removes the temp dir.
+exit 0

package/docs/ARCHITECTURE.md

@@ -189,6 +189,14 @@ to be invisible:
 | the distro is missing, stopped or unregistered | a `Wsl/Service/WSL_E_*` code on **stdout**, UTF-16 on some builds, with an empty stderr and exit 255 | `WslShellExecutor` reads the code with the NULs stripped and fails with the distro name and the remedy. Deliberately not a sandbox code: a wider permission cannot create a distro |
 | the working directory cannot be entered | a relay line on stderr, exit **0**, and the command runs in `/` | `WslShellExecutor` fails with the directory and the fallback, instead of reporting a success that acted on the wrong tree |
 
+
+What the model actually sees on a filesystem denial is two lines the tool layer
+prepends: `[sandbox: file access denied under <mode> mode]`, then
+`[sandbox: escalation available — retry this exact operation once with
+sandbox_permissions (the narrowest wider mode that suffices) + justification; the
+approval prompt asks the user]`. A code that is not `FS_SANDBOX_DENIED` gets neither
+line — which is the reason `FS_OUTSIDE_DISTRO` has its own code.
+
 ## The runtime mirror
 
 The checkout lives inside the distro. A DSH profile can only link a Windows path,

package/docs/CONFIGURATION.md

@@ -14,6 +14,7 @@ are schema defaults, listed because they are the ones worth knowing.
 | `wsl-shell` | `distro` | `''` *(shipped)* | distro name; empty means WSL's default distro |
 | | `shell` | `''` | pin a shell inside the distro; empty means the user's login shell |
 | | `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 |
 | | `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 |
@@ -50,3 +51,10 @@ confinement. `sandboxMode` then reports `undefined`, and the tool layer tells th
 model that these operations have no sandbox. That is the documented opt-out; see
 [ARCHITECTURE.md](ARCHITECTURE.md#sandbox) for what the sandbox does and does not
 cover.
+
+## `wsl-shell-env`
+
+| Key | Default | Meaning |
+| --- | --- | --- |
+| `distro` | `''` | the distro the `DSH_WSL_*` facts describe |
+| `portsRefreshMs` | `10000` | how often the `DSH_WSL_PORTS` listening-port snapshot refreshes through the resident agent |

package/docs/LIMITATIONS.md

@@ -31,13 +31,18 @@ boundary; one that is not is a bug report waiting to happen.
   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.
-- `watch()` (file change monitoring) is not provided. Watching a 9p share is
-  unreliable, so the plugin refuses instead of arming it.
+- `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
+  older than the watcher's stamp (`cp -p`, `tar -x`) is not seen until something
+  else touches the tree. Watching a 9p share from the Windows side remains
+  unsupported — the loop runs where the kernel can actually report change.
 - `glob` and `grep` use the Windows-side ripgrep over the share: correct results, but
   not fast, and `.gitignore` is interpreted with Windows rules. `editText` reads the
   whole file into memory before writing it back.
-- The terminal belongs to the whole app, not to one session. A session opened on a
-  Windows folder still gets the distro terminal, starting in `/mnt/<drive>/...`, and
-  its shell menu is deliberately reduced to the one configured profile.
+- Terminal routing is per-session by workspace coordinates (`subprocess-wsl.hostSessions`,
+  default on): a WSL-folder session gets the distro shell, a Windows-folder session gets
+  `powershell.exe` in its own directory. The shell MENU remains the single configured
+  profile, and a directory-less launch still lands in the distro.
 - Terminal activity reporting stops at `wsl.exe`, so the controller never reclaims
   these terminals when they are idle.

package/docs/PARITY.md

@@ -0,0 +1,70 @@
+# Parity with VS Code Remote-WSL
+
+What parity means for this plugin, the seam contracts the plan was audited
+against, and the phase checklist. Every phase below ends with rows of this
+table ticked and this document updated in the same change.
+
+## What parity means here
+
+Remote-WSL's experience rests on one thing: a resident server inside the
+distro. Everything users love — native ext4 semantics, inotify, native
+`rg`, low latency — is a derivative. This plugin's 9p-UNC plus one-shot
+`wsl.exe` model can only approach it. The plan therefore lands a resident
+in-distro agent and migrates the `fs` and `shell` seams onto it, keeping the
+current paths as the documented fallback (`wsl.agent: 'off'` must equal
+today's behaviour byte for byte).
+
+Not applicable, recorded so the gap is a decision and not an omission:
+
+- IntelliSense, debuggers, the extension marketplace: editor features. The
+  DSH analogue is tool latency and correctness (Phases 1–3).
+- Settings Sync, Remote-SSH tunnel chaining, Codespaces: composition-layer
+  responsibilities, not this plugin's.
+
+## Contract audit (Phase 0)
+
+Findings from reading the harness packages inside the app bundle; each one
+shaped a phase of the plan.
+
+1. **`ctx.fs.watch` is a coarse invalidation callback, not an event stream.**
+   `FileSystem.watch(target, changed, signal)` (dsh-fs) resolves once
+   observation is active and returns an async close function; `changed` takes
+   no event payload. So the in-distro watcher does not need to classify
+   rename vs. modify — any inotify (or polling) hit may call `changed()`.
+   Phase 1's watcher is accordingly simpler than planned.
+2. **Search is not an `fs` seam.** `dsh-tool-fs-search` spawns the PACKAGED
+   ripgrep binary (`@vscode/ripgrep`) through `ctx.subprocess` with a plain
+   argv vector and no shell; raw stdout is parsed by the tool. The correct
+   interception point is therefore the plugin's `subprocess-wsl` subclass:
+   when `argv[0]` is the packaged rg binary and the spec's cwd is inside this
+   distro's share, rewrite the spawn to run a distro-side `rg` (falling back
+   to `grep -rE` + `find` when absent) with identical stdout conventions.
+   Under the agent, that exec rides the agent's `exec` capability.
+3. **`dsh-fs-local` watches with chokidar over the share** — the behaviour
+   this plugin replaces: chokidar on 9p is the unreliability that made
+   `WslFileSystem.watch` refuse. The in-distro watcher replaces it wholesale.
+4. **`dsh-bash-local` carries the timeout machinery** (`clampTimeout`,
+   `deadline`, `timeoutOf`, `BASH_TIMEOUT`), which the WSL executor already
+   inherits. Migrating exec onto the agent keeps that shape: the deadline
+   arms on the host as today, but the SIGTERM→SIGKILL grace fires inside the
+   distro via the agent instead of against the Windows process tree.
+
+## Phase checklist
+
+| Phase | Deliverable | Parity row |
+| --- | --- | --- |
+| 0 | This document; contract audit above | baseline recorded |
+| 1 | `lib/agent/` + `wsl-agent` resident process: NDJSON-over-stdio protocol, capability handshake, lazy start, idle shutdown, crash-rebuild-once, permanent fallback | resident server |
+| 2 | real `watch()` SHIPPED (in-distro poll, `lib/watcher.js`); the native-ext4 migration of the remaining fs operations (and with it the workaround deletions) continues alongside Phase 3 | native file semantics, inotify — watch + publication done |
+| 3 | DONE — `WslShellExecutor` exec via agent; in-distro TERM→KILL; handle shape preserved (deviation: no streaming, no spill files) | native exec latency |
+| 4 | DONE (except the agent/plugin version handshake, which lands with the first agent-behaviour change after release) — `npm run bootstrap`, family-aware install command, `SANDBOX_UNAVAILABLE` names it | open-and-it-works |
+| 5 | DONE (routing half) — per-session routing by workspace coordinates (`terminal-route.js`, `hostSessions`); activity-based idle reclaim of distro terminals remains a documented limitation (PTY activity stops at `wsl.exe`) | terminal per window/session — routing done |
+| 6 | DONE — `DSH_WSL_PORTS` (agent-scanned `/proc/net/tcp{,6}`, timer-refreshed); localhost reachability (WSL2 localhost forwarding is platform behaviour) documented in README | port forwarding visibility |
+| 7 | DONE — recipes section in both READMEs: credential sharing, `/mnt/c` guidance, `WSLENV` policy | developer-loop odds and ends |
+
+## Fallback invariant
+
+Every phase must keep `wsl.agent: 'off'` (and, per capability, any runtime
+fallback) behaviourally identical to the pre-phase release. Probes assert
+this: `agent.sh` runs the same operation with the agent off and on and
+compares outcomes, not internals.

package/docs/README.zh.md

@@ -6,7 +6,7 @@
 [![npm](https://img.shields.io/npm/v/dsh-plugin-wsl-env)](https://www.npmjs.com/package/dsh-plugin-wsl-env)
 [![license](https://img.shields.io/npm/l/dsh-plugin-wsl-env)](../LICENSE)
 
-这个插件让 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 把 WSL 发行版当作工作环境：命令在发行版里执行，模型的文件工具读写发行版里的真实文件，文件夹选择器可以直接打开发行版目录，GUI 终端也开在发行版里。
+这个插件让 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 把 WSL 子系统当作工作环境：命令在子系统里执行，模型的文件工具读写子系统里的真实文件，文件夹选择器可以直接打开子系统目录，GUI 终端也开在子系统里。
 
 **只支持 Windows + WSL2。** 安装只需一条命令，插件自身没有依赖。环境按会话生效：打开 Windows 文件夹的会话继续使用原来的 Windows 环境。
 
@@ -26,9 +26,9 @@ dsh --profile wsl                                  # 4. 启动
 
 第 3 步应该打印出名为 `# == dsh-plugin-wsl-env` 的层，并且 `- id: terminal-controller` 上应出现 `shell: { path: wsl.exe, name: WSL }`。这个包是 DSH bundle，所以第 2 步会把 [`cordis.patch.yml`](../cordis.patch.yml) 作为配置层施加进去，没有任何需要手工合并的补丁。
 
-然后在 GUI 里打开 `\\wsl.localhost\<发行版>\...` 下的文件夹。选择器会在根一级列出每个已安装的发行版，**New terminal** 会在发行版里打开 shell。
+然后在 GUI 里打开 `\\wsl.localhost\<子系统>\...` 下的文件夹。选择器会在根一级列出每个已安装的子系统，**New terminal** 会在子系统里打开 shell。
 
-还需要在发行版里安装 **bubblewrap**：`sudo apt install bubblewrap`。没有它每条命令都会失败关闭，见[沙箱](#沙箱)。
+还需要在子系统里安装 **bubblewrap**：运行 `npm run bootstrap -- <子系统> --install`（只读检测去掉 `--install`），或直接执行 `wsl.exe -d <子系统> -u root -- apt-get install -y bubblewrap`。没有它每条命令都会失败关闭，见[沙箱](#沙箱)。
 
 卸载：`dsh plugin --profile wsl remove dsh-plugin-wsl-env`。升级：再执行一次同样的 `add` 命令。
 
@@ -36,12 +36,13 @@ dsh --profile wsl                                  # 4. 启动
 
 ## 使用
 
-把 `\\wsl.localhost\ubuntu\home\you\project` 作为工作区打开，然后问模型"我在什么内核上，`/etc/os-release` 里有什么"。它会在发行版里执行 `uname -r` 并读取该文件，不经过 `/mnt/c`，也不复制文件。
+把 `\\wsl.localhost\ubuntu\home\you\project` 作为工作区打开，然后问模型"我在什么内核上，`/etc/os-release` 里有什么"。它会在子系统里执行 `uname -r` 并读取该文件，不经过 `/mnt/c`，也不复制文件。
 
-- **发行版文件夹自动获得发行版环境。** 创建会话时就会绑定 `wsl` preset，所以第一次工具调用就已经正确。
-- **命令**以 `wsl.exe -d <发行版> --cd <Linux 目录> --exec <你的登录 shell> -lc <命令>` 执行，所以你的 `PATH`、`nvm`、`cargo`、`pyenv` 和 rc 配置都生效。shell 不是硬编码的 bash。
-- **文件就是发行版的真实文件。** `/home/you/x` 与 `\\wsl.localhost\ubuntu\home\you\x` 是同一个文件，`/mnt/c/...` 通向 Windows 磁盘。
-- **终端**（右侧栏 → *New terminal*）在发行版里打开会话目录下的 shell。
+- **子系统文件夹自动获得子系统环境。** 创建会话时就会绑定 `wsl` preset，所以第一次工具调用就已经正确。
+- **命令**以 `wsl.exe -d <子系统> --cd <Linux 目录> --exec <你的登录 shell> -lc <命令>` 执行，所以你的 `PATH`、`nvm`、`cargo`、`pyenv` 和 rc 配置都生效。shell 不是硬编码的 bash。
+- **文件就是子系统的真实文件。** `/home/you/x` 与 `\\wsl.localhost\ubuntu\home\you\x` 是同一个文件，`/mnt/c/...` 通向 Windows 磁盘。
+- **终端**（右侧栏 → *New terminal*）在子系统里打开会话目录下的 shell。
+- **端口可见性**：子系统里监听中的端口经 `DSH_WSL_PORTS` 暴露给模型（约每 10 秒刷新）；子系统内启动的 dev server 可由模型直接告知确切 URL（WSL2 的 localhost 转发是平台行为，Windows 侧直接可达）。
 - **模型能看到自己的 shell 环境。** 插件向受管的 `DSH_*` 命名空间注册 `DSH_WSL_DISTRO`、`DSH_WSL_SHELL` 和 `DSH_WSL_HOME`。
 - **权限与 Linux 主机一致。** 权限选择器在 `read-only`、`workspace-write`（默认）和 `danger-full-access` 之间切换。被拒绝的命令或写入会带回"放宽权限"的提议；批准后，这一次调用不加沙箱执行。
 
@@ -51,44 +52,52 @@ dsh --profile wsl                                  # 4. 启动
 
 | 行 | 键 | 默认值 | 说明 |
 |---|---|---|---|
-| `wsl-shell` | `distro` | `''` | 发行版名；空表示用 WSL 的默认发行版 |
+| `wsl-shell` | `distro` | `''` | 子系统名；空表示用 WSL 的默认子系统 |
 | | `sandbox` | `true` | 用 `bubblewrap` 约束命令；`false` 表示不用沙箱 |
 | `wsl-fs` | `distro` | `''` | 同上 |
-| | `restrictToDistro` | `true` | 拒绝指向**其它发行版**共享的路径；`/mnt/c` 属于本发行版内部，不受影响。拒绝码为 `FS_OUTSIDE_DISTRO`，它不是沙箱拒绝，放宽权限也无法解除 |
+| | `restrictToDistro` | `true` | 拒绝指向**其它子系统**共享的路径；`/mnt/c` 属于本子系统内部，不受影响。拒绝码为 `FS_OUTSIDE_DISTRO`，它不是沙箱拒绝，放宽权限也无法解除 |
 | | `sandbox` | `true` | 写入时按策略检查 `writeText` 和 `editText` |
 | `directory-picker-wsl` | `includeHostHome` | `true` | 同时列出 Windows 家目录 |
-| `subprocess-wsl` | `distro` | `''` | GUI 终端开在哪个发行版 |
+| `subprocess-wsl` | `distro` | `''` | GUI 终端开在哪个子系统 |
 
 [`cordis.patch.yml`](../cordis.patch.yml) 是每个随包值的注释参考。[docs/CONFIGURATION.md](CONFIGURATION.md) 列出其余键，包括 `shell`、`loginShell`、`cwd`、`timeoutMs`、`resolveSymlinks`、`preferredDistro` 和 `maxEntries`；[examples/profile.cordis.patch.yml](../examples/profile.cordis.patch.yml) 是一份可照抄的本机层。
 
 ## 沙箱
 
-命令由**发行版内的 `bubblewrap`** 约束，文件写入按同一份策略检查。Windows ACL 沙箱在这里用不了：它的受限令牌完全到不了 WSL。
+命令由**子系统内的 `bubblewrap`** 约束，文件写入按同一份策略检查。Windows ACL 沙箱在这里用不了：它的受限令牌完全到不了 WSL。
 
-| 模式 | 发行版里的命令可以做什么 |
+| 模式 | 子系统里的命令可以做什么 |
 |---|---|
-| `read-only` | 整个发行版只读；`/dev` 是新建的可写挂载（`/dev/null` 与 `/dev/shm` 可用），其余不可写 |
+| `read-only` | 整个子系统只读；`/dev` 是新建的可写挂载（`/dev/null` 与 `/dev/shm` 可用），其余不可写 |
 | `workspace-write` | 在上一行基础上，把会话工作区绑定为可写，并把 `/tmp` 挂成临时目录 |
 | `danger-full-access` | 不加沙箱；用于批准后的放宽权限请求 |
 
 **bubblewrap 是必需项，而且失败是关闭的。** 没有它时，每条受限命令都报 `SANDBOX_UNAVAILABLE`，而不是不受约束地运行。要退出约束就在任一 provider 上设 `sandbox: false`，工具层会如实告诉模型这些操作没有沙箱。
 
-**上报的强制程度是 `partial` 而不是 `full`。** 发行版里的进程仍可经 WSL interop 执行 Windows 程序（例如 `/mnt/c/.../*.exe`），bubblewrap 管不到它。`npm run probe:sandbox` 会在你的机器上演示这条边界。
+**上报的强制程度是 `partial` 而不是 `full`。** 子系统里的进程仍可经 WSL interop 执行 Windows 程序（例如 `/mnt/c/.../*.exe`），bubblewrap 管不到它。`npm run probe:sandbox` 会在你的机器上演示这条边界。
 
 设计见 [docs/ARCHITECTURE.md](ARCHITECTURE.md#sandbox)，插件不做的事情见 [docs/LIMITATIONS.md](LIMITATIONS.md)。
 
+## 配方
+
+- **Git 凭据共享**：让子系统里的 git 使用 Windows 侧的 Git Credential Manager，避免每次输密码：
+  `git config --global credential.helper "/mnt/c/Program\ Files/Git/mingw64/bin/git-credential-manager.exe"`
+  （路径按 Windows 侧 Git 的安装位置调整；WSL2 的 localhost 转发是平台行为，子系统内监听的端口 Windows 直接可达。）
+- **路径与性能**：模型看到并操作的是子系统内的 Linux 路径（`/home/...`），写入子系统自身的 ext4；`/mnt/c` 通向 Windows 磁盘但走 9p，大批量小文件操作明显慢——重 IO 的项目请放在子系统文件系统内。`npm run bootstrap -- <子系统>` 会一并报告 ripgrep / inotifywait（搜索与监视的后端）是否就位。
+- **WSLENV 透传**：WSL 只导入 `WSLENV` 中列出的变量。本插件按前缀放行托管的 `DSH_*` 命名空间，其中带 Windows 路径的两个（`DSH_HOME`、`DSH_PROFILE_DIR`）加 `/p` 让 WSL 翻译成 `/mnt/c/...`。`PATH` 故意不透传——否则 Windows 的 PATH 会覆盖子系统自身的 PATH。
+
 ## 常见问题
 
 | 现象 | 原因 | 处理 |
 |---|---|---|
-| 每条命令都报 `SANDBOX_UNAVAILABLE` | 发行版里没有 `bubblewrap` | 执行 `sudo apt install bubblewrap`，或在两个 provider 上都设 `sandbox: false` |
+| 每条命令都报 `SANDBOX_UNAVAILABLE` | 子系统里没有 `bubblewrap` | 执行 `npm run bootstrap -- <子系统> --install`，或在两个 provider 上都设 `sandbox: false` |
 | 命令或写入在会话目录之外被拒绝 | `workspace-write` 的预期行为 | 接受工具给出的放宽权限提示，或把会话直接开在需要的目录上 |
 | 连工作区内的写入也被拒绝 | 会处在 `read-only` 模式 | 切换权限选择器 |
 | `dsh plugin add` 提示"没有激活任何层" | 依赖之前已经装过，`add` 没有需要记录的内容 | 先执行 `dsh plugin --profile wsl remove dsh-plugin-wsl-env`，再装一次 |
 | 终端打开后仍然是 `cmd.exe` | 这一层里的 `terminal-controller` 行没有生效 | 用 `dsh --profile wsl --dump-config` 确认能看到 `shell: { path: wsl.exe, name: WSL }` |
 | 改了 `lib/` 但不生效 | ES module 缓存 | 重启应用 |
-| 用 `link:\\wsl.localhost\...` 安装后符号链接是坏的 | pnpm 无法链接 UNC 路径 | 改成链接 Windows 路径；在发行版内开发时用运行时镜像，见[开发](#开发) |
-| `glob`/`grep` 很慢 | Windows 侧的 ripgrep 在 9p 共享上遍历 | 属于预期，收窄搜索路径，或改用 `bash` 调用发行版内的工具 |
+| 用 `link:\\wsl.localhost\...` 安装后符号链接是坏的 | pnpm 无法链接 UNC 路径 | 改成链接 Windows 路径；在子系统内开发时用运行时镜像，见[开发](#开发) |
+| `glob`/`grep` 很慢 | Windows 侧的 ripgrep 在 9p 共享上遍历 | 属于预期，收窄搜索路径，或改用 `bash` 调用子系统内的工具 |
 | 终端活动显示 `unknown` | 官方 shell 集成只对 POSIX 主机上直接启动的 `bash`/`zsh` 生效 | 关闭标签页以释放进程；空闲回收不会对它触发 |
 | 结果里出现 `FS_*` 码 | 码本身说明了是谁拒绝的、以及怎样解除 | 见 [docs/ARCHITECTURE.md](ARCHITECTURE.md#error-codes) 的错误码表 |
 
@@ -97,8 +106,8 @@ dsh --profile wsl                                  # 4. 启动
 ```bash
 npm test                     # 风格与打包检查、语法检查、单元测试
 npm run test:coverage        # 带覆盖率阈值的单元测试（需 Node 22.8+）
-npm run probe:sandbox        # 在发行版里实测 bubblewrap 能约束什么、不能约束什么
-npm run probe                # 文件系统探针，需要真实发行版（仅 Windows + WSL）
+npm run probe:sandbox        # 在子系统里实测 bubblewrap 能约束什么、不能约束什么
+npm run probe                # 文件系统探针，需要真实子系统（仅 Windows + WSL）
 npm run probe:sandbox-shell  # 启动真实 harness，驱动受限执行器
 npm run probe:terminal       # 通过终端 provider 打开一个 PTY
 npm run probe:missing-wsl    # 启动一个 wslPath 无法启动的 profile（仅 Windows + WSL）

package/lib/agent-errors.js

@@ -0,0 +1,33 @@
+/**
+ * The error a {@link WslAgent} rejects with when the resident process is out
+ * for this host process — the executor's cue to fall back to the one-shot
+ * `wsl.exe` path. Deliberately its own class: callers must not confuse
+ * "the agent cannot serve" with a failure of the command itself.
+ *
+ * @module dsh-plugin-wsl/agent-errors
+ */
+export class AgentUnavailableError extends Error {
+  /**
+   * @param {string} message - why the agent is out, for the log.
+   */
+  constructor(message) {
+    super(message);
+    this.name = "AgentUnavailableError";
+  }
+}
+
+/**
+ * The request's workdir could not be entered inside the distro. Carries the
+ * Linux path so a caller can synthesize the same diagnostic the one-shot
+ * `wsl.exe` path produces from the relay's `chdir(...) failed` text.
+ */
+export class CwdError extends Error {
+  /**
+   * @param {string} linuxPath - the path that could not be entered.
+   */
+  constructor(linuxPath) {
+    super(`could not enter working directory "${linuxPath}"`);
+    this.name = "CwdError";
+    this.linuxPath = linuxPath;
+  }
+}