dsh-plugin-wsl-env 0.2.0 → 0.3.0

package/docs/ARCHITECTURE.md

@@ -19,7 +19,7 @@ smaller integrations.
 | 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.fs` | `WslFileSystem` | [`lib/index.js`](../lib/index.js) | Maps Linux paths onto the distro's UNC share, so the host filesystem stack and the packaged ripgrep work on real distro files. |
+| `ctx.fs` | `WslFileSystem` | [`lib/index.js`](../lib/index.js) | Serves the file tools from real distro files, on one of two I/O substrates (see below): the Windows-side host stack over the distro's UNC share (default), or the resident in-distro agent on ext4. |
 | `ctx.subprocess` | `WslSubprocessRuntime` | [`lib/subprocess.js`](../lib/subprocess.js) | Opens the GUI terminal inside the distro, in the session workspace. |
 
 `WslShellExecutor` extends the shipped `LocalBashExecutor`, and `WslFileSystem`
@@ -92,6 +92,32 @@ Three coordinate systems appear in the code:
 DSH package and performs no I/O. Its containment helpers decide whether a target
 path sits under a writable root. The filesystem fence uses them.
 
+## The filesystem substrate
+
+`wsl-fs` serves `ctx.fs` on one of two I/O substrates, chosen by
+`substrate: share | agent` (default `agent`):
+
+| | `agent` (default) | `share` (opt-out) |
+|---|---|---|
+| Reads, writes, identities | the resident in-distro agent, on ext4 | the Windows-side host stack (`dsh-fs-local`) over the distro's 9p share |
+| Symlinks | native; every identity is a distro-side `realpath` | the share cannot traverse them, so a missing read is retried once through the distro's canonical path |
+| Mode bits | native; the publication rename is the kernel's | the share drops a host-side chmod, so publication re-applies the mode from inside the distro before an atomic rename |
+| Guarded creates | the guard is forwarded; publication is a no-replace link, closing the check-then-write window for creates. An overwrite or edit carries its version into the write op and the agent re-verifies it one syscall before the rename — a concurrent writer wins, the stale write refuses with `FS_STALE_VERSION` | checked, then published without a guard (the share has no hard links) |
+| Kernel enforcement | stage two: a mutation runs on a confined resident — one long-lived agent per (distro, policy), whose bwrap profile binds exactly what the mode grants — so the kernel refuses what the check would have, and a check bug cannot become a write outside the workspace. Escalated writes (`danger-full-access`) ride the plain resident. A kernel refusal carries `FS_SANDBOX_DENIED`, the same dialect as the command path. | none: the fence is the host-side check |
+| New files | 0600 — the host backend's own POSIX publication semantics, as on a Linux host | the distro's umask default (0644) |
+| Agent outage | `FS_IO_ERROR` naming the substrate; no silent fallback to the share. A distro without usable bwrap refuses confined mutations with the bootstrap command, the same closed failure the command path has | not applicable |
+
+Both substrates fence writes with the same host-side policy check
+(`checkedTarget`), and neither changes what `sandboxMode` reports. The wire
+protocol the agent 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
+operations, including the write/edit guard orchestration), and
+[`lib/fsio-text.js`](../lib/fsio-text.js) (the pure text mechanics, replicated
+from upstream pending the export proposed in
+[UPSTREAM-FSIO-EXPORT.md](UPSTREAM-FSIO-EXPORT.md)).
+
 ## Sandbox
 
 ### Why the Windows runner cannot be used
@@ -238,6 +264,16 @@ 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

package/docs/CONFIGURATION.md

@@ -16,12 +16,15 @@ are schema defaults, listed because they are the ones worth knowing.
 | | `loginShell` | `true` *(shipped)* | use `<shell> -lc`, which sources your profile, instead of a bare `-c` |
 | | `agent` | `true` | run commands over the resident in-distro agent (one long-lived process; in-distro timeout); any agent failure falls back to the one-shot `wsl.exe` path |
 | | `sandbox` | `true` | confine commands with `bubblewrap`; `false` disables the sandbox |
+| | `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 |
 | | `sandbox` | `true` | check `writeText` and `editText` against the policy |
-| | `resolveSymlinks` | `true` | follow Linux symlinks that the share cannot traverse, such as `/etc/os-release` and `/bin` |
+| | `maskWindowsDrive` | `false` | as on `wsl-shell`: confined fs mutations publish through a resident whose profile shadows `/mnt` (same honest limits) |
+| | `substrate` | `agent` *(shipped)* | which I/O substrate serves the file tools: `agent` — the resident in-distro agent (`lib/fs-substrate.js`), where 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. `share` — the opt-out: the Windows-side host stack over the 9p share, with the symlink-retry and publication hooks. Both substrates fence writes with the same host-side policy check. See [LIMITATIONS.md](LIMITATIONS.md) for what changes between them |
+| | `resolveSymlinks` | `true` | *(share substrate only)* follow Linux symlinks that the share cannot traverse, such as `/etc/os-release` and `/bin` — the agent substrate follows them natively |
 | | `cwd` | `''` | base directory for relative paths; empty means the distro user's home |
 | `directory-picker-wsl` | `preferredDistro` | `''` *(shipped)* | the distro listed first in the picker |
 | | `includeHostHome` | `true` *(shipped)* | also list the Windows home directory |

package/docs/LIMITATIONS.md

@@ -3,9 +3,69 @@
 What the plugin does not do, and why. A limitation that is documented is a design
 boundary; one that is not is a bug report waiting to happen.
 
+## The filesystem substrate (`wsl-fs` `substrate`)
+
+`substrate: "agent"` (the default) serves the file tools through the resident
+in-distro agent, on ext4. `substrate: "share"` is the opt-out: the Windows-side
+host stack over the distro's 9p share. What differs:
+
+- **A new file publishes with mode 0600 on the agent substrate.** That is the
+  host backend's own POSIX publication semantics (a private 0600 staging file,
+  renamed into place), which a Linux-host DSH session has always had. The share
+  substrate was the outlier: the share drops mode sets, so new files took the
+  distro's umask default (0644). Overwrites and edits keep the original bits on
+  both substrates. Run `chmod` (or ask the model to) when a new file must be
+  executable.
+- **There is no silent fallback to the share.** When the agent substrate's
+  resident process is out — the distro stopped, or the agent crashed past its
+  one rebuild — file operations fail with `FS_IO_ERROR` naming the substrate,
+  rather than quietly degrading to share semantics that cannot follow symlinks
+  or keep mode bits. The share substrate dies with the distro anyway; the
+  agent only adds its own failure mode, which is the one honest way to fail.
+- **The mutation guard survives to the write.** `createIfAbsent` publishes with
+  a no-replace link inside the distro, which closes the check-then-write window
+  for creates outright. An overwrite or edit carries the version it was based
+  on into the write op, and the agent re-verifies it against a fresh stat one
+  syscall before the rename: a concurrent writer wins and the stale write
+  refuses with `FS_STALE_VERSION`. That narrows the share's window from a host
+  round trip to kernel-adjacent — the residual stat-then-rename pair is the
+  same sliver a Linux-host session's own rename has.
+- **Stage two routes mutations through a confined resident.** A write or edit
+  under a confined policy runs on its own long-lived agent, spawned inside the
+  bwrap profile that binds exactly what the mode grants — so the kernel, not
+  just the host-side check, refuses a write outside the workspace, and the
+  refusal carries `FS_SANDBOX_DENIED` (the command path's dialect). Costs to
+  know: `bubblewrap` becomes required for confined writes (a distro without it
+  refuses them with the bootstrap command, rather than downgrading); a policy
+  change addresses a different resident, so the first write after switching the
+  Permissions selector pays one agent startup; and a write the policy grants to
+  the distro's `/tmp` lands in the confined mount's tmpfs, not the real `/tmp`
+  — the same hand-off rule as the commands' `/tmp`: pass files through the
+  session workspace.
+- **`resolveSymlinks` is not consulted.** The share cannot traverse Linux
+  symlinks, so the share substrate retries missing reads through the distro's
+  canonical path; the agent substrate never misses them, so the config key has
+  no effect there.
+- **`glob` and `grep` are unchanged on both substrates.** They are tool-layer
+  searches running the packaged Windows ripgrep against the share — correct
+  results, slow, and `.gitignore` interpreted with Windows rules. Bringing them
+  in-distro is future work, not part of the substrate switch.
+- **`watch()` is the same poll loop on both substrates** (a `find -newer` scan
+  inside the distro), so the coarse-invalidation caveats below apply equally.
+  An inotify backend is planned, not shipped.
+
+Everything below applies to the share substrate unless it says otherwise.
+
 - **The sandbox does not govern WSL interop.** A confined command can still run a
   Windows program, which escapes the Linux-side boundary. The plugin reports this as
   `enforcement: partial`. See [ARCHITECTURE.md](ARCHITECTURE.md#reported-enforcement).
+  The `maskWindowsDrive` key on `wsl-shell` and `wsl-fs` narrows the hole: the
+  confined profile shadows `/mnt` with an empty tmpfs, so the drive's files cannot be
+  read or exfiltrated and its executables cannot be launched. It is not a closure — a
+  command that can write the workspace can write an executable there and run it
+  (binfmt interop dispatches on file content, not location) — so enforcement stays
+  `partial`, the result's sandbox fact reports `windowsDrive: "masked"`, and the only
+  complete closure remains distro-level (`[interop] enabled=false` in `wsl.conf`).
 - **`bubblewrap` must be installed**, or both providers fail immediately. The
   usability probe re-runs after a failure, so installing bubblewrap while the app
   runs is believed on the next command; only a success is cached.

package/docs/PEER-PARITY.md

@@ -0,0 +1,60 @@
+# Peer parity — the fsio replication, verified
+
+The agent substrate's text mechanics (`lib/fsio-text.js`) and its provider
+orchestration messages (`lib/fs-substrate.js`, `lib/fsio-agent.js`) are a
+deliberate replica of the pinned peer's fsio module, so the model reads the
+same refusal dialect on both substrates. This file records the verification of
+that claim against the real peers, which are not imported at build time.
+
+- Peer: `@deepseek-ai/dsh-fs-local@0.2.0-rc.2` (the exact version
+  `package.json` pins), plus `@deepseek-ai/dsh-fs@0.2.0-rc.2` for the
+  `FsVersion` brand the local package imports.
+- Method: `npm pack` both pins, extract, and compare the shipped
+  `lib/index.js` (unminified ESM) function-by-function and string-by-string
+  against this repository. Verified 2026-10-03.
+
+## Verdict
+
+**The replication is faithful.** Every load-bearing line matches the peer's
+shipped code; the differences are the substrate's declared extensions, listed
+at the end.
+
+## Verified identical
+
+| Item | Evidence (peer `lib/index.js`) | Ours |
+|---|---|---|
+| `normalizeLineEndings` | `content.replaceAll("\r\n", "\n")` | identical |
+| `detectLineEndings` | 4096-char sample; `crlf > lf - crlf` | identical |
+| `restoreLineEndings` | LF unchanged; CRLF re-normalizes then `\n` → `\r\n` | identical (`replaceAll` vs `split/join` — equivalent) |
+| occurrence counting | non-overlapping left-to-right | `split(needle).length - 1` — equivalent |
+| `applyLiteralEdit` | empty needle, not-found, and ambiguous refusals; single-pass `split/join` without rescanning | identical |
+| edit refusal strings | `old_string must be a non-empty string` (`FS_EDIT_NOT_FOUND`); ``old_string was not found in "${displayPath}"``; ``old_string matched ${n} times in "${displayPath}"; provide a more specific old_string or set replace_all to true`` (`FS_AMBIGUOUS_EDIT`) | identical |
+| invalid UTF-8 | ``cannot ${verb} "${displayPath}": invalid UTF-8 text`` (`FS_NOT_TEXT`) | identical |
+| binary detection | 8192-byte sample, NUL check; ``cannot read "${displayPath}": binary file`` (`FS_NOT_TEXT`) | identical |
+| size caps | ``cannot read "${displayPath}": ${size} bytes exceeds the ${maxBytes}-byte limit`` and ``content exceeds the ${maxBytes}-byte limit`` (`FS_TOO_LARGE`) | identical |
+| `writeText` guards | not-regular (`FS_NOT_REGULAR_FILE`), `file no longer exists` / `file changed since it was read` (`FS_STALE_VERSION`), ``cannot overwrite existing "${displayPath}" without reading it first`` (`FS_NOT_OBSERVED`) | identical |
+| `editText` guards | missing file refuses with `FS_STALE_VERSION` "file changed since it was read" (NOT `FS_NOT_FOUND`); not-regular; stale-version | identical — an earlier draft of this audit suspected a divergence here; the peer matches us |
+| `listDir` refusal | ``cannot list "${displayPath}": not a directory`` (`FS_NOT_DIRECTORY`) | identical |
+| diff-basis gate | `existing !== null && Buffer.byteLength(content) < diffBasisMaxBytes` — keyed on the NEW content's size, `null` above the cap | identical — the gate's new-size keying is inherited by design, not a divergence |
+| outcome shapes | `operation: "update" \| "create"`, the `missing:${targetKey}` sentinel version, `before`/`after` | identical |
+| version join | `` `${info.dev}:${info.ino}:${info.size}:${info.mtimeNs}:${info.ctimeNs}` `` (local `index.js:146`, branded by `dsh-fs`'s `FsVersion`) | `versionOf` — identical shape |
+
+## Deliberate divergences (declared, not drift)
+
+1. **Distro-side version re-verification.** A `replace` write carrying an
+   expected version is re-checked by the agent against a fresh stat one
+   syscall before the rename (`FS_STALE_VERSION` on mismatch). The peer's
+   check-then-write window stops at the host; ours narrows to kernel-adjacent.
+2. **Per-stream truncation flags.** The EXEC frame carries an output budget;
+   the RES line reports which streams the agent cut, surfaced as honest
+   `truncated` flags. The peer's collect-budget machinery is the spill-file
+   path we deliberately do not run.
+3. **The transport around the ops** (ACK, KILL, the confined resident) is
+   protocol this package owns; the peer has no agent.
+
+## Maintenance
+
+When `package.json` bumps the peer pins, re-run this comparison — extract the
+new tarballs and diff the regions above. The fastest canary: stat a file, list
+its directory, and compare the versions (`test/fsio-agent.test.mjs` asserts the
+intra-distro half of this); the strings above are the other half.

package/docs/README.zh.md

@@ -57,6 +57,7 @@ dsh --profile wsl                                  # 4. 启动
 | `wsl-fs` | `distro` | `''` | 同上 |
 | | `restrictToDistro` | `true` | 拒绝指向**其它子系统**共享的路径；`/mnt/c` 属于本子系统内部，不受影响。拒绝码为 `FS_OUTSIDE_DISTRO`，它不是沙箱拒绝，放宽权限也无法解除 |
 | | `sandbox` | `true` | 写入时按策略检查 `writeText` 和 `editText` |
+| | `substrate` | `agent` | 文件工具使用哪种 I/O 基座：`agent` —— 常驻子系统内代理，读写与路径解析直接在 ext4 上完成（原生符号链接、原生权限位，写入 guard 存活到发布时刻，受限策略下由内核强制）；`share` —— 退出项：Windows 侧宿主文件栈走 9p 共享。两种基座使用同一策略围栏；差异详见 [LIMITATIONS.md](LIMITATIONS.md) |
 | `directory-picker-wsl` | `includeHostHome` | `true` | 同时列出 Windows 家目录 |
 | `subprocess-wsl` | `distro` | `''` | GUI 终端开在哪个子系统 |
 
@@ -110,6 +111,7 @@ npm run probe:sandbox        # 在子系统里实测 bubblewrap 能约束什么
 npm run probe                # 文件系统探针，需要真实子系统（仅 Windows + WSL）
 npm run probe:sandbox-shell  # 启动真实 harness，驱动受限执行器
 npm run probe:terminal       # 通过终端 provider 打开一个 PTY
+npm run probe:substrate      # 用真实 wsl.exe 传输驱动 agent 文件基座（在子系统内运行）
 npm run probe:missing-wsl    # 启动一个 wslPath 无法启动的 profile（仅 Windows + WSL）
 npm run probe:picker         # 列出选择器的根级、拒绝路径与上限（仅 Windows + WSL）
 npm run probe:mode           # 哪些 POSIX 权限事实能穿过共享层（仅需 Windows node）

package/docs/UPSTREAM-FSIO-EXPORT.md

@@ -0,0 +1,87 @@
+# Upstream proposal: export the fsio module from `dsh-fs-local`
+
+Status: draft, targeting `deepseek-harness` @ `packages/fs/fs-local` (version
+line `0.2.0-rc.x`). This is the Shape-A upstream half of the in-distro I/O
+refactor: with the fsio module exported, `dsh-plugin-wsl-env` deletes its
+in-plugin replicas (`lib/fsio-text.js`) and imports the originals.
+
+## The change
+
+The fsio module already exists, is fully documented, and is pure (no peers
+beyond types). It is only not reachable: `package.json` exports `"."` and
+`"./package.json"`, and `lib/index.js` does not re-export the helpers. Two
+lines of surface, no behaviour change:
+
+```diff
+--- a/packages/fs/fs-local/package.json
++++ b/packages/fs/fs-local/package.json
+@@
+   "exports": {
+     ".": {
+       "types": "./lib/types/index.d.ts",
+       "default": "./lib/index.js"
+     },
++    "./fsio": {
++      "types": "./lib/types/fsio.d.ts",
++      "default": "./lib/fsio.js"
++    },
+     "./src/*": "./src/*",
+     "./package.json": "./package.json"
+   },
+```
+
+```diff
+--- a/packages/fs/fs-local/lib/index.js
++++ b/packages/fs/fs-local/lib/index.js
+@@
+-export { LocalFileSystem, LocalFileSystem as default };
++export {
++  LocalFileSystem,
++  LocalFileSystem as default,
++  applyLiteralEdit,
++  detectLineEndings,
++  normalizeLineEndings,
++  restoreLineEndings,
++};
+```
+
+(The module layout differs between the repo's `src/` and the built `lib/`;
+the export list is what matters. `readForEdit` and `readTextForDiff` stay
+internal — they are I/O orchestration, which the plugin drives against its own
+substrate — only the pure text mechanics are needed.)
+
+## Why the plugin needs it
+
+`dsh-plugin-wsl-env`'s agent substrate (`lib/fsio-agent.js`,
+`lib/fs-substrate.js`) re-runs fsio's orchestration inside a WSL distro: reads,
+writes, identities and edits execute where the files live, and the host side
+keeps only the validation and edit mechanics. Those mechanics —
+`applyLiteralEdit`, the line-ending trio, the binary NUL sample, the fatal UTF-8
+decode — are replicated today (`lib/fsio-text.js`) because the package does not
+export them. The replica is byte-for-byte faithful, including error messages,
+because the tool layer matches on both the code and the text the model reads;
+but a replica is a fork surface: every upstream change to the edit algorithm
+has to be re-ported by hand.
+
+With the export in place the plugin deletes `lib/fsio-text.js` and imports:
+
+```js
+import { applyLiteralEdit, detectLineEndings, normalizeLineEndings, restoreLineEndings } from "@deepseek-ai/dsh-fs-local/fsio";
+```
+
+## Why this is safe upstream
+
+- No new API surface beyond re-exporting functions that already exist and are
+  documented in `lib/types/fsio.d.ts`.
+- No behaviour change: the class's own call sites are untouched.
+- The functions are pure (text in, text out, structured errors), so exporting
+  them cannot widen the I/O contract.
+- Semver: additive export, a minor bump.
+
+## Follow-up (separate proposal, not required)
+
+A larger seam — parameterizing `LocalFileSystem`'s fsio call sites so a
+subclass can substitute an I/O substrate — would let integrations inherit the
+whole backend instead of re-running its orchestration. The export above is the
+prerequisite and is sufficient on its own; the parameterization is worth
+discussing only after a consumer exists in the wild.

package/lib/agent-confined.js

@@ -0,0 +1,81 @@
+/**
+ * Confined residents: one long-lived agent per (distro, policy) pair, running
+ * its WHOLE lifetime inside the bwrap profile that policy asks for — so every
+ * filesystem op it performs is enforced by the kernel's mount table, not just
+ * by the host-side check that chose it.
+ *
+ * This is stage two of the substrate's enforcement story. Stage one routed
+ * every op through the plain agent with the policy check deciding what may
+ * pass; stage two routes *mutations* to a confined resident whose view of the
+ * filesystem already matches the granted rights, so a bug in the check cannot
+ * become a write outside the workspace — the kernel refuses it.
+ *
+ * Keying is the whole design: the profile is fixed for an agent's lifetime,
+ * so a change in the policy (the Permissions selector, a session move) simply
+ * addresses a different key, and the previous resident retires through its own
+ * idle timer. Escalated writes (`danger-full-access`) keep addressing the
+ * plain agent, which is what an approved escalation means.
+ *
+ * The argv it hands the transport is a whole command — program, profile, `--` —
+ * assembled by the peer-free `lib/bwrap.js`, which both confinement sites share.
+ * That import is why this module needs no DSH peer either: a bare checkout can
+ * construct the factory and assert the command it produces, which is what
+ * `test/agent.test.mjs` does. It used to import the sandbox's own profile
+ * builder and assemble the prefix itself, missing the program; the probe inlined
+ * a third copy, so nothing compared production's command with a working one and
+ * every confined mutation failed the resident's handshake.
+ *
+ * @module dsh-plugin-wsl/agent-confined
+ */
+import { fileURLToPath } from "node:url";
+import { bwrapArgvPrefix } from "./bwrap.js";
+import { toLinuxPath } from "./paths.js";
+import { WslAgent } from "./agent.js";
+
+const AGENT_SCRIPT_PATH = fileURLToPath(new URL("../agent/wsl-agent.sh", import.meta.url));
+const confinedAgents = new Map();
+
+/**
+ * The confined agent for one distro and one resolved policy, created on first
+ * use and shared for the process lifetime. A success is remembered; a failed
+ * start is not (the agent's own rebuild rules take over from there).
+ *
+ * @param {object} request - the confinement request.
+ * @param {string} request.distro - the distro to run in.
+ * @param {string} [request.wslPath] - the `wsl.exe` path.
+ * @param {{mode: string, workspaceRoot: string}} request.policy - the RESOLVED
+ *   file-effect policy: the profile binds exactly what the mode grants.
+ * @param {boolean} [request.maskWindowsDrive] - shadow `/mnt` with an empty
+ *   tmpfs in the resident's profile; part of the cache key, since it changes
+ *   the mount table the resident lives under.
+ * @returns {WslAgent} the confined resident for this key.
+ */
+export function confinedAgent({ distro, wslPath = "wsl.exe", policy, maskWindowsDrive = false }) {
+  const key = `${wslPath}\0${distro}\0${policy.mode}\0${policy.workspaceRoot}\0${maskWindowsDrive ? "masked" : "visible"}`;
+  let agent = confinedAgents.get(key);
+  if (agent === undefined) {
+    agent = new WslAgent({
+      distro,
+      wslPath,
+      scriptPath: toLinuxPath(AGENT_SCRIPT_PATH),
+      // The prefix is a whole command from the distro's point of view — program,
+      // profile, `--` — because the transport inserts it between
+      // `wsl.exe --exec` and the `sh <script>` pair (`lib/agent.js`'s
+      // `spawnDefault`). Both confinement sites share that assembly in
+      // `lib/bwrap.js`, whose module doc records what happened when they did not.
+      argvPrefix: bwrapArgvPrefix(
+        { mode: policy.mode, workspaceRoot: toLinuxPath(policy.workspaceRoot, { distro }) },
+        { maskWindowsDrive },
+      ),
+    });
+    confinedAgents.set(key, agent);
+  }
+  return agent;
+}
+
+/** Test hook: forget every confined resident (the plain agent has no factory state). */
+export function resetConfinedAgents() {
+  confinedAgents.clear();
+}
+
+export default confinedAgent;

package/lib/agent-exec.js

@@ -6,13 +6,15 @@
  * budget, a deadline that kills the Windows process tree. This module builds
  * the SAME handle shape around one agent `exec` — the shape `dsh-tool-bash`
  * consumes, so the tool layer cannot tell which path ran. The deliberate
- * deviations, both memory-for-simplicity trades documented here rather than
- * hidden:
+ * deviations, documented here rather than hidden:
  *
- * - **No spill files.** The agent returns each stream as one buffer; the
- *   handle serves reads from memory. The upstream budget machinery exists to
- *   bound host memory for unbounded streams; the agent path accepts holding
- *   the stream (the protocol line already carries it whole).
+ * - **No spill files; the capture cap is the agent's.** The EXEC frame
+ *   carries the caller's per-stream budget and the AGENT cuts stdout and
+ *   stderr at it, so a chatty command costs bounded distro memory AND bounded
+ *   host memory; the RES line's flags say which streams were cut and the
+ *   handle reports them as `truncated: true`. What the budget spares is the
+ *   upstream spill machinery: the capture is still whole-in-memory, just
+ *   whole-at-a-bounded-size.
  * - **Killed commands report `SIGTERM`**, not a raw exit status: the
  *   in-distro timeout and `kill()` both mean "we stopped it", and upstream
  *   reports its own kills the same way.
@@ -54,13 +56,15 @@ function memoryReader(buffer) {
  * @param {string[]} request.argv - the distro-side argv, bwrap-wrapped when confined.
  * @param {number} [request.timeoutMs] - whole-command budget; the agent TERMs
  *   at the ceiling second and KILLs after its grace.
+ * @param {number} [request.maxOutputBytes] - per-stream capture ceiling the
+ *   agent enforces; the handle reports a cut stream as `truncated: true`.
  * @param {AbortSignal} [request.signal] - the caller's cancellation.
  * @param {(proc: object) => void} [request.onStarted] - provider-facts hook,
  *   called synchronously before the handle can settle.
  * @returns {object} the execution handle (`status`, `exitCode`, `signal`,
  *   `observed`, `done`, `readOutput`, `kill`, `result`).
  */
-export function agentExecutionHandle({ agent, cwd, argv, timeoutMs = 0, signal, onStarted }) {
+export function agentExecutionHandle({ agent, cwd, argv, timeoutMs = 0, maxOutputBytes = 0, signal, onStarted }) {
   // Our own controller is the kill channel; the caller's signal races it.
   const controller = new AbortController();
   let timedOut = false;
@@ -77,7 +81,7 @@ export function agentExecutionHandle({ agent, cwd, argv, timeoutMs = 0, signal,
     }, timeoutMs).unref?.();
   }
 
-  const settle = agent.exec({ cwd, argv, timeoutMs, signal: controller.signal }).then(
+  const settle = agent.exec({ cwd, argv, timeoutMs, maxOutputBytes, signal: controller.signal }).then(
     (result) => ({ ok: true, result }),
     (error) => {
       // A workdir the distro cannot enter is the command's own failure, not
@@ -102,6 +106,9 @@ export function agentExecutionHandle({ agent, cwd, argv, timeoutMs = 0, signal,
   let stdout = Buffer.alloc(0);
   /** @type {Buffer} */
   let stderr = Buffer.alloc(0);
+  /** The agent's per-stream capture-cap flags, surfaced as `truncated`. */
+  let stdoutTruncated = false;
+  let stderrTruncated = false;
   let exitOutcome = { exitCode: null, signal: "SIGTERM" };
 
   let settleError;
@@ -109,6 +116,8 @@ export function agentExecutionHandle({ agent, cwd, argv, timeoutMs = 0, signal,
     if (ok) {
       stdout = result.stdout;
       stderr = result.stderr;
+      stdoutTruncated = result.truncated?.stdout === true;
+      stderrTruncated = result.truncated?.stderr === true;
       // The distro timeout and kill() both mean "we stopped it"; a genuine
       // exit keeps its code.
       if (timedOut || killed || callerAborted) exitOutcome = { exitCode: null, signal: "SIGTERM" };
@@ -175,16 +184,17 @@ export function agentExecutionHandle({ agent, cwd, argv, timeoutMs = 0, signal,
         if (settleError !== undefined) throw settleError;
         // `truncated` is REQUIRED by the bash tool's canonical result — it
         // copies the field unconditionally, and an `undefined` fails the wire's
-        // lossless-JSON snapshot ("value is not lossless JSON").
-        const output = (text) => ({ text, lossy: false, truncated: false });
+        // lossless-JSON snapshot ("value is not lossless JSON"). The agent's
+        // capture-cap flags are what make it TRUE instead of a perma-lie.
+        const output = (text, truncated) => ({ text, lossy: false, truncated });
         return {
           exitCode: proc.exitCode,
           signal: proc.signal,
           timedOut,
           aborted: callerAborted && !timedOut,
           timeoutMs,
-          stdout: output(stdout.toString("utf8")),
-          stderr: output(stderr.toString("utf8")),
+          stdout: output(stdout.toString("utf8"), stdoutTruncated),
+          stderr: output(stderr.toString("utf8"), stderrTruncated),
         };
       });
     },

package/lib/agent-protocol.js

@@ -11,7 +11,14 @@
  */
 
 /** The protocol version this host side speaks; the agent must match. */
-export const PROTOCOL_VERSION = 1;
+export const PROTOCOL_VERSION = 3;
+
+/**
+ * Upper bound on one `read` op's payload, set by the HOST looping over windowed
+ * requests. Keeping each frame's decoded payload here means the agent's RES
+ * line stays modest even for a large file; the host accumulates chunks.
+ */
+export const FS_READ_CHUNK_BYTES = 1024 * 1024;
 
 /** The agent identifies itself with this name in its HELLO line. */
 export const AGENT_NAME = "wsl-agent";
@@ -47,20 +54,26 @@ export function decodeB64(value) {
 
 /**
  * Build the request lines for one EXEC frame: a header line naming the cwd,
- * the whole-request timeout in whole seconds (0 = none) and the argv word
- * count, followed by one base64 line per argv word.
+ * the whole-request timeout in whole seconds (0 = none), the argv word count
+ * and the per-stream output capture budget in bytes (0 = unlimited), followed
+ * by one base64 line per argv word.
  * @param {object} request - the execution request.
  * @param {string} request.id - caller-chosen request id (unique per agent).
  * @param {string} request.cwd - Linux path to cd into before exec.
  * @param {string[]} request.argv - the argv to execute, already bwrap-wrapped.
  * @param {number} [request.timeoutMs] - in-distro timeout; sub-second
  *   remainders round up, and `<= 0` disables the timeout.
+ * @param {number} [request.maxOutputBytes] - per-stream capture ceiling the
+ *   AGENT enforces: stdout and stderr are each cut at this many bytes and the
+ *   RES line reports what was cut. 0 (the default) keeps the historical
+ *   unbounded capture.
  * @returns {string[]} the lines to write to the agent's stdin, in order.
  */
-export function encodeExecFrame({ id, cwd, argv, timeoutMs = 0 }) {
+export function encodeExecFrame({ id, cwd, argv, timeoutMs = 0, maxOutputBytes = 0 }) {
   const timeoutSeconds = timeoutMs > 0 ? Math.ceil(timeoutMs / 1000) : 0;
+  const cap = maxOutputBytes > 0 ? Math.floor(maxOutputBytes) : 0;
   const lines = [
-    `EXEC|${id}|${encodeB64(cwd)}|${timeoutSeconds}|${argv.length}`,
+    `EXEC|${id}|${encodeB64(cwd)}|${timeoutSeconds}|${argv.length}|${cap}`,
     ...argv.map((word) => encodeB64(word)),
   ];
   return lines;
@@ -82,6 +95,38 @@ export function encodeKill(id) {
   return `KILL|${id}`;
 }
 
+/**
+ * Build the request lines for one FS frame — the filesystem-substrate request
+ * that lets the model's file tools run inside the distro. The shape mirrors
+ * EXEC: a header naming the op, the timeout in whole seconds and the argument
+ * count, followed by one base64 line per argument.
+ *
+ * Ops (see `agent/wsl-agent.sh` for the server side and the wire grammar):
+ * `stat`, `lstat`, `list`, `realpath`, `read`, `write`. Responses reuse the
+ * EXEC `ACK`/`RES`/`ERR` lines, so the request machinery (pending map, KILL,
+ * the watchdog) is shared unchanged.
+ *
+ * The argument contract: callers pass PLAINTEXT values here; this frame is the
+ * single base64 boundary, and the agent decodes each argument once. A write's
+ * content is no exception — the agent pipes its still-encoded wire line
+ * straight to `base64 -d`, so raw bytes never pass through a shell variable.
+ *
+ * @param {object} request - the filesystem request.
+ * @param {string} request.id - caller-chosen request id (unique per agent).
+ * @param {string} request.op - one of the op names above.
+ * @param {string[]} request.args - op arguments, base64-line encoded here.
+ * @param {number} [request.timeoutMs] - in-distro timeout; sub-second
+ *   remainders round up, and `<= 0` disables the timeout.
+ * @returns {string[]} the lines to write to the agent's stdin, in order.
+ */
+export function encodeFsFrame({ id, op, args, timeoutMs = 0 }) {
+  const timeoutSeconds = timeoutMs > 0 ? Math.ceil(timeoutMs / 1000) : 0;
+  return [
+    `FS|${id}|${op}|${timeoutSeconds}|${args.length}`,
+    ...args.map((word) => encodeB64(word)),
+  ];
+}
+
 /** The line parser's verdict for one line of agent stdout. */
 
 /**
@@ -90,6 +135,9 @@ export function encodeKill(id) {
  * @returns {object} one of:
  *   - `{ type: "hello", name, version }`
  *   - `{ type: "pong" }`
+ *   - `{ type: "ack", id }` — the agent dequeued the request for execution;
+ *     the host arms its stuck-request watchdog here, so queue time never
+ *     counts against a budget
  *   - `{ type: "result", id, exitCode, stdout, stderr }` — outputs as Buffers
  *   - `{ type: "agentError", id, reason, message }` — `id` is `""` when the
  *     agent reports a request-less problem (a protocol violation)
@@ -104,9 +152,19 @@ export function parseAgentLine(line) {
     return { type: "hello", name, version: Number(version) };
   }
   if (line === "PONG") return { type: "pong" };
+  if (line.startsWith("ACK|")) return { type: "ack", id: line.slice(4) };
   if (line.startsWith("RES|")) {
-    const [, id, exitCode, stdout, stderr] = line.split("|");
-    return { type: "result", id, exitCode: Number(exitCode), stdout: decodeB64(stdout ?? ""), stderr: decodeB64(stderr ?? "") };
+    const [, id, exitCode, stdout, stderr, outTruncated, errTruncated] = line.split("|");
+    return {
+      type: "result",
+      id,
+      exitCode: Number(exitCode),
+      stdout: decodeB64(stdout ?? ""),
+      stderr: decodeB64(stderr ?? ""),
+      // The capture-cap flags the agent appends when the EXEC frame carried a
+      // budget; frames without them (fakes, FS ops) are simply not truncated.
+      truncated: { stdout: outTruncated === "1", stderr: errTruncated === "1" },
+    };
   }
   if (line.startsWith("ERR|")) {
     const [, id, reason, message] = line.split("|");