humanish 0.106.1 → 0.107.0

package/dist/routes/terminal/session.js

@@ -1,4 +1,5 @@
 import { randomBytes, randomUUID } from "node:crypto";
+import { missingKeys } from "../../lab/requirements.js";
 import { declaredRuntimeProvenance } from "./runtime.js";
 import { digestText, redactText, scrubLiterals } from "../../evidence/redaction.js";
 import { describeMissingKeys } from "../../keys/key-resolution.js";
@@ -15,7 +16,7 @@ import { finishLiveTerminalSession } from "./live-finish.js";
  * a declared scorer. Returns the runtime key's command-scoped placement, or the refusal.
  */
 export function checkLiveTerminalMachine(plan, input, warnings) {
-    const env = input.hooks?.env ?? process.env;
+    const env = input.env ?? process.env;
     const { maxUsd } = plan.caps;
     // planTerminalLab refuses a positive maxUsd without a costProbe, so one is present here.
     if (maxUsd > 0) {
@@ -26,7 +27,8 @@ export function checkLiveTerminalMachine(plan, input, warnings) {
     if (!runtimeEnv.ok)
         return runtimeEnv;
     // The sandbox is created with E2B_API_KEY, so a missing key is refused before the run starts.
-    if (!env.E2B_API_KEY?.trim()) {
+    // The runtime key above is the plan's `key-one-of`; E2B_API_KEY is its only `key`.
+    if (missingKeys(plan.requirements, env).length > 0) {
         return {
             ok: false,
             code: "HUMANISH_TERMINAL_LAB_KEYS_MISSING",
@@ -46,9 +48,9 @@ export async function runLiveTerminalSession(args) {
     const { plan, input, cwd, warnings, failed, scope, runtimeEnv } = args;
     const { actor, product } = plan;
     const { maxUsd, maxMinutes } = plan.caps;
-    const hooks = input.hooks ?? {};
-    const env = hooks.env ?? process.env;
-    const now = hooks.now ?? (() => Date.now());
+    const deps = input.deps ?? {};
+    const env = input.env ?? process.env;
+    const now = deps.now ?? (() => Date.now());
     const nowIso = () => new Date(now()).toISOString();
     const prepared = await prepareLivePrompt({ plan, cwd, runtimeEnv, env, warnings });
     const { mission, physicalCwd, persona, composedPrompt, verdictNonce } = prepared;
@@ -61,7 +63,7 @@ export async function runLiveTerminalSession(args) {
         mode: "live",
         lab: plan.lab,
         renderReview: renderTerminalReviewMarkdown,
-        observer: { open: input.open === true, render: hooks.renderObserverFn },
+        observer: { open: input.open === true, render: deps.renderObserver },
         now,
     });
     if (!started.ok)
@@ -77,17 +79,18 @@ export async function runLiveTerminalSession(args) {
     const e2bApiKey = env.E2B_API_KEY?.trim() ?? "";
     // The ledgers + capture buffers, mutated through the live lifecycle.
     const recorder = createTerminalRecorder({ nowIso, sanitize, knownSecretValues });
-    const { version, model, reasoningEffort } = plan.runtime;
+    const { version, model, modelSource, reasoningEffort } = plan.runtime;
     const runtime = declaredRuntimeProvenance({
         ...(version === undefined ? {} : { version }),
-        ...(model === undefined ? {} : { model: sanitize(model) }),
+        model: sanitize(model),
+        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).`);
     const session = new LiveTerminalSandbox({
         plan,
         cwd,
-        hooks,
+        deps,
         now,
         nowIso,
         sanitize,
@@ -122,7 +125,6 @@ export async function runLiveTerminalSession(args) {
         plan,
         input,
         cwd,
-        hooks,
         sanitize,
         nowIso,
         knownSecretValues,
@@ -144,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 + the author mission ONLY (safety contract item 3).
+    // Compose the prompt from public surfaces and the author mission alone (safety contract item 3).
     // 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);
@@ -158,8 +160,8 @@ async function prepareLivePrompt(args) {
         verdictNonce,
     });
     const promptDigest = digestText(composedPrompt);
-    // --- Safety contract item 5: 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
+    // --- Safety contract item 5: 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
     // value past the scrubber.
@@ -177,7 +179,7 @@ async function prepareLivePrompt(args) {
         sanitize,
     };
 }
-/** Compose the live prompt: PUBLIC surfaces + author mission + the verdict-nonce marker contract. */
+/** Compose the live prompt: public surfaces + author mission + the verdict-nonce marker contract. */
 function composeLivePrompt(args) {
     return [
         args.personaLine,

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

@@ -1,6 +1,6 @@
-// Provider token accounting for the terminal lane (#531).
+// Provider token accounting for the terminal route (#531).
 //
-// THE GAP THIS CLOSES. A live terminal run reported `cost.lines.provider = null` with source
+// 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
@@ -10,11 +10,11 @@
 //   {"type":"turn.completed","usage":{"input_tokens":201536,"cached_input_tokens":170558,
 //    "cache_write_input_tokens":30951,"output_tokens":2283,"reasoning_output_tokens":902}}
 //
-// So the lane 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 lane has no
+// 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
 // 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
+// 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.
 const USAGE_RE = /"type"\s*:\s*"turn\.completed"\s*,\s*"usage"\s*:\s*(\{[^}\n]*\})/g;
 function num(value) {

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

@@ -1,5 +1,6 @@
 import type { ActorCompletionReason, ActorPersonaRef, ActorRuntimeProvenance, ActorStatus, ActorTokenUsage, ActorTrace } from "../../actors/contract.js";
 import type { LabRuntimeAuth } from "../../lab/types.js";
+import type { TerminalParticipantText } from "./participant-text.js";
 import { type CommandLogRecord, type TerminalEventRecord } from "./types.js";
 /**
  * Per-chunk sanitization cannot recognize a value split across deliveries. Redact those complete
@@ -10,9 +11,9 @@ export declare function scrubSplitKnownValues(events: TerminalEventRecord[], kno
 /** Redacted, ellipsis-prefixed tail of a captured stream/log for a message field. */
 export declare function tailOf(text: string): string;
 /**
- * Project the live terminal session into the provider-neutral humanish.actor-trace.v1 (lane
+ * 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
- * guard (a real run bumps them; a no-op is caught). No screenshots on this lane.
+ * guard (a real run bumps them; a no-op is caught). No screenshots on this route.
  */
 export declare function buildTerminalActorTrace(args: {
     persona: ActorPersonaRef;
@@ -31,10 +32,6 @@ export declare function buildTerminalActorTrace(args: {
     /** Runtime-turn aggregate usage parsed from the exec stream (#531). 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. */
+    participant: TerminalParticipantText;
 }): ActorTrace;
-/** Count distinct participant items in the retained Codex JSON stdout stream.
- * The caller supplies stdout only, after transport reconciliation and redaction.
- * Lifecycle, usage, launcher diagnostics, and nested command output are not activity.
- * Zero means no recognized item was retained, not that the participant succeeded.
- */
-export declare function countTerminalParticipantItems(stdout: string): number;

package/dist/routes/terminal/trace.js

@@ -1,6 +1,5 @@
 import { ACTOR_TRACE_SCHEMA, TERMINAL_AGENT_CAPABILITIES } from "../../actors/contract.js";
 import { redactedTail } from "../../evidence/redaction.js";
-import { normalizeLocalActorTranscript } from "../../run/terminal-contract.js";
 import { TAIL_CHARS } from "./types.js";
 /**
  * Per-chunk sanitization cannot recognize a value split across deliveries. Redact those complete
@@ -57,9 +56,9 @@ export function tailOf(text) {
     return redactedTail(text, TAIL_CHARS);
 }
 /**
- * Project the live terminal session into the provider-neutral humanish.actor-trace.v1 (lane
+ * 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
- * guard (a real run bumps them; a no-op is caught). No screenshots on this lane.
+ * guard (a real run bumps them; a no-op is caught). No screenshots on this route.
  */
 export function buildTerminalActorTrace(args) {
     const items = [
@@ -74,19 +73,7 @@ export function buildTerminalActorTrace(args) {
                 outputTail: args.transcriptTail,
             },
         })),
-        // One message item carrying the (already-redacted) transcript tail so the trace shows the agent
-        // narrated SOMETHING — the engagement signal the no-engagement guard reads.
-        ...(args.terminalEvents.length > 0
-            ? [
-                {
-                    id: "message-001",
-                    kind: "message",
-                    lifecycle: "completed",
-                    title: "agent terminal output",
-                    text: args.transcriptTail,
-                },
-            ]
-            : []),
+        ...args.participant.items,
     ];
     return {
         schema: ACTOR_TRACE_SCHEMA,
@@ -113,17 +100,13 @@ export function buildTerminalActorTrace(args) {
         ...(args.tokenUsage ? { tokenUsage: args.tokenUsage } : {}),
         counts: {
             commands: args.commandLog.length,
-            // Unlike the legacy transcript message/actions counts, this establishes
-            // actual runtime item activity. Stderr and bootstrap commands never count.
-            // Read the full retained stdout: its early items may no longer be in the tail.
-            runtimeParticipantItems: countTerminalParticipantItems(normalizeLocalActorTranscript(args.terminalEvents
-                .filter((event) => event.stream === "stdout")
-                .map((event) => event.chunk)
-                .join(""))),
-            // actions == executed commands; messages == 1 when the agent produced any output. The
-            // no-engagement guard (verify/actor.ts) reads these: a real run bumps them, a no-op is caught.
+            // Unlike the actions count, this establishes actual runtime item activity. Stderr and
+            // bootstrap commands never count.
+            runtimeParticipantItems: args.participant.participantItems,
+            // actions == executed commands, so the launcher command alone keeps the no-engagement guard
+            // (verify/actor.ts) satisfied; messages == the agent_message items in the stream.
             actions: args.commandLog.length,
-            messages: args.terminalEvents.length > 0 ? 1 : 0,
+            messages: args.participant.messages,
             terminalEvents: args.terminalEvents.length,
         },
         items,
@@ -132,41 +115,3 @@ export function buildTerminalActorTrace(args) {
             : TERMINAL_AGENT_CAPABILITIES,
     };
 }
-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);
-/** Count distinct participant items in the retained Codex JSON stdout stream.
- * The caller supplies stdout only, after transport reconciliation and redaction.
- * Lifecycle, usage, launcher diagnostics, and nested command output are not activity.
- * Zero means no recognized item was retained, not that the participant succeeded.
- */
-export function countTerminalParticipantItems(stdout) {
-    const ids = new Set();
-    for (const line of stdout.split("\n")) {
-        let event;
-        try {
-            event = JSON.parse(line);
-        }
-        catch {
-            continue;
-        }
-        if (!object(event) ||
-            typeof event.type !== "string" ||
-            !itemEvents.has(event.type) ||
-            !object(event.item))
-            continue;
-        const item = event.item;
-        if (!nonempty(item.id))
-            continue;
-        const active = ((item.type === "agent_message" || item.type === "reasoning") && nonempty(item.text)) ||
-            (item.type === "command_execution" && nonempty(item.command)) ||
-            (item.type === "web_search" &&
-                (nonempty(item.query) || (object(item.action) && nonempty(item.action.type)))) ||
-            (item.type === "file_change" &&
-                Array.isArray(item.changes) &&
-                item.changes.some((change) => object(change) && nonempty(change.path) && nonempty(change.kind)));
-        if (active)
-            ids.add(item.id);
-    }
-    return ids.size;
-}

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

@@ -1,15 +1,15 @@
-import { type AutomaticAnalysisHooks, type AutomaticAnalysisResult } from "../../analysis/automatic-completion.js";
+import type { LabEvent } from "../../lab/run-lab-events.js";
+import { type AutomaticAnalysisResult } from "../../analysis/automatic-completion.js";
 import type { ActorCompletionReason, ActorRuntimeProvenance, ActorStatus, ActorTrace } from "../../actors/contract.js";
-import { type RunLabProvenance } from "../../run/status.js";
 import type { CostCategory } from "../../run/terminal-contract.js";
 import type { RunScope } from "../../run/run.js";
 import type { buildRuntimeAuth } from "./credentials.js";
 import type { TerminalPlan } from "../../lab/plan-types.js";
+import type { LabDeps } from "../../lab/lab-deps.js";
 import type { LabConfig } from "../../lab/types.js";
-import { type E2BDesktopModule } from "../../substrates/e2b/sdk.js";
-import { renderObserver, type ObserverResult } from "../../observer/render.js";
+import type { ObserverResult } from "../../observer/render.js";
 import { type RunAdapterScore, type RunBundle, type RunFeedbackCandidate, type RunScorerProvenance } from "../../run/bundle.js";
-/** Provider-neutral metadata constant: the lane's non-secret tag (mirrors CUA_ACTOR_LAB_PROVIDER_METADATA). */
+/** 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";
     readonly tool: "humanish";
@@ -29,15 +29,19 @@ export declare const TERMINAL_SANDBOX_TIMEOUT_BUFFER_MS: number;
 export declare const DEFAULT_REQUEST_TIMEOUT_MS = 60000;
 export declare const PRODUCT_SETUP_TIMEOUT_MS = 300000;
 export declare const TAIL_CHARS = 2000;
+export declare const MESSAGE_CHARS = 8000;
+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
  * 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
+ * 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
- * to score the product attempt and derive feedback; it cannot mutate core's evidence (the lane
+ * 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).
  */
 export interface TerminalProductScoringContext {
@@ -48,8 +52,8 @@ export interface TerminalProductScoringContext {
     /** The persisted terminal-product ledgers (lifecycle/command/interventions/cleanup/cost/no-spend). */
     ledgers: TerminalLedgers;
     /**
-     * The FULL normalized transcript of the in-sandbox agent session — scrubbed (literal known
-     * values) then redacted (shape patterns) AT THE SOURCE, capped at MAX_TRANSCRIPT_BYTES, and
+     * The full normalized transcript of the in-sandbox agent session, scrubbed (literal known
+     * 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).
@@ -63,44 +67,27 @@ export interface TerminalProductScoringContext {
     runId: string;
 }
 /**
- * Library-level hooks: the DI seams that drive the full live path against a fake sandbox + mock
- * CLI at zero spend. The deterministic merge-gate test wires loadModule (a fake @e2b/desktop
- * module) + env (the operator key source) + now (an injected clock); the live rung uses none of
- * them (it loads the real module and reads the real environment).
+ * Known spend lines for the terminal cost ledger. Core has no product, media or payment spend
+ * signal, so it fills only the provider line from trace tokenUsage when present. A test injects
+ * known lines through `LabDeps.costProbe`; absent signals keep the null-discipline default.
  */
-export interface TerminalProductLabHooks {
-    /** Lazy-load the E2B module (tests inject a fake; default loadE2BDesktopModule). */
-    loadModule?: () => Promise<E2BDesktopModule>;
+export type TerminalCostProbe = (context: {
+    tokenCostUsd?: number;
+}) => Partial<Record<"product" | "media" | "payment" | "provider", CostLine>> | undefined;
+/** The scorer functions a terminal run calls: `RunLabOptions.scorer` without `deriveArtifacts`. */
+export interface TerminalScorer {
     /**
-     * The operator environment the lane reads the runtime key from (and from which it asserts no
-     * banned credential is requested). Defaults to process.env. The runtime key is injected ONLY
-     * into command-scoped `codex` env or an external header transform — NEVER Sandbox.create envs (the credential
-     * boundary); tests plant a fake key here and assert it never reaches metadata/global env/artifacts.
-     */
-    env?: Record<string, string | undefined>;
-    renderObserverFn?: typeof renderObserver;
-    /** Injected clock for deterministic timestamps + wall-clock arithmetic (tests only). */
-    now?: () => number;
-    /**
-     * Optional cost-ledger seam. Core has no product/media/payment spend signal, so it populates only
-     * the provider line from trace tokenUsage when present. Tests and adapters can inject KNOWN spend
-     * lines; absent signals retain the null-discipline default.
-     */
-    costProbe?: (context: {
-        tokenCostUsd?: number;
-    }) => Partial<Record<"product" | "media" | "payment" | "provider", CostLine>> | undefined;
-    /**
-     * 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 lane calls it
+     * 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
-     * `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. This is the SEAM the adopter's scorecard plugs
-     * into — NOT a built-in product scorer (that lives in the adopter's repo).
+     * `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
+     * scorers live in the adopter's repo, and core ships none.
      */
     score?: (ctx: TerminalProductScoringContext) => RunAdapterScore | Promise<RunAdapterScore>;
     /**
-     * Companion seam: derive product-feedback candidates from the same assembled evidence. The lane
+     * 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
@@ -111,28 +98,38 @@ export interface TerminalProductLabHooks {
     deriveFeedback?: (ctx: TerminalProductScoringContext) => RunFeedbackCandidate[] | Promise<RunFeedbackCandidate[]>;
 }
 export interface RunTerminalProductLabOptions {
-    automaticAnalysis?: AutomaticAnalysisHooks;
-    /** Which manifest produced this run (#455); threaded into the status record + bundle. */
-    lab?: RunLabProvenance;
+    /** Cancels post-run analysis only. */
+    analysisSignal?: AbortSignal;
+    /** Reports the analysis window to onEvent; built by normalizeRunLabOptions. */
+    emit?: (event: LabEvent) => void;
     cwd: string;
     config: LabConfig;
     /** Resolved upstream (scenario.mode + CLI override); defaults safe (dry-run). */
     dryRun: boolean;
     open?: boolean;
     runId?: string;
-    hooks?: TerminalProductLabHooks;
     /**
-     * Present ONLY when the scorer hooks were CONFIG-DECLARED and loaded by the CLI (#316). Its presence
-     * is the "declared" marker: a config-declared terminal scorer returning status:"fail" FLIPS
+     * The operator environment the route reads the runtime key from (and from which it asserts no
+     * banned credential is requested). Defaults to process.env. The runtime key goes only
+     * into command-scoped `codex` env or an external header transform, and never into Sandbox.create envs (the credential
+     * boundary); tests plant a fake key here and assert it never reaches metadata/global env/artifacts.
+     */
+    env?: Readonly<Record<string, string | undefined>>;
+    scorer?: TerminalScorer;
+    /** 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
+     * 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 `hooks` directly leaves this ABSENT and keeps today's purely
+     * entry. A library caller passing `scorer` leaves this absent and keeps today's purely
      * additive terminal behavior (verdict unchanged). Core-computed, never adopter-supplied.
      */
     scorerProvenance?: RunScorerProvenance;
 }
 export interface TerminalProductLabResult extends AutomaticAnalysisResult {
     schema: typeof TERMINAL_PRODUCT_LAB_SCHEMA;
-    /** True when the bundle verified AND (dry-run, or the live session reached a terminal verdict
+    /** 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;
@@ -150,7 +147,7 @@ export interface TerminalProductLabResult extends AutomaticAnalysisResult {
         completionReason: ActorCompletionReason;
         reason: string;
     };
-    /** Live-only: the sandbox lifecycle proof (the key/auth value is NEVER surfaced here). */
+    /** Live-only: the sandbox lifecycle proof (the key/auth value is never surfaced here). */
     sandbox?: {
         sandboxId: string;
         killed: boolean;
@@ -163,10 +160,10 @@ export interface TerminalProductLabResult extends AutomaticAnalysisResult {
     cost?: {
         knownTotalUsd: number;
         fullyMeasured: boolean;
-        /** Per-category USD: a known number, or null = NOT MEASURED (never coerced to 0). */
+        /** Per-category USD: a known number, or null = not measured (never coerced to 0). */
         lines: Record<"product" | "media" | "payment" | "provider", number | null>;
     };
-    /** Live-only: the no-spend proof DERIVED from the ledger. */
+    /** Live-only: the no-spend proof derived from the ledger. */
     noSpend?: {
         satisfied: boolean;
         maxUsd: number | null;
@@ -176,12 +173,7 @@ export interface TerminalProductLabResult extends AutomaticAnalysisResult {
     observer?: ObserverResult;
     warnings: string[];
     error?: {
-        /**
-         * HUMANISH_TERMINAL_AGENT_NOT_IMPLEMENTED is deprecated and no longer produced: the terminal
-         * agent runs only inside this route, and its fail-closed direct runner is gone. That code
-         * goes in the next minor.
-         */
-        code: "HUMANISH_LAB_ANALYSIS_INVALID" | "HUMANISH_LAB_TASKS_UNSUPPORTED" | "HUMANISH_LAB_OPTION_CONFLICT" | "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" | "HUMANISH_TERMINAL_AGENT_NOT_IMPLEMENTED";
+        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";
         message: string;
     };
 }
@@ -192,14 +184,14 @@ export interface LifecycleRecord {
     /** Redacted+scrubbed before persisting (it never carries a secret, but the harness never trusts that). */
     message: string;
 }
-/** Command-log ledger entry: which command ran, with what exit/duration (NEVER its env values). */
+/** Command-log ledger entry: which command ran, with what exit/duration (never its env values). */
 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. */
     commandDigest: string;
-    /** The env var NAMES injected command-scoped (values NEVER persisted) — the credential evidence. */
+    /** The env var names injected command-scoped (values never persisted): the credential evidence. */
     envNames: string[];
     exitCode?: number;
     timedOut?: boolean;
@@ -209,12 +201,12 @@ export interface CommandLogRecord {
 export interface TerminalEventRecord {
     at: string;
     stream: "stdout" | "stderr";
-    /** ALREADY scrubbed (literal known values) THEN redacted (shape patterns) at the source. */
+    /** Already scrubbed (literal known values), then redacted (shape patterns) at the source. */
     chunk: string;
 }
 /**
- * One operator intervention (assisted-input event). The current route ships NO assisted-input
- * path, so this ledger is ALWAYS empty — but always PRESENT (the safety contract: empty-present is
+ * One operator intervention (assisted-input event). The current route ships no assisted-input
+ * path, so this ledger is always empty, and always present (the safety contract: empty-present is
  * the contract, an absent ledger fails verify). A future assisted path can fill this shape.
  */
 export interface InterventionRecord {
@@ -224,28 +216,28 @@ export interface InterventionRecord {
     inputDigest: string;
 }
 /**
- * One cost line of the spend ledger. THE NULL DISCIPLINE (issue #154, the cost/no-spend asks):
- * three distinct states are crisply modeled and NEVER conflated —
- *   - `usd: 0`     => KNOWN to be zero. A measured-and-zero spend (we metered this category and it
+ * One cost line of the spend ledger. The null discipline (issue #154, the cost/no-spend asks):
+ * 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.
- *   - `usd: null`  => NOT MEASURED. This run carries no spend signal for the category. `null` is
+ *   - `usd: null`  => not measured. This run carries no spend signal for the category. `null` is
  *                     written explicitly (never undefined-omitted, never guessed to 0). The no-spend
- *                     proof must list this line as UNMEASURED and must NOT claim it is zero.
- *   - line ABSENT  => NOT APPLICABLE to this lane/run (n/a). The line simply does not appear in
+ *                     proof must list this line as unmeasured and must not claim it is zero.
+ *   - 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 lanes that genuinely have no such category.)
+ *                     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
  * 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.
  */
 export interface CostLine {
-    /** known zero (0) | not measured (null). The key is ALWAYS present when the line is applicable. */
+    /** known zero (0) | not measured (null). The key is always present when the line is applicable. */
     usd: number | null;
     /** Optional billable-unit count, same discipline: a known count, or null = not measured. */
     count?: number | null;
     /** 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
+    /** 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
      *  signal at all. */
      | "unpriced-token-usage";
@@ -253,39 +245,39 @@ export interface CostLine {
     note: string;
 }
 /**
- * The spend ledger (a block of `TerminalLedgers`). The no-spend PROOF is DERIVED from this — never
- * asserted independently. Every applicable category appears as a line; unknowns are `null`.
+ * The spend ledger (a block of `TerminalLedgers`). The no-spend proof is derived from this and
+ * never asserted independently. Every applicable category appears as a line; unknowns are `null`.
  */
 export interface TerminalCostLedger {
     schema: "humanish.terminal-cost-ledger.v1";
-    /** USD currency unit (recorded explicitly so a future multi-currency lane is unambiguous). */
+    /** USD currency unit (recorded explicitly so a future multi-currency route is unambiguous). */
     currency: "usd";
     lines: Record<CostCategory, CostLine>;
-    /** Sum of the KNOWN (non-null) lines. null lines contribute NOTHING and are NOT guessed as 0. */
+    /** Sum of the known (non-null) lines. Null lines contribute nothing and are never guessed as 0. */
     knownTotalUsd: number;
-    /** True when every applicable line is measured (no null). When false, knownTotalUsd is a LOWER
-     *  bound, not the full spend — the no-spend proof says so honestly. */
+    /** True when every applicable line is measured (no null). When false, knownTotalUsd is a lower
+     *  bound on the spend, and the no-spend proof says so. */
     fullyMeasured: boolean;
 }
 /**
- * The no-spend proof, DERIVED from the cost ledger (issue #154: "derived from a ledger, not
- * asserted"). It is honest about what it knows: 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); but a proof with unmeasured lines explicitly
- * says it could not measure them — it never claims zero on a line the ledger marks null.
+ * 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
+ * (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.
  */
 export interface NoSpendProof {
     schema: "humanish.terminal-no-spend-proof.v1";
     /** The maxUsd cap this proof was evaluated against (the no-spend scenario declares maxUsd: 0). */
     maxUsd: number | null;
-    /** True iff every KNOWN (measured) line is <= maxUsd (for a no-spend run, == 0). */
+    /** True iff every known (measured) line is <= maxUsd (for a no-spend run, == 0). */
     satisfied: boolean;
-    /** Categories the ledger MEASURED and found at (known) zero — the proof CAN vouch for these. */
+    /** 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`). */
     knownNonZeroLines: CostCategory[];
-    /** Categories the ledger marks `null` (NOT MEASURED). The proof explicitly lists these and does
-     *  NOT claim they are zero — it claims only that this run could not measure them. */
+    /** 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;
@@ -298,25 +290,25 @@ export interface TerminalLedgers {
     runtime?: ActorRuntimeProvenance;
     lifecycle: LifecycleRecord[];
     commandLog: CommandLogRecord[];
-    /** ALWAYS present; ALWAYS empty while no assisted-input path ships — the safety contract. */
+    /** Always present, and always empty while no assisted-input path ships (the safety contract). */
     interventions: InterventionRecord[];
     cleanup: {
         /** True when exact-id kill resolved, including the startup guard's acquired-instance kill
          *  (found-and-killed or already gone both prove absence; see `remaining`/`reason`). */
         killed: boolean;
-        /** BY-ID proof, NEVER derived from Sandbox.list: 0 = confirmed reclaimed (kill(id) RESOLVED
-         *  -- returned true "found and killed" OR false "404, exact id already gone" -- and, when the
+        /** By-id proof, never derived from Sandbox.list: 0 = confirmed reclaimed (kill(id) resolved,
+         *  returning true "found and killed" or false "404, exact id already gone", and, when the
          *  SDK exposes it, getInfo(id) did not report a live sandbox); 1 = getInfo(id) still reports
-         *  this exact sandbox running/paused (NOT reclaimed); -1 = kill(id) itself failed, threw, or
+         *  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`. */
         reason: string;
     };
     /** The spend ledger. Unknowns are `null`, never guessed; the no-spend proof
-     *  below is DERIVED from it. */
+     *  below is derived from it. */
     cost: TerminalCostLedger;
-    /** The no-spend proof DERIVED from `cost`. Never an independent assertion. */
+    /** The no-spend proof derived from `cost`. Never an independent assertion. */
     noSpendProof: NoSpendProof;
 }
 /** What a terminal run takes besides its plan. The plan carries the config, dry run and lab. */