dsh-plugin-wsl-env 0.3.0 → 0.5.0

package/CHANGELOG.md

@@ -12,6 +12,181 @@ reference below points at that record's numbering.
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-10-04
+
+One theme: telling the truth, in the reader's language. The Plugins page now
+renders localized titles and descriptions for every row this bundle owns, the
+README runs shallow to deep and carries an Architecture section in both
+languages, the tab-title limitation is documented with its upstream proposal,
+and the statements `hostSessions` had already falsified are gone.
+
+### Added
+
+- **The plugin page can speak the bundle's language.** The bundle and each of
+  its four inserted rows (`subprocess`, `picker`, `shell-env`, `auto-preset`)
+  now export localized display metadata — `locale/<lang>.json` with a
+  `meta.title` / `meta.description` pair, exposed through `exports` per row —
+  which is what the Plugins page reads before falling back to a package.json
+  `description`. A Chinese UI now renders Chinese titles and descriptions for
+  every row this package owns; previously the rows fell back to raw module
+  specifiers (no description at all), and the two official rows it inserts
+  keep their upstream English text, which only upstream locale files can fix.
+- **docs/UPSTREAM-TERMINAL-TITLE.md — the upstream proposal behind a documented
+  limitation, posted as
+  [deepseek-ai/deepseek-harness#8769](https://github.com/deepseek-ai/deepseek-harness/discussions/8769).** `subprocess-wsl.hostSessions` routes a Windows-folder session's
+  terminal to `powershell.exe`, but the tab still reads `WSL`: the controller
+  titles a tab from the composition's single shell profile before the provider
+  is consulted, the terminal spawn spec carries no display name, and a plugin
+  cannot bridge the gap (a patch layer asserts rather than renames a row's
+  module, and disabling the `terminal-controller` row fails web boot — its id
+  is what the client's `webTerminals` mount waits behind). The doc records the
+  gap, the three closed escape hatches with the web-boot failure that closed
+  the second one live, and the smallest upstream change that would close it.
+  LIMITATIONS.md gains the matching limitation paragraph with the workarounds
+  that do work: double-click rename, and a user-layer `shellCandidates` entry
+  whose manual selection is titled after itself.
+- **The README carries an Architecture section** (both languages): the two
+  mount heights — composition-level `subprocess-wsl` and the preset realm's
+  `wsl-shell` / `wsl-fs` — with the per-session terminal routing and the
+  command and file execution paths in one diagram and two paragraphs.
+  [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) remains the full reference.
+
+### Fixed
+
+- Stale statements that `hostSessions` had already falsified were corrected in
+  place: `cordis.patch.yml`'s consequence note and ARCHITECTURE.md's "the
+  terminal follows the app configuration" paragraph still described the
+  pre-routing behaviour.
+
+## [0.4.0] - 2026-10-03
+
+One theme: the enterprise review's remediation cycle completes. The
+security-decision layer gains its own peer-free module and unit tests, the
+coverage gate measures every unit file again, the fallback invariant is probed
+for real, and the file tools pick up the audit's fixes — a killed write no
+longer strands state, large reads stream instead of staging, `/tmp` writes
+land where readers read, cross-distro workdirs are refused, the resident's
+Windows environment is pinned, and `maskWindowsDrive` offers the interop
+mitigation.
+
+### Added
+
+- **The filesystem provider's policy decisions are a peer-free module with
+  their own unit tests.** The security-decision layer — which paths are
+  refused for naming another distro, which mode denies a mutation outright,
+  which write guards refuse which intents, how a substrate failure maps onto
+  the surfaced refusal, and whether a mutation routes to the confined
+  resident — used to live inline in `lib/index.js`, a file no unit test can
+  import. It is now `lib/fs-decisions.js` (pure in, refusal descriptor out,
+  byte-identical messages), with `test/fs-decisions.test.mjs` covering every
+  branch, and `lib/index.js` delegating at one `FsError` choke point.
+
+### Fixed
+
+- **The fallback invariant is now probed, not just promised.** PARITY.md's
+  hard rule — "`agent: false` must behave like the pre-agent release" — cited
+  a probe leg that did not exist, and spelled the key as `wsl.agent: 'off'`
+  when it is a boolean. `test/probe/agent.sh` now runs the same operations
+  through the resident AND through the one-shot `wsl.exe` path and compares
+  outcomes: exit code and stdout bytes (including `$`-metacharacters), stderr
+  and working directory, and NUL/CRLF binary safety. All three legs pass
+  against a real distro; the doc now names the key correctly and describes
+  what the probe actually compares.
+
+- **The coverage gate measures every unit file again.** `test:coverage` listed
+  six of the sixteen test files — the thresholds (85/85/70) were met by the
+  narrowed set while the full suite sat at 82.45% branches, so branch
+  regressions anywhere outside the six were invisible to the gate that claimed
+  to guard them. The gate now runs the whole unit suite (95.83% lines / 85.95%
+  branches / 91.01% functions), which got there the honest way: new tests for
+  the seams the audit found dark — the deny-dialect classification,
+  aborted-signal mapping, the transport env pin, handshake mismatch, protocol
+  garbage, cwd rejections, pre-aborted signals, idle retirement, mid-flight
+  over-cap buffers, failed rebuilds, watcher teardown and error paths, the
+  cross-distro workdir predicate, staging sweeps, setuid publication, and the
+  real-`/tmp` consistency the file tools now have.
+
+- **Reading a large file no longer copies its remainder to a temp file for
+  every window.** `fs_read` staged `tail -c +offset` to disk before `head`
+  took the requested bytes — so a full read of a 1 GB file performed ~1000
+  window round trips AND ~500 GB of aggregate temp-file writes inside the
+  distro, and a window that took over 30 seconds died as an opaque
+  "distro I/O failure". The remainder now streams through a `tail | head`
+  pipe (the request's own bound is the only staging), read failures still
+  classify through the same stderr dialect, and windowed reads are verified
+  byte-exact including the final partial window.
+- **A request the transport cannot deliver now fails its caller instead of
+  stranding it.** `writeLines` used to drop a frame silently when the
+  `wsl.exe` process was gone (a thin race between exit handling and the next
+  request), leaving a pending entry nothing would ever answer — the caller
+  waited forever when it had no timeout, and the watchdog had no process
+  left to kill. An undeliverable frame now rejects with
+  `AgentUnavailableError` ("the agent exited before the request could be
+  sent; it never ran"), the rebuild relay fails undeliverable re-sends the
+  same way, and `close()` no longer writes `SHUTDOWN` into an ended stdin
+  (whose async write-after-end error could crash the process during its own
+  shutdown).
+
+- **A confined write to `/tmp` now lands in the distro's real `/tmp`, where
+  every reader reads.** The fence grants `/tmp` as a writable root, but the
+  confined resident's profile mounted an ephemeral tmpfs over it — so the
+  write reported success into a private tmpfs, the read tools (unconfined)
+  could not see it, the post-write stat produced a `missing:` version that
+  made the next edit fail with `FS_STALE_VERSION`, and the file evaporated
+  when the resident retired. The file-writes resident's profile now binds the
+  real `/tmp` read-write (`realTmp`, on by default for the confined factory):
+  the write lands where the fence said it would, reads and edits agree, and
+  user terminals see the file. Commands keep their ephemeral per-run tmpfs —
+  the fresh-temp-area property (and its anti-poisoning guarantee) is
+  unchanged, so a command still cannot see files the write tools placed in
+  `/tmp` — the documented command-vs-tools split, now safe in both
+  directions. Verified live: confined write → plain read returns the content;
+  a confined `cat` still reports it absent, as documented.
+
+- **A killed write no longer leaves its staging directory in your files.** A
+  `KILL`/`SIGTERM` mid-write could not be trapped, so the private 0700
+  staging dir (`.<name>.<pid>.<rand>.tmpdir`) sat in the target's own
+  directory forever — and listings showed the debris to the model. The EXIT
+  trap now removes the in-flight staging along with the agent's temp dir, and
+  each write sweeps the target directory's leftovers whose creating agent's
+  PID (it rides the name) is no longer running — a live agent's staging is
+  left alone, PID reuse included.
+- **A write to a typo'd path refuses instead of materializing the chain.**
+  The staging `mkdir -p` silently created every missing parent directory and
+  reported success, where the peer's Node-fs publication fails `ENOENT` —
+  masking model errors as wins. Parents are no longer created: the refusal is
+  `FS_NOT_FOUND`, an existing directory stays fine, and a concurrent creator
+  of the directory still wins.
+- **Setuid, setgid and sticky bits survive an overwrite or edit.** The mode
+  was masked to `0o777` at the stat parse and again at the write, so a
+  `4755` binary became `755` and a `1777` directory file lost its sticky bit
+  — while LIMITATIONS claimed the bits were kept. The full mode now rides
+  stat and write end-to-end (`0o7777`), matching the share substrate's
+  `chmod --reference` behaviour.
+
+- **A shell command whose workdir names another WSL distro is refused, where
+  it used to run in the pinned distro against whatever tree shares the path.**
+  `toLinuxPath` strips a `\\wsl.localhost\<name>\…` UNC's distro name, and the
+  shell executor never compared it — so a `debian` workspace's commands ran
+  inside the pinned `ubuntu`, silently, while the fs side refused the same
+  workspace with `FS_OUTSIDE_DISTRO` ("open a session in that distro" — which
+  the user had done). The shell now refuses with the fs side's wording, and
+  the shell-env facts stay silent for a foreign-distro session instead of
+  presenting another distro's home and shell as this session's.
+
+- **The resident agent no longer inherits the Windows environment's WSLENV
+  forwarding.** Spawned bare, `wsl.exe` carried this process's whole
+  environment with it, and whatever the user's `WSLENV` names — dev machines
+  routinely route secrets (`GITHUB_TOKEN/u` is the documented example) — was
+  forwarded into the distro, where every model command inherited it. The
+  transport's Windows env is now pinned: the essentials `wsl.exe` itself
+  needs, the managed `DSH_*` facts, `WSL_UTF8=1`, and a `WSLENV` that names
+  only the managed entries with their original flags. Verified live: a secret
+  injected on the Windows side with a forwarding flag appears zero times in
+  the distro environment. `forwardEnv` remains one-shot-only today — the
+  resident path never forwarded it, and the pin keeps that posture instead of
+  widening it silently.
+
 ### Added
 
 - **`maskWindowsDrive` on `wsl-shell` and `wsl-fs`** — the mitigation knob for

package/README.md

@@ -10,7 +10,7 @@ This plugin lets [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harn
 
 **Windows + WSL2 only.** One install command, no dependencies of its own. The environment applies per session, so a session on a Windows folder keeps its normal Windows environment.
 
-[Install](#install) · [Using it](#using-it) · [Configure](#configure) · [Sandbox](#sandbox) ·
+[Install](#install) · [Using it](#using-it) · [Configure](#configure) · [Recipes](#recipes) · [Architecture](#architecture) · [Sandbox](#sandbox) ·
 [Troubleshooting](#troubleshooting) · [Development](#development) · [Documentation](#documentation)
 
 ## Install
@@ -42,6 +42,7 @@ Open `\\wsl.localhost\ubuntu\home\you\project` as the workspace, then ask the mo
 - **Commands** run as `wsl.exe -d <distro> --cd <linux dir> --exec <your login shell> -lc <command>`, so your `PATH`, `nvm`, `cargo`, `pyenv` and rc files apply. The shell is not hardcoded to bash.
 - **Files are the distro's real files.** `/home/you/x` and `\\wsl.localhost\ubuntu\home\you\x` are the same file, and `/mnt/c/...` reaches the Windows disk.
 - **The terminal** (right sidebar, then *New terminal*) opens a shell inside the distro, in the session's folder.
+- **Port visibility.** The model sees which ports have a listener inside the distro (`DSH_WSL_PORTS`, refreshed about every 10 s), so it can hand you the exact URL of a dev server it just started; WSL2's localhost forwarding makes it reachable from Windows directly.
 - **The model sees its shell environment.** The plugin registers `DSH_WSL_DISTRO`, `DSH_WSL_SHELL` and `DSH_WSL_HOME` in the managed `DSH_*` namespace.
 - **Permissions work as on a Linux host.** The Permissions selector switches between `read-only`, `workspace-write` (the default) and `danger-full-access`. A refused command or write comes back with an offer to run it with wider permissions; if you approve, that one call runs without the sandbox.
 
@@ -62,22 +63,6 @@ Override a row by id in `$DSH_HOME/profiles/<name>/cordis.patch.yml`. The keys w
 
 [`cordis.patch.yml`](cordis.patch.yml) is the commented reference for every shipped value. [docs/CONFIGURATION.md](docs/CONFIGURATION.md) lists the rest, including `shell`, `loginShell`, `cwd`, `timeoutMs`, `resolveSymlinks`, `preferredDistro` and `maxEntries`; [examples/profile.cordis.patch.yml](examples/profile.cordis.patch.yml) is a machine-local layer to copy from.
 
-## Sandbox
-
-Commands are confined by `bubblewrap` inside the distro, and file writes are checked against the same policy. The Windows ACL sandbox cannot be used here: its restricted token cannot reach WSL at all.
-
-| Mode | What a command inside the distro can do |
-|---|---|
-| `read-only` | read the whole distro; a fresh `/dev` is mounted writable, so `/dev/null` and `/dev/shm` work, and nothing else does |
-| `workspace-write` | the above, plus the session workspace is writable and `/tmp` is a temporary mount |
-| `danger-full-access` | no sandbox; used for an approved wider-permission request |
-
-**`bubblewrap` is required, and the failure is closed.** Without it every confined command reports `SANDBOX_UNAVAILABLE` instead of running unconfined. Set `sandbox: false` on either provider to opt out; the tool layer then tells the model these operations have no sandbox.
-
-**The reported enforcement is `partial`, not `full`.** A process inside the distro can still run a Windows program through WSL interop, for example `/mnt/c/.../*.exe`, and bubblewrap does not govern it. `npm run probe:sandbox` demonstrates the boundary on your machine.
-
-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
@@ -95,6 +80,44 @@ See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md#sandbox) for the design, and [do
   two Windows-path ones (`DSH_HOME`, `DSH_PROFILE_DIR`) with `/p`. `PATH` is
   deliberately never forwarded — it would shadow the distro's own PATH.
 
+## Architecture
+
+One DSH process serves both kinds of session at once — a workspace on a Windows folder, and a workspace inside the distro — because its providers mount at two levels:
+
+```text
+composition (app level, one per process)
+├─ subprocess-wsl        the GUI terminal's execution world
+│                          WSL-folder session     → the distro shell, in the session's Linux directory
+│                          Windows-folder session → powershell.exe, in the session's Windows directory
+├─ directory-picker-wsl  installed distros listed beside the Windows home
+├─ wsl-shell-env         the DSH_WSL_DISTRO / _SHELL / _HOME / _PORTS facts the model sees
+└─ auto-preset           binds the wsl preset when a session opens a distro folder
+
+preset-wsl (the wsl agent preset; its services run in isolate realms)
+├─ wsl-shell   ctx.shell — wsl.exe --exec <login shell>, confined by bubblewrap inside the distro
+└─ wsl-fs      ctx.fs    — real distro files; agent substrate on ext4, or the 9p share
+```
+
+**Why two levels.** `wsl-shell` and `wsl-fs` live inside the `wsl` agent preset, which `auto-preset` binds whenever a session's workspace is inside the distro: a Windows-folder session keeps the stock providers, a distro session gets the WSL ones — the environment is a property of the session, not of the process. The terminal controller is the exception: it resolves its execution world through the root context, which never sees a preset's isolate realms, so `subprocess-wsl` sits at the composition level instead.
+
+**Commands and files.** A command runs as `wsl.exe -d <distro> --cd <linux dir> --exec <login shell> -lc <cmd>` inside a distro-side bubblewrap profile assembled with the same arguments as DSH's own Linux runner, so confinement semantics and error messages match a Linux host. The file tools read and write real distro files on one of two substrates: the default `agent` — a resident in-distro process, where reads, writes and identities run on ext4 with native symlinks and mode bits — or `share`, the opt-out: the Windows-side host stack over the 9p share. Both check writes against the same policy the command sandbox enforces.
+
+## Sandbox
+
+Commands are confined by `bubblewrap` inside the distro, and file writes are checked against the same policy. The Windows ACL sandbox cannot be used here: its restricted token cannot reach WSL at all.
+
+| Mode | What a command inside the distro can do |
+|---|---|
+| `read-only` | read the whole distro; a fresh `/dev` is mounted writable, so `/dev/null` and `/dev/shm` work, and nothing else does |
+| `workspace-write` | the above, plus the session workspace is writable and `/tmp` is a temporary mount |
+| `danger-full-access` | no sandbox; used for an approved wider-permission request |
+
+**`bubblewrap` is required, and it fails closed.** Without it every confined command reports `SANDBOX_UNAVAILABLE` instead of running unconfined. Set `sandbox: false` on either provider to opt out; the tool layer then tells the model these operations have no sandbox.
+
+**The reported enforcement is `partial`, not `full`.** A process inside the distro can still run a Windows program through WSL interop, for example `/mnt/c/.../*.exe`, and bubblewrap does not govern it. `npm run probe:sandbox` demonstrates the boundary on your machine.
+
+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.
+
 ## Troubleshooting
 
 | Symptom | Cause | Fix |

package/agent/wsl-agent.sh

@@ -57,11 +57,15 @@ 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.
@@ -256,18 +260,22 @@ fs_realpath() {
 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.
-  local p offset max rd err
+  # 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
-  rd="$TMPDIR_AGENT/read"
-  tail -c +"$(( offset + 1 ))" -- "$p" >"$rd" 2>"$ERR_FILE" || {
+  : >"$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"
-  }
-  head -c "$max" -- "$rd"
+  fi
 }
 
 norm_time() {
@@ -299,6 +307,30 @@ fs_version() {
   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
@@ -315,10 +347,21 @@ fs_write() {
   dir=$(dirname -- "$path")
   base=$(basename -- "$path")
   [ -n "$base" ] && [ "$base" != "/" ] || fs_fail notfound "empty file name"
-  mkdir -p -- "$dir" 2>"$ERR_FILE" || {
-    err=$(cat "$ERR_FILE")
-    fs_fail "$(fs_classify "$err")" "$err"
-  }
+  # 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" || {
@@ -327,12 +370,13 @@ fs_write() {
     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 || {
-    rm -rf -- "$staging"
+    drop_staging
     fs_fail io "cannot stage content"
   }
   chmod 600 -- "$tmp"
@@ -340,7 +384,7 @@ fs_write() {
   if [ "$mode" != "-" ]; then
     chmod "$mode" -- "$tmp" 2>"$ERR_FILE" || {
       err=$(cat "$ERR_FILE")
-      rm -rf -- "$staging"
+      drop_staging
       fs_fail io "$err"
     }
   fi
@@ -351,7 +395,7 @@ fs_write() {
     # trips the stat/find skew a list-derived version would.
     version=$(fs_version "$path")
     if [ "$version" != "$expected" ]; then
-      rm -rf -- "$staging"
+      drop_staging
       if [ -n "$version" ]; then
         fs_fail stale "cannot write \"$path\": file changed since it was read"
       fi
@@ -363,12 +407,12 @@ fs_write() {
     # 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
-      rm -rf -- "$staging"
+      drop_staging
       fs_fail exists "cannot write \"$path\": it already exists"
     fi
     ln -- "$tmp" "$path" 2>"$ERR_FILE" || {
       err=$(cat "$ERR_FILE")
-      rm -rf -- "$staging"
+      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"
@@ -379,17 +423,17 @@ fs_write() {
       # 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"
-      rm -rf -- "$staging"
+      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")
-      rm -rf -- "$staging"
+      drop_staging
       fs_fail "$(fs_classify "$err")" "$err"
     }
   fi
-  rm -rf -- "$staging"
+  drop_staging
 }
 
 fs_dispatch() {

package/cordis.patch.yml

@@ -43,10 +43,12 @@
 #      directory, so offering host executables there would advertise shells this
 #      terminal never starts.
 #
-# Consequence: the terminal follows the composition, not the Session. A Session
-# whose workspace is a Windows folder gets the same distro terminal, started in
-# that folder as `/mnt/<drive>/…`. That is the honest limit of a per-session
-# execution world that no Session identity reaches.
+# Consequence: a terminal's EXECUTION WORLD follows the Session — a WSL-folder
+# session runs the distro's shell, a Windows-folder session runs PowerShell in
+# its own directory (`hostSessions` on `subprocess-wsl`) — while the shell menu
+# and the tab title stay the composition's single `WSL` profile, which no
+# Session identity reaches. The title that implies is documented in
+# docs/LIMITATIONS.md and bridged upstream in docs/UPSTREAM-TERMINAL-TITLE.md.
 # ═════════════════════════════════════════════════════════════════════════════
 - id: subprocess
   disabled: true

package/docs/ARCHITECTURE.md

@@ -74,9 +74,13 @@ So the layer disables the shipped `subprocess` row and inserts
 overrides `spawnTerminal` only. Ordinary `spawn()`, the host ripgrep search, the
 pwsh executor, and the LSP host reach the shipped implementation unchanged.
 
-The cost is that the terminal follows the app configuration, not the session. A
-session opened on a Windows folder still gets a distro terminal, started in
-`/mnt/<drive>/...`.
+The terminal's execution world follows the session (`hostSessions`, default on):
+a WSL-folder session runs the distro shell, a Windows-folder session runs
+`powershell.exe` in its own directory. What still follows the app configuration
+is the shell menu and the tab title, both derived from the composition's single
+`WSL` shell profile — so a host session's tab reads `WSL` over a PowerShell
+process. See [LIMITATIONS.md](LIMITATIONS.md) and
+[UPSTREAM-TERMINAL-TITLE.md](UPSTREAM-TERMINAL-TITLE.md).
 
 ## Path coordinates
 

package/docs/CONFIGURATION.md

@@ -32,6 +32,7 @@ are schema defaults, listed because they are the ones worth knowing.
 | `subprocess-wsl` | `distro` | `''` *(shipped)* | which distro the GUI terminal opens in |
 | | `shell` | `''` | pin a shell; empty lets `wsl.exe` decide |
 | | `loginShell` | `true` | whether a pinned shell uses login semantics |
+| | `hostSessions` | `true` | give a session opened on a Windows folder a host `powershell.exe` in its own directory instead of the distro shell at `/mnt/<drive>/…`; `false` restores the composition-owned distro terminal for every session |
 
 You can override the other keys in the same way; they keep their defaults. Those are
 `wslPath`, `hostCwd` and `forwardEnv` on the shell and terminal rows,

package/docs/LIMITATIONS.md

@@ -22,6 +22,9 @@ host stack over the distro's 9p share. What differs:
   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
@@ -90,7 +93,10 @@ Everything below applies to the share substrate unless it says otherwise.
 - 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
@@ -104,5 +110,15 @@ Everything below applies to the share substrate unless it says otherwise.
   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.
+- A host session's TAB TITLE still reads `WSL`, the composition's shell profile
+  name, over a PowerShell process. The controller titles a tab from that profile
+  before the provider rewrites the launch, and a plugin cannot correct it: a
+  patch layer asserts rather than renames a row's module, and the row's id is
+  load-bearing for the web composition (disabling it fails web boot with
+  "waiting for service: webTerminals"). The full account and the proposed
+  upstream change are in [UPSTREAM-TERMINAL-TITLE.md](UPSTREAM-TERMINAL-TITLE.md).
+  Meanwhile, double-click a tab's title to rename it, or add `shellCandidates`
+  to the `terminal-controller` row in your own profile layer — a manually
+  selected shell is titled after itself.
 - Terminal activity reporting stops at `wsl.exe`, so the controller never reclaims
   these terminals when they are idle.

package/docs/PARITY.md

@@ -11,7 +11,7 @@ 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
+current paths as the documented fallback (`wsl.agent: false` must equal
 today's behaviour byte for byte).
 
 Not applicable, recorded so the gap is a decision and not an omission:
@@ -64,7 +64,8 @@ shaped a phase of the plan.
 
 ## Fallback invariant
 
-Every phase must keep `wsl.agent: 'off'` (and, per capability, any runtime
+Every phase must keep `wsl.agent: false` (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.
+this: `agent.sh` runs the same operations through the resident and through
+the one-shot `wsl.exe` path and compares outcomes — exit code, stdout bytes,
+stderr bytes, working directory — not internals.

package/docs/README.zh.md

@@ -10,7 +10,7 @@
 
 **只支持 Windows + WSL2。** 安装只需一条命令，插件自身没有依赖。环境按会话生效：打开 Windows 文件夹的会话继续使用原来的 Windows 环境。
 
-[安装](#安装) · [使用](#使用) · [配置](#配置) · [沙箱](#沙箱) · [常见问题](#常见问题) ·
+[安装](#安装) · [使用](#使用) · [配置](#配置) · [配方](#配方) · [架构](#架构) · [沙箱](#沙箱) · [常见问题](#常见问题) ·
 [开发](#开发) · [文档](#文档)
 
 ## 安装
@@ -63,6 +63,36 @@ dsh --profile wsl                                  # 4. 启动
 
 [`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) 是一份可照抄的本机层。
 
+## 配方
+
+- **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。
+
+## 架构
+
+一个 DSH 进程同时服务两类会话：工作区开在 Windows 目录的，和工作区在子系统内的。能做到这一点，是因为 provider 分两层挂载：
+
+```text
+组合层（composition，每个进程一份）
+├─ subprocess-wsl        GUI 终端的执行世界
+│                          子系统目录会话   → 子系统 shell，落在会话的 Linux 目录
+│                          Windows 目录会话 → powershell.exe，落在会话自己的目录
+├─ directory-picker-wsl  在 Windows 家目录旁列出已安装的子系统
+├─ wsl-shell-env         向模型暴露 DSH_WSL_DISTRO / _SHELL / _HOME / _PORTS
+└─ auto-preset           会话打开子系统目录时自动绑定 wsl preset
+
+preset-wsl（wsl agent preset；其服务运行在 isolate realm 内）
+├─ wsl-shell   ctx.shell — wsl.exe --exec <登录 shell>，在子系统内经 bubblewrap 约束
+└─ wsl-fs      ctx.fs    — 子系统的真实文件；agent 基座落在 ext4，或走 9p 共享
+```
+
+**为什么分两层。** `wsl-shell` 和 `wsl-fs` 位于 `wsl` agent preset 内，`auto-preset` 在会话工作区位于子系统内时自动绑定它：Windows 目录的会话继续使用原生 provider，子系统会话拿到 WSL provider——环境是会话的属性，而不是进程的。终端控制器是例外：它经根上下文解析执行世界，永远看不到 preset 的 isolate realm，所以 `subprocess-wsl` 必须挂在组合层。
+
+**命令与文件。** 命令以 `wsl.exe -d <子系统> --cd <Linux 目录> --exec <登录 shell> -lc <命令>` 执行，外层是子系统内的 bubblewrap profile，参数与 DSH 自家 Linux runner 完全一致——约束语义与报错文案都和 Linux 主机相同。文件工具读写子系统的真实文件，基座二选一：默认 `agent`——常驻子系统内的进程，读写与路径解析落在 ext4，原生符号链接与权限位；或 `share`——退出项：Windows 侧宿主文件栈走 9p 共享。两个基座与命令沙箱使用同一份策略检查写入。
+
 ## 沙箱
 
 命令由**子系统内的 `bubblewrap`** 约束，文件写入按同一份策略检查。Windows ACL 沙箱在这里用不了：它的受限令牌完全到不了 WSL。
@@ -73,20 +103,12 @@ dsh --profile wsl                                  # 4. 启动
 | `workspace-write` | 在上一行基础上，把会话工作区绑定为可写，并把 `/tmp` 挂成临时目录 |
 | `danger-full-access` | 不加沙箱；用于批准后的放宽权限请求 |
 
-**bubblewrap 是必需项，而且失败是关闭的。** 没有它时，每条受限命令都报 `SANDBOX_UNAVAILABLE`，而不是不受约束地运行。要退出约束就在任一 provider 上设 `sandbox: false`，工具层会如实告诉模型这些操作没有沙箱。
+**bubblewrap 是必需项，缺失即失败关闭。** 没有它时，每条受限命令都报 `SANDBOX_UNAVAILABLE`，而不是不受约束地运行。要退出约束就在任一 provider 上设 `sandbox: false`，工具层会如实告诉模型这些操作没有沙箱。
 
 **上报的强制程度是 `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。
-
 ## 常见问题
 
 | 现象 | 原因 | 处理 |