humanish 0.104.3 → 0.106.0

package/dist/routes/terminal/live-sandbox.js

@@ -0,0 +1,452 @@
+// The live terminal session inside its E2B sandbox: acquire the sandbox, prove the shell and the
+// runtime, prepare the product, run `codex exec` once under the wall-clock bound, and tear the
+// sandbox down by exact id. The session's outcome (status, completion reason, reason, error) is
+// recorded on the instance as each step runs; a step that fails closed returns false.
+import { readFile, realpath, stat } from "node:fs/promises";
+import path from "node:path";
+import { digestText, toErrorMessage } from "../../evidence/redaction.js";
+import { desktopSpanToMinutes } from "../../run/cost-summary.js";
+import { validatePreparedRunArtifactPaths } from "../../run/paths.js";
+import { extractLocalActorVerdict, normalizeLocalActorTranscript, } from "../../run/terminal-contract.js";
+import { NODE_BOOTSTRAP_COMMAND, NODE_BOOTSTRAP_TIMEOUT_MS } from "../../subject/node-bootstrap.js";
+import { observeDesktopResources, } from "../../substrates/e2b/desktop-resources.js";
+import { acquireE2BShellSandbox } from "../../substrates/e2b/sandbox.js";
+import { E2BDesktopStartupError, loadE2BDesktopModule, } from "../../substrates/e2b/sdk.js";
+import { shellQuote } from "../../substrates/shell.js";
+import { buildOpenAiEgressNetwork } from "./runtime-auth.js";
+import { TERMINAL_RUNTIME_VERSION_TIMEOUT_MS, buildRuntimeExecPrefix, buildRuntimeVersionCommand, parseTerminalRuntimeVersion, } from "./runtime.js";
+import { runWithWallClock, teardownSandbox } from "./sandbox.js";
+import { DEFAULT_REQUEST_TIMEOUT_MS, PRODUCT_SETUP_TIMEOUT_MS, SANDBOX_WORKDIR, UPLOAD_MAX_BYTES, } from "./types.js";
+import { terminalSandboxTimeoutMs } from "./lifetime.js";
+export class LiveTerminalSandbox {
+    status = "failed";
+    completionReason = "harness_error";
+    reason = "live terminal-product session did not start";
+    error;
+    timedOut = false;
+    sandboxId;
+    cleanup = {
+        killed: false,
+        remaining: -1,
+        reason: "teardown not reached",
+    };
+    inputs;
+    requestTimeoutMs = DEFAULT_REQUEST_TIMEOUT_MS;
+    wallClockMs;
+    sandboxTimeoutMs;
+    sandbox;
+    module;
+    allocation;
+    startupCleanup;
+    // The sandbox's billed span (acquired to cleanup) and size price its compute time.
+    createdAtMs;
+    tornDownAtMs;
+    resources;
+    constructor(inputs) {
+        this.inputs = inputs;
+        this.wallClockMs = inputs.maxMinutes * 60_000;
+        this.sandboxTimeoutMs = terminalSandboxTimeoutMs({
+            maxMinutes: inputs.maxMinutes,
+            productInstall: inputs.plan.product.install !== undefined,
+        });
+    }
+    async acquire() {
+        const { plan, hooks, now, sanitize, runtimeEnv, e2bApiKey, runPaths, metadata } = this.inputs;
+        const { warnings } = this.inputs;
+        const { recordLifecycle } = this.inputs.recorder;
+        const { requestTimeoutMs, sandboxTimeoutMs } = this;
+        // Declared egress allowlist, or undefined for the historical unrestricted default (#538).
+        const egressAllow = plan.egressAllow;
+        const sandboxModule = await (hooks.loadModule ?? loadE2BDesktopModule)();
+        this.module = sandboxModule;
+        await validatePreparedRunArtifactPaths(runPaths);
+        // No sandbox-global env in either mode. In openai-egress, only this host-side SDK request
+        // carries the real runtime key; participant commands receive an inert placeholder. The proxy
+        // capability is available from sandbox creation, including during bootstrap/product setup.
+        const routing = egressAllow === undefined
+            ? undefined
+            : { allowOut: [...egressAllow], denyOut: ["0.0.0.0/0"] };
+        const network = runtimeEnv.mode === "openai-egress"
+            ? buildOpenAiEgressNetwork(runtimeEnv.keyValue, routing)
+            : routing;
+        const acquired = await acquireE2BShellSandbox({
+            module: sandboxModule,
+            options: {
+                apiKey: e2bApiKey,
+                requestTimeoutMs,
+                timeoutMs: sandboxTimeoutMs,
+                metadata,
+                ...(network === undefined ? {} : { network }),
+                lifecycle: { onTimeout: "kill" },
+            },
+            retry: {
+                // A failed first attempt may have allocated a sandbox whose id never reached this run;
+                // its own kill-on-timeout reclaims it.
+                onRetry: (reason) => {
+                    const named = sanitize(reason);
+                    warnings.push(`Sandbox create retried once after a transient provider error (${named}). A sandbox the failed attempt may have allocated is reclaimed by its ${sandboxTimeoutMs} ms timeout.`);
+                    recordLifecycle("terminal-lab.sandbox.create.retry", `sandbox create retried once (${named})`);
+                },
+            },
+            // The receipt is on disk the moment the sandbox exists, so reclaim can kill it by exact id.
+            receipt: { root: runPaths, participantId: "terminal", now },
+        });
+        const sandbox = acquired.sandbox;
+        this.sandbox = sandbox;
+        this.allocation = acquired.allocation;
+        const sandboxId = acquired.allocation.resourceId;
+        this.sandboxId = sandboxId;
+        this.createdAtMs = now();
+        await validatePreparedRunArtifactPaths(runPaths);
+        recordLifecycle("terminal-lab.sandbox.created", `E2B shell sandbox ${sandboxId} created with positive-allowlist metadata and kill-on-timeout; NO sandbox-global env.`);
+        const sandboxResources = await observeDesktopResources(sandbox);
+        this.resources = sandboxResources;
+        if ("reason" in sandboxResources) {
+            warnings.push(`Sandbox resource size unavailable (${sandboxResources.reason}); its compute cost remains unpriced.`);
+        }
+        // The allowlist is evidence: a reader of the ledger can see exactly what the participant was
+        // able to reach, without the ledger carrying any secret.
+        recordLifecycle("terminal-lab.egress.policy", egressAllow === undefined
+            ? "Egress UNRESTRICTED (no execution.egressAllow declared)."
+            : `Egress routing allowlist: ${egressAllow.length} declared host(s): ${egressAllow.join(", ")}; deny-all fallback. Domain routing is not strict destination isolation on shared infrastructure.`);
+        recordLifecycle("terminal-lab.runtime-auth", runtimeEnv.mode === "openai-egress"
+            ? "Runtime auth openai-egress: raw key remains outside the sandbox in the api.openai.com HTTPS Authorization transform; Codex receives an inert CODEX_API_KEY placeholder and the default OpenAI endpoint. Every sandbox process, including bootstrap/setup, can spend via this proxy; no added routing restriction or provider spending limit."
+            : `Runtime auth openai-env: raw key from ${runtimeEnv.keyName} is passed command-scoped to Codex and inherited by its child processes.`);
+        if (runtimeEnv.mode === "openai-egress") {
+            warnings.push("openai-egress keeps the raw runtime key outside the sandbox, but every sandbox process can spend through the api.openai.com proxy from creation until teardown. It adds no egress restriction or provider-enforced budget; extra provider calls may be absent from the Codex usage ledger.");
+        }
+    }
+    async probeReady() {
+        const { recordLifecycle } = this.inputs.recorder;
+        const { requestTimeoutMs } = this;
+        // Readiness: a tiny probe receives no runtime env; openai-egress's proxy is already available.
+        const ready = await this.sandbox.commands.run(`mkdir -p ${SANDBOX_WORKDIR} && echo HUMANISH_SHELL_READY`, { requestTimeoutMs });
+        recordLifecycle("terminal-lab.sandbox.ready", `Shell readiness probe exit=${ready.exitCode ?? "null"}; workdir ${SANDBOX_WORKDIR} prepared.`);
+    }
+    /** Returns false when the runtime bootstrap failed; the session then fails closed. */
+    async bootstrap() {
+        const { now, sanitize } = this.inputs;
+        const { recordLifecycle } = this.inputs.recorder;
+        const { requestTimeoutMs } = this;
+        // --- Runtime bootstrap: no runtime env; openai-egress proxy capability is already available. ---
+        // The stock desktop needs Node/npm on PATH before npx can run Codex. Reuse a working
+        // installation or install the pinned official binary after checksum verification (#674).
+        // No raw runtime key touches this step; the egress proxy, when selected, is already available.
+        const bootstrapStartedAt = now();
+        let bootstrapError;
+        try {
+            const bootstrap = await this.sandbox.commands.run(NODE_BOOTSTRAP_COMMAND, {
+                requestTimeoutMs,
+                timeoutMs: NODE_BOOTSTRAP_TIMEOUT_MS,
+            });
+            if ((bootstrap.exitCode ?? 1) !== 0) {
+                bootstrapError = `runtime bootstrap exited ${bootstrap.exitCode ?? "null"}`;
+            }
+        }
+        catch (error) {
+            bootstrapError = toErrorMessage(error);
+        }
+        const bootstrapDurationMs = Math.max(0, now() - bootstrapStartedAt);
+        recordLifecycle("terminal-lab.runtime.bootstrapped", bootstrapError
+            ? `Runtime bootstrap FAILED after ${bootstrapDurationMs}ms: ${bootstrapError}. codex exec runs via npx and needs Node/npm present; the participant fails closed rather than attempting an exec with no runtime.`
+            : `Runtime bootstrap ensured Node/npm present in ${bootstrapDurationMs}ms (codex exec runs via npx).`);
+        if (bootstrapError) {
+            // Fail closed as a structured lane status (never a raw throw): no codex exec is attempted
+            // without a proven runtime; this mirrors the exec-error status assignment below so the
+            // bundle and verify surface the failure the same way.
+            this.status = "failed";
+            this.completionReason = "harness_error";
+            this.error = sanitize(bootstrapError);
+            this.reason = `runtime bootstrap could not ensure Node/npm before codex exec: ${this.error}`;
+            return false;
+        }
+        return true;
+    }
+    /** Returns false when the observed Codex version is missing or not the requested one. */
+    async verifyRuntimeVersion() {
+        const { plan, sanitize, runtime } = this.inputs;
+        const requested = plan.runtime.version;
+        const { recordLifecycle } = this.inputs.recorder;
+        const { requestTimeoutMs } = this;
+        // Observe the executable without command-scoped auth, then use only that exact version.
+        // The SDK bounds the request and command; version failures reach the owned cleanup path.
+        try {
+            const versionProbe = await this.sandbox.commands.run(buildRuntimeVersionCommand(requested), {
+                requestTimeoutMs,
+                timeoutMs: TERMINAL_RUNTIME_VERSION_TIMEOUT_MS,
+            });
+            const observed = parseTerminalRuntimeVersion(versionProbe.stdout ?? "");
+            if (observed !== undefined)
+                runtime.observedVersion = observed;
+            if (versionProbe.exitCode !== 0 || observed === undefined)
+                throw new Error("Codex version probe did not return a successful `codex-cli <exact-version>` result.");
+            if (requested !== undefined && observed !== requested) {
+                throw new Error(`Codex version mismatch: requested ${requested}, observed ${observed}.`);
+            }
+            runtime.versionStatus = "verified";
+            recordLifecycle("terminal-lab.runtime.version", `Codex requested ${runtime.requestedVersion}, observed ${observed}; exact version selected for execution. Model ${runtime.requestedModel ?? "runtime default (unobserved)"}; reasoning effort ${runtime.requestedReasoningEffort ?? "runtime default (unobserved)"}.`);
+        }
+        catch (error) {
+            runtime.versionStatus = "failed";
+            this.status = "failed";
+            this.completionReason = "harness_error";
+            this.error = sanitize(toErrorMessage(error));
+            this.reason = `Codex runtime version could not be verified before execution: ${this.error}`;
+            recordLifecycle("terminal-lab.runtime.version.error", this.reason);
+            return false;
+        }
+        return true;
+    }
+    /** Returns false when the declared product upload or install could not prepare the world. */
+    async prepareProduct() {
+        const { plan, cwd, now, sanitize } = this.inputs;
+        const { recordLifecycle } = this.inputs.recorder;
+        const { requestTimeoutMs } = this;
+        // --- Optional product setup (no runtime env), before the Codex exec. ---
+        // Same channel and same guarantees as the runtime bootstrap above: no runtime key touches it,
+        // and a failure fails the lane closed rather than handing the agent a half-built world. It
+        // exists so a study can put the participant IN a prepared project — asking an agent what
+        // studies a project contains, in an empty directory, measures the lab and not the product
+        // (learned the hard way on the desktop lane, labs/tui-self-study.yaml).
+        const install = plan.product.install;
+        if (install === undefined)
+            return true;
+        // An optional local file, put on the machine before the install runs, so a study can meet a
+        // build that is not published yet. Read and checked HERE rather than trusted from the
+        // manifest: this puts a file from the operator's disk onto a machine an autonomous agent is
+        // about to drive, so it stays inside the project, must be a regular file, and is size-capped.
+        let uploadAssignment = "";
+        const uploadRel = plan.product.upload;
+        if (uploadRel !== undefined) {
+            const uploadStartedAt = now();
+            try {
+                const resolved = path.resolve(cwd, uploadRel);
+                const projectRoot = await realpath(cwd);
+                const real = await realpath(resolved);
+                if (real !== projectRoot && !real.startsWith(`${projectRoot}${path.sep}`)) {
+                    throw new Error("subject.product.upload resolved outside the project");
+                }
+                const info = await stat(real);
+                if (!info.isFile())
+                    throw new Error("subject.product.upload is not a regular file");
+                if (info.size > UPLOAD_MAX_BYTES) {
+                    throw new Error(`subject.product.upload is ${info.size} bytes; the cap is ${UPLOAD_MAX_BYTES}`);
+                }
+                const destination = `${SANDBOX_WORKDIR}/.humanish-upload/${path.basename(real)}`;
+                await this.sandbox.commands.run(`mkdir -p ${SANDBOX_WORKDIR}/.humanish-upload`, {
+                    requestTimeoutMs,
+                });
+                const bytes = await readFile(real);
+                await this.sandbox.files.write(destination, bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength));
+                // Inlined into the command string rather than passed as `envs`: the ONLY call in this
+                // lane that carries envs is the keyed codex exec, and that invariant is worth more than
+                // the convenience of a second envs channel.
+                uploadAssignment = `export HUMANISH_PRODUCT_UPLOAD=${shellQuote(destination)}; `;
+                recordLifecycle("terminal-lab.product.uploaded", `Uploaded ${info.size} bytes to the sandbox in ${Math.max(0, now() - uploadStartedAt)}ms (no runtime env; declared egress auth may already be available).`);
+            }
+            catch (error) {
+                this.status = "failed";
+                this.completionReason = "harness_error";
+                this.error = sanitize(toErrorMessage(error));
+                this.reason = `subject.product.upload could not be placed in the sandbox: ${this.error}`;
+                return false;
+            }
+        }
+        const setupStartedAt = now();
+        let setupError;
+        try {
+            const setup = await this.sandbox.commands.run(`${uploadAssignment}cd ${SANDBOX_WORKDIR} && ${install}`, {
+                // The install step may run the product itself (release:dogfood's does: `humanish init
+                // --yes`); on the 0.67.0 dogfood that one command arrived unmarked while the participant's
+                // nine others carried the marker (#546).
+                envs: { HUMANISH_STUDY_PARTICIPANT: "1" },
+                requestTimeoutMs,
+                timeoutMs: PRODUCT_SETUP_TIMEOUT_MS,
+            });
+            if ((setup.exitCode ?? 1) !== 0) {
+                setupError = `product setup exited ${setup.exitCode ?? "null"}`;
+            }
+        }
+        catch (error) {
+            setupError = toErrorMessage(error);
+        }
+        recordLifecycle("terminal-lab.product.prepared", setupError
+            ? `Product setup FAILED after ${Math.max(0, now() - setupStartedAt)}ms: ${sanitize(setupError)}`
+            : `Product setup completed in ${Math.max(0, now() - setupStartedAt)}ms (no runtime env; declared egress auth may already be available).`);
+        if (setupError) {
+            this.status = "failed";
+            this.completionReason = "harness_error";
+            this.error = sanitize(setupError);
+            this.reason = `subject.product.install could not prepare the world before codex exec: ${this.error}`;
+            return false;
+        }
+        return true;
+    }
+    async execCodex() {
+        const { plan, now, nowIso, sanitize, runtimeEnv, runtime } = this.inputs;
+        const { model, reasoningEffort } = plan.runtime;
+        const { composedPrompt, verdictNonce, maxMinutes } = this.inputs;
+        const { recordLifecycle, recordStreamedTerminalChunk, appendReturnedTerminalOutput } = this.inputs.recorder;
+        const { commandLog, terminalEvents } = this.inputs.recorder;
+        const { requestTimeoutMs, wallClockMs } = this;
+        // --- The keyed run: `codex exec --json` non-interactively (stdin disabled). ---
+        // openai-env passes the real key here; openai-egress passes an inert placeholder. stdin is
+        // never wired (safety contract item 7) — commands.run takes no stdin channel. The command's
+        // wall-clock is bounded by maxMinutes (safety contract item 2): commands.run timeoutMs +
+        // an injected-clock guard so a mock/real run that exceeds it is killed and fails closed.
+        const codexCommand = buildCodexExecCommand({
+            workdir: SANDBOX_WORKDIR,
+            prompt: composedPrompt,
+            runtimeAuth: runtimeEnv.mode,
+            version: runtime.observedVersion,
+            ...(model === undefined ? {} : { model }),
+            ...(reasoningEffort === undefined ? {} : { reasoningEffort }),
+        });
+        const commandDigest = digestText(codexCommand);
+        const startedAt = now();
+        recordLifecycle("terminal-lab.exec.started", `Launching codex exec (runtime auth ${runtimeEnv.mode}; command env names: ${Object.keys(runtimeEnv.envs).join(", ")}); wall-clock bound ${wallClockMs}ms.`);
+        let exitCode;
+        let runError;
+        try {
+            const result = await runWithWallClock(this.sandbox.commands.run(codexCommand, {
+                // The selected command env (raw key or inert placeholder). The participant
+                // marker rides the same command: humanish telemetry from inside a study reads as a new
+                // adopter otherwise. #546 added the flag and nothing set it; the 0.66.0 dogfood
+                // participant's twelve commands arrived unmarked.
+                envs: { ...runtimeEnv.envs, HUMANISH_STUDY_PARTICIPANT: "1" },
+                requestTimeoutMs,
+                timeoutMs: wallClockMs,
+                onStdout: (data) => recordStreamedTerminalChunk("stdout", data),
+                onStderr: (data) => recordStreamedTerminalChunk("stderr", data),
+            }), wallClockMs, now);
+            if (result.timedOut) {
+                this.timedOut = true;
+            }
+            else {
+                exitCode = result.value.exitCode;
+                // Reconcile the SDK's returned aggregate against bytes already delivered by callbacks.
+                if (result.value.stdout)
+                    appendReturnedTerminalOutput("stdout", result.value.stdout);
+                if (result.value.stderr)
+                    appendReturnedTerminalOutput("stderr", result.value.stderr);
+                if (result.value.error)
+                    runError = result.value.error;
+            }
+        }
+        catch (error) {
+            runError = toErrorMessage(error);
+        }
+        const durationMs = Math.max(0, now() - startedAt);
+        commandLog.push({
+            at: nowIso(),
+            label: "codex-exec",
+            commandDigest,
+            envNames: Object.keys(runtimeEnv.envs), // NAMES only — the credential evidence (item 4).
+            ...(exitCode === undefined ? {} : { exitCode }),
+            ...(this.timedOut ? { timedOut: true } : {}),
+            durationMs,
+        });
+        // Score by the verdict-nonce marker over the SCRUBBED+REDACTED, NORMALIZED transcript — the
+        // exact same logic the local-actor lanes use (extractLocalActorVerdict/normalizeLocalActorTranscript).
+        const rawTranscript = terminalEvents.map((e) => e.chunk).join("");
+        const normalizedTranscript = normalizeLocalActorTranscript(rawTranscript);
+        const markerStatus = extractLocalActorVerdict(normalizedTranscript, verdictNonce);
+        if (this.timedOut) {
+            this.status = "timed_out";
+            this.completionReason = "timed_out";
+            this.reason = `codex exec exceeded the maxMinutes wall-clock (${maxMinutes}m); killed and failed closed.`;
+            recordLifecycle("terminal-lab.exec.timed_out", this.reason);
+        }
+        else if (runError) {
+            this.status = "failed";
+            this.completionReason = "harness_error";
+            this.error = sanitize(runError);
+            this.reason = `codex exec could not run: ${this.error}`;
+            recordLifecycle("terminal-lab.exec.error", this.reason);
+        }
+        else if (markerStatus) {
+            this.status = markerStatus;
+            this.completionReason =
+                markerStatus === "passed"
+                    ? "goal_satisfied"
+                    : markerStatus === "blocked"
+                        ? "blocked_approval"
+                        : "gave_up";
+            this.reason = `agent reported ${markerStatus} verdict marker (nonce-verified)`;
+            recordLifecycle("terminal-lab.exec.completed", `codex exec exit=${exitCode ?? "null"}; ${this.reason}.`);
+        }
+        else {
+            // No nonce-verified verdict: the agent did not (credibly) report a terminal status. A run
+            // that exited 0 but printed no verified marker is BLOCKED evidence (the failure IS the
+            // evidence — still structurally verifiable), not a silent pass.
+            this.status = "blocked";
+            this.completionReason = "gave_up";
+            this.reason = `codex exec exit=${exitCode ?? "null"} but no nonce-verified HUMANISH_ACTOR_VERDICT marker was emitted; recorded as blocked (the missing verdict is the evidence).`;
+            recordLifecycle("terminal-lab.exec.blocked", this.reason);
+        }
+    }
+    /** Records a failure of the session around the steps (not one a step already recorded). */
+    recordSessionError(error) {
+        const { sanitize } = this.inputs;
+        const { recordLifecycle } = this.inputs.recorder;
+        if (error instanceof E2BDesktopStartupError)
+            this.startupCleanup = error.cleanup;
+        this.error = sanitize(toErrorMessage(error));
+        this.status = "failed";
+        this.completionReason = "harness_error";
+        this.reason = `live terminal-product session failed: ${this.error}`;
+        recordLifecycle("terminal-lab.session.error", this.reason);
+    }
+    async teardown() {
+        const { now, sanitize, warnings } = this.inputs;
+        const { recordLifecycle } = this.inputs.recorder;
+        const { requestTimeoutMs } = this;
+        // --- Safety contract item 8: PROVEN cleanup, BY EXACT ID, never Sandbox.list. ---
+        this.cleanup = await teardownSandbox({
+            allocation: this.allocation,
+            sandboxModule: this.module,
+            ...(this.startupCleanup === undefined ? {} : { startupCleanup: this.startupCleanup }),
+            requestTimeoutMs,
+            sanitize,
+            recordLifecycle,
+            warnings,
+        });
+        if (this.createdAtMs !== undefined)
+            this.tornDownAtMs = now();
+    }
+    /** The sandbox's compute time for the run cost summary, when a sandbox was acquired. */
+    runCostDesktops() {
+        if (this.createdAtMs === undefined)
+            return undefined;
+        return [
+            {
+                minutes: desktopSpanToMinutes(this.tornDownAtMs === undefined
+                    ? undefined
+                    : Math.max(0, this.tornDownAtMs - this.createdAtMs)),
+                observation: this.resources,
+                lifetimeComplete: this.cleanup.remaining === 0,
+            },
+        ];
+    }
+}
+/** Build the in-sandbox `codex exec` command (non-interactive, JSON, stdin disabled by mechanism). */
+function buildCodexExecCommand(args) {
+    // The prompt is passed via a heredoc on stdin of a wrapper? NO, stdin is DISABLED (item 7), so
+    // the prompt rides as the final positional arg, shell-quoted. codex exec --json runs once and
+    // exits (no interactive loop). --skip-git-repo-check: the workdir is a fresh scratch dir.
+    // Pinned via npx (never an ambient/preinstalled `codex` binary, which the stock @e2b/desktop
+    // image does not ship, per issue #159); npm_config_update_notifier=false silences npx's own
+    // update check so it cannot leak into the captured stdout the scorer/redactor parse.
+    const quotedPrompt = shellQuote(args.prompt);
+    // --dangerously-bypass-approvals-and-sandbox: codex's OWN inner sandbox is
+    // redundant here and blocks the network/file access the study mission needs.
+    // The E2B sandbox is the trust boundary (the disposable machine), and exec mode has no
+    // interactive approval channel at all.
+    // The egress transform protects only the default OpenAI host. Pin the effective built-in
+    // provider/base URL above config-file settings so setup-written custom endpoints cannot make
+    // this invocation silently claim protection for another provider. openai-env is unchanged.
+    const providerConfig = args.runtimeAuth === "openai-egress"
+        ? ` -c 'model_provider="openai"' -c 'openai_base_url="https://api.openai.com/v1"'`
+        : "";
+    return `cd ${args.workdir} && ${buildRuntimeExecPrefix(args.version, args.model, args.reasoningEffort)} --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check${providerConfig} --json ${quotedPrompt}`;
+}

package/dist/routes/terminal/persona.d.ts

@@ -0,0 +1,20 @@
+import type { ActorPersonaRef } from "../../actors/contract.js";
+import { type ResolvedPersona } from "../../lab/persona.js";
+import type { TerminalPlan } from "../../lab/plan-types.js";
+/** A terminal run's persona, resolved against the project's committed persona files. */
+export interface TerminalPersona {
+    personaId: string;
+    physicalCwd: string;
+    /** The persona section the agent prompt starts with. */
+    personaLine: string;
+    /** The committed persona, or null when no file resolved and only the id is used. */
+    resolved: ResolvedPersona | null;
+}
+/** Resolves the plan's persona; the resolver's warnings go into `warnings`. */
+export declare function resolveTerminalPersona(args: {
+    plan: TerminalPlan;
+    cwd: string;
+    warnings: string[];
+}): Promise<TerminalPersona>;
+/** The persona ref a terminal bundle records; `scrub` removes known secret values from the brief. */
+export declare function terminalPersonaRef(persona: TerminalPersona, promptDigest: string, scrub: (text: string) => string): ActorPersonaRef;

package/dist/routes/terminal/persona.js

@@ -0,0 +1,34 @@
+// The terminal route's persona. The dry path (dry-run.ts) and the live path (session.ts) both
+// resolve it here, so the persona line their prompts start with and the persona ref their bundles
+// record come from one place. Each path keeps its own prompt and its own set of scrubbed secrets.
+import { realpath } from "node:fs/promises";
+import path from "node:path";
+import { personaBrief, personaToDirectives, renderPersonaPromptSection, } from "../../lab/persona.js";
+import { resolveCommittedPersona } from "../../lab/persona-resolve.js";
+import { prepareSelectedOutputDirectory } from "../../run/contained-output.js";
+/** Resolves the plan's persona; the resolver's warnings go into `warnings`. */
+export async function resolveTerminalPersona(args) {
+    const personaId = args.plan.personaId ?? "autonomous-terminal-agent";
+    const physicalCwd = await realpath(args.cwd);
+    // Resolve the committed persona so its traits actually shape the agent prompt (#308); fail-safe to
+    // the bare persona id (no traits applied) when no persona file is committed.
+    const projectRoot = await prepareSelectedOutputDirectory(path.dirname(physicalCwd), physicalCwd);
+    const { persona, warnings } = await resolveCommittedPersona(projectRoot, personaId);
+    args.warnings.push(...warnings);
+    return {
+        personaId,
+        physicalCwd,
+        personaLine: persona ? renderPersonaPromptSection(persona) : `persona: ${personaId}`,
+        resolved: persona,
+    };
+}
+/** The persona ref a terminal bundle records; `scrub` removes known secret values from the brief. */
+export function terminalPersonaRef(persona, promptDigest, scrub) {
+    const { resolved } = persona;
+    return {
+        id: persona.personaId,
+        traitsApplied: resolved ? personaToDirectives(resolved).traitsApplied : [],
+        promptDigest,
+        ...(resolved ? { brief: personaBrief(resolved, scrub) } : {}),
+    };
+}

package/dist/routes/terminal/plan.d.ts

@@ -0,0 +1,21 @@
+import type { RoutePlanResult, RouteRefusal, TerminalPlan } from "../../lab/plan-types.js";
+import type { LabConfig } from "../../lab/types.js";
+import type { RunLabProvenance } from "../../run/status.js";
+import { type TerminalProductLabResult } from "./types.js";
+/** The error a terminal lab returns before a run starts. `actor` names the registered actor. */
+export interface TerminalRefusal extends RouteRefusal<"terminal", NonNullable<TerminalProductLabResult["error"]>["code"]> {
+    readonly actor?: string;
+}
+export type TerminalPlanResult = RoutePlanResult<TerminalPlan, TerminalRefusal>;
+/**
+ * Plan a terminal-product lab. It is called for any config handed to the terminal runner, not
+ * only one routeOf sends here, so a config for another route gets this route's refusal.
+ */
+export declare function planTerminalLab(config: LabConfig, input: {
+    readonly dryRun: boolean;
+    readonly lab?: RunLabProvenance;
+    /** A caller's costProbe can measure spend lines, so a positive maxUsd can trip. */
+    readonly hooks?: {
+        readonly costProbe?: unknown;
+    };
+}): TerminalPlanResult;

package/dist/routes/terminal/plan.js

@@ -0,0 +1,115 @@
+// The terminal route's plan: every configuration refusal the route makes before a run starts, in
+// its order and with its codes, then the plan the run uses. The route checks nothing here again;
+// what stays in the route reads external state (keys, the runtime env, the sandbox).
+import { resolveAutomaticAnalysis } from "../../analysis/automatic-config.js";
+import { isReasoningEffort } from "../../actors/reasoning-effort.js";
+import { actorRegistry, isTerminalActorDescriptor } from "../../actors/registry.js";
+import { isNonEmpty, planBase } from "../../lab/plan-base.js";
+import { desktopMediaValidationReason, taskProtocolValidationReason, } from "../../lab/validation.js";
+import { MAX_SANDBOX_MS } from "../../substrates/e2b/lifetime.js";
+import { NODE_BOOTSTRAP_TIMEOUT_MS } from "../../subject/node-bootstrap.js";
+import { terminalSandboxTimeoutMs } from "./lifetime.js";
+import { isExactRuntimeVersion, TERMINAL_RUNTIME_VERSION_TIMEOUT_MS } from "./runtime.js";
+import { PRODUCT_SETUP_TIMEOUT_MS, TERMINAL_SANDBOX_TIMEOUT_BUFFER_MS, } from "./types.js";
+/**
+ * Plan a terminal-product lab. It is called for any config handed to the terminal runner, not
+ * only one routeOf sends here, so a config for another route gets this route's refusal.
+ */
+export function planTerminalLab(config, input) {
+    const refuse = (code, message, actor) => ({
+        ok: false,
+        refusal: { route: "terminal", code, message, ...(actor === undefined ? {} : { actor }) },
+    });
+    if (String(config.comms?.email?.kind) === "real")
+        return refuse("HUMANISH_TERMINAL_LAB_SUBJECT_INVALID", "Real email receiving is unsupported on the terminal route. Use a supported hosted computer-use browser lab.");
+    const mediaReason = desktopMediaValidationReason(config);
+    if (mediaReason)
+        return refuse("HUMANISH_TERMINAL_LAB_SUBJECT_INVALID", mediaReason);
+    const analysis = resolveAutomaticAnalysis(config.review?.analysis);
+    if (!analysis.ok)
+        return refuse("HUMANISH_LAB_ANALYSIS_INVALID", analysis.message);
+    const tasksReason = taskProtocolValidationReason(config, false);
+    if (tasksReason)
+        return refuse("HUMANISH_LAB_TASKS_UNSUPPORTED", tasksReason);
+    const actorType = config.actors[0]?.type ?? "";
+    const descriptor = actorRegistry[actorType];
+    if (!descriptor || !isTerminalActorDescriptor(descriptor))
+        return refuse("HUMANISH_TERMINAL_LAB_ACTOR_UNSUPPORTED", `actors[0].type "${actorType}" is not a registered terminal actor.`);
+    const runtimeVersion = config.execution?.runtime?.version;
+    const actor = config.actors[0];
+    if ((config.execution?.runtime !== undefined && !isExactRuntimeVersion(runtimeVersion)) ||
+        (actor?.model !== undefined &&
+            (typeof actor.model !== "string" || actor.model.trim().length === 0)) ||
+        (actor?.reasoningEffort !== undefined && !isReasoningEffort(actor.reasoningEffort)))
+        return refuse("HUMANISH_TERMINAL_LAB_FAILED", "Terminal runtime settings require an exact Codex version, a nonempty model when declared, and a supported reasoning-effort value.");
+    const product = config.subject.product;
+    const surfaces = product?.publicSurfaces ?? [];
+    if (!product || !product.name || !isNonEmpty(surfaces))
+        return refuse("HUMANISH_TERMINAL_LAB_SUBJECT_INVALID", "terminal-product subjects require `subject.product` with a name and at least one public surface URL.", descriptor.id);
+    const base = planBase(config, {
+        dryRun: input.dryRun,
+        ...(input.lab === undefined ? {} : { lab: input.lab }),
+        analysis,
+    });
+    const egressAllow = config.execution?.egressAllow;
+    const stdin = config.execution?.terminal?.stdin;
+    const shared = {
+        ...base,
+        route: "terminal",
+        actor: descriptor.id,
+        product: { ...product, publicSurfaces: surfaces },
+        ...(actor?.persona === undefined ? {} : { personaId: actor.persona }),
+        ...(actor?.mission === undefined ? {} : { mission: actor.mission }),
+        runtime: {
+            ...(runtimeVersion === undefined ? {} : { version: runtimeVersion }),
+            ...(actor?.model === undefined ? {} : { model: actor.model }),
+            ...(actor?.reasoningEffort === undefined ? {} : { reasoningEffort: actor.reasoningEffort }),
+            ...(config.execution?.runtimeAuth === undefined
+                ? {}
+                : { auth: config.execution.runtimeAuth }),
+        },
+        ...(egressAllow === undefined ? {} : { egressAllow }),
+        ...(stdin === undefined ? {} : { stdin }),
+    };
+    const caps = config.scenario?.caps;
+    if (input.dryRun)
+        return { ok: true, plan: { ...shared, dryRun: true, ...(caps ? { caps } : {}) } };
+    // The live lane injects the runtime key into one command only, and only a registered actor
+    // that declares that placement may run live.
+    const keyPlacement = descriptor.capabilities.keyPlacement;
+    if (keyPlacement !== "in-sandbox-command-scoped")
+        return refuse("HUMANISH_TERMINAL_LAB_KEYPLACEMENT_INVALID", `Terminal actor "${descriptor.id}" must declare keyPlacement "in-sandbox-command-scoped" for a live run (got "${String(keyPlacement)}"). The engine requires this registered default before applying the declared runtime-auth mode.`, descriptor.id);
+    // A live run grants the in-sandbox agent provider access, so a fail-closed cap must be in force.
+    const maxUsd = caps?.maxUsd;
+    const maxMinutes = caps?.maxMinutes;
+    if (caps === undefined || maxUsd === undefined || maxMinutes === undefined || maxMinutes <= 0)
+        return refuse("HUMANISH_TERMINAL_LAB_CAPS_MISSING", "A live terminal-product run grants provider access to the in-sandbox agent and so REQUIRES a fail-closed cap: scenario.caps with maxUsd (0 = no-spend) and a positive maxMinutes (the codex command's wall-clock kill). The live key is never exercised without a cap in force.", descriptor.id);
+    // maxUsd is checked against the cost ledger after the session, and only known lines can trip it.
+    // Core records the Codex provider line as unpriced tokens (no rate for model `codex`) and has no
+    // product, media or payment signal, so without a costProbe every line is null and a positive
+    // maxUsd could never trip. That cap would promise a bound nothing enforces, so it is refused;
+    // maxMinutes is what bounds a live run.
+    if (maxUsd > 0 && input.hooks?.costProbe === undefined)
+        return refuse("HUMANISH_TERMINAL_LAB_UNPRICED_CAP", `scenario.caps.maxUsd=${maxUsd} cannot be enforced: the Codex participant's provider spend is recorded as unpriced tokens and no product, media or payment spend is measured, so a positive dollar cap can never trip. Set scenario.caps.maxUsd to 0 and bound the run with scenario.caps.maxMinutes, the codex command's wall-clock kill. No sandbox was created and the runtime key was not used.`, descriptor.id);
+    // The sandbox's timeout covers the steps before the codex command, maxMinutes and the teardown
+    // buffer, and E2B refuses a sandbox over an hour. Refuse here, with the arithmetic, rather than
+    // after the plan prints, from a provider 400 that names neither knob.
+    const productInstall = shared.product.install !== undefined;
+    const sandboxTimeoutMs = terminalSandboxTimeoutMs({ maxMinutes, productInstall });
+    if (sandboxTimeoutMs > MAX_SANDBOX_MS) {
+        const headroomMinutes = (sandboxTimeoutMs - maxMinutes * 60_000) / 60_000;
+        return refuse("HUMANISH_TERMINAL_LAB_CAPS_INVALID", `scenario.caps.maxMinutes ${maxMinutes} derives a ${sandboxTimeoutMs / 60_000}m sandbox deadline, and a sandbox may not live longer than ${MAX_SANDBOX_MS / 60_000}m. The deadline is maxMinutes plus ${headroomMinutes}m: the Node bootstrap (${NODE_BOOTSTRAP_TIMEOUT_MS / 60_000}m), the runtime version check (${TERMINAL_RUNTIME_VERSION_TIMEOUT_MS / 60_000}m)${productInstall ? `, the product setup (${PRODUCT_SETUP_TIMEOUT_MS / 60_000}m)` : ""} and the teardown buffer (${TERMINAL_SANDBOX_TIMEOUT_BUFFER_MS / 60_000}m). Lower scenario.caps.maxMinutes to at most ${MAX_SANDBOX_MS / 60_000 - headroomMinutes}. No sandbox was created and the runtime key was not used.`, descriptor.id);
+    }
+    return {
+        ok: true,
+        plan: {
+            ...shared,
+            dryRun: false,
+            caps: { ...caps, maxUsd, maxMinutes },
+            requirements: [
+                { kind: "key", name: "E2B_API_KEY" },
+                { kind: "key-one-of", names: ["CODEX_API_KEY", "OPENAI_API_KEY"] },
+            ],
+        },
+    };
+}