dsh-plugin-wsl-env 0.15.0 → 0.16.0

package/docs/CONFIGURATION.md

@@ -1,293 +1,274 @@
 # Configuration
 
-Every value lives in a profile row, and a row is overridden by id in your own
-profile layer: `$DSH_HOME/profiles/<name>/cordis.patch.yml`. Start from
-[`examples/profile.cordis.patch.yml`](../examples/profile.cordis.patch.yml), and keep
-[`cordis.patch.yml`](../cordis.patch.yml) open beside it — that file is the commented
-reference for every value the plugin ships.
-
-Which rows a patch can reach depends on where they sit. `fs-routing`,
-`directory-picker-wsl`, `subprocess-wsl`, `wsl-shell-env`
-and `preset-wsl` are top-level rows, so `- id: <row>` in your layer patches them.
-`wsl-shell` and `wsl-fs` are not top-level: they are plugins of the `wsl` agent
-preset, nested inside the `preset-wsl` row's `config.plugins`. A patch that
-targets them by id matches nothing — the loader logs `patch: entry "wsl-shell"
-not found` (a warning, not an error), the profile boots anyway, and the value you
-wrote is not in force. See
-[Overriding the rows inside `preset-wsl`](#overriding-the-rows-inside-preset-wsl).
-
-In the table below, *(shipped)* marks the values set by `cordis.patch.yml`. The rest
-are schema defaults, listed because they are the ones worth knowing. `wsl-shell-env`
-has its own table at the end of this page.
-
-| Row | Key | Default | Meaning |
+## Profile patches
+
+Store profile settings in `$DSH_HOME/profiles/<name>/cordis.patch.yml`. Use
+[`examples/profile.cordis.patch.yml`](../examples/profile.cordis.patch.yml) as a
+starting point. The bundled [`cordis.patch.yml`](../cordis.patch.yml) lists the
+rows and values shipped by this plugin.
+
+A profile layer can target a top-level row by `id`. Plugin rows at that level
+include `fs-routing`, `directory-picker-wsl`, `subprocess-wsl`, `wsl-shell-env`,
+`wsl-preflight`, `auto-preset`, and `preset-wsl`. The `wsl-shell` and `wsl-fs`
+rows are nested inside `preset-wsl.config.plugins`; a profile entry targeting
+either id directly is ignored with a `patch: entry <id> not found` warning.
+
+A row's `config` is replaced as a whole. Include any non-default values from
+the bundled row that you want to retain. This matters most for `preset-wsl`,
+whose config contains the complete preset and its nested plugins.
+
+In the tables below, **shipped** marks a value explicitly set in the bundled
+row. Other values are schema defaults. An omitted key uses the schema default.
+
+## Configure `wsl-shell` and `wsl-fs`
+
+These rows are nested inside `preset-wsl`. Use the helper to change their
+settings:
+
+```bash
+pnpm run preset --distro Ubuntu --session-sandbox false
+```
+
+Supported edits are `--distro`, `--session-sandbox`, `--sandbox`,
+`--mask-windows-drive`, and `--agent-backend`. Without `--out`, the helper
+prints the full `preset-wsl` block to merge into the profile manually. Use
+`pnpm run preset --check <file>` to detect profile layers that target nested
+rows directly; on detecting them it prints the block to use. `--out` replaces
+the entire destination file, including other overrides, even when it already
+contains a `preset-wsl` row. It refuses to replace an existing file without
+that row unless you pass `--force`. Prefer manual merging for existing profiles.
+
+To edit the preset manually, replace the entire `preset-wsl` row. Its config is
+not deep-merged: preserve `id`, `order`, and every item in `plugins`. Copy the
+current block from `cordis.patch.yml` or from
+`dsh --profile <name> --dump-config`, then change the nested values. Re-copy it
+after a plugin upgrade that changes the preset.
+
+### `wsl-shell`
+
+| Key | Default / shipped value | Description |
+|---|---|---|
+| `distro` | `''` (shipped) | Empty or `auto` follows the request workdir's distro. `default` selects WSL's default distro; a name pins commands to that distro. |
+| `shell` | `''` | Empty resolves the distro user's login shell. Set an absolute Linux path to pin a shell. |
+| `loginShell` | `true` (shipped) | Use login semantics for POSIX shells. Non-POSIX shells use their own command form. |
+| `agent` | `true` | Use the resident agent. If it is unavailable, commands use the one-shot `wsl.exe` path. Set `false` to always use that path. Cwd and sandbox refusals are returned directly. |
+| `agentBackend` | `auto` (shipped) | `auto` selects the packaged static-musl binary at `agent/native/linux-<arch>/dsh-wsl-agent` or the `DSH_WSL_AGENT_NATIVE` override; otherwise it uses the shell agent. `native` fails if it cannot prepare; `shell` forces the shell agent. Applies to commands, confined writes, and shared reads. |
+| `sessionSandbox` | `false`; shipped `true` | `true` runs the session in a persistent systemd user scope. Requires `agent: true`, systemd as PID 1 (`[boot] systemd=true` in `/etc/wsl.conf`), a user manager, `systemd-run`, and Linger (`loginctl enable-linger <user>`). `false` uses a per-command sandbox. `auto` uses the scope when available and otherwise keeps commands confined per command. The result reports `sessionScope: 'session'` or `'per-command'`. |
+| `sandbox` | `true` | Confine commands with `bwrap`. A missing or unusable `bwrap` fails closed. `false` runs commands without confinement. |
+| `interopVisibility` | Unset; effective default is `visible` | `visible`, `masked`, or `disabled`. When set, this takes precedence over `maskWindowsDrive`. See [Windows interop](#windows-interop). |
+| `maskWindowsDrive` | `false` | For confined commands, mount an empty tmpfs over `/mnt`. See [Windows interop](#windows-interop). |
+| `cwd` | `''` | Default workdir. Empty uses the distro user's home. |
+| `timeoutMs` / `maxTimeoutMs` | `120000` / `600000` (shipped) | Default per-call timeout and the maximum timeout a call may request. |
+| `wslPath` | `wsl.exe` | Path to `wsl.exe`. |
+| `hostCwd` | Unset | Windows workdir for the `wsl.exe` process. Defaults to `%SystemRoot%` when available. |
+| `forwardEnv` | `[]` | Additional host environment names to forward through `WSLENV`. See [Environment forwarding](#environment-forwarding). |
+
+### `wsl-fs`
+
+| Key | Default / shipped value | Description |
+|---|---|---|
+| `distro` | `''` (shipped) | Empty or `auto` follows the target path's distro. `default` selects WSL's default distro; a name pins the filesystem. |
+| `restrictToDistro` | `true` (shipped) | With a pinned distro, refuse paths in another distro's share with `FS_OUTSIDE_DISTRO`. |
+| `sandbox` | `true` | Check writes against the sandbox policy. Confined writes fail closed if `bwrap` is unavailable. |
+| `sessionSandbox` | `false`; shipped `true` | Use the same session runtime as `wsl-shell`. `auto` falls back to a per-policy confined resident when the session runtime is unavailable. |
+| `maskWindowsDrive` | `false` | Hide `/mnt` from confined mutations. Reads are unaffected. |
+| `substrate` | `agent` (shipped) | File operations use the in-distro agent. The legacy `share` value is refused at startup. |
+| `cwd` | `''` | Base directory for relative paths. Empty uses the distro user's home. |
+| `watchMaxDepth` | `0` | Watch the full tree. A positive depth uses bounded polling and can miss changes below the bound until a change above it triggers the callback. |
+| `wslPath` | `wsl.exe` | Path to `wsl.exe`. |
+| `diffBasisMaxBytes` | `10485760` | UTF-8 byte limit per side of an overwrite diff. Larger files are written without a diff. |
+
+### `fs-routing`
+
+This top-level row serves root-level `ctx.fs` calls. It routes distro UNC paths
+to the agent-backed filesystem and drive paths to the host filesystem. Its
+distro settings are independent of `wsl-fs`.
+The Loader validates the host and distro settings before mounting this row;
+values rejected by the schema prevent the router from starting. A `null`
+field value uses its schema default.
+
+| Key | Default / shipped value | Description |
+|---|---|---|
+| `distro` | `''` (shipped) | Empty or `auto` routes each UNC path to its named distro. `default` selects WSL's default distro; a name pins the route. |
+| `wslPath` | `wsl.exe` (shipped) | Path to `wsl.exe`, used to resolve the default distro. |
+| `sandbox` | `true` (shipped) | Check routed mutations against `ctx.sandboxPolicy`; fail closed if `bwrap` is unavailable. The row reports `sandboxMode: undefined` whether the fence is enabled or disabled. |
+| `maskWindowsDrive` | `false` (shipped) | Hide `/mnt` from confined routed mutations. |
+| `restrictToDistro` | `true` (shipped) | Refuse paths in another distro's share when `distro` is pinned. |
+| `watchMaxDepth` | `0` (shipped) | Watch the full tree. A positive depth uses bounded polling. |
+| `distroCwd` | `''` | Default distro workdir; empty uses the distro user's home. |
+| `cwd` | `process.cwd()` | Working directory for the host filesystem backend. |
+| `diffBasisMaxBytes` | `10485760` | Shared overwrite-diff limit for the host and routed backends. |
+
+The root router is app-level, not session-owned, so it does not use
+`sessionSandbox`.
+
+### Picker and terminal rows
+
+| Row | Key | Default / shipped value | Description |
+|---|---|---|---|
+| `directory-picker-wsl` | `preferredDistro` | `''` (shipped) | Distro shown first and used for the Home location. |
+| | `includeHostHome` | `true` (shipped) | Include the Windows home directory. |
+| | `maxEntries` | `1000` (shipped) | Maximum entries returned for one directory. |
+| | `wslPath` | `wsl.exe` | Path to `wsl.exe`. |
+| | `distroCacheMs` | `5000` | Cache lifetime for the distro list. |
+| `subprocess-wsl` | `distro` | `''` (shipped) | Empty or `auto` follows the launch directory's distro. `default` selects WSL's default; a name pins the distro. |
+| | `shell` | `''` | Shell to pin inside the distro. Empty lets `wsl.exe` select the login shell. |
+| | `loginShell` | `true` | Login semantics for a pinned shell. |
+| | `hostSessions` | `true` | A session opened on a Windows folder gets host PowerShell in that folder. WSL-folder sessions use the distro shell. Set `false` to use the composition-owned terminal for every session. |
+| | `terminalIdleReclaim` | `true` | Reclaim idle distro terminals based on their marked processes. An unknown activity state pauses reclamation. |
+| | `cwd` | `''` | Fallback launch directory when none is supplied. |
+| | `wslPath` | `wsl.exe` | Path to `wsl.exe`. |
+| | `hostCwd` | Unset | Windows workdir for the `wsl.exe` process. Defaults to `%SystemRoot%` when available. |
+| | `forwardEnv` | `[]` | Additional host environment names to forward through `WSLENV`. |
+
+### Other top-level rows
+
+| Row | Key | Default | Description |
 |---|---|---|---|
-| `wsl-shell` | `distro` | `''` *(shipped)* | distro mode: empty/`auto` follows the request workdir, `default` forces WSL's default, and a name pins every command |
-| | `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`. Applies only to the POSIX family; a non-POSIX shell (fish, csh) still gets a bare `-c` |
-| | `agent` | `true` | run commands over the resident in-distro agent (one long-lived process; in-distro timeout); the one-shot `wsl.exe` path is fallen back to only when the agent is out of service. Anything else — a cwd refusal, a sandbox refusal — is the command's own verdict and is raised, not retried on the other path |
-| | `sessionSandbox` | `true` *(shipped)* | `true`, `false`, or `auto`. With `true`, run this session's commands in one persistent systemd user scope (ADR 0001): a background dev server survives the command that started it, `/tmp` is the distro's real `/tmp` under `workspace-write`, and `ps` sees the session. The executor holds the runtime for the session and stops the scope from the preset's disposer, which reaps the cgroup. Requires `agent: true`, systemd as PID 1, a reachable user manager and `Linger` (`loginctl enable-linger <user>`); the preflight refuses with the remedy when systemd, the user manager, `systemd-run` or `Linger` is missing (a success is cached; a failure is re-probed, so following the remedy needs no app restart). `auto` uses the scope when those prerequisites answer, and otherwise falls back to the per-command `bwrap` profile — still confined, never unconfined — reporting `sessionScope: "per-command"` in the result (`"session"` when the scope ran); a failed `auto` verdict is re-probed at most once a minute. `false` is the per-command shape. On in the shipped preset |
-| | `agentBackend` | `auto` | the session runtime's in-distro agent. `auto` uses the native agent when a verified source is available — the packaged per-arch static-musl binary at `agent/native/linux-<arch>/dsh-wsl-agent` (x86_64 and aarch64; runs on glibc and musl distros), or the `DSH_WSL_AGENT_NATIVE` development override — and otherwise the shipped shell agent; `native` fails the first command when it cannot prepare instead of silently falling back; `shell` forces the shell agent. Confined writes share the runtime, so they follow the same selection. The native backend is the default (static musl x86_64/aarch64); the shell agent is the fallback, and `native` refuses instead of falling back. This key covers the session runtime (commands and confined writes) and, since A7, the shared read agent (unconfined reads), which also follows this selection with the shell fallback |
-| | `sandbox` | `true` | confine commands with `bubblewrap`; `false` disables the sandbox. Needs a usable `bwrap` inside the distro and fails closed without one (`SANDBOX_UNAVAILABLE`, never an unconfined run) — see [Turning the sandbox off](#turning-the-sandbox-off) |
-| | `interopVisibility` | `visible` | the stance in one key (WSL-314): `visible` / `masked` / `disabled` — see the stance table below. Set at all, the stance takes precedence over the legacy `maskWindowsDrive` boolean (unset lets it answer); `disabled` masks in-session and the doctor's remedy prints the distro-level `[interop] line for the full closure (a config key does not write distro config) |
-| | `maskWindowsDrive` | `false` | shadow `/mnt` with an empty tmpfs in every confined profile: the Windows drive's files cannot be read or exfiltrated and its executables cannot be launched through interop — the hole that lets a "sandboxed" command reach your full Windows token. A narrowing, not a closure (a command can still write an executable into the workspace and run it — binfmt dispatches on content, not location), so enforcement stays `partial` and the result's sandbox fact reports `windowsDrive: "masked"`. The complete closure is distro-level: `[interop] enabled=false` in `wsl.conf` |
-| | `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)* | distro mode: empty/`auto` follows each target path, `default` forces WSL's default, and a name pins the filesystem |
-| | `restrictToDistro` | `true` *(shipped)* | under a fixed `distro` (`default` or a name), refuse a path in **another distro**'s share (`FS_OUTSIDE_DISTRO`). Under `auto`, a UNC target is served by its own distro, so the fence has nothing foreign to refuse. `/mnt/c` is a directory *inside* the selected distro and is not affected |
-| | `sandbox` | `true` | check `writeText` and `editText` against the policy. Needs a usable `bwrap` in the distro too, and fails closed the same way: a distro without one refuses confined mutations (`FS_IO_ERROR`, with the install guidance) rather than downgrading them |
-| | `maskWindowsDrive` | `false` | as on `wsl-shell`: confined fs mutations publish through a resident whose profile shadows `/mnt` (same honest limits) |
-| | `sessionSandbox` | `true` *(shipped)* | `true`, `false`, or `auto`. With `true`, run confined mutations in the same session runtime the shell uses for the same `(distro, workspace, policy)` — one agent, one real `/tmp`, one workspace mount view; requires the same systemd/linger setup and the preflight refuses with the remedy. `auto` uses the runtime when the prerequisites answer and otherwise falls back to the per-policy confined resident (still kernel-confined). Set `false` for the per-policy confined resident. The app-level `fs-routing` backend is not session-owned and keeps this off |
-| | `substrate` | `agent` *(shipped)* | which I/O substrate serves the file tools. Only the resident in-distro agent (`lib/fs-substrate.js`) exists: reads, writes and identities run on ext4 — native symlinks, native mode bits, and the mutation guard survives to the write's atomic publication, kernel-enforced by the confined resident when the policy is confined. The former `share` opt-out (the Windows-side host stack over the 9p share) is refused at boot; delete the line. The comment shipped beside this key in `cordis.patch.yml` still calls `share` the opt-out — that comment is out of date, and the boot refusal is what runs |
-| | `cwd` | `''` | base directory for relative paths; empty means the distro user's home |
-| | `watchMaxDepth` | `0` | how deep the in-distro watch scan walks; `0` walks the whole tree and enables the inotify backend. A positive value keeps the polling scan (inotify cannot bound its walk); a change below the bound is seen only when another change above it fires the same callback |
-| `fs-routing` | `distro` | `''` *(shipped)* | distro mode for the root-plane filesystem: empty/`auto` follows each target's UNC distro, `default` forces WSL's default, and a name pins. **A row of its own**, with its own copy of the distro knobs — changing `wsl-fs` does not change this one, nor the other way round |
-| | `wslPath` | `wsl.exe` *(shipped)* | path to `wsl.exe`; used here only to resolve the default distro |
-| | `sandbox` | `true` *(shipped)* | fence routed mutations by `ctx.sandboxPolicy`; same `bwrap` requirement and fail-closed refusal as `wsl-fs`. The routing row reports no `sandboxMode` — `undefined` whether the fence is on or off |
-| | `maskWindowsDrive` | `false` *(shipped)* | as on `wsl-shell`, for routed mutations |
-| | `restrictToDistro` | `true` *(shipped)* | under a fixed `distro` (`default` or a name), refuse a path in another distro's share (`FS_OUTSIDE_DISTRO`); under `auto`, each UNC target is served by its own distro |
-| | `watchMaxDepth` | `0` *(shipped)* | how deep the routed watch scan walks; `0` walks the whole tree and enables the inotify backend; a positive value keeps the polling scan |
-| | `distroCwd` | `''` | the routed backend's default workdir; empty means the distro user's home. `cwd` belongs to the host backend only — the distro side reads `distroCwd` — while `diffBasisMaxBytes` is shared: it bounds the overwrite diff on both sides |
-| `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)* | distro mode for the GUI terminal: empty/`auto` follows the launch directory, `default` forces WSL's default, and a name pins |
-| | `shell` | `''` | pin a shell; empty lets `wsl.exe` decide |
-| | `loginShell` | `true` | whether a pinned shell uses login semantics |
-| | `hostSessions` | `true` | give a session opened on a Windows folder a host `powershell.exe` in its own directory instead of the distro shell at `/mnt/<drive>/…`; `false` restores the composition-owned distro terminal for every session |
-| | `terminalIdleReclaim` | `true` | let the controller reclaim an idle distro terminal: the launch is marked with a per-terminal `DSH_TERMINAL_ID`, and the handle's `inspectActivity` counts the marked processes through the resident agent — one (the shell at its prompt) is idle, more than one (a running command or a nested shell) is busy, `unknown` (agent out) pauses reclamation. `false` restores close-by-hand |
-
-The GUI file tree and previews use the shipped `workspace-files` row, not a plugin
-row. Its caps are the peer defaults (`maxBytes` 2 MiB, `maxFileBytes` 32 MiB,
-`maxLines` 5000, `maxEntries` 2000); override them with `- id: workspace-files`
-in your own layer.
-
-## Overriding the rows inside `preset-wsl`
-
-`wsl-shell` and `wsl-fs` are mounted as plugins of the `wsl` agent preset, inside
-the `preset-wsl` row's `config.plugins`. The loader indexes top-level entry ids —
-plus the plugin lists of rows that are themselves groups — and `preset-wsl` is a
-plain entry whose plugins sit inside its `config`, so those two ids are not
-addressable from a patch layer at all. A layer of
-
-```yaml
-- id: wsl-shell
-  config:
-    distro: Ubuntu
-
-- id: wsl-fs
-  config:
-    restrictToDistro: false
+| `auto-preset` | `preset` | `wsl` | Preset to bind when a session workspace is inside a distro. An explicit operator selection is preserved. |
+| | `attempts` | `6` | Number of attempts to bind the preset. |
+| | `retryMs` | `150` | Delay between attempts, in milliseconds. |
+| `wsl-preflight` | `distro` | `''` | Distro to check. Empty or `auto` follows the session workspace. |
+| | `wslPath` | `wsl.exe` | Path to `wsl.exe`. |
+| | `sandbox` | `true` | Run the session-start `bwrap` check. |
+| | `sessionSandbox` | `true` | Also check systemd, the user manager, `systemd-run`, and Linger. Set false when the profile does not use a session runtime. |
+| `wsl-shell-env` | `distro` | `''` | Distro used to populate the `DSH_WSL_*` environment facts. |
+| | `portsRefreshMs` | `10000` | Listening-port snapshot interval, in milliseconds. |
+
+The GUI file tree and previews use the bundled `workspace-files` row through
+`fs-routing`; they do not use a separate WSL provider row. To change its
+peer-defined limits, override `workspace-files` by id in the profile layer.
+
+## Shared command settings
+
+The shell row inherits output and process settings from
+`@deepseek-ai/dsh-bash-local`:
+
+| Key | Default | Description |
+|---|---|---|
+| `maxOutputBytes` | `64000` | Per-stream captured output limit. The agent enforces this limit inside the distro and marks truncated results. |
+| `maxSpillBytes` | `67108864` | Per-stream spill-file limit on the one-shot path. |
+| `graceMs` | `3000` | Grace period between SIGTERM and SIGKILL. |
+
+With `agent: true`, captured output is limited inside the distro and no spill
+file is written. `maxSpillBytes` and `graceMs` apply when `agent: false` or
+when the resident agent is unavailable and execution uses one-shot `wsl.exe`.
+
+## Environment forwarding
+
+WSL imports a host environment variable only when its name is listed in
+`WSLENV`. The providers forward `NO_COLOR`, `TERM`, `PAGER`, `GIT_PAGER`,
+`LANG`, `LC_ALL`, and managed `DSH_*` names by default. `forwardEnv` adds names
+to that list; `PATH` is never forwarded.
+
+For `wsl-shell`, `forwardEnv` applies to the one-shot `wsl.exe` path. The
+resident agent receives only the managed `DSH_*` environment, so custom names
+in `forwardEnv` do not reach commands running through that agent. The
+`subprocess-wsl` setting applies to its WSL launches.
+
+## Distro selection
+
+For command and terminal rows, an empty `distro` or `distro: auto` follows
+the request's UNC workdir. When the request does not name a distro, WSL's
+default distro is used. For `wsl-fs`, `auto` follows each target path. For
+`fs-routing`, each UNC target selects its own distro.
+
+`distro: default` always selects WSL's default distro. A distro name pins the
+row to that distro. With `restrictToDistro: true`, a path in another distro's
+share is refused with `FS_OUTSIDE_DISTRO`. The Windows drive mounted at
+`/mnt/c` is inside the selected distro and is not rejected by this fence.
+
+## Windows interop
+
+`interopVisibility` controls whether `/mnt` is masked for confined commands;
+it does not itself disable Windows interop. If unset, `maskWindowsDrive: false`
+gives the `visible` behavior.
+
+| Value | Effect |
+|---|---|
+| `visible` | Leaves `/mnt` visible. Confined commands can read Windows files and launch Windows executables through WSL interop. |
+| `masked` | Mounts an empty tmpfs over `/mnt` in confined profiles. Commands cannot access paths under `/mnt`; other mounts and unrestricted file reads are not covered. |
+| `disabled` | Applies the same `/mnt` mask as `masked`; it does not disable interop or edit `wsl.conf`. Configure the distro separately as described below. |
+
+`maskWindowsDrive: true` is equivalent to `interopVisibility: masked`.
+When `interopVisibility` is set, it takes precedence over
+`maskWindowsDrive`.
+
+Masking narrows access; it does not close interop. WSL can still run a Windows
+executable written into the workspace because `binfmt_misc` dispatches by file
+content. Enforcement therefore remains `partial`, and results report
+`windowsDrive: 'masked'`. To disable interop for the distro, add this section
+to `/etc/wsl.conf`:
+
+```ini
+[interop]
+enabled=false
 ```
 
-changes nothing and does not fail: the log carries
-`patch: entry "wsl-shell" not found` and `patch: entry "wsl-fs" not found`, and the
-composed config keeps the shipped values.
+Then run `wsl.exe --shutdown`. This distro-level change is required to close
+interop.
 
-The helper does the extraction and the common edits for you:
+To apply the masked profile to both nested rows:
 
 ```bash
-pnpm run preset -- --distro Ubuntu --session-sandbox false \
-  --out "$DSH_HOME/profiles/<name>/cordis.patch.yml"
+pnpm run preset --sandbox true --mask-windows-drive true
 ```
 
-`--distro`, `--session-sandbox`, `--sandbox`, `--mask-windows-drive` and
-`--agent-backend` are the supported edits; without `--out` the helper prints the
-complete block instead of writing it. `pnpm run preset -- --check <file>` reads an
-existing layer and **fails with the exact block to paste** when it finds a
-top-level `- id: wsl-shell`/`wsl-fs` entry — the silent no-op is caught before
-boot. The generated block is byte-for-byte the shipped row plus your edits, so a
-plugin upgrade only needs a re-run.
-
-The route that works is to override the `preset-wsl` row as a whole. A row's
-`config` is replaced whole, never deep-merged, so the replacement has to carry
-`id`, `order` and the entire `plugins` list — every plugin, the `wsl-env` group
-and everything after it. Copy the whole `- id: preset-wsl` block out of
-[`cordis.patch.yml`](../cordis.patch.yml) (or out of
-`dsh --profile <name> --dump-config`), paste it into your layer, and edit only the
-values you want:
-
-```yaml
-- id: preset-wsl
-  config:
-    id: wsl
-    order: 2
-    plugins:
-      - id: wsl-env
-        name: cordis:group
-        group: true
-        isolate:
-          shell: true
-          fs: true
-        config:
-          - id: wsl-shell
-            name: 'dsh-plugin-wsl-env'
-            config:
-              distro: Ubuntu          # ← the edit
-              loginShell: true
-              timeoutMs: 120000
-              maxTimeoutMs: 600000
-          - id: wsl-fs
-            name: 'dsh-plugin-wsl-env/fs'
-            config:
-              distro: ''
-              restrictToDistro: false # ← the edit
-              substrate: agent
-          # … and the rest of the group, verbatim — do not leave a plugin out …
-```
+Merge the printed block into the profile. The `visible` and `masked` behavior
+is covered by `test/probe/interop-shell.sh` for both resident and one-shot
+commands. The distro-level disabled state requires a manual check because it
+changes WSL configuration.
 
-Leaving a plugin out of the replacement drops it: the preset would mount only the
-plugins you listed. The keys described above are the only reason to rewrite this
-row, so treat the `preset-wsl` block as one unit and re-copy it after a plugin
-upgrade that changes it.
+## Sandbox and preflight
 
-For the root-plane filesystem — the row that serves `ctx.fs` outside any session,
-`fs-routing` — no rewrite is needed: it is a top-level row, and
-`restrictToDistro`, `sandbox` and `maskWindowsDrive` can be set on it directly.
-That governs different traffic from `wsl-fs`; see
-[`docs/root-fs-routing.md`](root-fs-routing.md).
+`sandbox: true` is the default for `wsl-shell`, `wsl-fs`, and
+`fs-routing`. Confined commands and mutations require a usable `bwrap` inside
+the distro. If it is missing or unusable, commands fail with
+`SANDBOX_UNAVAILABLE` and writes fail with `FS_IO_ERROR`; neither operation
+falls back to an unconfined run. The error distinguishes a missing package from
+a present but unusable `bwrap`.
 
-## Other keys
+Install the prerequisite with the bootstrap helper:
 
-You can override the other keys in the same way, with one split: every row in the
-table below except `wsl-shell` and `wsl-fs` is top-level, so `- id: <row>` in your
-own layer patches it — those two are inside `preset-wsl` and take the rewrite
-above. They all keep their defaults:
+```bash
+scripts/bootstrap.sh <distro> --install
+```
 
-| Row | Key | Default | Meaning |
-|---|---|---|---|
-| `wsl-shell` (in `preset-wsl`) | `wslPath` | `wsl.exe` | path to `wsl.exe`, for an installation that is not on `PATH` |
-| | `hostCwd` | unset → `%SystemRoot%` | the Windows directory the `wsl.exe` process itself starts in |
-| | `forwardEnv` | `[]` | extra host environment variable names to forward into the distro through `WSLENV`. This is the one key here that widens what crosses the boundary: `NO_COLOR`, `TERM`, `PAGER`, `GIT_PAGER`, `LANG`, `LC_ALL` and every managed `DSH_*` name ride along without it, and `PATH` is deliberately never forwarded. It applies to the **one-shot `wsl.exe` path**; the resident agent's environment stays pinned to the managed `DSH_*` namespace and deliberately does not forward these names, so a secret listed here does not widen every model command in the session |
-| `wsl-fs` (in `preset-wsl`) | `wslPath` | `wsl.exe` | as above; used only to resolve the default distro |
-| | `diffBasisMaxBytes` | `10485760` | UTF-8 byte limit per side of an overwrite diff; a larger file publishes without a diff |
-| `fs-routing` | `cwd`, `diffBasisMaxBytes` | `process.cwd()`, `10485760` | `cwd` configures the host side only (the distro side reads `distroCwd`); `diffBasisMaxBytes` is shared by both — it also bounds the routed backend's overwrite diff |
-| `directory-picker-wsl` | `wslPath` | `wsl.exe` | as above |
-| | `distroCacheMs` | `5000` | how long a resolved distro list stays fresh before `wsl.exe` is asked again |
-| `subprocess-wsl` | `wslPath` | `wsl.exe` | as above |
-| | `cwd` | `''` | fallback directory when a launch names none |
-| | `hostCwd` | unset → `%SystemRoot%` | as on `wsl-shell` |
-| | `forwardEnv` | `[]` | as on `wsl-shell`, for terminal launches |
-
-The shell row also inherits the shipped output budgets from `dsh-bash-local`,
-which documents them in full: `maxOutputBytes` (64000), `maxSpillBytes`
-(67108864) and `graceMs` (3000, the SIGTERM-to-SIGKILL grace). The spill keys
-belong to the one-shot path: with `agent: true` — the default — the capture is
-cut at `maxOutputBytes` per stream inside the distro, the result reports
-`truncated: true`, and no temporary file is written, so `maxSpillBytes` and
-`graceMs` have nothing to bound. They apply when `agent` is `false` or the agent
-is out of service and the call rides the one-shot `wsl.exe` path.
-
-## Which distro is used
-
-`distro: ''` (or `distro: 'auto'`) follows the workspace: opening
-`\\wsl.localhost\Debian\...` runs there even when Ubuntu is WSL's default.
-`distro: 'default'` forces WSL's default instead, and a fixed distro (`default` or
-a name) pins every session to that distro — a foreign UNC then refuses with
-`FS_OUTSIDE_DISTRO` while `restrictToDistro` holds. A single-distro installation
-needs no configuration.
-
-## The strict profile
-
-`maskWindowsDrive: true` with `sandbox: true` is the strict profile: every
-confined profile shadows `/mnt` with an empty tmpfs, so a confined command can
-neither read the Windows drive nor launch a Windows executable from it. Write it
-into a profile with the preset helper (the rows are nested inside `preset-wsl`):
+Without `--install`, the helper performs a read-only check. On apt-based
+distros, the direct install command is:
 
 ```bash
-pnpm run preset -- --sandbox true --mask-windows-drive true \
-  --out "$DSH_HOME/profiles/<name>/cordis.patch.yml"
+wsl.exe -d <distro> -u root -- apt-get install -y bubblewrap
 ```
 
-The trade-offs are real: confined commands lose `/mnt/c` entirely — no reading
-Windows files, no running Windows tools, no dev server that expects a Windows
-path. It is also a narrowing, not a closure: a command can still write a Windows
-executable into the workspace and run it there, because WSL's `binfmt_misc`
-dispatches on content, not location. Enforcement therefore stays `partial`, and
-the result reports `windowsDrive: "masked"`. The only complete closure is
-distro-level: `[interop] enabled=false` in `/etc/wsl.conf`, then
-`wsl.exe --shutdown`, which removes interop from the distro entirely.
-
-| Interop state | How | `/mnt` | Windows exe from `/mnt` | Workspace-written `.exe` | Evidence |
-|---|---|---|---|---|---|
-| visible (default) | — | readable | runs, and escapes the Linux sandbox | runs | `pnpm run probe:sandbox` — INFO "interop escape is open" |
-| masked (strict) | `maskWindowsDrive: true` | empty tmpfs | unreachable | still runs (binfmt) | `pnpm run probe:sandbox` — the strict-profile checks |
-| disabled | `[interop] enabled=false`, `wsl --shutdown` | no Windows mounts | n/a | fails (no binfmt) | documented; not probed automatically (needs a distro-level change) |
-
-The masked and visible legs are asserted on the real machine by
-`test/probe/sandbox.sh`; the disabled leg needs a distro configuration change and
-a WSL shutdown, so it stays a manual check recorded here.
-
-## Turning the sandbox off
-
-`sandbox: false` on `wsl-shell` and `wsl-fs` runs commands and writes without
-confinement. `sandboxMode` then reports `undefined`, and the tool layer tells the
-model that these operations have no sandbox. `fs-routing` takes the same key and
-drops the fence on the root-plane filesystem the same way, but that service reports
-no `sandboxMode` either way — it inherits the base class's empty getter — so the
-key decides the fence, not a capability fact the model reads. That is the documented
-opt-out; see [ARCHITECTURE.md](ARCHITECTURE.md#sandbox) for what the sandbox does
-and does not cover.
-
-The default posture needs `bubblewrap` **inside the distro** and fails closed: a
-distro without a usable `bwrap` refuses the command (`SANDBOX_UNAVAILABLE`) or the
-write (`FS_IO_ERROR`, the message carrying the same guidance) instead of
-running it unconfined. The refusal distinguishes the two causes — `bwrap`
-missing (install it) from `bwrap` present but failing (usually the kernel's
-unprivileged user namespaces; reinstalling will not help) — and the direct
-install command it prints follows the distro's own package family
-(apt/dnf/pacman/zypper). A failed probe is re-run,
-so installing `bubblewrap` takes effect on the next command without a restart.
-Install it with `scripts/bootstrap.sh <distro> --install`, or directly:
-`wsl.exe -d <distro> -u root -- apt-get install -y bubblewrap`. Run without
-`--install`, `scripts/bootstrap.sh <distro>` is a read-only check that prints what
-is missing.
-
-The same probe also runs when a session opens: the `wsl-preflight` row warns
-with the full remedy if `bwrap` is unusable, so the news arrives with the
-session rather than with the first failed command. It also checks the session
-runtime's prerequisites — systemd as PID 1, the user manager, `systemd-run` and
-Linger — when `sessionSandbox` on the preflight row is `true` (the default,
-matching the shipped preset). Set `sessionSandbox: false` on that row when the
-profile opts out of the session runtime, so it does not warn about a
-prerequisite the profile does not use.
-
-The advisory is logged and also published as a `wsl-preflight` runtime-context
-entry, so it reaches the session transcript; DSH 0.2.1 has no toast/banner seam
-for a plugin (see [UPSTREAM-SESSION-NOTICE.md](UPSTREAM-SESSION-NOTICE.md) and
-[LIMITATIONS.md](LIMITATIONS.md#session-start-advisories)). It is advisory — it
-never installs anything and never changes the fail-closed semantics; drop the
-`wsl-preflight` row from your layer (or set `sandbox: false` on it) to silence
-the warning.
-
-## Checking a change, and what refuses
-
-`dsh --profile <name> --dump-config` composes the profile and prints the result
-without booting. It is the fastest way to see whether a row you wrote landed —
-including the warning that says it did not — and for the rows inside `preset-wsl`
-the composed tree it prints carries the block to copy back into your layer.
-`scripts/bootstrap.sh <distro>` does the same for the distro-side prerequisites.
-
-When something refuses, the message names the row or the code:
-
-| Symptom | What you see | What clears it |
+The `wsl-preflight` row runs these checks when a session opens. It also checks
+the session-runtime prerequisites when `sessionSandbox: true`. The warning is
+advisory: it does not install packages or change the providers' fail-closed
+behavior. Set `sandbox: false` on this row or remove it to silence the
+sandbox warning. Set `sessionSandbox: false` when the profile does not use a
+session runtime.
+
+Setting `sandbox: false` on `wsl-shell` or `wsl-fs` runs commands or writes
+without confinement; their `sandboxMode` becomes `undefined`. The tool layer
+reports that no sandbox is active. On `fs-routing`, the setting disables the
+mutation fence; that row reports `sandboxMode: undefined` either way.
+
+## Diagnose configuration and refusals
+
+Use `dsh --profile <name> --dump-config` to inspect the composed profile
+without booting it. The output shows whether a row override applied. Use
+`scripts/bootstrap.sh <distro>` to inspect distro prerequisites.
+
+| Symptom | Result | Action |
 |---|---|---|
-| commands fail with no usable sandbox | `SANDBOX_UNAVAILABLE` — the text says whether `bwrap` is missing or present but failing, with the matching remedy | missing: install `bubblewrap` (`scripts/bootstrap.sh <distro> --install`, or the printed family command); present-but-failing: check `bwrap --version` and the kernel's unprivileged user namespaces, or set `sandbox: false` on `wsl-shell` |
-| writes fail with no usable sandbox | `FS_IO_ERROR`, with the same `bwrap` remedy the commands carry | the same install, or `sandbox: false` on `wsl-fs` (`fs-routing` for root-plane writes) |
-| file tools fail while the distro is down | `FS_IO_ERROR`, "the distro file substrate is unavailable" | start the distro (`wsl.exe -l -v`), restart the session if it stays out |
-| a command never starts | a `WSL_E_*` code naming the distro | start it with `wsl.exe -d <distro>`, or point `distro` at another one — wider permissions do not help |
-| `wsl.exe` itself cannot be started | the error names the executable and says to check `wslPath` on this row | fix `wslPath`, and check WSL is installed |
-| WSL wedges mid-command | no completion within the deadline | retry once, then `wsl.exe --shutdown` and reopen |
-| a watched path never fires | `FS_IO_ERROR` from `watch` | watch a path inside the selected distro |
-| a path in another distro is refused | `FS_OUTSIDE_DISTRO` | only when `distro` is pinned; set `distro: ''`/`auto` to follow the workspace, or open a session in that distro |
-
-The full code table — what each code means and what clears it — is
-[ARCHITECTURE.md § Error codes](ARCHITECTURE.md#error-codes); the design boundaries
-behind the fail-closed choices above are in [LIMITATIONS.md](LIMITATIONS.md).
-
-## `wsl-shell-env`
-
-| Key | Default | Meaning |
-| --- | --- | --- |
-| `distro` | `''` | distro mode for the `DSH_WSL_*` facts: empty/`auto` follows each session's workspace, `default` forces WSL's default, and a name pins |
-| `portsRefreshMs` | `10000` | how often the `DSH_WSL_PORTS` listening-port snapshot refreshes through the resident agent. A failed scan keeps the last successful list (and a debug line), so a transient agent outage does not read as “no ports”; only a successful empty scan means none were listening |
+| Command sandbox unavailable | `SANDBOX_UNAVAILABLE`; message distinguishes missing or unusable `bwrap`. | Install `bubblewrap`, repair user namespaces, or set `sandbox: false` on `wsl-shell`. |
+| Confined write unavailable | `FS_IO_ERROR` with the `bwrap` remedy. | Install or repair `bubblewrap`; to disable the fence, set `sandbox: false` on `wsl-fs` or `fs-routing`. |
+| File operations fail while the distro is stopped | `FS_IO_ERROR`: distro substrate unavailable. | Start the distro. If the agent remains unavailable, restart the session. |
+| Command cannot start in the selected distro | `WSL_E_*` code naming the distro. | Start that distro or change `distro`. Wider permissions do not resolve a stopped distro. |
+| `wsl.exe` cannot start | Error names the executable and the row's `wslPath`. | Correct `wslPath` and confirm WSL is installed. |
+| WSL hangs during a command | Command reaches its deadline without completion. | Retry once, then run `wsl.exe --shutdown` and reopen the session. |
+| A watched change does not notify | Polling can miss changes that preserve the observed metadata; no error is guaranteed. | Check the watcher limits in [LIMITATIONS.md](LIMITATIONS.md). |
+| A path in another distro is refused | `FS_OUTSIDE_DISTRO`. | Use `distro: ''` or `auto` to follow the workspace, or open the session in the target distro. |
+
+See [ARCHITECTURE.md — Error codes](ARCHITECTURE.md#error-codes) for the full
+error reference and [LIMITATIONS.md](LIMITATIONS.md) for the design boundaries.