toolroll 0.5.0

package/dist/exec.js

@@ -0,0 +1,1841 @@
+/**
+ * Running external commands.
+ *
+ * Two rules define this module. Arguments are passed as an array and never
+ * through a shell, so a directory named `; rm -rf ~` is a string and not a
+ * command. And nothing here rejects: a failed command is a value. Discovery
+ * walks repos it has never seen, and one broken repo must not end the scan.
+ */
+import { linuxFenceAvailable, linuxFenced, macosFenceAvailable, macosFenced } from "./agent-fence.js";
+import { execFile, spawn } from "node:child_process";
+import { realpathSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { observeProcessTree, stopProcessTree, readProcessObservationFailure } from "./process-tree.js";
+import { jsonlDiscriminants } from "./jsonl-discriminants.js";
+import { createContainer, currentContainment } from "./containment.js";
+import { claudeLimitsOf, noteLimits } from "./provider-limits.js";
+/** Shell convention for "could not be executed": the refusal before any target ran. */
+export const CONTAINMENT_REFUSED_CODE = 126;
+/** Live provider children, for the deterministic stop. Registered only when `processGroup` was set. */
+const liveProviders = new Set();
+/** Live children by owner tag (v52): the exact-attempt stop's handle. A
+ * child is registered here beside liveProviders when its options named an
+ * owner, and dropped the moment it closes. */
+const ownedChildren = new Map();
+function registerOwned(owner, child) {
+    if (owner === undefined)
+        return;
+    let set = ownedChildren.get(owner);
+    if (set === undefined) {
+        set = new Set();
+        ownedChildren.set(owner, set);
+    }
+    set.add(child);
+    child.once("close", () => {
+        const owned = ownedChildren.get(owner);
+        if (owned === undefined)
+            return;
+        owned.delete(child);
+        if (owned.size === 0)
+            ownedChildren.delete(owner);
+    });
+}
+/** The native OS object behind a live child, when it has one. */
+const containers = new WeakMap();
+/** Thrown BEFORE any spawn when required containment cannot be had. */
+export class ContainmentRefusal extends Error {
+    name = "ContainmentRefusal";
+}
+/** A spawn callback refused custody AFTER the child existed: the caller
+ * must reap exactly this child before answering. */
+class SpawnCustodyFailure extends Error {
+    child;
+    reason;
+    name = "SpawnCustodyFailure";
+    constructor(child, reason) {
+        super(String(reason));
+        this.child = child;
+        this.reason = reason;
+    }
+}
+/** The child a failed spawn road left behind, if any. */
+function rejectedChild(error, child) {
+    return error instanceof SpawnCustodyFailure ? error.child : child;
+}
+/**
+ * The ONE spawn road for containable children (buffered, streaming and
+ * held transports): consult the pinned policy, make this spawn's OS
+ * object, spawn the target INSIDE it, and register the object beside the
+ * handle. Under observed containment this is exactly the old spawn. A
+ * required policy that cannot be met throws ContainmentRefusal here —
+ * nothing has been spawned, so the caller's reap is a no-op and its
+ * result says `refused` in the policy's words.
+ */
+function spawnContained(file, args, spawnOptions, label, bag, contain = true) {
+    // The agent fence wraps the target itself (sandbox-exec then execs it, same pid).
+    if (bag.fence !== undefined && bag.fence.length > 0 && macosFenceAvailable())
+        ({ file, args } = macosFenced(file, args, bag.fence));
+    else if (bag.fence !== undefined && bag.fence.length > 0 && linuxFenceAvailable())
+        ({ file, args } = linuxFenced(file, args, bag.fence));
+    // The policy refusal comes first: nothing is reserved, recorded or
+    // spawned for a spawn that cannot be contained as required.
+    const effective = contain ? currentContainment() : null;
+    if (effective !== null && effective.refusal !== null)
+        throw new ContainmentRefusal(effective.refusal);
+    if (bag.beforeSpawn?.() === false)
+        throw new Error("the attempt stopped before this process could spawn");
+    const made = effective === null ? { container: null } : createContainer(effective, label);
+    if ("refused" in made)
+        throw new ContainmentRefusal(made.refused);
+    const container = made.container;
+    try {
+        if (container !== null)
+            bag.onContainer?.({ backend: container.backend, id: container.id, ...(container.identity ? { identity: container.identity } : {}) });
+    }
+    catch (error) {
+        container?.release();
+        throw error;
+    }
+    let launch;
+    try {
+        launch = container === null ? null : container.launch(file, args);
+    }
+    catch (error) {
+        container?.release();
+        throw error;
+    }
+    let child;
+    try {
+        child = spawn(launch === null ? file : launch.file, launch === null ? [...args] : launch.args, {
+            shell: false,
+            windowsHide: true,
+            detached: spawnOptions.detached,
+            stdio: [...spawnOptions.stdio, ...(launch === null ? [] : launch.extraStdio)],
+            ...(spawnOptions.cwd === undefined ? {} : { cwd: spawnOptions.cwd }),
+            ...(spawnOptions.env === undefined ? {} : { env: spawnOptions.env }),
+        });
+    }
+    catch (error) {
+        // The OS spawn itself threw: this invocation made no target process.
+        try {
+            if (container !== null)
+                bag.onContainerEmpty?.();
+        }
+        catch { }
+        container?.release();
+        throw error;
+    }
+    if (container !== null) {
+        containers.set(child, container);
+        // A descendant may keep stdout/stderr open after the root exits. Begin
+        // cleanup at root exit; waiting for `close` would wait for that descendant.
+        child.once("exit", () => {
+            void settleContainer(container, bag).then(empty => {
+                if (!empty) {
+                    child.stdout?.destroy();
+                    child.stderr?.destroy();
+                }
+            });
+        });
+        child.once("error", () => { void settleContainer(container, bag); });
+    }
+    try {
+        if (child.pid !== undefined) {
+            bag.onSpawn?.(child.pid);
+        }
+    }
+    catch (error) {
+        throw new SpawnCustodyFailure(child, error);
+    }
+    const attached = launch === null || child.pid === undefined ? Promise.resolve({ ok: true }) : launch.attach(child);
+    return { child, container, attached };
+}
+/**
+ * The settlement every containable transport runs at the root's exit:
+ * members that outlived the root (a setsid'd helper, a double fork) are
+ * killed and the OS asked for its empty state, bounded. The answer is
+ * the proof the custody record keeps — `false` leaves the record
+ * unproven and every stop/resume fence closed.
+ */
+const containerSettlements = new WeakMap();
+function settleContainer(container, bag, timeoutMs = 5_000) {
+    const existing = containerSettlements.get(container);
+    if (existing !== undefined)
+        return existing;
+    const settling = finishContainer(container, bag, timeoutMs);
+    containerSettlements.set(container, settling);
+    return settling;
+}
+async function finishContainer(container, bag, timeoutMs) {
+    let empty = container.populated() === false;
+    try {
+        if (!empty)
+            empty = await container.kill(timeoutMs);
+    }
+    catch {
+        empty = false;
+    }
+    try {
+        if (empty)
+            bag.onContainerEmpty?.();
+        else
+            bag.onUnknown?.();
+    }
+    catch {
+        // Custody that cannot be written stays unproven; the fences hold.
+        empty = false;
+    }
+    try {
+        container.release();
+    }
+    catch { /* proof already determines the result */ }
+    return empty;
+}
+/** The result's containment field for a spawn that ran inside an object. */
+function containmentOf(container, empty, attachFailure) {
+    if (attachFailure !== null)
+        return { containment: { refused: attachFailure } };
+    if (container === null || empty === null)
+        return {};
+    return { containment: { backend: container.backend, id: container.id, empty } };
+}
+/** The streaming transports' spawn: contained when the spawn is a provider (process group), plain otherwise. */
+function spawnStream(file, args, options, stdio, childEnv) {
+    return spawnContained(file, args, { cwd: options.cwd, env: childEnv, stdio, detached: options.processGroup === true && process.platform !== "win32" }, options.owner ?? "stream", { beforeSpawn: options.beforeSpawn, onSpawn: options.onSpawn, onContainer: options.onContainer, onContainerEmpty: options.onContainerEmpty, onUnknown: options.onUnknown, fence: options.fence }, options.processGroup === true);
+}
+/** The refusal-before-spawn shape shared by every containable transport. */
+function refusedResult(error) {
+    if (error instanceof ContainmentRefusal) {
+        return { code: CONTAINMENT_REFUSED_CODE, stdout: "", stderr: error.message, timedOut: false, notFound: false, containment: { refused: error.message } };
+    }
+    return { code: 1, stdout: "", stderr: String(error instanceof SpawnCustodyFailure ? error.reason : error), timedOut: false, notFound: false };
+}
+const databaseOwners = new WeakMap();
+let memoryDatabaseOwner = 0;
+/** Run IDs are local to a database. Connections to the same file share
+ * custody; separate files and separate in-memory databases never do. */
+export function runOwnerTag(store, runId) {
+    let owner = databaseOwners.get(store.handle);
+    if (owner === undefined) {
+        const main = store.handle.prepare("PRAGMA database_list").all().find(row => row["name"] === "main");
+        const file = main?.["file"];
+        owner = typeof file === "string" && file !== "" ? `file:${realpathSync(file)}` : `memory:${++memoryDatabaseOwner}`;
+        databaseOwners.set(store.handle, owner);
+    }
+    return JSON.stringify([owner, runId]);
+}
+/** How many live children this process still tracks under an owner tag. */
+// Zero is local to this process registry. Recovery must also inspect durable
+// witnesses and its authenticated OS census; this count is not an absence proof.
+export function ownedProcessCount(owner) {
+    return ownedChildren.get(owner)?.size ?? 0;
+}
+/**
+ * The exact-attempt stop (v52): SIGKILL the process group of every live
+ * child registered under the owner tag — and only those. Returns how many
+ * were signalled. Idempotent: a child already gone was dropped at close,
+ * and a tag nobody registered kills nothing. This is the ONLY kill road a
+ * task action may take; the global sweep below is the watch's shutdown.
+ */
+export function terminateOwnedProcesses(owner) {
+    const owned = ownedChildren.get(owner);
+    if (owned === undefined)
+        return 0;
+    let terminated = 0;
+    for (const child of owned) {
+        if (child.exitCode !== null || child.signalCode !== null)
+            continue;
+        killGroup(child);
+        terminated += 1;
+    }
+    return terminated;
+}
+/**
+ * Live held-session SUPERVISORS (v6 W7). Not in liveProviders: SIGKILLing a
+ * supervisor's group would orphan the agent living in its own fresh group.
+ * The sweep's contract here is SIGTERM first — the supervisor's handler
+ * fences its child (EOF → grace → group SIGKILL) — and SIGKILL only on a
+ * repeat sweep, which is the one road that can orphan an agent and is why
+ * it is the escalation, never the opener.
+ */
+const heldSupervisors = new Map();
+/** SIGKILL the child's whole process group; fall back to the child alone. */
+function killGroup(child) {
+    const container = containers.get(child);
+    if (container !== undefined) {
+        // The OS object reaches every member at once — detached helpers
+        // included — and its empty state is awaited by the transport's
+        // settlement, never assumed here.
+        void container.kill().catch(() => { });
+        // The Windows helper is the job's owner and reporter: it terminates the
+        // job on the order above and answers "empty"; killing it instead would
+        // close the handle (kill-on-close still ends the job) but lose the proof.
+        if (container.backend !== "job-object") {
+            try {
+                child.kill("SIGKILL");
+            }
+            catch { /* already gone */ }
+        }
+        return;
+    }
+    if (stopProcessTree(child))
+        return;
+    const pid = child.pid;
+    if (pid !== undefined && process.platform === "win32") {
+        // Windows has no process groups to signal (Codex M5-M8 audit, IV-6):
+        // taskkill /T walks the tree, so a harness's shell grandchildren die
+        // with it instead of writing to the worktree after "stopped". Untested
+        // on physical Windows, like the daemon — stated, not hidden.
+        try {
+            spawn("taskkill", ["/PID", String(pid), "/T", "/F"], { stdio: "ignore", windowsHide: true }).on("error", () => { });
+        }
+        catch {
+            // taskkill missing or refused — the direct kill below still runs.
+        }
+    }
+    if (pid !== undefined && process.platform !== "win32") {
+        try {
+            process.kill(-pid, "SIGKILL");
+            return;
+        }
+        catch {
+            // No group of ours (not detached, or already gone) — fall through.
+        }
+    }
+    try {
+        child.kill("SIGKILL");
+    }
+    catch {
+        // Already gone.
+    }
+}
+/**
+ * The hard stop (M6.12): SIGKILL every live provider's process group.
+ * Called by the watch when its stop grace expires — never on the first
+ * signal, which stays graceful. Late output cannot commit or publish:
+ * the killed process exits nonzero, the build finalizes as the failure
+ * it is, and every commit sits behind fences the corpse cannot pass.
+ */
+export function terminateLiveProviders() {
+    let terminated = 0;
+    for (const child of liveProviders) {
+        killGroup(child);
+        terminated += 1;
+    }
+    // Held supervisors take the graceful road first (v6 W7): SIGTERM makes
+    // the supervisor fence its own agent race-free through the handle only
+    // it holds. A second sweep escalates to SIGKILL — the documented
+    // residual hole, reachable only by double-escalation, with the startup
+    // orphan fence paging for anything that lingers.
+    for (const [supervisor, stage] of heldSupervisors) {
+        try {
+            if (stage === "fresh") {
+                supervisor.kill("SIGTERM");
+                heldSupervisors.set(supervisor, "termed");
+            }
+            else {
+                // With a native OS object the escalation reaches the agent too:
+                // the object's kill is the one road that cannot orphan it.
+                killGroup(supervisor);
+            }
+        }
+        catch {
+            // Already gone.
+        }
+        terminated += 1;
+    }
+    return terminated;
+}
+/** The one place a child's environment is decided (audit IV-5). */
+/**
+ * Chat credentials never reach a child process (Codex chat v3 review,
+ * change 10): ANTHROPIC_API_KEY is the chat key AND would silently flip
+ * the claude harness from subscription auth to API billing if inherited.
+ * A caller that genuinely needs it re-supplies it via `env` explicitly.
+ * (OPENROUTER_API_KEY is not listed: the openrouter BUILD adapter reads
+ * it from the child env by design, and the agent-facing shell excludes
+ * it separately via the provider's own config.)
+ */
+const CHAT_KEYS_NEVER_INHERITED = ["ANTHROPIC_API_KEY"];
+function resolveChildEnv(options) {
+    const { env, omitEnv, envAllowlist } = options;
+    if (envAllowlist !== undefined) {
+        const picked = {};
+        for (const name of envAllowlist) {
+            const value = process.env[name];
+            if (value !== undefined)
+                picked[name] = value;
+        }
+        Object.assign(picked, env ?? {});
+        for (const name of omitEnv ?? [])
+            delete picked[name];
+        for (const name of CHAT_KEYS_NEVER_INHERITED) {
+            if (env?.[name] === undefined)
+                delete picked[name];
+        }
+        return picked;
+    }
+    const merged = { ...process.env, ...(env ?? {}) };
+    for (const name of omitEnv ?? [])
+        delete merged[name];
+    for (const name of CHAT_KEYS_NEVER_INHERITED) {
+        if (env?.[name] === undefined)
+            delete merged[name];
+    }
+    return merged;
+}
+/** Conventions from the shell and from coreutils `timeout(1)`. */
+export const NOT_FOUND_CODE = 127;
+export const TIMEOUT_CODE = 124;
+/** Output too large to hold. Not a timeout, and must not be reported as one. */
+/** A spawn callback records custody after the child exists. If that write
+ * fails, stop and reap the owned child before reporting failure; otherwise
+ * an unrecorded provider could keep writing after its caller retries. */
+function reapRejectedSpawn(child, group) {
+    if (child === undefined)
+        return Promise.resolve();
+    return new Promise(resolve => {
+        if (group)
+            liveProviders.add(child);
+        child.once("close", () => {
+            liveProviders.delete(child);
+            const container = containers.get(child);
+            if (container === undefined)
+                resolve();
+            else
+                void settleContainer(container, {}).then(() => resolve());
+        });
+        child.on("error", () => { });
+        child.stdout?.resume();
+        child.stderr?.resume();
+        if (group)
+            killGroup(child);
+        else {
+            try {
+                child.kill("SIGKILL");
+            }
+            catch { /* The child must still exit before failure is returned. */ }
+        }
+    });
+}
+export const OVERFLOW_CODE = 125;
+export const DEFAULT_TIMEOUT_MS = 15_000;
+export const DEFAULT_MAX_BUFFER = 8 * 1024 * 1024;
+/**
+ * A streaming process may run for hours while it is making observable
+ * progress. This controller keeps the ordinary hard timeout available for
+ * bounded work, while allowing provider callers to choose an activity-based
+ * watchdog with no wall-clock deadline. Both roads share the same kill and
+ * settlement semantics.
+ */
+function streamWatchdog(options, onTimeout) {
+    const hardMs = options.timeoutMs ?? (options.idleTimeoutMs === undefined ? DEFAULT_TIMEOUT_MS : undefined);
+    const idleMs = options.idleTimeoutMs;
+    let fired = false;
+    let hardTimer;
+    let idleTimer;
+    const fire = () => {
+        if (fired)
+            return;
+        fired = true;
+        onTimeout();
+    };
+    const armIdle = () => {
+        if (idleMs === undefined)
+            return;
+        if (idleTimer !== undefined)
+            clearTimeout(idleTimer);
+        idleTimer = setTimeout(fire, idleMs);
+        idleTimer.unref?.();
+    };
+    if (hardMs !== undefined) {
+        hardTimer = setTimeout(fire, hardMs);
+        hardTimer.unref?.();
+    }
+    armIdle();
+    return {
+        touch: armIdle,
+        stop: () => {
+            if (hardTimer !== undefined)
+                clearTimeout(hardTimer);
+            if (idleTimer !== undefined)
+                clearTimeout(idleTimer);
+        },
+    };
+}
+const MAX_BUFFER_ERROR = "ERR_CHILD_PROCESS_STDIO_MAXBUFFER";
+/**
+ * A spawn the OS refused for the moment — no free process slot or file
+ * descriptor (a loaded machine, a fork storm from a parallel test suite) —
+ * is not the command failing: the command never ran. Left as an exit 1, a
+ * `git symbolic-ref` that never started reads as "no branch checked out"
+ * and an unattended pass refuses on a lie. So the two buffered transports
+ * retry EXACTLY this class, bounded, before answering.
+ */
+const TRANSIENT_SPAWN_CODES = new Set(["EAGAIN", "EMFILE", "ENFILE"]);
+export const SPAWN_RETRY_DELAYS_MS = [50, 100, 200, 400, 800];
+export function isTransientSpawnFailure(error) {
+    return error !== null && error !== undefined && typeof error.code === "string" && TRANSIENT_SPAWN_CODES.has(error.code);
+}
+/**
+ * Retry `attempt` while it reports a transient spawn failure, sleeping the
+ * given delays between tries; the last answer stands when they run out.
+ * A non-transient answer — success, a real exit code, not found, timeout —
+ * is returned at once: only the never-started case is retried.
+ */
+export async function retryTransientSpawn(attempt, delays = SPAWN_RETRY_DELAYS_MS, sleep = ms => new Promise(resolve => setTimeout(resolve, ms))) {
+    let last = await attempt();
+    for (const delay of delays) {
+        if (!last.transient)
+            return last.result;
+        await sleep(delay);
+        last = await attempt();
+    }
+    return last.result;
+}
+export function run(file, args, options = {}) {
+    const { cwd, timeoutMs = DEFAULT_TIMEOUT_MS, maxBuffer = DEFAULT_MAX_BUFFER } = options;
+    const childEnv = resolveChildEnv(options);
+    // A provider run needs its own process group; execFile cannot give one,
+    // so the buffered path detours through spawn with identical semantics.
+    if (options.processGroup === true) {
+        return retryTransientSpawn(() => runBufferedGroup(file, args, {
+            timeoutMs,
+            maxBuffer,
+            ...(options.stdin === undefined ? {} : { stdin: options.stdin }),
+            ...(cwd === undefined ? {} : { cwd }),
+            ...(childEnv === undefined ? {} : { childEnv }),
+            ...(options.onSpawn === undefined ? {} : { onSpawn: options.onSpawn }),
+            ...(options.owner === undefined ? {} : { owner: options.owner }),
+            ...(options.beforeSpawn === undefined ? {} : { beforeSpawn: options.beforeSpawn }),
+            ...(options.onStdout === undefined ? {} : { onStdout: options.onStdout }),
+            ...(options.onStderr === undefined ? {} : { onStderr: options.onStderr }),
+            ...(options.fence === undefined ? {} : { fence: options.fence }),
+            ...(options.onDescendant === undefined ? {} : { onDescendant: options.onDescendant }),
+            ...(options.onDescendantWriteFailure === undefined ? {} : { onDescendantWriteFailure: options.onDescendantWriteFailure }),
+            ...(options.onDescendantExit === undefined ? {} : { onDescendantExit: options.onDescendantExit }),
+            ...(options.onUnknown === undefined ? {} : { onUnknown: options.onUnknown }),
+            ...(options.onObservationFailure === undefined ? {} : { onObservationFailure: options.onObservationFailure }),
+            ...(options.onContainer === undefined ? {} : { onContainer: options.onContainer }),
+            ...(options.onContainerEmpty === undefined ? {} : { onContainerEmpty: options.onContainerEmpty }),
+        }));
+    }
+    return retryTransientSpawn(() => new Promise(resolve => {
+        execFile(file, [...args], {
+            cwd,
+            timeout: timeoutMs,
+            maxBuffer,
+            encoding: "utf8",
+            shell: false,
+            windowsHide: true,
+            ...(childEnv === undefined ? {} : { env: childEnv }),
+        }, (error, stdout, stderr) => {
+            if (error === null) {
+                resolve({ result: { code: 0, stdout, stderr, timedOut: false, notFound: false }, transient: false });
+                return;
+            }
+            resolve({
+                result: describeFailure(error, stdout, stderr),
+                transient: isTransientSpawnFailure(error),
+            });
+        });
+    }));
+}
+/**
+ * The buffered transport for process-group providers (claude): spawn
+ * detached so the harness and everything it launches share one killable
+ * group, collect output up to the same maxBuffer contract as execFile,
+ * and register as a live provider for the watch's hard stop.
+ */
+function runBufferedGroup(file, args, bag) {
+    return new Promise(resolve => {
+        let child;
+        let container = null;
+        let attached;
+        try {
+            const spawned = spawnContained(file, args, { cwd: bag.cwd, env: bag.childEnv, stdio: [bag.stdin === undefined ? "ignore" : "pipe", "pipe", "pipe"], detached: process.platform !== "win32" }, bag.owner ?? "buffered", { beforeSpawn: bag.beforeSpawn, onSpawn: bag.onSpawn, onContainer: bag.onContainer, onContainerEmpty: bag.onContainerEmpty, onUnknown: bag.onUnknown, fence: bag.fence });
+            child = spawned.child;
+            container = spawned.container;
+            attached = spawned.attached;
+        }
+        catch (error) {
+            const left = rejectedChild(error, child);
+            void reapRejectedSpawn(left, true).then(() => {
+                resolve({
+                    result: refusedResult(error),
+                    transient: left === undefined && isTransientSpawnFailure(error),
+                });
+            });
+            return;
+        }
+        liveProviders.add(child);
+        registerOwned(bag.owner, child);
+        if (container === null)
+            observeProcessTree(child, bag);
+        let stdout = "";
+        let stderr = "";
+        let timedOut = false;
+        let overflowed = false;
+        let inputFailed = false;
+        let notFound = false;
+        let attachFailure = null;
+        void attached.then(outcome => { if (!outcome.ok)
+            attachFailure = outcome.detail; });
+        const timer = setTimeout(() => {
+            timedOut = true;
+            killGroup(child);
+        }, bag.timeoutMs);
+        child.stdout?.setEncoding("utf8");
+        child.stdout?.on("data", (chunk) => {
+            stdout += chunk;
+            if (stdout.length > bag.maxBuffer) {
+                overflowed = true;
+                killGroup(child);
+            }
+            try {
+                bag.onStdout?.(chunk);
+            }
+            catch { /* a listener never breaks the run */ }
+        });
+        child.stderr?.setEncoding("utf8");
+        child.stderr?.on("data", (chunk) => {
+            if (stderr.length < bag.maxBuffer)
+                stderr += chunk.slice(0, bag.maxBuffer - stderr.length);
+            try {
+                bag.onStderr?.(chunk);
+            }
+            catch { /* a listener never breaks the run */ }
+        });
+        let settled = false;
+        let transient = false;
+        const finish = (code) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            liveProviders.delete(child);
+            // The OS object is settled BEFORE the answer: a root that exited is
+            // not an empty container until the OS says so.
+            const settlement = container === null ? Promise.resolve(null) : settleContainer(container, bag);
+            void settlement.then(empty => {
+                resolve({
+                    result: {
+                        code: notFound ? NOT_FOUND_CODE : overflowed ? OVERFLOW_CODE : timedOut ? TIMEOUT_CODE : inputFailed ? 1 : attachFailure !== null || empty === false ? CONTAINMENT_REFUSED_CODE : (code ?? 1),
+                        stdout,
+                        stderr: empty === false ? `${stderr}\nNative process containment could not prove all descendants exited.`.trim() : attachFailure !== null && stderr === "" ? attachFailure : stderr,
+                        // Overflow also killed the child; it is not a timeout and must not read as one.
+                        timedOut: timedOut && !overflowed,
+                        notFound,
+                        ...containmentOf(container, empty, attachFailure),
+                    },
+                    transient,
+                });
+            });
+        };
+        child.on("error", error => {
+            notFound = error.code === "ENOENT";
+            transient = isTransientSpawnFailure(error);
+            if (stderr === "")
+                stderr = String(error);
+            finish(null);
+        });
+        child.on("close", code => finish(code));
+        if (bag.stdin !== undefined && child.stdin !== null) {
+            child.stdin.on("error", () => {
+                inputFailed = true;
+                stderr = "prompt input failed: the provider closed its input before delivery completed";
+                killGroup(child);
+            });
+            child.stdin.end(bag.stdin, "utf8");
+        }
+    });
+}
+/**
+ * Turn an execFile error into a result. The order matters: a maxBuffer overflow
+ * also arrives with `killed: true`, so it has to be recognised before the
+ * timeout check or a truncated `git log` reads as a hung one.
+ */
+function describeFailure(error, stdout, stderr) {
+    const notFound = error.code === "ENOENT";
+    const overflowed = error.code === MAX_BUFFER_ERROR;
+    const timedOut = !overflowed && error.killed === true;
+    return {
+        code: resolveCode(error, { notFound, overflowed, timedOut }),
+        stdout,
+        stderr: stderr === "" ? error.message : stderr,
+        timedOut,
+        notFound,
+    };
+}
+function resolveCode(error, flags) {
+    if (typeof error.code === "number")
+        return error.code;
+    if (flags.notFound)
+        return NOT_FOUND_CODE;
+    if (flags.overflowed)
+        return OVERFLOW_CODE;
+    if (flags.timedOut)
+        return TIMEOUT_CODE;
+    return 1;
+}
+/**
+ * The streaming transport for JSONL-emitting providers.
+ *
+ * A long agent session can write far more event stream than any fixed
+ * buffer should hold, and the lines that matter — the session identity,
+ * the terminal usage — arrive LAST. Buffering-and-overflowing would kill
+ * the process at 8 MiB and lose exactly the facts a paid run must not
+ * lose (Codex provider review, high finding 2). So stdout is consumed
+ * incrementally and only the load-bearing lines are retained:
+ *
+ *   - a bounded identity witness for `thread.started` (first usable id,
+ *     first conflicting id, and last event), plus the LAST `turn.completed`
+ *     and `turn.failed` line
+ *   - the LAST `item.completed` line carrying an agent_message
+ *
+ * each capped per line; everything else is counted and dropped. The
+ * result's stdout is the retained lines joined — a synthetic, bounded
+ * envelope the parser reads exactly like test fixtures.
+ */
+const JSONL_LINE_CAP = 64 * 1024;
+const JSONL_STDERR_CAP = 64 * 1024;
+/** Canonical identity at the transport boundary. Never persist or expose
+ * provider framing whitespace as part of a resumable session id. */
+function transportSessionId(value) {
+    if (typeof value !== "string")
+        return null;
+    const id = value.trim();
+    return id === "" ? null : id;
+}
+/**
+ * Provider replies are nested inside their JSONL envelope. A 64 KiB reply
+ * therefore needs appreciably more than 64 KiB on the wire once quotes,
+ * backslashes, and control characters are escaped. 512 KiB carries that
+ * worst useful case while remaining a hard, per-event memory boundary.
+ */
+export const JSONL_EVENT_HARD_CAP = 512 * 1024;
+const JSONL_OVERFLOW_PREFIX_CAP = 4 * 1024;
+/**
+ * Split a byte stream into JSONL records without ever accumulating an
+ * unbounded partial line. The callback is synchronous so the same fixed
+ * storage can be reused for the next record. Counting the original bytes
+ * (rather than JavaScript characters) makes the overflow receipt exact.
+ */
+function boundedJsonlFramer(cap, onLine, inspectDiscriminants = false) {
+    const retained = Buffer.allocUnsafe(cap);
+    let retainedBytes = 0;
+    let originalBytes = 0;
+    let nonWhitespace = false;
+    let discriminants = inspectDiscriminants ? jsonlDiscriminants() : null;
+    const append = (part) => {
+        discriminants?.push(part);
+        originalBytes += part.length;
+        if (!nonWhitespace) {
+            for (const byte of part) {
+                if (byte !== 0x09 && byte !== 0x0a && byte !== 0x0d && byte !== 0x20) {
+                    nonWhitespace = true;
+                    break;
+                }
+            }
+        }
+        if (retainedBytes < cap) {
+            retainedBytes += part.copy(retained, retainedBytes, 0, cap - retainedBytes);
+        }
+    };
+    const emit = () => {
+        onLine({
+            prefix: retained.subarray(0, retainedBytes),
+            bytesOriginal: originalBytes,
+            overflowed: originalBytes > cap,
+            ...(discriminants === null ? {} : { discriminants: discriminants.finish() }),
+        });
+        retainedBytes = 0;
+        originalBytes = 0;
+        nonWhitespace = false;
+        discriminants = inspectDiscriminants ? jsonlDiscriminants() : null;
+    };
+    return {
+        push(chunk) {
+            let start = 0;
+            for (;;) {
+                const newline = chunk.indexOf(0x0a, start);
+                if (newline === -1) {
+                    append(chunk.subarray(start));
+                    return;
+                }
+                append(chunk.subarray(start, newline));
+                emit();
+                start = newline + 1;
+            }
+        },
+        finish() {
+            // Match the old `partial.trim() !== ""` rule: a final unterminated
+            // whitespace-only record is not an event and needs no receipt.
+            if (originalBytes > 0 && nonWhitespace)
+                emit();
+        },
+    };
+}
+function overflowReceiptText(transport, line) {
+    const rawPrefix = line.prefix.subarray(0, Math.min(line.prefix.length, JSONL_OVERFLOW_PREFIX_CAP));
+    return JSON.stringify({
+        type: "standing-orders.stream-event-overflow",
+        transport,
+        message: `The provider emitted a JSONL event larger than the ${JSONL_EVENT_HARD_CAP}-byte safety limit.`,
+        eventBytesOriginal: line.bytesOriginal,
+        hardCapBytes: JSONL_EVENT_HARD_CAP,
+        prefixBytes: rawPrefix.length,
+        prefix: rawPrefix.toString("utf8"),
+        // The readable prefix can end halfway through a UTF-8 character. This
+        // companion is the exact retained byte prefix for forensic evidence.
+        prefixBase64: rawPrefix.toString("base64"),
+    });
+}
+function malformedReceiptText(transport, line) {
+    const rawPrefix = line.prefix.subarray(0, Math.min(line.prefix.length, JSONL_OVERFLOW_PREFIX_CAP));
+    return JSON.stringify({
+        type: "standing-orders.stream-event-malformed",
+        transport,
+        message: "The provider emitted malformed JSON for a load-bearing stream event after initialization.",
+        eventBytesOriginal: line.bytesOriginal,
+        prefixBytes: rawPrefix.length,
+        prefix: rawPrefix.toString("utf8"),
+        prefixBase64: rawPrefix.toString("base64"),
+    });
+}
+function codexOverflowLine(line) {
+    return JSON.stringify({
+        type: "turn.failed",
+        error: {
+            type: "standing-orders.stream-event-overflow",
+            message: overflowReceiptText("codex", line),
+        },
+    });
+}
+function codexMalformedLine(line) {
+    return JSON.stringify({
+        type: "turn.failed",
+        error: {
+            type: "standing-orders.stream-event-malformed",
+            message: malformedReceiptText("codex", line),
+        },
+    });
+}
+function claudeOverflowLine(line) {
+    return JSON.stringify({
+        type: "result",
+        subtype: "standing-orders-stream-event-overflow",
+        is_error: true,
+        result: overflowReceiptText("claude", line),
+    });
+}
+function geminiOverflowLine(line) {
+    return JSON.stringify({
+        type: "result",
+        status: "standing-orders-stream-event-overflow",
+        error: { message: overflowReceiptText("gemini", line) },
+    });
+}
+function geminiMalformedLine(line) {
+    return JSON.stringify({
+        type: "result",
+        status: "standing-orders-stream-event-malformed",
+        error: { message: malformedReceiptText("gemini", line) },
+    });
+}
+/**
+ * Read only the leading, top-level `type` discriminant from an incomplete
+ * JSON object. Provider JSONL dialects put `type` first. Anchoring the match
+ * means content later in an oversized event can never spoof classification.
+ */
+function leadingJsonObjectType(prefix) {
+    const match = /^\s*\{\s*"type"\s*:\s*"([A-Za-z0-9._-]+)"/.exec(prefix.toString("utf8", 0, Math.min(prefix.length, 256)));
+    return match?.[1] ?? null;
+}
+/** Codex emits `item` immediately after the outer type. Only an agent
+ * message is load-bearing; completed command/tool telemetry is droppable. */
+function leadingCodexCompletedItemType(prefix) {
+    const match = /^\s*\{\s*"type"\s*:\s*"item\.completed"\s*,\s*"item"\s*:\s*\{\s*"type"\s*:\s*"([A-Za-z0-9._-]+)"/.exec(prefix.toString("utf8", 0, Math.min(prefix.length, 512)));
+    return match?.[1] ?? null;
+}
+function leadingClaudeSystemSubtype(prefix) {
+    const match = /^\s*\{\s*"type"\s*:\s*"system"\s*,\s*"subtype"\s*:\s*"([A-Za-z0-9._-]+)"/.exec(prefix.toString("utf8", 0, Math.min(prefix.length, 512)));
+    return match?.[1] ?? null;
+}
+function malformedCodexEventIsLoadBearing(prefix) {
+    const type = leadingJsonObjectType(prefix);
+    if (type === "thread.started" || type === "turn.completed" || type === "turn.failed")
+        return true;
+    if (type !== "item.completed")
+        return false;
+    const itemType = leadingCodexCompletedItemType(prefix);
+    return itemType === null || itemType === "agent_message";
+}
+function malformedGeminiEventIsLoadBearing(prefix) {
+    const type = leadingJsonObjectType(prefix);
+    // These two records authorize the session and the successful terminal.
+    // Malformed messages remain diagnostics only; startup prose, tool traffic,
+    // and warnings retain the transport's established noise tolerance.
+    return type === "init" || type === "result";
+}
+export function runStreamJsonl(file, args, options = {}) {
+    const { cwd } = options;
+    const childEnv = resolveChildEnv(options);
+    return new Promise(resolve => {
+        let child;
+        let container = null;
+        let attachFailure = null;
+        try {
+            const spawned = spawnStream(file, args, options, [options.stdin === undefined ? "ignore" : "pipe", "pipe", "pipe"], childEnv);
+            child = spawned.child;
+            container = spawned.container;
+            void spawned.attached.then(outcome => { if (!outcome.ok)
+                attachFailure = outcome.detail; });
+        }
+        catch (error) {
+            void reapRejectedSpawn(rejectedChild(error, child), options.processGroup === true).then(() => resolve(refusedResult(error)));
+            return;
+        }
+        if (options.processGroup === true)
+            liveProviders.add(child);
+        registerOwned(options.owner, child);
+        if (options.processGroup === true && container === null)
+            observeProcessTree(child, options);
+        let startedLine = null;
+        let startedIdentityLine = null;
+        let conflictingStartedLine = null;
+        let startedSessionId = null;
+        let completedLine = null;
+        let failedLine = null;
+        let overflowLine = null;
+        let malformedLine = null;
+        let lastMessage = null;
+        let stderr = "";
+        let timedOut = false;
+        let notFound = false;
+        let inputFailed = false;
+        const keep = (framed) => {
+            if (framed.overflowed) {
+                // Inspect structural keys across the complete byte stream, including
+                // keys AFTER discarded command output. Quoted or nested types cannot
+                // spoof these discriminants, and malformed/ambiguous input stays red.
+                const type = framed.discriminants?.type ?? null;
+                if (type !== null && !["thread.started", "turn.completed", "turn.failed", "item.completed"].includes(type)) {
+                    return;
+                }
+                if (type === "item.completed") {
+                    const itemType = framed.discriminants?.itemType;
+                    if (itemType !== undefined && itemType !== null && ["command_execution", "mcp_tool_call", "web_search", "file_change", "todo_list"].includes(itemType))
+                        return;
+                }
+                // A load-bearing or unclassifiable hard-cap breach is independently
+                // retained as failure. Once those bytes were discarded, a later
+                // ordinary message must never turn the run green.
+                if (overflowLine === null)
+                    overflowLine = codexOverflowLine(framed);
+                return;
+            }
+            const line = framed.prefix.toString("utf8");
+            try {
+                const event = JSON.parse(line);
+                const type = String(event["type"] ?? "");
+                if (type === "thread.started") {
+                    // Keep the last init for the existing transport contract and a
+                    // bounded pair of earlier witnesses so a conflict cannot hide.
+                    startedLine = line;
+                    const id = transportSessionId(event["thread_id"]);
+                    if (id !== null) {
+                        // Retain only enough events to prove the identity contract:
+                        // one usable id when the first init was blank, and one conflict.
+                        if (startedSessionId === null) {
+                            startedSessionId = id;
+                            startedIdentityLine = line;
+                        }
+                        else if (id !== startedSessionId && conflictingStartedLine === null) {
+                            conflictingStartedLine = line;
+                        }
+                        if (options.onSessionId !== undefined) {
+                            try {
+                                options.onSessionId(id);
+                            }
+                            catch {
+                                // A registry that cannot be written must not kill the turn.
+                            }
+                        }
+                    }
+                }
+                else if (type === "turn.completed") {
+                    completedLine = line;
+                }
+                else if (type === "turn.failed") {
+                    // Retain failure independently from completion: seeing either at
+                    // any point is load-bearing, while one slot per kind stays bounded.
+                    failedLine = line;
+                }
+                else if (type === "item.completed") {
+                    const item = event["item"];
+                    if (item !== undefined && String(item["type"] ?? "") === "agent_message") {
+                        lastMessage = line;
+                    }
+                }
+                if (options.onStreamEvent !== undefined) {
+                    try {
+                        options.onStreamEvent(event);
+                    }
+                    catch {
+                        // Observational only: a broken listener never touches the run.
+                    }
+                }
+            }
+            catch {
+                // Startup prose and ordinary malformed telemetry remain ignorable.
+                // Once initialization is proven, however, a recognizable control or
+                // answer record cannot disappear merely because its JSON was cut.
+                if (startedLine !== null &&
+                    malformedLine === null &&
+                    malformedCodexEventIsLoadBearing(framed.prefix)) {
+                    malformedLine = codexMalformedLine(framed);
+                }
+            }
+        };
+        const framing = boundedJsonlFramer(JSONL_EVENT_HARD_CAP, keep, true);
+        const watchdog = streamWatchdog(options, () => {
+            timedOut = true;
+            if (options.processGroup === true)
+                killGroup(child);
+            else
+                child.kill("SIGKILL");
+        });
+        child.stdout?.on("data", (chunk) => {
+            watchdog.touch();
+            framing.push(chunk);
+        });
+        child.stderr?.setEncoding("utf8");
+        child.stderr?.on("data", (chunk) => {
+            watchdog.touch();
+            if (stderr.length < JSONL_STDERR_CAP)
+                stderr += chunk.slice(0, JSONL_STDERR_CAP - stderr.length);
+        });
+        let settled = false;
+        const finish = (code) => {
+            if (settled)
+                return;
+            settled = true;
+            watchdog.stop();
+            liveProviders.delete(child);
+            framing.finish();
+            const lines = [
+                startedIdentityLine,
+                conflictingStartedLine,
+                startedLine,
+                completedLine,
+                failedLine,
+                overflowLine,
+                malformedLine,
+                lastMessage,
+            ]
+                .filter((line) => line !== null)
+                .filter((line, index, all) => all.indexOf(line) === index);
+            const settlement = container === null ? Promise.resolve(null) : settleContainer(container, options);
+            void settlement.then(empty => resolve({
+                code: notFound ? NOT_FOUND_CODE : timedOut ? TIMEOUT_CODE : inputFailed ? 1 : attachFailure !== null || empty === false ? CONTAINMENT_REFUSED_CODE : (code ?? 1),
+                stdout: lines.join("\n"),
+                stderr: empty === false ? `${stderr}\nNative process containment could not prove all descendants exited.`.trim() : attachFailure !== null && stderr === "" ? attachFailure : stderr,
+                timedOut,
+                notFound,
+                ...containmentOf(container, empty, attachFailure),
+            }));
+        };
+        // A failed spawn fires 'error' and may never fire 'close' — both routes
+        // settle, exactly once.
+        child.on("error", error => {
+            notFound = error.code === "ENOENT";
+            if (stderr === "")
+                stderr = String(error);
+            finish(null);
+        });
+        child.on("close", code => finish(code));
+        if (options.stdin !== undefined && child.stdin !== null) {
+            // Even an exit-0 child cannot prove a review if prompt delivery failed.
+            // Handle EPIPE without crashing the supervisor, then wait for close.
+            child.stdin.on("error", error => {
+                inputFailed = true;
+                stderr = `review prompt input failed: ${String(error)}`.slice(0, JSONL_STDERR_CAP);
+                if (options.processGroup === true)
+                    killGroup(child);
+                else
+                    child.kill("SIGKILL");
+            });
+            child.stdin.end(options.stdin, "utf8");
+        }
+    });
+}
+/**
+ * The streaming transport for gemini's stream-json dialect (Phase 3 D1/A7).
+ *
+ * Retention: a bounded `init` identity witness (the first init signal, first
+ * usable session id, and first conflicting id), the FIRST
+ * `severity:"error"` error event (diagnostics),
+ * the LAST `result` event (tokens + structural status), and the assistant's
+ * text — which gemini emits only as many `message` delta lines — ASSEMBLED
+ * into one line of a dedicated internal schema the real CLI cannot emit:
+ *
+ *   {"type":"synthetic_message","content":"...","truncated":true?}
+ *
+ * Assembly rules (round-3 f9): only `role:"assistant"` events with
+ * `delta === true` concatenate; a non-delta assistant message REPLACES the
+ * buffer (full-message semantics); non-string content is dropped; the cap
+ * is enforced on the SERIALIZED UTF-8 BYTES of the complete synthetic line
+ * (marker included), so it can never violate the runner's own line
+ * discipline. Everything else — user echoes, tool_use, tool_result,
+ * warnings — is dropped. Timeout, process-group, kill, and spawn
+ * semantics match `runStreamJsonl`.
+ */
+export function runGeminiStreamJsonl(file, args, options = {}) {
+    const { cwd } = options;
+    const childEnv = resolveChildEnv(options);
+    return new Promise(resolve => {
+        let child;
+        let container = null;
+        let attachFailure = null;
+        try {
+            const spawned = spawnStream(file, args, options, ["ignore", "pipe", "pipe"], childEnv);
+            child = spawned.child;
+            container = spawned.container;
+            void spawned.attached.then(outcome => { if (!outcome.ok)
+                attachFailure = outcome.detail; });
+        }
+        catch (error) {
+            void reapRejectedSpawn(rejectedChild(error, child), options.processGroup === true).then(() => resolve(refusedResult(error)));
+            return;
+        }
+        if (options.processGroup === true)
+            liveProviders.add(child);
+        registerOwned(options.owner, child);
+        if (options.processGroup === true && container === null)
+            observeProcessTree(child, options);
+        let initLine = null;
+        let initIdentityLine = null;
+        let conflictingInitLine = null;
+        let initSessionId = null;
+        let errorLine = null;
+        let resultLine = null;
+        let message = "";
+        let messageTruncated = false;
+        let stderr = "";
+        let timedOut = false;
+        let notFound = false;
+        let overflowLine = null;
+        let malformedLine = null;
+        const keep = (framed) => {
+            if (framed.overflowed) {
+                const type = leadingJsonObjectType(framed.prefix);
+                // Tool plumbing is never a terminal or answer. All load-bearing and
+                // unknown oversized events latch a terminal protocol failure so a
+                // later small success cannot hide discarded provider bytes.
+                if (type !== "tool_use" && type !== "tool_result") {
+                    if (overflowLine === null)
+                        overflowLine = geminiOverflowLine(framed);
+                }
+                return;
+            }
+            const line = framed.prefix.toString("utf8");
+            let event;
+            try {
+                event = JSON.parse(line);
+            }
+            catch {
+                if (initLine !== null &&
+                    malformedLine === null &&
+                    malformedGeminiEventIsLoadBearing(framed.prefix)) {
+                    malformedLine = geminiMalformedLine(framed);
+                }
+                return; // startup prose and non-load-bearing malformed noise are dropped
+            }
+            if (event === null || typeof event !== "object")
+                return;
+            const type = String(event["type"] ?? "");
+            if (type === "init") {
+                if (initLine === null)
+                    initLine = line;
+                const id = transportSessionId(event["session_id"]);
+                let identityWitness = false;
+                if (id !== null) {
+                    if (initSessionId === null) {
+                        initSessionId = id;
+                        initIdentityLine = line;
+                        identityWitness = true;
+                    }
+                    else if (id !== initSessionId && conflictingInitLine === null) {
+                        conflictingInitLine = line;
+                        identityWitness = true;
+                    }
+                    if (identityWitness && options.onSessionId !== undefined) {
+                        try {
+                            options.onSessionId(id);
+                        }
+                        catch {
+                            // A registry that cannot be written must not kill the turn.
+                        }
+                    }
+                }
+            }
+            else if (type === "result") {
+                resultLine = line; // last one wins
+            }
+            else if (type === "error") {
+                if (errorLine === null && String(event["severity"] ?? "") === "error")
+                    errorLine = line;
+            }
+            else if (type === "message" && String(event["role"] ?? "") === "assistant") {
+                const content = event["content"];
+                if (typeof content !== "string")
+                    return; // non-string content: dropped
+                if (event["delta"] === true) {
+                    if (!messageTruncated) {
+                        message += content;
+                        if (Buffer.byteLength(message, "utf8") > JSONL_LINE_CAP)
+                            messageTruncated = true;
+                    }
+                }
+                else {
+                    // A full (non-delta) assistant message replaces the buffer.
+                    message = content;
+                    messageTruncated = Buffer.byteLength(message, "utf8") > JSONL_LINE_CAP;
+                }
+            }
+            if (options.onStreamEvent !== undefined) {
+                try {
+                    options.onStreamEvent(event);
+                }
+                catch {
+                    // Observational only: a broken listener never touches the run.
+                }
+            }
+        };
+        const framing = boundedJsonlFramer(JSONL_EVENT_HARD_CAP, keep);
+        const watchdog = streamWatchdog(options, () => {
+            timedOut = true;
+            if (options.processGroup === true)
+                killGroup(child);
+            else
+                child.kill("SIGKILL");
+        });
+        child.stdout?.on("data", (chunk) => {
+            watchdog.touch();
+            framing.push(chunk);
+        });
+        child.stderr?.setEncoding("utf8");
+        child.stderr?.on("data", (chunk) => {
+            watchdog.touch();
+            if (stderr.length < JSONL_STDERR_CAP)
+                stderr += chunk.slice(0, JSONL_STDERR_CAP - stderr.length);
+        });
+        let settled = false;
+        const finish = (code) => {
+            if (settled)
+                return;
+            settled = true;
+            watchdog.stop();
+            liveProviders.delete(child);
+            framing.finish();
+            const lines = [initLine, initIdentityLine, conflictingInitLine]
+                .filter((line) => line !== null)
+                .filter((line, index, all) => all.indexOf(line) === index);
+            if (errorLine !== null)
+                lines.push(errorLine);
+            if (message !== "")
+                lines.push(syntheticMessageLine(message, messageTruncated));
+            if (resultLine !== null)
+                lines.push(resultLine);
+            // Keep the overflow last: gemini's contract is last-result-wins, and
+            // no later small event may erase evidence that a record was discarded.
+            if (overflowLine !== null)
+                lines.push(overflowLine);
+            // A recognizable, malformed terminal is just as conclusive as an
+            // oversized one. Keep it last so last-result-wins cannot erase it.
+            if (malformedLine !== null)
+                lines.push(malformedLine);
+            const settlement = container === null ? Promise.resolve(null) : settleContainer(container, options);
+            void settlement.then(empty => resolve({
+                code: notFound ? NOT_FOUND_CODE : timedOut ? TIMEOUT_CODE : attachFailure !== null || empty === false ? CONTAINMENT_REFUSED_CODE : (code ?? 1),
+                stdout: lines.join("\n"),
+                stderr: empty === false ? `${stderr}\nNative process containment could not prove all descendants exited.`.trim() : attachFailure !== null && stderr === "" ? attachFailure : stderr,
+                timedOut,
+                notFound,
+                ...containmentOf(container, empty, attachFailure),
+            }));
+        };
+        child.on("error", error => {
+            notFound = error.code === "ENOENT";
+            if (stderr === "")
+                stderr = String(error);
+            finish(null);
+        });
+        child.on("close", code => finish(code));
+    });
+}
+const TRUNCATION_MARKER = "…[truncated]";
+/**
+ * One serialized synthetic line, guaranteed ≤ JSONL_LINE_CAP in UTF-8
+ * bytes — the trim loop measures the COMPLETE serialized line (escaping
+ * and marker included), so pathological escaping cannot smuggle it past
+ * the cap (round-3 f9).
+ */
+function syntheticMessageLine(content, truncated) {
+    let body = content;
+    let marked = truncated;
+    for (;;) {
+        const line = JSON.stringify(marked
+            ? { type: "synthetic_message", content: body + TRUNCATION_MARKER, truncated: true }
+            : { type: "synthetic_message", content: body });
+        const over = Buffer.byteLength(line, "utf8") - JSONL_LINE_CAP;
+        if (over <= 0)
+            return line;
+        marked = true;
+        // Cut at least the overage in UTF-16 units; the loop re-measures.
+        const cut = Math.max(1, over);
+        body = body.slice(0, Math.max(0, body.length - cut));
+    }
+}
+/**
+ * The streaming transport for claude's stream-json dialect (arc 1).
+ *
+ * Same rationale as `runStreamJsonl`: a long agent session writes far more
+ * event stream than any fixed buffer should hold, and the line that matters
+ * — the terminal result carrying session, usage, and dollars — arrives
+ * LAST. The 8 MiB buffered kill would destroy exactly that accounting
+ * envelope, so stdout is consumed incrementally and only the load-bearing
+ * lines are retained:
+ *
+ *   - a bounded identity witness for `system`/`init`: the first init signal,
+ *     the first usable session id, and one conflicting id
+ *   - the FIRST primary `result` event, selected STRUCTURALLY (finding 10):
+ *     origin absent or `origin.kind === "human"` — an allowlist, so a
+ *     background task's result (or any future origin kind) can never be
+ *     mistaken for the main query's accounting. Later results are dropped.
+ *
+ * The result's stdout is the retained lines joined — a synthetic, bounded
+ * envelope `claudeParse` reads exactly like test fixtures. Timeout,
+ * process-group, kill, and spawn semantics match `runStreamJsonl`.
+ */
+function primaryResultOrigin(event) {
+    const origin = event["origin"];
+    if (origin === undefined || origin === null)
+        return true;
+    if (typeof origin === "object" && String(origin["kind"] ?? "") === "human")
+        return true;
+    return false; // task-notification, channel, peer, coordinator, unknown: never the envelope
+}
+export function runClaudeStreamJsonl(file, args, options = {}) {
+    const { cwd } = options;
+    const childEnv = resolveChildEnv(options);
+    return new Promise(resolve => {
+        let child;
+        let container = null;
+        let attachFailure = null;
+        try {
+            const spawned = spawnStream(file, args, options, ["ignore", "pipe", "pipe"], childEnv);
+            child = spawned.child;
+            container = spawned.container;
+            void spawned.attached.then(outcome => { if (!outcome.ok)
+                attachFailure = outcome.detail; });
+        }
+        catch (error) {
+            void reapRejectedSpawn(rejectedChild(error, child), options.processGroup === true).then(() => resolve(refusedResult(error)));
+            return;
+        }
+        if (options.processGroup === true)
+            liveProviders.add(child);
+        registerOwned(options.owner, child);
+        if (options.processGroup === true && container === null)
+            observeProcessTree(child, options);
+        let initLine = null;
+        let initIdentityLine = null;
+        let conflictingInitLine = null;
+        let initSessionId = null;
+        let resultLine = null;
+        let overflowLine = null;
+        let receiptFired = false;
+        let stderr = "";
+        let timedOut = false;
+        let notFound = false;
+        // Latch BEFORE invoking (finding 13): a throwing listener has already
+        // consumed its one firing, and the stream goes on unharmed.
+        const fireReceipt = () => {
+            if (receiptFired || options.onReceipt === undefined) {
+                receiptFired = true;
+                return;
+            }
+            receiptFired = true;
+            try {
+                options.onReceipt();
+            }
+            catch {
+                // A receipt that cannot be recorded must not alter the run; the
+                // note stays honestly unreceipted and re-attaches later.
+            }
+        };
+        const keep = (framed) => {
+            if (framed.overflowed) {
+                // An oversized result is the first primary candidate and therefore
+                // closes the slot fail-closed; an oversized non-result is merely a
+                // fallback that a later parseable primary result can supersede.
+                // Claude's parser trusts the first primary result. When a line is
+                // too large to classify, reserve that first slot fail-closed rather
+                // than let a later small result hide emitted bytes we discarded.
+                const type = leadingJsonObjectType(framed.prefix);
+                if (type !== null && type !== "result") {
+                    if (type !== "system")
+                        return;
+                    const subtype = leadingClaudeSystemSubtype(framed.prefix);
+                    if (subtype !== null && subtype !== "init")
+                        return;
+                    // An init too large to inspect may conceal a conflicting session
+                    // identity. Latch it independently from the primary result so the
+                    // same event set fails regardless of whether it arrived before or
+                    // after the terminal, while a normal terminal can still account
+                    // for the turn's usage.
+                    if (overflowLine === null)
+                        overflowLine = claudeOverflowLine(framed);
+                    return;
+                }
+                if (resultLine === null)
+                    resultLine = claudeOverflowLine(framed);
+                else if (overflowLine === null)
+                    overflowLine = claudeOverflowLine(framed);
+                return;
+            }
+            const line = framed.prefix.toString("utf8");
+            let event;
+            try {
+                event = JSON.parse(line);
+            }
+            catch {
+                return; // not JSON: not an event; dropped
+            }
+            if (event === null || typeof event !== "object")
+                return;
+            const type = String(event["type"] ?? "");
+            if (type === "system" && String(event["subtype"] ?? "") === "init") {
+                if (initLine === null)
+                    initLine = line;
+                const id = transportSessionId(event["session_id"]);
+                let identityWitness = false;
+                if (id !== null) {
+                    if (initSessionId === null) {
+                        initSessionId = id;
+                        initIdentityLine = line;
+                        identityWitness = true;
+                    }
+                    else if (id !== initSessionId && conflictingInitLine === null) {
+                        conflictingInitLine = line;
+                        identityWitness = true;
+                    }
+                    if (identityWitness && options.onSessionId !== undefined) {
+                        try {
+                            options.onSessionId(id);
+                        }
+                        catch {
+                            // A registry that cannot be written must not kill the turn.
+                        }
+                    }
+                }
+            }
+            else if (type === "assistant") {
+                // Top-level only (finding 11): assistant events carry no origin;
+                // parent_tool_use_id is the correlation field, and a subagent's
+                // words prove nothing about the main prompt.
+                const parent = event["parent_tool_use_id"];
+                if (parent === undefined || parent === null)
+                    fireReceipt();
+            }
+            else if (type === "rate_limit_event") {
+                // v105: the plan's usage windows, as Claude says them each turn (the Tasks page's limits).
+                noteLimits(claudeLimitsOf(event));
+            }
+            else if (type === "result" && resultLine === null && primaryResultOrigin(event)) {
+                resultLine = line;
+                // Fallback receipt (finding 11): a SUCCESSFUL main-query completion
+                // entails the prompt ran even if the stream elided assistant
+                // events. Error results never fire — startup death is not delivery.
+                if (event["is_error"] !== true && String(event["subtype"] ?? "") === "success")
+                    fireReceipt();
+            }
+            if (options.onStreamEvent !== undefined) {
+                try {
+                    options.onStreamEvent(event);
+                }
+                catch {
+                    // Observational only: a broken listener never touches the run.
+                }
+            }
+        };
+        const framing = boundedJsonlFramer(JSONL_EVENT_HARD_CAP, keep);
+        const watchdog = streamWatchdog(options, () => {
+            timedOut = true;
+            if (options.processGroup === true)
+                killGroup(child);
+            else
+                child.kill("SIGKILL");
+        });
+        child.stdout?.on("data", (chunk) => {
+            watchdog.touch();
+            framing.push(chunk);
+        });
+        child.stderr?.setEncoding("utf8");
+        child.stderr?.on("data", (chunk) => {
+            watchdog.touch();
+            if (stderr.length < JSONL_STDERR_CAP)
+                stderr += chunk.slice(0, JSONL_STDERR_CAP - stderr.length);
+        });
+        let settled = false;
+        const finish = (code) => {
+            if (settled)
+                return;
+            settled = true;
+            watchdog.stop();
+            liveProviders.delete(child);
+            framing.finish();
+            const lines = [initLine, initIdentityLine, conflictingInitLine, resultLine, overflowLine]
+                .filter((one) => one !== null)
+                .filter((line, index, all) => all.indexOf(line) === index);
+            const settlement = container === null ? Promise.resolve(null) : settleContainer(container, options);
+            void settlement.then(empty => resolve({
+                code: notFound ? NOT_FOUND_CODE : timedOut ? TIMEOUT_CODE : attachFailure !== null || empty === false ? CONTAINMENT_REFUSED_CODE : (code ?? 1),
+                stdout: lines.join("\n"),
+                stderr: empty === false ? `${stderr}\nNative process containment could not prove all descendants exited.`.trim() : attachFailure !== null && stderr === "" ? attachFailure : stderr,
+                timedOut,
+                notFound,
+                ...containmentOf(container, empty, attachFailure),
+            }));
+        };
+        child.on("error", error => {
+            notFound = error.code === "ENOENT";
+            if (stderr === "")
+                stderr = String(error);
+            finish(null);
+        });
+        child.on("close", code => finish(code));
+    });
+}
+// ---- the held session transport (Parity II Phase 2, spec v2 S0a + v6 W9) ----
+/**
+ * Where the supervisor script lives: a plain-.mjs sibling of this module in
+ * BOTH layouts (src/ under tsx, dist/ after build — postbuild copies it).
+ */
+export function supervisorPath() {
+    return fileURLToPath(new URL("./supervisor.mjs", import.meta.url));
+}
+/**
+ * Darwin's sun_path is 104 bytes including the terminator; Linux allows a
+ * hair more. Refusing at spawn beats failing inside bind() with a raw
+ * ENAMETOOLONG after custody was already recorded.
+ */
+export const HELD_SOCKET_PATH_LIMIT = 103;
+export function heldSocketPathProblem(path) {
+    const bytes = Buffer.byteLength(path, "utf8");
+    if (bytes > HELD_SOCKET_PATH_LIMIT) {
+        return `the control socket path is ${bytes} bytes — the platform limit is ${HELD_SOCKET_PATH_LIMIT}: ${path}`;
+    }
+    return null;
+}
+/**
+ * Hold one claude process open across stream-json turns, under a
+ * supervisor whose parenthood makes the eventual kill provable. Returns
+ * once the supervisor's control frame settles the spawn either way.
+ *
+ * No timers live here: the per-turn wall deadline, liveness lapse, and
+ * absolute expiry are the coordinator's exact timers (v2 S1d) — this
+ * transport only moves bytes and counts the protocol's own marks.
+ */
+export function startClaudeHeldSession(file, args, options) {
+    const pathProblem = heldSocketPathProblem(options.socketPath);
+    if (pathProblem !== null) {
+        return Promise.resolve({ ok: false, reason: "socket-path", message: pathProblem });
+    }
+    const childEnv = resolveChildEnv(options) ?? { ...process.env };
+    const events = options.events ?? {};
+    return new Promise(resolveStart => {
+        let supervisor;
+        let container = null;
+        let attachFailure = null;
+        try {
+            // The supervisor spawns INSIDE the OS object, so the agent it holds
+            // and every tool the agent launches are members too: one kill reaches
+            // the whole hold, and the object's empty state proves the hold over.
+            const spawned = spawnContained(process.execPath, [supervisorPath(), file, ...args], {
+                cwd: options.cwd,
+                env: {
+                    ...childEnv,
+                    SO_HELD_SOCKET: options.socketPath,
+                    SO_HELD_COOKIE: options.cookie,
+                    SO_HELD_GRACE_MS: String(options.graceMs ?? 10_000),
+                    SO_HELD_DIAGNOSTIC_FD: currentContainment().mode === "observed" ? "3" : "",
+                },
+                stdio: currentContainment().mode === "observed" ? ["pipe", "pipe", "pipe", "pipe"] : ["pipe", "pipe", "pipe"],
+                detached: false,
+            }, options.owner ?? "held", {
+                beforeSpawn: options.beforeSpawn,
+                onSpawn: options.onSpawn,
+                onContainer: options.onContainer,
+                onContainerEmpty: options.onContainerEmpty,
+                onUnknown: options.onUnknown,
+                fence: options.fence,
+            });
+            supervisor = spawned.child;
+            container = spawned.container;
+            void spawned.attached.then(outcome => { if (!outcome.ok)
+                attachFailure = outcome.detail; });
+            if (container === null)
+                observeProcessTree(supervisor, options);
+        }
+        catch (error) {
+            const left = rejectedChild(error, supervisor);
+            const refused = () => resolveStart({ ok: false, reason: "spawn-failed", message: String(error instanceof SpawnCustodyFailure ? error.reason : error) });
+            if (left === undefined)
+                refused();
+            else {
+                left.once("close", refused);
+                left.on("error", () => { });
+                killGroup(left);
+            }
+            return;
+        }
+        // This pipe belongs to the supervisor, not the agent's relayed stream.
+        // Native containment uses its existing attachment descriptors instead.
+        if (container === null) {
+            const diagnostics = supervisor.stdio[3];
+            let buffer = "", reportedFault = false;
+            const diagnosticFault = () => {
+                if (reportedFault)
+                    return;
+                reportedFault = true;
+                // This channel carries diagnostics only. Its failure cannot invent
+                // lost child identity; genuine supervisor uncertainty still exits126.
+                try {
+                    options.onObservationFailure?.({ phase: "supervisor", operation: "diagnostic-read", code: "SUPERVISOR_DIAGNOSTIC", rootPid: supervisor.pid ?? null, at: new Date().toISOString(), identityUnknown: false });
+                }
+                catch { }
+            };
+            if (diagnostics !== null && diagnostics !== undefined && "on" in diagnostics) {
+                diagnostics.on("data", (chunk) => {
+                    buffer += chunk.toString("utf8");
+                    if (buffer.length > 16_384) {
+                        buffer = "";
+                        diagnosticFault();
+                        return;
+                    }
+                    let cut;
+                    while ((cut = buffer.indexOf("\n")) !== -1) {
+                        const line = buffer.slice(0, cut);
+                        buffer = buffer.slice(cut + 1);
+                        let failure = null;
+                        try {
+                            failure = readProcessObservationFailure(JSON.parse(line));
+                        }
+                        catch { }
+                        if (failure === null) {
+                            diagnosticFault();
+                            continue;
+                        }
+                        try {
+                            options.onObservationFailure?.(failure);
+                        }
+                        catch { /* No diagnostic can certify exit or clear an existing witness. */ }
+                    }
+                });
+                diagnostics.on("error", diagnosticFault);
+                diagnostics.on("end", () => { if (buffer !== "")
+                    diagnosticFault(); });
+            }
+        }
+        heldSupervisors.set(supervisor, "fresh");
+        let settledStart = false;
+        let agentPgid = null;
+        let initSeq = 0;
+        let resultSeq = 0;
+        let sessionSeen = false;
+        let partial = "";
+        let exitResolve = () => { };
+        const exited = new Promise(pass => {
+            exitResolve = pass;
+        });
+        const readyTimer = setTimeout(() => {
+            if (settledStart)
+                return;
+            settledStart = true;
+            try {
+                killGroup(supervisor);
+            }
+            catch {
+                // Already gone.
+            }
+            resolveStart({ ok: false, reason: "ready-timeout", message: "the supervisor never sent its control frame" });
+        }, options.readyTimeoutMs ?? 10_000);
+        const handle = {
+            supervisorPid: null,
+            agentPgid: null,
+            writeTurn(json) {
+                const stdin = supervisor.stdin;
+                if (stdin === null || stdin.destroyed || !stdin.writable)
+                    return false;
+                try {
+                    stdin.write(json.endsWith("\n") ? json : `${json}\n`);
+                    return true;
+                }
+                catch {
+                    return false;
+                }
+            },
+            endInput() {
+                try {
+                    supervisor.stdin?.end();
+                }
+                catch {
+                    // Already closed.
+                }
+            },
+            terminate() {
+                try {
+                    supervisor.kill("SIGTERM");
+                    heldSupervisors.set(supervisor, "termed");
+                }
+                catch {
+                    // Already gone.
+                }
+            },
+            killHard() {
+                try {
+                    killGroup(supervisor);
+                }
+                catch {
+                    // Already gone.
+                }
+            },
+            exited,
+        };
+        const keep = (line) => {
+            if (line.length > JSONL_LINE_CAP)
+                return;
+            let event;
+            try {
+                event = JSON.parse(line);
+            }
+            catch {
+                return;
+            }
+            if (event === null || typeof event !== "object")
+                return;
+            // The control frame settles the start, exactly once, before any
+            // agent byte — the two-hop handshake (v6 W9).
+            if (!settledStart && typeof event["so_supervisor"] === "string") {
+                settledStart = true;
+                clearTimeout(readyTimer);
+                if (event["so_supervisor"] === "ready") {
+                    agentPgid = typeof event["agentPgid"] === "number" ? event["agentPgid"] : null;
+                    handle.agentPgid = agentPgid;
+                    handle.supervisorPid =
+                        typeof event["supervisorPid"] === "number" ? event["supervisorPid"] : (supervisor.pid ?? null);
+                    resolveStart({ ok: true, handle });
+                }
+                else {
+                    const message = typeof event["message"] === "string" ? event["message"] : "spawn failed";
+                    resolveStart({ ok: false, reason: "spawn-failed", message });
+                }
+                return;
+            }
+            if (typeof event["so_supervisor"] === "string")
+                return; // never two frames; drop strays
+            const type = String(event["type"] ?? "");
+            if (type === "system" && String(event["subtype"] ?? "") === "init") {
+                initSeq += 1;
+                if (!sessionSeen && events.onSessionId !== undefined) {
+                    const id = transportSessionId(event["session_id"]);
+                    if (id !== null) {
+                        sessionSeen = true;
+                        try {
+                            events.onSessionId(id);
+                        }
+                        catch {
+                            // A registry that cannot be written must not kill the turn.
+                        }
+                    }
+                }
+                try {
+                    events.onTurnInit?.(initSeq);
+                }
+                catch {
+                    // Observational.
+                }
+            }
+            else if (type === "rate_limit_event") {
+                noteLimits(claudeLimitsOf(event));
+            }
+            else if (type === "result" && primaryResultOrigin(event)) {
+                resultSeq += 1;
+                try {
+                    events.onTurnResult?.(resultSeq, event);
+                }
+                catch {
+                    // Observational.
+                }
+            }
+            try {
+                events.onStreamEvent?.(event);
+            }
+            catch {
+                // Observational only, arc-1 rule unchanged.
+            }
+        };
+        supervisor.stdout?.setEncoding("utf8");
+        supervisor.stdout?.on("data", (chunk) => {
+            partial += chunk;
+            let cut = partial.indexOf("\n");
+            while (cut !== -1) {
+                keep(partial.slice(0, cut));
+                partial = partial.slice(cut + 1);
+                cut = partial.indexOf("\n");
+            }
+            if (partial.length > JSONL_LINE_CAP * 2)
+                partial = partial.slice(-JSONL_LINE_CAP);
+        });
+        supervisor.on("error", error => {
+            heldSupervisors.delete(supervisor);
+            if (!settledStart) {
+                settledStart = true;
+                clearTimeout(readyTimer);
+                resolveStart({ ok: false, reason: "spawn-failed", message: String(error) });
+            }
+            exitResolve({ code: null });
+        });
+        supervisor.on("close", code => {
+            heldSupervisors.delete(supervisor);
+            if (partial.trim() !== "")
+                keep(partial);
+            // The POSIX supervisor could not prove its observed tree drained.
+            // Persist uncertainty before any onExit handler can release custody.
+            if (container === null && code === CONTAINMENT_REFUSED_CODE) {
+                try {
+                    options.onUnknown?.();
+                }
+                catch { /* the observer must not prevent settlement */ }
+            }
+            const settlement = container === null ? Promise.resolve(true) : settleContainer(container, options);
+            void settlement.then(empty => {
+                if (!settledStart) {
+                    settledStart = true;
+                    clearTimeout(readyTimer);
+                    resolveStart({ ok: false, reason: "spawn-failed", message: attachFailure ?? "the supervisor exited before its control frame" });
+                }
+                try {
+                    events.onExit?.({ code: empty ? code : CONTAINMENT_REFUSED_CODE });
+                }
+                catch {
+                    // Observational.
+                }
+                exitResolve({ code: empty ? code : CONTAINMENT_REFUSED_CODE });
+            });
+        });
+    });
+}