dsh-plugin-wsl-env 0.8.0 → 0.10.0

package/cordis.patch.yml

@@ -162,6 +162,15 @@
     - id: auto-preset
       name: 'dsh-plugin-wsl-env/auto-preset'
 
+    # Session-start sandbox preflight: when a distro session opens, run the
+    # providers' own bwrap usability probe (shared cache, so the first confined
+    # command pays nothing) and surface a missing or broken bubblewrap as a
+    # warning with the full remedy — instead of the first command's fail-closed
+    # error being the discovery moment. Advisory only: it never installs and
+    # never changes the providers' fail-closed semantics.
+    - id: wsl-preflight
+      name: 'dsh-plugin-wsl-env/preflight'
+
 - insert:
     # ═════════════════════════════════════════════════════════════════════════════
     # preset-wsl — the WSL environment, scoped to agents that select this preset.
@@ -178,9 +187,20 @@
     # Because a preset's plugins mount under a REGISTRY-owned scope (not this row's
     # ctx), the realm has to be declared here, inside config.plugins.
     #
-    # Generated from the shipped standard preset by build-preset-wsl.mjs so the
-    # embedded plan-mode section and every nested group survive byte-for-byte.
-    # Re-run it after an app update that changes the preset.
+    # Generated from the shipped standard preset so the embedded plan-mode
+    # section and every nested group survive byte-for-byte: this copy is
+    # `packages/bundle/web-app/presets/standard.patch.yml` of the
+    # `dsh-v0.2.1-rc.2` source tree, changed in exactly three ways —
+    #   1. every shipped row mounts inside `wsl-env`, so the preset's tools see
+    #      the distro's shell and fs (the realm is declared on the group);
+    #   2. `tool-bash` is enabled and `tool-pwsh` disabled outright, where the
+    #      shipped copy derives the choice from `process.platform`;
+    #   3. the identity: row `preset-wsl`, preset `wsl`, `order: 2`.
+    # Regenerate it when an app update changes the preset: take
+    # `packages/bundle/web-app/presets/standard.patch.yml` from the harness tree
+    # the peer pins track and run `node scripts/build-preset-wsl.mjs <that
+    # file>`, then replace this row to the end of the file. The script applies
+    # changes 1 and 2 itself, so only change 3 is yours.
     # ═════════════════════════════════════════════════════════════════════════════
     - id: preset-wsl
       name: '@deepseek-ai/dsh-agent-preset'
@@ -200,12 +220,15 @@
               # asked of the distro itself. Pin a directory here to override it —
               # a value that is right on one machine is wrong on every other.
               #
-              # Each command is confined inside the distro by bubblewrap, in the
-              # policy's mode, and the file tools are fenced by the same policy.
-              # Install bubblewrap there (`sudo apt install bubblewrap`); without
-              # it the providers fail closed rather than run unconfined. Add
-              # `sandbox: false` to either provider for the old, unconfined
-              # posture.
+              # Commands run in one persistent systemd user scope per session
+              # (ADR 0001): a background dev server survives the command that
+              # started it, `/tmp` is the distro's real `/tmp`, and `ps` sees the
+              # session. This needs systemd as PID 1 (`[boot] systemd=true` in
+              # /etc/wsl.conf) and a lingering user manager (`loginctl
+              # enable-linger <user>`); the preflight refuses with those remedies
+              # when one is missing. Set `sessionSandbox: false` for the old
+              # per-command shape. Bubblewrap is still required for the mount
+              # profile; without it the providers fail closed.
               - id: wsl-shell
                 name: 'dsh-plugin-wsl-env'
                 config:
@@ -213,6 +236,13 @@
                   loginShell: true
                   timeoutMs: 120000
                   maxTimeoutMs: 600000
+                  sessionSandbox: true
+                  # auto: the native session-runtime agent when a verified
+                  # source is available (packaged binary, or the
+                  # DSH_WSL_AGENT_NATIVE development override); otherwise the
+                  # shipped shell agent. native fails the first command instead
+                  # of falling back; shell forces the shell agent.
+                  agentBackend: auto
               - id: wsl-fs
                 name: 'dsh-plugin-wsl-env/fs'
                 config:
@@ -225,15 +255,19 @@
                   # share: the opt-out — the Windows-side host fs stack over
                   # the 9p share.
                   substrate: agent
+                  # Confined writes ride the session runtime (ADR 0001), so they
+                  # share the command's real /tmp and workspace mounts.
+                  sessionSandbox: true
               - id: persona
                 name: '@deepseek-ai/dsh-persona'
                 config:
-                  suffix: Your working directory is {{cwd}}.
                   prefix: You are a coding agent powered by the {{model}} model.
               - id: agent-instructions
                 name: '@deepseek-ai/dsh-agent-instructions'
                 config:
                   maxBytes: 65536
+              - id: time-context
+                name: '@deepseek-ai/dsh-time-context'
               - id: tool-bash
                 name: '@deepseek-ai/dsh-tool-bash'
                 disabled: false
@@ -248,6 +282,8 @@
                   sampleOverCapGlobResults: false
               - id: tool-jobs
                 name: '@deepseek-ai/dsh-tool-jobs'
+              - id: tool-schedule
+                name: '@deepseek-ai/dsh-tool-schedule'
               - id: skill-filesystem
                 name: '@deepseek-ai/dsh-skill-filesystem'
               - id: tool-skill
@@ -266,7 +302,7 @@
                     name: '@deepseek-ai/dsh-plan-mode'
                     config:
                       section: |
-                        You are in plan mode. Stay in plan mode until exit_plan_mode succeeds or the user switches the session mode. Imperative language to implement changes means plan the implementation, not execute it. A user's conversational agreement — including an answer confirming something you asked — approves nothing and does not end plan mode; fold the confirmed decision into the plan and submit it through exit_plan_mode.
+                        You are in plan mode. Stay in plan mode until the user approves your plan through exit_plan_mode or switches the session mode. Imperative language to implement changes means plan the implementation, not execute it. A user's conversational agreement — including an answer confirming something you asked — approves nothing and does not end plan mode; fold the confirmed decision into the plan and submit it through exit_plan_mode.
 
                         Explore first. Use non-mutating reads, searches, static analysis, and checks to ground the plan in the actual repository. Do not edit or write files, change configuration, run formatters or code generation that rewrites tracked files, commit, or otherwise carry out the plan. Prefer existing functions and patterns over new machinery.
 
@@ -310,41 +346,17 @@
                       provider: spawn
                       toolName: subagent
                       modelSelectionSettings: true
-                      backgroundMode: continuable
                   - id: tool-subagent-fork
                     name: '@deepseek-ai/dsh-tool-subagent'
                     config:
                       provider: fork
                       toolName: subagent_fork
-                      backgroundMode: continuable
-                  - id: tool-subagent-codex
-                    name: '@deepseek-ai/dsh-tool-subagent'
-                    disabled: true
-                    config:
-                      provider: codex
-                      toolName: subagent_codex
-                      backgroundMode: one-shot
-                      maxDepth: provider-managed
-                  - id: tool-subagent-claude-code
-                    name: '@deepseek-ai/dsh-tool-subagent'
-                    disabled: true
-                    config:
-                      provider: claude-code
-                      toolName: subagent_claude_code
-                      backgroundMode: one-shot
-                      maxDepth: provider-managed
                   - id: workflow-ptc
                     name: '@deepseek-ai/dsh-workflow-ptc'
                     config:
                       provider: spawn
                   - id: tool-workflow
                     name: '@deepseek-ai/dsh-tool-workflow'
-                  - id: tool-ralph
-                    name: '@deepseek-ai/dsh-tool-ralph'
-                    disabled: true
-                    config:
-                      subagentProvider: spawn
-                      maxRounds: 64
               - id: tool-ask-user
                 name: '@deepseek-ai/dsh-tool-ask-user'
               - id: tool-todo
@@ -361,3 +373,6 @@
               - id: tool-plugin-manager
                 name: '@deepseek-ai/dsh-plugin-manager/tools'
                 disabled: true
+              - id: tool-plugin-market
+                name: '@deepseek-ai/dsh-plugin-market/tools'
+                disabled: true

package/docs/ARCHITECTURE.md

@@ -11,28 +11,56 @@ DSH exposes its capabilities as services. The model-facing tools (`bash`, `read`
 `write`, `edit`, `glob`, `grep`) consume those services. They never touch a
 filesystem or a shell directly.
 
-This plugin supplies WSL-backed implementations of three of them, plus three
-smaller integrations.
+This plugin supplies WSL-backed implementations of three of them, takes over two
+root-plane services, and adds three smaller integrations.
 
 ## The three service providers
 
 | Service | Class | File | What it does |
 |---|---|---|---|
-| `ctx.shell` | `WslShellExecutor` | [`lib/index.js`](../lib/index.js) | Runs each command as `wsl.exe -d <distro> --cd <linux dir> --exec <login shell> -lc <cmd>`, wrapped in a distro-side `bwrap` sandbox. |
+| `ctx.shell` | `WslShellExecutor` | [`lib/index.js`](../lib/index.js) | Runs each command in the distro's login shell over the resident in-distro agent (the default), wrapped in a distro-side `bwrap` sandbox; while the agent is out, or with `agent: false`, the same command falls back to one `wsl.exe -d <distro> --cd <linux dir> --exec <login shell> -lc <cmd>` process. |
 | `ctx.fs` | `WslFileSystem` | [`lib/index.js`](../lib/index.js) | Serves the file tools from real distro files on the resident in-distro agent, on ext4 — the former Windows-side share substrate is retired (see below). |
-| `ctx.subprocess` | `WslSubprocessRuntime` | [`lib/subprocess.js`](../lib/subprocess.js) | Opens the GUI terminal inside the distro, in the session workspace, and rewrites the file-search spawn into the distro's own rg (see below). |
+| `ctx.subprocess` | `WslSubprocessRuntime` | [`lib/subprocess.js`](../lib/subprocess.js) | Opens the GUI terminal inside the distro, in the session workspace, and rewrites the file-search and git-snapshot spawns into the distro (see below). |
 
 `WslShellExecutor` extends the shipped `LocalBashExecutor`, and `WslFileSystem`
 extends the shipped `LocalFileSystem`. Only the parts that need a distro are
 overridden.
 
+## The two root-plane takeovers
+
+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:
+
+| 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
+`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
+all. [`cordis.patch.yml`](../cordis.patch.yml) carries the full row list, and
+`test/composition.test.mjs` runs the file through the real patch algorithm to
+keep the shape honest.
+
+One further module ships built but deliberately unwired:
+[`lib/file-reference-wsl.js`](../lib/file-reference-wsl.js), the distro-side
+traversal strategy for `@` completion. It is built and tested, but **not** wired
+into `cordis.patch.yml` — the seam it consumes is an upstream proposal
+([`upstream/rfc-wsl-workspaces.md`](upstream/rfc-wsl-workspaces.md)), and
+reaching the funnels without it would mean subclassing past module-internal
+functions.
+
 ## The three smaller integrations
 
 | Subpath | Class or name | File | What it does |
 |---|---|---|---|
 | `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`, and `DSH_WSL_HOME` to the managed `DSH_*` namespace. |
+| `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. |
 
 Three modules support them and import no DSH package.
 [`lib/paths.js`](../lib/paths.js) translates paths.
@@ -50,7 +78,9 @@ The environment is per session, not per process:
 | Row | Mounted | Why there |
 |---|---|---|
 | `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 | because no session identity reaches the terminal controller, see below |
+| `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 |
+| `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 |
 
 The preset mount requires the isolate realms. Without them the registry rejects the
@@ -71,8 +101,15 @@ does not use it.
 
 So the layer disables the shipped `subprocess` row and inserts
 `dsh-plugin-wsl-env/subprocess` in its place at the app level. The subclass
-overrides `spawnTerminal` only. Ordinary `spawn()`, the host ripgrep search, the
-pwsh executor, and the LSP host reach the shipped implementation unchanged.
+overrides two methods: `spawnTerminal` rewrites a `wsl.exe` launch into
+`wsl.exe -d <distro> --cd <linux dir>`, and `spawn()` rewrites two kinds of
+launches into the distro — the file-search tool's packaged ripgrep (agent-first,
+with the one-shot `wsl.exe --exec` handle as the fallback when the agent is out)
+and git snapshot commands. Both spawn decisions are pure coordinate functions
+(`lib/search-route.js`, `lib/git-route.js`); every other `spawn()` — including
+the one-shot fallback's own `wsl.exe -lc <command>` (the default agent path
+carries the command over the resident instead of spawning) — reaches the shipped
+implementation untouched, as do the pwsh executor and the LSP host.
 
 The terminal's execution world follows the session (`hostSessions`, default on):
 a WSL-folder session runs the distro shell, a Windows-folder session runs
@@ -124,9 +161,11 @@ profile carrying the value is refused at boot, and no file tool crosses the
   refuses confined mutations with the bootstrap command, the same closed
   failure the command path has.
 
-Writes fence with the same host-side policy check (`checkedTarget`) the
-command path uses, and the substrate does not change what `sandboxMode`
-reports. The wire protocol the substrate speaks is documented in
+Writes fence with the same host-side policy the command path's sandbox
+describes — `WslFileSystem.checkedTarget`, over the same writable list; the
+command path itself is confined by the distro-side profile and never calls it —
+and the substrate does not change what `sandboxMode` reports. The wire protocol
+the substrate speaks is documented in
 [`agent/wsl-agent.sh`](../agent/wsl-agent.sh); the orchestration layers are
 [`lib/fsio-agent.js`](../lib/fsio-agent.js) (fsio's mechanics over the FS
 frames), [`lib/fs-substrate.js`](../lib/fs-substrate.js) (the provider-shaped
@@ -148,24 +187,39 @@ sandbox.
 
 ### What the plugin does instead
 
-The plugin builds a `bubblewrap` profile on the Windows side and passes it to
-`wsl.exe --exec`. The confinement is created inside the distro:
+The plugin builds a `bubblewrap` profile on the Windows side and hands the
+resulting argv to the distro — over the resident agent by default, or to
+`wsl.exe --exec` on the one-shot fallback. The confinement is created inside the
+distro, and the argv is the same either way:
 
 ```text
 wsl.exe -d <distro> --cd <linux dir> --exec bwrap \
   --ro-bind / / --dev /dev --unshare-pid --proc /proc --die-with-parent \
-  [--tmpfs /tmp --bind <workspace> <workspace>]  --  <shell> -lc <cmd>
+  [--tmpfs /tmp --bind <workspace> <workspace>]  [--tmpfs /mnt]  --  <shell> -lc <cmd>
 ```
 
+By default the profile wraps the session's resident agent ONCE, under
+`systemd-run --user --scope`, and the command argv is the shell line itself:
+`bwrap … --die-with-parent --bind /tmp /tmp --bind <workspace> <workspace> -- sh agent.sh`.
+There is no `--unshare-pid` and no per-command tmpfs, so background processes
+survive, `/tmp` is the distro's real `/tmp`, and `ps` sees the session. The
+per-command argv above is what `sessionSandbox: false` (and the one-shot
+fallback) still runs.
+
 These are the same arguments DSH's Linux runner uses (`dsh-sandbox-local`), so the
 behaviour and the error messages match a Linux host. The function
 `bwrapProfileArgs` in [`lib/bwrap.js`](../lib/bwrap.js) builds them — the
-peer-free builder every confinement site composes from.
+peer-free builder every confinement site composes from. The trailing
+`[--tmpfs /mnt]` is the `maskWindowsDrive` option: when it is on, the Windows
+drive is shadowed by an empty tmpfs in every confined profile, so its files
+cannot be read or exfiltrated and its executables cannot be launched through
+interop. The option is off by default; [CONFIGURATION.md](CONFIGURATION.md) lists
+the row keys, and `lib/sandbox-core.js` states its honest ceiling.
 
 | Mode | What a command inside the distro can do |
 |---|---|
 | `read-only` | read the whole distro; a fresh `/dev` is mounted writable, so `/dev/null` and `/dev/shm` work, and nothing else does |
-| `workspace-write` | the above, plus the session workspace is writable and `/tmp` is a temporary mount |
+| `workspace-write` | the above, plus the session workspace is writable; `/tmp` is the distro's real `/tmp` in the session runtime, and a fresh tmpfs in the per-command profile (`sessionSandbox: false`) |
 | `danger-full-access` | no sandbox; used for an approved wider-permission request |
 
 `WslFileSystem` checks writes against the same policy and the same writable list,
@@ -185,6 +239,18 @@ selector read that value.
 distro can still run a Windows program through WSL interop, for example
 `/mnt/c/.../*.exe`. Bubblewrap does not govern that process.
 
+`maskWindowsDrive` is the one mitigation the profile can offer, and it is a
+narrowing rather than a closure: it takes the drive's data and its executables
+off the table, but `binfmt` interop dispatches on file *content*, so a command
+that can write the workspace can still write a PE there and have it launched as
+a Windows process. Either way the provider reports `partial` — the complete
+closure is distro-level (`[interop] enabled=false` in `wsl.conf`). The mask is
+reported on the result's sandbox fact as `windowsDrive: "masked"` (or
+`"visible"`), but that is this plugin's own extra field: the pinned harness's
+sandbox type and its model-facing notes carry `mode`, `denied`, `enforcement` and
+`runnerFailed` only, so the field reaches the result and the tests, not the
+model.
+
 `pnpm run probe:sandbox` demonstrates the boundary on your machine and records it as
 `INFO`.
 
@@ -212,18 +278,37 @@ and `sandboxMode` returns `undefined`.
 ## Error codes
 
 The plugin raises `FsError`s with a code the tool layer maps, and `wsl.exe`'s own
-failures are named as well. A model sees the code; a reader asking what refused them
-finds it here.
+failures are named as well. Every `FsError` code the plugin itself raises appears
+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.
 
 | 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` | the file-effect policy refused the write: `read-only`, or a target outside the writable roots | a wider permission for that one call, or a session workspace that contains the target |
+| `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_NOT_OBSERVED` | `WslFileSystem.assertGuard` | 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` | `WslFileSystem.assertGuard` | 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` | `WslFileSystem.watch` | the watch target is not a path inside the pinned distro, so there is nothing the in-distro poll loop can observe | watch a distro path; the watch itself runs where the files live (`lib/watcher.js`) |
-| `FS_NOT_FOUND` | the host filesystem stack | the path does not exist — the ordinary answer, passed through | — |
+| `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_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 |
+| `FS_NOT_TEXT` | `lib/fsio-agent.js`, `lib/fsio-text.js` | the content is not UTF-8 text: a NUL sample (binary) or a decode failure | not a policy refusal — read text, or use a command for binary content |
+| `FS_TOO_LARGE` | `lib/fsio-agent.js` | the content exceeds the byte cap the caller's operation carries | read a byte range (`WslFileSystem.readByteRange`) instead of the whole file, or raise the cap |
+| `FS_ABORTED` | `lib/fsio-agent.js`, `lib/fsio-text.js` | the caller's signal was aborted before or during the operation | not a refusal — the caller cancelled; a fresh call clears it |
+| `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.
 
 Two failures come from `wsl.exe` itself rather than from a code of ours, and both used
 to be invisible:
@@ -258,15 +343,35 @@ step with the checkout, and `pnpm run sync:windows` runs that script.
 |---|---|---|
 | Style and packaging checks | [`test/style.mjs`](../test/style.mjs) | no |
 | Syntax pass | [`test/syntax.mjs`](../test/syntax.mjs) | no |
+| Build consistency | [`test/build-freshness.mjs`](../test/build-freshness.mjs) | no; it re-runs the real build and byte-compares the committed `lib/`, so it also catches an orphan there |
+| 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 |
-| Host probes | [`test/probe/mode.sh`](../test/probe/mode.sh) | Windows Node, no harness |
+| 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 |
 
-The unit tests import only Node builtins, so they run on any platform. CI runs them
-on Linux and Windows, on Node 20, 22 and 24. The harness probes are a manual step,
-because a hosted runner has no WSL distro and no profile to mount.
+`pnpm test` runs the first five rows in order: `lint:style`, `test:syntax`,
+`lint:build`, `lint:types`, `test:unit`.
+[`test/probe/run-all-when-closed.sh`](../test/probe/run-all-when-closed.sh)
+waits for the app to exit and then runs the whole real-machine suite once —
+`--include-fs` prepends `run.sh`.
+
+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
+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
+`pnpm test` on Linux and Windows, on Node 22 and 24, and `pnpm run test:coverage` on
+Node 24 only — the threshold flags need Node 22.8. Node 20 is absent on purpose:
+`engines` requires `^22.19.0 || >=24.0.0`, the harness host's own floor. The harness
+probes are a manual step, because a hosted runner has no WSL distro and no profile to
+mount.
 
 The probe scripts share [`test/probe/env.sh`](../test/probe/env.sh), which derives
 the Windows user, the distro name and the UNC spelling of the checkout from the
@@ -276,33 +381,74 @@ placeholders that the scripts substitute into generated copies.
 
 ## File layout
 
+`lib/` is generated output: every module's source is `src/<name>.ts`, and
+`pnpm run build` emits `lib/<name>.js` plus its `lib/<name>.d.ts`. Never edit
+`lib/` by hand — `lint:build` fails when the committed bytes drift from a real
+build, and it also fails on an orphan in either direction.
+
+```text
+src/<name>.ts         the sources — edit THESE; each builds to lib/<name>.{js,d.ts}
+agent/wsl-agent.sh    the resident in-distro agent (POSIX sh, coreutils only)
+cordis.patch.yml      the bundle configuration layer (dsh.bundle), commented
+examples/             one machine-local profile layer, for comparison
+locale/               the Plugins-page display metadata (title/description)
+scripts/              the build (build.mjs), the release helpers
+                      (check-release-tag.mjs, changelog-section.mjs), and the
+                      distro-side bootstrap installer (bootstrap.sh)
+test/                 unit tests, the style/build/type gates, and the probes
+docs/                 this file, the configuration and limitation references,
+                      the release checklist, and the archived designs
+```
+
+The modules, in alphabetical order:
+
 ```text
-lib/paths.js        pure conversion between the three path formats
-lib/wsl.js          wsl.exe interop primitives (no DSH imports)
-lib/listing.js      pure directory listing and breadcrumb helpers (no DSH imports)
-lib/index.js        WslShellExecutor (ctx.shell) and WslFileSystem (ctx.fs)
-lib/sandbox.js      the distro-side bwrap confinement shared by both providers
-lib/bwrap.js        the bwrap command line both confinement sites assemble
-                    (no imports, so a bare checkout can assert it)
-lib/fsio-text.js    the peer's pure text mechanics, replicated pending the
-                    upstream fsio export (see UPSTREAM-FSIO-EXPORT.md)
-lib/fsio-agent.js   fsio's mechanics over the agent's FS frames
-lib/fs-substrate.js the agent substrate's provider-shaped operations
-lib/agent.js        the resident in-distro agent's host side
-lib/agent-confined.js the confined residents' factory (one per policy)
-lib/agent-protocol.js the wire protocol codecs (pure)
-agent/wsl-agent.sh  the resident in-distro agent (POSIX sh, coreutils only)
-lib/picker.js       WslDirectoryPicker (ctx.directoryPicker)
-lib/subprocess.js   WslSubprocessRuntime (ctx.subprocess), the terminal window
-lib/auto-preset.js  per-session environment selection
-lib/shell-env.js    registers the DSH_WSL_* environment variables
-lib/{shell,fs}.js   one-line subpath entry points
-cordis.patch.yml    the bundle configuration layer (dsh.bundle), commented
-examples/           one machine-local profile layer, for comparison
-scripts/            release helpers, used by the release workflow
-test/               unit tests, the style gate, and the behaviour probes
-docs/               this file, the configuration and limitation references, the
-                    release checklist, and the archived designs
+src/agent-confined.ts        the confined residents' factory (one per policy)
+src/agent-errors.ts          the error a resident outage rejects with
+src/agent-exec.ts            the agent-backed shell execution handle
+src/agent-protocol.ts        the wire protocol codecs (pure)
+src/agent-shared.ts          the per-distro resident shared by every provider
+src/agent.ts                 the resident in-distro agent's host side
+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/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
+src/fs-decisions.ts          the filesystem provider's policy decisions (pure,
+                             unit-testable in a bare checkout)
+src/fs-routing.ts            WslRoutingFileSystem, the root-plane ctx.fs
+src/fs-substrate.ts          the agent substrate's provider-shaped operations
+src/fsio-agent.ts            fsio's mechanics over the agent's FS frames
+src/fsio-text.ts             the peer's pure text mechanics, replicated pending
+                             the upstream fsio export (UPSTREAM-FSIO-EXPORT.md)
+src/git-route.ts             which git spawns belong inside the distro (pure)
+src/index.ts                 WslShellExecutor (ctx.shell) and WslFileSystem (ctx.fs)
+src/listing.ts               pure directory listing and breadcrumb helpers
+src/paths.ts                 pure conversion between the three path formats
+src/picker.ts                WslDirectoryPicker (ctx.directoryPicker)
+src/ports.ts                 the listening-port snapshot behind DSH_WSL_PORTS
+src/preset-choice.ts         whether a new session adopts the WSL preset (pure)
+src/probe-cache.ts           which probe verdicts may be remembered (pure)
+src/sandbox.ts               the distro-side bwrap confinement shared by both
+                             providers, bound to the peer's failure type
+src/sandbox-core.ts          the probe-and-confinement core, free of DSH peers
+src/search-exec.ts           the agent-backed execution handle for a search
+src/search-route.ts          which execution world a search spawn belongs to (pure)
+src/shell.ts                 the ctx.shell subpath entry point
+src/shell-env.ts             registers the DSH_WSL_* environment variables
+src/subprocess.ts            WslSubprocessRuntime (ctx.subprocess), the GUI
+                             terminal window
+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.json` publishes a subset of this tree: the `files` list is the contract, and
@@ -318,6 +464,8 @@ docs/               this file, the configuration and limitation references, the
 - [`archive/engineering-record.zh.md`](archive/engineering-record.zh.md) is the
   full engineering record, in Chinese: measured contracts, debugging rounds, and
   the conclusions as they stood then.
-- [`archive/README.md`](archive/README.md) indexes the archived material in
-  Chinese, and [`archive/README.en.md`](archive/README.en.md) is the English index.
+- [`archive/README.md`](archive/README.md) and
+  [`archive/README.en.md`](archive/README.en.md) are two English indexes of the
+  same three archived files, the second so a reader who does not read Chinese can
+  still tell what is there; the records themselves are Chinese.
 - [`README.md`](../README.md) is the only statement of current state.