humanish 0.106.1 → 0.107.0

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

@@ -17,11 +17,10 @@ import { TERMINAL_PRODUCT_LAB_SCHEMA, } from "./types.js";
 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,
+        env: input.env ?? process.env,
         warnings,
     });
     const started = await scope.startRun({
@@ -31,7 +30,7 @@ export async function runDryTerminalLab(args) {
         mode: "dry-run",
         lab: plan.lab,
         renderReview: renderTerminalReviewMarkdown,
-        observer: { open: input.open === true, render: hooks.renderObserverFn },
+        observer: { open: input.open === true, render: input.deps?.renderObserver },
     });
     if (!started.ok)
         return failed(started.code, started.message);
@@ -46,9 +45,8 @@ export async function runDryTerminalLab(args) {
     const policies = plan.residual.policies;
     const judgment = judgeTerminal({ dryRun: true, participant: undefined });
     const bundle = buildTerminalProductBundle({
-        ...(plan.lab === undefined ? {} : { lab: plan.lab }),
+        run,
         actorId: plan.actor,
-        createdAt,
         dryRun: true,
         labId: plan.labId,
         ...(plan.title ? { labTitle: plan.title } : {}),
@@ -65,7 +63,6 @@ export async function runDryTerminalLab(args) {
             allowPaymentCredentials: policies?.allowPaymentCredentials ?? false,
             allowGitHubMutation: policies?.allowGitHubMutation ?? false,
         },
-        runId,
         source,
         verdict: judgment.verdict,
     });
@@ -118,9 +115,9 @@ async function prepareDryPersona(args) {
         .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
+    // 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).
+    // is recorded as a digest (the safety contract's mission ruling).
     const composedPrompt = composePrompt({
         mission,
         personaLine: terminalPersona.personaLine,
@@ -133,7 +130,7 @@ async function prepareDryPersona(args) {
 }
 /** The declared runtime provenance as a dry-run event; nothing is observed without a sandbox. */
 function runtimeDeclaredEvent(runtime, createdAt) {
-    const { version, model, reasoningEffort } = runtime;
+    const { version, model, modelSource, reasoningEffort } = runtime;
     return {
         id: "event-terminal-runtime-declared",
         at: createdAt,
@@ -141,12 +138,13 @@ function runtimeDeclaredEvent(runtime, createdAt) {
         type: "terminal-lab.runtime.declared",
         message: redactText(JSON.stringify(declaredRuntimeProvenance({
             ...(version === undefined ? {} : { version }),
-            ...(model === undefined ? {} : { model }),
+            model,
+            modelSource,
             ...(reasoningEffort === undefined ? {} : { reasoningEffort }),
         }))),
     };
 }
-/** Compose the full prompt the agent would run. Bound to evidence by DIGEST only. */
+/** Compose the full prompt the agent would run. Bound to evidence by digest only. */
 export function composePrompt(args) {
     return [
         args.personaLine,

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

@@ -1,6 +1,6 @@
 /**
  * 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).
+ * 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.

package/dist/routes/terminal/encoding.js

@@ -1,6 +1,6 @@
 // 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
+// A participant found this (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
@@ -12,7 +12,7 @@
 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).
+ * 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.

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

@@ -3,10 +3,10 @@ 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):
+ * 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).
+ *     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,
@@ -31,13 +31,13 @@ export declare function noSpendNotEstablished(maxUsd: number): string;
  * 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
+/** Derive the no-spend proof from the ledger. 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
+ * Fail-closed caps enforcement. 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
+ * (`null`) never trip the cap (we cannot claim a violation we did not measure), and 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.
  */

package/dist/routes/terminal/ledger.js

@@ -2,10 +2,10 @@ 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):
+ * 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).
+ *     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,
@@ -47,7 +47,7 @@ export function buildCostLedger(args) {
         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
+    // knownTotalUsd sums only the non-null lines. A null line contributes nothing and is never
     // coerced to 0 (that would let an unmeasured category masquerade as a measured zero).
     let knownTotalUsd = 0;
     let fullyMeasured = true;
@@ -98,7 +98,7 @@ export function describeMeasuredSpend(ledger, tokenUsage) {
         .filter((part) => part.length > 0)
         .join(" ");
 }
-/** Derive the no-spend proof from the ledger. It is HONEST: it vouches for known-zero lines and
+/** Derive the no-spend proof from the ledger. 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 = [];
@@ -113,8 +113,8 @@ export function buildNoSpendProof(ledger, maxUsd, tokenUsage) {
         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
+    // 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 never 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;
@@ -138,9 +138,9 @@ export function buildNoSpendProof(ledger, maxUsd, tokenUsage) {
     };
 }
 /**
- * Full caps enforcement (fail-closed, not advisory). Returns a structured violation when a KNOWN
+ * Fail-closed caps enforcement. 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
+ * (`null`) never trip the cap (we cannot claim a violation we did not measure), and 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.
  */

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

@@ -2,7 +2,7 @@ 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";
+import type { RunLiveTerminalSessionArgs, TerminalProductLabResult } from "./types.js";
 type StartedRun = Extract<Awaited<ReturnType<RunScope["startRun"]>>, {
     ok: true;
 }>["run"];
@@ -11,7 +11,6 @@ export interface LiveFinishInputs {
     plan: RunLiveTerminalSessionArgs["plan"];
     input: RunLiveTerminalSessionArgs["input"];
     cwd: string;
-    hooks: TerminalProductLabHooks;
     sanitize: (text: string) => string;
     nowIso: () => string;
     knownSecretValues: string[];

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

@@ -3,7 +3,7 @@
 import { buildRunCostSummary } from "../../run/cost-summary.js";
 import { writeContainedOutputFile } from "../../run/contained-output.js";
 import { validatePreparedRunArtifactPaths, } from "../../run/paths.js";
-import { estimateActorCost } from "../../run/pricing.js";
+import { estimateAggregatedTurnCost } from "../../run/pricing.js";
 import { normalizeLocalActorTranscript, TERMINAL_EVENTS_ARTIFACT, TERMINAL_LEDGERS_ARTIFACT, TERMINAL_TRANSCRIPT_ARTIFACT, } from "../../run/terminal-contract.js";
 import { applyAdapterExtensionSeam } from "./adapter.js";
 import { buildLiveTerminalProductBundle } from "./bundle.js";
@@ -22,9 +22,9 @@ function buildLiveTrace(inputs) {
     // 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).
+    // 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
+    // Parsed from the full stream: usage records arrive once per turn, and the tail
     // would drop all but the last (#531).
     const terminalTokenUsage = parseTerminalTokenUsage(normalizedTranscript);
     const trace = buildTerminalActorTrace({
@@ -39,27 +39,30 @@ function buildLiveTrace(inputs) {
         terminalEvents,
         commandLog,
         transcriptTail: tailOf(normalizedTranscript),
+        participant: inputs.recorder.participantText.finish(),
         runtimeAuth: runtimeEnv.mode,
         runtime,
         ...(terminalTokenUsage === undefined ? {} : { tokenUsage: terminalTokenUsage }),
     });
-    // Codex tokens stay unpriced: the lane records its model as `codex`, which has no rate.
-    trace.estimatedCost = estimateActorCost(trace.tokenUsage, trace.provider);
+    // Priced from the model the route passed to Codex. turn.completed sums a turn's requests, so the
+    // estimate uses base rates and says so.
+    trace.estimatedCost = estimateAggregatedTurnCost(trace.tokenUsage, runtime.requestedModel);
     return { normalizedTranscript, trace };
 }
 async function settleLiveLedgers(inputs, trace, normalizedTranscript) {
-    const { hooks, runtime, session } = inputs;
+    const { runtime, session } = inputs;
+    const costProbe = inputs.input.deps?.costProbe;
     const { caps } = inputs.plan;
     const { maxUsd } = caps;
     const runPaths = inputs.run.paths;
     const { recordLifecycle, lifecycle, commandLog, interventions, terminalEvents } = inputs.recorder;
     // --- Spend ledger + no-spend proof + full caps enforcement (fail-closed). ---
-    // The cost ledger is DERIVED, with the null discipline: provider spend from the trace's
-    // tokenUsage.costUsd when present (else null = NOT MEASURED), product/media/payment null by
-    // default (core has no signal). The costProbe hook lets tests or adapters inject KNOWN
+    // The cost ledger is derived, with the null discipline: provider spend from the trace's
+    // tokenUsage.costUsd when present (else null = not measured), product/media/payment null by
+    // default (core has no signal). The costProbe hook lets tests or adapters inject known
     // spend to exercise the fail-closed cap without a real billable run.
-    const injectedLines = hooks.costProbe?.(trace.tokenUsage?.costUsd === undefined ? {} : { tokenCostUsd: trace.tokenUsage.costUsd });
-    if (hooks.costProbe)
+    const injectedLines = costProbe?.(trace.tokenUsage?.costUsd === undefined ? {} : { tokenCostUsd: trace.tokenUsage.costUsd });
+    if (costProbe)
         await validatePreparedRunArtifactPaths(runPaths);
     const cost = buildCostLedger({
         ...(trace.tokenUsage?.costUsd === undefined ? {} : { tokenCostUsd: trace.tokenUsage.costUsd }),
@@ -74,9 +77,9 @@ async function settleLiveLedgers(inputs, trace, normalizedTranscript) {
             : `No-spend proof satisfied on the measured lines for maxUsd=${maxUsd ?? "null"}.`;
     const measuredSpend = describeMeasuredSpend(cost, trace.tokenUsage);
     recordLifecycle("terminal-lab.cost.measured", `Cost ledger: known total ${cost.knownTotalUsd} USD${cost.fullyMeasured ? " (fully measured)" : " (lower bound)"}.${measuredSpend.length > 0 ? ` ${measuredSpend}` : ""} ${proofVerdict}`);
-    // FULL caps enforcement (fail-closed, NOT advisory): if a KNOWN spend line exceeds maxUsd (or a
+    // Fail-closed caps enforcement: if a known spend line exceeds maxUsd (or a
     // known job count exceeds maxJobs), the run fails closed — never a green result. Unknowns (null)
-    // do NOT trip the cap (we cannot claim a violation we did not measure) but never grant a pass
+    // never trip the cap (we cannot claim a violation we did not measure) but never grant a pass
     // either (the no-spend proof reports them as unmeasured). maxMinutes is already wall-clock-
     // enforced above. A blown cap is an execution failure: the agent's own status stays the
     // verdict, and the result's ok is false.
@@ -91,7 +94,7 @@ async function settleLiveLedgers(inputs, trace, normalizedTranscript) {
         runtime,
         lifecycle,
         commandLog,
-        interventions, // ALWAYS present, ALWAYS empty while no assisted-input path ships.
+        interventions, // Always present, and always empty while no assisted-input path ships.
         cleanup: session.cleanup,
         cost,
         noSpendProof,
@@ -102,11 +105,11 @@ async function settleLiveLedgers(inputs, trace, normalizedTranscript) {
 export async function finishLiveTerminalSession(inputs) {
     const { normalizedTranscript, trace } = buildLiveTrace(inputs);
     const { cost, noSpendProof, capFailure, ledgers } = await settleLiveLedgers(inputs, trace, normalizedTranscript);
-    const { plan, input, cwd, hooks, sanitize } = inputs;
+    const { plan, input, cwd, sanitize } = inputs;
     const { product, caps } = plan;
     const policies = plan.residual.policies;
     const { runtimeEnv, persona, mission, run, source, warnings, session } = inputs;
-    const { runId, createdAt, paths: runPaths } = run;
+    const { runId, paths: runPaths } = run;
     // One judgment, after a blown cap has overridden the session: the bundle's verdict (and so
     // status.json's outcome) and the result's ok both read it.
     const participant = terminalParticipantFacts(trace, session.error);
@@ -120,9 +123,8 @@ export async function finishLiveTerminalSession(inputs) {
         ...(desktops === undefined ? {} : { desktops }),
     });
     const bundle = buildLiveTerminalProductBundle({
-        ...(plan.lab === undefined ? {} : { lab: plan.lab }),
+        run,
         actorId: plan.actor,
-        createdAt,
         labId: plan.labId,
         ...(plan.title ? { labTitle: plan.title } : {}),
         mission: sanitize(mission),
@@ -138,7 +140,6 @@ export async function finishLiveTerminalSession(inputs) {
             allowPaymentCredentials: policies?.allowPaymentCredentials ?? false,
             allowGitHubMutation: policies?.allowGitHubMutation ?? false,
         },
-        runId,
         source,
         trace,
         ledgers,
@@ -154,7 +155,7 @@ export async function finishLiveTerminalSession(inputs) {
     // through foldScorerFailures below. Adapter payloads pass the same scrub and redaction as the
     // rest of the bundle, and the bundle verifier checks them downstream.
     const scorer = await applyAdapterExtensionSeam({
-        hooks,
+        scorer: input.scorer,
         bundle,
         trace,
         ledgers,

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

@@ -4,7 +4,8 @@ import type { RunScope } from "../../run/run.js";
 import type { buildRuntimeAuth, buildSandboxMetadata } from "./credentials.js";
 import type { createTerminalRecorder } from "./recorder.js";
 import { type declaredRuntimeProvenance } from "./runtime.js";
-import { type LiveTerminalPlan, type TerminalLedgers, type TerminalProductLabHooks } from "./types.js";
+import { type LiveTerminalPlan, type TerminalLedgers } from "./types.js";
+import type { LabDeps } from "../../lab/lab-deps.js";
 type StartedRun = Extract<Awaited<ReturnType<RunScope["startRun"]>>, {
     ok: true;
 }>["run"];
@@ -12,7 +13,7 @@ type StartedRun = Extract<Awaited<ReturnType<RunScope["startRun"]>>, {
 export interface LiveSandboxInputs {
     plan: LiveTerminalPlan;
     cwd: string;
-    hooks: TerminalProductLabHooks;
+    deps: LabDeps;
     now: () => number;
     nowIso: () => string;
     sanitize: (text: string) => string;

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

@@ -52,13 +52,13 @@ export class LiveTerminalSandbox {
         });
     }
     async acquire() {
-        const { plan, hooks, now, sanitize, runtimeEnv, e2bApiKey, runPaths, metadata } = this.inputs;
+        const { plan, deps, now, sanitize, runtimeEnv, e2bApiKey, runPaths, metadata } = this.inputs;
         const { warnings } = this.inputs;
         const { recordLifecycle } = this.inputs.recorder;
         const { requestTimeoutMs, sandboxTimeoutMs } = this;
         // Declared egress allowlist, or undefined for the historical unrestricted default (#538).
         const egressAllow = plan.egressAllow;
-        const sandboxModule = await (hooks.loadModule ?? loadE2BDesktopModule)();
+        const sandboxModule = await (deps.desktopModule ?? loadE2BDesktopModule)();
         this.module = sandboxModule;
         await validatePreparedRunArtifactPaths(runPaths);
         // No sandbox-global env in either mode. In openai-egress, only this host-side SDK request
@@ -130,7 +130,7 @@ export class LiveTerminalSandbox {
         const { recordLifecycle } = this.inputs.recorder;
         const { requestTimeoutMs } = this;
         // --- Runtime bootstrap: no runtime env; openai-egress proxy capability is already available. ---
-        // The stock desktop needs Node/npm on PATH before npx can run Codex. Reuse a working
+        // 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();
@@ -152,7 +152,7 @@ export class LiveTerminalSandbox {
             ? `Runtime bootstrap FAILED after ${bootstrapDurationMs}ms: ${bootstrapError}. codex exec runs via npx and needs Node/npm present; the participant fails closed rather than attempting an exec with no runtime.`
             : `Runtime bootstrap ensured Node/npm present in ${bootstrapDurationMs}ms (codex exec runs via npx).`);
         if (bootstrapError) {
-            // Fail closed as a structured lane status (never a raw throw): no codex exec is attempted
+            // Fail closed as a structured route status (never a raw throw): no codex exec is attempted
             // without a proven runtime; this mirrors the exec-error status assignment below so the
             // bundle and verify surface the failure the same way.
             this.status = "failed";
@@ -185,7 +185,7 @@ export class LiveTerminalSandbox {
                 throw new Error(`Codex version mismatch: requested ${requested}, observed ${observed}.`);
             }
             runtime.versionStatus = "verified";
-            recordLifecycle("terminal-lab.runtime.version", `Codex requested ${runtime.requestedVersion}, observed ${observed}; exact version selected for execution. Model ${runtime.requestedModel ?? "runtime default (unobserved)"}; reasoning effort ${runtime.requestedReasoningEffort ?? "runtime default (unobserved)"}.`);
+            recordLifecycle("terminal-lab.runtime.version", `Codex requested ${runtime.requestedVersion}, observed ${observed}; exact version selected for execution. Model ${runtime.requestedModel ?? "unrecorded"} (${runtime.modelStatus}); reasoning effort ${runtime.requestedReasoningEffort ?? "runtime default (unobserved)"}.`);
         }
         catch (error) {
             runtime.versionStatus = "failed";
@@ -205,15 +205,15 @@ export class LiveTerminalSandbox {
         const { requestTimeoutMs } = this;
         // --- Optional product setup (no runtime env), before the Codex exec. ---
         // Same channel and same guarantees as the runtime bootstrap above: no runtime key touches it,
-        // and a failure fails the lane closed rather than handing the agent a half-built world. It
-        // exists so a study can put the participant IN a prepared project — asking an agent what
+        // and a failure fails the run closed rather than handing the agent a half-built world. It
+        // exists so a study can put the participant in a prepared project: asking an agent what
         // studies a project contains, in an empty directory, measures the lab and not the product
-        // (learned the hard way on the desktop lane, labs/tui-self-study.yaml).
+        // (learned the hard way on the desktop route, labs/tui-self-study.yaml).
         const install = plan.product.install;
         if (install === undefined)
             return true;
         // An optional local file, put on the machine before the install runs, so a study can meet a
-        // build that is not published yet. Read and checked HERE rather than trusted from the
+        // build that is not published yet. It is read and checked here, so nothing is trusted from the
         // manifest: this puts a file from the operator's disk onto a machine an autonomous agent is
         // about to drive, so it stays inside the project, must be a regular file, and is size-capped.
         let uploadAssignment = "";
@@ -239,8 +239,8 @@ export class LiveTerminalSandbox {
                 });
                 const bytes = await readFile(real);
                 await this.sandbox.files.write(destination, bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength));
-                // Inlined into the command string rather than passed as `envs`: the ONLY call in this
-                // lane that carries envs is the keyed codex exec, and that invariant is worth more than
+                // Inlined into the command string rather than passed as `envs`: the only call on this
+                // route that carries envs is the keyed codex exec, and that invariant is worth more than
                 // the convenience of a second envs channel.
                 uploadAssignment = `export HUMANISH_PRODUCT_UPLOAD=${shellQuote(destination)}; `;
                 recordLifecycle("terminal-lab.product.uploaded", `Uploaded ${info.size} bytes to the sandbox in ${Math.max(0, now() - uploadStartedAt)}ms (no runtime env; declared egress auth may already be available).`);
@@ -300,7 +300,7 @@ export class LiveTerminalSandbox {
             prompt: composedPrompt,
             runtimeAuth: runtimeEnv.mode,
             version: runtime.observedVersion,
-            ...(model === undefined ? {} : { model }),
+            model,
             ...(reasoningEffort === undefined ? {} : { reasoningEffort }),
         });
         const commandDigest = digestText(codexCommand);
@@ -342,13 +342,13 @@ export class LiveTerminalSandbox {
             at: nowIso(),
             label: "codex-exec",
             commandDigest,
-            envNames: Object.keys(runtimeEnv.envs), // NAMES only — the credential evidence (item 4).
+            envNames: Object.keys(runtimeEnv.envs), // Names only: the credential evidence (item 4).
             ...(exitCode === undefined ? {} : { exitCode }),
             ...(this.timedOut ? { timedOut: true } : {}),
             durationMs,
         });
-        // Score by the verdict-nonce marker over the SCRUBBED+REDACTED, NORMALIZED transcript — the
-        // exact same logic the local-actor lanes use (extractLocalActorVerdict/normalizeLocalActorTranscript).
+        // Score by the verdict-nonce marker over the scrubbed, redacted and normalized transcript, with
+        // the exact same logic the local-actor routes use (extractLocalActorVerdict/normalizeLocalActorTranscript).
         const rawTranscript = terminalEvents.map((e) => e.chunk).join("");
         const normalizedTranscript = normalizeLocalActorTranscript(rawTranscript);
         const markerStatus = extractLocalActorVerdict(normalizedTranscript, verdictNonce);
@@ -378,8 +378,8 @@ export class LiveTerminalSandbox {
         }
         else {
             // No nonce-verified verdict: the agent did not (credibly) report a terminal status. A run
-            // that exited 0 but printed no verified marker is BLOCKED evidence (the failure IS the
-            // evidence — still structurally verifiable), not a silent pass.
+            // that exited 0 but printed no verified marker is blocked evidence: the failure is the
+            // evidence, and it stays structurally verifiable.
             this.status = "blocked";
             this.completionReason = "gave_up";
             this.reason = `codex exec exit=${exitCode ?? "null"} but no nonce-verified HUMANISH_ACTOR_VERDICT marker was emitted; recorded as blocked (the missing verdict is the evidence).`;
@@ -404,7 +404,7 @@ export class LiveTerminalSandbox {
         const { now, sanitize, warnings } = this.inputs;
         const { recordLifecycle } = this.inputs.recorder;
         const { requestTimeoutMs } = this;
-        // --- Safety contract item 8: PROVEN cleanup, BY EXACT ID, never Sandbox.list. ---
+        // --- Safety contract item 8: proven cleanup, by exact id, never Sandbox.list. ---
         this.cleanup = await teardownSandbox({
             allocation: this.allocation,
             sandboxModule: this.module,
@@ -435,14 +435,14 @@ export class LiveTerminalSandbox {
 }
 /** 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
+    // stdin is disabled (item 7), so no heredoc on a wrapper's stdin carries the prompt;
     // the prompt rides as the final positional arg, shell-quoted. codex exec --json runs once and
     // exits (no interactive loop). --skip-git-repo-check: the workdir is a fresh scratch dir.
     // Pinned via npx (never an ambient/preinstalled `codex` binary, which the stock @e2b/desktop
     // image does not ship, per issue #159); npm_config_update_notifier=false silences npx's own
     // update check so it cannot leak into the captured stdout the scorer/redactor parse.
     const quotedPrompt = shellQuote(args.prompt);
-    // --dangerously-bypass-approvals-and-sandbox: codex's OWN inner sandbox is
+    // --dangerously-bypass-approvals-and-sandbox: codex's own inner sandbox is
     // redundant here and blocks the network/file access the study mission needs.
     // The E2B sandbox is the trust boundary (the disposable machine), and exec mode has no
     // interactive approval channel at all.

package/dist/routes/terminal/participant-text.d.ts

@@ -0,0 +1,23 @@
+import type { ActorTraceItem } from "../../actors/contract.js";
+/** What the reader found in the agent's Codex JSON stdout. */
+export interface TerminalParticipantText {
+    /** Message and reasoning items, the most recent kept under the aggregate limits, then a notice
+     *  when older ones were left out. */
+    items: ActorTraceItem[];
+    /** Distinct agent_message items in the stream, kept or not. */
+    messages: number;
+    /** Distinct participant items: messages, reasoning, commands, web searches and file changes.
+     *  Lifecycle, usage, launcher diagnostics and nested command output are not activity. Zero
+     *  means no recognized item was retained, not that the participant succeeded. */
+    participantItems: number;
+}
+/**
+ * Read participant text from the raw stdout as the recorder receives it. Source redaction runs on
+ * the stored stream and can cut through JSON framing (a redacted URL takes the closing quote with
+ * it), so each line is parsed here, in memory, and only decoded text that has passed `sanitize`
+ * is kept. The raw bytes are never stored.
+ */
+export declare function createTerminalParticipantReader(sanitize: (text: string) => string): {
+    append(raw: string): void;
+    finish(): TerminalParticipantText;
+};