dsh-plugin-wsl-env 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,274 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project uses
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+The reasoning and the measurements behind each entry are in the archived
+engineering record,
+[docs/archive/engineering-record.zh.md](docs/archive/engineering-record.zh.md)
+(Chinese, repository only — it is history, never a second README). Every `§`
+reference below points at that record's numbering.
+
+## [Unreleased]
+
+## [0.1.0] - 2026-10-02
+
+First release. A WSL distro can be picked as a workspace, read and written
+with the model's own file tools, and run commands in; the GUI terminal opens
+inside it; commands are confined by a Linux-side sandbox built in the distro;
+and the package installs as a bundle that contributes its own profile layer.
+
+### Added
+
+- **Distro-side sandboxing** (`lib/sandbox.js`, and `sandbox: true` on both
+  providers): WSL commands are now confined instead of running unconfined. The
+  Windows ACL runner can never reach WSL — its restricted token fails `wsl.exe`
+  with `Wsl/E_ACCESSDENIED` — so the confinement is built on the host and
+  executed *inside* the distro: `wsl.exe … --exec bwrap --ro-bind / / --dev /dev
+  --unshare-pid --proc /proc --die-with-parent [--tmpfs /tmp --bind <workspace>
+  <workspace>] -- <shell> -lc <cmd>`. The profile arguments, the denial dialect
+  (`read-only file system`) and the runner-failure rules mirror
+  `@deepseek-ai/dsh-sandbox-local`'s Linux rung, so a denial reads the same
+  whether the command ran on a Linux host or in a distro. `WslShellExecutor` and
+  `WslFileSystem` advertise the mode through their `sandboxMode` capability fact,
+  which brings back the Permissions selector and the denied→escalate flow
+  (`danger-full-access` skips the wrap entirely). Enforcement is reported as
+  **`partial`**, not `full`: a distro process can still execute a Windows binary
+  through interop, which bubblewrap does not govern — measured, not assumed, by
+  the probe below. Without `bubblewrap` in the distro the providers fail closed
+  with `SANDBOX_UNAVAILABLE`; `sandbox: false` restores the old posture and
+  removes the capability fact with it.
+- Sandbox probes. `test/probe/sandbox.sh` (`npm run probe:sandbox`) needs no
+  harness: it applies the exact profile arguments and asserts what bubblewrap
+  governs — a write outside the workspace refused with EROFS, an ephemeral
+  sandbox `/tmp`, a read-only `/mnt/c`, and the interop escape, recorded as
+  `INFO` because a Linux sandbox cannot govern a Windows process.
+  `test/probe/sandbox-shell.sh` (`npm run probe:sandbox-shell`) boots the
+  throwaway profile with the executor mounted and drives the same three modes
+  through `ctx.shell`, asserting the result's `denied`/`enforcement` facts.
+- `WslSubprocessRuntime` (`ctx.subprocess`, subpath
+  `dsh-plugin-wsl-env/subprocess`): the GUI's right-sidebar terminal window now
+  opens a shell *inside the distro*, in the Session workspace, instead of
+  `cmd.exe` in a UNC directory. It is a `LocalSubprocessRuntime` subclass whose
+  only override is `spawnTerminal`, so every ordinary command, the host ripgrep
+  search and every other subprocess consumer keeps the shipped implementation.
+  The `wsl.exe` launch is rewritten to `wsl.exe -d <distro> --cd <linux dir>`,
+  with the request's `DSH_*` facts forwarded through `WSLENV`, and the distro's
+  own login shell is left to `wsl.exe` unless the provider pins one.
+- Terminal probe (`test/probe/terminal.sh`, `npm run probe:terminal`): boots the
+  throwaway Web profile with the provider in place, asks for the same
+  `spawnTerminal` request the GUI makes, and asserts the distro, the translated
+  initial directory, and the forwarded `DSH_SESSION_ID`.
+
+- `WslShellExecutor` (`ctx.shell`): runs every command inside the distro as
+  `wsl.exe -d <distro> --cd <linux dir> --exec <shell> -lc <cmd>`, where the
+  shell is the distro user's login shell rather than a hardcoded bash. (§3, §12)
+- `WslFileSystem` (`ctx.fs`): maps Linux paths onto the distro's UNC share so the
+  host fs stack — including the packaged ripgrep — operates on real distro files,
+  with Linux paths as the model-facing `displayPath` and the UNC path as the
+  opaque `targetKey`. (§3)
+- Symlinked paths resolve by asking the distro for `readlink -f` and retrying
+  once, which is what makes `/etc/os-release`, `/bin` and `/lib` readable over a
+  share that cannot traverse POSIX symlinks. (§10.4)
+- `WslDirectoryPicker` (`ctx.directoryPicker`): lists Windows home and every
+  installed distro at the root level, so the shipped GUI dialog becomes the
+  single workspace picker for host and distro folders alike. It reports
+  `kind: 'browse'` — a third kind would invalidate the three Remote verbs that
+  require it. (§8)
+- `auto-preset`: binds the `wsl` agent preset when a new session's workspace is
+  inside a distro, inside the `ensureSession` frame so the very first mount is
+  already correct and the host ACL sandbox never touches a 9p path. (§13, §15)
+- `shell-env`: contributes `DSH_WSL_DISTRO`, `DSH_WSL_SHELL` and `DSH_WSL_HOME`
+  to the managed `DSH_*` namespace, so the model can read the real environment
+  instead of inferring it from a tool name. (§14)
+- Behavioural probe harness under `test/probe/`, with two throwaway profiles and
+  a negative-control run. (§16.5)
+### Changed
+
+- `WslFileSystem` fences its mutations by `ctx.sandboxPolicy`: `writeText` and
+  `editText` check the policy before any I/O, re-resolve the target so the checked
+  identity is the mutated one, refuse `read-only` and anything outside the
+  writable roots with `FS_SANDBOX_DENIED`, and refuse nothing at all under
+  `danger-full-access`. The writable roots are the workspace plus the temp area of
+  the world that workspace lives in — a distro workspace grants the distro's
+  `/tmp`, a Windows-folder workspace keeps upstream's `/tmp` + `os.tmpdir()`.
+  `@deepseek-ai/dsh-sandbox` returns as a peer: the plugin imports the shared
+  `canonicalPath`/`writableRoots` and the runner-failure/diagnostic classifiers
+  rather than restating them.
+- The README's "one constraint that shapes everything" section is gone: it said
+  the plugin inherits `sandboxMode === undefined`, which is no longer true. The
+  replacement states the mechanism (Linux bubblewrap inside the distro), the mode
+  table, the `partial` enforcement and its interop cause, the `bubblewrap`
+  requirement and the fail-closed behaviour.
+- An empty `cwd` now means **the distro user's home** in both WSL providers,
+  instead of the host path the shipped default resolves to. `WslFileSystem`'s
+  default was `process.cwd()` — a Windows directory no `wsl.exe --cd` accepts —
+  and `cordis.patch.yml` papered over it with the author's own `/home/andy`, a
+  value that is wrong on every other machine. `WslShellExecutor.resolve()` keeps
+  the seam's synchronous contract (`ctx.shell.execute(ctx.shell.resolve(…))` is
+  called with no `await` in between) and marks the case with an empty `workdir`;
+  `execute()` fills it from the distro's `$HOME`, one cached `wsl.exe` query per
+  provider instance. Only relative input consults the base at all, so an
+  absolute path never pays for the query, and `DSH_WSL_HOME` now takes the POSIX
+  home directly (`linuxHomePath`) instead of converting the world path back. The
+  `wslfs` probe follows: its profile no longer pins a `cwd`, and `fs-probe.mjs`
+  resolves a relative name and asserts it lands under the home the distro itself
+  reports — which is the only place that fallback was reachable at all, since the
+  tool layer always passes an absolute Session directory.
+- The package is now a DSH **bundle**, so installing it applies the layer instead
+  of merely dropping code into a profile. `package.json` declares
+  `dsh.bundle.patch` → `./cordis.patch.yml`, which is the declaration
+  `dsh plugin --profile <name> add dsh-plugin-wsl-env` reads; `private: true` is
+  gone (npm refuses to publish it otherwise), and `repository`/`homepage`/`bugs`
+  now point at the GitHub repository. The package is plain JS with no
+  dependencies, so a published install needs no `allowBuilds` permission and no
+  build step. README's Install section follows: create the profile from the Web
+  template, `dsh plugin … add`, then `--dump-config`.
+- `cordis.patch.yml` is now only the plugin's own layer. The four machine-local
+  rows it used to carry — `agent-default-model`, `ui-settings-account`,
+  `ui-chat`, `ui-settings` — moved to
+  [examples/profile.cordis.patch.yml](examples/profile.cordis.patch.yml), which
+  documents what a reader's own `$DSH_HOME/profiles/<name>/cordis.patch.yml` is
+  for and what a by-id row override looks like.
+- The terminal is bound at the **composition** level, not in the `wsl` preset.
+  `dsh-api-terminal-controller` resolves its execution world with
+  `agent.ctx.get("subprocess")`, and an Agent's context is created by the agent
+  loop under the root realm (`createScope(loopCtx, …)`, `loopCtx` = the
+  root-mounted `ctx.agents`), while a preset's isolate realms belong to
+  `dsh-agent-preset-registry`'s own context (`createScope(this.owner, …)`). A
+  `subprocess` provider inside `preset-wsl` is therefore invisible to the
+  terminal window — the registry's `agentPresets.serviceFor(agent, name)` is the
+  sanctioned channel for that gap, and the controller does not use it.
+  `cordis.patch.yml` consequently disables the shipped `subprocess` row and
+  inserts this provider, and configures `terminal-controller` with
+  `shell: { path: wsl.exe, name: WSL }` and `shellCandidates: []`.
+- `@deepseek-ai/dsh-subprocess-local` is now a declared peer. A linked plugin's
+  bare imports are routed through its `peerDependencies` by the runtime's
+  resolution interception, so an undeclared peer is not merely untidy — the
+  module fails to import with `failed to import`.
+- The README is now **current state only**. The five sections describing designs
+  that this one replaced — the per-process `DSH_WSL` switch and the three
+  abandoned tool-naming routes — moved to
+  [docs/archive/design-history.zh.md](docs/archive/design-history.zh.md), which
+  keeps their original numbering and records where each conclusion lives now.
+  The README renumbered accordingly; its §0.1 explains the split. The one part of
+  the old desktop section that is still current (regenerating the generated
+  `preset-wsl` block after an app upgrade) stayed, as §13.9.
+- Static review: the manifest now says only what the shipped code does.
+  - `main` pointed at `lib/index.js` while `exports["."]` resolved to
+    `lib/shell.js`. Only the latter exposes a default export, so a tool that
+    read `main` instead of `exports` got a module with no plugin in it.
+  - `lib/index.js` re-exported path helpers that nothing could reach: the
+    `exports` map does not expose `lib/index.js`, and the helpers already have
+    their own `./paths` and `./wsl` subpaths.
+  - Dropped an unused `ENV_OVERRIDES` import.
+### Known limitations
+
+- The sandbox does not govern WSL interop: a confined distro command can still
+  execute a Windows binary from `/mnt/c`, and that process runs outside
+  bubblewrap under the ordinary Windows token. Enforcement is therefore reported
+  as `partial`, and `npm run probe:sandbox` re-measures the escape. Closing it
+  would mean denying execution under `/mnt`, which breaks `/mnt/c/…` Sessions.
+- `bubblewrap` must be installed in the distro, and both providers **fail
+  closed** without it (`SANDBOX_UNAVAILABLE` rather than a silent unconfined
+  run). `sandbox: false` is the documented opt-out. A `workspace-write` profile
+  also refuses to bind a workspace root that does not exist, so a Session whose
+  workspace directory was deleted reports a runner diagnostic instead of being
+  recreated.
+- The GUI terminal is an interactive shell and is not wrapped in the sandbox,
+  exactly like the shipped terminal provider.
+- The runtime mirror's destination lies outside every Session workspace, so the
+  sync step of `npm run probe` (and of a manual `sync-to-windows.sh`) needs an
+  approved `danger-full-access` escalation when an agent runs it.
+- 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>/…`.
+- Terminal activity reporting stops at `wsl.exe`, so the controller's unattended
+  idle reclamation never fires for these terminals; close the tab to release the
+  process.
+
+See the archived record's §7 for the full list, including the 9p
+performance caveat, unsupported `watch()`, and the missing executable bit on
+freshly created files.
+### Removed
+
+- `README.zh.md` stopped being a README: the file moved to
+  `docs/archive/engineering-record.zh.md` and left the package's `files` list, so
+  npm and GitHub now render exactly one README. The reasoning is under Fixed
+  below; nothing was deleted, only renamed out of the slot that made it look
+  current.
+- Three peer declarations this plugin neither imports nor injects:
+  `@deepseek-ai/dsh-sandbox`, `@deepseek-ai/dsh-shell` and
+  `@deepseek-ai/dsh-tools`. They were required by the abandoned tool-renaming
+  designs (archive §15/§18), which could only stub the sandbox symbols locally
+  (archive §15.5). The remaining set is checkable in one command —
+  `grep -rho 'from "@deepseek-ai/[^"]*"' lib/ | sort -u` — plus
+  `@deepseek-ai/dsh-subprocess` (the service `static inject` requires) and
+  `@deepseek-ai/cordis`, which every DSH plugin declares.
+  (`@deepseek-ai/dsh-sandbox` came back in this same release: the distro-side
+  sandbox imports `canonicalPath`/`writableRoots` and the runner diagnostics, so
+  the declaration is earned again rather than vestigial — and that same check is
+  what surfaced it, by listing the package this entry had removed.)
+### Fixed
+
+- `lib/listing.js` built breadcrumbs with the platform-default
+  `dirname`/`basename` from `node:path` rather than the `win32` flavour its own
+  comments describe. On Linux — where the CI runners run, and where this
+  checkout itself lives — a UNC path parses as a single opaque POSIX segment,
+  so the ancestry chain collapsed to `['.', <whole path>]` and three
+  `test/listing.test.mjs` checks failed. The helpers serve Windows paths only;
+  they now call `win32.dirname`/`win32.basename` explicitly, and the suite
+  passes on Linux again.
+
+Documentation that a reader would have acted on, and that was no longer true:
+
+- The repository briefly carried two READMEs. `README.zh.md` called itself the
+  current description of the plugin while its conclusions had been superseded
+  three times over — most sharply by the sandbox work below — which is exactly
+  the ambiguity a second README creates. It is now
+  [docs/archive/engineering-record.zh.md](docs/archive/engineering-record.zh.md):
+  the same content, renamed out of the README slot and banner-headed as history,
+  with README.md the single statement of current state. Nothing was deleted from
+  the record; §0.1 names the conclusions that are now historical.
+- §2.1 and §3.4 of that record conclude that "any WSL plugin must run on a
+  non-sandboxing provider" and that both providers report `sandboxMode:
+  undefined` (§9's recorded self-check prints exactly that). The Windows ACL
+  constraint in §2.1 holds and is unchanged; the *conclusion* it drew about our
+  own confinement does not, because the sandbox now runs inside the distro — see
+  the README's *Sandboxing* section.
+- §9.4's three-step install ends with writing the plugin's rows into the profile's
+  own `cordis.patch.yml` by hand. The package is a bundle now, so that step is
+  gone (and the row set it describes has since gained the sandbox config); the
+  current install is in README.md.
+- §9.6 and §10.5 claimed the `wsl` and `wsltest` profiles were still available,
+  and §13.6 said the same about `envweb`. All three are gone.
+- The desktop section documented the superseded `build-desktop-patch.mjs`
+  regeneration flow instead of `build-preset-wsl.mjs`.
+- §15.5 answered "nothing to do after an app upgrade" while the desktop section
+  said the generated preset copy has to be regenerated.
+- References to `dsh-wsl-research/` now say it is a machine-local directory that
+  is not part of the repository.
+
+- `wsl.exe` was handed the command without `--exec`, so the distro's default
+  shell expanded it once first: `$x`, `$?`, `$(...)`, `${...}` and backticks were
+  silently eaten. (§11)
+- The shell was hardcoded to bash, discarding the PATH and rc setup of a user
+  whose login shell is zsh, fish or dash. (§12)
+- Guarded creation (`createIfAbsent`) failed with `FS_IO_ERROR`, because the host
+  backend publishes it with a hard link and the share rejects hard links with
+  `ENOTSUP`; the guard is now checked by this backend and publication is a plain
+  rename. (§2.2)
+- The managed `DSH_*` namespace never reached the distro. WSL imports only the
+  names listed in `WSLENV`, and the executor forwarded a fixed allowlist; it now
+  forwards the whole prefix, and marks the two Windows-path facts `DSH_HOME` and
+  `DSH_PROFILE_DIR` with `/p` so the distro sees `/mnt/c/...`. (§14.7)
+- **Every write to an existing file, and therefore every edit, failed** with
+  `EIO: GetFileSecurityW EIO (Win32 1)`. `dsh-fs-local` takes a Windows branch
+  whenever the destination exists — to inherit the replaced file's DACL — and a
+  9p share carries no Windows security descriptor. Publication now uses the POSIX
+  path. (§16)
+- Overwriting or editing a file silently dropped its POSIX mode, so editing a
+  script made it non-executable: the share ignores a host-side `chmod`, and a
+  host-side `stat` always reports 0666. The target's real mode is now copied onto
+  the staged temp file inside the distro, where a rename preserves it. (§16.3)

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Andy Zhao
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,314 @@
+# dsh-plugin-wsl-env
+
+Run a [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) session
+against a WSL distro. Commands execute *inside* the distro, the model's file tools
+read and write real distro files, and the GUI's folder dialog can open one.
+
+> The engineering record this file summarises — design rationale, measurements,
+> and every discarded design with the reason it was abandoned — is archived at
+> **[docs/archive/engineering-record.zh.md](docs/archive/engineering-record.zh.md)**
+> (Chinese). It is history, not a second README: where it and this file disagree,
+> **this file is the current state**. Its §0.1 lists which of its conclusions the
+> later sandbox work superseded.
+
+## What it does
+
+DSH is a Cordis application whose capabilities are exposed as *service seams*.
+The model-facing tools (`bash`, `read`, `write`, `edit`, `glob`, `grep`) consume
+those seams and never touch a filesystem or a shell directly. A WSL integration
+is therefore not a new tool; it is two seam providers:
+
+| Seam | Provider | Effect |
+|---|---|---|
+| `ctx.shell` | `WslShellExecutor` | every command runs as `wsl.exe -d <distro> --cd <linux dir> --exec <login shell> -lc <cmd>`, wrapped in a distro-side `bwrap` sandbox |
+| `ctx.fs` | `WslFileSystem` | Linux paths map onto the distro's UNC share, so the host fs stack (and the packaged ripgrep) operates on real distro files, fenced by the same policy |
+| `ctx.subprocess` | `WslSubprocessRuntime` | the GUI's right-sidebar terminal window opens a shell *inside the distro*, in the Session workspace, instead of `cmd.exe` in a UNC directory |
+
+It also ships three smaller integrations:
+
+| Package | Provides |
+|---|---|
+| `dsh-plugin-wsl-env/picker` | `ctx.directoryPicker` — lists Windows home *and* every installed distro at the root level, so one dialog opens a host folder or a distro folder |
+| `dsh-plugin-wsl-env/auto-preset` | binds the `wsl` agent preset when a new session's workspace is inside a distro, in the `ensureSession` frame, so the very first mount is already correct and the host ACL sandbox never touches a 9p path |
+| `dsh-plugin-wsl-env/shell-env` | contributes `DSH_WSL_DISTRO`, `DSH_WSL_SHELL`, `DSH_WSL_HOME` to the managed `DSH_*` namespace the model reads |
+
+## Why the terminal provider sits at the composition level
+
+`ctx.shell` and `ctx.fs` are served *per Session*: they live in the `wsl` agent
+preset's isolate realm, so a host workspace keeps the shipped sandboxed
+PowerShell environment while a WSL workspace gets the distro, concurrently.
+
+The terminal window cannot be served that way, and the reason is not visible in
+the profile YAML. `dsh-api-terminal-controller` resolves its execution world from
+the Session's own context — `agent.ctx.get("subprocess")` — and an Agent's
+context is created by the agent loop under the **root** realm
+(`createScope(loopCtx, …)`, where `loopCtx` is the root-mounted `ctx.agents`),
+while a preset's isolate realms are created by `dsh-agent-preset-registry` under
+the **registry's** context (`createScope(this.owner, …)`). The two subtrees never
+meet, so a `subprocess` provider mounted inside `preset-wsl` is invisible to the
+terminal window. The registry ships `agentPresets.serviceFor(agent, name)` for
+exactly that gap; the terminal controller does not use it.
+
+So [`cordis.patch.yml`](cordis.patch.yml) replaces the composition-level
+`subprocess` row instead, with a subclass whose only override is
+`spawnTerminal`: a `wsl.exe` launch is rewritten to
+`wsl.exe -d <distro> --cd <linux dir>`, and everything else — every ordinary
+`spawn()`, the host ripgrep search, the pwsh executor, the LSP host — reaches the
+shipped implementation untouched.
+
+Consequence worth stating plainly: 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; and because
+`terminalEnvironment()` and `resolveExecutable()` receive no Session at all, the
+controller is configured with the single shell profile that matters
+(`shell: { path: wsl.exe }`) rather than having executable lookup rewritten for
+every root consumer to make one shell menu prettier.
+
+## Sandboxing: a different mechanism, not the Windows one
+
+On Windows, DSH confines commands with `dsh-sandbox-windows-acl`: a restricted,
+low-integrity token plus a write allowlist. **That token cannot reach WSL at
+all** — `wsl.exe` fails with `Wsl/E_ACCESSDENIED` and `\\wsl.localhost\<distro>`
+reports access denied. Both work normally outside the sandbox. There is no way
+to run a distro command under that token, so the WSL execution world cannot
+inherit the Windows sandbox.
+
+It gets the Linux one instead. `lib/sandbox.js` builds a **bubblewrap** profile
+on the host and hands it to `wsl.exe --exec`, so the confinement is created and
+enforced *inside* the distro:
+
+```
+wsl.exe -d <distro> --cd <linux dir> --exec bwrap \
+  --ro-bind / / --dev /dev --unshare-pid --proc /proc --die-with-parent \
+  [--tmpfs /tmp --bind <workspace> <workspace>]  --  <shell> -lc <cmd>
+```
+
+That is DSH's own Linux rung, argument for argument (`dsh-sandbox-local`), which
+is why the semantics and the diagnostics line up with a Linux host:
+
+| Mode | What the distro command gets |
+|---|---|
+| `read-only` | the whole distro read-only, `/dev/null` writable — the sink a shell needs |
+| `workspace-write` | the above plus the Session workspace bound read-write and an ephemeral `/tmp` |
+| `danger-full-access` | no wrap at all; the approved escalation |
+
+`WslFileSystem` fences the same policy on its own mutation path (`writeText`,
+`editText`) against the same writable roots, so "the write tool cannot write
+/tmp but bash can" asymmetries do not arise. Both providers report the mode
+through their `sandboxMode` capability fact, which is what brings back the
+Permissions selector and the *denied → request escalation* flow.
+
+**Enforcement is `partial`, and this is the honest part.** A WSL distro process
+can execute a *Windows* binary through interop (`/mnt/c/…/*.exe`). That process
+is not a Linux process: bubblewrap does not govern it, and it runs under your
+ordinary Windows token, able to write anywhere you can. `npm run probe:sandbox`
+demonstrates exactly that, and keeps demonstrating it. Closing the hole means
+denying execution under `/mnt`, which would also break `/mnt/c/…` Sessions — so
+it is stated rather than papered over. Network and process visibility are
+outside `SandboxMode`'s vocabulary on every platform.
+
+Two consequences worth knowing:
+
+- **`bubblewrap` is required in the distro** (`sudo apt install bubblewrap`).
+  Without it the provider *fails closed*: every confined command reports
+  `SANDBOX_UNAVAILABLE` instead of quietly running unconfined. The capability
+  fact also disappears with the enforcement — an unusable runner never leaves a
+  "confined" claim behind.
+- Configure `sandbox: false` on either provider to get the pre-sandbox
+  behaviour back: commands run unconfined and `sandboxMode` returns `undefined`,
+  so the tool layer tells the model these operations are not confined.
+
+## Requirements
+
+- Windows with WSL2 and at least one distro.
+- `bubblewrap` inside the distro, for the sandbox (see above).
+- DSH `0.2.0-rc.2`-era packages (`@deepseek-ai/dsh-base`, `dsh-web-app`).
+- **No dependencies.** Everything the package needs is a peer, supplied by the
+  profile that mounts it.
+
+## Install
+
+The package is a DSH **bundle**: its `package.json` declares
+`dsh.bundle.patch`, so `dsh plugin add` installs the code *and* applies
+[`cordis.patch.yml`](cordis.patch.yml) as a configuration layer. There is no
+patch to merge by hand. Start from the Web template, because the layer
+substitutes web-surface rows — the composition-level `subprocess` provider, the
+terminal controller, the directory picker:
+
+```powershell
+dsh wsl --from-default-profile web --dump-config   # create the profile from the Web template
+dsh plugin --profile wsl add dsh-plugin-wsl-env    # npm; or link:C:\path\to\checkout while developing
+dsh --profile wsl --dump-config        # compose only, no boot: the fastest check
+dsh --profile wsl
+```
+
+`cordis.patch.yml` is commented line by line and is the authoritative install
+reference, including the generated `preset-wsl` block. Two of its rows are not
+additions but substitutions: it **disables** the shipped composition-level
+`subprocess` provider and inserts this package's in its place, and it gives
+`terminal-controller` the `wsl.exe` shell profile. Both are needed for the
+terminal window and neither can live in the preset — see above.
+
+Machine-local preferences do not belong in that file. Layers compose as
+bundles, then the profile's own `cordis.patch.yml`, then the home-level one,
+then `--patch` overlays, and a later layer wins per row — so override a row by
+id in `$DSH_HOME/profiles/<name>/cordis.patch.yml`.
+[`examples/profile.cordis.patch.yml`](examples/profile.cordis.patch.yml) is one
+such layer, and shows what a row override looks like.
+
+> A running process caches ES modules. **Restart the app after changing `lib/`**,
+> or the old code stays loaded.
+
+## Layout
+
+```
+lib/paths.js        pure path translation between the three coordinate systems
+lib/wsl.js          wsl.exe interop primitives (no DSH imports)
+lib/listing.js      pure directory-listing and breadcrumb helpers (no DSH imports)
+lib/index.js        WslShellExecutor (ctx.shell) + WslFileSystem (ctx.fs)
+lib/sandbox.js      the distro-side bwrap confinement both providers apply
+lib/picker.js       WslDirectoryPicker (ctx.directoryPicker)
+lib/subprocess.js   WslSubprocessRuntime (ctx.subprocess) — the terminal window
+lib/auto-preset.js  per-session environment selection
+lib/shell-env.js    DSH_WSL_* environment facts
+lib/{shell,fs}.js   one-line subpath entry points
+cordis.patch.yml    the bundle patch layer (dsh.bundle), with comments
+examples/           a machine-local profile layer, for contrast
+test/               unit tests and the behavioural probes
+docs/archive/       the designs this one replaced, and why
+```
+
+## Testing
+
+```bash
+npm test                  # syntax check + unit tests — dependency-free, runs anywhere
+npm run probe:sandbox     # the bwrap profile's semantics, measured inside the distro
+npm run probe             # filesystem probe against a real distro (Windows + WSL only)
+npm run probe:sandbox-shell  # shell probe: drives the confined executor through a real boot
+npm run probe:terminal    # terminal probe: opens a PTY through the provider
+```
+
+`npm test` covers the pure modules plus a `--check` parse pass over every shipped
+module. It cannot import the service modules: they need DSH peers that a bare
+checkout does not have. That leaves an evaluation-time gap which only booting the
+harness closes — the archived record's §15.4 documents the five rounds of
+misdiagnosis that gap once caused.
+
+`test/probe/sandbox.sh` needs no harness at all: it applies the exact profile
+arguments `lib/sandbox.js` builds and asserts what bubblewrap does and does not
+govern — including the interop escape, which it records as `INFO` rather than a
+failure because a Linux sandbox cannot govern a Windows process.
+
+`test/probe/` drives the seams inside throwaway profiles bound to the distro.
+The filesystem probe asserts the whole publication path — create, read, version
+guard, edit, overwrite, mode preservation, and the two guard rejections — plus
+the fence: a write outside the policy root and a `read-only` write are both
+refused with `FS_SANDBOX_DENIED`, and `danger-full-access` is not fenced. The
+shell probe boots the same profile with the WSL executor mounted and asserts the
+same three modes through `ctx.shell`, including the denial classification the
+tool layer renders. The terminal probe boots the Web profile with the provider in
+place, asks for the same `spawnTerminal` request the GUI makes, and asserts the
+shell it lands in: distro, initial directory, and the `DSH_*` fact forwarded
+through `WSLENV`.
+
+Those probes need a Windows-side profile whose `node_modules/dsh-plugin-wsl-env`
+points at the checkout; `test/probe/run.sh` documents the one-time setup in its
+header, and `terminal.sh` and `sandbox-shell.sh` reuse that same profile.
+
+## Verified
+
+Local, on Windows 11 + WSL2 (Ubuntu 26.04):
+
+- the seam wiring, UNC primitives and picker behaviour, in and out of process;
+- the plugin mounted in a real profile, end to end;
+- a **real model turn** in a WSL-only headless profile:
+  `write → chmod → read → edit → execute`, with the executable bit surviving the
+  edit;
+- the same `write`/`edit` tools in the daily GUI profile;
+- the **terminal provider**, booted in the Web composition:
+  `spawnTerminal({ argv: ["wsl.exe"], cwd: <UNC workspace> })` lands in
+  `ubuntu` as the distro user's login shell (`/usr/bin/zsh`), in the workspace's
+  Linux path, with the request's `DSH_SESSION_ID` forwarded. `npm run
+  probe:terminal` re-runs exactly that, and it is what the throwaway Web boot
+  showed;
+- the same provider **in the daily GUI profile**: pressing *New terminal* starts,
+  from the harness process, exactly
+  `wsl.exe -d ubuntu --cd /home/andy/Projects/dsh/plugins/dsh-plugin-wsl-env`
+  (recorded from the live process table), and the window lands in the distro
+  user's zsh.
+- the **sandbox**, three ways: the profile arguments measured directly in the
+  distro (`npm run probe:sandbox`: a write outside the workspace is refused with
+  EROFS, the sandbox's `/tmp` is ephemeral, `/mnt/c` is read-only, and the
+  interop escape is recorded); the filesystem fence (`npm run probe`: a write
+  outside the policy root and a `read-only` write both refused with
+  `FS_SANDBOX_DENIED`, `danger-full-access` not fenced); and the shell path
+  (`npm run probe:sandbox-shell`: `sandboxMode` advertised, the same three modes
+  through `ctx.shell`, the refusal classified as a denial with
+  `enforcement: partial`).
+- the sandbox **in the daily GUI profile**, from the agent's own session: a
+  command that writes outside the Session workspace is refused inside the distro
+  (`zsh: read-only file system: /home/andy/…`), and the tool layer answers with
+  the escalation hint that `sandbox_permissions` then grants — which is how the
+  runtime mirror gets synced now that its destination sits outside the workspace.
+
+42 unit assertions, 18 filesystem-probe assertions and 10 shell-probe checks
+pass; the bwrap probe adds 10 measured expectations plus the recorded escape, and
+the terminal probe asserts three more.
+
+## Known limitations
+
+- **The sandbox does not govern WSL interop.** A confined distro command can
+  still execute a Windows binary from `/mnt/c`, and that Windows process runs
+  outside bubblewrap under your ordinary token. Closing it would mean denying
+  execution under `/mnt`, which breaks `/mnt/c/…` Sessions; the provider reports
+  `enforcement: partial` for exactly this reason, and `npm run probe:sandbox`
+  re-measures it. Network and process visibility are outside the mode vocabulary
+  on every platform.
+- **`bubblewrap` must be installed in the distro**, and the providers fail
+  closed without it (`SANDBOX_UNAVAILABLE` for every confined command). That is
+  deliberate: the alternative is a silent run without the boundary the model was
+  told it has. `sandbox: false` is the documented opt-out.
+- A `workspace-write` profile binds the workspace root read-write, and bubblewrap
+  refuses a bind whose source does not exist — so a Session whose workspace
+  directory has been deleted fails closed with a runner diagnostic rather than
+  being recreated.
+- Freshly created files get the distro umask default (0644), not an executable
+  bit: a host-side `chmod` over the share is silently ignored. Overwrites and
+  edits *do* preserve the mode. `chmod +x` from inside the distro when needed.
+- Guards are check-then-act, not atomic: this backend checks the caller's guard
+  itself because the host backend's guarded publication uses a hard link the
+  share rejects. The race is the one `dsh-fs-sandbox` already documents.
+- `watch()` is refused outright rather than armed unreliably over 9p.
+- `glob`/`grep` run the host ripgrep over the share: correct, but not fast, and
+  the `.gitignore` semantics are the host's.
+- `editText` reads and rewrites the whole file in memory.
+- The terminal is a **composition** property, not a Session one (see above): a
+  Windows-folder Session gets the distro terminal at `/mnt/<drive>/…`, and the
+  shell menu is deliberately reduced to the one configured profile.
+- The GUI terminal is an interactive shell and is **not** wrapped in the
+  sandbox, exactly like the shipped terminal provider: the mode vocabulary
+  governs command execution and file mutations, not a human's interactive
+  session.
+- Terminal activity reporting stops at `wsl.exe`. The shipped provider's shell
+  integration runs only for a direct `bash`/`zsh` launch on a POSIX host, so a
+  distro terminal reports `unknown` activity and the controller's unattended idle
+  reclamation never fires for it — close the tab to release the process.
+
+## Repository notes
+
+The checkout is developed inside the distro, but the harness is a Windows process
+and a profile can only link a Windows path (`link:\\wsl.localhost\…` is rewritten
+to a broken `/wsl.localhost/…` symlink by pnpm). The Windows copy under
+`default-workspace/dsh-plugin-wsl` is therefore a **runtime mirror**; keep the two
+in sync with `test/probe/sync-to-windows.sh` before launching the app.
+
+That destination is outside every Session workspace, so an agent running the sync
+through a confined shell is refused by the workspace-write policy and has to
+approve `danger-full-access` for that one command. That is the sandbox working as
+described above, not a broken script — run it from a plain distro terminal when
+the prompt is unwelcome.
+
+## License
+
+MIT — see [LICENSE](LICENSE).