toolroll 0.9.62 → 0.9.65

package/dist/exec.d.ts

@@ -6,6 +6,7 @@
  * 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 { type FenceGrants } from "./agent-fence.js";
 import { type ProcessTreeObserver } from "./process-tree.js";
 import { type ContainmentBackendId } from "./containment.js";
 import type { Store } from "./store.js";
@@ -43,8 +44,28 @@ export type RunOptions = ProcessTreeObserver & {
      * inside a sandbox that denies these paths. Applied here, at the one spawn
      * road, so an injected test runner still sees the provider's own argv. */
     fence?: readonly string[];
+    /** What the fence gives back beside those paths (agent-fence.ts FenceGrants). */
+    fenceGrants?: FenceGrants;
+    /** `required`: this spawn runs code a build controls, so it runs inside the OS fence or not at all (never unwrapped
+     * because no backend applies here). The caller passes the fence it must run in. */
+    confinement?: "required";
     /** UTF-8 input for JSONL or buffered process-group transports; closed after delivery. */
     stdin?: string;
+    /** One ACP conversation (runAcpSession only): the brief, the sealed model, and the agent the attestation names. */
+    acp?: AcpRun;
+    /** The conformance check's own admission (the gateway only; set by the check job and nothing else): this run is the
+     * request's current step, admitted by the request instead of an attestation. */
+    acpCheck?: {
+        requestId: number;
+        step: 1 | 2;
+        /** Step 1: the plane's isolation probes — a canary file in the fenced state, and a canary value the launching
+         * environment carries under a key every ACP launch sheds. */
+        isolation?: {
+            file: string;
+            fileCanary: string;
+            envValue: string;
+        };
+    };
     /**
      * Absolute wall-clock ceiling. Keep this for bounded commands and repair
      * turns. Long-running provider sessions use idleTimeoutMs instead: useful
@@ -161,6 +182,19 @@ export type RunOptions = ProcessTreeObserver & {
 export declare class ContainmentRefusal extends Error {
     readonly name = "ContainmentRefusal";
 }
+/**
+ * The command as it runs inside the agent fence (sandbox-exec or bubblewrap wrapping it), or as it is when it has no
+ * fence. A spawn whose confinement is required and that no backend here can wrap is refused (ContainmentRefusal):
+ * nothing runs, and nothing falls back to running it unwrapped.
+ */
+export declare function confined(file: string, args: readonly string[], bag: {
+    fence?: readonly string[] | undefined;
+    fenceGrants?: FenceGrants | undefined;
+    confinement?: "required" | undefined;
+}): {
+    file: string;
+    args: string[];
+};
 /** Run IDs are local to a database. Connections to the same file share
  * custody; separate files and separate in-memory databases never do. */
 export declare function runOwnerTag(store: Store, runId: number): string;
@@ -246,6 +280,53 @@ export declare function runStreamJsonl(file: string, args: readonly string[], op
  * semantics match `runStreamJsonl`.
  */
 export declare function runGeminiStreamJsonl(file: string, args: readonly string[], options?: RunOptions): Promise<ExecResult>;
+/** What runAcpSession needs beyond a process: the conversation's terms (acp-client.ts). */
+export type AcpRun = {
+    prompt: string;
+    model: string;
+    /** The agent's name and version as its attestation recorded them; the handshake must say the same. */
+    expect: {
+        name: string;
+        version: string;
+    } | null;
+    /** Handed the conversation's controls once it starts (the conformance probe cancels with it). */
+    onControl?: (control: AcpControl) => void;
+    /** Each handshake step's deadline (ACP_HANDSHAKE_MS unless a test shortens it). */
+    handshakeMs?: number;
+};
+/** What a caller (the conformance check) may do with a running ACP conversation. */
+export type AcpControl = {
+    /** Ask the agent to stop the prompt in flight; unanswered within `deadlineMs`, the agent is stopped and the
+     * conversation fails (a check's cancel must be answered in time). */
+    cancel: (deadlineMs?: number) => void;
+    /** A fresh, plane-side reading, now, of what the agent itself started and is still running: the live (never zombie)
+     * processes beneath the agent's own process — below any wrapper the fence put around it — with their process
+     * groups. Null when it can't be read here (Windows). */
+    liveDescendants: () => {
+        pid: number;
+        group: number;
+    }[] | null;
+};
+/** How long each shutdown step waits: session/close's answer, then exit after stdin closes, then exit after SIGTERM. */
+export declare const ACP_SHUTDOWN_MS: {
+    readonly close: 2000;
+    readonly eof: 5000;
+    readonly term: 5000;
+};
+/** How long each handshake step (initialize, session/new, choosing the model) may take before the agent is stopped. */
+export declare const ACP_HANDSHAKE_MS = 30000;
+/**
+ * One ACP build conversation over the agent's stdio (docs/plans/acp-adapter.md § Gateway, runner, custody). The
+ * conversation itself is acp-client.ts; this owns the process: the same contained spawn, ownership, descendant
+ * observation, container settlement and watchdog every other runner uses, with both clocks at once.
+ *
+ * After the prompt is answered it shuts the agent down in bounded steps — session/close (when offered), stdin EOF,
+ * SIGTERM to the group, then the forced kill — and returns only when the process has settled, so the gateway's
+ * witness records the real exit. A protocol failure kills at once. A stop, from the gateway's stop watch, kills at
+ * any step. The result's stdout is the conversation's retained record, never the agent's stream; its code is 0 only
+ * when the prompt was answered end_turn and the agent then exited cleanly or on our own signal.
+ */
+export declare function runAcpSession(file: string, args: readonly string[], options?: RunOptions): Promise<ExecResult>;
 /**
  * A live session's account so far (one main result per turn, checked on Claude Code 2.1.290): the latest result's
  * session, ending, words and cost — `total_cost_usd` is already the session's running total — with the usage token

package/dist/exec.js

@@ -6,9 +6,11 @@
  * 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 { ACP_LINE_CAP, createAcpConversation } from "./acp-client.js";
 import { linuxFenceAvailable, linuxFenced, macosFenceAvailable, macosFenced } from "./agent-fence.js";
-import { execFile, spawn } from "node:child_process";
-import { realpathSync } from "node:fs";
+import { execFile, execFileSync, spawn } from "node:child_process";
+import { readFileSync, realpathSync } from "node:fs";
+import { join } from "node:path";
 import { observeProcessTree, stopProcessTree } from "./process-tree.js";
 import { jsonlDiscriminants } from "./jsonl-discriminants.js";
 import { createContainer, currentContainment } from "./containment.js";
@@ -45,6 +47,24 @@ const containers = new WeakMap();
 export class ContainmentRefusal extends Error {
     name = "ContainmentRefusal";
 }
+/**
+ * The command as it runs inside the agent fence (sandbox-exec or bubblewrap wrapping it), or as it is when it has no
+ * fence. A spawn whose confinement is required and that no backend here can wrap is refused (ContainmentRefusal):
+ * nothing runs, and nothing falls back to running it unwrapped.
+ */
+export function confined(file, args, bag) {
+    const fence = bag.fence ?? [];
+    if (fence.length > 0 && macosFenceAvailable())
+        return macosFenced(file, args, fence, bag.fenceGrants);
+    if (fence.length > 0 && linuxFenceAvailable())
+        return linuxFenced(file, args, fence, bag.fenceGrants);
+    if (bag.confinement === "required") {
+        throw new ContainmentRefusal(fence.length === 0
+            ? "This process must run inside the agent fence, and it was given none."
+            : "This machine can't confine a build (no macOS sandbox, no working bubblewrap), so nothing was started.");
+    }
+    return { file, args: [...args] };
+}
 /** A spawn callback refused custody AFTER the child existed: the caller
  * must reap exactly this child before answering. */
 class SpawnCustodyFailure extends Error {
@@ -72,10 +92,7 @@ function rejectedChild(error, child) {
  */
 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));
+    ({ file, args } = confined(file, args, bag));
     // 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;
@@ -224,7 +241,7 @@ function containmentOf(container, empty, attachFailure) {
 }
 /** 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, onSpawnFailed: options.onSpawnFailed, onContainer: options.onContainer, onContainerEmpty: options.onContainerEmpty, onUnknown: options.onUnknown, fence: options.fence }, options.processGroup === true);
+    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, onSpawnFailed: options.onSpawnFailed, onContainer: options.onContainer, onContainerEmpty: options.onContainerEmpty, onUnknown: options.onUnknown, fence: options.fence, fenceGrants: options.fenceGrants, confinement: options.confinement }, options.processGroup === true);
 }
 /** The refusal-before-spawn shape shared by every containable transport. */
 function refusedResult(error) {
@@ -521,6 +538,8 @@ export function run(file, args, options = {}) {
             ...(options.onStdout === undefined ? {} : { onStdout: options.onStdout }),
             ...(options.onStderr === undefined ? {} : { onStderr: options.onStderr }),
             ...(options.fence === undefined ? {} : { fence: options.fence }),
+            ...(options.fenceGrants === undefined ? {} : { fenceGrants: options.fenceGrants }),
+            ...(options.confinement === undefined ? {} : { confinement: options.confinement }),
             ...(options.onDescendant === undefined ? {} : { onDescendant: options.onDescendant }),
             ...(options.onDescendantWriteFailure === undefined ? {} : { onDescendantWriteFailure: options.onDescendantWriteFailure }),
             ...(options.onDescendantExit === undefined ? {} : { onDescendantExit: options.onDescendantExit }),
@@ -530,8 +549,19 @@ export function run(file, args, options = {}) {
             ...(options.onContainerEmpty === undefined ? {} : { onContainerEmpty: options.onContainerEmpty }),
         }));
     }
+    // The plain road wraps exactly as the process-group road does: a fence given here is never dropped, and a spawn
+    // whose confinement is required and can't be wrapped refuses before anything runs.
+    let wrapped;
+    try {
+        wrapped = confined(file, args, options);
+    }
+    catch (error) {
+        if (!(error instanceof ContainmentRefusal))
+            throw error;
+        return Promise.resolve({ code: CONTAINMENT_REFUSED_CODE, stdout: "", stderr: error.message, timedOut: false, notFound: false, containment: { refused: error.message } });
+    }
     return retryTransientSpawn(() => new Promise(resolve => {
-        execFile(file, [...args], {
+        execFile(wrapped.file, wrapped.args, {
             cwd,
             timeout: timeoutMs,
             maxBuffer,
@@ -563,7 +593,7 @@ function runBufferedGroup(file, args, bag) {
         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, onSpawnFailed: bag.onSpawnFailed, onContainer: bag.onContainer, onContainerEmpty: bag.onContainerEmpty, onUnknown: bag.onUnknown, fence: bag.fence });
+            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, onSpawnFailed: bag.onSpawnFailed, onContainer: bag.onContainer, onContainerEmpty: bag.onContainerEmpty, onUnknown: bag.onUnknown, fence: bag.fence, fenceGrants: bag.fenceGrants, confinement: bag.confinement });
             child = spawned.child;
             container = spawned.container;
             attached = spawned.attached;
@@ -1402,6 +1432,335 @@ export function runGeminiStreamJsonl(file, args, options = {}) {
         child.on("close", code => finish(code));
     });
 }
+/** One process listing: ids, group, state and command name only (never arguments — they can carry a brief). */
+function processRows() {
+    try {
+        return execFileSync("/bin/ps", ["-axo", "pid=,ppid=,pgid=,stat=,comm="], { encoding: "utf8", timeout: 2_000, maxBuffer: 8 * 1024 * 1024 })
+            .split("\n").flatMap(line => {
+            const parts = /^\s*(\d+)\s+(\d+)\s+(\d+)\s+(\S+)\s+(.*)$/.exec(line);
+            return parts === null ? [] : [{ pid: Number(parts[1]), parent: Number(parts[2]), group: Number(parts[3]), state: parts[4], name: parts[5].trim() }];
+        });
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * What the agent started and is still running: from `root` (the spawned process — the agent itself, or a fence
+ * wrapper around it), down to the agent's own process (the first whose command is the agent's launch, `names`), then
+ * every live, non-zombie process beneath it, with its group. The agent itself and any wrapper are never counted.
+ */
+function liveUnderAgent(root, names) {
+    const rows = processRows();
+    if (rows === null)
+        return null;
+    const children = new Map();
+    for (const row of rows)
+        children.set(row.parent, [...(children.get(row.parent) ?? []), row]);
+    const self = rows.find(row => row.pid === root);
+    const named = (row) => names.some(name => row.name === name || row.name.endsWith(`/${name}`));
+    // The agent: the root when it is the agent (macOS sandbox-exec execs in place), else the first named descendant.
+    let agent = self !== undefined && named(self) ? root : null;
+    const pending = [...(children.get(root) ?? [])];
+    while (agent === null && pending.length > 0) {
+        const row = pending.shift();
+        if (named(row))
+            agent = row.pid;
+        else
+            pending.push(...(children.get(row.pid) ?? []));
+    }
+    if (agent === null)
+        return [];
+    const found = [];
+    const below = [...(children.get(agent) ?? [])];
+    while (below.length > 0) {
+        const row = below.pop();
+        if (!row.state.startsWith("Z"))
+            found.push({ pid: row.pid, group: row.group });
+        below.push(...(children.get(row.pid) ?? []));
+    }
+    return found;
+}
+/** How long each shutdown step waits: session/close's answer, then exit after stdin closes, then exit after SIGTERM. */
+export const ACP_SHUTDOWN_MS = { close: 2_000, eof: 5_000, term: 5_000 };
+/** How long each handshake step (initialize, session/new, choosing the model) may take before the agent is stopped. */
+export const ACP_HANDSHAKE_MS = 30_000;
+/** After the agent itself has exited, how long its pipes may stay open (a descendant holding them) before they are closed. */
+const ACP_PIPES_AFTER_EXIT_MS = 5_000;
+/** SIGTERM the child's process group (POSIX) or the child alone; a container's own stop is the forced one, later. */
+function termGroup(child) {
+    const pid = child.pid;
+    try {
+        if (pid !== undefined && process.platform !== "win32")
+            process.kill(-pid, "SIGTERM");
+        else
+            child.kill("SIGTERM");
+    }
+    catch {
+        // Already gone.
+    }
+}
+/**
+ * One ACP build conversation over the agent's stdio (docs/plans/acp-adapter.md § Gateway, runner, custody). The
+ * conversation itself is acp-client.ts; this owns the process: the same contained spawn, ownership, descendant
+ * observation, container settlement and watchdog every other runner uses, with both clocks at once.
+ *
+ * After the prompt is answered it shuts the agent down in bounded steps — session/close (when offered), stdin EOF,
+ * SIGTERM to the group, then the forced kill — and returns only when the process has settled, so the gateway's
+ * witness records the real exit. A protocol failure kills at once. A stop, from the gateway's stop watch, kills at
+ * any step. The result's stdout is the conversation's retained record, never the agent's stream; its code is 0 only
+ * when the prompt was answered end_turn and the agent then exited cleanly or on our own signal.
+ */
+export function runAcpSession(file, args, options = {}) {
+    const acp = options.acp;
+    if (acp === undefined)
+        return Promise.resolve({ code: CONTAINMENT_REFUSED_CODE, stdout: "", stderr: "an ACP run needs its conversation terms", timedOut: false, notFound: false });
+    const childEnv = resolveChildEnv(options);
+    return new Promise(resolve => {
+        let child;
+        let container = null;
+        let attachFailure = null;
+        try {
+            const spawned = spawnStream(file, args, options, ["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);
+        const conversation = createAcpConversation({ cwd: options.cwd ?? process.cwd(), prompt: acp.prompt, model: acp.model, expect: acp.expect });
+        // The agent's own process, as a listing names it: the launched file, or the script a pinned interpreter runs.
+        const agentNames = [...new Set([file, ...args.slice(0, 2)].filter(one => one.startsWith("/")).map(one => one.split("/").pop()).filter(one => one !== ""))];
+        let stderr = "";
+        let timedOut = false;
+        let notFound = false;
+        let settled = false;
+        let shuttingDown = false;
+        /** The signals the plane itself sent after the prompt was answered, by its own shutdown ladder: an exit by one of
+         * those is clean. A stop or a timeout kills through other roads and never sets these. */
+        let termAfterTerminal = false;
+        let killAfterTerminal = false;
+        /** How the process came to end, for the record: on its own (before or after stdin closed), or by our signal. */
+        let endedBy = "self";
+        let announced = null;
+        const timers = [];
+        const later = (ms, fn) => { const timer = setTimeout(fn, ms); timer.unref?.(); timers.push(timer); };
+        const write = (lines) => {
+            for (const one of lines) {
+                if (child.stdin === null || child.stdin.destroyed || child.stdin.writableEnded)
+                    return;
+                try {
+                    child.stdin.write(`${one}\n`);
+                }
+                catch { /* the agent closed its stdin: its exit decides */ }
+            }
+        };
+        const forceKill = () => {
+            endedBy = "kill";
+            if (options.processGroup === true)
+                killGroup(child);
+            else
+                child.kill("SIGKILL");
+        };
+        /** Each handshake step has its own deadline, beside the run's clocks. */
+        let handshakePhase = null;
+        const armHandshake = () => {
+            const phase = conversation.phase();
+            if (phase === handshakePhase || (phase !== "initialize" && phase !== "session" && phase !== "model"))
+                return;
+            handshakePhase = phase;
+            const limit = acp.handshakeMs ?? ACP_HANDSHAKE_MS;
+            later(limit, () => {
+                if (settled || conversation.phase() !== phase)
+                    return;
+                conversation.refuse(`the agent took more than ${limit / 1000} s to answer ${phase === "initialize" ? "initialize" : phase === "session" ? "session/new" : "the model choice"}`);
+                forceKill();
+            });
+        };
+        const exited = () => child.exitCode !== null || child.signalCode !== null;
+        const shutdown = () => {
+            if (shuttingDown)
+                return;
+            shuttingDown = true;
+            if (conversation.phase() === "failed") {
+                forceKill();
+                return;
+            }
+            const endInput = () => {
+                if (exited())
+                    return;
+                try {
+                    child.stdin?.end();
+                }
+                catch { /* gone */ }
+                endedBy = "eof";
+                later(ACP_SHUTDOWN_MS.eof, () => {
+                    if (exited())
+                        return;
+                    termAfterTerminal = conversation.phase() === "ended";
+                    endedBy = "term";
+                    termGroup(child);
+                    later(ACP_SHUTDOWN_MS.term, () => {
+                        if (exited())
+                            return;
+                        killAfterTerminal = conversation.phase() === "ended";
+                        forceKill();
+                    });
+                });
+            };
+            const close = conversation.close();
+            if (close.length === 0) {
+                endInput();
+                return;
+            }
+            write(close);
+            const started = Date.now();
+            const waitClose = () => {
+                if (conversation.closeAnswered() || Date.now() - started >= ACP_SHUTDOWN_MS.close || exited())
+                    endInput();
+                else
+                    later(50, waitClose);
+            };
+            waitClose();
+        };
+        const onLine = (framed) => {
+            if (settled)
+                return;
+            armHandshake();
+            const reaction = framed.overflowed
+                ? (conversation.refuse("the agent wrote a line too long to read"), { send: [], live: [] })
+                : conversation.receive(framed.prefix.toString("utf8"));
+            write(reaction.send);
+            const id = conversation.sessionId();
+            if (id !== null && announced === null) {
+                announced = id;
+                try {
+                    options.onSessionId?.(id);
+                }
+                catch { /* a registry that cannot be written must not kill the turn */ }
+            }
+            for (const update of reaction.live) {
+                try {
+                    options.onStreamEvent?.({ acp: update });
+                }
+                catch { /* observational only */ }
+            }
+            const phase = conversation.phase();
+            if (phase === "failed" || phase === "ended")
+                shutdown();
+            else
+                armHandshake();
+        };
+        const framing = boundedJsonlFramer(ACP_LINE_CAP, onLine);
+        const watchdog = streamWatchdog(options, () => {
+            timedOut = true;
+            forceKill();
+        });
+        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);
+        });
+        child.stdin?.on("error", () => { });
+        write(conversation.start());
+        armHandshake();
+        try {
+            acp.onControl?.({
+                cancel: (deadlineMs) => {
+                    write(conversation.cancel());
+                    if (deadlineMs !== undefined)
+                        later(deadlineMs, () => {
+                            if (settled || conversation.terminal() !== null)
+                                return;
+                            conversation.refuse(`the agent didn't answer the cancel within ${Math.round(deadlineMs / 1000)} s`);
+                            forceKill();
+                        });
+                },
+                liveDescendants: () => process.platform === "win32" ? null : exited() || child.pid === undefined ? [] : liveUnderAgent(child.pid, agentNames),
+            });
+        }
+        catch { /* the caller's own failure */ }
+        // The moment the agent itself exits, what it left in its own group ends with it — not at "close", which a
+        // descendant holding the agent's pipes can postpone forever; and if those pipes are still open shortly after, they
+        // are closed, so settlement never waits on a stray. Escaped groups are the custody observer's, as for every runner.
+        let leftover = false;
+        child.on("exit", () => {
+            if (options.processGroup === true && container === null && child.pid !== undefined && process.platform !== "win32") {
+                try {
+                    process.kill(-child.pid, 0);
+                    leftover = true;
+                }
+                catch {
+                    leftover = false;
+                }
+                try {
+                    process.kill(-child.pid, "SIGKILL");
+                }
+                catch { /* none left */ }
+            }
+            later(ACP_PIPES_AFTER_EXIT_MS, () => {
+                if (settled)
+                    return;
+                for (const pipe of [child.stdout, child.stderr, child.stdin]) {
+                    try {
+                        pipe?.destroy();
+                    }
+                    catch { /* gone */ }
+                }
+            });
+        });
+        const finish = (code, signal) => {
+            if (settled)
+                return;
+            // The last record, even one with no newline after it, is read before anything is decided.
+            framing.finish();
+            settled = true;
+            for (const timer of timers)
+                clearTimeout(timer);
+            watchdog.stop();
+            liveProviders.delete(child);
+            // Whatever the agent started in its own group and left running ends with it (a group id can't be reused while any
+            // member lives, so this reaches only what it left). Escaped groups are the custody observer's, as for every runner.
+            const terminal = conversation.terminal();
+            const answered = terminal !== null && "stopReason" in terminal && terminal.stopReason === "end_turn" && conversation.failure() === null;
+            // A clean exit after the answer, or an exit by the plane's own post-answer signal (its shutdown ladder's SIGTERM,
+            // then SIGKILL), is success; anything else — a stop, a timeout, another signal — is its code.
+            const ownSignal = (termAfterTerminal && (signal === "SIGTERM" || code === 143)) || (killAfterTerminal && (signal === "SIGKILL" || code === 137));
+            const exitCode = answered && !timedOut && (code === 0 || ownSignal) ? 0 : (code ?? 1);
+            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 : exitCode,
+                // The runner's own account of the ending rides last: a type no agent can emit.
+                stdout: `${conversation.retained()}${JSON.stringify({ type: "acp.exit", how: endedBy, leftover: leftover || empty === false, timedOut })}\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 => {
+            endedBy = "error";
+            notFound = error.code === "ENOENT";
+            if (stderr === "")
+                stderr = String(error);
+            finish(null, null);
+        });
+        child.on("close", (code, signal) => finish(code, signal));
+    });
+}
 const TRUNCATION_MARKER = "…[truncated]";
 /**
  * One serialized synthetic line, guaranteed ≤ JSONL_LINE_CAP in UTF-8

package/dist/export-ui.js

@@ -2,10 +2,10 @@
  * Settings → Data (v105): an instance operator downloads everything Standing
  * Orders knows as one .zip. One form: the password, typed again, and a button.
  */
-import { html, postForm } from "./html.js";
+import { html, postForm, reauth } from "./html.js";
 export const EXPORT_CSS = `.data-export{max-width:720px;min-width:0}.data-export label{display:grid;gap:4px;margin:14px 0 0;font-size:.875rem}` +
     `.data-export input[type=password]{width:100%;max-width:360px;box-sizing:border-box}.data-export button[type=submit]{margin-top:14px;min-height:44px;white-space:nowrap}`;
 export function dataExportHtml(notice) {
     const note = notice.problem ? html `<p class="problem" role="alert">${notice.problem}</p>` : "";
-    return html `<section class="data-export">${note}<p>Everything Toolroll knows, as one .zip: projects, tasks, runs and cost, the action ledger, evidence packs, chats, flows, subagents and settings. Passwords, keys and tokens are never included.</p>${postForm("/settings/data", html `<label>Your Toolroll password<input type="password" name="password" autocomplete="current-password" required></label><button type="submit">Download export</button>`)}<p class="meta">The same export from the command line: <code>toolroll export --out &lt;path&gt; [--zip]</code></p></section>`;
+    return html `<section class="data-export">${note}<p>Everything Toolroll knows, as one .zip: projects, tasks, runs and cost, the action ledger, evidence packs, chats, flows, subagents and settings. Passwords, keys and tokens are never included.</p>${postForm("/settings/data", html `${reauth(html `<label>Your Toolroll password<input type="password" name="password" autocomplete="current-password" required></label>`)}<button type="submit">Download export</button>`)}<p class="meta">The same export from the command line: <code>toolroll export --out &lt;path&gt; [--zip]</code></p></section>`;
 }

package/dist/flow-code.d.ts

@@ -1,11 +1,11 @@
 import type { Runner } from "./backend.js";
 import type { FlowScriptRow } from "./store.js";
+import { projectFile } from "./project-file.js";
+export { projectFile };
 export { LANGUAGE_WORDS, SCRIPT_LANGUAGES, type ScriptLanguage } from "./flows.js";
 /** A step's result on the card: what the script printed, up to what a step passes on (the end, when longer; the whole
  * is in the step's log). */
 export declare const CODE_OUTPUT_CHARS: 12000;
-/** A project file a script names, if it is one: inside the project, and there. */
-export declare function projectFile(root: string, path: string): string | null;
 export type CodeRun = {
     script: FlowScriptRow;
     /** Where it runs, and the project folder a file script is found in. */

package/dist/flow-code.js

@@ -15,13 +15,15 @@
  *   keys are out of reach), under a time limit, with the setup's plain
  *   environment rather than this process's.
  */
-import { chmodSync, existsSync, mkdirSync, realpathSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { chmodSync, existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
 import { randomBytes } from "node:crypto";
-import { isAbsolute, join, relative } from "node:path";
+import { join } from "node:path";
 import { SETUP_ENV_ALLOWLIST, SETUP_ENV_DENYLIST } from "./builder.js";
 import { redactSecretLines, scanForSecrets } from "./evidence.js";
 import { scrubSecrets } from "./flow-secrets.js";
 import { TEXT_LIMITS } from "./text-limits.js";
+import { projectFile } from "./project-file.js";
+export { projectFile };
 import { LANGUAGE_WORDS } from "./flows.js";
 export { LANGUAGE_WORDS, SCRIPT_LANGUAGES } from "./flows.js";
 const EXTENSION = { shell: "sh", python: "py", node: "mjs" };
@@ -33,19 +35,6 @@ const LOG_CHARS = 64_000;
 function runtimeOf(language, file) {
     return language === "python" ? { file: "python3", args: [file] } : language === "node" ? { file: process.execPath, args: [file] } : { file: "/bin/sh", args: [file] };
 }
-/** A project file a script names, if it is one: inside the project, and there. */
-export function projectFile(root, path) {
-    if (path === "" || isAbsolute(path) || path.split(/[\\/]/).includes(".."))
-        return null;
-    try {
-        const base = realpathSync(root), full = realpathSync(join(root, path));
-        const inside = relative(base, full);
-        return inside !== "" && !inside.startsWith("..") && !isAbsolute(inside) && statSync(full).isFile() ? full : null;
-    }
-    catch {
-        return null;
-    }
-}
 /** What it printed, without key-shaped lines or saved secrets, and the goto line taken off the end. */
 export function codeOutput(stdout, secrets) {
     const clean = scrubSecrets(stdout.replace(/\r\n?/g, "\n"), secrets);