dsh-plugin-wsl-env 0.2.0 → 0.4.0

package/lib/agent.js

@@ -5,16 +5,25 @@
  * distro. The lifetime rules, in order of importance:
  *
  * 1. **Correctness before speed.** Any agent failure is answered by at most
- *    one rebuild; the requests that were in flight ride the rebuild. A second
- *    failure marks the agent permanently dead and every future call rejects
- *    with {@link AgentUnavailableError} — the executor's cue to fall back to
- *    the one-shot `wsl.exe` path it shipped with, so the worst case of the
- *    agent is "today's behaviour, plus one failed round trip".
+ *    one rebuild; the requests that were in flight ride it ONLY when their
+ *    first execution provably changed nothing (the read-only FS ops). A
+ *    command or a write that was in flight has UNKNOWN state — replaying it
+ *    would run non-idempotent work twice or report a create that actually
+ *    succeeded as a refusal — so it fails instead, and the caller re-reads
+ *    before retrying. A second failure marks the agent permanently dead and
+ *    every future call rejects with {@link AgentUnavailableError} — the
+ *    executor's cue to fall back to the one-shot `wsl.exe` path it shipped
+ *    with, so the worst case of the agent is "today's behaviour, plus one
+ *    failed round trip".
  * 2. **The in-distro timeout is the real one.** The EXEC frame carries the
  *    timeout in whole seconds and the agent SIGTERMs the child itself, so a
  *    timed-out command dies where it lives instead of leaving an orphan
- *    behind a dead `wsl.exe`. A host-side watchdog only guards an agent that
- *    stopped answering at all.
+ *    behind a dead `wsl.exe`. The host-side watchdog is armed on the agent's
+ *    `ACK` — the dequeue signal — so it measures EXECUTION, never the queue
+ *    wait: a short-budget request queued behind a long one can no longer
+ *    kill the shared transport for a stall that was never its own. It still
+ *    catches an agent that accepted a request and then stopped answering at
+ *    all.
  * 3. **Idle agents go away.** `idleMs` after the last exchange the process is
  *    killed; the next call starts a fresh one. WSL VMs are shared, but every
  *    process is a promise someone has to keep.
@@ -26,9 +35,8 @@
  */
 
 import { spawn } from "node:child_process";
-import { createInterface } from "node:readline";
 import { AgentUnavailableError, CwdError } from "./agent-errors.js";
-import { AGENT_NAME, PROTOCOL_VERSION, encodeExecFrame, encodeKill, encodeSetEnv, parseAgentLine } from "./agent-protocol.js";
+import { AGENT_NAME, MAX_FRAME_BYTES, PROTOCOL_VERSION, encodeExecFrame, encodeFsFrame, encodeKill, encodeSetEnv, parseAgentLine } from "./agent-protocol.js";
 
 /** How long a rebuilt agent has to re-answer the handshake before giving up. */
 const HANDSHAKE_TIMEOUT_MS = 15000;
@@ -36,6 +44,50 @@ const HANDSHAKE_TIMEOUT_MS = 15000;
 /** Extra time the host watchdog waits past the request's own in-distro timeout. */
 const WATCHDOG_GRACE_MS = 13000;
 
+/** The Windows essentials `wsl.exe` itself needs to start and report cleanly. */
+const WINDOWS_ESSENTIALS = /^(systemroot|systemdrive|windir|path|pathext|comspec|os|computername)$/i;
+
+/** The managed facts prefix whose names (and only theirs) may be forwarded. */
+const MANAGED_ENV_PREFIX = "DSH_";
+
+/**
+ * The Windows environment the transport starts from, pinned.
+ *
+ * Spawned bare, `wsl.exe` would inherit this process's whole environment — and
+ * the `WSLENV` variable riding along decides which of those names are
+ * FORWARDED into the distro, where every model command inherits them. Dev
+ * machines routinely route secrets that way (`WSLENV=GITHUB_TOKEN/u` is the
+ * documented example), so the resident's env is built from scratch instead:
+ * the Windows essentials `wsl.exe` itself needs, the managed `DSH_*` facts,
+ * and a `WSLENV` that names only those managed entries — preserving their
+ * original forwarding flags. Nothing else on the Windows side can reach a
+ * model command.
+ *
+ * Deliberately NOT here: the executor's `forwardEnv` names. They ride the
+ * one-shot path's WSLENV (`spawnSpec` builds it per call); the resident path
+ * has never forwarded them, and this pin keeps that posture instead of
+ * widening it silently.
+ *
+ * @param {Record<string, string|undefined>} parent - this process's environment.
+ * @returns {Record<string, string>} the pinned environment for `wsl.exe`.
+ */
+export function pinnedWindowsEnv(parent) {
+  const env = {};
+  for (const [name, value] of Object.entries(parent)) {
+    if (value === undefined) continue;
+    if (WINDOWS_ESSENTIALS.test(name) || name.startsWith(MANAGED_ENV_PREFIX)) env[name] = value;
+  }
+  env.WSLENV = String(parent.WSLENV ?? "")
+    .split(":")
+    .filter((entry) => entry.startsWith(MANAGED_ENV_PREFIX))
+    .join(":");
+  // wsl.exe writes its own diagnostics as UTF-16LE without this, and a UTF-16
+  // message read as UTF-8 is mojibake — including the `WSL_E_*` codes. Same
+  // pin the one-shot path applies to every spawn.
+  env.WSL_UTF8 = "1";
+  return env;
+}
+
 /**
  * @param {object} options - the spawn options.
  * @param {string} options.wslPath - the `wsl.exe` path.
@@ -45,8 +97,9 @@ const WATCHDOG_GRACE_MS = 13000;
  *   `agent/wsl-agent.sh`).
  * @returns {import("node:child_process").ChildProcess} the spawned process.
  */
-function spawnDefault({ wslPath, distro, scriptPath }) {
-  return spawn(wslPath, ["-d", distro, "--exec", "sh", scriptPath], {
+function spawnDefault({ wslPath, distro, scriptPath, argvPrefix = [] }) {
+  return spawn(wslPath, ["-d", distro, "--exec", ...argvPrefix, "sh", scriptPath], {
+    env: pinnedWindowsEnv(process.env),
     stdio: ["pipe", "pipe", "pipe"],
     windowsHide: true,
   });
@@ -63,14 +116,22 @@ export class WslAgent {
    *   inside the distro (see {@link spawnDefault}).
    * @param {string} [config.wslPath] - the `wsl.exe` path.
    * @param {number} [config.idleMs] - idle shutdown delay; 0 disables.
-   * @param {(options: {wslPath: string, distro: string, scriptPath: string}) => import("node:child_process").ChildProcess} [config.spawnTransport]
+   * @param {string[]} [config.argvPrefix] - arguments inserted between
+   *   `wsl.exe --exec` and the `sh script` pair — the confinement wrapper
+   *   (`bwrap … --`) a confined agent runs its whole lifetime under, so every
+   *   filesystem op it performs is kernel-enforced. Empty for the plain agent.
+   * @param {(options: {wslPath: string, distro: string, scriptPath: string, argvPrefix: string[]}) => import("node:child_process").ChildProcess} [config.spawnTransport]
    *   injectable process factory for tests.
    */
   constructor(config) {
     this.distro = config.distro;
     this.scriptPath = config.scriptPath;
     this.wslPath = config.wslPath ?? "wsl.exe";
+    this.argvPrefix = config.argvPrefix ?? [];
     this.idleMs = config.idleMs ?? 600000;
+    /** Hard ceiling on one stdout protocol line; a longer line is a broken or
+     * hostile agent, not data to hold — readline used to accumulate it all. */
+    this.frameCapBytes = config.frameCapBytes ?? MAX_FRAME_BYTES;
     this.configuredSpawn = config.spawnTransport;
     /** @type {import("node:child_process").ChildProcess|null} */
     this.process = null;
@@ -117,6 +178,7 @@ export class WslAgent {
         wslPath: this.wslPath,
         distro: this.distro,
         scriptPath: this.scriptPath,
+        argvPrefix: this.argvPrefix,
       }));
       const handshakeTimer = setTimeout(() => {
         this.lastError = `agent handshake timed out after ${HANDSHAKE_TIMEOUT_MS}ms`;
@@ -145,8 +207,34 @@ export class WslAgent {
         }
         this.handleProcessExit(code, signalName);
       });
-      const out = createInterface({ input: child.stdout });
-      out.on("line", (line) => this.handleLine(line, settleStart, handshakeTimer));
+      // A bounded line splitter instead of readline: readline accumulates an
+      // over-long line whole before anyone can object, which is exactly the
+      // unbounded-capture hole. Protocol lines are ASCII by construction
+      // (ids, numbers, base64), so chunk-boundary decoding is not a concern.
+      let buffered = "";
+      child.stdout.on("data", (chunk) => {
+        buffered += chunk.toString("utf8");
+        for (;;) {
+          const newline = buffered.indexOf("\n");
+          if (newline === -1) {
+            if (buffered.length > this.frameCapBytes) {
+              this.lastError = `agent frame of ${buffered.length} bytes exceeded the ${this.frameCapBytes}-byte protocol cap`;
+              buffered = "";
+              this.process?.kill();
+            }
+            return;
+          }
+          const line = buffered.slice(0, newline);
+          buffered = buffered.slice(newline + 1);
+          if (line.length > this.frameCapBytes) {
+            this.lastError = `agent frame of ${line.length} bytes exceeded the ${this.frameCapBytes}-byte protocol cap`;
+            buffered = "";
+            this.process?.kill();
+            return;
+          }
+          this.handleLine(line, settleStart, handshakeTimer);
+        }
+      });
       child.stderr?.on("data", (chunk) => {
         // Diagnostics only; `wsl.exe` and the shell chatter here on failure.
         this.lastError = String(chunk).trim().slice(0, 2000) || this.lastError;
@@ -173,13 +261,22 @@ export class WslAgent {
         settleStart();
         break;
       }
+      case "ack": {
+        // Dequeue signal: start this request's own budget clock NOW. Armed
+        // here instead of at submission, a queued request can no longer time
+        // out on a queue it never chose to join — and its watchdog can never
+        // kill the shared transport for a stall that was never its own.
+        const pending = this.pending.get(message.id);
+        pending?.armWatchdog?.();
+        break;
+      }
       case "result": {
         const pending = this.pending.get(message.id);
         if (!pending) break; // answered after its caller gave up — noise
         this.clearPending(pending);
         this.pending.delete(message.id);
         this.rearmIdleTimer();
-        pending.resolve({ exitCode: message.exitCode, stdout: message.stdout, stderr: message.stderr });
+        pending.resolve({ exitCode: message.exitCode, stdout: message.stdout, stderr: message.stderr, truncated: message.truncated });
         break;
       }
       case "agentError": {
@@ -223,16 +320,51 @@ export class WslAgent {
       this.startPromise = null;
       const carrying = [...this.pending.values()];
       this.pending.clear();
+      // Only provably read-only FS requests ride the rebuild: whatever their
+      // first execution did, it changed nothing. A command or a write that was
+      // in flight has UNKNOWN state — replaying it would run non-idempotent
+      // work a second time, or report a guarded create that actually
+      // succeeded as a refusal — so it fails with that fact instead. A stale
+      // watchdog must not survive either: its closure kills `this.process`,
+      // which after the rebuild is the NEW transport.
+      const relayable = [];
+      for (const pending of carrying) {
+        if (pending.signal?.aborted) {
+          // Already rejected to its caller by the abort listener; do not
+          // resurrect it on the rebuilt agent.
+          this.clearPending(pending);
+          continue;
+        }
+        if (isReplayableFrame(pending.lines)) {
+          if (pending.watchdog) {
+            clearTimeout(pending.watchdog);
+            pending.watchdog = null;
+          }
+          relayable.push(pending);
+        } else {
+          this.clearPending(pending);
+          pending.reject(new AgentUnavailableError(
+            `agent exited while request ${pending.id} was in flight; its state is unknown — inspect the distro before retrying`,
+          ));
+        }
+      }
       this.start()
         .then(() => {
-          for (const pending of carrying) {
+          for (const pending of relayable) {
             const id = `r${this.nextRequestId++}`;
+            pending.id = id;
             this.pending.set(id, pending);
-            this.writeLines(relabelFrame(pending.lines, id));
+            // The rebuilt transport can itself be gone by now; a frame that
+            // cannot be written must fail its caller, not strand the entry.
+            if (!this.writeLines(relabelFrame(pending.lines, id))) {
+              this.clearPending(pending);
+              this.pending.delete(id);
+              pending.reject(new AgentUnavailableError(`agent exited before request ${id} could be re-sent; its state is unknown`));
+            }
           }
         })
         .catch((error) => {
-          for (const pending of carrying) {
+          for (const pending of relayable) {
             this.clearPending(pending);
             pending.reject(error);
           }
@@ -249,6 +381,70 @@ export class WslAgent {
     this.pending.clear();
   }
 
+  /**
+   * Register one request's pending entry and write its frame: the shared
+   * request machinery (abort, submission, the ACK-armed watchdog). The
+   * watchdog is deliberately NOT armed here — it starts at the agent's
+   * dequeue `ACK`, so time spent queued behind an earlier request never
+   * spends this request's budget and never kills the shared transport for a
+   * stall that was not its own.
+   * @private
+   */
+  track({ id, lines, resolve, reject, timeoutMs, signal }) {
+    const pending = {
+      id,
+      lines,
+      resolve,
+      reject,
+      watchdog: null,
+      signal: signal ?? null,
+      onAbort: null,
+      armWatchdog:
+        timeoutMs > 0
+          ? () => {
+              if (pending.watchdog) return;
+              // The in-distro timeout does the killing; this only catches an
+              // agent that accepted the request and then stopped answering
+              // even to its own timer.
+              pending.watchdog = setTimeout(() => {
+                this.lastError = `agent did not answer request ${pending.id} within ${timeoutMs + WATCHDOG_GRACE_MS}ms of its dispatch`;
+                this.process?.kill();
+              }, timeoutMs + WATCHDOG_GRACE_MS);
+            }
+          : null,
+    };
+    this.pending.set(id, pending);
+    if (signal) {
+      if (signal.aborted) {
+        this.pending.delete(id);
+        reject(signal.reason instanceof Error ? signal.reason : new Error("aborted"));
+        return;
+      }
+      pending.onAbort = () => {
+        // Address by the entry's CURRENT id: a request relayed across a
+        // rebuild was re-registered under a fresh one, and a stale KILL (or a
+        // stale map delete) would strand the entry and leave the command
+        // running to its own timeout.
+        this.writeLines([encodeKill(pending.id)]);
+        this.clearPending(pending);
+        this.pending.delete(pending.id);
+        reject(signal.reason instanceof Error ? signal.reason : new Error("aborted"));
+      };
+      signal.addEventListener("abort", pending.onAbort, { once: true });
+    }
+    // A frame that cannot be WRITTEN must fail its caller now. Silently
+    // dropping it used to strand the request: nothing would ever answer, the
+    // watchdog (armed on an ACK that will not come) had no process to kill,
+    // and with no timeout the caller waited forever.
+    if (!this.writeLines(lines)) {
+      this.clearPending(pending);
+      this.pending.delete(pending.id);
+      reject(new AgentUnavailableError("the agent exited before the request could be sent; it never ran"));
+      return;
+    }
+    this.rearmIdleTimer();
+  }
+
   /**
    * Run one command inside the distro through the agent.
    * @param {object} request - the execution request.
@@ -256,14 +452,18 @@ export class WslAgent {
    * @param {string[]} request.argv - the argv, already bwrap-wrapped when the
    *   caller confines.
    * @param {number} [request.timeoutMs] - in-distro timeout, whole seconds
-   *   upward; `<= 0` or omitted means none.
+   *   upward, measured from the agent's dequeue ACK; `<= 0` or omitted means
+   *   none. Queue time ahead of the dispatch is never counted.
    * @param {Record<string, string>} [request.env] - extra environment for this
    *   request only; values lose trailing newlines (protocol limitation).
+   * @param {number} [request.maxOutputBytes] - per-stream capture ceiling the
+   *   agent enforces (carried on the EXEC frame); the RES line reports which
+   *   streams were cut. 0 (the default) keeps the unbounded capture.
    * @param {AbortSignal} [request.signal] - cancels the request (KILL + reject).
-   * @returns {Promise<{exitCode: number, stdout: Buffer, stderr: Buffer}>}
+   * @returns {Promise<{exitCode: number, stdout: Buffer, stderr: Buffer, truncated: {stdout: boolean, stderr: boolean}}>}
    * @throws {AgentUnavailableError} when the agent is out for this process.
    */
-  async exec({ cwd, argv, timeoutMs = 0, env, signal }) {
+  async exec({ cwd, argv, timeoutMs = 0, maxOutputBytes = 0, env, signal }) {
     if (this.state === "dead") {
       throw new AgentUnavailableError(this.lastError);
     }
@@ -271,35 +471,39 @@ export class WslAgent {
     const id = `r${this.nextRequestId++}`;
     const lines = [
       ...(env ? Object.entries(env).map(([key, value]) => encodeSetEnv(key, value)) : []),
-      ...encodeExecFrame({ id, cwd, argv, timeoutMs }),
+      ...encodeExecFrame({ id, cwd, argv, timeoutMs, maxOutputBytes }),
     ];
     return new Promise((resolve, reject) => {
-      const pending = { lines, resolve, reject, watchdog: null, signal, onAbort: null };
-      this.pending.set(id, pending);
-      if (signal) {
-        if (signal.aborted) {
-          this.pending.delete(id);
-          reject(signal.reason instanceof Error ? signal.reason : new Error("aborted"));
-          return;
-        }
-        pending.onAbort = () => {
-          this.writeLines([encodeKill(id)]);
-          this.clearPending(pending);
-          this.pending.delete(id);
-          reject(signal.reason instanceof Error ? signal.reason : new Error("aborted"));
-        };
-        signal.addEventListener("abort", pending.onAbort, { once: true });
-      }
-      if (timeoutMs > 0) {
-        // The in-distro timeout does the killing; this only catches an agent
-        // that stopped answering even to its own timer.
-        pending.watchdog = setTimeout(() => {
-          this.lastError = `agent did not answer request ${id} within ${timeoutMs + WATCHDOG_GRACE_MS}ms`;
-          this.process?.kill();
-        }, timeoutMs + WATCHDOG_GRACE_MS);
-      }
-      this.writeLines(lines);
-      this.rearmIdleTimer();
+      this.track({ id, lines, resolve, reject, timeoutMs, signal });
+    });
+  }
+
+  /**
+   * Run one filesystem-substrate op inside the distro through the agent.
+   * Responses reuse the EXEC `ACK`/`RES` lines, so cancellation and the
+   * watchdog are exactly the command path's. The rebuild relay differs by op:
+   * a read-only op rides a rebuild, a `write` in flight fails with an
+   * unknown-state error instead of being replayed.
+   * @param {object} request - the filesystem request.
+   * @param {string} request.op - op name (`stat`, `lstat`, `list`, `realpath`,
+   *   `read`, `write`), dispatched by `agent/wsl-agent.sh`.
+   * @param {string[]} request.args - op arguments; each rides one base64 line.
+   * @param {number} [request.timeoutMs] - in-distro timeout, whole seconds
+   *   upward, measured from the agent's dequeue ACK; `<= 0` or omitted means
+   *   none.
+   * @param {AbortSignal} [request.signal] - cancels the request (KILL + reject).
+   * @returns {Promise<{exitCode: number, stdout: Buffer, stderr: Buffer}>}
+   * @throws {AgentUnavailableError} when the agent is out for this process.
+   */
+  async fs({ op, args, timeoutMs = 0, signal }) {
+    if (this.state === "dead") {
+      throw new AgentUnavailableError(this.lastError);
+    }
+    await this.start();
+    const id = `r${this.nextRequestId++}`;
+    const lines = encodeFsFrame({ id, op, args, timeoutMs });
+    return new Promise((resolve, reject) => {
+      this.track({ id, lines, resolve, reject, timeoutMs, signal });
     });
   }
 
@@ -315,19 +519,7 @@ export class WslAgent {
     return new Promise((resolve, reject) => {
       const id = `r${this.nextRequestId++}`;
       const lines = encodeExecFrame({ id, cwd: "/", argv: ["true"], timeoutMs: 0 });
-      const pending = {
-        lines,
-        resolve: () => resolve(),
-        reject,
-        watchdog: setTimeout(() => {
-          this.lastError = "agent did not answer ping";
-          this.process?.kill();
-        }, HANDSHAKE_TIMEOUT_MS),
-        signal: null,
-        onAbort: null,
-      };
-      this.pending.set(id, pending);
-      this.writeLines(lines);
+      this.track({ id, lines, resolve: () => resolve(), reject, timeoutMs: HANDSHAKE_TIMEOUT_MS, signal });
     });
   }
 
@@ -359,15 +551,20 @@ export class WslAgent {
   /** @private */
   writeLines(lines) {
     const child = this.process;
-    if (!child || !child.stdin.writable) return;
+    if (!child || !child.stdin.writable) return false;
     child.stdin.write(`${lines.join("\n")}\n`);
     this.rearmIdleTimer();
+    return true;
   }
 
   /** @private */
   writeLinesSafe(child, lines) {
+    // The writable check matters beyond politeness: a write to an ENDED stdin
+    // does not throw here — it emits an async 'error' event the caller never
+    // listens for, which crashes the process during its own shutdown.
+    if (!child.stdin || !child.stdin.writable) return;
     try {
-      child.stdin?.write(`${lines.join("\n")}\n`);
+      child.stdin.write(`${lines.join("\n")}\n`);
     } catch {
       // A dead pipe is what close() is cleaning up after.
     }
@@ -390,6 +587,24 @@ export class WslAgent {
   }
 }
 
+/** The read-only FS ops: replaying them across a rebuild changes nothing. */
+const REPLAYABLE_FS_OPS = new Set(["stat", "lstat", "list", "realpath", "read"]);
+
+/**
+ * Whether a stored request frame's first execution provably had no side
+ * effects, so the frame may ride the one permitted rebuild. An EXEC never
+ * qualifies — a command's effects are unknowable after the agent died — and
+ * neither does an FS `write`. (A SETENV prefix line never decides: the frame
+ * header sits at `lines[0]` only for FS frames, which carry no SETENV.)
+ * @param {string[]} lines - the stored frame.
+ * @returns {boolean}
+ */
+function isReplayableFrame(lines) {
+  const header = lines[0] ?? "";
+  if (!header.startsWith("FS|")) return false;
+  return REPLAYABLE_FS_OPS.has(header.split("|")[2]);
+}
+
 /**
  * Rewrite the request id inside a stored frame so a resent request does not
  * collide with ids the new process has already seen. SETENV lines pass
@@ -403,7 +618,7 @@ export function relabelFrame(lines, newId) {
     const separator = line.indexOf("|");
     if (separator === -1) return line;
     const kind = line.slice(0, separator);
-    if (kind !== "EXEC" && kind !== "KILL") return line;
+    if (kind !== "EXEC" && kind !== "FS" && kind !== "KILL") return line;
     const rest = line.slice(separator + 1);
     const pipe = rest.indexOf("|");
     const tail = pipe === -1 ? "" : rest.slice(pipe);

package/lib/bwrap.js

@@ -0,0 +1,91 @@
+/**
+ * The distro-side `bwrap` command line, shared by every confinement site.
+ *
+ * Two callers compose a confined command and they must agree on it exactly:
+ * `lib/sandbox.js` wraps a *single* command (`confine()`, and the usability
+ * probe), and `lib/agent-confined.js` wraps a *resident* whose whole lifetime
+ * runs inside the profile — it hands the prefix to the transport, which inserts
+ * it between `wsl.exe --exec` and the `sh <script>` pair.
+ *
+ * That split is why this module exists. The two sites used to assemble the argv
+ * themselves, and only one of them prepended the program: the confined resident's
+ * prefix began at `--ro-bind`, so `wsl.exe --exec` tried to run a `--ro-bind`
+ * executable, the agent exited 1 during its handshake, and every confined
+ * mutation failed with `FS_IO_ERROR: … agent exited during handshake`. The
+ * verified probe could not see it because it inlined its own copy of the argv.
+ *
+ * This module imports nothing, so a bare checkout can assert the argv both sites
+ * actually produce.
+ *
+ * @module dsh-plugin-wsl/bwrap
+ */
+
+/**
+ * Build the bwrap profile arguments for one file-effect policy, exactly as
+ * upstream's `bwrapProfileArgs` does.
+ *
+ * `--ro-bind / /` makes the whole distro read-only, `--dev /dev` supplies the
+ * `/dev/null` sink a shell needs, `--unshare-pid` keeps the sandbox's process
+ * view its own, and `--proc /proc` gives it a matching `/proc`. Under
+ * `workspace-write` the workspace is bound read-write and `/tmp` becomes an
+ * ephemeral tmpfs — the temp area the mode promises, without exposing the
+ * distro's real `/tmp`.
+ *
+ * `options.maskWindowsDrive` mounts an empty tmpfs over `/mnt` AFTER the
+ * read-only root, shadowing the Windows drive: the drive's files disappear
+ * from the command's view, which severs interop as a side effect — a Windows
+ * executable on the drive can no longer be reached to launch, and the drive's
+ * data cannot be read or exfiltrated. It is a narrowing, not a closure: a
+ * command may still WRITE an executable into the workspace and run it
+ * (binfmt interop dispatches on file content, not location), so `enforcement`
+ * stays `partial` — see `lib/sandbox.js`.
+ *
+ * `options.realTmp` changes what workspace-write does at `/tmp`. The default
+ * (`--tmpfs /tmp`) gives the sandbox an ephemeral, empty temp area — the right
+ * shape for a COMMAND: fresh per run, cannot touch the distro's real `/tmp`,
+ * cannot be poisoned by a previous run. `realTmp: true` binds the REAL `/tmp`
+ * read-write instead — the right shape for the FILE-WRITES resident: the
+ * fence grants `/tmp` as a writable root, so a write the fence approved must
+ * land where every reader (the plain agent, the user's own shell) reads — not
+ * inside a private tmpfs that reads cannot see and that dies with the
+ * resident. Read-only mode mounts no `/tmp` at all, so the option is inert
+ * there.
+ *
+ * @param policy - the policy to express as bwrap mounts.
+ * @param options - profile options.
+ * @param options.maskWindowsDrive - shadow `/mnt` with an empty tmpfs.
+ * @param options.realTmp - workspace-write binds the real `/tmp` read-write
+ *   instead of mounting an ephemeral tmpfs over it.
+ * @returns profile arguments, before the `--` separator and the command argv.
+ */
+export function bwrapProfileArgs(policy, options = {}) {
+  const args = ["--ro-bind", "/", "/", "--dev", "/dev", "--unshare-pid", "--proc", "/proc", "--die-with-parent"];
+  if (policy.mode === "workspace-write") {
+    if (options.realTmp) {
+      args.push("--bind", "/tmp", "/tmp");
+    } else {
+      args.push("--tmpfs", "/tmp");
+    }
+    args.push("--bind", policy.workspaceRoot, policy.workspaceRoot);
+  }
+  if (options.maskWindowsDrive) {
+    args.push("--tmpfs", "/mnt");
+  }
+  return args;
+}
+
+/**
+ * The argv prefix that runs one command (or one resident) inside the profile.
+ *
+ * The prefix is a complete command from the distro's point of view: it names the
+ * program (`bwrap`), the profile, and the `--` separator that ends bwrap's own
+ * options. `workspaceRoot` must already be spelled as a Linux path inside the
+ * distro; the callers own that translation.
+ *
+ * @param policy - the resolved policy: `mode`, plus the Linux `workspaceRoot`.
+ * @param options - profile options, passed through to {@link bwrapProfileArgs}.
+ * @returns argv to insert before the command, as the transport receives it.
+ */
+export function bwrapArgvPrefix(policy, options = {}) {
+  return ["bwrap", ...bwrapProfileArgs(policy, options), "--"];
+}