dsh-plugin-wsl-env 0.1.0 → 0.1.2

package/CHANGELOG.md

@@ -12,6 +12,61 @@ reference below points at that record's numbering.
 
 ## [Unreleased]
 
+## [0.1.2] - 2026-10-02
+
+### Fixed
+
+- The npm package page rendered the Chinese README instead of the English one. npm
+  chooses a package's readme by globbing `{README,README.*}` in the package root and
+  taking the first `.md` match (`@npmcli/package-json/lib/normalize.js`), so two
+  candidate files made the choice depend on directory enumeration order. 0.1.1
+  shipped with `readmeFilename: README.zh.md`. The translation now lives at
+  `docs/README.zh.md`, which leaves exactly one candidate at the root and removes
+  the ambiguity by construction rather than by luck. The English header still links
+  to it and it still ships in the tarball through `files`. 0.1.1 remains on the
+  registry with the wrong readme; 0.1.2 supersedes it.
+
+## [0.1.1] - 2026-10-02
+
+Documentation only: the README was reorganised for readers and translated into Chinese. No code changed.
+
+### Added
+
+- A Chinese translation of the README, [docs/README.zh.md](docs/README.zh.md), linked from
+  the English header (and back). It is a translation, not the second README that
+  was removed earlier: that file's problem was genre — it called itself the current
+  description while contradicting the English one — whereas these two say the same
+  thing section for section, and the English file remains the only statement of
+  current state. The Chinese text also ships in the package (`files`), so the
+  tarball is readable in either language; npm still renders `README.md`.
+
+### Changed
+
+- The README is reorganised around a reader's path instead of the design log's:
+  "What you get", then Install, Using it, Configure, Sandbox, Troubleshooting —
+  with the two architecture essays moved to *Design notes* at the end. It gains
+  CI/npm/license badges, a section index, a one-paragraph example session, the
+  upgrade command, and a nine-row troubleshooting table. The Configure table was
+  re-checked against the schemas: it now labels which values the shipped patch sets
+  and which are schema defaults, and no longer omits `timeoutMs`/`maxTimeoutMs`
+  or `maxEntries`.
+- The Chinese README was rewritten in plain technical Chinese. The first pass was
+  dense and literary — comma-spliced clauses, dash-heavy sentences, and calques
+  such as 能力事实, 布防 and 围栏 used as a verb — which is what makes a translated
+  document hard to read even when it is accurate. It now averages 61 characters per
+  sentence, keeps the English term beside the Chinese where the term matters
+  (`enforcement`, `escalation`, `interop`), and turns the paragraphs that packed
+  three probes or three facts into one sentence into lists. The section names are
+  plainer too (能做什么 / 使用 / 常见问题 / 设计说明). Nothing factual changed: the
+  two READMEs still match section for section.
+- The English README then got the same treatment, once the Chinese rewrite made the
+  problem obvious in both languages. A single "what has been verified" sentence ran
+  to 125 words; the sandbox section explained itself with asides ("and that is the
+  honest part", "stated rather than papered over"); and terms such as *composition*,
+  *capability fact*, *isolate realm* and *fence* (as a verb) appeared before they
+  were explained. The prose now averages 15 words a sentence with a 42-word maximum,
+  the verification list is a list, and each term is glossed where it first appears.
+
 ## [0.1.0] - 2026-10-02
 
 First release. A WSL distro can be picked as a workspace, read and written
@@ -193,7 +248,7 @@ 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/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
@@ -223,7 +278,7 @@ freshly created files.
 
 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
+- The repository briefly carried two READMEs. `docs/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

package/README.md

@@ -1,314 +1,216 @@
 # 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.
+**English** · [中文](docs/README.zh.md)
 
-> 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.
+[![CI](https://github.com/Big-Dao/dsh-plugin-wsl-env/actions/workflows/ci.yml/badge.svg)](https://github.com/Big-Dao/dsh-plugin-wsl-env/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/dsh-plugin-wsl-env)](https://www.npmjs.com/package/dsh-plugin-wsl-env)
+[![license](https://img.shields.io/npm/l/dsh-plugin-wsl-env)](LICENSE)
 
-## What it does
+This plugin lets [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) use a WSL distro as its working environment. Commands run inside the distro. The model's file tools read and write real distro files. The folder picker can open a distro folder directly, and the GUI terminal also opens inside the distro instead of `cmd.exe` on a UNC path.
 
-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:
+**Windows + WSL2 only.** Installation is one command, and the plugin has no dependencies of its own. The WSL environment applies per session, so a session opened on a Windows folder keeps its normal Windows environment.
 
-| 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 |
+[What you get](#what-you-get) · [Install](#install) · [Using it](#using-it) ·
+[Configure](#configure) · [Sandbox](#sandbox) · [Troubleshooting](#troubleshooting) ·
+[Limitations](#limitations) · [Development](#development) · [Design notes](#design-notes)
 
-It also ships three smaller integrations:
+## What you get
 
-| Package | Provides |
+| Before | After |
 |---|---|
-| `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:
+| Commands run on Windows | Commands run **inside your distro**, using your login shell, starting in the session's Linux directory |
+| `read`/`write`/`edit`/`glob`/`grep` work on Windows paths | These tools work on **the distro's real files**, through the `\\wsl.localhost\<distro>` share |
+| The folder picker cannot see WSL | One picker lists the Windows home directory and every installed distro, so you can open `/home/you/project` |
+| The terminal opens `cmd.exe` in a UNC directory | The terminal opens **inside the distro**, in the session's directory, as your distro user |
+| Commands have no sandbox | Commands are confined by **bubblewrap inside the distro**; see [Sandbox](#sandbox) |
+
+If you open a session on a folder inside a distro, the WSL environment applies automatically. The `wsl` preset is bound while the session is created, so the first tool call already runs in the distro. You do not switch anything by hand.
+
+**How to check that it works.** Ask the model to run `uname -r`. The output should be a WSL2 kernel such as `6.18.40.1-microsoft-standard-WSL2`. You can also run `echo $WSL_DISTRO_NAME`.
+
+## Install
+
+Run these four commands in a Windows terminal:
 
+```powershell
+dsh wsl --from-default-profile web --dump-config   # 1. create the profile from the Web template
+dsh plugin --profile wsl add dsh-plugin-wsl-env    # 2. install the code and its configuration layer
+dsh --profile wsl --dump-config                    # 3. compose only, no boot (the fast check)
+dsh --profile wsl                                  # 4. run
 ```
+
+Step 3 should print a layer named `# == dsh-plugin-wsl-env`, plus the rows that layer changes. The most important row is `- id: terminal-controller`, which should now carry `shell: { path: wsl.exe, name: WSL }`.
+
+Then open a folder under `\\wsl.localhost\<distro>\...` in the GUI. The picker lists every installed distro at its root level. You can also just press **New terminal**.
+
+The package is a DSH **bundle**. It declares `dsh.bundle.patch`, so step 2 applies [`cordis.patch.yml`](cordis.patch.yml) as a configuration layer. You do not merge any patch by hand. Step 1 uses the Web template because this layer overrides rows that only the Web surface has: the app-wide `subprocess` provider, the terminal controller and the directory picker.
+
+You also need **bubblewrap inside the distro** (`sudo apt install bubblewrap`). Without it every command fails immediately. See [Sandbox](#sandbox).
+
+Uninstall: `dsh plugin --profile wsl remove dsh-plugin-wsl-env`.
+
+Upgrade: run `dsh plugin --profile wsl add dsh-plugin-wsl-env` again. The new version replaces the old configuration layer with its own.
+
+> **If you change `lib/` in a checkout, restart the app.** A running process caches ES modules and keeps using the old code until you do.
+
+## Using it
+
+A typical session: open `\\wsl.localhost\ubuntu\home\you\project` as the workspace, then ask "what kernel am I on, and what is in `/etc/os-release`?". The model runs `uname -r` and reads that file inside the distro. Nothing goes through `/mnt/c`, and no files are copied.
+
+- **Open a distro folder.** The picker lists the Windows home directory and one entry per distro. If you pick `\\wsl.localhost\ubuntu\home\you\project`, the session workspace, the shell's working directory and the terminal all follow it.
+- **Commands** run as `wsl.exe -d <distro> --cd <linux dir> --exec <your login shell> -lc <command>`. Your `PATH`, `nvm`, `cargo`, `pyenv` and rc files therefore 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.
+- **The model can see its shell environment.** The plugin registers `DSH_WSL_DISTRO`, `DSH_WSL_SHELL` and `DSH_WSL_HOME` in the managed `DSH_*` namespace, and the shell tool points the model at them.
+- **Permissions work as they do on a Linux host.** The Permissions selector switches between `read-only`, `workspace-write` (the default) and `danger-full-access`. When a command or a write is refused, the tool offers to run it with wider permissions. If you approve, that single call runs without the sandbox.
+
+## Configure
+
+To change a value, override that row by id in your own profile layer. The file is `$DSH_HOME/profiles/<name>/cordis.patch.yml`; see [`examples/profile.cordis.patch.yml`](examples/profile.cordis.patch.yml). In the table below, *(shipped)* marks the values set by [`cordis.patch.yml`](cordis.patch.yml). The others are schema defaults, listed because they are worth knowing.
+
+| Row | Key | Default | Meaning |
+|---|---|---|---|
+| `wsl-shell` | `distro` | `''` *(shipped)* | distro name; empty means WSL's default distro |
+| | `shell` | `''` | pin a shell inside the distro; empty means the user's login shell |
+| | `loginShell` | `true` *(shipped)* | use `<shell> -lc`, which sources your profile, instead of a bare `-c` |
+| | `sandbox` | `true` | confine commands with `bubblewrap`; `false` disables the sandbox |
+| | `cwd` | `''` | default working directory; empty means the distro user's home |
+| | `timeoutMs` / `maxTimeoutMs` | `120000` / `600000` *(shipped)* | per-call time limit, and the ceiling a call may ask for |
+| `wsl-fs` | `distro` | `''` *(shipped)* | as above |
+| | `restrictToDistro` | `true` *(shipped)* | refuse paths outside the pinned distro, including `/mnt/c` |
+| | `sandbox` | `true` | check `writeText` and `editText` against the policy |
+| | `resolveSymlinks` | `true` | follow Linux symlinks that the share cannot traverse, such as `/etc/os-release` and `/bin` |
+| | `cwd` | `''` | base directory for relative paths; empty means the distro user's home |
+| `directory-picker-wsl` | `preferredDistro` | `''` *(shipped)* | the distro listed first in the picker |
+| | `includeHostHome` | `true` *(shipped)* | also list the Windows home directory |
+| | `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 |
+
+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, `diffBasisMaxBytes` on `wsl-fs`, and `distroCacheMs` on the picker.
+
+## Sandbox
+
+**In short:** commands are confined by `bubblewrap` inside the distro, and writes are checked against the same policy. The reported enforcement level is `partial`, not `full`, because a process inside the distro can still reach Windows through WSL interop. `bubblewrap` must be installed; without it the plugin refuses to run rather than run unconfined.
+
+On Windows, DSH confines commands with `dsh-sandbox-windows-acl`. It uses a restricted, low-integrity Windows token and an allowlist of writable paths. **That token cannot reach WSL.** `wsl.exe` fails with `Wsl/E_ACCESSDENIED`, and `\\wsl.localhost\<distro>` reports access denied, while both work normally outside the sandbox. The WSL environment therefore cannot reuse the Windows sandbox and uses a Linux sandbox instead. The plugin builds the `bubblewrap` arguments on the Windows side and passes them to `wsl.exe --exec`, which runs them inside the distro:
+
+```text
 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:
+These are the same arguments DSH uses on a Linux host (`dsh-sandbox-local`), so the behaviour and the error messages match.
 
-| Mode | What the distro command gets |
+| Mode | What a command inside the distro can do |
 |---|---|
-| `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
+| `read-only` | read the whole distro; only `/dev/null` is writable, which a shell needs |
+| `workspace-write` | the above, plus the session workspace is writable and `/tmp` is a temporary mount |
+| `danger-full-access` | no sandbox at all, used for an approved wider-permission request |
 
-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:
+`WslFileSystem` checks writes against the same policy and the same writable list. That avoids a mismatch where `bash` could write `/tmp` but the write tool could not. Both providers report their current mode through `sandboxMode`, which is what brings back the Permissions selector and the "refused, then request wider permissions" flow.
 
-```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
-```
+**Why the level is `partial`, not `full`.** A process inside the distro can run a Windows program through interop, for example `/mnt/c/.../*.exe`. That is not a Linux process, so bubblewrap does not govern it. It runs with your normal Windows token and can write anywhere you can. `npm run probe:sandbox` demonstrates this, and every run of that probe checks it again. Closing the hole would mean denying execution of programs under `/mnt`. That would also break sessions whose workspace is `/mnt/c/...`, so the hole stays open and is documented here. Network and process visibility are outside the scope of this mode on every platform.
 
-`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.
+**`bubblewrap` is required, and the failure is closed.** Without it, every confined command reports `SANDBOX_UNAVAILABLE`. The plugin does not fall back to running without a sandbox, and the `sandboxMode` value disappears too, so it never claims to confine when it cannot. If you do not want a sandbox, set `sandbox: false` on either provider. Commands then run unconfined, `sandboxMode` returns `undefined`, and the tool layer tells the model that these operations have no sandbox.
 
-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.
+**The GUI terminal is not sandboxed.** It is an interactive shell for a person, which matches the shipped terminal provider.
 
-> A running process caches ES modules. **Restart the app after changing `lib/`**,
-> or the old code stays loaded.
+## Troubleshooting
 
-## Layout
+| Symptom | Cause | Fix |
+|---|---|---|
+| every command reports `SANDBOX_UNAVAILABLE` | `bubblewrap` is not installed in the distro | run `sudo apt install bubblewrap`, or set `sandbox: false` on both providers |
+| a command or write is refused outside the session folder | expected behaviour of `workspace-write` | accept the wider-permission offer, or open a session on the folder you need |
+| writes are refused even inside the workspace | the session is in `read-only` mode | switch the Permissions selector |
+| `dsh plugin add` warns that no layer was activated | the dependency was already installed, so `add` had nothing to record | run `dsh plugin --profile wsl remove dsh-plugin-wsl-env`, then add it again |
+| the terminal still opens `cmd.exe` | the `terminal-controller` row from the layer did not apply | check that `dsh --profile wsl --dump-config` shows `shell: { path: wsl.exe, name: WSL }` |
+| changes to `lib/` have no effect | ES module cache | restart the app |
+| `link:\\wsl.localhost\...` leaves a broken symlink | pnpm cannot link a UNC path | link a Windows path instead; developing inside the distro needs the runtime mirror, see [Development](#development) |
+| `glob` and `grep` are slow | the Windows-side ripgrep walks the 9p share | expected; narrow the path, or use `bash` to call tools inside the distro |
+| the terminal reports `unknown` activity | shell integration only covers `bash`/`zsh` started directly on a POSIX host | close the tab to release the process; idle reclamation does not run for these terminals |
+
+## Limitations
+
+- **The sandbox does not govern WSL interop.** A confined command can still run a Windows program, which escapes the Linux-side boundary. The plugin reports this as `enforcement: partial`. See [Sandbox](#sandbox).
+- **`bubblewrap` must be installed**, or both providers fail immediately.
+- `workspace-write` binds the workspace root as writable, and bubblewrap refuses a bind whose source directory does not exist. If a session's workspace directory is deleted, commands fail with a runner error; the plugin does not recreate the directory.
+- New files get the distro's umask default (0644). A `chmod` from the Windows side on a share path is silently ignored; overwrites and edits keep the original permission bits. Run `chmod +x` inside the distro when you need an executable.
+- 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.
+- `watch()` (file change monitoring) is not provided. Watching a 9p share is unreliable, so the plugin refuses instead of arming it.
+- `glob` and `grep` use the Windows-side ripgrep over the share: correct results, but not fast, and `.gitignore` is interpreted with Windows rules. `editText` reads the whole file into memory before writing it back.
+- The terminal belongs to the whole app, not to one session. A session opened on a Windows folder still gets the distro terminal, starting in `/mnt/<drive>/...`, and its shell menu is deliberately reduced to the one configured profile.
+- Terminal activity reporting stops at `wsl.exe`, so the controller never reclaims these terminals when they are idle.
+
+## Development
 
+```bash
+npm test                     # syntax check and unit tests; no dependencies, runs anywhere
+npm run probe:sandbox        # measure inside the distro what bubblewrap does and does not confine
+npm run probe                # filesystem probe against a real distro (Windows + WSL only)
+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
 ```
-lib/paths.js        pure path translation between the three coordinate systems
+
+Layout:
+
+```text
+lib/paths.js        pure conversion between the three path formats
 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/listing.js      pure directory listing and breadcrumb helpers (no DSH imports)
+lib/index.js        WslShellExecutor (ctx.shell) and WslFileSystem (ctx.fs)
+lib/sandbox.js      the distro-side bwrap confinement shared by both providers
 lib/picker.js       WslDirectoryPicker (ctx.directoryPicker)
-lib/subprocess.js   WslSubprocessRuntime (ctx.subprocess) — the terminal window
+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-env.js    registers the DSH_WSL_* environment variables
 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
+cordis.patch.yml    the bundle configuration layer (dsh.bundle), commented
+examples/           one machine-local profile layer, for comparison
+test/               unit tests and behaviour probes
 docs/archive/       the designs this one replaced, and why
 ```
 
-## Testing
+`npm test` covers the pure modules and runs a `--check` syntax pass over every shipped module. It cannot import the service modules, because those need DSH peer packages that a bare checkout does not have. Only booting the harness closes that gap; the archived record's §15.4 documents the five rounds of misdiagnosis it once caused.
 
-```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
-```
+`test/probe/sandbox.sh` needs no harness. It uses the same arguments that `lib/sandbox.js` builds, and asserts what bubblewrap does and does not confine. It records the interop escape as `INFO`, because a Linux sandbox cannot govern a Windows process.
+
+The other probes boot a throwaway profile bound to the distro:
+
+- The filesystem probe asserts the write path and the write checks. A write outside the policy root, and a write in `read-only` mode, both return `FS_SANDBOX_DENIED`; `danger-full-access` is not checked.
+- The shell probe drives all three modes through `ctx.shell` and checks the refusal classification that the tool layer returns.
+- The terminal probe asserts the distro, the starting directory, and the `DSH_*` variables forwarded through `WSLENV`.
+
+The setup steps for the throwaway profile are in the header of `test/probe/run.sh`; `terminal.sh` and `sandbox-shell.sh` reuse it.
+
+**What has been verified** on Windows 11 + WSL2 (Ubuntu 26.04):
+
+- the wiring of each service, the UNC path handling and the picker behaviour;
+- the plugin mounted end to end in a real profile;
+- one real model turn in a WSL-only headless profile: `write → chmod → read → edit → execute`, with the executable bit surviving the edit;
+- the terminal provider in a throwaway Web boot and in the daily GUI profile;
+- the sandbox in four ways: the arguments measured inside the distro, the filesystem write checks, the shell path (`enforcement: partial`, with refusals classified correctly), and the daily GUI profile, where a write from the agent's own session outside the session workspace is refused inside the distro and the following wider-permission request succeeds.
+
+Counts: 42 unit assertions, 18 filesystem-probe assertions, 10 shell-probe checks, 10 sandbox expectations plus the recorded escape, and 3 terminal assertions.
+
+**The runtime mirror.** The checkout is developed inside the distro, but the harness is a Windows process, and a profile can only link a Windows path: pnpm rewrites `link:\\wsl.localhost\...` into a broken `/wsl.localhost/...` symlink. The Windows copy at `default-workspace/dsh-plugin-wsl` is therefore a runtime mirror. Sync it with `test/probe/sync-to-windows.sh` before launching the app. That destination is outside every session workspace, so an agent running the sync in a confined shell is refused by `workspace-write` and must approve `danger-full-access` for that one command. That is the sandbox behaving as designed, not a broken script; run the sync from a normal distro terminal if you prefer not to see the prompt.
+
+**CI** runs `npm test` on Linux with Node 20, 22 and 24.
+
+## Design notes
+
+Two decisions are not visible in the profile YAML. The full reasoning, the measurements and every rejected design are in the archived engineering record: [docs/archive/engineering-record.zh.md](docs/archive/engineering-record.zh.md). It is a historical document, not a second README; if it disagrees with this file, this file is correct.
+
+**Why the terminal provider is app-wide.** `ctx.shell` and `ctx.fs` are provided per session, inside the isolated scope of the `wsl` agent preset. A workspace on Windows therefore keeps the shipped sandboxed PowerShell environment, while a WSL workspace gets the distro. Both can exist in one process at the same time.
+
+The terminal cannot be provided that way. `dsh-api-terminal-controller` looks up its environment with `agent.ctx.get("subprocess")`. An Agent's context is created by the agent loop under the **root** scope, while a preset's isolated scope is created by `dsh-agent-preset-registry` under the registry's own context. These two scope chains never meet, so a `subprocess` provider mounted inside `preset-wsl` is invisible to the terminal window.
+
+For that reason, [`cordis.patch.yml`](cordis.patch.yml) replaces the **app-wide** `subprocess` row with a subclass that overrides only `spawnTerminal`. Ordinary `spawn()`, the Windows-side ripgrep search, the pwsh executor and the LSP host still use the shipped implementation. The cost is that the terminal follows the app configuration rather than the session; see [Limitations](#limitations).
 
-`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.
+**Why the sandbox is on the Linux side.** The Windows ACL runner's restricted token cannot reach WSL at all, so the confinement has to be built on the Windows side and run inside the distro. `lib/sandbox.js` copies the Linux `bwrap` approach from `dsh-sandbox-local` instead of using `ctx.sandbox`. `dsh-tool-bash` never asks for `ctx.sandbox` anyway: it reads the executor's `sandboxMode` and `ctx.sandboxPolicy`, and this plugin supplies both.
 
 ## License
 
-MIT — see [LICENSE](LICENSE).
+MIT. See [LICENSE](LICENSE).

package/docs/README.zh.md

@@ -0,0 +1,214 @@
+# dsh-plugin-wsl-env
+
+[English](../README.md) · **中文**
+
+[![CI](https://github.com/Big-Dao/dsh-plugin-wsl-env/actions/workflows/ci.yml/badge.svg)](https://github.com/Big-Dao/dsh-plugin-wsl-env/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/dsh-plugin-wsl-env)](https://www.npmjs.com/package/dsh-plugin-wsl-env)
+[![license](https://img.shields.io/npm/l/dsh-plugin-wsl-env)](../LICENSE)
+
+这个插件让 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 直接把 WSL 发行版当作工作环境使用。命令在发行版里执行，模型的文件工具读写发行版里的真实文件，打开文件夹时可以直接选择发行版目录，GUI 终端也开在发行版里，而不是开在 UNC 路径下的 `cmd.exe`。
+
+**只支持 Windows + WSL2。** 安装只有一条命令，插件自身没有依赖。WSL 环境按会话生效：会话如果打开的是 Windows 文件夹，它继续使用原来的 Windows 环境，不受影响。
+
+目录：[能做什么](#能做什么) · [安装](#安装) · [使用](#使用) · [配置](#配置) · [沙箱](#沙箱) · [常见问题](#常见问题) · [已知限制](#已知限制) · [开发](#开发) · [设计说明](#设计说明)
+
+## 能做什么
+
+| 原来的行为 | 现在的行为 |
+|---|---|
+| 命令在 Windows 上执行 | 命令在**你的发行版里**执行，使用你的登录 shell，起始目录是会话的 Linux 目录 |
+| `read`/`write`/`edit`/`glob`/`grep` 操作 Windows 路径 | 这些工具直接操作**发行版里的真实文件**，路径经由 `\\wsl.localhost\<发行版名>` 共享访问 |
+| 文件夹选择器看不到 WSL | 同一个选择器既列出 Windows 家目录，也列出每个已安装的发行版，可以直接打开 `/home/you/project` |
+| 终端开在 UNC 目录下的 `cmd.exe` | 终端开在**发行版里**的会话目录，身份是你的发行版用户 |
+| 命令没有沙箱约束 | 命令由**发行版内的 bubblewrap** 约束，见[沙箱](#沙箱)一节 |
+
+如果会话打开的是发行版里的文件夹，WSL 环境会自动生效：创建会话时就会绑定 `wsl` preset，所以第一次调用工具时环境已经正确，不需要手动切换。
+
+**怎么确认它在工作？** 让模型执行 `uname -r`，输出的应该是 WSL2 内核，例如 `6.18.40.1-microsoft-standard-WSL2`。也可以执行 `echo $WSL_DISTRO_NAME`。
+
+## 安装
+
+在 Windows 终端里执行这四条命令：
+
+```powershell
+dsh wsl --from-default-profile web --dump-config   # 1. 用 Web 模板创建 profile
+dsh plugin --profile wsl add dsh-plugin-wsl-env    # 2. 安装代码和配置层
+dsh --profile wsl --dump-config                    # 3. 只做组合检查，不启动（最快）
+dsh --profile wsl                                  # 4. 启动
+```
+
+第 3 步应该能看到 `# == dsh-plugin-wsl-env` 这一层，以及被它覆盖的行，其中最关键的是 `- id: terminal-controller` 上的 `shell: { path: wsl.exe, name: WSL }`。
+
+然后在 GUI 里打开 `\\wsl.localhost\<发行版名>\...` 下的文件夹（选择器会在根一级列出每个发行版），或者直接点 **New terminal**。
+
+这个包是一个 DSH bundle：`package.json` 里声明了 `dsh.bundle.patch`，所以第 2 步会把 [`cordis.patch.yml`](../cordis.patch.yml) 作为配置层加入，不需要手工合并补丁。第 1 步用 Web 模板创建 profile，原因是这一层要覆盖几个只有 Web 界面才有的行：组合层的 `subprocess` provider、终端控制器和文件夹选择器。
+
+还需要在发行版里安装 **bubblewrap**（`sudo apt install bubblewrap`）。没有它时每条命令都会直接失败，原因见[沙箱](#沙箱)。
+
+卸载：`dsh plugin --profile wsl remove dsh-plugin-wsl-env`。
+
+升级：再执行一次 `dsh plugin --profile wsl add dsh-plugin-wsl-env`，新版本会用自带的配置层替换旧层。
+
+> **如果改的是 checkout 里的 `lib/`，必须重启应用。** 运行中的进程会缓存 ES module，不重启就还在用旧代码。
+
+## 使用
+
+一个典型用法：把 `\\wsl.localhost\ubuntu\home\you\project` 作为工作区打开，然后问"当前内核版本是什么，`/etc/os-release` 里有什么"。模型会直接在发行版里执行 `uname -r` 并读取该文件，不需要经过 `/mnt/c`，也不需要复制文件。
+
+- **打开发行版文件夹**：选择器列出 Windows 家目录和每个发行版。选择 `\\wsl.localhost\ubuntu\home\you\project` 之后，会话工作区、shell 的起始目录和终端都会跟着它。
+- **命令**以 `wsl.exe -d <发行版> --cd <Linux 目录> --exec <你的登录 shell> -lc <命令>` 的形式执行，所以你的 `PATH`、`nvm`、`cargo`、`pyenv` 和 rc 配置都会生效，而不是固定使用 bash。
+- **文件**就是发行版里的真实文件：`/home/you/x` 和 `\\wsl.localhost\ubuntu\home\you\x` 指向同一个文件，`/mnt/c/...` 指向 Windows 磁盘。
+- **终端**（右侧栏 → New terminal）在发行版里打开会话目录下的 shell。
+- **模型知道自己的 shell 环境**：插件向受管的 `DSH_*` 命名空间注册了 `DSH_WSL_DISTRO`、`DSH_WSL_SHELL` 和 `DSH_WSL_HOME`，shell 工具会引导模型读取这些变量。
+- **权限**和在 Linux 主机上一致：权限选择器可在 `read-only`、`workspace-write`（默认）和 `danger-full-access` 之间切换。命令或写入被拒绝时，工具会给出放宽权限的提示；批准后，这一次调用会在不加沙箱的情况下执行。
+
+## 配置
+
+修改配置的方式是在自己的 profile 层里按 id 覆盖某一行。文件是 `$DSH_HOME/profiles/<名字>/cordis.patch.yml`，示例见 [`examples/profile.cordis.patch.yml`](../examples/profile.cordis.patch.yml)。下表中标了 *(shipped)* 的值是 [`cordis.patch.yml`](../cordis.patch.yml) 里实际设置的值，其余是 schema 的默认值，列出来是因为它们比较常用。
+
+| 行 | 键 | 默认值 | 说明 |
+|---|---|---|---|
+| `wsl-shell` | `distro` | `''` *(shipped)* | 发行版名；空表示用 WSL 的默认发行版 |
+| | `shell` | `''` | 指定发行版内的 shell；空表示用该用户的登录 shell |
+| | `loginShell` | `true` *(shipped)* | 用 `<shell> -lc`（会加载你的 profile），而不是裸 `-c` |
+| | `sandbox` | `true` | 用 `bubblewrap` 约束命令；`false` 表示不用沙箱 |
+| | `cwd` | `''` | 默认工作目录；空表示发行版用户的家目录 |
+| | `timeoutMs` / `maxTimeoutMs` | `120000` / `600000` *(shipped)* | 单次调用的时限，以及调用方可以申请的上限 |
+| `wsl-fs` | `distro` | `''` *(shipped)* | 同上 |
+| | `restrictToDistro` | `true` *(shipped)* | 拒绝发行版之外的路径（包括 `/mnt/c`） |
+| | `sandbox` | `true` | 写入时按策略检查 `writeText` 和 `editText` |
+| | `resolveSymlinks` | `true` | 跟随共享层无法穿越的 Linux 符号链接，例如 `/etc/os-release`、`/bin` |
+| | `cwd` | `''` | 相对路径的基准目录；空表示发行版用户的家目录 |
+| `directory-picker-wsl` | `preferredDistro` | `''` *(shipped)* | 在选择器里排在第一位的发行版 |
+| | `includeHostHome` | `true` *(shipped)* | 同时列出 Windows 家目录 |
+| | `maxEntries` | `1000` *(shipped)* | 单个目录最多列出多少条 |
+| `subprocess-wsl` | `distro` | `''` *(shipped)* | GUI 终端开在哪个发行版 |
+| | `shell` | `''` | 指定 shell；空表示由 `wsl.exe` 决定 |
+| | `loginShell` | `true` | 指定 shell 时是否使用登录语义 |
+
+其余键也可以用同样的方式覆盖，默认值不变：shell 和终端行的 `wslPath`、`hostCwd`、`forwardEnv`；`wsl-fs` 的 `diffBasisMaxBytes`；选择器的 `distroCacheMs`。
+
+## 沙箱
+
+**简单说：** 命令在发行版内由 `bubblewrap` 约束，文件写入按同一份策略检查。但约束范围报为 `partial`（部分生效），因为发行版里的进程仍然可以通过 WSL interop 访问 Windows。bubblewrap 必须安装；缺少它时插件会直接拒绝执行，而不是静默地不加约束。
+
+在 Windows 上，DSH 用 `dsh-sandbox-windows-acl` 约束命令：它使用受限的低完整性令牌和写入白名单。这个令牌**完全无法访问 WSL**：`wsl.exe` 会报 `Wsl/E_ACCESSDENIED`，`\\wsl.localhost\<发行版名>` 会报拒绝访问，而在沙箱之外两者都正常。所以 WSL 执行环境无法沿用 Windows 沙箱，改用 Linux 沙箱：插件在 Windows 侧拼出 bubblewrap 的参数，交给 `wsl.exe --exec` 在发行版内执行。
+
+```text
+wsl.exe -d <发行版> --cd <Linux 目录> --exec bwrap \
+  --ro-bind / / --dev /dev --unshare-pid --proc /proc --die-with-parent \
+  [--tmpfs /tmp --bind <工作区> <工作区>]  --  <shell> -lc <命令>
+```
+
+这套参数与 DSH 自带的 Linux 方案（`dsh-sandbox-local`）逐参数一致，所以行为和错误信息都与在 Linux 主机上运行相同。
+
+| 模式 | 发行版里的命令得到什么 |
+|---|---|
+| `read-only` | 整个发行版只读，只有 `/dev/null` 可写，这是 shell 必需的 |
+| `workspace-write` | 在上一行基础上，把会话工作区绑定为可写，并把 `/tmp` 挂成临时目录 |
+| `danger-full-access` | 完全不加包装，用于批准后的放宽权限请求 |
+
+`WslFileSystem` 在写入路径上使用同一份策略和同一批可写目录，所以不会出现"bash 能写 `/tmp`，但写工具不能"这种不一致。两个 provider 都通过 `sandboxMode` 上报当前模式，权限选择器和"被拒绝 → 申请放宽权限"的流程因此恢复。
+
+**约束范围是 `partial`，不是 `full`，这一点必须说明。** 发行版里的进程仍然可以通过 interop 执行 Windows 程序（`/mnt/c/.../*.exe`）。那不是 Linux 进程，bubblewrap 管不到它；它以你平常的 Windows 令牌运行，能写你有权限写的任何位置。`npm run probe:sandbox` 会实际演示这一点，并且以后每次运行都会再确认一次。要堵住这个缺口，就必须禁止执行 `/mnt` 下的程序，而那会同时切断 `/mnt/c/...` 会话，所以这里如实说明，不做掩盖。网络和进程可见性在所有平台上都不属于这个模式的管辖范围。
+
+**bubblewrap 是必需项，缺少时会直接失败。** 没有它时，每条受约束的命令都会报 `SANDBOX_UNAVAILABLE`，不会退化成不加约束地执行；同时 `sandboxMode` 也不再上报，避免出现"声称有沙箱、实际没有"的情况。确实不想用沙箱时，可以在任一 provider 上设 `sandbox: false`：命令会不加约束地执行，`sandboxMode` 返回 `undefined`，工具层会如实告诉模型这些操作没有沙箱。
+
+**GUI 终端不受沙箱约束。** 它是给人用的交互式 shell，与官方终端 provider 的行为一致。
+
+## 常见问题
+
+| 现象 | 原因 | 处理 |
+|---|---|---|
+| 每条命令都报 `SANDBOX_UNAVAILABLE` | 发行版里没有 `bubblewrap` | 执行 `sudo apt install bubblewrap`，或在两个 provider 上都设 `sandbox: false` |
+| 命令或写入在会话目录之外被拒绝 | `workspace-write` 的预期行为 | 接受工具给出的放宽权限提示，或把会话直接开在需要的目录上 |
+| 连工作区内的写入也被拒绝 | 会处在 `read-only` 模式 | 切换权限选择器 |
+| `dsh plugin add` 提示"没有激活任何层" | 依赖之前已经装过，`add` 没有需要记录的内容 | 先执行 `dsh plugin --profile wsl remove dsh-plugin-wsl-env`，再装一次 |
+| 终端打开后仍然是 `cmd.exe` | 这一层里的 `terminal-controller` 行没有生效 | 用 `dsh --profile wsl --dump-config` 确认能看到 `shell: { path: wsl.exe, name: WSL }` |
+| 改了 `lib/` 但不生效 | ES module 缓存 | 重启应用 |
+| 用 `link:\\wsl.localhost\...` 安装后符号链接是坏的 | pnpm 无法链接 UNC 路径 | 改成链接 Windows 路径；在发行版内开发时用运行时镜像，见[开发](#开发) |
+| `glob`/`grep` 很慢 | Windows 侧的 ripgrep 在 9p 共享上遍历 | 属于预期，收窄搜索路径，或改用 `bash` 调用发行版内的工具 |
+| 终端活动显示 `unknown` | 官方 shell 集成只对 POSIX 主机上直接启动的 `bash`/`zsh` 生效 | 关闭标签页以释放进程；空闲回收不会对它触发 |
+
+## 已知限制
+
+- **沙箱管不到 WSL interop**，见[沙箱](#沙箱)：受约束的命令仍然可以运行 Windows 程序，从而超出 Linux 侧的约束范围。插件把这种情况报为 `enforcement: partial`。
+- **必须安装 `bubblewrap`**，否则两个 provider 都会直接失败。
+- `workspace-write` 会把工作区根目录绑定为可写，而 bubblewrap 不允许绑定的源目录不存在。所以如果会话的工作区目录被删掉，命令会因 runner 报错而失败，插件不会替你重建目录。
+- 新建文件的权限是发行版的 umask 默认值（0644）。在 Windows 侧对共享路径执行 `chmod` 会被静默忽略；覆盖和编辑会保留原有权限位。需要可执行权限时，请在发行版内执行 `chmod +x`。
+- 写入前的检查是"先检查再写入"，不是原子操作。本后端自己检查调用方的守卫，因为 Windows 后端发布受守卫保护的新建文件时使用硬链接，而共享层不支持硬链接。这是 `dsh-fs-sandbox` 已经记录过的竞态。
+- 不提供 `watch()`（文件变更监视）。9p 共享上的监视不可靠，所以直接拒绝，而不是勉强启用。
+- `glob`/`grep` 使用 Windows 侧的 ripgrep 在共享路径上搜索：结果正确，但速度不快，`.gitignore` 规则也按 Windows 侧的规则处理。`editText` 会把整个文件读入内存后再写回。
+- 终端属于整个应用（组合层），不属于单个会话。所以工作在 Windows 文件夹的会话也会打开发行版终端，起始目录是 `/mnt/<盘符>/...`，并且它的 shell 菜单被有意缩减为配置里的那一个。
+- 终端活动状态的上报止步于 `wsl.exe`，所以控制器不会对这些终端触发空闲回收。
+
+## 开发
+
+```bash
+npm test                     # 语法检查 + 单元测试，无依赖，任何平台都能跑
+npm run probe:sandbox        # 在发行版里实测 bubblewrap 能约束什么、不能约束什么
+npm run probe                # 文件系统探针，需要真实发行版（仅 Windows + WSL）
+npm run probe:sandbox-shell  # 启动真实 harness，驱动受限执行器
+npm run probe:terminal       # 通过终端 provider 打开一个 PTY
+```
+
+目录结构：
+
+```text
+lib/paths.js        三套路径写法之间的纯转换函数
+lib/wsl.js          wsl.exe 互操作原语（不 import DSH）
+lib/listing.js      目录列举与面包屑的纯函数（不 import DSH）
+lib/index.js        WslShellExecutor（ctx.shell）和 WslFileSystem（ctx.fs）
+lib/sandbox.js      两个 provider 共用的发行版内 bwrap 约束
+lib/picker.js       WslDirectoryPicker（ctx.directoryPicker）
+lib/subprocess.js   WslSubprocessRuntime（ctx.subprocess），即终端窗口
+lib/auto-preset.js  按会话选择环境
+lib/shell-env.js    注册 DSH_WSL_* 环境变量
+lib/{shell,fs}.js   各一行的子路径入口
+cordis.patch.yml    bundle 配置层（dsh.bundle），带逐行注释
+examples/           一份本机 profile 层，作为对照
+test/               单元测试和行为探针
+docs/archive/       被本设计替换掉的方案，以及原因
+```
+
+`npm test` 覆盖纯模块，并对每个随包模块执行一次 `--check` 语法检查。它无法 import 服务类模块，因为这些模块需要 DSH 的 peer 包，而裸 checkout 里没有。这个缺口只有在真正启动 harness 时才会暴露；归档记录 §15.4 记录了它曾经导致的五轮误诊。
+
+`test/probe/sandbox.sh` 不需要 harness：它使用 `lib/sandbox.js` 生成的同一套参数，断言 bubblewrap 能约束什么、不能约束什么，并把 interop 逃逸记为 `INFO`，因为 Linux 沙箱管不了 Windows 进程。
+
+其余探针会启动绑定到发行版的一次性 profile：
+
+- 文件系统探针断言写入路径和写入检查。策略根目录之外、以及 `read-only` 模式下的写入都会返回 `FS_SANDBOX_DENIED`，`danger-full-access` 不做检查。
+- shell 探针通过 `ctx.shell` 驱动三种模式，并检查工具层返回的拒绝分类。
+- 终端探针断言发行版、起始目录，以及经 `WSLENV` 转发的 `DSH_*` 变量。
+
+一次性 profile 的搭建步骤写在 `test/probe/run.sh` 的头部；`terminal.sh` 和 `sandbox-shell.sh` 复用它。
+
+**已验证**（Windows 11 + WSL2，Ubuntu 26.04）：
+
+- 与各服务接入点的对接、UNC 路径处理和选择器行为；
+- 插件在真实 profile 里端到端挂载；
+- 在仅 WSL 的 headless profile 里完成一次真实模型回合：`write → chmod → read → edit → execute`，编辑后可执行权限仍然保留；
+- 终端 provider 在一次性 Web 启动和日常 GUI profile 中都成立；
+- 沙箱用四种方式验证：在发行版里实测参数、文件系统写入检查、shell 路径（`enforcement: partial`，拒绝被正确分类），以及日常 GUI profile 里 agent 自己的会话在会话工作区之外写入时被发行版内拒绝、随后的放宽权限请求成功。
+
+数量：42 条单元测试断言、18 条文件系统探针断言、10 条 shell 探针检查、10 条沙箱预期另加被记录的逃逸、3 条终端断言。
+
+**运行时镜像。** checkout 在发行版内开发，但 harness 是 Windows 进程，而 profile 只能链接 Windows 路径：pnpm 会把 `link:\\wsl.localhost\...` 改写成坏掉的 `/wsl.localhost/...` 符号链接。所以 `default-workspace/dsh-plugin-wsl` 这份 Windows 副本是运行时镜像，启动应用前用 `test/probe/sync-to-windows.sh` 同步。该目标目录不在任何会话工作区内，所以 agent 在受限 shell 里执行同步时会被 `workspace-write` 拒绝，需要为这一条命令批准 `danger-full-access`。这是沙箱的预期行为，不是脚本坏了；不想看到提示就在普通 distro 终端里执行。
+
+**CI** 在 Linux 上用 Node 20、22、24 运行 `npm test`。
+
+## 设计说明
+
+有两处设计从 profile YAML 里看不出来。完整推理、实测数据和所有被放弃的方案都在归档工程记录里：[docs/archive/engineering-record.zh.md](archive/engineering-record.zh.md)。它是历史文档，不是第二份 README；如果它与本文冲突，以本文为准。
+
+**为什么终端 provider 放在组合层。** `ctx.shell` 和 `ctx.fs` 是按会话提供的，位于 `wsl` agent preset 的 isolate realm 中。因此宿主工作区继续使用官方受限的 PowerShell 环境，WSL 工作区使用发行版，两者可以在同一个进程里同时存在。
+
+终端无法这样提供。`dsh-api-terminal-controller` 通过 `agent.ctx.get("subprocess")` 查找执行环境。Agent 的 context 由 agent loop 创建在**根** realm 之下；preset 的 isolate realm 则由 `dsh-agent-preset-registry` 创建在**注册表自身的** context 之下。这两条作用域链不会相交，所以挂在 `preset-wsl` 里的 `subprocess` provider 对终端窗口不可见。
+
+因此 [`cordis.patch.yml`](../cordis.patch.yml) 替换的是**组合层**的 `subprocess` 行，换成一个只覆写 `spawnTerminal` 的子类。普通的 `spawn()`、Windows 侧的 ripgrep 搜索、pwsh 执行器和 LSP 宿主都仍然走官方实现。代价是终端跟着组合走，而不是跟着会话走，见[已知限制](#已知限制)。
+
+**为什么沙箱放在 Linux 侧。** Windows ACL runner 的受限令牌完全到不了 WSL，所以约束只能在 Windows 侧构造、在发行版内执行。`lib/sandbox.js` 因此照搬 `dsh-sandbox-local` 的 Linux `bwrap` 方案，而不是去用 `ctx.sandbox`；后者 `dsh-tool-bash` 从来不用，它读的是执行器的 `sandboxMode` 和 `ctx.sandboxPolicy`，这两样都由本插件提供。
+
+## 许可
+
+MIT，见 [LICENSE](../LICENSE)。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-plugin-wsl-env",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Run a DeepSeek Harness session against a WSL distro: a ctx.shell executor that runs commands inside the distro and a ctx.fs backend over its UNC share",
   "keywords": [
     "deepseek-harness",
@@ -34,6 +34,7 @@
     "cordis.patch.yml",
     "examples/**/*.yml",
     "README.md",
+    "docs/README.zh.md",
     "CHANGELOG.md",
     "LICENSE"
   ],