dsh-plugin-wsl-env 0.11.0 → 0.13.0

package/docs/ARCHITECTURE.md

@@ -26,19 +26,25 @@ root-plane services, and adds three smaller integrations.
 extends the shipped `LocalFileSystem`. Only the parts that need a distro are
 overridden.
 
-## The two root-plane takeovers
+## The root-plane filesystem takeover
 
-Two of the shipped services are session-less — the GUI file tree and the root
-`ctx.fs` — so they cannot be served from an agent preset. The layer replaces
-their shipped rows outright, with subclasses that route by coordinate:
+One of the shipped services is session-less — the root `ctx.fs` — so it cannot
+be served from an agent preset. The layer replaces its shipped row outright with
+a subclass that routes by coordinate:
 
 | Service | Class | File | What it does |
 |---|---|---|---|
-| `ctx.workspaceFiles` | `WorkspaceFilesWsl` | [`lib/workspace-files-wsl.js`](../lib/workspace-files-wsl.js) | The GUI file tree and previews for a `\\wsl.localhost\<distro>` workspace, served from inside the distro over the resident agent instead of Windows-side 9P walks. Extends the shipped service: a distro UNC routes distro-side, a drive path calls `super`, and the watch stream delegates unchanged — so replacing the row is safe for Windows-folder sessions too. Replaces the shipped `workspace-files` row. |
 | `ctx.fs` (root plane) | `WslRoutingFileSystem` | [`lib/fs-routing.js`](../lib/fs-routing.js) | The root filesystem, routed by coordinate: a distro UNC identity is served by the resident agent (real watch events, ext4 reads), a drive path stays host-native. Replaces the shipped `fs-sandbox` row, whose write fence has no root-plane consumers — the model's writes ride the preset filesystems. [`root-fs-routing.md`](root-fs-routing.md) is the design. |
 
-Both routes are composition-level for the mirror-image reason the terminal is
-(see below): no session identity reaches them. Each takeover is a top-level
+The GUI file tree and previews keep the shipped `workspace-files` row. Its
+client half is the browser `file` resource provider the Sidebar previews need,
+so replacing the row with a server-only subclass would drop it; the shipped
+service reads WSL paths through the routed root filesystem instead. The cost is
+extra `ctx.fs` round trips per listing, `stat` or page read (see
+[LIMITATIONS](LIMITATIONS.md)).
+
+The takeover is composition-level for the mirror-image reason the terminal is
+(see below): no session identity reaches the root filesystem. It is a top-level
 `disabled:` entry targeting the shipped row plus a bare `insert:` list holding
 the replacement — because a `disabled` written *inside* an insert list is not a
 patch but a duplicate-id data row, and a nested `insert:` is never interpreted at
@@ -60,7 +66,7 @@ functions.
 |---|---|---|---|
 | `dsh-plugin-wsl-env/picker` | `WslDirectoryPicker` | [`lib/picker.js`](../lib/picker.js) | Adds the installed distros to the folder picker, next to the Windows home directory, and lists distro levels from inside the distro (the resident's `ls`, one-shot `wsl.exe` when it is out). |
 | `dsh-plugin-wsl-env/auto-preset` | `auto-preset` | [`lib/auto-preset.js`](../lib/auto-preset.js) | Binds the `wsl` agent preset when a new session's workspace is inside a distro. |
-| `dsh-plugin-wsl-env/shell-env` | `wsl-shell-env` | [`lib/shell-env.js`](../lib/shell-env.js) | Contributes `DSH_WSL_DISTRO`, `DSH_WSL_SHELL`, `DSH_WSL_HOME` and `DSH_WSL_PORTS` to the managed `DSH_*` namespace. The port list is a snapshot, refreshed every `portsRefreshMs` (10000 by default), so a server started moments ago may not be listed yet. |
+| `dsh-plugin-wsl-env/shell-env` | `wsl-shell-env` | [`lib/shell-env.js`](../lib/shell-env.js) | Contributes `DSH_WSL_DISTRO`, `DSH_WSL_SHELL`, `DSH_WSL_HOME` and `DSH_WSL_PORTS` to the managed `DSH_*` namespace, choosing the session workspace's distro (default/pinned facts are probed at mount; other distros are warmed when their session appears). The port list is a snapshot per active distro, refreshed every `portsRefreshMs` (10000 by default), so a server started moments ago may not be listed yet. |
 
 Three modules support them and import no DSH package.
 [`lib/paths.js`](../lib/paths.js) translates paths.
@@ -79,9 +85,9 @@ The environment is per session, not per process:
 |---|---|---|
 | `wsl-shell`, `wsl-fs` | inside `preset-wsl`, an agent preset with isolate realms | so one process can serve a Windows workspace and a distro workspace at the same time |
 | `subprocess-wsl` | at the app level, called the composition; the shipped `subprocess` row is disabled | because no session identity reaches the terminal controller, see below |
-| `workspace-files-wsl` | at the app level; the shipped `workspace-files` row is disabled | the GUI file tree is session-less, so it cannot be served from a preset |
+| `workspace-files` | shipped, not replaced | its client half is the browser `file` resource provider the Sidebar previews need; it reads WSL paths through the routed root filesystem |
 | `fs-routing` | at the app level; the shipped `fs-sandbox` row is disabled | the root `ctx.fs` is session-less, and its write fence has no root-plane consumers |
-| `directory-picker-wsl`, `wsl-shell-env`, `auto-preset` | at the app level | they answer questions that are not scoped to a session |
+| `directory-picker-wsl`, `wsl-shell-env`, `auto-preset` | at the app level | they answer questions that are not scoped to a single preset; `shell-env` resolves its facts per session workspace |
 
 The preset mount requires the isolate realms. Without them the registry rejects the
 providers with `Preset services require isolate realms: shell, fs`.
@@ -282,16 +288,17 @@ failures are named as well. Every `FsError` code the plugin itself raises appear
 below — a model sees the code, and a reader asking what refused them finds it here.
 Codes the shipped host stack raises behind a drive path pass through
 `lib/fs-routing.js` unchanged and are the peer's, not this table's; the GUI file
-tree's own wire refusals are a separate dialect, listed after the table.
+service is the shipped `workspace-files` row, so its wire refusals are the peer's
+own dialect, described after the table.
 
 | Code | Raised by | Meaning | What clears it |
 |---|---|---|---|
 | `SANDBOX_UNAVAILABLE` | `WslSandbox.confine` | the requested mode cannot be enforced: no usable `bwrap` in the distro | install `bubblewrap` there (a failed probe is re-run, so no restart is needed), or set `sandbox: false` |
 | `FS_SANDBOX_DENIED` | `WslFileSystem.checkedTarget`, and `lib/fsio-agent.js` (a write the confined resident's mount table refused, classified from the kernel's `read-only file system`) | the file-effect policy refused the write: `read-only`, or a target outside the writable roots — or the kernel refused it at the resident's profile | a wider permission for that one call, or a session workspace that contains the target |
-| `FS_OUTSIDE_DISTRO` | `WslFileSystem.worldPath` | `restrictToDistro` is on and the path names **another distro**'s share — a configuration fence, not a sandbox decision | open a session in that distro, or set `restrictToDistro: false`. A wider permission does **not** lift it |
+| `FS_OUTSIDE_DISTRO` | `WslFileSystem.worldPath` | `distro` is fixed (`default` or a name), `restrictToDistro` is on, and the path names **another distro**'s share — a configuration fence, not a sandbox decision. With `distro: ''`/`auto` a UNC target is served by its own distro, so the fence has nothing foreign to refuse | set `distro` to `''`/`auto` (the default), or open a session in that distro. A wider permission does **not** lift it |
 | `FS_NOT_OBSERVED` | `lib/fs-substrate.js` (`writeText`; the agent's `exists` conclusion, mapped in `lib/fsio-agent.js`) | a guarded create (`createIfAbsent`) targeted a file that exists and had not been read first | read the file, then overwrite with the version guard or edit it |
 | `FS_STALE_VERSION` | `lib/fs-substrate.js` (`writeText`, `editText`; the agent's `stale` conclusion, mapped in `lib/fsio-agent.js`) | the version the caller holds no longer matches: the file changed, or is gone | read it again and retry with the fresh version |
-| `FS_IO_ERROR` | the filesystem stack: `lib/fs-decisions.js` (the substrate is unavailable), `lib/fsio-agent.js` (a `perm`/`loop`/`io` reason or a malformed record), `lib/index.js` (a path that cannot be mapped, or a `SandboxUnavailableError`), and `WslFileSystem.watch` | the catch-all I/O failure — most often the resident agent is out or the distro returned an I/O error, the "agent outage fails closed" case above. A watch target outside the pinned distro is the narrow one | get the resident back (check `wsl.exe -l -v`, then restart the session); for a watch, aim it at a distro path — the watch itself runs where the files live (`lib/watcher.js`) |
+| `FS_IO_ERROR` | the filesystem stack: `lib/fs-decisions.js` (the substrate is unavailable), `lib/fsio-agent.js` (a `perm`/`loop`/`io` reason or a malformed record), `lib/index.js` (a path that cannot be mapped, or a `SandboxUnavailableError`), and `WslFileSystem.watch` | the catch-all I/O failure — most often the resident agent is out or the distro returned an I/O error, the "agent outage fails closed" case above. A watch target outside the selected distro is the narrow one | get the resident back (check `wsl.exe -l -v`, then restart the session); for a watch, aim it at a distro path — the watch itself runs where the files live (`lib/watcher.js`) |
 | `FS_NOT_FOUND` | `lib/fsio-agent.js` and `lib/fs-substrate.js` (the agent's `notfound`/`notdir` conclusion, an empty path, or a missing edit target), and the host filesystem stack behind a drive path | the path does not exist — the ordinary answer | — |
 | `FS_NOT_REGULAR_FILE` | `lib/fsio-agent.js`, `lib/fs-substrate.js` | the target is not a regular file where one is required: a directory, symlink or device on a read, or a non-file target on a write | point the call at a regular file |
 | `FS_NOT_DIRECTORY` | `lib/fsio-agent.js` (`listChildren`) | the target is not a directory, so there are no children to list | list a directory |
@@ -301,14 +308,11 @@ tree's own wire refusals are a separate dialect, listed after the table.
 | `FS_EDIT_NOT_FOUND` | `lib/fsio-text.js` (`applyLiteralEdit`) | `old_string` was empty, or matched nothing in the file | give an `old_string` the file actually contains |
 | `FS_AMBIGUOUS_EDIT` | `lib/fsio-text.js` (`applyLiteralEdit`) | `old_string` matched more than once and `replace_all` was not set | make `old_string` unique, or set `replace_all` |
 
-The GUI file tree speaks a second dialect. `WorkspaceFilesWsl` refuses through the
-typert wire's `RemoteError`s, not `FsError`s, so its codes are not in the table
-above: `workspace-file/not-found`, `workspace-file/outside-workspace`,
-`workspace-file/not-directory`, `workspace-file/not-regular-file`,
-`workspace-file/not-text`, and `workspace-file/too-large` (one code for both the
-full-file cap and the byte-window cap), plus `gateway/bad-request` for a malformed
-page request (a non-integer offset, or a limit above `maxLines`). A drive-path
-workspace calls the shipped service and gets the peer's own answers instead.
+The GUI file service keeps the shipped `workspace-files` row, so its wire
+refusals are the peer's `workspace-file/*` dialect (plus `gateway/bad-request`
+for a malformed page request), not this plugin's `FsError` codes. The plugin
+supplies the routed `ctx.fs`; an agent outage reaches the service as
+`FS_IO_ERROR` and the peer maps it.
 
 Two failures come from `wsl.exe` itself rather than from a code of ours, and both used
 to be invisible:
@@ -347,7 +351,7 @@ step with the checkout, and `pnpm run sync:windows` runs that script.
 | Type check | `tsc --noEmit` over `test/**` and `types/*.d.ts` (`src/` is checked by the build itself) | no |
 | Unit tests | `test/*.test.mjs` | no |
 | Sandbox probe | [`test/probe/sandbox.sh`](../test/probe/sandbox.sh) | no; it applies the profile arguments directly |
-| Harness probes | [`test/probe/run.sh`](../test/probe/run.sh), `terminal.sh`, `sandbox-shell.sh`, `picker.sh`, `missing-wsl.sh`, `sandbox-off.sh` | yes: Windows, WSL2, a mounted profile, and a linked checkout |
+| Harness probes | [`test/probe/run.sh`](../test/probe/run.sh), `terminal.sh`, `sandbox-shell.sh`, `picker.sh`, `fs-routing.sh`, `missing-wsl.sh`, `sandbox-off.sh` | yes: Windows, WSL2, a mounted profile, and a linked checkout |
 | Distro probes | [`test/probe/substrate.sh`](../test/probe/substrate.sh), `watch.sh`, `agent.sh`, `exec.sh` | Windows and WSL2, but no harness boot and no profile: they run from a distro terminal with Node available, reaching `wsl.exe` through interop |
 | Host probe | [`test/probe/mode.sh`](../test/probe/mode.sh) | Windows Node, no harness |
 | Probe plugins | the `*-probe.mjs` and `*-probe.yml` files in `test/probe/` | loaded by the scripts above |
@@ -361,9 +365,8 @@ waits for the app to exit and then runs the whole real-machine suite once —
 The unit tests come in two kinds: most import only Node builtins, while
 [`test/composition.test.mjs`](../test/composition.test.mjs),
 [`test/fs.boot.test.mjs`](../test/fs.boot.test.mjs),
-[`test/fsio-agent.test.mjs`](../test/fsio-agent.test.mjs),
-[`test/provider.test.mjs`](../test/provider.test.mjs) and
-[`test/workspace-files-wsl.test.mjs`](../test/workspace-files-wsl.test.mjs) import
+[`test/fsio-agent.test.mjs`](../test/fsio-agent.test.mjs) and
+[`test/provider.test.mjs`](../test/provider.test.mjs) import
 pinned `@deepseek-ai/*` development dependencies (the composition and boot tests run
 the loader's real patch algorithm). One `pnpm install` reproduces that tree before
 the first run; the runtime package itself still ships zero dependencies. CI runs
@@ -413,6 +416,8 @@ src/auto-preset.ts           per-session environment selection
 src/bwrap.ts                 the bwrap command line every confinement site
                              assembles (no imports, so a bare checkout can
                              assert it)
+src/distro-route.ts          the pure distro-mode selector (pinned / workspace /
+                             default) shared by shell, fs, preflight and env
 src/file-reference-wsl.ts    the distro-side `@`-completion traversal — built,
                              tested, not yet wired (see above)
 src/fs.ts                    the ctx.fs subpath entry point
@@ -444,10 +449,6 @@ src/terminal-activity.ts     the distro-side activity probe for idle terminal
                              reclamation
 src/terminal-route.ts        which execution world a terminal launch belongs to (pure)
 src/watcher.ts               in-distro file watching for WslFileSystem.watch
-src/workspace-files-route.ts pure builders and parsers for the routed
-                             workspace-files service
-src/workspace-files-wsl.ts   WorkspaceFilesWsl (ctx.workspaceFiles), the GUI
-                             file tree and previews
 src/wsl.ts                   wsl.exe interop primitives (no DSH imports)
 ```
 

package/docs/CONFIGURATION.md

@@ -7,7 +7,7 @@ profile layer: `$DSH_HOME/profiles/<name>/cordis.patch.yml`. Start from
 reference for every value the plugin ships.
 
 Which rows a patch can reach depends on where they sit. `fs-routing`,
-`workspace-files-wsl`, `directory-picker-wsl`, `subprocess-wsl`, `wsl-shell-env`
+`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
@@ -22,44 +22,45 @@ has its own table at the end of this page.
 
 | Row | Key | Default | Meaning |
 |---|---|---|---|
-| `wsl-shell` | `distro` | `''` *(shipped)* | distro name; empty means WSL's default distro |
+| `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)* | 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). On in the shipped preset; set `false` for the per-command shape |
+| | `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) |
 | | `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)* | as above |
-| | `restrictToDistro` | `true` *(shipped)* | refuse a path in **another distro**'s share. `/mnt/c` is a directory *inside* the pinned distro, so it is not affected. The refusal carries `FS_OUTSIDE_DISTRO`; that is not a sandbox decision, so the file tools do not offer a wider permission for it. Set `false` to allow another distro's share |
+| `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)* | 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. Set `false` for the per-policy confined resident. The app-level `fs-routing` backend is not session-owned and keeps this off |
+| | `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)* | which distro the root-plane filesystem routes to; empty resolves WSL's default. **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 |
+| `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)* | refuse a path in another distro's share (`FS_OUTSIDE_DISTRO`) |
+| | `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 |
-| `workspace-files-wsl` | `maxBytes` | `2097152` *(shipped)* | byte cap on one page of a text read, and the default byte window of a byte read |
-| | `maxFileBytes` | `33554432` *(shipped)* | full-file byte cap for the byte reader |
-| | `maxLines` | `5000` *(shipped)* | line cap on one text read |
-| | `maxEntries` | `2000` *(shipped)* | directory entries listed per level before the listing is flagged truncated |
 | `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 |
+| `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
@@ -82,6 +83,21 @@ 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.
 
+The helper does the extraction and the common edits for you:
+
+```bash
+pnpm run preset -- --distro Ubuntu --session-sandbox false \
+  --out "$DSH_HOME/profiles/<name>/cordis.patch.yml"
+```
+
+`--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
@@ -163,9 +179,43 @@ is out of service and the call rides the one-shot `wsl.exe` path.
 
 ## Which distro is used
 
-`distro: ''` means the distro `wsl.exe` treats as default, so an installation with a
-single distro needs no configuration. Name one when you have several, or when the
-default is not the one you want sessions in.
+`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`):
+
+```bash
+pnpm run preset -- --sandbox true --mask-windows-drive true \
+  --out "$DSH_HOME/profiles/<name>/cordis.patch.yml"
+```
+
+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
 
@@ -194,8 +244,18 @@ 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 is advisory — it never
-installs anything and never changes the fail-closed semantics; drop 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.
 
@@ -217,8 +277,8 @@ When something refuses, the message names the row or the code:
 | 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 pinned distro |
-| a path in another distro is refused | `FS_OUTSIDE_DISTRO` | open a session in that distro, or set `restrictToDistro: false` |
+| 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
@@ -228,5 +288,5 @@ behind the fail-closed choices above are in [LIMITATIONS.md](LIMITATIONS.md).
 
 | Key | Default | Meaning |
 | --- | --- | --- |
-| `distro` | `''` | the distro the `DSH_WSL_*` facts describe |
+| `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 |

package/docs/LIMITATIONS.md

@@ -18,8 +18,10 @@ crosses the 9p share. What to know about the one substrate there is:
   Overwrites and edits keep the original bits. Run `chmod` (or ask the model to)
   when a new file must be executable.
 - **When the agent is out, file operations fail closed.** The distro stopped, or
-  the resident crashed past its one rebuild: `FS_IO_ERROR` naming the substrate,
-  with the recovery path in the message. There is no fallback I/O to degrade
+  the resident crashed through its revive budget: `FS_IO_ERROR` naming the
+  substrate, with the recovery path in the message. A single crash rides the
+  one rebuild (read-only ops only); a spent rebuild enters the bounded revival
+  (2/4/8 s), and three deaths make the state permanent with the restart remedy. There is no fallback I/O to degrade
   into — deliberately; the old failure message pointed at the share, and the
   share is what this plugin exists to keep the model off.
 - **The mutation guard survives to the write.** `createIfAbsent` publishes with
@@ -110,6 +112,37 @@ crosses the 9p share. What to know about the one substrate there is:
   kernel can actually report change.
 - `editText` reads the whole file into memory before writing it back.
 
+## The GUI workspace-files service
+
+- **The GUI file tree and previews use the shipped `workspace-files` row.** The
+  plugin deliberately does not replace it: its client half is the browser `file`
+  resource provider the Sidebar previews need, and a server-only replacement
+  drops it (the earlier `workspace-files-wsl` takeover did exactly that). The
+  shipped service reads WSL paths through the routed root filesystem
+  (`fs-routing`), so the file tree and previews still run inside the distro.
+
+- **That path costs extra agent round trips.** A listing, `stat` or page read
+  goes through `ctx.fs` before reaching the resident agent: roughly four to six
+  round trips instead of one, and a deep page read streams the preceding lines
+  through the pipe before cutting. Expect the GUI file tree and previews to be
+  slower than a direct agent call, especially on large files; the model's own
+  file operations are unaffected — they use the preset filesystem and the
+  resident agent directly. Measured 2026-10-19 with
+  [`test/probe/gui-preview.sh`](../test/probe/gui-preview.sh) (20 iterations on
+  this machine): the routed backend's `stat` p95 2.7 ms, `listDir` p95 5.1 ms,
+  and a 1 MiB `readByteRange` p95 **63.5 ms/MiB** — the service's own round
+  trips sit on top of those, and the 1 s/MiB budget has a wide margin. No
+  optimization is justified by these numbers; revisit only with a measured
+  regression.
+
+- **`fs-routing` is the seam.** The shipped service depends on the routed root
+  filesystem staying enabled and faithful to the `ctx.fs` contract (`resolve`,
+  `lstat`, `stat`, `listDir`, `streamText`, `readBytes`, `watch`, `contains`,
+  `processPath`). Disabling `fs-routing` restores the host 9p-backed root
+  filesystem, and the GUI file service then crosses 9p for WSL workspaces. The
+  shipped row's own caps (`maxBytes`, `maxFileBytes`, `maxLines`, `maxEntries`)
+  can be overridden on the `workspace-files` row.
+
 ## The sandbox
 
 - **The one-shot fallback has only the host deadline.** With `agent: false`, or
@@ -168,15 +201,47 @@ crosses the 9p share. What to know about the one substrate there is:
   a separate case and is now reported as an error naming that directory, because
   `wsl.exe` would otherwise run the command in `/` and exit 0.
 
+## Agent diagnostics
+
+- **The doctor's `agent.handshake` check probes a fresh resident, not the live
+  one.** It starts `agent/wsl-agent.sh` in the distro, reads its HELLO (pid,
+  protocol, script digest) and stops it, so it proves that the agent path can
+  start and that the file the distro reads is the shipped one. It cannot read
+  the running app resident's last error — there is no IPC channel from a plugin
+  script to the app process — so that error stays in the app log. In-process,
+  `WslAgent.status()` exposes state, pid, lastError, deaths and pending.
+- **`dsh-wsl-*.scope` counts are point-in-time.** The doctor lists and inspects
+  the user scopes once; a scope created or stopped a moment later is not
+  reflected. `--fix` runs the same sweep the session preflight uses.
+
+## Session-start advisories
+
+- **There is no session-UI notice seam in DSH 0.2.1.** When a distro session
+  opens, `wsl-preflight` checks `bubblewrap`, systemd as PID 1, the user
+  manager, `systemd-run` and Linger. A failure is advisory: it never installs
+  anything, never cancels the session and never changes the fail-closed
+  behavior of the first command. The finding goes to the host log
+  (`logger.warn`) and into the session's runtime context as a `wsl-preflight`
+  entry — model-visible on the next assembly — but the GUI today has no
+  toast/banner service a plugin can publish to. `pnpm run doctor` is the
+  deterministic human-facing check; the exact upstream ask is
+  [UPSTREAM-SESSION-NOTICE.md](UPSTREAM-SESSION-NOTICE.md).
+- **The runtime-context entry is a repeated snapshot, not a dismissible
+  notification.** It appears in every assembly until the environment is fixed;
+  it has no severity decoration and no dismiss control. Removing the
+  `wsl-preflight` row (or setting `sandbox: false` on it) silences the probe
+  entirely.
+
 ## Ports
 
 - **The port poller keeps the resident agent permanently warm.** The
   `DSH_WSL_PORTS` snapshot refreshes through the shared resident agent every
   `portsRefreshMs` (10 s by default, well inside the agent's idle timeout), so
-  while the app runs the agent never idles out: one `wsl.exe` and one
-  in-distro agent process stay resident per pinned distro even with no command
-  in flight. Raising `portsRefreshMs` past the agent's idle timeout restores
-  idle shutdown, at the cost of staler port facts.
+  while a distro's session is active the agent never idles out: one `wsl.exe`
+  and one in-distro agent process stay resident per active distro even with no
+  command in flight. The poller starts only for a distro a session actually
+  uses; raising `portsRefreshMs` past the agent's idle timeout restores idle
+  shutdown, at the cost of staler port facts.
 
 ## The directory picker
 

package/docs/MIGRATION.md

@@ -0,0 +1,98 @@
+# Configuration stability and migration
+
+What a release may change, how a breaking configuration change is announced and
+carried, and which gates a release must clear. The version table in
+[RELEASING.md](RELEASING.md#1-decide-the-version) is the source for the bump; this
+page is the contract those bumps follow.
+
+## The freeze below 1.0
+
+The package is below `1.0.0`, so the on-disk profile format and the peer pins may
+still move in a **minor**. Within that freedom:
+
+- **Adding a configuration key is a minor.** The key must have a schema default
+  that preserves the previous behavior; a key that changes behavior by existing
+  is a major-shaped change and waits.
+- **Removing or renaming a key is a major** *or* a minor with a boot-time refusal
+  that names the migration (see below). Silent acceptance of a retired key is
+  never allowed: it is the failure the `preset-wsl` trap and the `substrate`
+  refusal exist to prevent.
+- **Changing a key's meaning is a minor with a migration note**, because a profile
+  written for the old meaning keeps booting. The note must say what changed, how
+  to keep the old posture, and where the behavior differs.
+- **Peer pins are exact.** A new upstream peer line is tested by the
+  [peer canary](../.github/workflows/peer-canary.yml) and lands as a minor with
+  the delta in the release note (or as a patch if the plugin code needs no
+  change).
+- **Tool names and error codes are API.** `FS_OUTSIDE_DISTRO`,
+  `SANDBOX_UNAVAILABLE`, `FS_STALE_VERSION` and the diagnostic scripts
+  (`doctor`, `diagnose`, `preset`, `bootstrap`) keep their names and contracts;
+  a rename follows the deprecation path below.
+
+## Deprecating a configuration value
+
+1. **Announce it in the release that introduces the deprecation**: a CHANGELOG
+   entry and the row in [CONFIGURATION.md](CONFIGURATION.md). The old value keeps
+   working for that release.
+2. **Keep the old spelling for one minor** when it is unambiguous. When keeping
+   it would silently change behavior, refuse it at boot instead and print the
+   migration — the `substrate: "share"` case: the value is refused with the
+   message that says to delete the line, because serving the share is exactly
+   what the plugin must not do.
+3. **Remove it in the next minor** with another CHANGELOG entry. The release note
+   names the version where the refusal appeared.
+
+### Case study: `distro: ''` (0.12.0)
+
+`distro: ''` used to mean "WSL's default distro". 0.12.0 made the empty value
+mean **auto**: follow the request workdir's UNC distro. A profile that relied on
+the old meaning keeps booting, but now behaves differently. The migration:
+
+```yaml
+# keep the old posture: every command in WSL's default distro
+- id: preset-wsl
+  config:
+    plugins:
+      # … full block; set on both rows …
+      - id: wsl-shell
+        config:
+          distro: default
+      - id: wsl-fs
+        config:
+          distro: default
+```
+
+`pnpm run preset -- --distro default --out …` writes that block. The CHANGELOG
+entry for 0.12.0 states the change; this page is the durable copy. `doctor`
+reports the effective distro mode in its host/distro rows, and `--dump-config`
+shows the composed value.
+
+## Gates a release must clear
+
+| Gate | How | Runs where |
+|---|---|---|
+| Config docs and CHANGELOG current | review the diff; `lint:links` covers cross-references | CI |
+| `pnpm test` | style, links, syntax, build freshness, tsc, 40 unit files | CI (Node 22/24, Ubuntu + Windows) |
+| `pnpm run test:coverage` | lines 85 / branches 84 / functions 70 | CI (Node 24, Ubuntu) |
+| Peer line tested | `peer-canary` workflow resolves `next` and runs the scratch upgrade | CI schedule/manual |
+| Packed install/upgrade/uninstall | `pnpm run e2e:install` (temp `DSH_HOME`, 0.11.0 → current, marker) | manual, this machine (10/10 on 2026-10-19) |
+| Real-machine probe suite | `test/probe/run-all-when-closed.sh` (needs the app closed) | manual; **not run in this environment** since the last batch's targeted probes |
+| Clean Win11 + Ubuntu first run ≤ 5 min | a clean machine, a stopwatch | **not run** (the project's machine is already configured) |
+| aarch64 executed | the native suite on aarch64 WSL or qemu | **not run** (CI builds the binary only) |
+| No open P0 bug for 30 days | issue tracker | time-based; cannot be asserted from a checkout |
+
+The last four rows are deliberately marked as unrun rather than assumed: a
+release note must not claim them, and [ROADMAP-1.0.md](ROADMAP-1.0.md#wsl-304--10-readiness)
+tracks them. A release that skips the manual rows still ships through the tag
+workflow, but its notes say which gates were executed.
+
+## Verifying a migration locally
+
+```bash
+pnpm run preset -- --distro default --check <profile>/cordis.patch.yml  # no nested-row trap
+pnpm run doctor -- --json                                               # effective environment facts
+dsh --profile <name> --dump-config                                      # composed rows
+```
+
+A profile that fails to boot after a migration should name the remedy in the
+error; if it does not, that is a bug — report it with the `doctor --json` output.

package/docs/PARITY.md

@@ -83,7 +83,7 @@ shaped a phase of the plan.
 | --- | --- | --- | --- |
 | 0 | landed | This document; contract audit above | baseline recorded |
 | 1 | landed | `lib/agent.js` (with `lib/agent-protocol.js`, `lib/agent-shared.js`) and `agent/wsl-agent.sh`: resident process speaking a line protocol (pipe-separated fields, single-line base64 payloads), version + script-digest handshake, lazy start, idle shutdown, crash-rebuild-once, one-shot `wsl.exe` fallback for execution | resident server |
-| 2 | landed | real `watch()` shipped (in-distro mtime poll, `lib/watcher.js`); the native-ext4 migration of the remaining fs operations finished with the share's retirement — every model-facing file operation now runs on the agent, and the share-era workarounds went with it | native file semantics, change invalidation — watch + publication done (a poll, not inotify; blind spots in LIMITATIONS and CONFIGURATION) |
+| 2 | landed | real `watch()` shipped: inotify for an unbounded directory since 0.10.0 (polling fallback for a file target, a bounded depth or a distro without `inotify-tools`); the native-ext4 migration of the remaining fs operations finished with the share's retirement — every model-facing file operation now runs on the agent, and the share-era workarounds went with it | native file semantics, change invalidation — inotify primary, polling fallback; blind spots in LIMITATIONS and CONFIGURATION |
 | 3 | landed (deviation: no streaming, no spill files) | `WslShellExecutor` exec via agent; in-distro TERM→KILL; handle shape preserved | native exec latency |
 | 4 | landed | `npm run bootstrap`, family-aware install command, `SANDBOX_UNAVAILABLE` names it; the handshake ships the protocol version plus the script digest | open-and-it-works |
 | 5 | landed | per-session routing by workspace coordinates (`terminal-route.js`, `hostSessions`); idle distro terminals are reclaimed by a distro-side scan (`lib/terminal-activity.js`) — the host-side shell-activity integration still does not arm for `wsl.exe`, which is why the observation is a scan | terminal per window/session |

package/docs/PERFORMANCE.md

@@ -0,0 +1,60 @@
+# Performance: ext4 agent vs the 9p share
+
+The plugin's reason to exist is not only correctness: a WSL workspace served
+through the Windows 9p share is measurably slower than the same files read on
+the distro's ext4 through the resident agent. This page records the measurements
+and how to reproduce them; it does not extrapolate beyond them.
+
+## The two substrates
+
+| | 9p share (`\\wsl.localhost\...`) | This plugin |
+|---|---|---|
+| File I/O | host stack crosses the VM boundary per operation | resident agent serves reads/writes on ext4 inside the distro |
+| Change feed | polling the share | inotify inside the distro (`watchMaxDepth: 0`) |
+| Commands | host process | distro login shell through `wsl.exe` |
+
+The plugin's root filesystem routes every WSL path to the distro backend
+(`fs-routing`), so the GUI file tree, previews and the model's file tools all
+use the agent path. The design and its trade-offs are in
+[root-fs-routing.md](root-fs-routing.md); the known limits are in
+[LIMITATIONS.md](LIMITATIONS.md).
+
+## Measured numbers
+
+Machine: Windows 11 + WSL 2, Ubuntu, x86_64, the project's development machine.
+Absolute numbers are machine-dependent; the ratio and the budgets are the point.
+
+| Scenario | 9p share | Agent (ext4) | Source |
+|---|---|---|---|
+| 16 concurrent shared reads | 342–614 ms (queue up to 583 ms) | **2.4–4.1 ms** after A7, first start ~70 ms once | [ADR 0002 fs queue](adr/0002-native-agent.md#fs-queue-measurement-a6-2026-10-18) |
+| Single FS op (host round trip) | — | p95 ≈ 22 ms | [ROADMAP-1.0.md](ROADMAP-1.0.md#7-metrics) |
+| GUI-preview backend: `stat` | — | p95 **2.7 ms** | `pnpm run probe:gui-preview` (20 iterations, 2026-10-19) |
+| GUI-preview backend: listing | — | p95 **5.1 ms** | same |
+| GUI-preview backend: 1 MiB page | — | p95 **63.5 ms/MiB** | same |
+
+The GUI-preview number covers the routed backend operations a preview pays.
+The shipped `workspace-files` service adds its own calls on top; that service
+shape stays qualitative in [LIMITATIONS.md](LIMITATIONS.md). The 1 s/MiB budget
+has a wide margin, so no further optimization (the deferred v6 FS concurrency)
+is justified by these measurements.
+
+## Reproduce
+
+Inside the distro, with the checkout:
+
+```bash
+pnpm run probe:gui-preview        # stat / listDir / 1 MiB page read, p50/p95
+node test/probe/fs-queue.mjs      # the agent queue, sequential vs concurrent, with per-op latency
+```
+
+Both need a working distro and Node; neither boots the harness. The probes print
+the raw samples' p50/p95/max and fail when a budget is exceeded, so a regression
+is a red probe rather than a claim in prose.
+
+## What is not measured
+
+- End-to-end GUI paint time (the browser and the service's own work are out of
+  scope for these probes).
+- 9p numbers for large files or many small files beyond the A6 sample above;
+  the A6 measurement is the recorded baseline, not a re-runnable benchmark.
+- aarch64; the binary is built but not executed in CI.