humanish 0.107.0 → 0.109.0

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

@@ -1,5 +1,5 @@
 // Finishing a live terminal session: the actor trace from the captured stream, the spend ledger
-// and its caps check, the evidence files, the bundle, and the lab result.
+// and its caps check, the evidence files, the bundle, and the study result.
 import { buildRunCostSummary } from "../../run/cost-summary.js";
 import { writeContainedOutputFile } from "../../run/contained-output.js";
 import { validatePreparedRunArtifactPaths, } from "../../run/paths.js";
@@ -9,7 +9,7 @@ import { applyAdapterExtensionSeam } from "./adapter.js";
 import { buildLiveTerminalProductBundle } from "./bundle.js";
 import { buildCostLedger, buildNoSpendProof, describeMeasuredSpend, evaluateCapsAgainstLedger, noSpendLineMeasured, noSpendNotEstablished, } from "./ledger.js";
 import { foldScorerFailures, judgeExecution, judgeTerminal, OUTCOME_POLICIES, } from "../../run/judge.js";
-import { terminalExecutionFailures, terminalLabResult, terminalParticipantFacts, } from "./result.js";
+import { terminalExecutionFailures, terminalStudyResult, terminalParticipantFacts, } from "./result.js";
 import { parseTerminalTokenUsage } from "./token-usage.js";
 import { buildTerminalActorTrace, scrubSplitKnownValues, tailOf } from "./trace.js";
 function buildLiveTrace(inputs) {
@@ -25,7 +25,7 @@ function buildLiveTrace(inputs) {
     // 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: usage records arrive once per turn, and the tail
-    // would drop all but the last (#531).
+    // would drop all but the last.
     const terminalTokenUsage = parseTerminalTokenUsage(normalizedTranscript);
     const trace = buildTerminalActorTrace({
         persona,
@@ -71,14 +71,14 @@ async function settleLiveLedgers(inputs, trace, normalizedTranscript) {
     });
     const noSpendProof = buildNoSpendProof(cost, maxUsd ?? null, trace.tokenUsage);
     const proofVerdict = !noSpendProof.satisfied
-        ? `No-spend proof NOT satisfied for maxUsd=${maxUsd ?? "null"}.`
+        ? `No-spend proof not satisfied for maxUsd=${maxUsd ?? "null"}.`
         : noSpendLineMeasured(noSpendProof)
             ? noSpendNotEstablished(maxUsd ?? 0)
             : `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}`);
     // 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)
+    // known job count exceeds maxJobs), the run fails closed with no green result. Unknowns (null)
     // 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
@@ -125,8 +125,8 @@ export async function finishLiveTerminalSession(inputs) {
     const bundle = buildLiveTerminalProductBundle({
         run,
         actorId: plan.actor,
-        labId: plan.labId,
-        ...(plan.title ? { labTitle: plan.title } : {}),
+        studyId: plan.studyId,
+        ...(plan.title ? { studyTitle: plan.title } : {}),
         mission: sanitize(mission),
         persona,
         productName: product.name,
@@ -161,7 +161,7 @@ export async function finishLiveTerminalSession(inputs) {
         ledgers,
         transcript: normalizedTranscript,
         product: product.name,
-        labId: plan.labId,
+        studyId: plan.studyId,
         runId,
         sanitize,
         warnings,
@@ -182,9 +182,9 @@ export async function finishLiveTerminalSession(inputs) {
         cleanup: session.cleanup,
         observer,
     }), OUTCOME_POLICIES.terminal);
-    const result = terminalLabResult({
+    const result = terminalStudyResult({
         cwd,
-        labId: plan.labId,
+        studyId: plan.studyId,
         actorId: plan.actor,
         productName: product.name,
         runId,

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

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

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

@@ -18,6 +18,7 @@ import { TERMINAL_RUNTIME_VERSION_TIMEOUT_MS, buildRuntimeExecPrefix, buildRunti
 import { runWithWallClock, teardownSandbox } from "./sandbox.js";
 import { DEFAULT_REQUEST_TIMEOUT_MS, PRODUCT_SETUP_TIMEOUT_MS, SANDBOX_WORKDIR, UPLOAD_MAX_BYTES, } from "./types.js";
 import { terminalSandboxTimeoutMs } from "./lifetime.js";
+import { plural } from "../../run/text.js";
 export class LiveTerminalSandbox {
     status = "failed";
     completionReason = "harness_error";
@@ -56,7 +57,7 @@ export class LiveTerminalSandbox {
         const { warnings } = this.inputs;
         const { recordLifecycle } = this.inputs.recorder;
         const { requestTimeoutMs, sandboxTimeoutMs } = this;
-        // Declared egress allowlist, or undefined for the historical unrestricted default (#538).
+        // Declared egress allowlist, or undefined for the historical unrestricted default.
         const egressAllow = plan.egressAllow;
         const sandboxModule = await (deps.desktopModule ?? loadE2BDesktopModule)();
         this.module = sandboxModule;
@@ -99,7 +100,7 @@ export class LiveTerminalSandbox {
         this.sandboxId = sandboxId;
         this.createdAtMs = now();
         await validatePreparedRunArtifactPaths(runPaths);
-        recordLifecycle("terminal-lab.sandbox.created", `E2B shell sandbox ${sandboxId} created with positive-allowlist metadata and kill-on-timeout; NO sandbox-global env.`);
+        recordLifecycle("terminal-lab.sandbox.created", `E2B shell sandbox ${sandboxId} created with allowlisted metadata and kill-on-timeout, and with no sandbox-wide environment variables.`);
         const sandboxResources = await observeDesktopResources(sandbox);
         this.resources = sandboxResources;
         if ("reason" in sandboxResources) {
@@ -108,8 +109,8 @@ export class LiveTerminalSandbox {
         // The allowlist is evidence: a reader of the ledger can see exactly what the participant was
         // able to reach, without the ledger carrying any secret.
         recordLifecycle("terminal-lab.egress.policy", egressAllow === undefined
-            ? "Egress UNRESTRICTED (no execution.egressAllow declared)."
-            : `Egress routing allowlist: ${egressAllow.length} declared host(s): ${egressAllow.join(", ")}; deny-all fallback. Domain routing is not strict destination isolation on shared infrastructure.`);
+            ? "Egress is unrestricted (no execution.egressAllow declared)."
+            : `Egress routing allowlist: ${plural(egressAllow.length, "declared host")}: ${egressAllow.join(", ")}; deny-all fallback. Domain routing is not strict destination isolation on shared infrastructure.`);
         recordLifecycle("terminal-lab.runtime-auth", runtimeEnv.mode === "openai-egress"
             ? "Runtime auth openai-egress: raw key remains outside the sandbox in the api.openai.com HTTPS Authorization transform; Codex receives an inert CODEX_API_KEY placeholder and the default OpenAI endpoint. Every sandbox process, including bootstrap/setup, can spend via this proxy; no added routing restriction or provider spending limit."
             : `Runtime auth openai-env: raw key from ${runtimeEnv.keyName} is passed command-scoped to Codex and inherited by its child processes.`);
@@ -131,7 +132,7 @@ export class LiveTerminalSandbox {
         const { requestTimeoutMs } = this;
         // --- Runtime bootstrap: no runtime env; openai-egress proxy capability is already available. ---
         // The stock desktop needs Node/npm on `PATH` before npx can run Codex. Reuse a working
-        // installation or install the pinned official binary after checksum verification (#674).
+        // installation or install the pinned official binary after checksum verification.
         // No raw runtime key touches this step; the egress proxy, when selected, is already available.
         const bootstrapStartedAt = now();
         let bootstrapError;
@@ -149,7 +150,7 @@ export class LiveTerminalSandbox {
         }
         const bootstrapDurationMs = Math.max(0, now() - bootstrapStartedAt);
         recordLifecycle("terminal-lab.runtime.bootstrapped", bootstrapError
-            ? `Runtime bootstrap FAILED after ${bootstrapDurationMs}ms: ${bootstrapError}. codex exec runs via npx and needs Node/npm present; the participant fails closed rather than attempting an exec with no runtime.`
+            ? `Runtime bootstrap failed after ${bootstrapDurationMs}ms: ${bootstrapError}. codex exec runs through npx and needs Node and npm, so the participant stops here instead of starting codex with no runtime.`
             : `Runtime bootstrap ensured Node/npm present in ${bootstrapDurationMs}ms (codex exec runs via npx).`);
         if (bootstrapError) {
             // Fail closed as a structured route status (never a raw throw): no codex exec is attempted
@@ -207,7 +208,7 @@ export class LiveTerminalSandbox {
         // Same channel and same guarantees as the runtime bootstrap above: no runtime key touches it,
         // 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
+        // studies a project contains, in an empty directory, measures the study and not the product
         // (learned the hard way on the desktop route, labs/tui-self-study.yaml).
         const install = plan.product.install;
         if (install === undefined)
@@ -259,7 +260,7 @@ export class LiveTerminalSandbox {
             const setup = await this.sandbox.commands.run(`${uploadAssignment}cd ${SANDBOX_WORKDIR} && ${install}`, {
                 // The install step may run the product itself (release:dogfood's does: `humanish init
                 // --yes`); on the 0.67.0 dogfood that one command arrived unmarked while the participant's
-                // nine others carried the marker (#546).
+                // nine others carried the marker.
                 envs: { HUMANISH_STUDY_PARTICIPANT: "1" },
                 requestTimeoutMs,
                 timeoutMs: PRODUCT_SETUP_TIMEOUT_MS,
@@ -272,7 +273,7 @@ export class LiveTerminalSandbox {
             setupError = toErrorMessage(error);
         }
         recordLifecycle("terminal-lab.product.prepared", setupError
-            ? `Product setup FAILED after ${Math.max(0, now() - setupStartedAt)}ms: ${sanitize(setupError)}`
+            ? `Product setup failed after ${Math.max(0, now() - setupStartedAt)}ms: ${sanitize(setupError)}`
             : `Product setup completed in ${Math.max(0, now() - setupStartedAt)}ms (no runtime env; declared egress auth may already be available).`);
         if (setupError) {
             this.status = "failed";
@@ -292,8 +293,8 @@ export class LiveTerminalSandbox {
         const { requestTimeoutMs, wallClockMs } = this;
         // --- The keyed run: `codex exec --json` non-interactively (stdin disabled). ---
         // openai-env passes the real key here; openai-egress passes an inert placeholder. stdin is
-        // never wired (safety contract item 7) — commands.run takes no stdin channel. The command's
-        // wall-clock is bounded by maxMinutes (safety contract item 2): commands.run timeoutMs +
+        // never wired: commands.run takes no stdin channel. The command's
+        // wall-clock is bounded by maxMinutes: commands.run timeoutMs +
         // an injected-clock guard so a mock/real run that exceeds it is killed and fails closed.
         const codexCommand = buildCodexExecCommand({
             workdir: SANDBOX_WORKDIR,
@@ -312,8 +313,7 @@ export class LiveTerminalSandbox {
             const result = await runWithWallClock(this.sandbox.commands.run(codexCommand, {
                 // The selected command env (raw key or inert placeholder). The participant
                 // marker rides the same command: humanish telemetry from inside a study reads as a new
-                // adopter otherwise. #546 added the flag and nothing set it; the 0.66.0 dogfood
-                // participant's twelve commands arrived unmarked.
+                // adopter otherwise.
                 envs: { ...runtimeEnv.envs, HUMANISH_STUDY_PARTICIPANT: "1" },
                 requestTimeoutMs,
                 timeoutMs: wallClockMs,
@@ -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. ---
+        // --- Proven cleanup, by exact id, never Sandbox.list. ---
         this.cleanup = await teardownSandbox({
             allocation: this.allocation,
             sandboxModule: this.module,
@@ -439,7 +439,7 @@ function buildCodexExecCommand(args) {
     // 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
+    // image does not ship); 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

package/dist/routes/terminal/participant-text.js

@@ -1,5 +1,6 @@
 import { normalizeLocalActorTranscript } from "../../run/terminal-contract.js";
 import { MESSAGE_CHARS, PENDING_LINE_CHARS, TEXT_ITEMS_BYTES, TEXT_ITEMS_MAX } from "./types.js";
+import { plural } from "../../run/text.js";
 const itemEvents = new Set(["item.started", "item.updated", "item.completed"]);
 const nonempty = (value) => typeof value === "string" && value.trim().length > 0;
 const object = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
@@ -148,7 +149,7 @@ export function createTerminalParticipantReader(sanitize) {
             if (droppedLines > 0)
                 notices.push([
                     "agent output lines skipped",
-                    `Skipped ${droppedLines} stdout line(s) that ran past ${PENDING_LINE_CHARS} characters without a newline. Items on those lines are not in this trace or its counts.`,
+                    `Skipped ${plural(droppedLines, "stdout line")} that ran past ${PENDING_LINE_CHARS} characters without a newline. Items on those lines are not in this trace or its counts.`,
                 ]);
             notices.forEach(([title, text], index) => items.push({
                 id: `notice-${String(index + 1).padStart(3, "0")}`,

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

@@ -1,6 +1,6 @@
 import type { ActorPersonaRef } from "../../actors/contract.js";
-import { type ResolvedPersona } from "../../lab/persona.js";
-import type { TerminalPlan } from "../../lab/plan-types.js";
+import { type ResolvedPersona } from "../../study/persona.js";
+import type { TerminalPlan } from "../../study/plan-types.js";
 /** A terminal run's persona, resolved against the project's committed persona files. */
 export interface TerminalPersona {
     personaId: string;

package/dist/routes/terminal/persona.js

@@ -3,14 +3,14 @@
 // record come from one place. Each path keeps its own prompt and its own set of scrubbed secrets.
 import { realpath } from "node:fs/promises";
 import path from "node:path";
-import { personaBrief, personaToDirectives, renderPersonaPromptSection, } from "../../lab/persona.js";
-import { resolveCommittedPersona } from "../../lab/persona-resolve.js";
+import { personaBrief, personaToDirectives, renderPersonaPromptSection, } from "../../study/persona.js";
+import { resolveCommittedPersona } from "../../study/persona-resolve.js";
 import { prepareSelectedOutputDirectory } from "../../run/contained-output.js";
 /** Resolves the plan's persona; the resolver's warnings go into `warnings`. */
 export async function resolveTerminalPersona(args) {
     const personaId = args.plan.personaId ?? "autonomous-terminal-agent";
     const physicalCwd = await realpath(args.cwd);
-    // Resolve the committed persona so its traits actually shape the agent prompt (#308); fail-safe to
+    // Resolve the committed persona so its traits actually shape the agent prompt; fail-safe to
     // the bare persona id (no traits applied) when no persona file is committed.
     const projectRoot = await prepareSelectedOutputDirectory(path.dirname(physicalCwd), physicalCwd);
     const { persona, warnings } = await resolveCommittedPersona(projectRoot, personaId);

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

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

package/dist/routes/terminal/plan.js

@@ -5,48 +5,48 @@ import { DEFAULT_OPENAI_CU_MODEL } from "../../actors/computer-use/openai-provid
 import { resolveAutomaticAnalysis } from "../../analysis/automatic-config.js";
 import { isReasoningEffort } from "../../actors/reasoning-effort.js";
 import { actorRegistry, isTerminalActorDescriptor } from "../../actors/registry.js";
-import { isNonEmpty, planBase } from "../../lab/plan-base.js";
-import { desktopMediaValidationReason, taskProtocolValidationReason, } from "../../lab/validation.js";
+import { isNonEmpty, planBase } from "../../study/plan-base.js";
+import { desktopMediaValidationReason, taskProtocolValidationReason, } from "../../study/validation.js";
 import { MAX_SANDBOX_MS } from "../../substrates/e2b/lifetime.js";
 import { NODE_BOOTSTRAP_TIMEOUT_MS } from "../../subject/node-bootstrap.js";
 import { terminalSandboxTimeoutMs } from "./lifetime.js";
 import { isExactRuntimeVersion, TERMINAL_RUNTIME_VERSION_TIMEOUT_MS } from "./runtime.js";
 import { PRODUCT_SETUP_TIMEOUT_MS, TERMINAL_SANDBOX_TIMEOUT_BUFFER_MS, } from "./types.js";
 /**
- * Plan a terminal-product lab. It is called for any config handed to the terminal runner, not
+ * Plan a terminal-product study. It is called for any config handed to the terminal runner, not
  * only one routeOf sends here, so a config for another route gets this route's refusal.
  */
-export function planTerminalLab(config, input) {
+export function planTerminalStudy(config, input) {
     const refuse = (code, message, actor) => ({
         ok: false,
         refusal: { route: "terminal", code, message, ...(actor === undefined ? {} : { actor }) },
     });
     if (String(config.comms?.email?.kind) === "real")
-        return refuse("HUMANISH_TERMINAL_LAB_SUBJECT_INVALID", "Real email receiving is unsupported on the terminal route. Use a supported hosted computer-use browser lab.");
+        return refuse("HUMANISH_TERMINAL_SUBJECT_INVALID", "Real email receiving is unsupported on the terminal route. Use a supported hosted computer-use browser study.");
     const mediaReason = desktopMediaValidationReason(config);
     if (mediaReason)
-        return refuse("HUMANISH_TERMINAL_LAB_SUBJECT_INVALID", mediaReason);
+        return refuse("HUMANISH_TERMINAL_SUBJECT_INVALID", mediaReason);
     const analysis = resolveAutomaticAnalysis(config.review?.analysis);
     if (!analysis.ok)
-        return refuse("HUMANISH_LAB_ANALYSIS_INVALID", analysis.message);
+        return refuse("HUMANISH_STUDY_ANALYSIS_INVALID", analysis.message);
     const tasksReason = taskProtocolValidationReason(config, false);
     if (tasksReason)
-        return refuse("HUMANISH_LAB_TASKS_UNSUPPORTED", tasksReason);
+        return refuse("HUMANISH_STUDY_TASKS_UNSUPPORTED", tasksReason);
     const actorType = config.actors[0]?.type ?? "";
     const descriptor = actorRegistry[actorType];
     if (!descriptor || !isTerminalActorDescriptor(descriptor))
-        return refuse("HUMANISH_TERMINAL_LAB_ACTOR_UNSUPPORTED", `actors[0].type "${actorType}" is not a registered terminal actor.`);
+        return refuse("HUMANISH_TERMINAL_ACTOR_UNSUPPORTED", `actors[0].type "${actorType}" is not a registered terminal actor.`);
     const runtimeVersion = config.execution?.runtime?.version;
     const actor = config.actors[0];
     if ((config.execution?.runtime !== undefined && !isExactRuntimeVersion(runtimeVersion)) ||
         (actor?.model !== undefined &&
             (typeof actor.model !== "string" || actor.model.trim().length === 0)) ||
         (actor?.reasoningEffort !== undefined && !isReasoningEffort(actor.reasoningEffort)))
-        return refuse("HUMANISH_TERMINAL_LAB_FAILED", "Terminal runtime settings require an exact Codex version, a nonempty model when declared, and a supported reasoning-effort value.");
+        return refuse("HUMANISH_TERMINAL_FAILED", "Terminal runtime settings require an exact Codex version, a nonempty model when declared, and a supported reasoning-effort value.");
     const product = config.subject.product;
     const surfaces = product?.publicSurfaces ?? [];
     if (!product || !product.name || !isNonEmpty(surfaces))
-        return refuse("HUMANISH_TERMINAL_LAB_SUBJECT_INVALID", "terminal-product subjects require `subject.product` with a name and at least one public surface URL.", descriptor.id);
+        return refuse("HUMANISH_TERMINAL_SUBJECT_INVALID", "terminal-product subjects require `subject.product` with a name and at least one public surface URL.", descriptor.id);
     const base = planBase(config, {
         dryRun: input.dryRun,
         analysis,
@@ -82,19 +82,19 @@ export function planTerminalLab(config, input) {
     // that declares that placement may run live.
     const keyPlacement = descriptor.capabilities.keyPlacement;
     if (keyPlacement !== "in-sandbox-command-scoped")
-        return refuse("HUMANISH_TERMINAL_LAB_KEYPLACEMENT_INVALID", `Terminal actor "${descriptor.id}" must declare keyPlacement "in-sandbox-command-scoped" for a live run (got "${String(keyPlacement)}"). The engine requires this registered default before applying the declared runtime-auth mode.`, descriptor.id);
+        return refuse("HUMANISH_TERMINAL_KEYPLACEMENT_INVALID", `Terminal actor "${descriptor.id}" must declare keyPlacement "in-sandbox-command-scoped" for a live run (got "${String(keyPlacement)}"). The engine requires this registered default before applying the declared runtime-auth mode.`, descriptor.id);
     // A live run grants the in-sandbox agent provider access, so a fail-closed cap must be in force.
     const maxUsd = caps?.maxUsd;
     const maxMinutes = caps?.maxMinutes;
     if (caps === undefined || maxUsd === undefined || maxMinutes === undefined || maxMinutes <= 0)
-        return refuse("HUMANISH_TERMINAL_LAB_CAPS_MISSING", "A live terminal-product run grants provider access to the in-sandbox agent and so REQUIRES a fail-closed cap: scenario.caps with maxUsd (0 = no-spend) and a positive maxMinutes (the codex command's wall-clock kill). The live key is never exercised without a cap in force.", descriptor.id);
+        return refuse("HUMANISH_TERMINAL_CAPS_MISSING", "A live terminal-product run gives the agent in the sandbox access to a model provider, so it needs a cap: set scenario.caps with maxUsd (0 means no spend) and a positive maxMinutes (the time limit for the codex command). The key is used only while the cap is in force.", descriptor.id);
     // maxUsd is checked against the cost ledger after the session, and only known lines can trip it.
     // The ledger's provider line takes only provider-reported cost, which Codex does not report (the
     // token estimate in run.json is not a measurement), and core has no product, media or payment
     // signal, so without a costProbe every line is null and a positive maxUsd could never trip. That
     // cap would promise a bound nothing enforces, so it is refused; maxMinutes bounds a live run.
     if (maxUsd > 0 && input.hasCostProbe !== true)
-        return refuse("HUMANISH_TERMINAL_LAB_UNPRICED_CAP", `scenario.caps.maxUsd=${maxUsd} cannot be enforced: Codex reports no provider cost for the participant (its token cost is only estimated after the run) and no product, media or payment spend is measured, so a positive dollar cap can never trip. Set scenario.caps.maxUsd to 0 and bound the run with scenario.caps.maxMinutes, the codex command's wall-clock kill. No sandbox was created and the runtime key was not used.`, descriptor.id);
+        return refuse("HUMANISH_TERMINAL_UNPRICED_CAP", `scenario.caps.maxUsd=${maxUsd} cannot be enforced: Codex reports no provider cost for the participant (its token cost is only estimated after the run) and no product, media or payment spend is measured, so a positive dollar cap can never trip. Set scenario.caps.maxUsd to 0 and bound the run with scenario.caps.maxMinutes, the codex command's wall-clock kill. No sandbox was created and the runtime key was not used.`, descriptor.id);
     // The sandbox's timeout covers the steps before the codex command, maxMinutes and the teardown
     // buffer, and E2B refuses a sandbox over an hour. Refuse here, with the arithmetic, rather than
     // after the plan prints, from a provider 400 that names neither knob.
@@ -102,7 +102,7 @@ export function planTerminalLab(config, input) {
     const sandboxTimeoutMs = terminalSandboxTimeoutMs({ maxMinutes, productInstall });
     if (sandboxTimeoutMs > MAX_SANDBOX_MS) {
         const headroomMinutes = (sandboxTimeoutMs - maxMinutes * 60_000) / 60_000;
-        return refuse("HUMANISH_TERMINAL_LAB_CAPS_INVALID", `scenario.caps.maxMinutes ${maxMinutes} derives a ${sandboxTimeoutMs / 60_000}m sandbox deadline, and a sandbox may not live longer than ${MAX_SANDBOX_MS / 60_000}m. The deadline is maxMinutes plus ${headroomMinutes}m: the Node bootstrap (${NODE_BOOTSTRAP_TIMEOUT_MS / 60_000}m), the runtime version check (${TERMINAL_RUNTIME_VERSION_TIMEOUT_MS / 60_000}m)${productInstall ? `, the product setup (${PRODUCT_SETUP_TIMEOUT_MS / 60_000}m)` : ""} and the teardown buffer (${TERMINAL_SANDBOX_TIMEOUT_BUFFER_MS / 60_000}m). Lower scenario.caps.maxMinutes to at most ${MAX_SANDBOX_MS / 60_000 - headroomMinutes}. No sandbox was created and the runtime key was not used.`, descriptor.id);
+        return refuse("HUMANISH_TERMINAL_CAPS_INVALID", `scenario.caps.maxMinutes ${maxMinutes} derives a ${sandboxTimeoutMs / 60_000}m sandbox deadline, and a sandbox may not live longer than ${MAX_SANDBOX_MS / 60_000}m. The deadline is maxMinutes plus ${headroomMinutes}m: the Node bootstrap (${NODE_BOOTSTRAP_TIMEOUT_MS / 60_000}m), the runtime version check (${TERMINAL_RUNTIME_VERSION_TIMEOUT_MS / 60_000}m)${productInstall ? `, the product setup (${PRODUCT_SETUP_TIMEOUT_MS / 60_000}m)` : ""} and the teardown buffer (${TERMINAL_SANDBOX_TIMEOUT_BUFFER_MS / 60_000}m). Lower scenario.caps.maxMinutes to at most ${MAX_SANDBOX_MS / 60_000 - headroomMinutes}. No sandbox was created and the runtime key was not used.`, descriptor.id);
     }
     return {
         ok: true,

package/dist/routes/terminal/recorder.js

@@ -32,13 +32,13 @@ export function createTerminalRecorder(args) {
             return;
         }
         transcriptBytes += Buffer.byteLength(raw, "utf8");
-        // Scrub, then redact, at the source (safety contract item 5). Only the participant reader below
+        // Scrub, then redact, at the source. Only the participant reader below
         // sees the raw bytes, and it stores none of them.
         terminalEvents.push({ at: nowIso(), stream, chunk: sanitize(raw) });
         if (stream === "stdout")
             participantText.append(raw);
     };
-    // E2B can stream every byte through callbacks and return the same complete output (#667).
+    // E2B can stream every byte through callbacks and return the same complete output.
     // Track transport delivery, independently per stream, rather than deduplicating participant
     // lines or equal usage records. Hash raw callback bytes before redaction/truncation so the
     // comparison cannot confuse two values that redact identically or lose capped-away delivery.

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

@@ -1,7 +1,7 @@
 import type { ObserverResult } from "../../observer/render.js";
 import type { ActorCompletionReason, ActorStatus, ActorTrace } from "../../actors/contract.js";
 import { type ExecutionFailure, type ExecutionOutcome, type Judgment, type ParticipantFacts } from "../../run/judge.js";
-import { type NoSpendProof, type TerminalCostLedger, type TerminalLedgers, type TerminalProductLabResult } from "./types.js";
+import { type NoSpendProof, type TerminalCostLedger, type TerminalLedgers, type TerminalProductStudyResult } from "./types.js";
 /**
  * What judge.ts reads from a finished terminal session, after a blown cap has overridden it. It has
  * no engagement or blocker rule: the agent's nonce-verified marker is its declared outcome.
@@ -20,10 +20,10 @@ export declare function terminalExecutionFailures(args: {
     cleanup: TerminalLedgers["cleanup"];
     observer: Pick<ObserverResult, "ok" | "error">;
 }): ExecutionFailure[];
-/** The terminal-product lab result for a live run, from its session, cleanup and cost ledger. */
-export declare function terminalLabResult(args: {
+/** The terminal-product study result for a live run, from its session, cleanup and cost ledger. */
+export declare function terminalStudyResult(args: {
     cwd: string;
-    labId: string;
+    studyId: string;
     actorId: string;
     productName: string;
     runId: string;
@@ -44,4 +44,4 @@ export declare function terminalLabResult(args: {
     execution: ExecutionOutcome;
     observer: ObserverResult;
     warnings: string[];
-}): TerminalProductLabResult;
+}): TerminalProductStudyResult;

package/dist/routes/terminal/result.js

@@ -1,5 +1,6 @@
 import { OUTCOME_POLICIES, participantHarnessFailed, resultOk, } from "../../run/judge.js";
-import { TERMINAL_PRODUCT_LAB_SCHEMA, } from "./types.js";
+import {} from "./types.js";
+import { studyResultIdentity } from "../../run/study-result.js";
 /**
  * What judge.ts reads from a finished terminal session, after a blown cap has overridden it. It has
  * no engagement or blocker rule: the agent's nonce-verified marker is its declared outcome.
@@ -38,21 +39,21 @@ export function terminalExecutionFailures(args) {
             : [
                 {
                     kind: "evidence",
-                    message: observer.error?.message ?? "Observer failed for the terminal-product lab run.",
+                    message: observer.error?.message ?? "Observer failed for the terminal-product run.",
                 },
             ]),
     ];
 }
-/** The terminal-product lab result for a live run, from its session, cleanup and cost ledger. */
-export function terminalLabResult(args) {
-    const { cwd, labId, actorId, productName, runId, sessionStatus, completionReason, sessionReason, sessionError, sandboxId, cleanup, cost, noSpendProof, capFailure, declaredScorerFailure, judgment, execution, observer, warnings, } = args;
-    // The lab's exit code: verified evidence, no harness error and proven cleanup. A blocked/
+/** The terminal-product study result for a live run, from its session, cleanup and cost ledger. */
+export function terminalStudyResult(args) {
+    const { cwd, studyId, actorId, productName, runId, sessionStatus, completionReason, sessionReason, sessionError, sandboxId, cleanup, cost, noSpendProof, capFailure, declaredScorerFailure, judgment, execution, observer, warnings, } = args;
+    // The run's exit code: verified evidence, no harness error and proven cleanup. A blocked/
     // timed-out agent run is still ok-as-evidence at the bundle level (the failure is the evidence),
-    // but the lab result surfaces ok:false on a harness error or unproven teardown (fail-closed).
+    // but the study result surfaces ok:false on a harness error or unproven teardown (fail-closed).
     // remaining===0 is the by-id-confirmed-reclaimed state; remaining===1 (still present) and
     // remaining===-1 (kill(id) itself failed) are both unproven by design.
     const cleanupProven = cleanup.killed && cleanup.remaining === 0;
-    // A CONFIG-DECLARED scorer that failed to render a pass (status:"fail" / malformed / throw) fails the
+    // A config-declared scorer that failed to render a pass (status:"fail" / malformed / throw) fails the
     // run result as well as the persisted verdict: the keystone route's declared rubric is a gate, so
     // its fail must drive exit code. Library callers never set this (additive, back-compat).
     const ok = resultOk({
@@ -62,10 +63,9 @@ export function terminalLabResult(args) {
         policy: OUTCOME_POLICIES.terminal,
     });
     return {
-        schema: TERMINAL_PRODUCT_LAB_SCHEMA,
+        ...studyResultIdentity("terminal", studyId),
         ok,
         cwd,
-        labId,
         actor: actorId,
         product: productName,
         dryRun: false,
@@ -97,12 +97,12 @@ export function terminalLabResult(args) {
             : {
                 error: {
                     code: (!cleanupProven
-                        ? "HUMANISH_TERMINAL_LAB_CLEANUP_UNPROVEN"
+                        ? "HUMANISH_TERMINAL_CLEANUP_UNPROVEN"
                         : capFailure !== undefined
-                            ? "HUMANISH_TERMINAL_LAB_CAPS_EXCEEDED"
-                            : "HUMANISH_TERMINAL_LAB_FAILED"),
+                            ? "HUMANISH_TERMINAL_CAPS_EXCEEDED"
+                            : "HUMANISH_TERMINAL_FAILED"),
                     message: !cleanupProven
-                        ? `Live terminal-product run could not prove sandbox teardown (killed=${cleanup.killed}, remaining=${cleanup.remaining}): ${cleanup.reason}. A run that cannot prove teardown fails closed.${sessionError !== undefined ? ` Session failure: ${sessionError}` : ""}`
+                        ? `Live terminal-product run could not prove sandbox teardown (killed=${cleanup.killed}, remaining=${cleanup.remaining}): ${cleanup.reason}. A run that cannot prove its sandbox was removed does not pass.${sessionError !== undefined ? ` Session failure: ${sessionError}` : ""}`
                         : (declaredScorerFailure ??
                             capFailure ??
                             sessionError ??

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

@@ -1,22 +1,22 @@
 import { type TerminalRefusal } from "./plan.js";
-import type { TerminalPlan } from "../../lab/plan-types.js";
-import type { AdmittedPlan } from "../../run-lab.js";
-import { type RunTerminalProductLabOptions, type TerminalProductLabResult, type TerminalRunInput } from "./types.js";
+import type { TerminalPlan } from "../../study/plan-types.js";
+import type { AdmittedPlan } from "../../run-study.js";
+import { type RunTerminalProductStudyOptions, type TerminalProductStudyResult, type TerminalRunInput } from "./types.js";
 /**
  * The config-taking entry point. It plans, returns a refusal with the same envelope and analysis
  * record the route has always returned, and otherwise runs the plan.
  */
-export declare function runTerminalProductLab(options: RunTerminalProductLabOptions): Promise<TerminalProductLabResult>;
-/** A refused terminal lab's result: the route's envelope, and the analysis record a refusal gets. */
-export declare function terminalLabRefusal(options: RunTerminalProductLabOptions, refusal: TerminalRefusal): Promise<TerminalProductLabResult>;
+export declare function runTerminalProductStudy(options: RunTerminalProductStudyOptions): Promise<TerminalProductStudyResult>;
+/** A refused terminal study's result: the route's envelope, and the analysis record a refusal gets. */
+export declare function terminalStudyRefusal(options: RunTerminalProductStudyOptions, refusal: TerminalRefusal): Promise<TerminalProductStudyResult>;
 /**
  * Run a terminal plan. The run scope gives a direct library caller the same run lifetime the CLI
- * gets: whichever of its fail-closed exits the lab takes, the run it started is closed, and only a
+ * gets: whichever of its fail-closed exits the run takes, the run it started is closed, and only a
  * run that published its final bundle reaches automatic analysis.
  */
-export declare function runTerminalPlan(plan: TerminalPlan, input: TerminalRunInput): Promise<TerminalProductLabResult>;
+export declare function runTerminalPlan(plan: TerminalPlan, input: TerminalRunInput): Promise<TerminalProductStudyResult>;
 /**
- * runLab's step for a terminal plan. It runs a live plan's local checks (checkLiveTerminalMachine)
+ * runStudyWith's step for a terminal plan. It runs a live plan's local checks (checkLiveTerminalMachine)
  * before any run scope opens, so the CLI can present their refusal before it loads a declared
  * scorer, and returns the run that continues from them with that scorer.
  */