humanish 0.107.0 → 0.108.0

package/dist/routes/terminal/plan.js

@@ -22,31 +22,31 @@ export function planTerminalLab(config, input) {
         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 lab.");
     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.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.
@@ -52,7 +53,7 @@ export function terminalLabResult(args) {
     // 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", labId),
         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.js

@@ -8,7 +8,7 @@
 //      live-sandbox.ts and live-finish.ts); a dry plan publishes its contract bundle (dry-run.ts);
 //   4. automatic analysis of a run that published its final bundle.
 //
-// The safety contract (`docs/goals/terminal-product-lane/goal.md`) is enforced by construction in
+// The safety contract (`docs/history/goals/terminal-product-lane/goal.md`) is enforced by construction in
 // the files each item names, and checked by the verifier (verify/actor.ts
 // validateTerminalProductEvidence):
 //   1. Explicit key placement. openai-env (default) injects the raw runtime key command-scoped,
@@ -20,7 +20,7 @@
 //      (default/require 0 = no-spend) + maxMinutes (wall-clock kill of the codex command).
 //      Enforced in plan.ts (caps required), live-sandbox.ts and lifetime.ts (the wall clock).
 //   3. Public surfaces only. The mission references only subject.product.publicSurfaces + the
-//      author mission. No clone, no private-source access — nothing is git-cloned on this route.
+//      author mission. No clone and no private-source access: nothing is git-cloned on this route.
 //      Enforced in session.ts, which composes the prompt.
 //   4. Deny-by-default credentials. The command envs are built from an allowlist holding only the
 //      declared runtime key; GITHUB_TOKEN/GH_TOKEN/payment/deploy/db/media keys are excluded by
@@ -52,7 +52,8 @@ import { runDryTerminalLab } from "./dry-run.js";
 import { checkLiveTerminalMachine, runLiveTerminalSession } from "./session.js";
 import { terminalRouteScorer } from "../../lab/adapter-scorer-loader.js";
 import { withLateScorer } from "../../lab/route-inputs.js";
-import { TERMINAL_PRODUCT_LAB_SCHEMA, } from "./types.js";
+import {} from "./types.js";
+import { studyResultIdentity } from "../../run/study-result.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.
@@ -71,10 +72,9 @@ export async function runTerminalProductLab(options) {
 export function terminalLabRefusal(options, refusal) {
     const { config, dryRun } = options;
     const refused = {
-        schema: TERMINAL_PRODUCT_LAB_SCHEMA,
+        ...studyResultIdentity("terminal", config.id),
         ok: false,
         cwd: path.resolve(options.cwd),
-        labId: config.id,
         actor: refusal.actor ?? config.actors[0]?.type ?? "",
         product: config.subject.product?.name ?? "",
         dryRun,
@@ -141,10 +141,9 @@ function completeTerminalAnalysis(plan, input, result, finished) {
 function terminalFailure(plan, input, warnings) {
     const cwd = path.resolve(input.cwd);
     return (code, message) => ({
-        schema: TERMINAL_PRODUCT_LAB_SCHEMA,
+        ...studyResultIdentity("terminal", plan.labId),
         ok: false,
         cwd,
-        labId: plan.labId,
         actor: plan.actor,
         product: plan.product.name,
         dryRun: plan.dryRun,

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

@@ -25,7 +25,7 @@ export declare function teardownSandbox(args: {
     warnings: string[];
 }): Promise<TerminalLedgers["cleanup"]>;
 /**
- * Race a commands.run promise against the maxMinutes wall-clock (safety contract item 2). The E2B
+ * Race a commands.run promise against the maxMinutes wall-clock. The E2B
  * commands.run timeoutMs is the primary kill; this injected-clock guard is the belt-and-suspenders
  * backstop so a mock CLI (which ignores timeoutMs) is still bounded and fails closed in CI.
  */

package/dist/routes/terminal/sandbox.js

@@ -98,7 +98,7 @@ export async function teardownSandbox(args) {
     }
 }
 /**
- * Race a commands.run promise against the maxMinutes wall-clock (safety contract item 2). The E2B
+ * Race a commands.run promise against the maxMinutes wall-clock. The E2B
  * commands.run timeoutMs is the primary kill; this injected-clock guard is the belt-and-suspenders
  * backstop so a mock CLI (which ignores timeoutMs) is still bounded and fails closed in CI.
  */

package/dist/routes/terminal/session.js

@@ -22,7 +22,7 @@ export function checkLiveTerminalMachine(plan, input, warnings) {
     if (maxUsd > 0) {
         warnings.push(`scenario.caps.maxUsd=${maxUsd} is checked after the session against the lines the costProbe measures; lines it leaves null (unmeasured) never trip it. scenario.caps.maxMinutes bounds the run while it runs.`);
     }
-    // --- Safety contract item 4: deny-by-default credentials; build the command-scoped allowlist. ---
+    // --- Deny-by-default credentials: build the command-scoped allowlist. ---
     const runtimeEnv = buildRuntimeAuth({ runtimeAuth: plan.runtime.auth, env });
     if (!runtimeEnv.ok)
         return runtimeEnv;
@@ -31,7 +31,7 @@ export function checkLiveTerminalMachine(plan, input, warnings) {
     if (missingKeys(plan.requirements, env).length > 0) {
         return {
             ok: false,
-            code: "HUMANISH_TERMINAL_LAB_KEYS_MISSING",
+            code: "HUMANISH_TERMINAL_KEYS_MISSING",
             message: `Live terminal-product labs need E2B_API_KEY in the environment (values are never persisted). ${describeMissingKeys(["E2B_API_KEY"], env)}`,
         };
     }
@@ -86,7 +86,7 @@ export async function runLiveTerminalSession(args) {
         modelSource,
         ...(reasoningEffort === undefined ? {} : { reasoningEffort }),
     });
-    recorder.recordLifecycle("terminal-lab.run.created", `Created live terminal-product run ${runId} (actor ${actor}, product ${product.name}). Caps: maxUsd=${maxUsd}, maxMinutes=${maxMinutes}. Subject provenance UNPINNED (public surfaces only).`);
+    recorder.recordLifecycle("terminal-lab.run.created", `Created live terminal-product run ${runId} (actor ${actor}, product ${product.name}). Caps: maxUsd=${maxUsd}, maxMinutes=${maxMinutes}. Subject provenance: unpinned (public pages only).`);
     const session = new LiveTerminalSandbox({
         plan,
         cwd,
@@ -101,7 +101,7 @@ export async function runLiveTerminalSession(args) {
         maxMinutes,
         e2bApiKey,
         runPaths,
-        metadata: buildSandboxMetadata({ labId: plan.labId, simId: "sim-001", runId }),
+        metadata: buildSandboxMetadata({ labId: plan.labId, recordId: "sim-001", runId }),
         warnings,
         recorder,
     });
@@ -146,7 +146,7 @@ export async function runLiveTerminalSession(args) {
 async function prepareLivePrompt(args) {
     const { plan, cwd, runtimeEnv, env, warnings } = args;
     const { product } = plan;
-    // Compose the prompt from public surfaces and the author mission alone (safety contract item 3).
+    // Compose the prompt from public surfaces and the author mission alone.
     // Inject a per-run verdict nonce: the agent echoes HUMANISH_ACTOR_VERDICT=<status>
     // HUMANISH_ACTOR_NONCE=<nonce>; the scorer verifies the nonce so replayed text cannot forge it.
     const mission = plan.mission ?? defaultMission(product.name);
@@ -160,10 +160,10 @@ async function prepareLivePrompt(args) {
         verdictNonce,
     });
     const promptDigest = digestText(composedPrompt);
-    // --- Safety contract item 5: literal-scrub every known value, then pattern-redact, at the source. ---
+    // --- Literal-scrub every known value, then pattern-redact, at the source. ---
     // The runtime key value (+ any other provisioned value) is scrubbed by literal match before
     // anything persists (a key has no detectable "shape" if it is an arbitrary token); redactText is
-    // the second pass for secret-SHAPED content. Applied PRE-truncation so a cut can never split a
+    // the second pass for secret-shaped content. Applied pre-truncation so a cut can never split a
     // value past the scrubber.
     const knownSecretValues = [runtimeEnv.keyValue, env.E2B_API_KEY?.trim() ?? ""].filter((v) => v.length >= 4);
     const scrubKnownValues = scrubLiterals(knownSecretValues);
@@ -181,6 +181,7 @@ async function prepareLivePrompt(args) {
 }
 /** Compose the live prompt: public surfaces + author mission + the verdict-nonce marker contract. */
 function composeLivePrompt(args) {
+    // prose-check: model prompt (the terminal agent reads this, not a person)
     return [
         args.personaLine,
         `product: ${args.productName}`,

package/dist/routes/terminal/token-usage.d.ts

@@ -3,7 +3,7 @@ import type { ActorTokenUsage } from "../../actors/contract.js";
  * Accumulate runtime-turn usage from a captured `codex exec --json` stream. A Codex turn may
  * include multiple provider requests; these records cannot establish per-request pricing tiers.
  *
- * Returns undefined when the stream carried no usage record at all, which is the honest "no
+ * Returns undefined when the stream carried no usage record at all, which is the "no
  * signal" case and must stay distinguishable from a measured zero. Per-turn records are preserved
  * in `turns` because long-context pricing can only be computed from per-request sizes
  * (src/run/pricing.ts), and totals cannot say which requests crossed a threshold.

package/dist/routes/terminal/token-usage.js

@@ -1,10 +1,9 @@
-// Provider token accounting for the terminal route (#531).
+// Provider token accounting for the terminal route.
 //
-// The gap this closes: a live terminal run reported `cost.lines.provider = null` with source
-// "unmeasured", and the no-spend proof then read `satisfied: true` for `maxUsd: 0` on a run that
-// had demonstrably consumed hundreds of thousands of provider tokens. The statement was honest
-// (it listed provider as unmeasured) but it conflated two very different states: having no signal
-// at all, and knowing exactly how many tokens were spent while lacking a rate to price them.
+// Without these counts, a provider line of `null` with source "unmeasured" would let the no-spend
+// proof read `satisfied: true` for `maxUsd: 0` on a run that consumed hundreds of thousands of
+// provider tokens, conflating two different states: having no signal at all, and knowing exactly
+// how many tokens were spent while lacking a rate to price them.
 //
 // The counts were already in the bundle. `codex exec --json` emits one usage record per turn:
 //   {"type":"turn.completed","usage":{"input_tokens":201536,"cached_input_tokens":170558,
@@ -12,7 +11,7 @@
 //
 // So the route can record a measured token fact even when it cannot record a priced one. Rates stay
 // out of this module deliberately: pricing lives in src/run/pricing.ts, and the terminal route has no
-// real model id to price against (it records `model: "codex"`), so the honest output is
+// real model id to price against (it records `model: "codex"`), so the output is
 // tokens-known-rate-unknown rather than a guessed dollar figure.
 // Bounded to a single line on purpose. `[^}]*` would run past a truncated record's missing brace
 // and swallow the next, valid record's body, silently dropping a real turn from the count.
@@ -24,7 +23,7 @@ function num(value) {
  * Accumulate runtime-turn usage from a captured `codex exec --json` stream. A Codex turn may
  * include multiple provider requests; these records cannot establish per-request pricing tiers.
  *
- * Returns undefined when the stream carried no usage record at all, which is the honest "no
+ * Returns undefined when the stream carried no usage record at all, which is the "no
  * signal" case and must stay distinguishable from a measured zero. Per-turn records are preserved
  * in `turns` because long-context pricing can only be computed from per-request sizes
  * (src/run/pricing.ts), and totals cannot say which requests crossed a threshold.

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

@@ -12,7 +12,7 @@ export declare function scrubSplitKnownValues(events: TerminalEventRecord[], kno
 export declare function tailOf(text: string): string;
 /**
  * Project the live terminal session into the provider-neutral humanish.actor-trace.v1 (`lane`
- * "terminal", protocol "terminal-exec"). counts.actions/messages drive the no-engagement honesty
+ * "terminal", protocol "terminal-exec"). counts.actions/messages drive the no-engagement
  * guard (a real run bumps them; a no-op is caught). No screenshots on this route.
  */
 export declare function buildTerminalActorTrace(args: {
@@ -29,7 +29,7 @@ export declare function buildTerminalActorTrace(args: {
     transcriptTail: string;
     runtimeAuth: LabRuntimeAuth;
     runtime: ActorRuntimeProvenance;
-    /** Runtime-turn aggregate usage parsed from the exec stream (#531). Absent when the stream
+    /** Runtime-turn aggregate usage parsed from the exec stream. Absent when the stream
      *  carried no usage record, which stays distinct from a measured zero. */
     tokenUsage?: ActorTokenUsage;
     /** The agent's own text and activity, read from the raw stdout as it arrived. */

package/dist/routes/terminal/trace.js

@@ -57,7 +57,7 @@ export function tailOf(text) {
 }
 /**
  * Project the live terminal session into the provider-neutral humanish.actor-trace.v1 (`lane`
- * "terminal", protocol "terminal-exec"). counts.actions/messages drive the no-engagement honesty
+ * "terminal", protocol "terminal-exec"). counts.actions/messages drive the no-engagement
  * guard (a real run bumps them; a no-op is caught). No screenshots on this route.
  */
 export function buildTerminalActorTrace(args) {
@@ -88,7 +88,7 @@ export function buildTerminalActorTrace(args) {
         redaction: {
             status: "passed",
             screenshots: "n/a",
-            notes: "Terminal exec output captured via commands.run onStdout/onStderr, scrubbed (literal known values) then redacted (shape patterns) AT THE SOURCE before persisting; no screenshots on this lane.",
+            notes: "Terminal output captured through commands.run onStdout and onStderr; known values are scrubbed and shape patterns redacted before anything is stored. This route takes no screenshots.",
         },
         startedAt: args.createdAt,
         completedAt: args.completedAt,

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

@@ -9,6 +9,7 @@ import type { LabDeps } from "../../lab/lab-deps.js";
 import type { LabConfig } from "../../lab/types.js";
 import type { ObserverResult } from "../../observer/render.js";
 import { type RunAdapterScore, type RunBundle, type RunFeedbackCandidate, type RunScorerProvenance } from "../../run/bundle.js";
+import { type StudyResultIdentity } from "../../run/study-result.js";
 /** Provider-neutral metadata constant: the route's non-secret tag (mirrors CUA_ACTOR_LAB_PROVIDER_METADATA). */
 export declare const TERMINAL_PRODUCT_LAB_PROVIDER_METADATA: {
     readonly mode: "terminal-product-lab";
@@ -22,7 +23,7 @@ export declare const UPLOAD_MAX_BYTES: number;
 /**
  * Server-side reclamation buffer past the codex command's own wall-clock (caps.maxMinutes) kill.
  * Shorter than the desktop routes' SANDBOX_TIMEOUT_BUFFER_MS (src/substrates/e2b/lifetime.ts):
- * when #158 set it, the terminal sandbox ran nothing but the codex command, and after its kill only
+ * when this buffer was set, the terminal sandbox ran nothing but the codex command, and after its kill only
  * teardown remained.
  */
 export declare const TERMINAL_SANDBOX_TIMEOUT_BUFFER_MS: number;
@@ -34,13 +35,12 @@ export declare const TEXT_ITEMS_MAX = 200;
 export declare const TEXT_ITEMS_BYTES: number;
 export declare const PENDING_LINE_CHARS: number;
 export declare const MAX_TRANSCRIPT_BYTES: number;
-export declare const TERMINAL_PRODUCT_LAB_SCHEMA = "humanish.terminal-lab-result.v1";
 /**
- * The read-only evidence a thin adapter's scorer/feedback hook sees (the layer-6 extension seam,
- * issue #154 acceptance #8). It is the FULLY-ASSEMBLED, redacted, verifiable evidence — the live run
+ * The read-only evidence a thin adapter's scorer/feedback hook sees (the adapter extension seam).
+ * It is the fully assembled, redacted, verifiable evidence: the live run
  * bundle, the provider-neutral actor trace, and the persisted ledgers (substrate/command/
  * interventions/cleanup/cost/no-spend). Every member is an exported public type, so a thin adapter
- * types against `import("humanish")` alone — never a deep `src/` import. The adapter reads this
+ * types against `import("humanish")` alone and never needs a deep `src/` import. The adapter reads this
  * to score the product attempt and derive feedback; it cannot mutate core's evidence (the route
  * attaches only the namespaced `RunAdapterScore` it returns + the feedback candidates it derives).
  */
@@ -56,7 +56,7 @@ export interface TerminalProductScoringContext {
      * values) then redacted (shape patterns) at the source, capped at MAX_TRANSCRIPT_BYTES, and
      * byte-identical to the persisted terminal-transcript.txt artifact. The trace's transcriptTail
      * is a ~2KB projection of this; a scorer needs the whole session so a rubric can find
-     * command-tier evidence anywhere in it, not only in the tail window (#341).
+     * command-tier evidence anywhere in it.
      */
     transcript: string;
     /** The studied product name (public-safe). */
@@ -77,9 +77,9 @@ export type TerminalCostProbe = (context: {
 /** The scorer functions a terminal run calls: `RunLabOptions.scorer` without `deriveArtifacts`. */
 export interface TerminalScorer {
     /**
-     * The layer-6 extension seam (issue #154 acceptance #8: "product-adapter hooks without forking
-     * core"). A thin in-repo/out-of-tree adapter registers a product scorer here. The route calls it
-     * (when provided) over the fully-assembled evidence and attaches the returned, ADAPTER-NAMESPACED
+     * The adapter extension seam: product-adapter hooks without forking
+     * core. A thin in-repo/out-of-tree adapter registers a product scorer here. The route calls it
+     * (when provided) over the fully-assembled evidence and attaches the returned, adapter-namespaced
      * `RunAdapterScore` to `bundle.adapterScore` without core knowing any product noun (the score is
      * namespaced + its component breakdown rides in `data`). When no scorer is given, the default
      * mission-based verdict (`review`) is unchanged. The adopter's scorecard plugs in here; product
@@ -90,9 +90,9 @@ export interface TerminalScorer {
      * Companion seam: derive product-feedback candidates from the same assembled evidence. The route
      * appends the returned candidates to `bundle.feedbackCandidates`. The adapter records its
      * product-specific concepts (public CLI command observed, hosted success-or-blocker, feedback id,
-     * media/job ids, no-spend proof, defection/friction risk) under each candidate's ADAPTER-NAMESPACED
-     * `adapter` block — never as core enums (issue #154's "record product-specific concepts as
-     * NON-core nouns" list). The candidates must still satisfy core's feedback-candidate shape (which
+     * media/job ids, no-spend proof, defection/friction risk) under each candidate's adapter-namespaced
+     * `adapter` block and never as core enums.
+     * The candidates must still satisfy core's feedback-candidate shape (which
      * the bundle verifier enforces), so a malformed adapter candidate fails closed.
      */
     deriveFeedback?: (ctx: TerminalProductScoringContext) => RunFeedbackCandidate[] | Promise<RunFeedbackCandidate[]>;
@@ -119,7 +119,7 @@ export interface RunTerminalProductLabOptions {
     /** Test seams: the E2B module, the Observer renderer, the clock and the cost probe. */
     deps?: LabDeps;
     /**
-     * Present only when the scorer was config-declared and loaded by the CLI (#316). Its presence
+     * Present only when the scorer was config-declared and loaded by the CLI. Its presence
      * is the "declared" marker: a config-declared terminal scorer returning status:"fail" flips
      * bundle.review.verdict (like the browser routes), and one that throws becomes a visible review.gaps
      * entry. A library caller passing `scorer` leaves this absent and keeps today's purely
@@ -127,14 +127,12 @@ export interface RunTerminalProductLabOptions {
      */
     scorerProvenance?: RunScorerProvenance;
 }
-export interface TerminalProductLabResult extends AutomaticAnalysisResult {
-    schema: typeof TERMINAL_PRODUCT_LAB_SCHEMA;
+export interface TerminalProductLabResult extends AutomaticAnalysisResult, StudyResultIdentity<"terminal"> {
     /** True when the bundle verified and (dry-run, or the live session reached a terminal verdict
      *  without a harness error + cleanup was proven). The agent's pass/fail is evidence, not the
      *  lab's exit code. */
     ok: boolean;
     cwd: string;
-    labId: string;
     /** The registry-resolved actor id that ran (or would run) the session. */
     actor: string;
     /** The studied product name (public-safe). */
@@ -151,11 +149,11 @@ export interface TerminalProductLabResult extends AutomaticAnalysisResult {
     sandbox?: {
         sandboxId: string;
         killed: boolean;
-        /** BY-ID proof (never a re-list): 0 = confirmed reclaimed, 1 = still present (unconfirmed),
+        /** By-id proof (never a re-list): 0 = confirmed reclaimed, 1 = still present (unconfirmed),
          *  -1 = kill(id) itself failed or was unavailable. See TerminalLedgers["cleanup"]. */
         remaining: number;
     };
-    /** Live-only: the spend ledger surfaced on the result — unknowns are null, never guessed.
+    /** Live-only: the spend ledger surfaced on the result. Unknowns are null, never guessed.
      *  Lets a programmatic caller read spend without parsing the bundle. */
     cost?: {
         knownTotalUsd: number;
@@ -173,7 +171,7 @@ export interface TerminalProductLabResult extends AutomaticAnalysisResult {
     observer?: ObserverResult;
     warnings: string[];
     error?: {
-        code: "HUMANISH_LAB_ANALYSIS_INVALID" | "HUMANISH_LAB_TASKS_UNSUPPORTED" | "HUMANISH_LAB_OPTION_UNSUPPORTED" | "HUMANISH_TERMINAL_LAB_FAILED" | "HUMANISH_TERMINAL_LAB_ACTOR_UNSUPPORTED" | "HUMANISH_TERMINAL_LAB_SUBJECT_INVALID" | "HUMANISH_TERMINAL_LAB_KEYPLACEMENT_INVALID" | "HUMANISH_TERMINAL_LAB_RUNTIME_AUTH_MISSING" | "HUMANISH_TERMINAL_LAB_KEYS_MISSING" | "HUMANISH_TERMINAL_LAB_CAPS_MISSING" | "HUMANISH_TERMINAL_LAB_CAPS_INVALID" | "HUMANISH_TERMINAL_LAB_UNPRICED_CAP" | "HUMANISH_TERMINAL_LAB_CAPS_EXCEEDED" | "HUMANISH_TERMINAL_LAB_CREDENTIAL_DENIED" | "HUMANISH_TERMINAL_LAB_CLEANUP_UNPROVEN" | "HUMANISH_RUN_ID_IN_USE";
+        code: "HUMANISH_STUDY_ANALYSIS_INVALID" | "HUMANISH_STUDY_TASKS_UNSUPPORTED" | "HUMANISH_STUDY_OPTION_UNSUPPORTED" | "HUMANISH_TERMINAL_FAILED" | "HUMANISH_TERMINAL_ACTOR_UNSUPPORTED" | "HUMANISH_TERMINAL_SUBJECT_INVALID" | "HUMANISH_TERMINAL_KEYPLACEMENT_INVALID" | "HUMANISH_TERMINAL_RUNTIME_AUTH_MISSING" | "HUMANISH_TERMINAL_KEYS_MISSING" | "HUMANISH_TERMINAL_CAPS_MISSING" | "HUMANISH_TERMINAL_CAPS_INVALID" | "HUMANISH_TERMINAL_UNPRICED_CAP" | "HUMANISH_TERMINAL_CAPS_EXCEEDED" | "HUMANISH_TERMINAL_CREDENTIAL_DENIED" | "HUMANISH_TERMINAL_CLEANUP_UNPROVEN" | "HUMANISH_RUN_ID_IN_USE";
         message: string;
     };
 }
@@ -189,7 +187,7 @@ export interface CommandLogRecord {
     at: string;
     /** A public-safe label for the command (e.g. "codex-exec"); the full argv is bound by digest only. */
     label: string;
-    /** sha256-12 of the exact command string — pins "same recipe" without persisting it. */
+    /** sha256-12 of the exact command string. It pins "same recipe" without persisting it. */
     commandDigest: string;
     /** The env var names injected command-scoped (values never persisted): the credential evidence. */
     envNames: string[];
@@ -216,7 +214,7 @@ export interface InterventionRecord {
     inputDigest: string;
 }
 /**
- * One cost line of the spend ledger. The null discipline (issue #154, the cost/no-spend asks):
+ * One cost line of the spend ledger. The null discipline:
  * three distinct states are kept apart:
  *   - `usd: 0`     => known to be zero. A measured-and-zero spend (we metered this category and it
  *                     billed nothing). The no-spend proof may legitimately assert this is zero.
@@ -226,7 +224,7 @@ export interface InterventionRecord {
  *   - line absent  => not applicable to this route/run (n/a). The line simply does not appear in
  *                     `lines`. (The current route emits all four lines, so absence is reserved for
  *                     future routes that genuinely have no such category.)
- * `null` vs missing-key is the load-bearing distinction: a missing key means "this category does not
+ * `null` vs missing-key is the distinction that matters: a missing key means "this category does not
  * exist for this run"; a present key with `null` means "this category exists but we did not measure
  * it". A no-spend proof that claimed zero on a `null` line would claim more than it measured.
  */
@@ -238,7 +236,7 @@ export interface CostLine {
     /** How this line's value was established (provenance for the verifier + the human reviewer). */
     source: "provider-token-usage" | "no-spend-signal" | "operator-cap" | "unmeasured"
     /** Tokens were counted but no rate could price them, so `usd` stays null while the note
-     *  carries the measured token totals (#531). Distinct from "unmeasured", which means no
+     *  carries the measured token totals. Distinct from "unmeasured", which means no
      *  signal at all. */
      | "unpriced-token-usage";
     /** A short, public-safe note (never a secret value). */
@@ -260,8 +258,8 @@ export interface TerminalCostLedger {
     fullyMeasured: boolean;
 }
 /**
- * The no-spend proof, derived from the cost ledger (issue #154: "derived from a ledger, not
- * asserted"). It lists the known-zero lines it can vouch for and, separately, the unmeasured
+ * The no-spend proof, derived from the cost ledger.
+ * It lists the known-zero lines it can vouch for and, separately, the unmeasured
  * (null) lines it cannot vouch for. `satisfied` is true only when every known line is zero (a
  * known non-zero line fails it). A proof with unmeasured lines says it could not measure them;
  * it never claims zero on a line the ledger marks null.
@@ -274,14 +272,14 @@ export interface NoSpendProof {
     satisfied: boolean;
     /** Categories the ledger measured and found at (known) zero: the proof can vouch for these. */
     knownZeroLines: CostCategory[];
-    /** Categories the ledger measured with a known NON-zero spend (these break `satisfied`). */
+    /** Categories the ledger measured with a known non-zero spend (these break `satisfied`). */
     knownNonZeroLines: CostCategory[];
     /** Categories the ledger marks `null` (not measured). The proof lists these and does not claim
      *  they are zero; it claims only that this run could not measure them. */
     unmeasuredLines: CostCategory[];
     /** Sum of the known lines (== 0 for a satisfied no-spend run). */
     knownTotalUsd: number;
-    /** Human-readable honesty statement covering both what is proven and what is unmeasured. */
+    /** Human-readable statement covering both what is proven and what is unmeasured. */
     statement: string;
 }
 /** The persisted terminal-product ledgers artifact (substrate lifecycle + command log + interventions + cleanup + cost). */
@@ -302,7 +300,7 @@ export interface TerminalLedgers {
          *  this exact sandbox running/paused (still present); -1 = kill(id) itself failed, threw, or
          *  was unavailable (the server-side kill-on-timeout is the backstop). */
         remaining: number;
-        /** Honest, human-readable statement of which by-id signal produced `remaining`. */
+        /** Human-readable statement of which by-id signal produced `remaining`. */
         reason: string;
     };
     /** The spend ledger. Unknowns are `null`, never guessed; the no-spend proof

package/dist/routes/terminal/types.js

@@ -1,5 +1,6 @@
 import {} from "../../analysis/automatic-completion.js";
 import {} from "../../run/bundle.js";
+import {} from "../../run/study-result.js";
 /** Provider-neutral metadata constant: the route's non-secret tag (mirrors CUA_ACTOR_LAB_PROVIDER_METADATA). */
 export const TERMINAL_PRODUCT_LAB_PROVIDER_METADATA = {
     mode: "terminal-product-lab",
@@ -13,7 +14,7 @@ export const UPLOAD_MAX_BYTES = 64 * 1024 * 1024;
 /**
  * Server-side reclamation buffer past the codex command's own wall-clock (caps.maxMinutes) kill.
  * Shorter than the desktop routes' SANDBOX_TIMEOUT_BUFFER_MS (src/substrates/e2b/lifetime.ts):
- * when #158 set it, the terminal sandbox ran nothing but the codex command, and after its kill only
+ * when this buffer was set, the terminal sandbox ran nothing but the codex command, and after its kill only
  * teardown remained.
  */
 export const TERMINAL_SANDBOX_TIMEOUT_BUFFER_MS = 5 * 60_000;
@@ -31,6 +32,5 @@ export const TEXT_ITEMS_BYTES = 128 * 1024;
 // The longest stdout line the participant reader holds while waiting for its newline.
 export const PENDING_LINE_CHARS = 1024 * 1024;
 // Hard cap on the retained event-stream + transcript size, so a runaway agent cannot balloon the
-// bundle. Redaction runs PRE-truncation so a cut can never split a secret past the scrubber.
+// bundle. Redaction runs pre-truncation so a cut can never split a secret past the scrubber.
 export const MAX_TRANSCRIPT_BYTES = 512 * 1024;
-export const TERMINAL_PRODUCT_LAB_SCHEMA = "humanish.terminal-lab-result.v1";

package/dist/run/bundle-shape.js

@@ -156,9 +156,9 @@ function isDesktopBrowserEvidence(value) {
 }
 /** Short lowercase-hex content digest (digestText default is 12 chars; tolerate longer future digests). */
 const SCORER_DIGEST_PATTERN = /^[a-f0-9]{12,64}$/;
-/** Shape guard for RunScorerProvenance (#316), mirroring isRunSubjectProvenance: tolerated-absent in
+/** Shape guard for RunScorerProvenance, mirroring isRunSubjectProvenance: tolerated-absent in
  *  isRunBundle, well-shaped when present. Semantics (does the digest still match the file) are not a
- *  verify concern — the block is core-stamped evidence of what was loaded, not a re-execution proof. */
+ *  verify concern: the block is core-stamped evidence of what was loaded and proves no re-execution. */
 function isRunScorerProvenance(value) {
     return (isRecord(value) &&
         value.schema === "humanish.scorer-provenance.v1" &&
@@ -183,7 +183,7 @@ export function isRunAdapterScore(value) {
         (value.data === undefined || isRecord(value.data)));
 }
 // The local-tree archive content pin: sha256 hex, full 64 chars (unlike the repo's 16-char
-// display-digest convention -- this value is the provenance pin itself, persisted in full).
+// display-digest convention; this value is the provenance pin itself, persisted in full).
 export const ARCHIVE_SHA256_PATTERN = /^[a-f0-9]{64}$/;
 function isRunSubjectProvenance(value) {
     if (!isRecord(value))