dsh-plugin-wsl-env 0.2.0 → 0.4.0

package/docs/PARITY.md

@@ -11,7 +11,7 @@ distro. Everything users love — native ext4 semantics, inotify, native
 `rg`, low latency — is a derivative. This plugin's 9p-UNC plus one-shot
 `wsl.exe` model can only approach it. The plan therefore lands a resident
 in-distro agent and migrates the `fs` and `shell` seams onto it, keeping the
-current paths as the documented fallback (`wsl.agent: 'off'` must equal
+current paths as the documented fallback (`wsl.agent: false` must equal
 today's behaviour byte for byte).
 
 Not applicable, recorded so the gap is a decision and not an omission:
@@ -64,7 +64,8 @@ shaped a phase of the plan.
 
 ## Fallback invariant
 
-Every phase must keep `wsl.agent: 'off'` (and, per capability, any runtime
+Every phase must keep `wsl.agent: false` (and, per capability, any runtime
 fallback) behaviourally identical to the pre-phase release. Probes assert
-this: `agent.sh` runs the same operation with the agent off and on and
-compares outcomes, not internals.
+this: `agent.sh` runs the same operations through the resident and through
+the one-shot `wsl.exe` path and compares outcomes — exit code, stdout bytes,
+stderr bytes, working directory — not internals.

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,87 @@
+/**
+ * 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.
+ * @param {boolean} [request.realTmp] - default TRUE: workspace-write binds the
+ *   distro's real `/tmp` read-write into the resident's profile, so a write
+ *   the fence approved lands where every reader reads. `false` restores the
+ *   ephemeral tmpfs — for tests and probes, not production: a `/tmp` write
+ *   behind an ephemeral mount reports success into a directory no reader can
+ *   see, which is the bug this default exists to prevent.
+ * @returns {WslAgent} the confined resident for this key.
+ */
+export function confinedAgent({ distro, wslPath = "wsl.exe", policy, maskWindowsDrive = false, realTmp = true }) {
+  const key = `${wslPath}\0${distro}\0${policy.mode}\0${policy.workspaceRoot}\0${maskWindowsDrive ? "masked" : "visible"}\0${realTmp ? "real" : "ephemeral"}`;
+  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, realTmp },
+      ),
+    });
+    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("|");