dsh-plugin-wsl-env 0.11.0 → 0.13.0

package/README.md

@@ -6,200 +6,186 @@
 [![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)
 
-This plugin lets [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) work inside a WSL distro. The model's commands run there. Its file tools read and write the real distro files. The folder picker can open a distro folder, and the GUI terminal opens a shell inside it.
+A [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) plugin that runs a session inside a WSL 2 distribution on Windows.
 
-**Windows + WSL2 only.** One install command, no dependencies of its own. The environment is chosen per session: a session on a Windows folder keeps the normal Windows tools.
+The harness process stays on Windows. Commands, file operations, the folder picker and the GUI terminal use the distro. No helper service or daemon is installed, no port is opened, and confined commands run under `bubblewrap`.
 
-[Install](#install) · [Using it](#using-it) · [How it compares](#how-it-compares) · [Configure](#configure) · [Recipes](#recipes) · [Architecture](#architecture) · [Sandbox](#sandbox) ·
-[Troubleshooting](#troubleshooting) · [Development](#development) · [Documentation](#documentation)
+Windows + WSL 2 only.
 
-## Install
+**New here?** Start with [docs/QUICKSTART.md](docs/QUICKSTART.md) — five minutes, prerequisites, recipes and the honest compatibility table.
 
-Run these four commands in a Windows terminal:
+## Why this plugin
 
-```powershell
-dsh wsl --from-default-profile web --dump-config   # 1. create a profile (a named set of dsh settings) from the Web template
-dsh plugin --profile wsl add dsh-plugin-wsl-env    # 2. install the plugin and its settings
-dsh --profile wsl --dump-config                    # 3. a quick check: see the merged settings without starting the app
-dsh --profile wsl                                  # 4. run
-```
+A Windows coding tool that works on WSL projects has three options: run the whole tool inside the distro, connect to a helper server inside the distro, or let the plugin provide the distro environment. This plugin is the third option. One workflow covers both kinds of session, with the distro's real tools and the command sandbox intact.
 
-Step 3 should print a line `# == dsh-plugin-wsl-env`. That line is the plugin's settings arriving in your profile. The plugin ships its own settings, so step 2 wires everything in automatically — there is nothing to merge by hand.
+- **Real Linux environment.** Commands run in the distro's own login shell. Its `PATH`, `nvm`, `cargo`, `pyenv` and rc files apply. File tools read and write the distro's real files on ext4.
+- **No service in the distro.** There is no helper server, no daemon and no listening port. The only persisted artifact is a content-addressed copy of the native agent in `~/.cache/dsh-wsl/agent/`.
+- **Sandboxed by default.** Confined commands run under `bubblewrap` inside the distro. If `bubblewrap` is missing, the command fails; it does not run unconfined.
+- **Per-session.** A session opened on a distro folder gets the distro environment. A session opened on a Windows folder keeps the normal Windows tools. Both can run in one harness process.
+- **Integrated with the GUI.** The folder picker lists installed distros, the terminal opens a shell in the distro, and the model can see listening ports.
 
-**Before the first command, give the distro bubblewrap.** Every command runs inside a bubblewrap sandbox, and most distros do not have bubblewrap preinstalled. Without it, every command fails instead of running unsandboxed:
+### Why Linux, not PowerShell
 
-```powershell
-wsl.exe -d <distro> -u root -- apt-get install -y bubblewrap    # Debian/Ubuntu
-```
+Most coding agents learn from Linux-first material, and most open-source toolchains are built and tested on Linux first. Asking an agent to work through a Windows shell adds a translation layer on every call:
 
-From a plugin checkout, `pnpm run bootstrap -- <distro>` checks the four tools the plugin uses (bubblewrap, ripgrep, git, inotify-tools) and prints the install command for the distro's package manager; `--install` runs it. If this step is skipped, the session reports the missing package with the exact install command when it opens.
+- **Training prior.** Examples, CI scripts, Dockerfiles and most public answers use POSIX shells and GNU tools. A model's first instinct is `bash`, not PowerShell.
+- **Toolchain support.** Node, Python, Rust, Go, C/C++ and most build systems are validated on Linux first. Windows support is often a port with different quoting, paths, line endings and file locking.
+- **Shell semantics.** PowerShell and `cmd` differ from POSIX in quoting, escaping, pipelines, environment variables, exit codes and path separators. Mixing the two produces errors that look like model mistakes.
+- **Environment drift.** Windows setups vary by PowerShell version, execution policy, PATH and installed tools. Linux environments are easier to reproduce and containerize.
 
-**The shipped preset also needs systemd.** Commands run in one systemd user scope per session (background dev servers survive, `/tmp` is shared, `ps` sees the session). Set `[boot] systemd=true` in `/etc/wsl.conf`, restart WSL, and enable lingering once: `loginctl enable-linger "$USER"`. The session refuses with those remedies if any piece is missing; `sessionSandbox: false` on the preset's `wsl-shell` restores the per-command sandbox.
+The result is more failed commands, more retries and more time spent on syntax instead of the task. Generated code is affected too: shell snippets, build commands and CI-style one-liners are usually written for POSIX, and the distro is where they run unchanged. A real Linux login shell removes that translation layer. Modern PowerShell and Windows-native toolchains narrow the gap, but the default prior and most project scripts still assume POSIX.
 
-Then open a folder like `\\wsl.localhost\<distro>\...` in the GUI. The folder picker lists every installed distro, and **New terminal** opens a shell inside the distro.
+This plugin keeps the GUI on Windows and moves only the execution environment into the distro, so the agent gets the shell that its training and the toolchain both assume.
 
-Uninstall: `dsh plugin --profile wsl remove dsh-plugin-wsl-env`. Upgrade: run the same `add` command again.
+## How it compares
 
-> **Changed anything under `lib/`? Sync the Windows-side copy, then restart the app.** The app loads the Windows-side copy of the code, so run `pnpm run sync:windows` first. A restart without the sync just reloads the old code, and a running process also caches modules. See [Development](#development).
+| | Desktop remote (VS Code, ZCode) | This plugin |
+|---|---|---|
+| Inside the distro | a helper server | one cached agent binary |
+| Network | a listening port | none |
+| Command sandbox | none | `bubblewrap` |
+| Removal | delete the server | delete the cache |
 
-## Using it
+A desktop remote reconnects faster and is more mature. A CLI agent installed inside WSL is simpler if it covers your work. This plugin is for the case where the harness stays on Windows and commands must be sandboxed.
 
-Open a distro folder as the workspace — for example `\\wsl.localhost\ubuntu\home\you\project` — and ask the model "what kernel am I on, and what is in `/etc/os-release`?". It runs `uname -r` and reads that file inside the distro. Nothing is copied, and nothing crosses `/mnt/c`.
+## Requirements
 
-- **A distro folder gets the distro environment.** When a session opens a distro folder, it is automatically given the WSL environment. The very first command is already right.
-- **Commands run where you expect.** They run inside the distro, in your own login shell — so your `PATH`, `nvm`, `cargo`, `pyenv` and rc files all apply. The shell comes from the distro's configuration; it is not hardcoded to bash.
-- **Files are the real files.** `/home/you/x` and `\\wsl.localhost\ubuntu\home\you\x` are the same file. `/mnt/c/...` reaches the Windows disk as usual.
-- **The terminal too.** Right sidebar, *New terminal*: a shell inside the distro, in the session's folder.
-- **Port visibility.** The model sees which ports are listening inside the distro (refreshed about every 10 seconds) and can return the exact URL of a dev server it starts. WSL2 forwards localhost to Windows, so the URL opens in the browser directly.
-- **Permissions work like on a Linux host.** The Permissions selector offers `read-only`, `workspace-write` (the default) and `danger-full-access`. When something is refused, the model is offered one retry with the smallest permission that would work. Only `danger-full-access` runs without the sandbox.
+- Windows 10 or 11 with WSL 2 and at least one distro.
+- `bubblewrap` in the distro. It is required.
+- systemd in the distro for the default session sandbox: set `[boot] systemd=true` in `/etc/wsl.conf`, restart WSL, then run `loginctl enable-linger "$USER"` once. Without systemd, set `sessionSandbox: false` on both `wsl-shell` and `wsl-fs`.
+- Optional: `ripgrep` for search, `git` for change snapshots, `inotify-tools` for file watching.
 
-## How it compares
+No Node.js is required inside the distro.
 
-Three ways for a Windows coding tool to work on a WSL project:
+## Install
 
-1. **Install the tool inside WSL.** Codex CLI, Claude Code and ZCode CLI all recommend this, and they are right — it is the simplest path when a CLI tool covers your work. It needs the whole tool to live inside WSL. DeepSeek Harness cannot, so it needs one of the next two.
-2. **Connect from a desktop app.** VS Code (Remote-WSL, and its open-source mirror [open-remote-wsl](https://github.com/jeanp413/open-remote-wsl)) and agent desktops like [ZCode](https://github.com/zai-org/ZCode) keep the app on Windows and set up a helper server inside the distro. Battle-tested. The cost: a server folder (`~/.vscode-server`, `~/.zcode/server`), a port, and no sandbox for commands.
-3. **This plugin.** The harness stays on Windows. Nothing is installed in the distro, no port is opened, and commands run inside a bubblewrap sandbox. If something is missing, the session says what to install the moment it opens.
+Run these commands in a Windows terminal:
 
-| | Option 2 (desktop remote) | Option 3 (this plugin) |
-|---|---|---|
-| installed in the distro | a server folder | nothing |
-| opens a port | yes | no |
-| command sandbox | none | bubblewrap + systemd session scope |
-| after uninstall | remove the server manually | nothing left |
-| after a WSL upgrade | server may need repair | the next command recovers automatically |
+```powershell
+dsh wsl --from-default-profile web --dump-config   # create the profile
+dsh plugin --profile wsl add dsh-plugin-wsl-env    # install the plugin and its settings
+dsh --profile wsl --dump-config                    # verify: prints "# == dsh-plugin-wsl-env"
+dsh --profile wsl                                  # start
+```
 
-**Where the others win.** A desktop remote re-opens a workspace instantly — its server stays warm — and VS Code's remote has years of hardening behind it. A CLI inside WSL needs none of this. This plugin is for one case: DeepSeek Harness on Windows, working on WSL projects, with commands sandboxed.
+Install `bubblewrap` before the first command:
 
-## Configure
+```powershell
+wsl.exe -d <distro> -u root -- apt-get install -y bubblewrap
+```
 
-Each setting lives on a named row. To change one, add a row with the same id to `$DSH_HOME/profiles/<name>/cordis.patch.yml` (`$DSH_HOME` is DSH's settings folder). The keys worth knowing:
+From a checkout, `pnpm run doctor` is the one-command environment check: Windows/WSL versions, the distro and its shell, bubblewrap usability, systemd / the user manager / Linger, the optional tools, peer versions, the agent cache, a fresh-agent handshake, stale session scopes and the known profile-patch trap. Each failure prints one copy-paste remedy; `--json` is for scripts, and `--fix` sweeps stale scopes (package installation needs `--fix --install` and an explicit confirmation). `pnpm run diagnose` is its read-only alias. `pnpm run bootstrap -- <distro>` remains the narrower tool-install helper.
 
-| Row | Key | Default | Meaning |
-|---|---|---|---|
-| `wsl-shell` | `distro` | `''` | which distro to use; empty means WSL's default distro |
-| | `sandbox` | `true` | run commands inside the `bubblewrap` sandbox; `false` turns it off |
-| | `sessionSandbox` | `true` | run the session's commands in one persistent systemd user scope: background dev servers survive, `/tmp` is shared, `ps` sees the session. Needs systemd as PID 1, a reachable user manager and `Linger`; the preflight refuses with the remedy. `false` restores the per-command sandbox |
-| | `agentBackend` | `auto` | the session runtime's agent: `auto` uses the native in-distro agent when a verified source exists (packaged static-musl binary at `agent/native/linux-<arch>/dsh-wsl-agent` (x86_64/aarch64) or the `DSH_WSL_AGENT_NATIVE` override), else the shell agent; `native` refuses instead of falling back; `shell` forces the shell agent. Covers commands and confined writes. The native backend is the default; the shell agent is the fallback |
-| `wsl-fs` | `distro` | `''` | same as above |
-| | `restrictToDistro` | `true` | refuse paths that belong to a **different** distro. (`/mnt/c` belongs to this distro, so it is not affected.) The refusal is `FS_OUTSIDE_DISTRO`; wider permissions cannot lift it |
-| | `sandbox` | `true` | check file writes against the same policy |
-| | `sessionSandbox` | `true` | run confined file writes in the same session runtime as commands (one real `/tmp`, one workspace mount view); needs the same systemd/linger setup; `false` uses the per-policy confined resident |
-| | `substrate` | `agent` | how file operations reach the distro. Only one value remains: the in-distro agent, so reads and writes run on the distro's own filesystem, with native symlinks and permissions. The former `"share"` option used the 9p share and is rejected at startup |
-| `directory-picker-wsl` | `includeHostHome` | `true` | also list the Windows home directory in the picker |
-| `subprocess-wsl` | `distro` | `''` | which distro the GUI terminal opens in |
+Upgrade by running the `add` command again. Uninstall with `dsh plugin --profile wsl remove dsh-plugin-wsl-env`; the agent cache under `~/.cache/dsh-wsl` can then be deleted. If you added a local `workspace-files-wsl` workaround to your profile to restore previews, remove it after upgrading: the plugin no longer mounts that row.
 
-`wsl-shell` and `wsl-fs` cannot be reached by adding `- id: wsl-shell` to your override file: they live inside the `wsl` preset's own settings (a preset is a named environment DSH can give a session), so the loader only warns `patch: entry "wsl-shell" not found` and the shipped value stays in force. To change them, copy and override the whole `preset-wsl` row — [docs/CONFIGURATION.md](docs/CONFIGURATION.md#overriding-the-rows-inside-preset-wsl) has the recipe.
+## Using it
 
-[`cordis.patch.yml`](cordis.patch.yml) is the commented reference for every value the plugin ships. [docs/CONFIGURATION.md](docs/CONFIGURATION.md) lists the rest — `shell`, `loginShell`, `cwd`, `timeoutMs`, `preferredDistro`, `maxEntries` — and [examples/profile.cordis.patch.yml](examples/profile.cordis.patch.yml) is a settings file you can copy and edit.
+Open a distro folder as the workspace, for example `\\wsl.localhost\ubuntu\home\you\project`.
 
-## Recipes
+- Opening a folder in any distro runs there, even when it is not WSL's default.
+- Commands run in the distro's login shell. `/home/you/x` and `\\wsl.localhost\ubuntu\home\you\x` are the same file.
+- **New terminal** opens a shell in the same distro and directory.
+- The model sees listening ports and can return the URL of a dev server. WSL 2 forwards localhost to Windows.
+- The Permissions selector offers `read-only`, `workspace-write` (default) and `danger-full-access`. Only `danger-full-access` runs without the sandbox.
 
-- **Use your Windows git credentials inside the distro**: `git config --global credential.helper "/mnt/c/Program\ Files/Git/mingw64/bin/git-credential-manager.exe"` (adjust the path to where your Windows Git is installed). After this, `git push` inside the distro uses the same saved credentials as Windows.
-- **Keep projects on the distro's own disk.** The model works on Linux paths (`/home/...`) on the distro's own disk, which is fast. It can still reach Windows files through `/mnt/c`, but that bridge is slow when many small files are involved. `pnpm run bootstrap -- <distro>` tells you whether ripgrep, git and inotifywait — used for search and file watching — are installed.
-- **Environment variables**: WSL only forwards the variables named in `WSLENV`. This plugin forwards its own `DSH_*` values, and translates the two that hold Windows paths (`DSH_HOME`, `DSH_PROFILE_DIR`) into Linux paths. Your `PATH` is never forwarded — forwarding it would hide the distro's own PATH.
+## Configure
+
+Settings live on named rows in `$DSH_HOME/profiles/<name>/cordis.patch.yml`. The main values:
+
+| Row | Key | Default | Purpose |
+|---|---|---|---|
+| `wsl-shell` | `distro` | `''` | distro mode; empty/`auto` follows the workspace, `default` forces WSL's default |
+| | `sandbox` | `true` | confine commands with `bubblewrap` |
+| | `sessionSandbox` | `true` | run the session's commands in one systemd user scope |
+| | `agentBackend` | `auto` | `auto`, `native` or `shell` for the in-distro agent |
+| | `maskWindowsDrive` | `false` | hide `/mnt` from confined commands |
+| `wsl-fs` | `distro` | `''` | distro mode; empty/`auto` follows each target path |
+| | `restrictToDistro` | `true` | under a fixed distro, refuse paths that belong to another distro |
+| | `sandbox` | `true` | check confined writes against the policy |
+| | `sessionSandbox` | `true` | run confined writes in the session runtime |
+| | `substrate` | `agent` | in-distro agent; `share` is rejected at startup |
+| `directory-picker-wsl` | `includeHostHome` | `true` | also list the Windows home directory |
+| `subprocess-wsl` | `distro` | `''` | distro mode; empty/`auto` follows the launch directory |
+
+`wsl-shell` and `wsl-fs` are inside the shipped `wsl` preset, so overriding them by id does not work. Override the whole `preset-wsl` row instead; [docs/CONFIGURATION.md](docs/CONFIGURATION.md) has the recipe and the remaining keys. [`cordis.patch.yml`](cordis.patch.yml) is the commented reference for every shipped value.
 
 ## Architecture
 
-One DSH process can serve both kinds of session at the same time: a session on a Windows folder, and a session inside the distro. The plugin's parts attach at two levels, because some things belong to one session and some belong to the whole app:
+One harness process can serve Windows-folder and distro-folder sessions at the same time. Services attach at two levels:
 
 ```text
-composition (app level, one per process)
-├─ subprocess-wsl        the GUI terminal's execution world
-│                          WSL-folder session     → the distro shell, in the session's Linux directory
-│                          Windows-folder session → powershell.exe, in the session's Windows directory
-├─ directory-picker-wsl  installed distros listed beside the Windows home
-├─ workspace-files-wsl   the GUI file tree and previews of a distro workspace, served from inside it
-├─ fs-routing            the root filesystem, routed by coordinate
-│                          distro UNC → the resident agent; a drive path → the host backend
-├─ wsl-shell-env         the DSH_WSL_DISTRO / _SHELL / _HOME / _PORTS facts the model sees
-└─ auto-preset           binds the wsl preset when a session opens a distro folder
-
-preset-wsl (the wsl agent preset; its settings are separate from the app's)
-├─ wsl-shell   ctx.shell — wsl.exe --exec <login shell>, confined by bubblewrap inside the distro
-└─ wsl-fs      ctx.fs    — real distro files on the resident agent substrate (ext4)
+app level (one per process)
+├─ directory-picker-wsl, workspace-files, subprocess-wsl
+├─ fs-routing: root filesystem routed by path
+└─ auto-preset: binds the wsl preset when a session opens a distro folder
+
+wsl preset (per session)
+├─ wsl-shell: commands
+└─ wsl-fs: file operations
 ```
 
-**Why two levels.** The `wsl` preset holds `wsl-shell` and `wsl-fs`, the two things that differ per session. When a session opens a distro folder, `auto-preset` gives that session the preset; a Windows-folder session keeps the normal Windows tools. One environment per session, in one process. The GUI terminal is the exception: it reads its shell from the app level, which never sees a preset, so `subprocess-wsl` is mounted at the app level. The GUI file tree and the root filesystem have the same shape of problem — every session uses them, so no single preset can own them — and `workspace-files-wsl` and `fs-routing` sit at the app level for that reason. They replace two shipped rows; [docs/root-fs-routing.md](docs/root-fs-routing.md) has the routing design.
-
-**How a command runs.** A session gets one resident agent inside a systemd user scope. By default that agent is the native `dsh-wsl-agent` — the packaged static-musl binary for the distro's architecture, selected by `agentBackend: auto`; the runtime's shell agent is the fallback when the binary is missing or fails its copy/digest/exec check, and `agentBackend: shell` forces it while `native` refuses instead of falling back. The agent executes each command in your login shell under a bubblewrap mount profile. Because the scope outlives the command, a background dev server survives, `/tmp` is the distro's real `/tmp`, and `ps` sees the whole session. With `sessionSandbox: false`, the agent stays per distro, each command gets its own bwrap profile (`--unshare-pid`, a fresh `/tmp`), background processes do not survive, and the native backend is not used. If the agent is unavailable (or you set `agent: false`), the one-shot `wsl.exe` path runs the command instead — same result, slightly slower, and per-command isolation.
-
-**How file operations run.** Reads, writes and searches also happen inside the distro, on its own filesystem, with the distro's own tools. A search over a distro workspace runs the distro's `rg`, never the Windows binary over the 9p share. File writes are checked against the same policy the command sandbox enforces; with `wsl-fs` `sessionSandbox` on (the shipped preset), a confined write runs in the same session runtime as the commands — the same native/shell agent — so it sees the same `/tmp` and workspace mounts. Reads use the shared native read agent (A7; the packaged binary, shell fallback): 16 concurrent reads measure ~2.4 ms, down from 342-614 ms on the shell.
+- `wsl-shell` runs commands through one resident agent inside a systemd user scope. The agent is the packaged static-musl `dsh-wsl-agent` for the distro's architecture (`x86_64` or `aarch64`), with the shell agent as fallback. Each command runs in the login shell under a `bubblewrap` mount profile. The scope outlives the command, so background servers survive and `ps` sees the session. With `sessionSandbox: false`, the agent stays per distro and each command gets its own profile.
+- `wsl-fs` serves reads and writes through the same in-distro agent. Confined writes run in a long-lived agent whose mount profile matches the policy, so the kernel enforces the write boundary. There is no host-side file fallback: if the agent is unavailable, file operations fail.
+- The GUI file tree and previews are the shipped `workspace-files` row, not a plugin replacement: its client half is the browser `file` provider. It reads WSL paths through the routed root filesystem, so it stays distro-side, at the cost of a few extra agent round trips.
+- App-level services route by path. A distro UNC path goes to the distro; a Windows drive path stays on the host. See [docs/root-fs-routing.md](docs/root-fs-routing.md).
 
 ## Sandbox
 
-Commands run inside a `bubblewrap` sandbox in the distro, and file writes are checked against the same policy. The Windows sandbox cannot be used here: its restricted account cannot reach WSL at all.
-
-| Mode | What a command inside the distro can do |
+| Mode | What a command can do |
 |---|---|
-| `read-only` | read the whole distro. A fresh `/dev` is mounted so `/dev/null` and `/dev/shm` work; nothing else is writable |
-| `workspace-write` | all of the above, plus the session workspace is writable and `/tmp` is the distro's real `/tmp` (with `sessionSandbox: false`, the per-command profile mounts a fresh tmpfs there instead) |
-| `danger-full-access` | no sandbox; used when you approve a wider-permission request |
+| `read-only` | read the whole distro; a fresh `/dev` is mounted, nothing else is writable |
+| `workspace-write` | the above, plus the session workspace; `/tmp` is the distro's real `/tmp` with the session runtime |
+| `danger-full-access` | no sandbox |
 
-**bubblewrap is required, and the plugin fails closed.** Without it, every confined command reports `SANDBOX_UNAVAILABLE` — the command does not run unsandboxed. To turn the sandbox off, set `sandbox: false` on the row that owns the operation: `wsl-shell` for commands, `wsl-fs` for file writes, and the top-level `fs-routing` row for writes to the app's own filesystem. (The two preset rows are reached through `preset-wsl` — see [Configure](#configure).) The model is then told that these operations have no sandbox.
+With `sessionSandbox: false`, each command gets a private `/tmp` instead of the distro's real one.
 
-**Known limits.** A command inside the distro can still start a Windows program (anything under `/mnt/c/.../*.exe`), and bubblewrap does not watch Windows programs. `pnpm run probe:sandbox` demonstrates this boundary on your machine. Setting `maskWindowsDrive: true` on the three rows narrows it: `/mnt` disappears from the command's view, so the drive's files cannot be read and its programs cannot be started. It does not close the hole completely — a command could still copy a Windows program into the workspace and run it — so the report stays `partial`. The only complete fix is in the distro itself: `[interop] enabled=false` in `wsl.conf` (see [docs/CONFIGURATION.md](docs/CONFIGURATION.md)).
+`bubblewrap` is required. If it is missing or broken, confined commands report `SANDBOX_UNAVAILABLE` and do not run. Setting `sandbox: false` on the owning row disables confinement; the model is told that the operation is unsandboxed.
 
-See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md#sandbox) for the design, and [docs/LIMITATIONS.md](docs/LIMITATIONS.md) for everything the plugin does not do.
+Enforcement is reported as `partial`. A command inside the distro can still start a Windows executable through `/mnt/c`, and `bubblewrap` cannot control Windows processes. `maskWindowsDrive: true` hides `/mnt` from the confined view, which narrows the hole but does not close it. The complete fix is distro-level: set `[interop] enabled=false` in `/etc/wsl.conf`. See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md#sandbox) and [SECURITY.md](SECURITY.md).
 
 ## Troubleshooting
 
-| Symptom | Cause | Fix |
-|---|---|---|
-| every command reports `SANDBOX_UNAVAILABLE` | `bubblewrap` is missing from the distro, or present but broken — the error text tells you which one it is and what to do | follow the fix in the error, or set `sandbox: false` on `wsl-shell` (commands) and `wsl-fs` (writes) — see [Configure](#configure) for how to reach those rows |
-| a command or write is refused outside the session folder | expected: `workspace-write` only allows writes in the session folder | accept the wider-permission offer, or open the 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` prints no confirmation that anything was added | the plugin is already installed, so there is nothing new to report — this is success, not failure | nothing to do: the settings are already in place, and `dsh --profile wsl --dump-config` still shows `# == dsh-plugin-wsl-env` |
-| the terminal still opens `cmd.exe` | the `terminal-controller` row from the plugin's settings did not apply | check that `dsh --profile wsl --dump-config` shows `shell: { path: wsl.exe, name: WSL }` |
-| changes to `lib/` have no effect | the app runs a Windows-side copy of the code, and a running process also caches modules | run `pnpm run sync:windows` to update the copy, then 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 Windows-side copy, see [Development](#development) |
-| `glob` and `grep` are slow | searches inside the distro need `rg` installed in the distro; Windows-folder searches are unaffected | run `pnpm run bootstrap -- <distro> --install` (installs ripgrep); distro searches always run the distro's rg — they never cross the slow bridge |
-| the terminal reports `unknown` activity | only while the in-distro agent is temporarily unavailable — distro terminals are watched from inside the distro (a `DSH_TERMINAL_ID` marker scanned in `/proc`: a shell alone is `idle`, a shell running anything is `busy`) | check the distro is running; idle terminals are closed automatically after the controller's idle timeout (2 h by default), and `terminalIdleReclaim: false` turns the auto-close off |
-| a result names an `FS_*` code | the code says what refused it, and what clears it | see the error-code table in [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md#error-codes) |
+| Symptom | Fix |
+|---|---|
+| every command reports `SANDBOX_UNAVAILABLE` | install `bubblewrap` in the distro, or set `sandbox: false` |
+| the session refuses before the first command | run `pnpm run doctor`; enable systemd and linger, or set `sessionSandbox: false` on `wsl-shell` and `wsl-fs` |
+| `glob` and `grep` are slow in the distro | install `ripgrep` with `pnpm run bootstrap -- <distro> --install` |
+| `dsh plugin add` prints nothing | the plugin is already installed; this is success |
+| a profile patch for `wsl-shell`/`wsl-fs` changes nothing | those rows are nested inside `preset-wsl`. Run `pnpm run preset -- --check <patch>`; it fails with the complete block to paste |
+| changes under `lib/` have no effect | run `pnpm run sync:windows`, then restart the app |
+
+More error codes and refusals are in [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md#error-codes). Everything the plugin does not do is in [docs/LIMITATIONS.md](docs/LIMITATIONS.md).
 
 ## Development
 
 ```bash
-pnpm run build                # compile src/ into lib/ (the built files are committed; rebuild after editing src/)
-pnpm test                     # style checks, syntax pass, build consistency, type check, and unit tests
-pnpm run sync:windows         # copy the checkout onto the Windows-side copy the app loads (after any lib/ change, then restart the app)
-pnpm run test:coverage        # the unit tests with coverage thresholds (Node 22.8+)
-pnpm run diagnose             # read-only diagnostic report for a bug issue: versions, tools, bwrap probe
-pnpm run bootstrap -- <distro> # check the four distro tools; add --install to install what is missing
-pnpm run probe:sandbox        # measure inside the distro what bubblewrap does and does not confine
-pnpm run probe                # filesystem probe against a real distro (Windows + WSL only)
-pnpm run probe:sandbox-shell  # boot a real harness and drive the confined executor
-pnpm run probe:terminal       # open a PTY through the terminal provider
-pnpm run probe:substrate      # drive the agent filesystem over a real wsl.exe transport (from inside the distro)
-pnpm run probe:watch          # arm the in-distro watcher over a real directory (from inside the distro)
-pnpm run probe:agent          # compare the resident path against the fallback path (from inside the distro)
-pnpm run probe:exec           # the agent-backed execution: timeout, kill, cwd failure (from inside the distro)
-pnpm run probe:missing-wsl    # boot a profile whose wslPath cannot start (Windows + WSL only)
-pnpm run probe:picker         # list the picker's root level, refusals and its cap (Windows + WSL only)
-pnpm run probe:mode           # which POSIX-mode facts survive the share (needs a Windows node and an installed harness; opens no profile)
-pnpm run probe:sandbox-off    # prove sandbox: false unconfines both providers (Windows + WSL only)
+pnpm install           # development dependencies
+pnpm run build         # compile src/ into lib/ (lib/ is committed)
+pnpm test              # style, syntax, build consistency, types, unit tests
+pnpm run test:coverage # unit tests with coverage thresholds
+pnpm run sync:windows  # update the Windows-side copy the app loads
 ```
 
-The app runs a Windows-side copy of the code, not your checkout. After changing anything under `lib/`, run `pnpm run sync:windows` before restarting the app — otherwise the restart just loads the old code. `pnpm run build` regenerates `lib/` from `src/`; the built files are committed, and `pnpm test` checks that they match.
-
-Run `pnpm install` once to get the development dependencies. The tests use the pinned `@deepseek-ai/*` packages; the plugin itself ships none. CI runs the tests on Node 22 and 24, on Linux and Windows, and coverage on Node 24.
+The toolchain follows the harness host: Node `^22.19.0 || >=24.0.0`. `src/` is TypeScript; `lib/` is generated and must stay in sync. The app loads a Windows-side copy of `lib/`, so run `sync:windows` and restart the app after a build.
 
-[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) has the file layout, how the parts attach, and the sandbox design. [CONTRIBUTING.md](CONTRIBUTING.md) has the development loop, the Windows-side copy, the full gate list, and what has been verified.
+Real-machine probes run on Windows + WSL only. See [CONTRIBUTING.md](CONTRIBUTING.md) and `test/probe/`.
 
 ## Documentation
 
-| Document | What it covers |
+| Document | Content |
 |---|---|
-| [docs/CONFIGURATION.md](docs/CONFIGURATION.md) | every configuration key, and how to override it |
-| [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | the plugin's parts and how they attach, path coordinates, the sandbox, testing, file layout |
-| [docs/ROADMAP.md](docs/ROADMAP.md) | the plan: done, next (A7 native shared reads, A8 aarch64), deferred (v6) |
-| [docs/LIMITATIONS.md](docs/LIMITATIONS.md) | what the plugin does not do, and why |
-| [docs/VALUE.zh.md](docs/VALUE.zh.md) | the plugin's value in Chinese: what it is worth, what it costs, and when not to use it |
-| [CONTRIBUTING.md](CONTRIBUTING.md) | the development loop, gates, conventions, verification |
-| [SECURITY.md](SECURITY.md) | reporting a vulnerability privately |
-| [SUPPORT.md](SUPPORT.md) | supported versions, and where to ask |
-| [docs/RELEASING.md](docs/RELEASING.md) | the release checklist |
-| [docs/archive/README.en.md](docs/archive/README.en.md) | English index of the archived engineering record |
+| [docs/QUICKSTART.md](docs/QUICKSTART.md) | five-minute first run, recipes, compatibility |
+| [docs/PERFORMANCE.md](docs/PERFORMANCE.md) | ext4 agent vs 9p, measured latency, how to reproduce |
+| [docs/CONFIGURATION.md](docs/CONFIGURATION.md) | every configuration key and how to override it |
+| [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | services, path routing, sandbox, error codes |
+| [docs/LIMITATIONS.md](docs/LIMITATIONS.md) | what the plugin does not do |
+| [docs/ROADMAP.md](docs/ROADMAP.md) | current plan and deferred work |
+| [docs/ROADMAP-1.0.md](docs/ROADMAP-1.0.md) | the 1.0 and ecosystem plan |
+| [docs/VALUE.zh.md](docs/VALUE.zh.md) | value and trade-offs in Chinese |
+| [CONTRIBUTING.md](CONTRIBUTING.md) | development loop, gates, probes |
+| [SECURITY.md](SECURITY.md) | private vulnerability reporting |
+| [SUPPORT.md](SUPPORT.md) | supported versions and support channels |
+| [docs/RELEASING.md](docs/RELEASING.md) | release checklist |
 
 ## License
 

package/SECURITY.md

@@ -88,8 +88,18 @@ This is a documented design boundary, not a vulnerability by itself. The command
 distro, where `bubblewrap` and `node` must be installed; the README states it in
 its Sandbox section.
 
+The strict profile (`maskWindowsDrive: true` with `sandbox: true`) narrows this:
+confined profiles shadow `/mnt` with an empty tmpfs, so the Windows executables
+cannot be launched from there. It does not close the hole — a Windows executable
+written into the workspace still runs, because WSL's `binfmt_misc` dispatches on
+content, not location — so the reported enforcement stays `partial`. The complete
+closure is distro-level (`[interop] enabled=false` in `/etc/wsl.conf`). The three
+states and their evidence are tabulated in
+[docs/CONFIGURATION.md](docs/CONFIGURATION.md#the-strict-profile).
+
 A report is still welcome if you find an escape that does not depend on interop,
-or if the plugin ever reports `full` while interop is reachable.
+if the masked profile is bypassable from `/mnt`, or if the plugin ever reports
+`full` while interop is reachable.
 
 ## Credentials
 

package/SUPPORT.md

@@ -7,6 +7,12 @@
 | Operating system | Windows 10 and Windows 11 |
 | Linux side | WSL2 with at least one distro, and systemd as PID 1 with a lingering user manager (`loginctl enable-linger`) for the shipped session runtime. Set `sessionSandbox: false` on the preset's `wsl-shell` to keep the per-command sandbox instead |
 | DSH packages | the `0.2.1-rc.2`-era packages listed in `peerDependencies` |
+
+The DSH row is checked weekly: `.github/workflows/peer-canary.yml` resolves the
+`next` dist-tag of every pinned peer, installs that line into a scratch copy and
+runs `pnpm test` plus the composition boot test. A successful run prints the
+exact version delta in its summary; update the row above from that summary. A
+red run means the plugin has not been validated against the new line yet.
 | Plugin version | the latest published version only |
 | Node | 22.19+ (`^22.19.0`), or 24 and later (`>=24.0.0`) |
 
@@ -22,9 +28,14 @@ supported configuration.
 
 Open an issue in the repository:
 
-https://github.com/Big-Dao/dsh-plugin-wsl-env/issues
+https://github.com/Big-Dao/dsh-plugin-wsl-env/issues/new/choose
+
+The chooser offers a **feature request** and a **setup report**; the setup
+report requires the `doctor --json` output, which is what makes a first-run
+problem diagnosable without a round trip. For a security issue, use the private
+advisory link instead (see [SECURITY.md](SECURITY.md)).
 
-Use it for bug reports and for questions about configuration. Search the open and
+Use issues for bug reports and for questions about configuration. Search the open and
 the closed issues first, and check whether the answer is already written down:
 [docs/LIMITATIONS.md](docs/LIMITATIONS.md) lists the known design boundaries, and
 the Troubleshooting table in [README.md](README.md#troubleshooting) covers the
@@ -56,6 +67,22 @@ loudly instead of quietly.
 
 There is no long-term support branch. Fixes go to the latest version.
 
+## Triage and release cadence
+
+- **Roadmap.** The public plan is [docs/ROADMAP-1.0.md](docs/ROADMAP-1.0.md);
+  the open issues #5–#22 map to its WSL-1xx/2xx/3xx blocks.
+- **Triage target.** A `priority:P1` report gets its first response within three
+  business days, best effort. Security reports follow the response targets in
+  [SECURITY.md](SECURITY.md).
+- **Cadence.** Releases ship when there is a change worth shipping, roughly every
+  two to four weeks; the tag workflow and its gates are in
+  [docs/RELEASING.md](docs/RELEASING.md), and the configuration-stability and
+  migration rules are in [docs/MIGRATION.md](docs/MIGRATION.md). There is no
+  long-term support branch.
+- **Good first issues.** The `good first issue` label marks changes that need no
+  prior context; [CONTRIBUTING.md](CONTRIBUTING.md#good-first-issues-and-the-contributor-path)
+  lists the usual shapes and how to claim one.
+
 ## What a good bug report contains
 
 The one-command path: `pnpm run diagnose` (from a checkout of the plugin, or

package/cordis.patch.yml

@@ -66,6 +66,8 @@
     - id: subprocess-wsl
       name: 'dsh-plugin-wsl-env/subprocess'
       config:
+        # auto: follow the launch directory's UNC distro; "default" forces WSL's
+        # default, and a name pins. Empty is auto.
         distro: ''
 
 # ═════════════════════════════════════════════════════════════════════════════
@@ -104,25 +106,24 @@
       name: '@deepseek-ai/dsh-client-ui-directory-picker-browse'
 
 # ═════════════════════════════════════════════════════════════════════════════
-# The distro-side takeovers of the two root-plane services.
+# The distro-side takeover of the root-plane filesystem.
 #
 # A patch layer is a flat list: an `id:` entry patches the shipped row, and a
 # bare `insert:` list appends new rows as data. A disable written INSIDE an
 # insert list is not a patch — it becomes a duplicate-id data row that shadows
 # the real service row (the loader keys rows by id, last occurrence wins), and
-# a nested `insert:` list is never interpreted at all. Both takeovers are
+# a nested `insert:` list is never interpreted at all. This takeover is
 # therefore two top-level entries: disable the shipped row by id, then append
 # the replacement with a bare insert. test/composition.test.mjs runs this file
 # through the real patch algorithm to keep the shape honest.
 # ═════════════════════════════════════════════════════════════════════════════
 
-# The GUI file tree and previews for a distro workspace are served from inside
-# the distro (resident agent) instead of Windows-side 9P walks. The variant
-# extends the shipped service — a distro UNC routes distro-side, a drive path
-# calls super (host native), the watch stream delegates unchanged — so
-# replacing the row is safe for Windows-folder sessions too.
-- id: workspace-files
-  disabled: true
+# The GUI file service keeps the shipped `workspace-files` row: its client half
+# is the browser `file` resource provider the Sidebar previews need, and a
+# server-only replacement drops it (docs/LIMITATIONS.md). The shipped service
+# reads WSL paths through the routed root filesystem below, so the GUI file tree
+# and previews still run inside the distro, at the cost of a few extra agent
+# round trips.
 
 # The root-plane filesystem routes by coordinate: distro UNC identities are
 # served by the resident agent (real watch events, ext4 reads), drive paths
@@ -133,17 +134,11 @@
   disabled: true
 
 - insert:
-    - id: workspace-files-wsl
-      name: 'dsh-plugin-wsl-env/workspace-files-wsl'
-      config:
-        maxBytes: 2097152
-        maxFileBytes: 33554432
-        maxLines: 5000
-        maxEntries: 2000
-
     - id: fs-routing
       name: 'dsh-plugin-wsl-env/fs-routing'
       config:
+        # auto: route each UNC target to its own distro; "default" forces WSL's
+        # default, and a name pins. Empty is auto.
         distro: ''
         wslPath: wsl.exe
         sandbox: true
@@ -232,6 +227,8 @@
               - id: wsl-shell
                 name: 'dsh-plugin-wsl-env'
                 config:
+                  # auto: follow the request workdir's UNC distro; "default"
+                  # forces WSL's default, and a name pins. Empty is auto.
                   distro: ''
                   loginShell: true
                   timeoutMs: 120000
@@ -246,14 +243,15 @@
               - id: wsl-fs
                 name: 'dsh-plugin-wsl-env/fs'
                 config:
+                  # auto: follow each target path's UNC distro; "default"
+                  # forces WSL's default, and a name pins. Empty is auto.
                   distro: ''
                   restrictToDistro: true
                   # agent (the default): reads/writes/identities run inside the
                   # distro over the resident agent (lib/fs-substrate.js) —
                   # native symlinks and mode bits, the write guard survives to
                   # publication, and confined mutations are kernel-enforced.
-                  # share: the opt-out — the Windows-side host fs stack over
-                  # the 9p share.
+                  # "share" is retired; a profile carrying it is refused at boot.
                   substrate: agent
                   # Confined writes ride the session runtime (ADR 0001), so they
                   # share the command's real /tmp and workspace mounts.