agentplane 0.3.7 → 0.3.8

package/dist/runner/policy-decision.js

@@ -0,0 +1,89 @@
+import { readRecipeRunProfile } from "./adapters/recipe-run-profile.js";
+function toRequestedMap(profile) {
+    if (!profile)
+        return {};
+    const requested = {};
+    for (const [key, value] of Object.entries(profile)) {
+        if (value !== undefined) {
+            requested[key] = value;
+        }
+    }
+    return requested;
+}
+export function buildRunnerPolicyDecision(opts) {
+    const profile = readRecipeRunProfile(opts.recipe);
+    const requested = toRequestedMap(profile);
+    const effective = {};
+    const fields = {};
+    const capabilityFields = opts.capabilities?.fields ?? {};
+    for (const [fieldName, capability] of Object.entries(capabilityFields)) {
+        const hasRequest = Object.hasOwn(requested, fieldName);
+        const requestedValue = hasRequest ? requested[fieldName] : undefined;
+        const decision = {
+            requested: requestedValue,
+            status: "not_requested",
+            capability_level: capability.level,
+            channel: capability.channel,
+            ...(capability.supported_values ? { supported_values: capability.supported_values } : {}),
+            ...(capability.note ? { note: capability.note } : {}),
+        };
+        if (!hasRequest) {
+            fields[fieldName] = decision;
+            continue;
+        }
+        if (capability.level === "native" || capability.level === "wrapper") {
+            if (Array.isArray(capability.supported_values) &&
+                typeof requestedValue === "string" &&
+                !capability.supported_values.includes(requestedValue)) {
+                fields[fieldName] = {
+                    ...decision,
+                    status: "unsupported",
+                };
+                continue;
+            }
+            effective[fieldName] = requestedValue;
+            fields[fieldName] = {
+                ...decision,
+                effective: requestedValue,
+                status: "enforced",
+            };
+            continue;
+        }
+        fields[fieldName] = {
+            ...decision,
+            status: capability.level === "advisory" ? "advisory" : "unsupported",
+        };
+    }
+    for (const [fieldName, requestedValue] of Object.entries(requested)) {
+        if (Object.hasOwn(fields, fieldName))
+            continue;
+        fields[fieldName] = {
+            requested: requestedValue,
+            status: "unsupported",
+            capability_level: "unsupported",
+            channel: "none",
+        };
+    }
+    return {
+        adapter_id: opts.adapter_id,
+        requested,
+        effective,
+        fields,
+        refusal_reason: null,
+    };
+}
+export function applyRunnerPolicyRefusal(opts) {
+    return {
+        ...opts.decision,
+        refusal_reason: {
+            code: opts.error.code,
+            message: opts.error.message,
+            ...(typeof opts.error.context?.policy_field === "string"
+                ? { policy_field: opts.error.context.policy_field }
+                : {}),
+            ...(Object.hasOwn(opts.error.context ?? {}, "declared_value")
+                ? { declared_value: opts.error.context?.declared_value }
+                : {}),
+        },
+    };
+}

package/dist/runner/policy-display.d.ts

@@ -0,0 +1,4 @@
+import type { RunnerAdapterCapabilities, RunnerPolicyDecision } from "./types.js";
+export declare function formatRunnerCapabilitySummaryLines(capabilities: RunnerAdapterCapabilities | undefined): string[];
+export declare function formatRunnerPolicyFieldSummaryLines(decision: RunnerPolicyDecision | undefined): string[];
+//# sourceMappingURL=policy-display.d.ts.map

package/dist/runner/policy-display.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy-display.d.ts","sourceRoot":"","sources":["../../src/runner/policy-display.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,yBAAyB,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAYlF,wBAAgB,kCAAkC,CAChD,YAAY,EAAE,yBAAyB,GAAG,SAAS,GAClD,MAAM,EAAE,CAgBV;AAED,wBAAgB,mCAAmC,CACjD,QAAQ,EAAE,oBAAoB,GAAG,SAAS,GACzC,MAAM,EAAE,CAmBV"}

package/dist/runner/policy-display.js

@@ -0,0 +1,41 @@
+function appendPart(parts, key, value) {
+    if (!value)
+        return;
+    parts.push(`${key}=${value}`);
+}
+function renderValue(value) {
+    if (value === undefined)
+        return null;
+    return JSON.stringify(value);
+}
+export function formatRunnerCapabilitySummaryLines(capabilities) {
+    if (!capabilities)
+        return [];
+    return Object.entries(capabilities.fields).map(([fieldName, capability]) => {
+        const parts = [
+            `capability[${fieldName}]:`,
+            `level=${capability.level}`,
+            `channel=${capability.channel}`,
+        ];
+        appendPart(parts, "supported", capability.supported_values?.length ? capability.supported_values.join(",") : null);
+        appendPart(parts, "note", capability.note ?? null);
+        return parts.join(" ");
+    });
+}
+export function formatRunnerPolicyFieldSummaryLines(decision) {
+    if (!decision)
+        return [];
+    return Object.entries(decision.fields).map(([fieldName, field]) => {
+        const parts = [
+            `policy_field[${fieldName}]:`,
+            `status=${field.status}`,
+            `capability=${field.capability_level}`,
+            `channel=${field.channel}`,
+        ];
+        appendPart(parts, "requested", renderValue(field.requested));
+        appendPart(parts, "effective", renderValue(field.effective));
+        appendPart(parts, "supported", field.supported_values?.length ? field.supported_values.join(",") : null);
+        appendPart(parts, "note", field.note ?? null);
+        return parts.join(" ");
+    });
+}

package/dist/runner/process-supervision.d.ts

@@ -0,0 +1,48 @@
+import type { RunnerInvocation, RunnerProcessSignal, RunnerRunState, RunnerTimeoutReason } from "./types.js";
+export type SupervisedProcessResult = {
+    exit_code: number | null;
+    exit_signal: RunnerProcessSignal | null;
+    stdout_tail: string;
+    stderr_tail: string;
+    stdout_bytes: number;
+    stderr_bytes: number;
+    pid: number | null;
+    started_at: string;
+    ended_at: string;
+    cancel_requested_at: string | null;
+    cancel_signal: RunnerProcessSignal | null;
+    timeout_reason: RunnerTimeoutReason | null;
+    timeout_requested_at: string | null;
+    terminate_sent_at: string | null;
+    kill_sent_at: string | null;
+    force_killed: boolean;
+    heartbeat_at: string;
+    trace_artifact_path: string | null;
+    trace_archive_path: string | null;
+    stderr_artifact_path: string | null;
+    stderr_archive_path: string | null;
+};
+export type ObservedProcessIdentity = {
+    pid: number;
+    command: string | null;
+    started_at: string | null;
+};
+export declare function exitCodeForSignal(signal: RunnerProcessSignal | null): number | null;
+export declare function isProcessAlive(pid: number): boolean;
+export declare function readObservedProcessIdentity(pid: number): Promise<ObservedProcessIdentity | null>;
+export declare function waitForProcessExit(opts: {
+    pid: number;
+    timeout_ms: number;
+    poll_ms?: number;
+}): Promise<boolean>;
+export declare function runSupervisedProcess(opts: {
+    invocation: RunnerInvocation;
+    stdin_text: string;
+    start_message: string;
+}): Promise<SupervisedProcessResult>;
+export declare function waitForRunnerStateStop(opts: {
+    state_path: string;
+    timeout_ms: number;
+    poll_ms?: number;
+}): Promise<RunnerRunState | null>;
+//# sourceMappingURL=process-supervision.d.ts.map

package/dist/runner/process-supervision.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"process-supervision.d.ts","sourceRoot":"","sources":["../../src/runner/process-supervision.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EACV,gBAAgB,EAChB,mBAAmB,EACnB,cAAc,EAEd,mBAAmB,EACpB,MAAM,YAAY,CAAC;AAapB,MAAM,MAAM,uBAAuB,GAAG;IACpC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,WAAW,EAAE,mBAAmB,GAAG,IAAI,CAAC;IACxC,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,mBAAmB,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,aAAa,EAAE,mBAAmB,GAAG,IAAI,CAAC;IAC1C,cAAc,EAAE,mBAAmB,GAAG,IAAI,CAAC;IAC3C,oBAAoB,EAAE,MAAM,GAAG,IAAI,CAAC;IACpC,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,YAAY,EAAE,OAAO,CAAC;IACtB,YAAY,EAAE,MAAM,CAAC;IACrB,mBAAmB,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,kBAAkB,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,oBAAoB,EAAE,MAAM,GAAG,IAAI,CAAC;IACpC,mBAAmB,EAAE,MAAM,GAAG,IAAI,CAAC;CACpC,CAAC;AAEF,MAAM,MAAM,uBAAuB,GAAG;IACpC,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B,CAAC;AA2EF,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,mBAAmB,GAAG,IAAI,GAAG,MAAM,GAAG,IAAI,CAOnF;AAED,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAUnD;AAED,wBAAsB,2BAA2B,CAC/C,GAAG,EAAE,MAAM,GACV,OAAO,CAAC,uBAAuB,GAAG,IAAI,CAAC,CA6BzC;AAED,wBAAsB,kBAAkB,CAAC,IAAI,EAAE;IAC7C,GAAG,EAAE,MAAM,CAAC;IACZ,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,GAAG,OAAO,CAAC,OAAO,CAAC,CAQnB;AAED,wBAAsB,oBAAoB,CAAC,IAAI,EAAE;IAC/C,UAAU,EAAE,gBAAgB,CAAC;IAC7B,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;CACvB,GAAG,OAAO,CAAC,uBAAuB,CAAC,CA+UnC;AAED,wBAAsB,sBAAsB,CAAC,IAAI,EAAE;IACjD,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,GAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAUjC"}

package/dist/runner/process-supervision.js

@@ -0,0 +1,490 @@
+import { execFile, spawn } from "node:child_process";
+import { appendFileSync } from "node:fs";
+import { promisify } from "node:util";
+import { appendRunnerEvent, evolveRunnerRunState, readRunnerRunState, writeRunnerRunState, } from "./artifacts.js";
+import { finalizeTraceArtifact, redactTraceText } from "./trace-artifacts.js";
+import { createRunnerTraceEvent, serializeRunnerTraceEvent } from "./trace.js";
+const SUPPORTED_SIGNALS = new Set([
+    "SIGHUP",
+    "SIGINT",
+    "SIGQUIT",
+    "SIGTERM",
+    "SIGKILL",
+]);
+const execFileAsync = promisify(execFile);
+function renderInvocationCommand(invocation) {
+    const commandLine = invocation.argv
+        .map((part) => part.trim())
+        .filter((part) => part.length > 0)
+        .join(" ");
+    return commandLine.length > 0 ? commandLine : null;
+}
+function normalizeSignal(signal) {
+    if (!signal)
+        return null;
+    return SUPPORTED_SIGNALS.has(signal)
+        ? signal
+        : null;
+}
+function mergeSupervisionState(current, patch) {
+    return {
+        ...current,
+        ...Object.fromEntries(Object.entries(patch).filter(([, value]) => value !== undefined)),
+    };
+}
+function buildInvocationEventData(invocation, pid) {
+    return {
+        executable: invocation.argv[0] ?? null,
+        argv_count: invocation.argv.length,
+        cwd: invocation.run_dir,
+        env_keys: Object.keys(invocation.env).toSorted(),
+        has_bootstrap_path: typeof invocation.bootstrap_path === "string" && invocation.bootstrap_path.trim().length > 0,
+        has_output_last_message_path: typeof invocation.output_last_message_path === "string" &&
+            invocation.output_last_message_path.trim().length > 0,
+        has_trace_path: typeof invocation.trace_path === "string" && invocation.trace_path.trim().length > 0,
+        has_stderr_path: typeof invocation.stderr_path === "string" && invocation.stderr_path.trim().length > 0,
+        trace_policy: invocation.trace_policy,
+        timeout_policy: invocation.timeout_policy,
+        pid,
+    };
+}
+function appendTail(current, incoming, maxBytes) {
+    const combined = Buffer.from(`${current}${incoming}`, "utf8");
+    if (combined.length <= maxBytes)
+        return combined.toString("utf8");
+    return combined.subarray(combined.length - maxBytes).toString("utf8");
+}
+function splitCompletedLines(buffer) {
+    const lines = [];
+    let start = 0;
+    while (start < buffer.length) {
+        const newlineIndex = buffer.indexOf("\n", start);
+        if (newlineIndex === -1) {
+            return { lines, remainder: buffer.slice(start) };
+        }
+        let line = buffer.slice(start, newlineIndex);
+        if (line.endsWith("\r")) {
+            line = line.slice(0, -1);
+        }
+        lines.push(line);
+        start = newlineIndex + 1;
+    }
+    return { lines, remainder: "" };
+}
+export function exitCodeForSignal(signal) {
+    if (signal === "SIGINT")
+        return 130;
+    if (signal === "SIGTERM")
+        return 143;
+    if (signal === "SIGKILL")
+        return 137;
+    if (signal === "SIGHUP")
+        return 129;
+    if (signal === "SIGQUIT")
+        return 131;
+    return null;
+}
+export function isProcessAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        const code = err?.code;
+        if (code === "ESRCH")
+            return false;
+        if (code === "EPERM")
+            return true;
+        throw err;
+    }
+}
+export async function readObservedProcessIdentity(pid) {
+    try {
+        const { stdout } = await execFileAsync("ps", ["-o", "lstart=,command=", "-p", String(pid)], {
+            encoding: "utf8",
+        });
+        const line = stdout
+            .split("\n")
+            .map((entry) => entry.trim())
+            .find((entry) => entry.length > 0);
+        if (!line)
+            return null;
+        const match = /^([A-Z][a-z]{2}\s+[A-Z][a-z]{2}\s+\d{1,2}\s+\d\d:\d\d:\d\d\s+\d{4})\s+(.*)$/u.exec(line);
+        const startedAtRaw = match?.[1]?.trim() ?? null;
+        const command = match?.[2]?.trim() ?? null;
+        const parsedStartedAt = startedAtRaw && !Number.isNaN(Date.parse(startedAtRaw))
+            ? new Date(startedAtRaw).toISOString()
+            : null;
+        return {
+            pid,
+            command,
+            started_at: parsedStartedAt,
+        };
+    }
+    catch (err) {
+        const errno = err?.code;
+        const exitCode = err?.code;
+        if (errno === "ESRCH" || exitCode === 1)
+            return null;
+        throw err;
+    }
+}
+export async function waitForProcessExit(opts) {
+    const started = Date.now();
+    const poll_ms = opts.poll_ms ?? 100;
+    while (Date.now() - started < opts.timeout_ms) {
+        if (!isProcessAlive(opts.pid))
+            return true;
+        await new Promise((resolve) => setTimeout(resolve, poll_ms));
+    }
+    return !isProcessAlive(opts.pid);
+}
+export async function runSupervisedProcess(opts) {
+    return await new Promise((resolve, reject) => {
+        const [command, ...args] = opts.invocation.argv;
+        if (!command) {
+            reject(new Error("Runner invocation is missing the executable command"));
+            return;
+        }
+        const child = spawn(command, args, {
+            cwd: opts.invocation.run_dir,
+            env: { ...process.env, ...opts.invocation.env },
+            stdio: ["pipe", "pipe", "pipe"],
+        });
+        const pid = typeof child.pid === "number" ? child.pid : null;
+        const started_at = new Date().toISOString();
+        let heartbeat_at = started_at;
+        let stdout_tail = "";
+        let stderr_tail = "";
+        let stdout_bytes = 0;
+        let stderr_bytes = 0;
+        let stdout_buffer = "";
+        let stderr_buffer = "";
+        let trace_seq = 0;
+        let settled = false;
+        const tracePolicy = opts.invocation.trace_policy;
+        const timeoutPolicy = opts.invocation.timeout_policy;
+        const traceMode = tracePolicy.mode;
+        const captureStderr = tracePolicy.capture_stderr;
+        const maxTailBytes = tracePolicy.max_tail_bytes;
+        const redactPatterns = tracePolicy.redact_patterns ?? [];
+        let timeoutReason = null;
+        let timeoutRequestedAt = null;
+        let terminateSentAt = null;
+        let killSentAt = null;
+        let idleTimer = null;
+        let wallTimer = null;
+        let killTimer = null;
+        const queueAppend = (kind, text) => {
+            if (kind === "trace" && traceMode !== "raw")
+                return;
+            if (kind === "stderr" && !captureStderr)
+                return;
+            const path = kind === "trace" ? opts.invocation.trace_path : opts.invocation.stderr_path;
+            try {
+                appendFileSync(path, text, "utf8");
+            }
+            catch (err) {
+                finishWithError(err);
+            }
+        };
+        const writeTraceLine = (stream, raw) => {
+            trace_seq += 1;
+            queueAppend("trace", serializeRunnerTraceEvent(createRunnerTraceEvent({
+                ts: new Date().toISOString(),
+                seq: trace_seq,
+                stream,
+                adapter_id: opts.invocation.adapter_id,
+                raw,
+            })));
+        };
+        const flushTraceBuffer = (buffer, stream) => {
+            const { lines, remainder } = splitCompletedLines(buffer);
+            for (const line of lines) {
+                writeTraceLine(stream, line);
+            }
+            return remainder;
+        };
+        const clearTimers = () => {
+            if (idleTimer)
+                clearTimeout(idleTimer);
+            if (wallTimer)
+                clearTimeout(wallTimer);
+            if (killTimer)
+                clearTimeout(killTimer);
+            idleTimer = null;
+            wallTimer = null;
+            killTimer = null;
+        };
+        const patchRunningSupervision = async (patch) => {
+            const currentState = await readRunnerRunState(opts.invocation.state_path);
+            if (!currentState)
+                return;
+            await writeRunnerRunState({
+                state_path: opts.invocation.state_path,
+                state: evolveRunnerRunState({
+                    state: currentState,
+                    status: currentState.status,
+                    updated_at: new Date().toISOString(),
+                    supervision: mergeSupervisionState(currentState.supervision, patch),
+                }),
+            });
+        };
+        const requestTimeout = (reason) => {
+            if (settled || timeoutReason)
+                return;
+            timeoutReason = reason;
+            timeoutRequestedAt = new Date().toISOString();
+            terminateSentAt = timeoutRequestedAt;
+            void patchRunningSupervision({
+                timeout_reason: reason,
+                timeout_requested_at: timeoutRequestedAt,
+                terminate_sent_at: terminateSentAt,
+                heartbeat_at: timeoutRequestedAt,
+            }).catch(finishWithError);
+            void appendRunnerEvent({
+                events_path: opts.invocation.events_path,
+                event: {
+                    at: timeoutRequestedAt,
+                    type: "runner_timeout_requested",
+                    message: `runner timeout requested (${reason})`,
+                    data: {
+                        reason,
+                        pid,
+                        timeout_policy: timeoutPolicy,
+                    },
+                },
+            }).catch(finishWithError);
+            if (pid && isProcessAlive(pid)) {
+                try {
+                    process.kill(pid, "SIGTERM");
+                }
+                catch (err) {
+                    const code = err?.code;
+                    if (code !== "ESRCH") {
+                        finishWithError(err);
+                        return;
+                    }
+                }
+            }
+            const graceMs = timeoutPolicy.terminate_grace_ms;
+            if (graceMs <= 0) {
+                killSentAt = new Date().toISOString();
+                void patchRunningSupervision({
+                    timeout_reason: reason,
+                    timeout_requested_at: timeoutRequestedAt,
+                    terminate_sent_at: terminateSentAt,
+                    kill_sent_at: killSentAt,
+                    force_killed: true,
+                    heartbeat_at: killSentAt,
+                }).catch(finishWithError);
+                if (pid && isProcessAlive(pid)) {
+                    try {
+                        process.kill(pid, "SIGKILL");
+                    }
+                    catch (err) {
+                        const code = err?.code;
+                        if (code !== "ESRCH") {
+                            finishWithError(err);
+                        }
+                    }
+                }
+                return;
+            }
+            killTimer = setTimeout(() => {
+                if (settled || !timeoutReason)
+                    return;
+                killSentAt = new Date().toISOString();
+                void patchRunningSupervision({
+                    timeout_reason: timeoutReason,
+                    timeout_requested_at: timeoutRequestedAt,
+                    terminate_sent_at: terminateSentAt,
+                    kill_sent_at: killSentAt,
+                    force_killed: true,
+                    heartbeat_at: killSentAt,
+                }).catch(finishWithError);
+                void appendRunnerEvent({
+                    events_path: opts.invocation.events_path,
+                    event: {
+                        at: killSentAt,
+                        type: "runner_timeout_force_kill",
+                        message: `runner force-killed after timeout (${timeoutReason})`,
+                        data: {
+                            reason: timeoutReason,
+                            pid,
+                            timeout_policy: timeoutPolicy,
+                        },
+                    },
+                }).catch(finishWithError);
+                if (pid && isProcessAlive(pid)) {
+                    try {
+                        process.kill(pid, "SIGKILL");
+                    }
+                    catch (err) {
+                        const code = err?.code;
+                        if (code !== "ESRCH") {
+                            finishWithError(err);
+                        }
+                    }
+                }
+            }, graceMs);
+        };
+        const resetIdleTimer = () => {
+            if (timeoutPolicy.idle_ms <= 0 || settled || timeoutReason)
+                return;
+            if (idleTimer)
+                clearTimeout(idleTimer);
+            idleTimer = setTimeout(() => {
+                requestTimeout("idle");
+            }, timeoutPolicy.idle_ms);
+        };
+        const updateRunningState = async () => {
+            const initialState = await readRunnerRunState(opts.invocation.state_path);
+            if (!initialState)
+                return;
+            const supervision = mergeSupervisionState(initialState.supervision, {
+                pid,
+                command: renderInvocationCommand(opts.invocation),
+                started_at,
+                heartbeat_at,
+                exit_signal: null,
+                timeout_reason: null,
+            });
+            await writeRunnerRunState({
+                state_path: opts.invocation.state_path,
+                state: evolveRunnerRunState({
+                    state: initialState,
+                    status: "running",
+                    updated_at: started_at,
+                    supervision,
+                }),
+            });
+            await appendRunnerEvent({
+                events_path: opts.invocation.events_path,
+                event: {
+                    at: started_at,
+                    type: "runner_execute_start",
+                    message: opts.start_message,
+                    data: buildInvocationEventData(opts.invocation, pid),
+                },
+            });
+        };
+        const finishWithError = (err) => {
+            if (settled)
+                return;
+            clearTimers();
+            settled = true;
+            reject(err instanceof Error ? err : new Error(String(err)));
+        };
+        void updateRunningState().catch((err) => {
+            if (pid && isProcessAlive(pid)) {
+                try {
+                    process.kill(pid, "SIGKILL");
+                }
+                catch {
+                    // best effort
+                }
+            }
+            finishWithError(err);
+        });
+        child.stdout.on("data", (chunk) => {
+            const text = chunk.toString();
+            const persistedText = redactTraceText(text, redactPatterns);
+            heartbeat_at = new Date().toISOString();
+            resetIdleTimer();
+            stdout_bytes += Buffer.byteLength(text, "utf8");
+            stdout_tail = appendTail(stdout_tail, persistedText, maxTailBytes);
+            stdout_buffer = flushTraceBuffer(`${stdout_buffer}${persistedText}`, "stdout");
+        });
+        child.stderr.on("data", (chunk) => {
+            const text = chunk.toString();
+            const persistedText = redactTraceText(text, redactPatterns);
+            heartbeat_at = new Date().toISOString();
+            resetIdleTimer();
+            stderr_bytes += Buffer.byteLength(text, "utf8");
+            stderr_tail = appendTail(stderr_tail, persistedText, maxTailBytes);
+            stderr_buffer = flushTraceBuffer(`${stderr_buffer}${persistedText}`, "stderr");
+            queueAppend("stderr", persistedText);
+        });
+        child.on("error", finishWithError);
+        child.on("close", async (code, signal) => {
+            if (settled)
+                return;
+            clearTimers();
+            const ended_at = new Date().toISOString();
+            if (stdout_buffer) {
+                writeTraceLine("stdout", stdout_buffer);
+            }
+            if (stderr_buffer) {
+                writeTraceLine("stderr", stderr_buffer);
+            }
+            if (settled)
+                return;
+            const normalizedSignal = normalizeSignal(signal);
+            const currentState = await readRunnerRunState(opts.invocation.state_path);
+            const supervision = currentState?.supervision;
+            const runStatus = supervision?.cancel_requested_at
+                ? "cancelled"
+                : timeoutReason
+                    ? "failed"
+                    : code === 0
+                        ? "success"
+                        : "failed";
+            const [traceArtifact, stderrArtifact] = await Promise.all([
+                finalizeTraceArtifact({
+                    file_path: opts.invocation.trace_path,
+                    policy: tracePolicy,
+                    run_status: runStatus,
+                }),
+                finalizeTraceArtifact({
+                    file_path: opts.invocation.stderr_path,
+                    policy: tracePolicy,
+                    run_status: runStatus,
+                }),
+            ]);
+            settled = true;
+            resolve({
+                exit_code: code,
+                exit_signal: normalizedSignal,
+                stdout_tail,
+                stderr_tail,
+                stdout_bytes,
+                stderr_bytes,
+                pid,
+                started_at,
+                ended_at,
+                cancel_requested_at: supervision?.cancel_requested_at ?? null,
+                cancel_signal: supervision?.cancel_signal ?? null,
+                timeout_reason: supervision?.timeout_reason ?? timeoutReason,
+                timeout_requested_at: supervision?.timeout_requested_at ?? timeoutRequestedAt,
+                terminate_sent_at: supervision?.terminate_sent_at ?? terminateSentAt,
+                kill_sent_at: supervision?.kill_sent_at ?? killSentAt,
+                force_killed: supervision?.force_killed === true || killSentAt !== null,
+                heartbeat_at: heartbeat_at || ended_at,
+                trace_artifact_path: traceArtifact.artifact_path,
+                trace_archive_path: traceArtifact.archive_path,
+                stderr_artifact_path: stderrArtifact.artifact_path,
+                stderr_archive_path: stderrArtifact.archive_path,
+            });
+        });
+        if (timeoutPolicy.wall_clock_ms > 0) {
+            wallTimer = setTimeout(() => {
+                requestTimeout("wall_clock");
+            }, timeoutPolicy.wall_clock_ms);
+        }
+        resetIdleTimer();
+        child.stdin.end(opts.stdin_text);
+    });
+}
+export async function waitForRunnerStateStop(opts) {
+    const started = Date.now();
+    const poll_ms = opts.poll_ms ?? 100;
+    while (Date.now() - started < opts.timeout_ms) {
+        const state = await readRunnerRunState(opts.state_path);
+        if (state && state.status !== "running")
+            return state;
+        await new Promise((resolve) => setTimeout(resolve, poll_ms));
+    }
+    const state = await readRunnerRunState(opts.state_path);
+    return state && state.status !== "running" ? state : null;
+}