humanish 0.105.0 → 0.106.0

package/dist/routes/terminal/adapter.js

@@ -0,0 +1,201 @@
+import path from "node:path";
+import {} from "../../run/bundle.js";
+import { isFeedbackIdempotencyKey } from "../../run/feedback-shape.js";
+import { adapterScoreFailureMessage, declaredScorerThrew, DECLARED_SCORER_MALFORMED, frozenBundleView, } from "../../lab/adapter-extension.js";
+/**
+ * Run the layer-6 product-adapter extension seam (issue #154 acceptance #8) over the assembled
+ * evidence and attach its results to the bundle IN PLACE — without core knowing any product noun.
+ * The review is not touched here: the returned failures are folded into it by the caller.
+ *
+ *  - `score`: when present, the returned namespaced `RunAdapterScore` lands on `bundle.adapterScore`.
+ *    For a LIBRARY caller (no `scorerProvenance`), the adapter score is additive and never a
+ *    failure. For a CONFIG-DECLARED scorer (#316; `scorerProvenance` present), a status:"fail" is a
+ *    failure (the keystone lane is the product's own definition of pass/fail), and so is a scorer
+ *    that THROWS or returns a malformed value, so a crashed declared gate is never a silent green.
+ *  - `deriveFeedback`: when present, the returned candidates are appended to
+ *    `bundle.feedbackCandidates`; each carries its own namespaced `adapter` product-noun block.
+ *
+ * Defense in depth: the adapter's namespaced payloads are re-serialized through the run's scrub +
+ * redact, and any candidate / score that does not satisfy core's exported shape is DROPPED with a
+ * warning (a malformed adapter output never poisons a verifiable bundle). The bundle verifier
+ * re-checks the surviving shapes downstream, so the seam stays fail-closed end to end.
+ */
+export async function applyAdapterExtensionSeam(args) {
+    const { hooks, bundle, trace, ledgers, transcript, product, labId, runId, sanitize, warnings, scorerProvenance, } = args;
+    if (!hooks.score && !hooks.deriveFeedback)
+        return { failures: [] };
+    const declared = scorerProvenance !== undefined;
+    // Record the loaded scorer's identity regardless of hook outcome (a throwing/invalid scorer was
+    // still loaded and attempted).
+    if (scorerProvenance)
+        bundle.scorerProvenance = scorerProvenance;
+    // The scorer sees a READ-ONLY view of the bundle so it cannot mutate noSpend/cost/review in place to
+    // launder a verdict (a tamper attempt throws and is caught as a hook failure below). The seam stamps
+    // the REAL bundle. The transcript is the SAME normalized, source-scrubbed text the run persists as
+    // terminal-transcript.txt — no new exposure beyond what disk already holds (#341).
+    const ctx = {
+        bundle: frozenBundleView(bundle),
+        trace,
+        ledgers,
+        transcript,
+        product,
+        labId,
+        runId,
+    };
+    // Best-effort re-scrub of the adapter payload: round-trip the whole JSON through the run's denylist
+    // sanitizer. This is NOT containment — it catches recognizable secret shapes and known local paths,
+    // but not encoded/split/custom secrets, DB passwords, PII, or abs paths outside the denylist. A
+    // payload from config-declared code is acceptable only because the trust boundary (the party who
+    // declares the scorer runs the lab) already permits direct exfiltration; the re-scrub is
+    // defense-in-depth, not a wall.
+    const scrubValue = (value) => JSON.parse(sanitize(JSON.stringify(value)));
+    // Set for a DECLARED scorer that fails to render a PASS verdict (status:"fail", malformed, or throw).
+    // The caller folds it into the review and fails the run RESULT on it — a declared gate that cannot
+    // pass is a fail, never a silent green. Empty for a library caller and for a passing scorer.
+    const failures = [];
+    if (hooks.score) {
+        try {
+            const score = await hooks.score(ctx);
+            const cleaned = scrubValue(score);
+            if (isAdapterScoreShape(cleaned)) {
+                bundle.adapterScore = cleaned;
+                // A CONFIG-DECLARED terminal scorer owns the product verdict: a status:"fail" fails the
+                // review and the run result. A library caller keeps the additive no-fail behavior.
+                const message = declared ? adapterScoreFailureMessage(bundle) : undefined;
+                if (message !== undefined)
+                    failures.push(message);
+            }
+            else {
+                warnings.push("terminalHooks.score returned a value that is not a well-formed humanish.adapter-score.v1 (non-empty namespace + status + numeric score + summary); dropped so the bundle stays verifiable.");
+                // A declared gate that returned a MALFORMED value never rendered a verdict — fail closed.
+                if (declared)
+                    failures.push(DECLARED_SCORER_MALFORMED);
+            }
+        }
+        catch (error) {
+            const detail = sanitize(error instanceof Error ? error.message : String(error));
+            warnings.push(`terminalHooks.score threw (${detail}); dropped so the bundle stays verifiable.`);
+            // A crashed DECLARED gate must be visible, never a silent pass: it fails the review and the
+            // run result.
+            if (declared)
+                failures.push(declaredScorerThrew(detail));
+        }
+    }
+    if (hooks.deriveFeedback) {
+        try {
+            const candidates = await hooks.deriveFeedback(ctx);
+            const accepted = [];
+            for (const candidate of Array.isArray(candidates) ? candidates : []) {
+                const cleaned = scrubValue(candidate);
+                if (isAdapterFeedbackCandidateShape(cleaned))
+                    accepted.push(cleaned);
+                else
+                    warnings.push("terminalHooks.deriveFeedback returned a candidate that is not a well-formed humanish.feedback-candidate.v1 (or its adapter block lacked a non-empty namespace + data record); dropped so the bundle stays verifiable.");
+            }
+            if (accepted.length > 0) {
+                bundle.feedbackCandidates = [...bundle.feedbackCandidates, ...accepted];
+            }
+        }
+        catch (error) {
+            warnings.push(`terminalHooks.deriveFeedback threw (${sanitize(error instanceof Error ? error.message : String(error))}); dropped so the bundle stays verifiable.`);
+        }
+    }
+    return { failures };
+}
+/** Structural guard for an adapter-returned RunAdapterScore (mirrors run/bundle-shape.ts isRunAdapterScore, kept
+ *  local so the lane fails closed at the seam BEFORE the bundle verifier re-checks it). */
+function isAdapterScoreShape(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        !Array.isArray(value) &&
+        value.schema === "humanish.adapter-score.v1" &&
+        typeof value.namespace === "string" &&
+        value.namespace.trim().length > 0 &&
+        ["pass", "partial", "fail"].includes(value.status) &&
+        typeof value.score === "number" &&
+        Number.isFinite(value.score) &&
+        typeof value.summary === "string");
+}
+/** Structural guard for an adapter-returned feedback candidate. This mirrors run/feedback-shape.ts's full
+ * isRunFeedbackCandidate predicate, including its local evidence-path contract, so a malformed
+ * candidate is dropped at the extension seam instead of poisoning the persisted bundle. */
+function isAdapterFeedbackCandidateShape(value) {
+    return (isAdapterRecord(value) &&
+        value.schema === "humanish.feedback-candidate.v1" &&
+        typeof value.id === "string" &&
+        typeof value.run_id === "string" &&
+        (typeof value.stream_id === "string" || value.stream_id === undefined) &&
+        typeof value.adapter_id === "string" &&
+        typeof value.scenario_id === "string" &&
+        typeof value.persona_id === "string" &&
+        isAdapterFeedbackActor(value.actor) &&
+        isAdapterFeedbackSubstrate(value.substrate) &&
+        isAdapterFeedbackFailureOwner(value.failure_owner) &&
+        typeof value.summary === "string" &&
+        value.summary.trim().length > 0 &&
+        typeof value.expected === "string" &&
+        typeof value.actual === "string" &&
+        Array.isArray(value.evidence) &&
+        value.evidence.every(isAdapterFeedbackEvidence) &&
+        isAdapterRecord(value.redaction) &&
+        value.redaction.status === "passed" &&
+        typeof value.redaction.notes === "string" &&
+        isFeedbackIdempotencyKey(value.idempotency_key) &&
+        isAdapterFeedbackNextState(value.proposed_next_state) &&
+        Array.isArray(value.acceptance_proof) &&
+        value.acceptance_proof.every((item) => typeof item === "string") &&
+        (value.adapter === undefined ||
+            (isAdapterRecord(value.adapter) &&
+                typeof value.adapter.namespace === "string" &&
+                value.adapter.namespace.trim().length > 0 &&
+                isAdapterRecord(value.adapter.data))));
+}
+function isAdapterFeedbackEvidence(value) {
+    return (isAdapterRecord(value) &&
+        typeof value.path === "string" &&
+        value.path.length > 0 &&
+        !path.isAbsolute(value.path) &&
+        !value.path.includes("://") &&
+        !value.path.includes("..") &&
+        (value.kind === "review" ||
+            value.kind === "state" ||
+            value.kind === "log" ||
+            value.kind === "trace" ||
+            value.kind === "screenshot" ||
+            value.kind === "filesystem") &&
+        typeof value.note === "string");
+}
+function isAdapterFeedbackActor(value) {
+    return (value === "codex-tui" ||
+        value === "codex-exec" ||
+        value === "codex-app-server" ||
+        value === "computer-use" ||
+        value === "synthetic-dry-run" ||
+        value === "unknown");
+}
+function isAdapterFeedbackSubstrate(value) {
+    return (value === "e2b-desktop" ||
+        value === "local-desktop" ||
+        value === "e2b-terminal" ||
+        value === "local-filesystem" ||
+        value === "codex-app-server" ||
+        value === "unknown");
+}
+function isAdapterFeedbackFailureOwner(value) {
+    return (value === "harness" ||
+        value === "target-app" ||
+        value === "actor" ||
+        value === "environment" ||
+        value === "unknown");
+}
+function isAdapterFeedbackNextState(value) {
+    return (value === "watch" ||
+        value === "adapter-hardening" ||
+        value === "target-app-setup" ||
+        value === "actor-auth" ||
+        value === "setup-quality-review" ||
+        value === "study-quality-review");
+}
+function isAdapterRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

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

@@ -0,0 +1,79 @@
+import type { ActorPersonaRef, ActorTrace } from "../../actors/contract.js";
+import { type RunLabProvenance } from "../../run/status.js";
+import type { LabScenarioCaps, LabRuntimeAuth } from "../../lab/types.js";
+import { type RunBundle, type RunCostSummary } from "../../run/bundle.js";
+import type { Verdict } from "../../run/judge.js";
+import type { TerminalLedgers } from "./types.js";
+/**
+ * Project the terminal-product lab run into a humanish.run-bundle.v1 (no schema change — a new
+ * producer only). DRY-RUN: a contract bundle. The terminal stream is a contract placeholder
+ * (stdin disabled, no captured tail — honest: nothing ran), the subject is declared UNPINNED, and
+ * the caps/policies/runtime-auth declarations are recorded without pretending that live ledgers
+ * exist. The shipped live builder fills the same evidence contract. Exported for tests.
+ */
+export declare function buildTerminalProductBundle(args: {
+    /** Lab provenance for the bundle\'s own `lab` field (#455). */
+    lab?: RunLabProvenance;
+    actorId: string;
+    createdAt: string;
+    dryRun: boolean;
+    labId: string;
+    labTitle?: string;
+    mission: string;
+    persona: ActorPersonaRef;
+    productName: string;
+    publicSurfaces: string[];
+    caps?: LabScenarioCaps;
+    runtimeAuth?: string;
+    stdin: "disabled" | "planned" | "sent";
+    policies: {
+        allowPrivateRepoAccess: boolean;
+        allowProviderCredentials: boolean;
+        allowPaymentCredentials: boolean;
+        allowGitHubMutation: boolean;
+    };
+    runId: string;
+    source: RunBundle["source"];
+    /** The run's judgment verdict (judgeTerminal): a contract for a dry run. */
+    verdict: Verdict;
+}): RunBundle;
+/**
+ * Build the LIVE terminal-product run bundle (mode "live") from the captured session: the actor
+ * trace seam (stream.actor = trace), the substrate-lifecycle events, the terminal stream with the
+ * redacted transcript tail, and references to the written evidence artifacts (terminal event
+ * stream, transcript, ledgers, actor trace). verifyRun's terminal-product check (gated on
+ * mode==="live") enforces the ledgers + proven cleanup + interventions-present over this bundle.
+ */
+export declare function buildLiveTerminalProductBundle(args: {
+    /** Lab provenance for the bundle\'s own `lab` field (#455). */
+    lab?: RunLabProvenance;
+    actorId: string;
+    createdAt: string;
+    labId: string;
+    labTitle?: string;
+    mission: string;
+    persona: ActorPersonaRef;
+    productName: string;
+    publicSurfaces: string[];
+    caps?: LabScenarioCaps;
+    runtimeAuthKeyName: string;
+    runtimeAuth?: LabRuntimeAuth;
+    policies: {
+        allowPrivateRepoAccess: boolean;
+        allowProviderCredentials: boolean;
+        allowPaymentCredentials: boolean;
+        allowGitHubMutation: boolean;
+    };
+    runId: string;
+    source: RunBundle["source"];
+    trace: ActorTrace;
+    ledgers: TerminalLedgers;
+    cost?: RunCostSummary;
+    sessionReason: string;
+    /** The run's judgment verdict (judgeTerminal). */
+    verdict: Verdict;
+    /** The cap check's message when known spend or jobs exceeded the caps: an execution failure
+     *  the review names, beside the agent's own verdict. */
+    capFailure?: string;
+}): RunBundle;
+export declare function renderTerminalReviewMarkdown(bundle: RunBundle): string;

package/dist/routes/terminal/bundle.js

@@ -0,0 +1,305 @@
+import {} from "../../run/status.js";
+import { redactText } from "../../evidence/redaction.js";
+import { participantAssignment } from "../../lab/participant-assignment.js";
+import { REVIEW_SCHEMA, bundleArtifacts, bundleHead, } from "../../run/bundle.js";
+import {} from "../../run/streams.js";
+import { participantEvent, participantIds, participantRecord, participantStream, } from "../../run/participant-records.js";
+import { TERMINAL_EVENTS_ARTIFACT, TERMINAL_LEDGERS_ARTIFACT, TERMINAL_TRANSCRIPT_ARTIFACT, } from "../../run/terminal-contract.js";
+import { describeMeasuredSpend, noSpendLineMeasured, noSpendNotEstablished } from "./ledger.js";
+/**
+ * Project the terminal-product lab run into a humanish.run-bundle.v1 (no schema change — a new
+ * producer only). DRY-RUN: a contract bundle. The terminal stream is a contract placeholder
+ * (stdin disabled, no captured tail — honest: nothing ran), the subject is declared UNPINNED, and
+ * the caps/policies/runtime-auth declarations are recorded without pretending that live ledgers
+ * exist. The shipped live builder fills the same evidence contract. Exported for tests.
+ */
+export function buildTerminalProductBundle(args) {
+    const reason = "Contract bundle only: dry-run declared the terminal-product study contract without creating an E2B sandbox, injecting any key, or spending. This run did not execute an agent or prove live behavior.";
+    // The terminal stream is a CONTRACT PLACEHOLDER on the dry-run path: stdin is disabled and no
+    // exec output was captured, so the tail is empty and transport stays "snapshot" — NOT "pty"
+    // (captured non-interactive exec output is never an interactive PTY; invariant 6 + the PTY
+    // ruling). The shipped live builder fills terminal.tail from redacted exec-stream capture.
+    const { simulation, stream } = terminalParticipant(args, {
+        status: "contract_proof_only",
+        reason,
+        summary: `Contract participant for the terminal agent (${args.actorId}) studying ${args.productName} from public surfaces.`,
+        updatedAt: args.createdAt,
+        stdin: args.stdin,
+        tail: "",
+        artifacts: [
+            { label: "run bundle", path: "run.json", kind: "bundle" },
+            { label: "review", path: "review.md", kind: "review" },
+            { label: "events", path: "events.ndjson", kind: "events" },
+        ],
+    });
+    const capsText = describeCaps(args.caps);
+    const events = [
+        {
+            id: "event-000-created",
+            at: args.createdAt,
+            level: "info",
+            type: "terminal-lab.run.created",
+            message: `Created terminal-product lab run for ${args.labId} (actor ${args.actorId}, product ${args.productName}).`,
+        },
+        participantEvent(TERMINAL_IDS, {
+            id: "event-001-subject",
+            at: args.createdAt,
+            level: "info",
+            type: "terminal-lab.subject.declared",
+            // Invariant 5: provenance recorded or its absence DECLARED. The agent drives PUBLIC surfaces,
+            // not a clone, so the subject provenance is explicitly UNPINNED; evidence binds to the
+            // composed-prompt digest. Public surfaces are recorded (they are public by declaration).
+            message: `Subject product declared: ${args.productName}; public surfaces: ${args.publicSurfaces.join(", ")}. The lab did not provision/clone the product — subject provenance is UNPINNED (a public-surface study cannot be commit-pinned); evidence binds to the composed-prompt digest ${args.persona.promptDigest}.`,
+        }),
+        participantEvent(TERMINAL_IDS, {
+            id: "event-002-credentials",
+            at: args.createdAt,
+            level: "info",
+            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; 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}.`,
+        }),
+        participantEvent(TERMINAL_IDS, {
+            id: "event-003-caps",
+            at: args.createdAt,
+            level: "info",
+            type: "terminal-lab.caps.declared",
+            message: `Spend/job/time caps: ${capsText}. A live run never exercises the runtime key without a fail-closed cap; its no-spend proof is derived from the persisted cost ledger. This dry-run spends $0 by mechanism.`,
+        }),
+        participantEvent(TERMINAL_IDS, {
+            id: "event-004-contract",
+            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 declared runtime-auth placement.",
+        }),
+    ];
+    const review = {
+        schema: REVIEW_SCHEMA,
+        verdict: args.verdict,
+        summary: reason,
+        gaps: [
+            "This dry-run did not execute the live in-sandbox agent route; it proves contract shape only, not live behavior, scale, or adoption.",
+            "No exec-stream, transcript, substrate, cost, or cleanup artifacts were produced because no live session ran; live verification requires those artifacts.",
+        ],
+    };
+    return terminalRunBundle(args, {
+        mode: args.dryRun ? "dry-run" : "live",
+        lifecycle: [
+            {
+                at: args.createdAt,
+                event: "terminal-lab.run.created",
+                message: `Created terminal-product lab run with one in-sandbox agent participant (actor ${args.actorId}, product ${args.productName}).`,
+            },
+        ],
+        simulation,
+        stream,
+        events,
+        redactionNotes: "Dry-run contract bundle: no sandbox ran, no key was injected, no exec output was captured. The author mission is public-safe committed lab text (redacted defensively); the composed prompt is bound by digest. The shipped live path applies scrubKnownValues then redactText at the capture source before persistence.",
+        review,
+    });
+}
+/**
+ * Build the LIVE terminal-product run bundle (mode "live") from the captured session: the actor
+ * trace seam (stream.actor = trace), the substrate-lifecycle events, the terminal stream with the
+ * redacted transcript tail, and references to the written evidence artifacts (terminal event
+ * stream, transcript, ledgers, actor trace). verifyRun's terminal-product check (gated on
+ * mode==="live") enforces the ledgers + proven cleanup + interventions-present over this bundle.
+ */
+export function buildLiveTerminalProductBundle(args) {
+    const recordStatus = args.trace.status === "passed"
+        ? "passed"
+        : args.trace.status === "blocked"
+            ? "blocked"
+            : args.trace.status === "timed_out"
+                ? "timed_out"
+                : "failed";
+    const messageItem = args.trace.items.find((item) => item.kind === "message");
+    const tail = (messageItem?.text ?? args.trace.reason).slice(0, 2000);
+    // transport "snapshot": the persisted tail is a redacted snapshot of the captured exec output,
+    // NOT an interactive PTY (stdin disabled). The actor trace seam carries the structured evidence.
+    const { simulation, stream } = terminalParticipant(args, {
+        status: recordStatus,
+        reason: args.sessionReason,
+        summary: `Terminal agent (${args.actorId}) studied ${args.productName} from public surfaces (${args.trace.status}).`,
+        updatedAt: args.trace.completedAt,
+        stdin: "disabled",
+        tail,
+        actor: args.trace,
+        artifacts: [
+            { label: "run bundle", path: "run.json", kind: "bundle" },
+            { label: "review", path: "review.md", kind: "review" },
+            { label: "event log", path: "events.ndjson", kind: "events" },
+            { label: "actor trace", path: "actor.json", kind: "trace" },
+            { label: "terminal event stream", path: TERMINAL_EVENTS_ARTIFACT, kind: "log" },
+            { label: "terminal transcript", path: TERMINAL_TRANSCRIPT_ARTIFACT, kind: "log" },
+            { label: "terminal ledgers", path: TERMINAL_LEDGERS_ARTIFACT, kind: "log" },
+        ],
+    });
+    // Substrate-lifecycle ledger -> bundle events (each already sanitized when recorded).
+    const lifecycleEvents = args.ledgers.lifecycle.map((record, index) => participantEvent(TERMINAL_IDS, {
+        id: `event-${String(index).padStart(3, "0")}-${record.event}`,
+        at: record.at,
+        level: record.event.includes("error") ||
+            record.event.includes("timed_out") ||
+            record.event.includes("exceeded")
+            ? "warn"
+            : "info",
+        type: record.event,
+        message: record.message,
+    }));
+    // Surface the no-spend proof as a first-class bundle event so the Observer/review can SHOW it.
+    // It is DERIVED from the cost ledger (never asserted): it lists the known-zero lines it vouches
+    // for AND the unmeasured (null) lines it explicitly cannot vouch for.
+    const noSpend = args.ledgers.noSpendProof;
+    lifecycleEvents.push(participantEvent(TERMINAL_IDS, {
+        id: "event-cost-no-spend-proof",
+        at: args.trace.completedAt,
+        level: noSpend.satisfied ? "info" : "warn",
+        type: "terminal-lab.no-spend.proof",
+        message: noSpend.statement,
+    }));
+    const review = {
+        schema: REVIEW_SCHEMA,
+        verdict: args.verdict,
+        summary: args.sessionReason,
+        gaps: [
+            ...(args.trace.status === "passed"
+                ? []
+                : [`Agent session ended ${args.trace.status}: ${args.sessionReason}`]),
+            ...(args.capFailure === undefined ? [] : [args.capFailure]),
+            // Honesty gap: the no-spend proof always declares which spend lines it could NOT measure, so a
+            // green run never silently over-claims a fully-proven $0.
+            ...(noSpend.unmeasuredLines.length > 0
+                ? [
+                    `${noSpendLineMeasured(noSpend) ? noSpendNotEstablished(noSpend.maxUsd ?? 0) : "No-spend proof is partial."} ${describeMeasuredSpend(args.ledgers.cost, args.trace.tokenUsage)} An adapter may supply the missing signals through costProbe.`,
+                ]
+                : []),
+        ],
+    };
+    return terminalRunBundle(args, {
+        mode: "live",
+        lifecycle: args.ledgers.lifecycle.map((record) => ({
+            at: record.at,
+            event: record.event,
+            message: record.message,
+        })),
+        simulation,
+        stream,
+        events: lifecycleEvents,
+        redactionNotes: `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).`,
+        review,
+        ...(args.cost === undefined ? {} : { cost: args.cost }),
+    });
+}
+/** The one terminal participant's saved ids. */
+const TERMINAL_IDS = participantIds(0);
+/** The one terminal participant: its record and its stream. */
+function terminalParticipant(args, session) {
+    const simulation = participantRecord(TERMINAL_IDS, 1, {
+        personaId: args.persona.id,
+        scenarioId: `terminal-${args.labId}`,
+        status: session.status,
+        streamKind: "terminal",
+        mode: "cli-sim",
+        progress: 100,
+        currentStep: session.reason,
+        summary: session.summary,
+        startedAt: args.createdAt,
+        updatedAt: session.updatedAt,
+    });
+    const stream = participantStream(TERMINAL_IDS, {
+        assignment: participantAssignment({ mission: args.mission }),
+        kind: "terminal",
+        label: `Terminal agent — ${args.labId}`,
+        status: session.status,
+        transport: "snapshot",
+        updatedAt: session.updatedAt,
+        embed: { kind: "placeholder", title: `Terminal agent (${args.productName})` },
+        terminal: {
+            title: `${args.actorId} exec (stdin ${session.stdin})`,
+            format: "plain",
+            stdin: session.stdin,
+            tail: session.tail,
+        },
+        ui: {
+            intent: `Watch the terminal agent discover and use ${args.productName} from its public surfaces.`,
+            state: session.reason,
+        },
+        ...(session.actor === undefined ? {} : { actor: session.actor }),
+        artifacts: session.artifacts,
+    });
+    return { simulation, stream };
+}
+/** The run bundle around the lane: the fields both builders fill the same way. */
+function terminalRunBundle(args, parts) {
+    return {
+        ...bundleHead({
+            runId: args.runId,
+            mode: parts.mode,
+            participants: 1,
+            createdAt: args.createdAt,
+            ...(args.lab === undefined ? {} : { lab: args.lab }),
+            source: args.source,
+        }),
+        persona: {
+            id: args.persona.id,
+            name: `Autonomous terminal agent (${args.persona.id})`,
+            source: `lab:${args.labId}`,
+            sourceDigest: args.persona.promptDigest,
+        },
+        scenario: {
+            id: `terminal-${args.labId}`,
+            title: args.labTitle ?? `Terminal-product lab: ${args.labId}`,
+            // The author mission is public-safe committed lab text — recorded plaintext as the goal,
+            // redacted defensively before persisting (it never carries a secret, but the harness never
+            // trusts that). The full composed prompt is bound by digest, not text.
+            goal: redactText(args.mission),
+            source: `lab:${args.labId}`,
+            sourceDigest: args.persona.promptDigest,
+        },
+        lifecycle: parts.lifecycle,
+        simulations: [parts.simulation],
+        streams: [parts.stream],
+        events: parts.events,
+        redaction: { status: "passed", notes: parts.redactionNotes },
+        artifacts: bundleArtifacts(),
+        review: parts.review,
+        feedbackCandidates: [],
+        ...(parts.cost === undefined ? {} : { cost: parts.cost }),
+    };
+}
+function describeCaps(caps) {
+    if (!caps)
+        return "none declared (a live run requires caps)";
+    const parts = [];
+    if (caps.maxUsd !== undefined)
+        parts.push(`maxUsd=${caps.maxUsd}`);
+    if (caps.maxJobs !== undefined)
+        parts.push(`maxJobs=${caps.maxJobs}`);
+    if (caps.maxMinutes !== undefined)
+        parts.push(`maxMinutes=${caps.maxMinutes}`);
+    return parts.length > 0 ? parts.join(", ") : "empty";
+}
+export function renderTerminalReviewMarkdown(bundle) {
+    const subject = bundle.events.find((event) => event.type === "terminal-lab.subject.declared");
+    const credentials = bundle.events.find((event) => event.type === "terminal-lab.credentials.declared");
+    const caps = bundle.events.find((event) => event.type === "terminal-lab.caps.declared");
+    return [
+        `# ${bundle.scenario.title}`,
+        "",
+        `- run: ${bundle.runId}`,
+        `- mode: ${bundle.mode}`,
+        `- verdict: ${bundle.review.verdict}`,
+        `- summary: ${bundle.review.summary}`,
+        `- mission: ${bundle.scenario.goal}`,
+        ...(subject ? [`- subject: ${subject.message}`] : []),
+        ...(credentials ? [`- credentials: ${credentials.message}`] : []),
+        ...(caps ? [`- caps: ${caps.message}`] : []),
+        ...(bundle.review.gaps.length > 0
+            ? ["", "## Gaps", ...bundle.review.gaps.map((gap) => `- ${gap}`)]
+            : []),
+        "",
+    ].join("\n");
+}

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

@@ -0,0 +1,34 @@
+import type { LabRuntimeAuth } from "../../lab/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 declare function buildRuntimeAuth(args: {
+    /** Undefined retains the historical openai-env default. */
+    runtimeAuth: LabRuntimeAuth | undefined;
+    /** The operator environment the key value is read from (process.env or a test fake). */
+    env: Record<string, string | undefined>;
+}): {
+    ok: true;
+    mode: LabRuntimeAuth;
+    envs: Record<string, string>;
+    keyName: string;
+    keyValue: string;
+} | {
+    ok: false;
+    code: "HUMANISH_TERMINAL_LAB_RUNTIME_AUTH_MISSING" | "HUMANISH_TERMINAL_LAB_CREDENTIAL_DENIED";
+    message: string;
+};
+/**
+ * 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 declare function buildSandboxMetadata(allowlist: {
+    labId: string;
+    simId: string;
+    runId: string;
+}): Record<string, string>;