humanish 0.104.3 → 0.106.0

package/dist/routes/terminal/credentials.js

@@ -0,0 +1,102 @@
+import { E2B_SYSTEM_CA_BUNDLE, OPENAI_EGRESS_PLACEHOLDER } from "./runtime-auth.js";
+import { TERMINAL_PRODUCT_LAB_PROVIDER_METADATA } from "./types.js";
+/**
+ * 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.
+ */
+export 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
+    // invocation, which is exactly this lane's shape (no persisted auth.json/CODEX_HOME, per-command
+    // envs only). A dated in-repo receipt
+    // (docs/goals/humanish-recursive-proof-critical-point/receipts/actor-required-attempt.md) shows a
+    // job-wide OPENAI_API_KEY alone failing bearer auth for this same pinned-exec pattern. When the
+    // operator only exported OPENAI_API_KEY, its value is ALSO injected under CODEX_API_KEY below, so
+    // the documented exec auth channel is always populated regardless of which name the operator
+    // used. The ALLOWLIST is exactly these two names; everything else is denied by construction.
+    const ALLOWED_RUNTIME_KEY_NAMES = ["CODEX_API_KEY", "OPENAI_API_KEY"];
+    // Tripwire (safety contract item 4): if a FUTURE widening of ALLOWED_RUNTIME_KEY_NAMES ever
+    // added a clearly-non-runtime credential (a GitHub/payment/deploy/db secret), fail closed. The
+    // generic `*_KEY` shape is deliberately NOT a tripwire here, since a runtime key legitimately
+    // ends in _KEY (CODEX_API_KEY/OPENAI_API_KEY), so testing it against the generic shape would
+    // false-positive on the very key this lane exists to inject. The positive allowlist itself is
+    // the real boundary: the command env is built from exactly these names and nothing else (so
+    // GITHUB_TOKEN/payment/db keys present in the operator env are never forwarded, proven by the
+    // deterministic test).
+    if (ALLOWED_RUNTIME_KEY_NAMES.some((name) => isNonRuntimeCredentialName(name))) {
+        return {
+            ok: false,
+            code: "HUMANISH_TERMINAL_LAB_CREDENTIAL_DENIED",
+            message: "Internal invariant violated: a runtime-key allowlist entry is a non-runtime credential (GitHub/payment/deploy/db).",
+        };
+    }
+    const keyName = ALLOWED_RUNTIME_KEY_NAMES.find((name) => (args.env[name]?.trim() ?? "").length > 0);
+    if (!keyName) {
+        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 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];
+    // The command-scoped env is the ALLOWLIST: exactly the runtime key name(s), nothing else. No
+    // 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 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,
+    };
+}
+// Clearly-non-runtime credential NAME shapes. Used as the runtime-key allowlist tripwire (a
+// runtime key must never be one of these). Deliberately EXCLUDES the generic `*_KEY` shape: the
+// runtime key this lane injects (CODEX_API_KEY/OPENAI_API_KEY) legitimately ends in _KEY, so the
+// generic shape would false-positive on it. The positive allowlist, not a denylist, is what
+// keeps every OTHER operator-env credential (GitHub/payment/deploy/db/media keys) out of the
+// sandbox: the command env is built from exactly the allowlisted runtime key and nothing else.
+const NON_RUNTIME_CREDENTIAL_NAME_PATTERNS = [
+    /^GITHUB_TOKEN$/i,
+    /^GH_TOKEN$/i,
+    /TOKEN$/i, // deploy tokens, write tokens
+    /SECRET/i, // *_SECRET, payment secrets
+    /PASSWORD/i,
+    /DATABASE_URL/i,
+    /(^|_)DSN$/i,
+    /STRIPE/i,
+    /AWS_/i,
+];
+/** True when `name` is a clearly-non-runtime credential (cannot be a runtime-key allowlist entry). */
+function isNonRuntimeCredentialName(name) {
+    return NON_RUNTIME_CREDENTIAL_NAME_PATTERNS.some((pattern) => pattern.test(name));
+}
+/**
+ * Build the sandbox metadata from a POSITIVE ALLOWLIST (safety contract item 6). This is the ONLY
+ * way metadata is set on the terminal lane — it carries solely non-secret labels and rejects any
+ * value that is not a plain short label. A verifier check asserts the persisted metadata has no
+ * prompt/token/secret shapes; this builder makes that true by construction.
+ */
+export function buildSandboxMetadata(allowlist) {
+    return {
+        mode: TERMINAL_PRODUCT_LAB_PROVIDER_METADATA.mode,
+        tool: TERMINAL_PRODUCT_LAB_PROVIDER_METADATA.tool,
+        provider: "codex",
+        labId: allowlist.labId,
+        simId: allowlist.simId,
+        // The run id is a harness-minted token (terminal-<ts>-<hex>), not user data.
+        runId: allowlist.runId,
+    };
+}

package/dist/routes/terminal/dry-run.d.ts

@@ -0,0 +1,24 @@
+import type { TerminalPlan } from "../../lab/plan-types.js";
+import type { RunScope } from "../../run/run.js";
+import { type RunLiveTerminalSessionArgs, type TerminalProductLabResult, type TerminalRunInput } from "./types.js";
+/**
+ * The dry-run path: a contract bundle with the persona and prompt digest bound, published through
+ * the run scope with no sandbox, key or spend.
+ */
+export declare function runDryTerminalLab(args: {
+    plan: Extract<TerminalPlan, {
+        readonly dryRun: true;
+    }>;
+    input: TerminalRunInput;
+    cwd: string;
+    warnings: string[];
+    failed: RunLiveTerminalSessionArgs["failed"];
+    scope: RunScope;
+}): Promise<TerminalProductLabResult>;
+/** Compose the full prompt the agent would run. Bound to evidence by DIGEST only. */
+export declare function composePrompt(args: {
+    mission: string;
+    personaLine: string;
+    productName: string;
+    publicSurfaces: readonly string[];
+}): string;

package/dist/routes/terminal/dry-run.js

@@ -0,0 +1,157 @@
+// The terminal route's dry run: a contract-only bundle with the persona and prompt digest bound,
+// published through the run scope with no sandbox, key or spend. session.ts holds the live path.
+import { digestText, redactText, scrubLiterals } from "../../evidence/redaction.js";
+import { participantAssignment } from "../../lab/participant-assignment.js";
+import { buildRunSource } from "../../run/bundle.js";
+import { judgeExecution, judgeTerminal, OUTCOME_POLICIES, resultOk } from "../../run/judge.js";
+import { validatePreparedRunArtifactPaths } from "../../run/paths.js";
+import { buildTerminalProductBundle, renderTerminalReviewMarkdown } from "./bundle.js";
+import { resolveTerminalPersona, terminalPersonaRef } from "./persona.js";
+import { declaredRuntimeProvenance } from "./runtime.js";
+import { defaultMission, makeTerminalRunId } from "./session.js";
+import { TERMINAL_PRODUCT_LAB_SCHEMA, } from "./types.js";
+/**
+ * The dry-run path: a contract bundle with the persona and prompt digest bound, published through
+ * the run scope with no sandbox, key or spend.
+ */
+export async function runDryTerminalLab(args) {
+    const { plan, input, cwd, warnings, failed, scope } = args;
+    const { product } = plan;
+    const hooks = input.hooks ?? {};
+    const { evidenceMission, physicalCwd, persona } = await prepareDryPersona({
+        plan,
+        cwd,
+        env: hooks.env ?? process.env,
+        warnings,
+    });
+    const started = await scope.startRun({
+        cwd: physicalCwd,
+        runId: input.runId,
+        mintRunId: makeTerminalRunId,
+        mode: "dry-run",
+        lab: plan.lab,
+        renderReview: renderTerminalReviewMarkdown,
+        observer: { open: input.open === true, render: hooks.renderObserverFn },
+    });
+    if (!started.ok)
+        return failed(started.code, started.message);
+    const { run } = started;
+    const { runId, createdAt } = run;
+    const source = await buildRunSource({
+        capturedAt: createdAt,
+        cwd: physicalCwd,
+        humanishSource: "present",
+        packageName: "humanish",
+    });
+    const policies = plan.residual.policies;
+    const judgment = judgeTerminal({ dryRun: true, participant: undefined });
+    const bundle = buildTerminalProductBundle({
+        ...(plan.lab === undefined ? {} : { lab: plan.lab }),
+        actorId: plan.actor,
+        createdAt,
+        dryRun: true,
+        labId: plan.labId,
+        ...(plan.title ? { labTitle: plan.title } : {}),
+        mission: evidenceMission,
+        persona,
+        productName: product.name,
+        publicSurfaces: product.publicSurfaces,
+        ...(plan.caps ? { caps: plan.caps } : {}),
+        ...(plan.runtime.auth ? { runtimeAuth: plan.runtime.auth } : {}),
+        stdin: plan.stdin ?? "disabled",
+        policies: {
+            allowPrivateRepoAccess: policies?.allowPrivateRepoAccess ?? false,
+            allowProviderCredentials: policies?.allowProviderCredentials ?? false,
+            allowPaymentCredentials: policies?.allowPaymentCredentials ?? false,
+            allowGitHubMutation: policies?.allowGitHubMutation ?? false,
+        },
+        runId,
+        source,
+        verdict: judgment.verdict,
+    });
+    bundle.events.push(runtimeDeclaredEvent(plan.runtime, createdAt));
+    const finished = await run.finish(bundle);
+    const observer = await finished.renderObserver();
+    await validatePreparedRunArtifactPaths(finished.paths);
+    const policy = OUTCOME_POLICIES.terminal;
+    const execution = judgeExecution(observer.ok
+        ? []
+        : [
+            {
+                kind: "evidence",
+                message: observer.error?.message ?? "Observer failed for the terminal-product lab run.",
+            },
+        ], policy);
+    const ok = resultOk({ judgment, execution, scorerFailures: [], policy });
+    await finished.recordOutcome({ ok, execution });
+    return {
+        schema: TERMINAL_PRODUCT_LAB_SCHEMA,
+        ok,
+        cwd,
+        labId: plan.labId,
+        actor: plan.actor,
+        product: product.name,
+        dryRun: true,
+        runId,
+        observer,
+        warnings: [...warnings, ...observer.warnings],
+        ...(ok
+            ? {}
+            : {
+                error: {
+                    code: "HUMANISH_TERMINAL_LAB_FAILED",
+                    message: observer.error?.message ?? "Observer failed for the terminal-product lab run.",
+                },
+            }),
+    };
+}
+/**
+ * The persona and prompt digest a dry run records: the author mission with known key values
+ * scrubbed, and the committed persona's traits and brief.
+ */
+async function prepareDryPersona(args) {
+    const { plan, cwd, env, warnings } = args;
+    const { product } = plan;
+    const mission = plan.mission ?? defaultMission(product.name);
+    const knownSecretValues = [env.CODEX_API_KEY, env.OPENAI_API_KEY, env.E2B_API_KEY]
+        .map((value) => value?.trim() ?? "")
+        .filter((value) => value.length >= 4);
+    const evidenceMission = participantAssignment({ mission }, scrubLiterals(knownSecretValues)).mission;
+    const terminalPersona = await resolveTerminalPersona({ plan, cwd, warnings });
+    // The composed prompt = mission + persona + public-surface manifest. Only the AUTHOR mission
+    // goes plaintext into evidence (it is public-safe committed lab text); the full composed prompt
+    // is recorded as a DIGEST (the safety contract's mission ruling).
+    const composedPrompt = composePrompt({
+        mission,
+        personaLine: terminalPersona.personaLine,
+        productName: product.name,
+        publicSurfaces: product.publicSurfaces,
+    });
+    const persona = terminalPersonaRef(terminalPersona, digestText(composedPrompt), scrubLiterals(knownSecretValues));
+    const { physicalCwd } = terminalPersona;
+    return { evidenceMission, physicalCwd, persona };
+}
+/** The declared runtime provenance as a dry-run event; nothing is observed without a sandbox. */
+function runtimeDeclaredEvent(runtime, createdAt) {
+    const { version, model, reasoningEffort } = runtime;
+    return {
+        id: "event-terminal-runtime-declared",
+        at: createdAt,
+        level: "info",
+        type: "terminal-lab.runtime.declared",
+        message: redactText(JSON.stringify(declaredRuntimeProvenance({
+            ...(version === undefined ? {} : { version }),
+            ...(model === undefined ? {} : { model }),
+            ...(reasoningEffort === undefined ? {} : { reasoningEffort }),
+        }))),
+    };
+}
+/** Compose the full prompt the agent would run. Bound to evidence by DIGEST only. */
+export function composePrompt(args) {
+    return [
+        args.personaLine,
+        `product: ${args.productName}`,
+        `public-surfaces: ${args.publicSurfaces.join(" ")}`,
+        `mission: ${args.mission}`,
+    ].join("\n");
+}

package/dist/routes/terminal/encoding.js

@@ -0,0 +1,79 @@
+// Whether this terminal can render the characters we write to it.
+//
+// FOUND BY A PARTICIPANT, not by us (labs/tui-self-study.yaml): a computer-use participant sitting
+// at a stock desktop ran `humanish` and read back `humanish ��� run realistic synthetic personas`.
+// The em dash is three bytes of UTF-8, and a terminal whose locale is not UTF-8 renders each byte
+// as a replacement glyph. Every ASCII character on the same screen was fine, which is exactly the
+// signature.
+//
+// The honest fix is not "stop using em dashes" — it is to ask what the terminal can render and mean
+// it. A surface that emits characters its own terminal cannot decode is not being expressive, it is
+// producing garbage that reads as a bug in the tool.
+const UTF8 = /utf-?8/i;
+/**
+ * Does this environment declare a UTF-8 locale? The POSIX variables are checked in the order the C
+ * library resolves them (LC_ALL overrides LC_CTYPE overrides LANG).
+ *
+ * Windows terminals declare none of these and are handled as UTF-8: modern Windows Terminal and
+ * PowerShell render it, and the failure this guards against is a Unix locale that says C/POSIX.
+ */
+export function terminalRendersUnicode(env = process.env) {
+    if (process.platform === "win32")
+        return true;
+    const declared = env.LC_ALL ?? env.LC_CTYPE ?? env.LANG;
+    if (declared === undefined || declared.trim().length === 0) {
+        // Nothing declared at all. A bare login shell on a stock image lands here, and that is the
+        // case the participant hit — assume it cannot, because the failure is silent and ugly while
+        // the fallback is merely plainer.
+        return false;
+    }
+    return UTF8.test(declared);
+}
+/**
+ * The ASCII stand-in for a character, when the terminal cannot render the real one. Anything with
+ * no entry here is already ASCII and passes through.
+ */
+const ASCII_FALLBACKS = new Map([
+    ["—", "--"],
+    ["–", "-"],
+    ["’", "'"],
+    ["‘", "'"],
+    ["“", '"'],
+    ["”", '"'],
+    ["…", "..."],
+    ["·", "-"],
+    ["❯", ">"],
+    ["‹", "<"],
+    ["▸", ">"],
+    ["✓", "+"],
+    ["⚑", "!"],
+    ["⏎", "Enter"],
+    ["↑", "^"],
+    ["↓", "v"],
+    ["←", "<-"],
+    ["→", "->"],
+    ["×", "x"],
+    ["≈", "~"],
+    ["✗", "x"],
+]);
+/**
+ * Rewrite a string so a non-UTF-8 terminal can read it. A no-op when the terminal handles Unicode,
+ * so the good case keeps every glyph it was designed with.
+ *
+ * Characters with no declared fallback are replaced with `?` rather than passed through: passing
+ * them through is what produced `���` in the first place, and one `?` is at least legible as
+ * "something did not survive".
+ */
+export function forTerminal(text, env = process.env) {
+    if (terminalRendersUnicode(env))
+        return text;
+    let out = "";
+    for (const character of text) {
+        if (character.codePointAt(0) < 128) {
+            out += character;
+            continue;
+        }
+        out += ASCII_FALLBACKS.get(character) ?? "?";
+    }
+    return out;
+}

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

@@ -0,0 +1,49 @@
+import type { ActorTokenUsage } from "../../actors/contract.js";
+import type { LabScenarioCaps } from "../../lab/types.js";
+import { type CostCategory } from "../../run/terminal-contract.js";
+import type { CostLine, NoSpendProof, TerminalCostLedger } from "./types.js";
+/**
+ * Build the spend ledger from the captured session. THE NULL DISCIPLINE (issue #154):
+ *   - The `provider` line is populated from the actor trace's tokenUsage.costUsd when the trace
+ *     CARRIES it (a measured value, incl. a measured 0). When the trace carries NO costUsd, the
+ *     provider line is `null` = NOT MEASURED (never guessed to 0 just because no-spend was intended).
+ *   - product/media/payment are `null` by default: core has no signal for those categories; an
+ *     adapter may provide one through the shipped costProbe seam.
+ * `injectedLines` lets a test or adapter supply known spend for a category,
+ * exercising the fail-closed cap enforcement deterministically without a real billable run.
+ */
+export declare function buildCostLedger(args: {
+    tokenCostUsd?: number;
+    /** Measured token counts, when the run produced them but no rate could price them (#531). */
+    tokenUsage?: ActorTokenUsage;
+    injectedLines?: Partial<Record<CostCategory, CostLine>>;
+}): TerminalCostLedger;
+/** True when no cost line carries a dollar value, so a no-spend proof has nothing to stand on. */
+export declare function noSpendLineMeasured(proof: Pick<NoSpendProof, "knownZeroLines" | "knownNonZeroLines">): boolean;
+/**
+ * The verdict for an all-null ledger. `satisfied` stays true there (no known line exceeds the
+ * cap), so the words must say the proof was not established rather than passed.
+ */
+export declare function noSpendNotEstablished(maxUsd: number): string;
+/**
+ * What the ledger measured, in words: the dollar lines it knows, provider tokens it counted but
+ * could not price, and the lines it has no signal for. A reader of a maxUsd=0 run must not take
+ * an all-null ledger for a proven $0.
+ */
+export declare function describeMeasuredSpend(ledger: TerminalCostLedger, tokenUsage?: ActorTokenUsage): string;
+/** Derive the no-spend proof from the ledger. It is HONEST: it vouches for known-zero lines and
+ *  explicitly lists the unmeasured (null) lines it cannot vouch for — never claiming zero on null. */
+export declare function buildNoSpendProof(ledger: TerminalCostLedger, maxUsd: number | null, tokenUsage?: ActorTokenUsage): NoSpendProof;
+/**
+ * Full caps enforcement (fail-closed, not advisory). Returns a structured violation when a KNOWN
+ * (measured) spend line exceeds maxUsd, or a known billable-job count exceeds maxJobs. Unknowns
+ * (`null`) NEVER trip the cap (we cannot claim a violation we did not measure) — but they also never
+ * grant a green pass: the no-spend proof reports them as unmeasured. maxMinutes is wall-clock and is
+ * enforced separately (runWithWallClock); it is not a ledger-derived cap.
+ */
+export declare function evaluateCapsAgainstLedger(ledger: TerminalCostLedger, caps: LabScenarioCaps): {
+    ok: true;
+} | {
+    ok: false;
+    message: string;
+};

package/dist/routes/terminal/ledger.js

@@ -0,0 +1,170 @@
+import { describeTokenUsage } from "./token-usage.js";
+import { round6 } from "../../run/pricing.js";
+import { COST_CATEGORIES } from "../../run/terminal-contract.js";
+/**
+ * Build the spend ledger from the captured session. THE NULL DISCIPLINE (issue #154):
+ *   - The `provider` line is populated from the actor trace's tokenUsage.costUsd when the trace
+ *     CARRIES it (a measured value, incl. a measured 0). When the trace carries NO costUsd, the
+ *     provider line is `null` = NOT MEASURED (never guessed to 0 just because no-spend was intended).
+ *   - product/media/payment are `null` by default: core has no signal for those categories; an
+ *     adapter may provide one through the shipped costProbe seam.
+ * `injectedLines` lets a test or adapter supply known spend for a category,
+ * exercising the fail-closed cap enforcement deterministically without a real billable run.
+ */
+export function buildCostLedger(args) {
+    const providerLine = typeof args.tokenCostUsd === "number"
+        ? {
+            usd: args.tokenCostUsd,
+            source: "provider-token-usage",
+            note: `Provider spend metered from the actor trace tokenUsage.costUsd (${args.tokenCostUsd} USD).`,
+        }
+        : args.tokenUsage
+            ? {
+                // Tokens counted, no rate to price them. This stays `usd: null` because a guessed
+                // dollar figure would be worse than none, but the note carries the measured fact so a
+                // reader never mistakes "no charge recorded" for "nothing was consumed" (#531).
+                usd: null,
+                source: "unpriced-token-usage",
+                note: `Provider spend UNPRICED: the run consumed ${describeTokenUsage(args.tokenUsage)}, ` +
+                    "but the terminal participant records the model as `codex` and src/run/pricing.ts carries no " +
+                    "rate for it, so no dollar figure is claimed. Tokens are a MEASURED fact here; the " +
+                    "price is the unknown. Recorded null (never guessed to 0).",
+            }
+            : {
+                usd: null,
+                source: "unmeasured",
+                note: "Provider spend NOT MEASURED: the actor trace carried no tokenUsage.costUsd this run. Recorded null (not guessed to 0).",
+            };
+    const unmeasured = (category) => ({
+        usd: null,
+        count: null,
+        source: "unmeasured",
+        note: `${category} spend NOT MEASURED: core has no ${category}-spend signal for this run; an adapter may supply one through costProbe. Recorded null (never guessed to 0).`,
+    });
+    const lines = {
+        product: args.injectedLines?.product ?? unmeasured("product"),
+        media: args.injectedLines?.media ?? unmeasured("media"),
+        payment: args.injectedLines?.payment ?? unmeasured("payment"),
+        provider: args.injectedLines?.provider ?? providerLine,
+    };
+    // knownTotalUsd sums ONLY the non-null lines. A null line contributes NOTHING — it is never
+    // coerced to 0 (that would let an unmeasured category masquerade as a measured zero).
+    let knownTotalUsd = 0;
+    let fullyMeasured = true;
+    for (const category of COST_CATEGORIES) {
+        const usd = lines[category].usd;
+        if (usd === null) {
+            fullyMeasured = false;
+        }
+        else {
+            knownTotalUsd += usd;
+        }
+    }
+    return {
+        schema: "humanish.terminal-cost-ledger.v1",
+        currency: "usd",
+        lines,
+        knownTotalUsd: round6(knownTotalUsd),
+        fullyMeasured,
+    };
+}
+/** True when no cost line carries a dollar value, so a no-spend proof has nothing to stand on. */
+export function noSpendLineMeasured(proof) {
+    return proof.knownZeroLines.length + proof.knownNonZeroLines.length === 0;
+}
+/**
+ * The verdict for an all-null ledger. `satisfied` stays true there (no known line exceeds the
+ * cap), so the words must say the proof was not established rather than passed.
+ */
+export function noSpendNotEstablished(maxUsd) {
+    return `No-spend proof not established for maxUsd=${maxUsd}: no spend line was measured.`;
+}
+/**
+ * What the ledger measured, in words: the dollar lines it knows, provider tokens it counted but
+ * could not price, and the lines it has no signal for. A reader of a maxUsd=0 run must not take
+ * an all-null ledger for a proven $0.
+ */
+export function describeMeasuredSpend(ledger, tokenUsage) {
+    const measured = COST_CATEGORIES.filter((c) => ledger.lines[c].usd !== null).map((c) => `${c} ${ledger.lines[c].usd} USD`);
+    const unpricedProvider = ledger.lines.provider.source === "unpriced-token-usage";
+    const unmeasured = COST_CATEGORIES.filter((c) => ledger.lines[c].usd === null && !(c === "provider" && unpricedProvider));
+    return [
+        measured.length > 0 ? `Measured: ${measured.join(", ")}.` : "",
+        unpricedProvider
+            ? `Provider tokens were consumed${tokenUsage === undefined ? "" : ` (${describeTokenUsage(tokenUsage)})`} and are unpriced, not zero.`
+            : "",
+        unmeasured.length > 0 ? `Not measured (null, not claimed zero): ${unmeasured.join(", ")}.` : "",
+    ]
+        .filter((part) => part.length > 0)
+        .join(" ");
+}
+/** Derive the no-spend proof from the ledger. It is HONEST: it vouches for known-zero lines and
+ *  explicitly lists the unmeasured (null) lines it cannot vouch for — never claiming zero on null. */
+export function buildNoSpendProof(ledger, maxUsd, tokenUsage) {
+    const knownZeroLines = [];
+    const knownNonZeroLines = [];
+    const unmeasuredLines = [];
+    for (const category of COST_CATEGORIES) {
+        const usd = ledger.lines[category].usd;
+        if (usd === null)
+            unmeasuredLines.push(category);
+        else if (usd === 0)
+            knownZeroLines.push(category);
+        else
+            knownNonZeroLines.push(category);
+    }
+    // satisfied only when every KNOWN line is within the cap (for a no-spend run, maxUsd 0 => every
+    // known line must be exactly 0). Unmeasured lines do NOT make it satisfied — they are reported
+    // separately as the proof's honest blind spot.
+    const cap = maxUsd ?? 0;
+    const satisfied = knownNonZeroLines.length === 0 && ledger.knownTotalUsd <= cap;
+    const verdict = !satisfied
+        ? `No-spend proof NOT satisfied for maxUsd=${cap}: known spend total ${ledger.knownTotalUsd} USD${knownNonZeroLines.length > 0 ? ` (non-zero: ${knownNonZeroLines.join(", ")})` : ""}.`
+        : noSpendLineMeasured({ knownZeroLines, knownNonZeroLines })
+            ? noSpendNotEstablished(cap)
+            : `No-spend proof SATISFIED for maxUsd=${cap} on the measured lines (known total ${ledger.knownTotalUsd} USD).`;
+    const statement = [verdict, describeMeasuredSpend(ledger, tokenUsage)]
+        .filter((part) => part.length > 0)
+        .join(" ");
+    return {
+        schema: "humanish.terminal-no-spend-proof.v1",
+        maxUsd,
+        satisfied,
+        knownZeroLines,
+        knownNonZeroLines,
+        unmeasuredLines,
+        knownTotalUsd: ledger.knownTotalUsd,
+        statement,
+    };
+}
+/**
+ * Full caps enforcement (fail-closed, not advisory). Returns a structured violation when a KNOWN
+ * (measured) spend line exceeds maxUsd, or a known billable-job count exceeds maxJobs. Unknowns
+ * (`null`) NEVER trip the cap (we cannot claim a violation we did not measure) — but they also never
+ * grant a green pass: the no-spend proof reports them as unmeasured. maxMinutes is wall-clock and is
+ * enforced separately (runWithWallClock); it is not a ledger-derived cap.
+ */
+export function evaluateCapsAgainstLedger(ledger, caps) {
+    if (caps.maxUsd !== undefined && ledger.knownTotalUsd > caps.maxUsd) {
+        const overLines = COST_CATEGORIES.filter((c) => ledger.lines[c].usd !== null && ledger.lines[c].usd > 0);
+        return {
+            ok: false,
+            message: `Observed KNOWN spend ${ledger.knownTotalUsd} USD exceeds scenario.caps.maxUsd=${caps.maxUsd}${overLines.length > 0 ? ` (non-zero lines: ${overLines.join(", ")})` : ""}. The run fails closed: the cap is a fail-closed mechanism, not an advisory.`,
+        };
+    }
+    if (caps.maxJobs !== undefined) {
+        let knownJobs = 0;
+        for (const category of COST_CATEGORIES) {
+            const count = ledger.lines[category].count;
+            if (typeof count === "number")
+                knownJobs += count;
+        }
+        if (knownJobs > caps.maxJobs) {
+            return {
+                ok: false,
+                message: `Observed KNOWN billable-job count ${knownJobs} exceeds scenario.caps.maxJobs=${caps.maxJobs}. The run fails closed.`,
+            };
+        }
+    }
+    return { ok: true };
+}

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

@@ -0,0 +1,10 @@
+/**
+ * The most the sandbox runs before the codex command starts: the Node bootstrap, the runtime
+ * version check and, when the lab declares `subject.product.install`, the product setup.
+ */
+export declare function terminalPreExecBudgetMs(productInstall: boolean): number;
+/** The terminal sandbox's server-side timeout for a codex command bounded at `maxMinutes`. */
+export declare function terminalSandboxTimeoutMs(args: {
+    maxMinutes: number;
+    productInstall: boolean;
+}): number;

package/dist/routes/terminal/lifetime.js

@@ -0,0 +1,22 @@
+// How long a live terminal sandbox may live. Its server-side timeout has to cover everything that
+// runs in it before the codex command, the command's own wall clock (scenario.caps.maxMinutes) and
+// the reclamation buffer after that clock's kill. A timeout shorter than that lets E2B kill the
+// sandbox before the command's deadline and before the evidence is read.
+import { NODE_BOOTSTRAP_TIMEOUT_MS } from "../../subject/node-bootstrap.js";
+import { TERMINAL_RUNTIME_VERSION_TIMEOUT_MS } from "./runtime.js";
+import { PRODUCT_SETUP_TIMEOUT_MS, TERMINAL_SANDBOX_TIMEOUT_BUFFER_MS } from "./types.js";
+/**
+ * The most the sandbox runs before the codex command starts: the Node bootstrap, the runtime
+ * version check and, when the lab declares `subject.product.install`, the product setup.
+ */
+export function terminalPreExecBudgetMs(productInstall) {
+    return (NODE_BOOTSTRAP_TIMEOUT_MS +
+        TERMINAL_RUNTIME_VERSION_TIMEOUT_MS +
+        (productInstall ? PRODUCT_SETUP_TIMEOUT_MS : 0));
+}
+/** The terminal sandbox's server-side timeout for a codex command bounded at `maxMinutes`. */
+export function terminalSandboxTimeoutMs(args) {
+    return (terminalPreExecBudgetMs(args.productInstall) +
+        args.maxMinutes * 60_000 +
+        TERMINAL_SANDBOX_TIMEOUT_BUFFER_MS);
+}

package/dist/routes/terminal/live-finish.d.ts

@@ -0,0 +1,31 @@
+import type { ActorPersonaRef } from "../../actors/contract.js";
+import type { RunBundle } from "../../run/bundle.js";
+import type { RunScope } from "../../run/run.js";
+import type { LiveSandboxInputs, LiveTerminalSandbox } from "./live-sandbox.js";
+import type { RunLiveTerminalSessionArgs, TerminalProductLabHooks, TerminalProductLabResult } from "./types.js";
+type StartedRun = Extract<Awaited<ReturnType<RunScope["startRun"]>>, {
+    ok: true;
+}>["run"];
+/** What the finish reads from the run. */
+export interface LiveFinishInputs {
+    plan: RunLiveTerminalSessionArgs["plan"];
+    input: RunLiveTerminalSessionArgs["input"];
+    cwd: string;
+    hooks: TerminalProductLabHooks;
+    sanitize: (text: string) => string;
+    nowIso: () => string;
+    knownSecretValues: string[];
+    runtimeEnv: LiveSandboxInputs["runtimeEnv"];
+    runtime: LiveSandboxInputs["runtime"];
+    persona: ActorPersonaRef;
+    mission: string;
+    run: StartedRun;
+    source: RunBundle["source"];
+    /** The run's warnings. The finish appends to them. */
+    warnings: string[];
+    recorder: LiveSandboxInputs["recorder"];
+    /** The session's outcome; a blown cap overrides it. */
+    session: LiveTerminalSandbox;
+}
+export declare function finishLiveTerminalSession(inputs: LiveFinishInputs): Promise<TerminalProductLabResult>;
+export {};