humanish 0.80.0 → 0.82.0

package/dist/e2b-terminal-lab.js

@@ -1,5 +1,5 @@
 // The terminal-product lab backend: a real autonomous agent (Codex) studying a CLI/product from
-// PUBLIC SURFACES ONLY, running INSIDE an E2B shell with command-scoped runtime auth, capturing
+// PUBLIC SURFACES ONLY, running INSIDE an E2B shell with explicit runtime-auth placement, capturing
 // its non-interactive exec output (stdin disabled) as a redacted event stream + normalized
 // transcript, capped at no-spend, emitting durable terminal/substrate/cost/no-spend/cleanup/
 // intervention proof. Mirrors cua-actor-lab.ts / scripted-browser-lab.ts.
@@ -12,10 +12,10 @@
 //
 // THE SAFETY CONTRACT (docs/goals/terminal-product-lane/goal.md) is enforced BY CONSTRUCTION here
 // and CHECKED by the verifier (run.ts validateTerminalProductEvidence):
-//   1. COMMAND-SCOPED KEY. The runtime LLM key is injected ONLY into the per-command `envs` of the
-//      `codex exec` invocation (commands.run({envs})), NEVER Sandbox.create({envs}) — driven off
-//      the registered actor's keyPlacement: "in-sandbox-command-scoped" capability (engine-
-//      enforced: a terminal actor lacking that metadata FAILS CLOSED before any sandbox exists).
+//   1. EXPLICIT KEY PLACEMENT. openai-env (default) injects the raw runtime key command-scoped,
+//      NEVER Sandbox.create({envs}). Opt-in openai-egress sends it only in the host-side E2B
+//      header transform and passes an inert command placeholder. The proxy is spendable by every
+//      sandbox process from creation; this protects the raw key, not provider spending.
 //   2. FAIL-CLOSED CAP. The live key is never exercised without scenario.caps in force: maxUsd
 //      (default/require 0 = no-spend) + maxMinutes (wall-clock kill of the codex command).
 //   3. PUBLIC SURFACES ONLY. The mission references only subject.product.publicSurfaces + the
@@ -36,8 +36,11 @@
 //      Sandbox.getInfo(id) when the SDK exposes it (a thrown SandboxNotFoundError means gone).
 //      humanish NEVER calls Sandbox.list to prove cleanup, so a shared operator key never reaches a
 //      sandbox it did not create. A live run that cannot prove teardown fails closed.
-import { randomBytes, randomUUID } from "node:crypto";
+import { createHash, randomBytes, randomUUID } from "node:crypto";
+import { TERMINAL_NODE_BOOTSTRAP_COMMAND } from "./terminal-node-bootstrap.js";
 import { describeTokenUsage, parseTerminalTokenUsage } from "./terminal-token-usage.js";
+import { buildRuntimeExecPrefix, buildRuntimeVersionCommand, declaredRuntimeProvenance, isExactRuntimeVersion, parseTerminalRuntimeVersion, TERMINAL_RUNTIME_VERSION_TIMEOUT_MS } from "./terminal-runtime.js";
+import { isReasoningEffort } from "./reasoning-effort.js";
 import { readFile, realpath, stat } from "node:fs/promises";
 import path from "node:path";
 import { parse as parseYaml } from "yaml";
@@ -45,6 +48,7 @@ import { beginRunStatus, withRunStatusScope } from "./run-status.js";
 import { ACTOR_TRACE_SCHEMA, TERMINAL_AGENT_CAPABILITIES } from "./actor-contract.js";
 import { actorRegistry, isTerminalActorDescriptor } from "./actor-registry.js";
 import { toErrorMessage } from "./command-failure.js";
+import { buildOpenAiEgressNetwork, E2B_SYSTEM_CA_BUNDLE, OPENAI_EGRESS_PLACEHOLDER } from "./terminal-runtime-auth.js";
 import { isSandboxNotFoundError, loadE2BDesktopModule } from "./e2b-desktop-launch.js";
 import { renderObserver } from "./observer.js";
 import { parseResolvedPersona, personaToDirectives, renderPersonaPromptSection } from "./persona.js";
@@ -74,24 +78,8 @@ const UPLOAD_MAX_BYTES = 64 * 1024 * 1024;
 // Server-side reclamation buffer past the codex command's own wall-clock (caps.maxMinutes) kill.
 const SANDBOX_TIMEOUT_BUFFER_MS = 5 * 60_000;
 const DEFAULT_REQUEST_TIMEOUT_MS = 60_000;
-// The runtime-bootstrap step (ensure Node/npm) can run an apt-get install; the SDK's commands.run
-// timeoutMs default (60s) is far too short for that, so this step gets an explicit generous budget.
+// Allow the pinned runtime download and install enough time while retaining a finite deadline.
 const RUNTIME_BOOTSTRAP_TIMEOUT_MS = 300_000;
-// UNKEYED (no envs) shell command that ensures Node/npm are present before the keyed codex exec.
-// Reuses the oss-meta-lab.ts ensure_node() shape: check node's major version, else install
-// Node 22 via NodeSource plus passwordless sudo (the stock @e2b/desktop image ships neither codex
-// nor a recent Node, per issue #159). A final presence check makes the whole command exit non-zero
-// (so the bootstrap step fails closed) if the install still leaves node/npm missing.
-const RUNTIME_BOOTSTRAP_COMMAND = [
-    `node_major=0`,
-    `if command -v node >/dev/null 2>&1; then node_major=$(node -e 'console.log(Number(process.versions.node.split(".")[0]))' 2>/dev/null || echo 0); fi`,
-    `if command -v node >/dev/null 2>&1 && command -v npm >/dev/null 2>&1 && [ "$node_major" -ge 20 ]; then exit 0; fi`,
-    `sudo -n apt-get update`,
-    `sudo -n apt-get install -y ca-certificates curl gnupg`,
-    `curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -n -E bash -`,
-    `sudo -n apt-get install -y nodejs`,
-    `command -v node >/dev/null 2>&1 && command -v npm >/dev/null 2>&1`
-].join(" && ");
 // How much of a captured stream / log tail rides a (redacted) message field.
 const TAIL_CHARS = 2000;
 // Hard cap on the retained event-stream + transcript size, so a runaway agent cannot balloon the
@@ -135,6 +123,13 @@ async function runTerminalProductLabInScope(options) {
     if (!descriptor || !isTerminalActorDescriptor(descriptor)) {
         return failed("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 failed("HUMANISH_TERMINAL_LAB_FAILED", "Terminal runtime settings require an exact Codex version, a nonempty model when declared, and a supported reasoning-effort value.");
+    }
     // Re-enforce the subject shape at the engine (the parser rejects these too, but this is exported
     // npm surface). A terminal-product subject MUST declare product.name + public surfaces.
     if (!product || !product.name || product.publicSurfaces.length === 0) {
@@ -207,6 +202,17 @@ async function runTerminalProductLabInScope(options) {
         runId,
         source
     });
+    bundle.events.push({
+        id: "event-terminal-runtime-declared",
+        at: createdAt,
+        level: "info",
+        type: "terminal-lab.runtime.declared",
+        message: redactText(JSON.stringify(declaredRuntimeProvenance({
+            ...(config.execution?.runtime?.version === undefined ? {} : { version: config.execution.runtime.version }),
+            ...(config.actors[0]?.model === undefined ? {} : { model: config.actors[0].model }),
+            ...(config.actors[0]?.reasoningEffort === undefined ? {} : { reasoningEffort: config.actors[0].reasoningEffort })
+        })))
+    });
     await writeContainedOutputFile(runPaths, "run.json", `${JSON.stringify(bundle, null, 2)}\n`, "utf8");
     // Finalize identity+liveness from the bundle just written; a throw before this leaves the record
     // stale, which reads as interrupted rather than as a false outcome (#455).
@@ -416,17 +422,12 @@ function roundUsd(value) {
     return Math.round(value * 1_000_000) / 1_000_000;
 }
 /**
- * Build the per-command runtime-auth env from a DENY-BY-DEFAULT ALLOWLIST containing ONLY the
- * declared runtime key (safety contract item 4). The key NAME is derived from the actor's
- * keyPlacement capability plus the declared runtimeAuth channel, not a hardcoded string the caller
- * can widen. Banned credential names (GitHub/payment/deploy/db/media) are excluded by construction
- * AND guarded: if a banned name is ever requested the lane fails closed. Returns the allowlisted
- * env (values from `env`) and the resolved key name, or a structured failure.
- *
- * Engine-enforced placement (safety contract item 1): the key is only ever returned as a
- * COMMAND-scoped env here; the caller passes it to commands.run({envs}), never Sandbox.create.
+ * Resolve the runtime key on the host. Legacy openai-env passes it command-scoped; openai-egress
+ * returns an inert command env while retaining the actual value for the external transform and
+ * literal redaction. Only CODEX_API_KEY/OPENAI_API_KEY are accepted as sources. No other operator
+ * credential is forwarded. The real value must never be logged or persisted in either mode.
  */
-function buildCommandScopedRuntimeEnv(args) {
+function buildRuntimeAuth(args) {
     // The "openai-env" channel accepts CODEX_API_KEY or OPENAI_API_KEY as the runtime key SOURCE
     // name, read in this preference order. CODEX_API_KEY is preferred: the official Codex docs
     // (developers.openai.com/codex/noninteractive) document it as the channel for a SINGLE codex exec
@@ -458,7 +459,7 @@ function buildCommandScopedRuntimeEnv(args) {
         return {
             ok: false,
             code: "HUMANISH_TERMINAL_LAB_RUNTIME_AUTH_MISSING",
-            message: `Live terminal-product labs declare runtimeAuth "${String(args.runtimeAuth)}" and need ${ALLOWED_RUNTIME_KEY_NAMES.join(" or ")} in the environment (pass via --env-file; the value is injected ONLY into the command-scoped codex invocation and is never persisted).`
+            message: `Live terminal-product labs declare runtimeAuth "${String(args.runtimeAuth)}" and need ${ALLOWED_RUNTIME_KEY_NAMES.join(" or ")} in the environment (pass via --env-file; the selected auth mode places the value in command-scoped env or an external E2B header transform; the value is never persisted).`
         };
     }
     const keyValue = args.env[keyName];
@@ -466,9 +467,15 @@ function buildCommandScopedRuntimeEnv(args) {
     // GITHUB_TOKEN/GH_TOKEN, no payment/deploy/db/media key, excluded by construction. When the
     // SOURCE was OPENAI_API_KEY, the SAME value is also injected as CODEX_API_KEY so codex exec's
     // documented single-invocation auth channel is populated either way (see the comment above).
-    const envs = keyName === "OPENAI_API_KEY" ? { CODEX_API_KEY: keyValue, OPENAI_API_KEY: keyValue } : { [keyName]: keyValue };
+    const mode = args.runtimeAuth ?? "openai-env";
+    const envs = mode === "openai-egress"
+        // Codex documents this verified-TLS trust channel. The stock image's default OpenSSL CA
+        // file can be absent even though E2B has installed its proxy CA in the system bundle.
+        ? { CODEX_API_KEY: OPENAI_EGRESS_PLACEHOLDER, CODEX_CA_CERTIFICATE: E2B_SYSTEM_CA_BUNDLE }
+        : keyName === "OPENAI_API_KEY" ? { CODEX_API_KEY: keyValue, OPENAI_API_KEY: keyValue } : { [keyName]: keyValue };
     return {
         ok: true,
+        mode,
         envs,
         keyName,
         keyValue
@@ -525,21 +532,20 @@ async function runLiveTerminalSession(args) {
     const env = hooks.env ?? process.env;
     const now = hooks.now ?? (() => Date.now());
     const nowIso = () => new Date(now()).toISOString();
-    // --- Safety contract item 1: ENGINE-ENFORCED command-scoped key placement. ---
-    // Drive the placement off the registered actor's keyPlacement CAPABILITY, not a code convention.
-    // A terminal actor that does not declare in-sandbox-command-scoped placement FAILS CLOSED here,
-    // before any sandbox exists — the engine refuses to guess where the key goes.
+    // Check the registered terminal actor's default placement contract before launching. The
+    // explicit openai-egress mode overrides the resolved trace's placement to external; registry
+    // metadata continues to describe the compatible openai-env default.
     const descriptor = actorRegistry[descriptorId];
     const keyPlacement = descriptor?.capabilities.keyPlacement;
     if (keyPlacement !== "in-sandbox-command-scoped") {
-        return failed("HUMANISH_TERMINAL_LAB_KEYPLACEMENT_INVALID", `Terminal actor "${descriptorId}" must declare keyPlacement "in-sandbox-command-scoped" for the live lane (got "${String(keyPlacement)}"). The engine routes the runtime key by this capability; without it the lane cannot place the key safely and fails closed.`, { actor: descriptorId });
+        return failed("HUMANISH_TERMINAL_LAB_KEYPLACEMENT_INVALID", `Terminal actor "${descriptorId}" must declare keyPlacement "in-sandbox-command-scoped" for the live lane (got "${String(keyPlacement)}"). The engine requires this registered default before applying the declared runtime-auth mode.`, { actor: descriptorId });
     }
     // --- Safety contract item 2: a fail-closed cap MUST be in force before the live key runs. ---
     const caps = config.scenario?.caps;
     const maxUsd = caps?.maxUsd;
     const maxMinutes = caps?.maxMinutes;
     if (caps === undefined || maxUsd === undefined || maxMinutes === undefined || maxMinutes <= 0) {
-        return failed("HUMANISH_TERMINAL_LAB_CAPS_MISSING", "A live terminal-product run passes a real key to the in-sandbox agent command 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.", { actor: descriptorId });
+        return failed("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.", { actor: descriptorId });
     }
     // maxUsd is ENFORCED fail-closed against the cost ledger (evaluateCapsAgainstLedger after the
     // session), not advisory. A positive maxUsd is permitted, but core still has no
@@ -552,7 +558,7 @@ async function runLiveTerminalSession(args) {
         warnings.push(`scenario.caps.maxUsd=${maxUsd} declares a non-zero spend budget. maxUsd is enforced fail-closed against the cost ledger, but core meters only the provider line from tokenUsage; product/media/payment stay null (UNMEASURED, never guessed zero) unless an adapter supplies those signals through costProbe. The no-spend proof reports unmeasured lines honestly.`);
     }
     // --- Safety contract item 4: deny-by-default credentials; build the command-scoped allowlist. ---
-    const runtimeEnv = buildCommandScopedRuntimeEnv({ runtimeAuth: config.execution?.runtimeAuth, env });
+    const runtimeEnv = buildRuntimeAuth({ runtimeAuth: config.execution?.runtimeAuth, env });
     if (!runtimeEnv.ok) {
         return failed(runtimeEnv.code, runtimeEnv.message, { actor: descriptorId });
     }
@@ -610,6 +616,10 @@ async function runLiveTerminalSession(args) {
     const lifecycle = [];
     const commandLog = [];
     const terminalEvents = [];
+    // Capture may stop inside a known key. Keep only enough following characters to finish the
+    // cross-chunk redaction below; this overlap is never added to terminal events/artifacts.
+    const discardedPrefixes = { stdout: "", stderr: "", combined: "" };
+    const maxDiscardedPrefixChars = Math.max(0, ...knownSecretValues.map((value) => value.length - 1));
     const interventions = []; // ALWAYS empty while no assisted-input path ships.
     let transcriptBytes = 0;
     let cleanup = { killed: false, remaining: -1, reason: "teardown not reached" };
@@ -617,12 +627,49 @@ async function runLiveTerminalSession(args) {
         lifecycle.push({ at: nowIso(), event, message: sanitize(message) });
     };
     const appendTerminalChunk = (stream, raw) => {
-        if (transcriptBytes >= MAX_TRANSCRIPT_BYTES)
+        if (transcriptBytes >= MAX_TRANSCRIPT_BYTES) {
+            for (const order of [stream, "combined"]) {
+                const remaining = maxDiscardedPrefixChars - discardedPrefixes[order].length;
+                if (remaining > 0)
+                    discardedPrefixes[order] += raw.slice(0, remaining);
+            }
             return;
+        }
         transcriptBytes += Buffer.byteLength(raw, "utf8");
         // Scrub THEN redact at the SOURCE — raw bytes never leave this function (safety contract item 5).
         terminalEvents.push({ at: nowIso(), stream, chunk: sanitize(raw) });
     };
+    // E2B can stream every byte through callbacks AND return the same complete output (#667).
+    // Track transport delivery, independently per stream, rather than deduplicating participant
+    // lines or equal usage records. Hash raw callback bytes before redaction/truncation so the
+    // comparison cannot confuse two values that redact identically or lose capped-away delivery.
+    // Delivery tracking retains only counts and hashes; payloads still pass the artifact sanitizer.
+    const streamedOutput = {
+        stdout: { bytes: 0, hash: createHash("sha256") },
+        stderr: { bytes: 0, hash: createHash("sha256") }
+    };
+    const recordStreamedTerminalChunk = (stream, raw) => {
+        streamedOutput[stream].bytes += Buffer.byteLength(raw, "utf8");
+        streamedOutput[stream].hash.update(raw, "utf8");
+        appendTerminalChunk(stream, raw);
+    };
+    const appendReturnedTerminalOutput = (stream, raw) => {
+        const delivered = streamedOutput[stream];
+        const returned = Buffer.from(raw, "utf8");
+        if (delivered.bytes > 0 && returned.length >= delivered.bytes) {
+            const returnedPrefixHash = createHash("sha256").update(returned.subarray(0, delivered.bytes)).digest("hex");
+            if (returnedPrefixHash === delivered.hash.copy().digest("hex")) {
+                // A complete replay adds nothing; a partly streamed prefix keeps only the unseen tail.
+                const suffix = returned.subarray(delivered.bytes).toString("utf8");
+                if (suffix)
+                    appendTerminalChunk(stream, suffix);
+                return;
+            }
+        }
+        // Older/final-only SDK delivery, or output that does not match the streamed prefix: keep it.
+        // Guessing at overlap here could erase legitimate repeated participant text.
+        appendTerminalChunk(stream, raw);
+    };
     let sandbox;
     let sandboxModule;
     let sandboxId;
@@ -631,6 +678,11 @@ async function runLiveTerminalSession(args) {
     let sessionReason = "live terminal-product session did not start";
     let sessionError;
     let timedOut = false;
+    const runtime = declaredRuntimeProvenance({
+        ...(config.execution?.runtime?.version === undefined ? {} : { version: config.execution.runtime.version }),
+        ...(config.actors[0]?.model === undefined ? {} : { model: sanitize(config.actors[0].model) }),
+        ...(config.actors[0]?.reasoningEffort === undefined ? {} : { reasoningEffort: config.actors[0].reasoningEffort })
+    });
     recordLifecycle("terminal-lab.run.created", `Created live terminal-product run ${runId} (actor ${descriptorId}, product ${product.name}). Caps: maxUsd=${maxUsd}, maxMinutes=${maxMinutes}. Subject provenance UNPINNED (public surfaces only).`);
     const requestTimeoutMs = DEFAULT_REQUEST_TIMEOUT_MS;
     const wallClockMs = maxMinutes * 60_000;
@@ -639,50 +691,48 @@ async function runLiveTerminalSession(args) {
     try {
         sandboxModule = await (hooks.loadModule ?? loadE2BDesktopModule)();
         await validatePreparedRunArtifactPaths(runPaths);
-        // SAFETY CONTRACT ITEM 1 (enforced HERE): Sandbox.create carries metadata (positive allowlist)
-        // + lifecycle kill-on-timeout, and DELIBERATELY NO `envs` — the runtime key is NEVER passed
-        // sandbox-global. It is injected ONLY into the per-command codex `envs` below.
+        // 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;
         sandbox = await sandboxModule.Sandbox.create({
             apiKey: e2bApiKey,
             requestTimeoutMs,
             timeoutMs: sandboxTimeoutMs,
             metadata,
-            // Egress allowlist when the lab declares one (#538). This is the ONE bound on the injected
-            // runtime key that does not depend on the participant's cooperation: codex spawns the
-            // participant's shell as a child, so it inherits that key and can spend it anywhere it can
-            // reach. It cannot reach a host that is not on this list. Absent means unrestricted, the
-            // historical default, because a wrong host list fails studies in confusing ways.
-            ...(egressAllow === undefined
-                ? {}
-                : { network: { allowOut: egressAllow, denyOut: ["0.0.0.0/0"] } }),
+            ...(network === undefined ? {} : { network }),
             lifecycle: { onTimeout: "kill" }
-            // NOTE: no `envs` key — see the credential boundary above. (A sandbox-global key would leak
-            // into every process in the sandbox; command-scoped bounds it to the codex invocation.)
         });
         await validatePreparedRunArtifactPaths(runPaths);
         sandboxId = sandbox.sandboxId;
         // #358 salvage: durable id receipt the moment the sandbox exists (reclaim by exact id).
         await appendSandboxReceipt(runPaths, { at: nowIso(), laneId: "terminal", sandboxId, timeoutMs: sandboxTimeoutMs });
-        recordLifecycle("terminal-lab.sandbox.created", `E2B shell sandbox ${sandboxId} created with positive-allowlist metadata and kill-on-timeout; NO sandbox-global env (runtime key is command-scoped).`);
+        recordLifecycle("terminal-lab.sandbox.created", `E2B shell sandbox ${sandboxId} created with positive-allowlist metadata and kill-on-timeout; NO sandbox-global env.`);
         // 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): the injected runtime key can reach any host."
-            : `Egress DENIED except ${egressAllow.length} declared host(s): ${egressAllow.join(", ")}.`);
-        // Readiness: a tiny in-sandbox probe (no key) confirms the shell answers before the keyed run.
+            ? "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.");
+        }
+        // Readiness: a tiny probe receives no runtime env; openai-egress's proxy is already available.
         const ready = await 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.`);
-        // --- Runtime bootstrap: ensure Node/npm are present (UNKEYED, no envs) before the keyed exec. ---
-        // The stock @e2b/desktop image does not ship a recent Node (issue #159); codex is now invoked
-        // via `npx` (buildCodexExecCommand), which needs Node/npm on PATH. Reuses the proven
-        // oss-meta-lab.ts ensure_node() shape: a node major-version check, else install Node 22 via
-        // NodeSource plus passwordless sudo. UNKEYED: no runtime key touches this step. An apt-get
-        // install can exceed the SDK's default 60s commands.run timeout, so this step gets an
-        // explicit, generous timeoutMs (requestTimeoutMs is passed through unchanged, as everywhere else).
+        // --- 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 sandbox.commands.run(RUNTIME_BOOTSTRAP_COMMAND, {
+            const bootstrap = await sandbox.commands.run(TERMINAL_NODE_BOOTSTRAP_COMMAND, {
                 requestTimeoutMs,
                 timeoutMs: RUNTIME_BOOTSTRAP_TIMEOUT_MS
             });
@@ -707,7 +757,34 @@ async function runLiveTerminalSession(args) {
             sessionReason = `runtime bootstrap could not ensure Node/npm before codex exec: ${sessionError}`;
         }
         else if (await (async () => {
-            // --- Optional product setup (UNKEYED, no envs), before the keyed exec. ---
+            // 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 sandbox.commands.run(buildRuntimeVersionCommand(config.execution?.runtime?.version), {
+                    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 (config.execution?.runtime?.version !== undefined && observed !== config.execution.runtime.version) {
+                    throw new Error(`Codex version mismatch: requested ${config.execution.runtime.version}, 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";
+                sessionStatus = "failed";
+                completionReason = "harness_error";
+                sessionError = sanitize(toErrorMessage(error));
+                sessionReason = `Codex runtime version could not be verified before execution: ${sessionError}`;
+                recordLifecycle("terminal-lab.runtime.version.error", sessionReason);
+                return false;
+            }
+            // --- 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
@@ -745,7 +822,7 @@ async function runLiveTerminalSession(args) {
                     // 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='${destination.replace(/'/g, "'\\''")}'; `;
-                    recordLifecycle("terminal-lab.product.uploaded", `Uploaded ${info.size} bytes to the sandbox in ${Math.max(0, now() - uploadStartedAt)}ms (UNKEYED).`);
+                    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) {
                     sessionStatus = "failed";
@@ -775,7 +852,7 @@ async function runLiveTerminalSession(args) {
             }
             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 (UNKEYED).`);
+                : `Product setup completed in ${Math.max(0, now() - setupStartedAt)}ms (no runtime env; declared egress auth may already be available).`);
             if (setupError) {
                 sessionStatus = "failed";
                 completionReason = "harness_error";
@@ -786,38 +863,43 @@ async function runLiveTerminalSession(args) {
             return true;
         })()) {
             // --- The keyed run: `codex exec --json` non-interactively (stdin disabled). ---
-            // The runtime key is injected ONLY here, command-scoped (safety contract item 1). stdin is
+            // 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 });
+            const codexCommand = buildCodexExecCommand({
+                workdir: SANDBOX_WORKDIR, prompt: composedPrompt, runtimeAuth: runtimeEnv.mode,
+                version: runtime.observedVersion,
+                ...(config.actors[0]?.model === undefined ? {} : { model: config.actors[0].model }),
+                ...(config.actors[0]?.reasoningEffort === undefined ? {} : { reasoningEffort: config.actors[0].reasoningEffort })
+            });
             const commandDigest = digestText(codexCommand);
             const startedAt = now();
-            recordLifecycle("terminal-lab.exec.started", `Launching codex exec (command-scoped runtime key ${runtimeEnv.keyName}); wall-clock bound ${wallClockMs}ms.`);
+            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(sandbox.commands.run(codexCommand, {
-                    // <-- THE command-scoped key channel. The ONLY place the key goes. The participant
+                    // 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) => appendTerminalChunk("stdout", data),
-                    onStderr: (data) => appendTerminalChunk("stderr", data)
+                    onStdout: (data) => recordStreamedTerminalChunk("stdout", data),
+                    onStderr: (data) => recordStreamedTerminalChunk("stderr", data)
                 }), wallClockMs, now);
                 if (result.timedOut) {
                     timedOut = true;
                 }
                 else {
                     exitCode = result.value.exitCode;
-                    // Some SDK shapes return final stdout/stderr in the result too (not only via callbacks).
+                    // Reconcile the SDK's returned aggregate against bytes already delivered by callbacks.
                     if (result.value.stdout)
-                        appendTerminalChunk("stdout", result.value.stdout);
+                        appendReturnedTerminalOutput("stdout", result.value.stdout);
                     if (result.value.stderr)
-                        appendTerminalChunk("stderr", result.value.stderr);
+                        appendReturnedTerminalOutput("stderr", result.value.stderr);
                     if (result.value.error)
                         runError = result.value.error;
                 }
@@ -888,6 +970,10 @@ async function runLiveTerminalSession(args) {
             warnings
         });
     }
+    // Prefix reconciliation may cut through a known key. Scrub literal values across the retained
+    // chunks before any transcript/trace/event artifact is persisted. Check both each stream and
+    // the combined event order that the transcript uses; either view can assemble a split value.
+    scrubSplitKnownValues(terminalEvents, knownSecretValues, discardedPrefixes);
     // Build the actor trace FIRST (the cost ledger reads its tokenUsage).
     const normalizedTranscript = normalizeLocalActorTranscript(terminalEvents.map((e) => e.chunk).join(""));
     // Parsed from the FULL stream, not the tail: usage records arrive once per turn and the tail
@@ -905,6 +991,8 @@ async function runLiveTerminalSession(args) {
         terminalEvents,
         commandLog,
         transcriptTail: tailOf(normalizedTranscript),
+        runtimeAuth: runtimeEnv.mode,
+        runtime,
         ...(terminalTokenUsage === undefined ? {} : { tokenUsage: terminalTokenUsage })
     });
     // --- Spend ledger + no-spend proof + full caps enforcement (fail-closed). ---
@@ -945,6 +1033,7 @@ async function runLiveTerminalSession(args) {
     // event stream, the normalized transcript, the actor trace, and the run bundle.
     const ledgers = {
         schema: "humanish.terminal-ledgers.v1",
+        runtime,
         lifecycle,
         commandLog,
         interventions, // ALWAYS present, ALWAYS empty while no assisted-input path ships.
@@ -968,6 +1057,7 @@ async function runLiveTerminalSession(args) {
         publicSurfaces: product.publicSurfaces,
         caps,
         runtimeAuthKeyName: runtimeEnv.keyName,
+        runtimeAuth: runtimeEnv.mode,
         policies: {
             allowPrivateRepoAccess: config.policies?.allowPrivateRepoAccess ?? false,
             allowProviderCredentials: config.policies?.allowProviderCredentials ?? false,
@@ -1350,6 +1440,58 @@ async function runWithWallClock(promise, wallClockMs, now) {
     }
     return value;
 }
+/**
+ * Per-chunk sanitization cannot recognize a value split across deliveries. Redact those complete
+ * known values before persistence without collapsing events or changing stdout/stderr ordering.
+ * Work backwards through matches so edits to later text leave earlier offsets valid.
+ */
+function scrubSplitKnownValues(events, knownValues, discardedPrefixes) {
+    for (const order of ["stdout", "stderr", "combined"]) {
+        const chunks = order === "combined"
+            ? [...events]
+            : events.filter((event) => event.stream === order);
+        // A virtual final chunk makes a key crossing the capture cap recognizable. Edits to retained
+        // events redact evidence; the raw overlap and this virtual chunk are never persisted.
+        if (discardedPrefixes[order])
+            chunks.push({ chunk: discardedPrefixes[order] });
+        for (const value of knownValues) {
+            if (!value)
+                continue;
+            let offset = 0;
+            const starts = chunks.map((event) => {
+                const start = offset;
+                offset += event.chunk.length;
+                return start;
+            });
+            const text = chunks.map((event) => event.chunk).join("");
+            const matches = [];
+            for (let at = text.indexOf(value); at !== -1; at = text.indexOf(value, at + value.length))
+                matches.push(at);
+            for (const at of matches.reverse()) {
+                let first = 0;
+                while (first + 1 < starts.length && (starts[first + 1] ?? Infinity) <= at)
+                    first += 1;
+                let last = first;
+                while (last + 1 < starts.length && (starts[last + 1] ?? Infinity) < at + value.length)
+                    last += 1;
+                const firstChunk = chunks[first];
+                const lastChunk = chunks[last];
+                if (!firstChunk || !lastChunk)
+                    continue;
+                const before = firstChunk.chunk.slice(0, at - (starts[first] ?? 0));
+                const after = lastChunk.chunk.slice(at + value.length - (starts[last] ?? 0));
+                firstChunk.chunk = `${before}[REDACTED_SECRET]${first === last ? after : ""}`;
+                for (let index = first + 1; index < last; index += 1) {
+                    const middle = chunks[index];
+                    if (middle)
+                        middle.chunk = "";
+                }
+                if (first !== last)
+                    lastChunk.chunk = after;
+            }
+        }
+    }
+}
 /** 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
@@ -1364,7 +1506,13 @@ function buildCodexExecCommand(args) {
     // The E2B sandbox is the trust boundary (the disposable machine); the sibling
     // oss-meta-lab lane carries the same flag at both live call sites for the
     // same reason, and exec mode has no interactive approval channel at all.
-    return `cd ${args.workdir} && npm_config_update_notifier=false npx -y @openai/codex@latest exec --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check --json ${quotedPrompt}`;
+    // 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}`;
 }
 /** Compose the live prompt: PUBLIC surfaces + author mission + the verdict-nonce marker contract. */
 function composeLivePrompt(args) {
@@ -1409,6 +1557,8 @@ function buildTerminalActorTrace(args) {
     return {
         schema: ACTOR_TRACE_SCHEMA,
         provider: "codex",
+        ...(args.runtime.versionStatus === "verified" ? { providerVersion: args.runtime.observedVersion } : {}),
+        runtime: args.runtime,
         protocol: "terminal-exec",
         lane: "terminal",
         persona: args.persona,
@@ -1423,7 +1573,7 @@ function buildTerminalActorTrace(args) {
         status: args.status,
         completionReason: args.completionReason,
         reason: args.reason,
-        ids: { model: "codex" },
+        ids: {}, // Runtime model requests are not observed; declarations live in runtime provenance.
         ...(args.tokenUsage ? { tokenUsage: args.tokenUsage } : {}),
         counts: {
             commands: args.commandLog.length,
@@ -1434,7 +1584,9 @@ function buildTerminalActorTrace(args) {
             terminalEvents: args.terminalEvents.length
         },
         items,
-        capabilities: TERMINAL_AGENT_CAPABILITIES
+        capabilities: args.runtimeAuth === "openai-egress"
+            ? { ...TERMINAL_AGENT_CAPABILITIES, keyPlacement: "external" }
+            : TERMINAL_AGENT_CAPABILITIES
     };
 }
 /**
@@ -1518,7 +1670,7 @@ export function buildTerminalProductBundle(args) {
             type: "terminal-lab.credentials.declared",
             // Names-only evidence (invariant 1): the runtime-auth CHANNEL is declared; no value is ever
             // recorded. The deny-by-default policies are recorded so the credential posture is auditable.
-            message: `Runtime auth channel: ${args.runtimeAuth ?? "none declared"} (names only; values never persist; command-scoped injection is enforced by the shipped live engine, while this dry-run performs no injection). Credential policies (deny-by-default): allowPrivateRepoAccess=${args.policies.allowPrivateRepoAccess}, allowProviderCredentials=${args.policies.allowProviderCredentials}, allowPaymentCredentials=${args.policies.allowPaymentCredentials}, allowGitHubMutation=${args.policies.allowGitHubMutation}.`,
+            message: `Runtime auth channel: ${args.runtimeAuth ?? "none declared"} (names only; values never persist; the live engine applies the selected key placement, while this dry-run performs no injection). Credential policies (deny-by-default): allowPrivateRepoAccess=${args.policies.allowPrivateRepoAccess}, allowProviderCredentials=${args.policies.allowProviderCredentials}, allowPaymentCredentials=${args.policies.allowPaymentCredentials}, allowGitHubMutation=${args.policies.allowGitHubMutation}.`,
             simId: "sim-001",
             streamId: "stream-001"
         },
@@ -1536,7 +1688,7 @@ export function buildTerminalProductBundle(args) {
             at: args.createdAt,
             level: "info",
             type: "terminal-lab.contract.ready",
-            message: "Dry-run contract bundle ready. Switch scenario.mode to live with the required runtime auth and caps to exercise the in-sandbox agent route, captured exec stream, and command-scoped credential boundary.",
+            message: "Dry-run contract bundle ready. Switch scenario.mode to live with the required runtime auth and caps to exercise the in-sandbox agent route, captured exec stream, and declared runtime-auth placement.",
             simId: "sim-001",
             streamId: "stream-001"
         }
@@ -1737,7 +1889,7 @@ export function buildLiveTerminalProductBundle(args) {
         events: lifecycleEvents,
         redaction: {
             status: "passed",
-            notes: `Live terminal-product run: the in-sandbox agent's output was captured via commands.run onStdout/onStderr and scrubbed (literal known values incl. the runtime key) THEN redacted (shape patterns) AT THE SOURCE before persisting. The runtime key (${args.runtimeAuthKeyName}) was injected ONLY into the command-scoped codex invocation, never sandbox-global env or metadata; only its NAME appears in evidence. Subject provenance is UNPINNED (public-surface study).`
+            notes: `Live terminal-product run: the in-sandbox agent's output was captured via commands.run onStdout/onStderr and scrubbed (literal known values incl. the runtime key) THEN redacted (shape patterns) AT THE SOURCE before persisting. ${args.runtimeAuth === "openai-egress" ? `Runtime auth openai-egress: the raw key from ${args.runtimeAuthKeyName} is reserved for E2B's external api.openai.com HTTPS header transform. ${args.ledgers.commandLog.some((command) => command.label === "codex-exec") ? "Codex received an inert CODEX_API_KEY placeholder." : "Codex was not launched."} Any created sandbox retains a spendable OpenAI proxy capability until teardown; additional provider calls may not appear in the Codex usage ledger.` : `Runtime auth openai-env: the runtime key (${args.runtimeAuthKeyName}) was injected ONLY into the command-scoped codex invocation, never sandbox-global env or metadata; only its NAME appears in evidence.`} Subject provenance is UNPINNED (public-surface study).`
         },
         artifacts: {
             run: "run.json",