dsh-plugin-wsl-env 0.4.0 → 0.6.0

package/CHANGELOG.md

@@ -12,6 +12,132 @@ reference below points at that record's numbering.
 
 ## [Unreleased]
 
+## [0.6.0] - 2026-10-04
+
+One theme: the P2 backlog from the 2026-10-03 review, closed with the same
+evidence bar as its P0/P1 — every fix carries a check that fails without it,
+and the real-distro probes run green over the changed paths — plus the
+import-time regression that backlog carried, caught at the first
+sync-and-restart: `watchMaxDepth` was written `z.number().int()`, a member the
+pinned schemastery does not publish, which took `wsl-shell` and `wsl-fs` down
+in every distro workspace session. The key now uses `z.natural()`, and
+`test/syntax.mjs` reads the chained half of the schemastery surface so the
+next such member dies in CI instead of in the app.
+
+### Fixed
+
+- **The in-distro watcher no longer fails silently (review M10).** Four defects
+  in `lib/watcher.js`, fixed together because they share one loop:
+  the stamp file is removed on every way out (EXIT trap; TERM/INT/HUP routed
+  through a plain exit so the trap runs); a target that vanishes mid-watch now
+  ends the loop with a report through the error channel instead of arming
+  forever (`E` protocol line, unit- and probe-tested); the scan's depth is
+  boundable through the new `wsl-fs.watchMaxDepth` key (`0`, the default,
+  keeps the whole-tree walk); and the loop's stderr is drained continuously
+  with its tail kept for error context, so a chatty `sh` can no longer stall
+  the watch at the 64 KiB pipe limit.
+- **`watchMaxDepth` no longer takes both preset rows down at import (a
+  regression the M10 entry above introduced, caught after the first
+  sync-and-restart).** The key was written `z.number().int().min(0)`, but the
+  pinned schemastery publishes no `int` on any schema instance, and a Config
+  schema is a class field — so `lib/index.js` threw
+  `TypeError: z.number(...).int is not a function` while it was still being
+  imported, the loader left `wsl-shell` and `wsl-fs` fiber-less, and the preset
+  audit reported exactly those two rows as `never started`: every session in a
+  distro workspace, new or historical, failed at the first message. The key is
+  now `z.natural().default(0)` — the pinned spelling of "integer >= 0", the
+  idiom `picker` and `auto-preset` already use — and `test/syntax.mjs` now
+  reads the chained half of the schemastery surface (a balanced walk that
+  survives nested call arguments, string literals and template
+  interpolations), so a member the peer does not publish fails the suite
+  instead of waiting for the Desktop app. Reproduced and verified in a
+  peer-stub harness: the `lib/index.js` import went from the `TypeError` to
+  clean with the fix, and the new check fails on the old line.
+- **A wedged WSL service can no longer hang a tool call forever (review M11).**
+  Every `wsl.exe` resolution call in `lib/wsl.js` now runs under a deadline
+  (`DEFAULT_WSL_DEADLINE_MS`, 60 s — generous on purpose for cold boots, `0`
+  waits forever), and the deadline kill is named for what it is in the error,
+  with the `wsl.exe --shutdown` remedy. Separately, the agent execution path's
+  `confine()` now receives the request's abort signal, the same one the
+  one-shot path always passed.
+- **A timed-out command can no longer leave descendants running (review M12).**
+  EXEC requests run as their own session and process group (`setsid`, detected
+  at startup with a documented fallback), and the in-distro timeout and KILL
+  frames signal the whole group — TERM, then KILL after the grace, descendants
+  included. Proven by a new real-script check: a command that backgrounds a
+  marked shell and outlives its budget leaves zero survivors.
+- **Documentation drift cluster (review M9).** ARCHITECTURE.md's service table
+  claimed the share substrate was the default (it is `agent`), pointed at
+  `lib/sandbox.js` for `bwrapProfileArgs` (built in `lib/bwrap.js`), and kept
+  the long-gone `watch()` refusal in the error-code table; the `substrate`
+  schema docstring claimed watches run through the substrate (both substrates
+  ride the same `lib/watcher.js` poll loop); PARITY.md now records the rg
+  interception as designed-but-never-implemented instead of leaving it
+  implied; and the probe checklists (both READMEs, CONTRIBUTING, RELEASING,
+  the PR template, CI's comment) list the agent, watch, substrate and exec
+  probes that had shipped without being listed anywhere.
+
+### Changed
+
+- **Test structure (review M15).** The sandbox checks run everywhere now:
+  the probe-and-confine logic moved to the peer-free `lib/sandbox-core.js`
+  (one implementation, still shipped), `lib/sandbox.js` binds it to the peer's
+  `SandboxUnavailableError`, and the tests inject a stand-in with the same
+  `code` — CI no longer skips them. `FS_SANDBOX_DENIED`'s write-only
+  classification carries three unit checks (write denial classified, the same
+  signature ignored off the write path, ordinary permission failures keep
+  theirs). The probes stopped carrying inline bwrap profiles: `exec.sh` and
+  `sandbox.sh` derive their profiles from `lib/bwrap.js` itself, so a profile
+  change fails the probe instead of hiding behind a copy. `lib/wsl.js`'s
+  spawning half — previously probe-only — gained `test/wsl.test.mjs`.
+  `test/probe/agent.sh` is wired as `npm run probe:agent` like its siblings.
+
+## [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

package/CONTRIBUTING.md

@@ -69,6 +69,10 @@ terminal if you would rather not see the prompt.
 | `npm run probe:sandbox` | what bubblewrap confines and what it does not | no |
 | `npm run probe:sandbox-shell` | the confined executor through a real boot | yes |
 | `npm run probe:terminal` | the terminal provider | yes |
+| `npm run probe:substrate` | the agent filesystem substrate over a real `wsl.exe` transport | yes; inside the distro |
+| `npm run probe:watch` | the in-distro watcher over a real directory | yes; inside the distro |
+| `npm run probe:agent` | the resident-vs-one-shot fallback parity legs | yes; inside the distro |
+| `npm run probe:exec` | the agent-backed execution handle: timeout, kill, cwd failure | yes; inside the distro |
 | `npm run probe:missing-wsl` | how a `wslPath` that cannot start is reported | yes |
 | `npm run probe:picker` | the picker's root level, its refusals and its cap | yes |
 | `npm run probe:mode` | which POSIX-mode facts survive the share | no; Windows Node |

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 |
@@ -120,6 +143,9 @@ npm run probe                # filesystem probe against a real distro (Windows +
 npm run probe:sandbox-shell  # boot a real harness and drive the confined executor
 npm run probe:terminal       # open a PTY through the terminal provider
 npm run probe:substrate      # drive the agent filesystem substrate over a real wsl.exe transport (from inside the distro)
+npm run probe:watch          # arm the in-distro watcher over a real directory (from inside the distro)
+npm run probe:agent          # the resident-vs-one-shot fallback parity legs (from inside the distro)
+npm run probe:exec           # the agent-backed execution handle: timeout, kill, cwd failure (from inside the distro)
 npm run probe:missing-wsl    # boot a profile whose wslPath cannot start (Windows + WSL only)
 npm run probe:picker         # list the picker's root level, refusals and its cap (Windows + WSL only)
 npm run probe:mode           # which POSIX-mode facts survive the share (Windows node only)

package/agent/wsl-agent.sh

@@ -27,6 +27,10 @@
 #          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)
+#       An EXEC request runs as its own session and process group (`setsid`),
+#       so a timeout or a KILL frame takes the whole descendant tree — not
+#       just the direct child, which is how a build tool's daemonized
+#       grandchild outlives the kill.
 #   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
@@ -81,31 +85,58 @@ b64enc_file() {
 
 kill_current() {
   if [ -n "$CURRENT_PID" ]; then
-    kill -TERM "$CURRENT_PID" 2>/dev/null
+    kill_request TERM "$CURRENT_PID"
   fi
 }
 
+# Signal one in-flight request, descendants included. With `setsid` (EXEC
+# requests, below) the request is its own process-group leader, so the
+# negative PID signals the WHOLE group — every descendant that did not make
+# its own session. Without it the group does not exist, the negative-PID kill
+# fails with ESRCH, and the direct kill keeps the old guarantee. A shell whose
+# `kill` builtin cannot parse `-- -PID` at all also lands here.
+kill_request() {
+  # $1 = signal name, $2 = request PID.
+  kill -s "$1" -- "-$2" 2>/dev/null || kill -s "$1" "$2" 2>/dev/null || :
+}
+
 shutdown() {
   kill_current
   exit 0
 }
 trap shutdown TERM INT HUP
 
+# Whether EXEC requests can run as their own session. `setsid` makes the
+# request process a session AND process-group leader (pid = pgid), which is
+# what lets kill_request signal the whole descendant tree; the agent's own
+# shell cannot do this portably — `set -m` in a non-interactive dash has been
+# observed skipping the setpgid entirely, and a kill against a PID that is
+# not a group leader is a no-op. A distro without `setsid` keeps working:
+# requests then run in the agent's own group and the direct-child kill of the
+# pre-setsid behaviour applies.
+SETSID=
+if command -v setsid >/dev/null 2>&1; then
+  SETSID=setsid
+fi
+
 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.
+  # $1 = seconds, $2 = pid, $3 = grace seconds. TERM first — the whole group,
+  # so a command that ignores TERM takes its descendants with it when the
+  # KILL lands; 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
+  kill_request TERM "$2"
   sleep "${3:-3}"
-  kill -KILL "$2" 2>/dev/null
+  kill_request KILL "$2"
 }
 
 # 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.
+# request process, in its own session via `setsid` when the distro has it —
+# the timeout and KILL then signal the whole descendant group; `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
@@ -121,6 +152,8 @@ run_capture() {
   CURRENT_ID=$req_id
   if [ "$mode" = subshell ]; then
     ( "$@" ) >"$OUT_FILE" 2>"$ERR_FILE" &
+  elif [ -n "$SETSID" ]; then
+    ( exec setsid "$@" ) >"$OUT_FILE" 2>"$ERR_FILE" &
   else
     "$@" >"$OUT_FILE" 2>"$ERR_FILE" &
   fi

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

@@ -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) | 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.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 resident in-distro agent on ext4 (default), or the Windows-side host stack over the distro's UNC share. |
 | `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`
@@ -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
 
@@ -142,7 +146,8 @@ wsl.exe -d <distro> --cd <linux dir> --exec bwrap \
 
 These are the same arguments DSH's Linux runner uses (`dsh-sandbox-local`), so the
 behaviour and the error messages match a Linux host. The function
-`bwrapProfileArgs` in [`lib/sandbox.js`](../lib/sandbox.js) builds them.
+`bwrapProfileArgs` in [`lib/bwrap.js`](../lib/bwrap.js) builds them — the
+peer-free builder every confinement site composes from.
 
 | Mode | What a command inside the distro can do |
 |---|---|
@@ -204,7 +209,7 @@ finds it here.
 | `FS_OUTSIDE_DISTRO` | `WslFileSystem.worldPath` | `restrictToDistro` is on and the path names **another distro**'s share — a configuration fence, not a sandbox decision | open a session in that distro, or set `restrictToDistro: false`. A wider permission does **not** lift it |
 | `FS_NOT_OBSERVED` | `WslFileSystem.assertGuard` | a guarded create (`createIfAbsent`) targeted a file that exists and had not been read first | read the file, then overwrite with the version guard or edit it |
 | `FS_STALE_VERSION` | `WslFileSystem.assertGuard` | the version the caller holds no longer matches: the file changed, or is gone | read it again and retry with the fresh version |
-| `FS_IO_ERROR` | `WslFileSystem.watch` | `watch()` is refused, because a 9p share cannot be watched reliably | poll, or watch from inside the distro |
+| `FS_IO_ERROR` | `WslFileSystem.watch` | the watch target is not a path inside the pinned distro, so there is nothing the in-distro poll loop can observe | watch a distro path; the watch itself runs where the files live (`lib/watcher.js`) |
 | `FS_NOT_FOUND` | the host filesystem stack | the path does not exist — the ordinary answer, passed through | — |
 
 Two failures come from `wsl.exe` itself rather than from a code of ours, and both used

package/docs/CONFIGURATION.md

@@ -26,12 +26,14 @@ are schema defaults, listed because they are the ones worth knowing.
 | | `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 |
+| | `watchMaxDepth` | `0` | how deep the in-distro watch scan walks; `0` walks the whole tree. Bound it (e.g. `4`) when the watched tree holds a `node_modules` — a change below the bound is seen only when another change above it fires the same callback |
 | `directory-picker-wsl` | `preferredDistro` | `''` *(shipped)* | the distro listed first in the picker |
 | | `includeHostHome` | `true` *(shipped)* | also list the Windows home directory |
 | | `maxEntries` | `1000` *(shipped)* | maximum entries listed per directory |
 | `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

@@ -110,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

@@ -40,6 +40,10 @@ shaped a phase of the plan.
    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.
+   **Not implemented, and recorded so the gap is a decision, not an
+   omission:** search still runs the packaged Windows rg over the share. The
+   interception was designed (above) but never landed; nothing in the phase
+   table below delivers it, and no phase claims it.
 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.

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。
-
 ## 常见问题
 
 | 现象 | 原因 | 处理 |
@@ -112,6 +134,9 @@ npm run probe                # 文件系统探针，需要真实子系统（仅
 npm run probe:sandbox-shell  # 启动真实 harness，驱动受限执行器
 npm run probe:terminal       # 通过终端 provider 打开一个 PTY
 npm run probe:substrate      # 用真实 wsl.exe 传输驱动 agent 文件基座（在子系统内运行）
+npm run probe:watch          # 在真实目录上装上 distro 内轮询 watcher（在子系统内运行）
+npm run probe:agent          # resident 与 one-shot 的回退不变量对比腿（在子系统内运行）
+npm run probe:exec           # agent 执行句柄：超时、杀停、cwd 失败（在子系统内运行）
 npm run probe:missing-wsl    # 启动一个 wslPath 无法启动的 profile（仅 Windows + WSL）
 npm run probe:picker         # 列出选择器的根级、拒绝路径与上限（仅 Windows + WSL）
 npm run probe:mode           # 哪些 POSIX 权限事实能穿过共享层（仅需 Windows node）

package/docs/UPSTREAM-TERMINAL-TITLE.md

@@ -0,0 +1,81 @@
+# Upstream proposal: a terminal tab title that follows the session's shell
+
+Status: proposed upstream as
+[deepseek-ai/deepseek-harness#8769](https://github.com/deepseek-ai/deepseek-harness/discussions/8769)
+(targeting `packages/api/terminal-controller`, version line `0.2.0-rc.x`). This
+is the record of a gap this plugin worked around, could not work around, and
+now documents: the GUI terminal titles every tab from the composition's single
+shell profile, so a per-session shell choice is invisible in the title.
+
+## The gap
+
+`TerminalController.spawn` fixes a terminal's display title from the resolved
+shell profile before the provider is ever consulted:
+
+```ts
+const info: WebTerminalInfo = {
+  id: request.id, shell, title: shell.name, cwd: environment.cwd, ...
+}
+```
+
+`shell` is `resolveShell(subprocess, this.config.shell, signal)` — the
+composition's configured profile (`shell.name: WSL` in this plugin's layer),
+kept verbatim; `resolveExecutable` swaps only the `path`. Two properties of the
+seam make the title unable to follow a per-session shell:
+
+- `SubprocessTerminalSpawnSpec` carries no display-name field, so a provider
+  that rewrites the launch (this plugin routes a Windows-folder session's
+  `wsl.exe` launch to `powershell.exe` — `subprocess-wsl.hostSessions`) cannot
+  say what it actually started.
+- The controller never reads the effective program back from the
+  `SubprocessTerminalHandle`, so the rewrite is invisible to `info.title`.
+
+The result on this plugin's default configuration: a terminal that runs
+PowerShell under a tab that reads `WSL`.
+
+## Why a plugin cannot bridge it
+
+Three escape hatches were evaluated against `0.2.0-rc.2` and each is closed:
+
+1. **Replace the controller row's module with a subclass** that corrects the
+   title after `super.spawn` (the class exports itself; `BrowserTerminal.rename`
+   is public and lands before `create()` publishes the terminal). Closed by the
+   patch-layer contract: *"A truthy name asserts the existing plugin name
+   rather than renaming it"* (`packages/boot/app-boot/src/config-schema/document.ts`)
+   — an id-targeted patch can replace `config`, but not the module.
+2. **Disable the shipped row and insert the subclass under a new id.** Closed
+   by the web composition: the row id is load-bearing. The web-app bundle
+   inserts `terminal-controller`, and the client model that the
+   `dsh-client-ui-sidebar-terminal` entry waits for mounts with
+   `inject = ['remote', 'remote.terminal']` — the `terminal` namespace the host
+   controller registers in its constructor. Disabling the row fails web boot:
+   `1 entry did not activate: @deepseek-ai/dsh-client-ui-sidebar-terminal:
+   pending (waiting for service: webTerminals)`. Verified live against
+   `dsh-desktop 0.2.0-rc.2`.
+3. **Per-session config.** The `shell` profile is composition state; `!!js`
+   expressions evaluate once at config resolution and reach no Session
+   identity.
+
+## The proposal
+
+Any one of these closes the gap; the first is the smallest and keeps the
+profile name as the fallback:
+
+- `SubprocessTerminalSpawnSpec` gains an optional `displayTitle` (or the handle
+  exposes the launched `argv`), and `create()` uses it for `info.title` when
+  present — falling back to `shell.name`. A provider that rewrites a launch
+  states the program it started; every other launch keeps the profile name.
+- Alternatively, the controller derives the title from the effective program
+  itself: title `executableName(effectiveArgv[0])` when it differs from
+  `shell.path`, else `shell.name`.
+
+With either, this plugin deletes the limitation paragraph in
+[LIMITATIONS.md](LIMITATIONS.md) and the `WSL`-over-PowerShell title, for any
+provider that rewrites launches — not just WSL.
+
+## Workarounds until then
+
+- Double-click a tab's title to rename it (a shipped client feature; the
+  controller's `rename` Remote API accepts 1–120 characters).
+- Add `shellCandidates` to the `terminal-controller` row in a user layer: a
+  manually selected shell is titled after itself.