comisai 1.0.42 → 1.0.45

package/node_modules/@comis/skills/dist/tools/builtin/terminal-driver/terminal-render.js

@@ -0,0 +1,279 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * The per-session terminal-emulator wrapper (spec §2.4 rendering).
+ *
+ * Wraps a REAL `@xterm/headless` `Terminal` into a small pluggable surface the
+ * worker stores per session. This is the new source of truth for the `read`
+ * snapshot: a stable `cols×rows` character grid, the REAL cursor
+ * (`buffer.active.cursorX/cursorY`), and the REAL alt-screen flag
+ * (`buffer.active.type === "alternate"`) — REPLACING the earlier raw stdout-ring
+ * snapshot. Full-screen TUIs (`vim`/`htop`) draw into a stable grid; the agent
+ * must perceive that grid, not a raw byte log.
+ *
+ * The emulator is extracted into this module (not inlined in the worker) so the
+ * worker stays under the 800-line architecture cap — the heavy @xterm
+ * integration lives here.
+ *
+ * Render formats (§2.4): `snapshot({format})` returns the plain grid
+ * (`text`, default), the ansi-with-SGR serialization (`ansi` via the
+ * SerializeAddon's `serialize()`), or an HTML fragment (`html` via
+ * `serializeAsHTML()`). `snapshot({scrollback:N})` includes the N retained rows
+ * ABOVE the viewport (perception beyond the fold). Per §11 the
+ * addon-serialize dep is pinned (0.14.0) + golden-frame tested against
+ * churn.
+ *
+ * Perception signals: `hasContentBelowFold()` is the "more content below
+ * the fold ⇒ NOT settled" rendering signal the settle composes (a still-scrolling
+ * frame is not marked idle); `diffSnapshot(prev, next)` is the per-read
+ * screen-diff (a changed flag + changed-row range) so the agent / the
+ * classifier can cheaply see what changed without re-diffing whole grids.
+ *
+ * §2.4 flush primitive: `@xterm`'s `term.write(data, cb)` is ASYNC-PARSED — the
+ * callback fires once the chunk is fully parsed into the buffer. `write` here
+ * returns a Promise that resolves on that callback, so the worker can `await`
+ * the parse before serializing a SETTLED frame (the "debounce → serialize once
+ * stable" discipline — a snapshot taken before the parse completes would lag the
+ * bytes). The settle's idle debounce already waits for quiet; awaiting the
+ * write-flush guarantees the grid reflects every emitted byte.
+ *
+ * Architecture invariants: NO module-global mutable state (everything is local to
+ * the returned object); NO `@comis/infra` import; NO raw timers / clock / env
+ * (the globals gate). A pure, injectable wrapper.
+ *
+ * @module
+ */
+import { createRequire } from "node:module";
+const xtermRequire = createRequire(import.meta.url);
+const { Terminal } = xtermRequire("@xterm/headless");
+const { SerializeAddon } = xtermRequire("@xterm/addon-serialize");
+/**
+ * Read one viewport row's cells (chars + SGR-2 `dim` + display width) — the structured input a
+ * read-side profile `transformSnapshot` needs (the flat `screen` string loses `dim`). Mirrors the
+ * cell-attribute extraction `translateToString` would do, exposing the per-cell `dim` flag.
+ */
+function readRowCells(line) {
+    const cells = [];
+    if (line === undefined)
+        return cells;
+    for (let x = 0; x < line.length; x++) {
+        const cell = line.getCell(x);
+        // xterm's cell attribute getters return a number (0/non-0), not boolean — coerce.
+        cells.push(cell
+            ? { chars: cell.getChars(), dim: cell.isDim() !== 0, width: cell.getWidth() }
+            : { chars: "", dim: false, width: 1 });
+    }
+    return cells;
+}
+export function createSessionEmulator(opts) {
+    const transformSnapshot = opts.transformSnapshot;
+    const term = new Terminal({
+        cols: opts.cols,
+        rows: opts.rows,
+        scrollback: opts.scrollback,
+        allowProposedApi: true,
+    });
+    // The SerializeAddon backs the `ansi`/`html` formats. Loaded once at
+    // construction; `serialize()`/`serializeAsHTML()` read the buffer on demand.
+    // Pinned 0.14.0 + golden-frame tested against addon churn (§11).
+    const serializeAddon = new SerializeAddon();
+    term.loadAddon(serializeAddon);
+    let disposed = false;
+    /**
+     * Read the grid as plain text. The viewport rows are
+     * `getLine(baseY + y)?.translateToString(true)` for `y` in `0..rows-1` (read
+     * via `baseY` so the viewport is correct even when scrollback has accumulated).
+     * When `scrollback > 0`, the off-screen rows ABOVE the viewport
+     * (`max(0, baseY - scrollback) .. baseY - 1`) are prepended (the scrollback perception).
+     */
+    function readText(scrollback) {
+        const buf = term.buffer.active;
+        const lines = [];
+        if (scrollback > 0) {
+            const from = Math.max(0, buf.baseY - scrollback);
+            for (let i = from; i < buf.baseY; i++) {
+                lines.push(buf.getLine(i)?.translateToString(true) ?? "");
+            }
+        }
+        // The AGNOSTIC grid: every viewport row is the plain `translateToString(true)` — no platform
+        // transforms (RENDER-01 / INV-1). A profile's read-side `transformSnapshot` (e.g. the Claude
+        // ghost-strip) is applied later, in `snapshot()`, using the cell `grid` — never woven in here.
+        for (let y = 0; y < term.rows; y++) {
+            lines.push(buf.getLine(buf.baseY + y)?.translateToString(true) ?? "");
+        }
+        return lines.join("\n");
+    }
+    /**
+     * Build the viewport cell grid (rows × cells) for a read-side profile transform. Read on demand
+     * (text format + a wired transform only) so the agnostic path pays nothing (INV-1).
+     */
+    function readViewportGrid() {
+        const buf = term.buffer.active;
+        const grid = [];
+        for (let y = 0; y < term.rows; y++) {
+            grid.push(readRowCells(buf.getLine(buf.baseY + y)));
+        }
+        return grid;
+    }
+    /**
+     * Encode the `screen` for the requested format. `ansi` → `serialize()` (SGR
+     * preserved); `html` → `serializeAsHTML()`; `text` → the plain grid. The
+     * SerializeAddon's `scrollback` option includes off-screen rows for ansi/html
+     * (both call shapes are valid — `serializeAsHTML` options are `Partial<>`).
+     */
+    function renderScreen(format, scrollback) {
+        if (format === "ansi") {
+            return serializeAddon.serialize(scrollback > 0 ? { scrollback } : {});
+        }
+        if (format === "html") {
+            return serializeAddon.serializeAsHTML(scrollback > 0 ? { scrollback } : {});
+        }
+        return readText(scrollback);
+    }
+    return {
+        term,
+        write(data) {
+            // The callback is the §2.4 parse-complete flush — resolve on it (NOT on
+            // write's synchronous return) so the worker's await genuinely waits for the
+            // grid to reflect the bytes.
+            return new Promise((resolve) => {
+                term.write(data, resolve);
+            });
+        },
+        snapshot(opts) {
+            const buf = term.buffer.active;
+            const format = opts?.format ?? "text";
+            const scrollback = opts?.scrollback ?? 0;
+            const base = {
+                screen: renderScreen(format, scrollback),
+                cursor: { x: buf.cursorX, y: buf.cursorY },
+                cols: term.cols,
+                rows: term.rows,
+                alt: buf.type === "alternate",
+            };
+            // Apply the selected profile's read-side transform (RENDER-01) AFTER the agnostic snapshot.
+            // ONLY for `text` (the sole format whose `screen` is the plain row grid the transform rewrites)
+            // and ONLY when a transform is wired — the engine attaches the viewport cell `grid` so the
+            // transform can read cell attributes (`dim`) the flat `screen` lost. No transform / non-text ⇒
+            // the plain grid is returned untouched (INV-1). The engine stays platform-agnostic: it applies
+            // a generic hook, never a Claude-specific branch.
+            if (transformSnapshot !== undefined && format === "text") {
+                return transformSnapshot({ ...base, grid: readViewportGrid() });
+            }
+            return base;
+        },
+        resize(cols, rows) {
+            term.resize(cols, rows);
+        },
+        hasContentBelowFold() {
+            // `viewportY` is the DISPLAYED viewport-top line index (it tracks scroll);
+            // `length` is the total buffer lines. Content sits below the displayed fold
+            // when the displayed `rows` rows do not reach the buffer bottom. (NOTE: we
+            // use `viewportY`, NOT `baseY` — in @xterm/headless `baseY` is the
+            // cursor-anchored bottom-viewport index and does NOT move when the display
+            // scrolls up, so `baseY + rows` always equals `length` after settled output
+            // and would never detect a below-fold frame.) On the alternate buffer the
+            // app owns the full screen with no scrollback below, so `viewportY` is 0 and
+            // `length === rows` ⇒ correctly false.
+            const buf = term.buffer.active;
+            return buf.viewportY + term.rows < buf.length;
+        },
+        dispose() {
+            if (disposed)
+                return;
+            disposed = true;
+            term.dispose();
+        },
+    };
+}
+/**
+ * Diff two snapshots' `screen` text line-by-line. A pure helper (no
+ * emulator access) so the worker can cheaply compare two snapshots and tell the
+ * agent / the classifier "did anything change" without re-diffing whole grids.
+ *
+ * `prev === undefined` ⇒ `changed:true` over the full range (the first read).
+ * Otherwise the line arrays are compared: `changed` is true when they differ;
+ * `firstChangedRow`/`lastChangedRow` bound the differing lines (both `-1` when
+ * unchanged). Lines present in only one snapshot count as changed (the longer
+ * array's extra indices extend the range).
+ *
+ * @param prev - The previous snapshot, or `undefined` for the first read.
+ * @param next - The current snapshot.
+ * @returns The {@link SnapshotDiff}.
+ */
+export function diffSnapshot(prev, next) {
+    const nextLines = next.screen.split("\n");
+    if (prev === undefined) {
+        return { changed: true, firstChangedRow: 0, lastChangedRow: Math.max(0, nextLines.length - 1) };
+    }
+    const prevLines = prev.screen.split("\n");
+    const max = Math.max(prevLines.length, nextLines.length);
+    let first = -1;
+    let last = -1;
+    for (let i = 0; i < max; i++) {
+        if (prevLines[i] !== nextLines[i]) {
+            if (first === -1)
+                first = i;
+            last = i;
+        }
+    }
+    return { changed: first !== -1, firstChangedRow: first, lastChangedRow: last };
+}
+/**
+ * Parse the `read` frame params into {@link SnapshotOptions}. `format` is
+ * validated to one of `text|ansi|html` (anything else → `text`); `scrollback` is
+ * a non-negative number (anything else → `0`). Kept here so the worker stays
+ * under the 800-line cap. `includeAltBuffer` is ignored for now — alt is captured
+ * by default per §2.4; an explicit alt-exclude is out of scope.
+ *
+ * @param params - The decoded read-frame params (`frame.params`).
+ * @returns The validated `{format, scrollback}` snapshot options.
+ */
+export function readSnapshotParams(params) {
+    const rawFormat = params["format"];
+    const format = rawFormat === "ansi" || rawFormat === "html" || rawFormat === "text" ? rawFormat : "text";
+    const rawScrollback = params["scrollback"];
+    const scrollback = typeof rawScrollback === "number" && rawScrollback > 0 ? rawScrollback : 0;
+    return { format, scrollback };
+}
+/**
+ * Assemble the worker's `read` reply from an emulator snapshot + the session
+ * context. When `snap` is present (the live emulator-backed path) it is the SOLE
+ * source for `screen`/`cursor`/`cols`/`rows`/`alt`; when absent (emulator not
+ * constructed) the raw `ring` + recorded geometry + `{0,0}` cursor is the
+ * degraded fallback — NOT a dual path on the live backend. `alive` always comes
+ * from the session context.
+ *
+ * @param snap - The emulator snapshot, or `undefined` when no emulator exists.
+ * @param ctx - The session ring/geometry/liveness fallback.
+ * @returns The `{screen,cursor,cols,rows,alt,alive}` read view.
+ */
+export function buildReadResult(snap, ctx) {
+    return {
+        screen: snap?.screen ?? ctx.ring,
+        cursor: snap?.cursor ?? { x: 0, y: 0 },
+        cols: snap?.cols ?? ctx.cols,
+        rows: snap?.rows ?? ctx.rows,
+        alt: snap?.alt ?? false,
+        alive: ctx.alive,
+    };
+}
+/** Bound for the raw-ring fallback when no emulator snapshot exists (degraded pipe backend). */
+const PERCEPTION_RING_TAIL = 8192;
+/**
+ * The post-action perception screen for `send_key`/`send_text`/`wait` results: the
+ * emulator's PLAIN grid snapshot (ANSI-free viewport + real cursor) — NEVER the raw,
+ * accumulating ANSI `ring`. The raw ring routinely exceeds the 100K tool-result
+ * offload cap (a full-screen TUI's byte-log), which offloads the result and BLINDS a
+ * driving agent to the settled grid (`read` already uses the snapshot via
+ * {@link buildReadResult}; these three handlers wrongly returned the ring). When the
+ * emulator is absent (the degraded pipe backend) it falls back to the bounded TAIL of
+ * the ring, so the result still never offloads.
+ */
+export function perceptionScreen(snap, ring) {
+    if (snap !== undefined)
+        return { screen: snap.screen, cursor: snap.cursor };
+    return {
+        screen: ring.length > PERCEPTION_RING_TAIL ? ring.slice(-PERCEPTION_RING_TAIL) : ring,
+        cursor: { x: 0, y: 0 },
+    };
+}

package/node_modules/@comis/skills/dist/tools/builtin/terminal-driver/terminal-scope-args.d.ts

@@ -0,0 +1,94 @@
+/**
+ * buildScopeArgs -- materialize a {@link TerminalScope} into the exact bwrap argv
+ * (filesystem/network/uid + credentialPaths + the ~/.comis carve-out).
+ *
+ * This is THE central scope -> jail mapping. It is MODELED on
+ * `BwrapProvider.buildArgs` (`sandbox/bwrap-provider.ts:140-224`) but is a
+ * SEPARATE composer: that method is hardwired to the daemon-exec profile (it
+ * binds the daemon's HOME dotfiles `~/.gitconfig`/`~/.local`/`~/.nvm`
+ * unconditionally, `:168,186`) and is shared with the exec path; adding
+ * terminal-scope branches there would couple two trust models and risk an exec
+ * regression. This composer REUSES `SYSTEM_RO_PATHS` verbatim for the RO base and
+ * emits the net-new `--uid`/`--gid` (proven on the VPS) + the
+ * always-on carve-out.
+ *
+ * It is a PURE function (no `os`/`fs` side effects — `home`/`dataDir`/the resolved
+ * `systemRoPaths` are injected), so the full scope->argv matrix is macOS-testable
+ * WITHOUT spawning bwrap (the `bwrap-secure-profile.test.ts` idiom). The actual
+ * jail enforcement is the VPS suite, which builds the argv via THIS
+ * composer so the test proves the real mapping.
+ *
+ * Returns `[bwrapPath, ...args, "--"]`; the caller appends `bin, ...argv`
+ * (`pty.spawn(scopeArgs[0], [...scopeArgs.slice(1), bin, ...argv])`).
+ *
+ * @module
+ */
+import { SYSTEM_RO_PATHS } from "../sandbox/bwrap-provider.js";
+import type { TerminalScope } from "./allowlist-matcher.js";
+export { SYSTEM_RO_PATHS };
+/**
+ * The composer input: the scope plus its jail companions (workspace/cwd/home/
+ * dataDir/the resolved system RO set) and the two net-new dimensions
+ * (dedicatedUid + the egress relay socket).
+ */
+export interface ScopeArgsInput {
+    /** The operator-declared scope — sourced only from `matched.entry`. */
+    scope: TerminalScope;
+    /** The resolved bwrap binary path (from the provider). */
+    bwrapPath: string;
+    /** The session workspace — always `--bind` RW. */
+    workspace: string;
+    /** The `--chdir` target. */
+    cwd: string;
+    /** Injected `os.homedir()` — TESTABLE (the home bind + the ~/.claude/.comis roots). */
+    home: string;
+    /** The carve-out target — `os.homedir()/.comis` (non-configurable). */
+    dataDir: string;
+    /** `SYSTEM_RO_PATHS`, filtered to existing by the caller (the provider resolves them once). */
+    systemRoPaths: readonly string[];
+    /** The net-new uid/gid (e.g. `{uid:65534,gid:65534}` = nobody) when `scope.uid === "dedicated"`. */
+    dedicatedUid?: {
+        uid: number;
+        gid: number;
+    };
+    /** The egress relay socket to bind-mount — present ONLY when `scope.network === "listed-hosts"`. */
+    relaySocketPath?: string;
+    /**
+     * The on-disk relay-as-init SCRIPT the in-jail `node` execs — RO-bound into the
+     * jail so node can READ it (the worker spawns `bwrap [scope] -- node <this> -- bin`).
+     * Present ONLY for `scope.network === "listed-hosts"` (supplied by `buildSpawnPlan`
+     * from `buildEgressRelayLaunch().relayInitScriptPath`). The file exists on the HOST
+     * but is NOT covered by SYSTEM_RO_PATHS or the workspace bind, so without this
+     * `--ro-bind` the jail dies with `Cannot find module …/egress-relay-init.js`
+     * (the last VPS scope-matrix egress-cell failure). none/full never run the
+     * relay, so this is unset for them.
+     */
+    relayInitScriptPath?: string;
+    /**
+     * Extra env KEY NAMES to `--unsetenv` BEYOND the fixed {@link JAIL_UNSET_ENV_VARS}
+     * (interpreter-control + CLAUDECODE). The caller (`terminal-spawn-plan`) passes the
+     * concrete daemon-secret keys present in the live env (`secretEnvKeysIn` — the
+     * gateway-token family / master key). bwrap `--unsetenv` is name-only, so a prefix
+     * family (`GATEWAY_TOKEN_*`) must arrive here as enumerated concrete names; this is
+     * what protects the DEFAULT tmux/durable backend, which inherits the tmux SERVER env
+     * and bypasses the `scrubChildEnv` object (TERM-ENV-GATEWAY-TOKEN-LEAK). Order- and
+     * duplicate-insensitive (deduped against the fixed list before emit).
+     */
+    extraUnsetEnvKeys?: readonly string[];
+}
+/**
+ * Build the bwrap argv for a {@link TerminalScope}, in the canonical order:
+ *
+ *   [bwrapPath, ...systemRO(--ro-bind p p), --proc, --dev, --dev-bind /dev/pts,
+ *    --tmpfs /tmp, <FS binds>, <credentialPaths ro-bind-try>, <uid>,
+ *    --unshare-all, <network>, --die-with-parent, --new-session, --chdir <cwd>,
+ *    <CARVE-OUT --tmpfs <dataDir>>, <workspace re-bind if under dataDir>, --]
+ *
+ * `--unshare-all` already supplies `--unshare-pid` + `--unshare-user` + ipc/uts/
+ * cgroup — no separate `--unshare-pid`. `--new-session` is emitted
+ * explicitly for the controlling tty. The `<network>` refinement comes AFTER
+ * `--unshare-all` — bwrap mutates its unshare set per flag IN ARG ORDER, so a
+ * `--share-net` emitted before the unshare-all would be re-clobbered and the
+ * jail would get NO network even at `network:"full"` (the live-VPS T5 bug).
+ */
+export declare function buildScopeArgs(input: ScopeArgsInput): string[];

package/node_modules/@comis/skills/dist/tools/builtin/terminal-driver/terminal-scope-args.js

@@ -0,0 +1,261 @@
+// SPDX-License-Identifier: Apache-2.0
+// @allow-throw: exhaustiveness guards on the filesystem + network unions; unreachable at runtime, caught by TypeScript; equivalent to assertNever().
+/**
+ * buildScopeArgs -- materialize a {@link TerminalScope} into the exact bwrap argv
+ * (filesystem/network/uid + credentialPaths + the ~/.comis carve-out).
+ *
+ * This is THE central scope -> jail mapping. It is MODELED on
+ * `BwrapProvider.buildArgs` (`sandbox/bwrap-provider.ts:140-224`) but is a
+ * SEPARATE composer: that method is hardwired to the daemon-exec profile (it
+ * binds the daemon's HOME dotfiles `~/.gitconfig`/`~/.local`/`~/.nvm`
+ * unconditionally, `:168,186`) and is shared with the exec path; adding
+ * terminal-scope branches there would couple two trust models and risk an exec
+ * regression. This composer REUSES `SYSTEM_RO_PATHS` verbatim for the RO base and
+ * emits the net-new `--uid`/`--gid` (proven on the VPS) + the
+ * always-on carve-out.
+ *
+ * It is a PURE function (no `os`/`fs` side effects — `home`/`dataDir`/the resolved
+ * `systemRoPaths` are injected), so the full scope->argv matrix is macOS-testable
+ * WITHOUT spawning bwrap (the `bwrap-secure-profile.test.ts` idiom). The actual
+ * jail enforcement is the VPS suite, which builds the argv via THIS
+ * composer so the test proves the real mapping.
+ *
+ * Returns `[bwrapPath, ...args, "--"]`; the caller appends `bin, ...argv`
+ * (`pty.spawn(scopeArgs[0], [...scopeArgs.slice(1), bin, ...argv])`).
+ *
+ * @module
+ */
+import { SYSTEM_RO_PATHS } from "../sandbox/bwrap-provider.js";
+import { JAIL_UNSET_ENV_VARS } from "./terminal-env-scrub.js";
+// Re-export so consumers can `import { SYSTEM_RO_PATHS } from "./terminal-scope-args.js"`
+// alongside the composer — but the composer itself uses it as the RO base by default.
+export { SYSTEM_RO_PATHS };
+/** Push a `--proc /proc`, `--dev /dev`, `--dev-bind /dev/pts`, `--tmpfs /tmp` block. */
+function pushSpecialFs(args) {
+    args.push("--proc", "/proc");
+    args.push("--dev", "/dev");
+    args.push("--dev-bind", "/dev/pts", "/dev/pts"); // PTY slave devices (the controlling tty)
+    args.push("--tmpfs", "/tmp");
+}
+/**
+ * Emit the filesystem binds for the scope's `filesystem` dimension.
+ *
+ * For `full`, after the broad host bind RE-EMIT the special filesystems
+ * (`pushSpecialFs`) so the root bind cannot clobber `--proc`/`--dev`/`/tmp`.
+ * The `~/.comis` carve-out is appended by the CALLER as the
+ * very last mount so it wins even over `--bind / /`.
+ */
+function pushFilesystemBinds(args, input) {
+    const { scope, workspace, home } = input;
+    // The workspace is ALWAYS bound RW (the session's working dir).
+    args.push("--bind", workspace, workspace);
+    switch (scope.filesystem) {
+        case "workspace":
+            // workspace-only (+ the system RO base). Do NOT bind dotfiles — that is the
+            // exec profile (bwrap-provider.ts:168,186), a different trust model.
+            break;
+        case "listed-paths":
+            for (const p of scope.paths ?? []) {
+                args.push("--bind", p, p);
+            }
+            break;
+        case "home":
+            args.push("--bind", home, home);
+            break;
+        case "full":
+            // Broad host fs. `--bind / /` exposes everything incl. /proc, /dev, /tmp —
+            // so re-emit the special filesystems AFTER so the root bind cannot shadow
+            // them, and the caller appends the ~/.comis carve-out LAST.
+            args.push("--bind", "/", "/");
+            pushSpecialFs(args);
+            break;
+        default: {
+            const _exhaustive = scope.filesystem;
+            throw new Error(`Unhandled filesystem scope: ${String(_exhaustive)}`);
+        }
+    }
+}
+/**
+ * Emit the network flag for the scope's `network` dimension.
+ *
+ * - `none` (default) -> `--unshare-net` (kernel-enforced netns, NO socket, NO proxy).
+ * - `listed-hosts` -> `--unshare-net` + `--bind <relaySocketPath>` (the egress
+ *   proxy socket) + `--ro-bind <relayInitScriptPath>` (the in-jail relay-as-init
+ *   script node execs — it must be readable INSIDE the jail; the relay launch).
+ *   Mirrors the exec `broker-only` socket bind, but the socket is the egress proxy,
+ *   not a broker. WITHOUT the script ro-bind the jail dies `Cannot find module
+ *   …/egress-relay-init.js` (the file is on the HOST but unbound).
+ * - `full` -> `--share-net` (host network, no proxy).
+ */
+function pushNetwork(args, input) {
+    switch (input.scope.network) {
+        case "none":
+            args.push("--unshare-net");
+            break;
+        case "listed-hosts":
+            args.push("--unshare-net");
+            if (input.relaySocketPath !== undefined) {
+                args.push("--bind", input.relaySocketPath, input.relaySocketPath);
+            }
+            // The in-jail relay-as-init script must be READABLE inside the jail (in-jail
+            // node execs it). Bind it RO at the same host path. Only for listed-hosts —
+            // none/full never spawn the relay (the VPS Cannot-find-module fix).
+            if (input.relayInitScriptPath !== undefined) {
+                args.push("--ro-bind", input.relayInitScriptPath, input.relayInitScriptPath);
+            }
+            break;
+        case "full":
+            args.push("--share-net");
+            break;
+        default: {
+            const _exhaustive = input.scope.network;
+            throw new Error(`Unhandled network scope: ${String(_exhaustive)}`);
+        }
+    }
+}
+/**
+ * True when `child` is a STRICT subpath of `parent` (segment-aware via a trailing
+ * separator, so `/a/.comis-evil` is NOT under `/a/.comis`). Deliberately false when
+ * `child === parent`: re-binding the data dir onto ITSELF would re-expose the
+ * secrets the carve-out exists to mask, so only a NESTED workspace is re-exposed.
+ */
+function isUnderDir(child, parent) {
+    const withSep = parent.endsWith("/") ? parent : `${parent}/`;
+    return child.startsWith(withSep);
+}
+/**
+ * Build the bwrap argv for a {@link TerminalScope}, in the canonical order:
+ *
+ *   [bwrapPath, ...systemRO(--ro-bind p p), --proc, --dev, --dev-bind /dev/pts,
+ *    --tmpfs /tmp, <FS binds>, <credentialPaths ro-bind-try>, <uid>,
+ *    --unshare-all, <network>, --die-with-parent, --new-session, --chdir <cwd>,
+ *    <CARVE-OUT --tmpfs <dataDir>>, <workspace re-bind if under dataDir>, --]
+ *
+ * `--unshare-all` already supplies `--unshare-pid` + `--unshare-user` + ipc/uts/
+ * cgroup — no separate `--unshare-pid`. `--new-session` is emitted
+ * explicitly for the controlling tty. The `<network>` refinement comes AFTER
+ * `--unshare-all` — bwrap mutates its unshare set per flag IN ARG ORDER, so a
+ * `--share-net` emitted before the unshare-all would be re-clobbered and the
+ * jail would get NO network even at `network:"full"` (the live-VPS T5 bug).
+ */
+export function buildScopeArgs(input) {
+    const args = [input.bwrapPath];
+    // -- System paths (read-only, reused verbatim from BwrapProvider) --
+    for (const sysPath of input.systemRoPaths) {
+        args.push("--ro-bind", sysPath, sysPath);
+    }
+    // -- Special filesystems --
+    pushSpecialFs(args);
+    // -- Filesystem binds (the scope.filesystem dimension; workspace always bound) --
+    pushFilesystemBinds(args, input);
+    // -- credentialPaths: RO-bind each operator-listed credential path so the driven CLI sees
+    //    its own creds/config. TOOL-AGNOSTIC (no hardcoded ~/.claude): the operator lists what
+    //    to expose (~/.claude[.json] for Claude, ~/.codex for Codex, ~/.gemini for Gemini, …).
+    //    `~`/`~/` expands to home; `--ro-bind-try` skips a not-yet-created path (e.g. a first-run
+    //    trust file) instead of failing the spawn. Empty list (the default) binds nothing.
+    for (const credPath of input.scope.credentialPaths) {
+        if (credPath.length === 0)
+            continue;
+        const expanded = credPath === "~"
+            ? input.home
+            : credPath.startsWith("~/")
+                ? `${input.home}${credPath.slice(1)}`
+                : credPath;
+        args.push("--ro-bind-try", expanded, expanded);
+    }
+    // -- uid: a net-new uid != the daemon at the default (dedicated) --
+    if (input.scope.uid === "dedicated" && input.dedicatedUid !== undefined) {
+        args.push("--uid", String(input.dedicatedUid.uid));
+        args.push("--gid", String(input.dedicatedUid.gid));
+    }
+    // -- Isolation flags (--unshare-all => --unshare-pid/--unshare-user + ipc/uts/cgroup) --
+    args.push("--unshare-all");
+    // -- Network (the scope.network dimension) — MUST come AFTER --unshare-all --
+    //    bwrap processes namespace flags SEQUENTIALLY (each mutates the unshare set in
+    //    arg order), so a `--share-net` emitted BEFORE `--unshare-all` is re-clobbered
+    //    by the later unshare-all and the jail gets NO network even at network:"full"
+    //    (proven live on the VPS: curl 000 vs 404 by flag order alone). Emitting the
+    //    network refinement after the namespace base makes `--share-net` retain the
+    //    host netns; the `none`/`listed-hosts` `--unshare-net` is order-insensitive
+    //    (unshare twice = unshare) but rides here for one coherent rule.
+    pushNetwork(args, input);
+    args.push("--die-with-parent");
+    args.push("--new-session"); // controlling tty
+    // -- Working directory --
+    args.push("--chdir", input.cwd);
+    // -- Env hardening (BACKEND-INDEPENDENT) -- emitted as bwrap flags (NOT mounts, so placed BEFORE
+    //    the carve-out/workspace re-bind that must stay the LAST mounts) so they apply whether the
+    //    worker spawns bwrap directly (PTY backend: env via `pty.spawn({env})`) OR via `tmux
+    //    new-session -- bwrap …` (the DEFAULT durable backend, where the new session inherits the tmux
+    //    SERVER env, BYPASSING the worker's scrubbed env object — real-VPS 2026-06-17: the daemon's
+    //    `NODE_OPTIONS=--permission …` leaked into a driven claude AND CLAUDE_CODE_BUBBLEWRAP never
+    //    reached it → its Bash/SessionStart hook EROFS'd on the default backend). `--unsetenv` strips
+    //    the daemon's interpreter-control hardening (NODE_OPTIONS, BASH_ENV, …) + the CLAUDECODE
+    //    sentinel; `--setenv CLAUDE_CODE_BUBBLEWRAP=1` (EROFS-01) tells the driven CLI it is already
+    //    bubblewrapped so it does NOT nest its own (nested-broken) sandbox. The PTY-path `env` scrub
+    //    (`scrubChildEnv`) stays as defense-in-depth; this is the authoritative, backend-independent
+    //    application.
+    //    The fixed interpreter-control/CLAUDECODE names ALWAYS unset; the caller-supplied
+    //    daemon-secret names (the gateway-token family / master key present in the live env —
+    //    TERM-ENV-GATEWAY-TOKEN-LEAK) are deduped in so the tmux backend strips them too.
+    const unsetEnvKeys = new Set([...JAIL_UNSET_ENV_VARS, ...(input.extraUnsetEnvKeys ?? [])]);
+    for (const key of unsetEnvKeys) {
+        args.push("--unsetenv", key);
+    }
+    args.push("--setenv", "CLAUDE_CODE_BUBBLEWRAP", "1");
+    // -- claude session-env carve-out (EROFS-03) -- a writable tmpfs at <home>/.claude/session-env.
+    //    claude's OWN bash sandbox remounts $HOME read-only IN-PLACE before `mkdir ~/.claude/
+    //    session-env/<id>` (its per-bash-command state) → EROFS on the default durable backend in the
+    //    prod seccomp'd daemon (CLAUDE_CODE_BUBBLEWRAP does NOT suppress that remount there — it only
+    //    appeared to on a non-seccomp socket). A SEPARATE sub-mount survives the in-place parent
+    //    remount, so the mkdir lands on a rw tmpfs → claude's Bash tool runs (live-proven 2026-06-17,
+    //    seccomp'd daemon, `--permission-mode bypassPermissions`). Ephemeral + per-jail; claude's
+    //    creds/config under ~/.claude stay intact (only the transient session-env subdir is the
+    //    tmpfs). Placed BEFORE the ~/.comis mask so that mask + the workspace re-bind stay the LAST
+    //    mounts. Harmless for a non-claude CLI (an unused empty tmpfs at a path it never touches).
+    //
+    //    SKIP it when an operator credentialPath RO-binds the carve-out's PARENT
+    //    (<home>/.claude, or an ancestor like ~): bwrap then cannot mkdir the
+    //    session-env mountpoint inside the read-only subtree and the WHOLE jail
+    //    fails to launch ("Can't mkdir …/.claude/session-env: Read-only file
+    //    system" — live-reproduced on the VPS). A writable subdir cannot exist in a
+    //    RO bind anyway, so the RO-cred operator opt-in takes precedence over the
+    //    carve-out (claude's per-bash session-env then falls back to its own EROFS
+    //    handling, no worse than without the carve-out).
+    const sessionEnvParent = `${input.home}/.claude`;
+    const carveOutParentIsRoBound = input.scope.credentialPaths.some((credPath) => {
+        if (credPath.length === 0)
+            return false;
+        const expanded = credPath === "~"
+            ? input.home
+            : credPath.startsWith("~/")
+                ? `${input.home}${credPath.slice(1)}`
+                : credPath;
+        return sessionEnvParent === expanded || isUnderDir(sessionEnvParent, expanded);
+    });
+    if (!carveOutParentIsRoBound) {
+        args.push("--tmpfs", `${input.home}/.claude/session-env`);
+    }
+    // -- The ~/.comis carve-out LAST -- later bwrap mount wins (the bind-order
+    //    insight); even at filesystem:full (--bind / / | --bind <home>) ~/.comis is
+    //    shadowed by this tmpfs, so the master key / secret store / runtime is denied
+    //    to EVERY driven child regardless of scope (non-configurable, not a scope field).
+    args.push("--tmpfs", input.dataDir);
+    // -- Agent-workspace persistence -- the carve-out above masks ALL of <dataDir>,
+    //    which also shadows the session workspace when it IS the agent's OWN workspace
+    //    (the default `<dataDir>/workspace/<agent>`, the same dir the agent's read/
+    //    write/exec tools operate on). Re-bind ONLY that subpath RW on top of the
+    //    tmpfs so the workspace is writable + PERSISTENT in the jail (a driven GSD
+    //    milestone's work survives), while the secrets at sibling <dataDir> paths
+    //    (secret.db / .env / config.yaml / memory.db) stay shadowed. A workspace
+    //    OUTSIDE <dataDir> (e.g. an operator-relocated dir) needs no re-bind — its
+    //    earlier `pushFilesystemBinds` mount is never masked. `isUnderDir` is strict
+    //    (workspace === dataDir is NOT re-exposed → re-binding ~/.comis onto itself
+    //    would defeat the carve-out).
+    if (isUnderDir(input.workspace, input.dataDir)) {
+        args.push("--bind", input.workspace, input.workspace);
+    }
+    // The caller appends `bin, ...argv` after the terminator.
+    args.push("--");
+    return args;
+}