humanish 0.107.0 → 0.109.0

package/dist/actors/computer-use/openai-wire.js

@@ -11,7 +11,7 @@
 export function asRecord(value) {
     return typeof value === "object" && value !== null ? value : {};
 }
-function asArray(value) {
+export function asArray(value) {
     return Array.isArray(value) ? value : [];
 }
 function asNumber(value) {
@@ -165,9 +165,9 @@ export function parseOpenAiResponse(raw) {
                 const callId = optionalString(item.call_id);
                 if (callId !== undefined)
                     callIds.push(callId);
-                // The live Responses API returns the actions as an ARRAY (`item.actions`); a single
-                // computer_call can carry several. (An older/alt shape used a singular `item.action` —
-                // supported as a fallback.) Reading only `item.action` silently dropped EVERY action,
+                // The live Responses API returns the actions as an array (`item.actions`); a single
+                // computer_call can carry several. (An older/alt shape used a singular `item.action`,
+                // supported as a fallback.) Reading only `item.action` silently dropped every action,
                 // which made the loop see zero actions and stop on a false `goal_satisfied`.
                 const rawActions = Array.isArray(item.actions)
                     ? item.actions
@@ -209,9 +209,9 @@ export function parseOpenAiResponse(raw) {
     // Of the input tokens, how many the provider served from its prompt cache. This loop threads
     // state with previous_response_id and re-sends a growing warm prefix every turn, so most input on
     // a long session is a cache hit billed at a fraction of the full rate. Not reading it made every
-    // cost line materially overstate the bill (#391).
+    // cost line materially overstate the bill.
     const usageCachedInput = optionalNumber(asRecord(usageRecord.input_tokens_details).cached_tokens);
-    // GPT-5.6+ bills cache WRITES (1.25x input) and reports them here; older models omit the field.
+    // GPT-5.6+ bills cache writes (1.25x input) and reports them here; older models omit the field.
     const usageCacheWriteInput = optionalNumber(asRecord(usageRecord.input_tokens_details).cache_write_tokens);
     const usage = usageInput === undefined && usageOutput === undefined
         ? undefined
@@ -253,12 +253,12 @@ function sharedRequestFields(ctx) {
         // instructions, a provider that does not fully retain prior state can drift
         // into asking the operator what to do.
         instructions: ctx.instructions,
-        // The Responses API `computer` tool takes no display/environment fields — the model infers
+        // The Responses API `computer` tool takes no display/environment fields; the model infers
         // resolution from the screenshots it is sent. (Sending display_* returns a 400
         // "Unknown parameter tools[0].display_width", confirmed against the live API 2026-06.)
         tools: [{ type: "computer" }],
         truncation: "auto",
-        // `summary` asks for the provider-SANCTIONED reasoning summary items (#427) — the
+        // `summary` asks for the provider-sanctioned reasoning summary items; the
         // capture side never scrapes or reconstructs raw chain-of-thought. Parsed by
         // parseOpenAiResponse into turn.reasoning; the loop records them as redacted
         // `kind: "reasoning"` trace items.
@@ -267,6 +267,7 @@ function sharedRequestFields(ctx) {
             ...(ctx.reasoningSummary === undefined ? {} : { summary: ctx.reasoningSummary }),
         },
         ...(ctx.safetyIdentifier === undefined ? {} : { safety_identifier: ctx.safetyIdentifier }),
+        ...(ctx.stateless === true ? { store: false, include: ["reasoning.encrypted_content"] } : {}),
     };
 }
 /**
@@ -284,32 +285,35 @@ export function buildInitialRequest(ctx, screenshot) {
     const maxOutputTokens = Math.min(ctx.maxOutputTokens ?? FIRST_TURN_OUTPUT_LIMIT, FIRST_TURN_OUTPUT_LIMIT);
     return {
         ...sharedRequestFields({ ...ctx, maxOutputTokens }),
-        input: [
-            {
-                role: "user",
-                content: [
-                    { type: "input_text", text: ctx.instructions },
-                    ...(screenshot === undefined
-                        ? []
-                        : [
-                            {
-                                type: "input_image",
-                                image_url: `data:image/png;base64,${screenshot.toString("base64")}`,
-                            },
-                        ]),
-                ],
-            },
-        ],
+        input: [openingMessage(ctx.instructions, screenshot)],
     };
 }
+/** One input message, read as the words of `sender`: the user, the developer, or the model itself. */
+export function inputMessage(sender, content) {
+    return { role: sender, content: [...content] };
+}
+/** The first request's only input item: the instructions and, when there is one, the first screen. */
+export function openingMessage(instructions, screenshot) {
+    return inputMessage("user", [
+        { type: "input_text", text: instructions },
+        ...(screenshot === undefined
+            ? []
+            : [
+                {
+                    type: "input_image",
+                    image_url: `data:image/png;base64,${screenshot.toString("base64")}`,
+                },
+            ]),
+    ]);
+}
 /**
  * Build one computer_call_output for a pending call id, carrying the latest
  * screenshot as an inline data URL. Acknowledged safety checks (if any) are
  * echoed back so the model can proceed past a check the harness approved.
  *
  * The screenshot param is `Buffer | undefined` because CuaObservation.screenshot is now
- * optional (a non-vision executor omits it). This provider is a VISION model (it sets
- * requiresFrame), so a missing frame is a hard error here — defense-in-depth: the loop's
+ * optional (a non-vision executor omits it). This provider is a vision model (it sets
+ * requiresFrame), so a missing frame is a hard error here as defense-in-depth: the loop's
  * per-turn requiresFrame guard already fails closed before this is reached, but throwing keeps
  * the mapper self-validating and isolable.
  */
@@ -335,19 +339,17 @@ export function buildCallOutput(callId, screenshot, acknowledged) {
             : {}),
     };
 }
-// Turn an optional context-hint string into an input item array (or empty).
-function hintItems(contextHint) {
-    return contextHint
-        ? [{ role: "user", content: [{ type: "input_text", text: contextHint }] }]
-        : [];
+/** An optional context hint as input items (none when there is no hint). */
+export function hintItems(contextHint) {
+    return contextHint ? [inputMessage("user", [{ type: "input_text", text: contextHint }])] : [];
 }
 /**
  * Build a continuation request body. Two modes:
  *  - default: thread server-side state via previous_response_id and send only the
  *    new call outputs (plus an optional hint).
- *  - explicit-context (ZDR): no previous_response_id; the prior output items are
- *    re-sent inline ahead of the new call outputs so the model has full context
- *    without the server retaining any.
+ *  - explicit-context (ZDR): no previous_response_id; the carried conversation
+ *    (openai-context.ts) is sent inline ahead of the new call outputs, so the model
+ *    has the session without the server retaining any.
  */
 export function buildContinuationRequest(args) {
     const { ctx, previousResponseId, callOutputs, contextHint, explicitContextItems } = args;

package/dist/actors/computer-use/provider-error.d.ts

@@ -5,23 +5,23 @@ export declare const isCuaProviderFailurePhase: (value: unknown) => value is Cua
 declare const codes: readonly ["request_rejected", "unavailable", "busy", "refused", "invalid_response", "protocol_error", "timeout", "cancelled", "process_failed", "cleanup_unconfirmed"];
 export type CuaProviderErrorCode = (typeof codes)[number];
 /** Safe local classification. Never attach provider prose, stderr, paths or a raw cause. */
-export declare class CuaProviderError extends Error {
+export declare class ComputerUseProviderError extends Error {
     readonly code: CuaProviderErrorCode;
     readonly receipt: ProviderRequestReceipt;
     readonly usage?: ActorTokenUsage;
     readonly failurePhase?: CuaProviderFailurePhase;
     constructor(code: CuaProviderErrorCode, receipt: ProviderRequestReceipt, usage?: ActorTokenUsage, failurePhase?: CuaProviderFailurePhase);
 }
-export declare const isCuaProviderError: (value: unknown) => value is CuaProviderError;
+export declare const isComputerUseProviderError: (value: unknown) => value is ComputerUseProviderError;
 /**
  * The model provider refused the request under its usage policy (OpenAI `invalid_prompt`). A
  * refusal is the provider's decision about this prompt, so it is not a harness fault, and sending
  * the same prompt again is not a recovery path. `providerCode` is the provider's identifier only;
  * the provider's message can echo the prompt and is never attached.
  */
-export declare class CuaPromptRefusedError extends Error {
+export declare class ComputerUsePromptRefusedError extends Error {
     readonly providerCode: string;
     constructor(provider: string, providerCode: string);
 }
-export declare const isCuaPromptRefusedError: (value: unknown) => value is CuaPromptRefusedError;
+export declare const isComputerUsePromptRefusedError: (value: unknown) => value is ComputerUsePromptRefusedError;
 export {};

package/dist/actors/computer-use/provider-error.js

@@ -24,7 +24,7 @@ const codes = Object.freeze([
 ]);
 const errors = new WeakSet();
 /** Safe local classification. Never attach provider prose, stderr, paths or a raw cause. */
-export class CuaProviderError extends Error {
+export class ComputerUseProviderError extends Error {
     code;
     receipt;
     usage;
@@ -50,7 +50,7 @@ export class CuaProviderError extends Error {
             throw new TypeError("Invalid participant provider error declaration.");
         }
         super(`Participant provider: ${code}`);
-        this.name = "CuaProviderError";
+        this.name = "ComputerUseProviderError";
         this.code = code;
         this.receipt = Object.freeze({
             dispatched: receipt.dispatched,
@@ -66,7 +66,7 @@ export class CuaProviderError extends Error {
         errors.add(this);
     }
 }
-export const isCuaProviderError = (value) => typeof value === "object" && value !== null && errors.has(value);
+export const isComputerUseProviderError = (value) => typeof value === "object" && value !== null && errors.has(value);
 const refusals = new WeakSet();
 /**
  * The model provider refused the request under its usage policy (OpenAI `invalid_prompt`). A
@@ -74,13 +74,13 @@ const refusals = new WeakSet();
  * the same prompt again is not a recovery path. `providerCode` is the provider's identifier only;
  * the provider's message can echo the prompt and is never attached.
  */
-export class CuaPromptRefusedError extends Error {
+export class ComputerUsePromptRefusedError extends Error {
     providerCode;
     constructor(provider, providerCode) {
         super(`${provider} refused the prompt under its usage policy (${providerCode})`);
-        this.name = "CuaPromptRefusedError";
+        this.name = "ComputerUsePromptRefusedError";
         this.providerCode = providerCode;
         refusals.add(this);
     }
 }
-export const isCuaPromptRefusedError = (value) => typeof value === "object" && value !== null && refusals.has(value);
+export const isComputerUsePromptRefusedError = (value) => typeof value === "object" && value !== null && refusals.has(value);

package/dist/actors/contract.d.ts

@@ -1,35 +1,35 @@
 import type { AffordanceUse } from "./affordance.js";
 import type { ActorEstimatedCost } from "../run/pricing.js";
-import type { TaskFunnel } from "../lab/tasks.js";
+import type { TaskFunnel } from "../study/tasks.js";
 import { type CuaProviderFailurePhase } from "./computer-use/provider-error.js";
 export declare const ACTOR_TRACE_SCHEMA = "humanish.actor-trace.v1";
 /**
- * How a session ended, from the point of view of the STUDY rather than the harness.
+ * How a session ended, from the point of view of the study rather than the harness.
  *
  * The distinction matters because two of these are participant outcomes and the rest are not. A
  * participant who abandons a task is the single most valuable thing a usability study produces, and
- * recording that as `failed` — as this type used to force — reads as the instrument breaking. See
+ * recording that as `failed` reads as the instrument breaking. See
  * docs/principles/three-roles.md.
  *
  * - `passed`      the participant reached the goal
- * - `abandoned`   the participant stopped trying. A FINDING, not a malfunction
+ * - `abandoned`   the participant stopped trying. A finding, not a malfunction
  * - `incomplete`  the session ended (time or budget) before the goal was reached
  * - `blocked`     the participant could not proceed: an approval the run could not give, or a
- *                 blocker they described in their own final words (#476)
+ *                 blocker they described in their own final words
  * - `timed_out`   the session hit its deadline with no productive activity at all
- * - `failed`      the HARNESS failed: a dead sandbox, a provider error, a broken artifact
+ * - `failed`      the harness failed: a dead sandbox, a provider error, a broken artifact
  */
 export declare const ACTOR_STATUSES: readonly ["passed", "abandoned", "incomplete", "blocked", "timed_out", "failed"];
 export type ActorStatus = (typeof ACTOR_STATUSES)[number];
 /**
- * What the PARTICIPANT said happened, in a field rather than a paragraph (#570). Providers whose
+ * What the participant said happened, in a field rather than a paragraph. Providers whose
  * reply is schema-constrained (the local-agent routes) fill it on their final turn; a free-text
  * provider leaves it absent and the route falls back to reading the closing message. `reached`:
  * the task is finished. `blocked`: something in the app stopped the participant. `not_reached`:
  * the participant stopped for another reason (gave up, ran out of ideas).
  */
 export type ParticipantDeclaredOutcome = "reached" | "not_reached" | "blocked";
-/** Statuses that describe what happened to a PARTICIPANT rather than a harness malfunction. Verify
+/** Statuses that describe what happened to a participant rather than a harness malfunction. Verify
  *  treats these as study results, so a run whose evidence is sound is not called untrustworthy just
  *  because a persona gave up. */
 export declare const PARTICIPANT_OUTCOME_STATUSES: readonly ActorStatus[];
@@ -62,11 +62,11 @@ export interface ActorTraceItem {
         redaction: "blurred" | "ocr_scrubbed" | "none";
     };
     text?: string;
-    /** When the item was recorded (ISO-8601), from the loop's injected clock. Additive
-     *  (#441): items from older bundles and non-stamping producers lack it, so every
+    /** When the item was recorded (ISO-8601), from the loop's injected clock. Additive:
+     *  items from older bundles and non-stamping producers lack it, so every
      *  consumer must treat absence as "timing unknown", never as t=0. */
     at?: string;
-    /** Structured pointer coordinates for click-like `ui_action` items (#441) — the
+    /** Structured pointer coordinates for click-like `ui_action` items: the
      *  recorded fact the Observer's pins previously re-parsed out of the title text. */
     coord?: {
         x: number;
@@ -83,13 +83,13 @@ export interface ActorCapabilities {
     inProcessTools: boolean;
     license: "open" | "source-available" | "proprietary";
     /**
-     * WHERE this actor's runtime key lives, per the placement rule (invariants-and-defaults.md):
-     * "keys live where the keyed process runs — and nowhere else." Registry metadata the engine
-     * enforces, NOT a code convention.
+     * Where this actor's runtime key lives, per the placement rule (invariants-and-defaults.md):
+     * "keys live where the keyed process runs, and nowhere else." Registry metadata the engine
+     * enforces, not a code convention.
      *   - "external" (the implicit default for every existing actor): the keyed process (e.g. a
-     *     computer-use provider loop) runs OUTSIDE any sandbox, so its key never enters one.
+     *     computer-use provider loop) runs outside any sandbox, so its key never enters one.
      *   - "in-sandbox-command-scoped": the keyed process is an agent-harness-under-test that runs
-     *     INSIDE the sandbox; its runtime key is injected ONLY into the per-command `envs` of that
+     *     inside the sandbox; its runtime key is injected only into the per-command `envs` of that
      *     invocation (never `Sandbox.create({envs})`, which is sandbox-global), the key is presumed
      *     exfiltratable, and the blast radius is bounded by key scoping + a spend budget.
      * Absent === "external". On the shipped terminal-product live route, the engine enforces this
@@ -115,18 +115,18 @@ export interface ActorPersonaRef {
 export interface ActorTokenUsage {
     input?: number;
     output?: number;
-    /** Of `input`, how many tokens were served from the provider's prompt cache. Optional and
-     *  HONESTLY ABSENT: a provider that does not report it leaves this undefined rather than
-     *  reporting 0, because 0 and "unknown" price very differently (#391). */
+    /** Of `input`, how many tokens were served from the provider's prompt cache. Optional. A
+     *  provider that does not report it leaves this undefined rather than
+     *  reporting 0, because 0 and "unknown" price very differently. */
     cachedInput?: number;
-    /** Of `input`, how many tokens were newly WRITTEN to the provider's prompt cache
+    /** Of `input`, how many tokens were newly written to the provider's prompt cache
      *  (OpenAI 5.6+ bills these at a surcharge and reports `cache_write_tokens`). Same
-     *  honestly-absent discipline as `cachedInput` (#334). */
+     *  absent-when-unreported rule as `cachedInput`. */
     cacheWriteInput?: number;
     /** Per model-inference request usage, in request order. One provider interaction can contain
      *  several inferences around native tool calls. A provider that re-prices whole requests past
      *  an input-size threshold can only be priced exactly from these sizes; totals cannot say which
-     *  requests crossed. Additive and honestly absent on producers that do not record it (#334). */
+     *  requests crossed. Additive, and absent on producers that do not record it. */
     turns?: Array<{
         input?: number;
         cachedInput?: number;
@@ -137,12 +137,13 @@ export interface ActorTokenUsage {
     costUsd?: number;
 }
 /**
- * Codex CLI releases a recorded account profile may name. Append-only: a release can leave the
- * launch lists in codex/qualified-versions.ts, but saved bundles naming it stay readable.
+ * The oldest Codex CLI release a recorded account profile may name. Readers accept every stable
+ * `MAJOR.MINOR.PATCH` release from it on, so a saved bundle stays readable whichever release
+ * recorded it; launch admission (codex/codex-admission.ts) alone decides what runs.
  */
-export declare const RECORDED_CODEX_CLI_VERSIONS: readonly ["0.154.0", "0.157.1", "0.159.2", "0.159.3", "0.160.0"];
-export type RecordedCodexCliVersion = (typeof RECORDED_CODEX_CLI_VERSIONS)[number];
-export declare function isRecordedCodexCliVersion(value: unknown): value is RecordedCodexCliVersion;
+export declare const RECORDED_CODEX_CLI_FLOOR = "0.154.0";
+/** A stable release at or above the floor. Parts compare as digit strings, exact at any length. */
+export declare function isRecordedCodexCliVersion(value: unknown): value is string;
 /** Requested execution profile; per-request verification is recorded separately. */
 export interface ActorExecutionProfile {
     schema: "humanish.actor-execution-profile.v1";
@@ -151,7 +152,8 @@ export interface ActorExecutionProfile {
     billing: "account-unknown";
     requestedModel: string;
     reasoningEffort: import("./reasoning-effort.js").ReasoningEffort;
-    cliVersion: RecordedCodexCliVersion;
+    /** A stable release at or above RECORDED_CODEX_CLI_FLOOR. */
+    cliVersion: string;
     toolPolicy: "restricted-codex-v1" | "codex-ui-tools-v1";
     participantSchema: "humanish.restricted-participant-turn.v1" | "humanish.codex-ui-tool.v1";
     memoryPolicy: "recent-eight-16k-v1" | "continuing-thread-v1";
@@ -200,6 +202,37 @@ export interface ActorRuntimeProvenance {
     /** Codex turn.completed aggregates requests; it cannot establish per-request pricing tiers. */
     usageGranularity: "runtime_turn";
 }
+/**
+ * How a provider carried the conversation between its requests. `threaded`: the provider's server
+ * kept it (OpenAI previous_response_id). `explicit_context`: the server kept none (a
+ * zero-data-retention org, or zeroDataRetention set), so each request carried it from the client
+ * within a token budget, with the oldest turns summarized as text once it passed the budget.
+ */
+export interface ActorConversation {
+    /** The mode of the session's last request. */
+    mode: "threaded" | "explicit_context";
+    /** Why the session used explicit_context: configured, or the org rejected server-side state. */
+    explicitReason?: "configured" | "zdr_rejection";
+    /** When a threaded session switched to explicit_context (ISO-8601), and on which request. */
+    switchedAt?: string;
+    switchedAtRequest?: number;
+    /**
+     * Earlier turns the latest explicit_context request no longer carried whole, to stay within the
+     * budget: written as lines of a text note, or only counted once the note reached its cap. Their
+     * screenshots were dropped. 0 when no explicit_context request summarized any.
+     */
+    summarizedTurns: number;
+    /**
+     * Per participant request, in order: its mode and, in explicit_context, what it carried and its
+     * estimated input. `tokenUsage.turns` has each request's billed input.
+     */
+    requests: Array<{
+        mode: "threaded" | "explicit_context";
+        carriedExchanges?: number;
+        carriedScreenshots?: number;
+        estimatedInputTokens?: number;
+    }>;
+}
 export interface ActorTrace {
     schema: typeof ACTOR_TRACE_SCHEMA;
     provider: string;
@@ -207,6 +240,8 @@ export interface ActorTrace {
     executionProfile?: ActorExecutionProfile;
     providerRequests?: ActorProviderRequest[];
     historyTurnsOmitted?: number;
+    /** How the provider carried the conversation; present for the OpenAI computer-use provider. */
+    conversation?: ActorConversation;
     runtime?: ActorRuntimeProvenance;
     protocol: ActorProtocol;
     lane: ActorRunKind;
@@ -231,15 +266,15 @@ export interface ActorTrace {
         model?: string;
     };
     /**
-     * ADDITIVE + OPTIONAL record of HOW the model was asked to run (humanish.model-settings.v1,
-     * #497). `ids.model` says which model; this says the reasoning effort the request actually
+     * Additive + optional record of how the model was asked to run (humanish.model-settings.v1).
+     * `ids.model` says which model; this says the reasoning effort the request actually
      * carried. Present on traces whose provider declares settings; absent everywhere else and on
      * every pre-existing bundle, and its absence is tolerated by verify.
      *
-     * It exists because effort was a silent constant: unreachable from a lab, so every run took the
-     * provider default. Effort is part of WHO the participant was, not of how the instrument was
+     * It exists because effort was a silent constant: unreachable from a study, so every run took the
+     * provider default. Effort is part of who the participant was, not of how the instrument was
      * tuned (docs/principles/actor-fidelity.md), so a trace that does not carry it is a result with
-     * half its sample description missing — and two such traces cannot honestly be compared.
+     * half its sample description missing, and two such traces cannot be compared.
      */
     modelSettings?: {
         reasoningEffort: string;
@@ -247,29 +282,29 @@ export interface ActorTrace {
     };
     counts: Record<string, number>;
     /**
-     * ADDITIVE + OPTIONAL affordance record (humanish.affordance-use.v1, #369): which KIND of route
-     * this actor took — pointer, keyboard, url-navigation, script-execution, devtools,
-     * browser-internal, observation — as per-class counts over the run's dispatched actions.
+     * Additive + optional affordance record (humanish.affordance-use.v1): which kind of route
+     * this actor took (pointer, keyboard, url-navigation, script-execution, devtools,
+     * browser-internal, observation), as per-class counts over the run's dispatched actions.
      * Present on computer-use traces that dispatched at least one action; absent elsewhere and on
      * every pre-existing bundle (its absence is tolerated by verify). The harness records the class
-     * and states NO verdict: whether a class is faithful depends on the population the study
+     * and states no verdict: whether a class is faithful depends on the population the study
      * declares, which is product semantics and belongs to the adopter's scorer. See
      * docs/principles/actor-fidelity.md.
      */
     affordanceUse?: AffordanceUse;
     /**
-     * ADDITIVE + OPTIONAL task funnel (humanish.task-funnel.v1, #414): how far this participant got
-     * through the lab's declared protocol, corroborated per task by observations rather than by the
-     * actor's own narration. Present only when the lab declared `tasks` and the session ran; absent
-     * on every pre-existing bundle and on dry-run contract bundles (honest absence — a funnel that
+     * Additive + optional task funnel (humanish.task-funnel.v1): how far this participant got
+     * through the study's declared protocol, corroborated per task by observations rather than by the
+     * actor's own narration. Present only when the study declared `tasks` and the session ran; absent
+     * on every pre-existing bundle and on dry-run contract bundles (a funnel that
      * was never measured is not an empty funnel). Its absence is tolerated by verify.
      */
     taskFunnel?: TaskFunnel;
     /**
-     * ADDITIVE + OPTIONAL (#570): the outcome the participant declared on its final turn, when its
+     * Additive + optional: the outcome the participant declared on its final turn, when its
      * provider's reply carries the field. Absent on free-text providers and on every older bundle.
      * The route reads this before it reads the closing paragraph; three regex patches in one month
-     * (#453, #549, #565) each fixed a false refusal and each left the next shape unhandled.
+     * each fixed a false refusal and each left the next shape unhandled.
      */
     declaredOutcome?: ParticipantDeclaredOutcome;
     /** Closing report after a harness-owned stop. Does not change task outcomes or permit actions. */
@@ -289,13 +324,13 @@ export interface ActorTrace {
      *  Known tokenUsage remains usable as a partial total. Absence is not proof of completeness. */
     interactionUsageIncomplete?: true;
     /**
-     * ADDITIVE + OPTIONAL token-derived cost ESTIMATE for this trace (humanish.actor-estimated-cost.v1).
-     * Distinct from `tokenUsage.costUsd`, which is RESERVED for a real provider-returned charge: a
+     * Additive + optional token-derived cost estimate for this trace (humanish.actor-estimated-cost.v1).
+     * Distinct from `tokenUsage.costUsd`, which is reserved for a real provider-returned charge: a
      * bare `costUsd` always means "the provider billed this", while `estimatedCost.estimatedCostUsd`
-     * is a rate-table multiply named honestly as an estimate (invariant 6). Absent on the Codex
+     * is a rate-table multiply named as an estimate, so the claim matches the mechanism. Absent on the Codex
      * app-server and scripted traces and on every pre-existing bundle; the terminal trace records a
      * null estimate. Its absence is tolerated by verify (fail-open on display). A `null`
-     * estimatedCostUsd is DECLARED ABSENT (unknown rate / no usage), never 0.
+     * estimatedCostUsd is declared absent (unknown rate / no usage), never 0.
      */
     estimatedCost?: ActorEstimatedCost;
     capabilities: ActorCapabilities;

package/dist/actors/contract.js

@@ -6,24 +6,24 @@ import { isCuaProviderFailurePhase, } from "./computer-use/provider-error.js";
 // The schema maps the providers and routes implemented by the closed first-party
 // registry. The broader Actor.run(input) and ApprovalPolicy contract remains
 // design-only and is intentionally absent from these runtime types. RedactionHooks
-// (src/evidence/redaction.ts) and ResolvedPersona (src/lab/persona.ts) ship in
+// (src/evidence/redaction.ts) and ResolvedPersona (src/study/persona.ts) ship in
 // their own modules.
 export const ACTOR_TRACE_SCHEMA = "humanish.actor-trace.v1";
 /**
- * How a session ended, from the point of view of the STUDY rather than the harness.
+ * How a session ended, from the point of view of the study rather than the harness.
  *
  * The distinction matters because two of these are participant outcomes and the rest are not. A
  * participant who abandons a task is the single most valuable thing a usability study produces, and
- * recording that as `failed` — as this type used to force — reads as the instrument breaking. See
+ * recording that as `failed` reads as the instrument breaking. See
  * docs/principles/three-roles.md.
  *
  * - `passed`      the participant reached the goal
- * - `abandoned`   the participant stopped trying. A FINDING, not a malfunction
+ * - `abandoned`   the participant stopped trying. A finding, not a malfunction
  * - `incomplete`  the session ended (time or budget) before the goal was reached
  * - `blocked`     the participant could not proceed: an approval the run could not give, or a
- *                 blocker they described in their own final words (#476)
+ *                 blocker they described in their own final words
  * - `timed_out`   the session hit its deadline with no productive activity at all
- * - `failed`      the HARNESS failed: a dead sandbox, a provider error, a broken artifact
+ * - `failed`      the harness failed: a dead sandbox, a provider error, a broken artifact
  */
 export const ACTOR_STATUSES = [
     "passed",
@@ -33,7 +33,7 @@ export const ACTOR_STATUSES = [
     "timed_out",
     "failed",
 ];
-/** Statuses that describe what happened to a PARTICIPANT rather than a harness malfunction. Verify
+/** Statuses that describe what happened to a participant rather than a harness malfunction. Verify
  *  treats these as study results, so a run whose evidence is sound is not called untrustworthy just
  *  because a persona gave up. */
 export const PARTICIPANT_OUTCOME_STATUSES = ["abandoned", "incomplete"];
@@ -55,18 +55,23 @@ export const ACTOR_STOP_CAUSES = [
     "usage_unreported",
 ];
 /**
- * Codex CLI releases a recorded account profile may name. Append-only: a release can leave the
- * launch lists in codex/qualified-versions.ts, but saved bundles naming it stay readable.
+ * The oldest Codex CLI release a recorded account profile may name. Readers accept every stable
+ * `MAJOR.MINOR.PATCH` release from it on, so a saved bundle stays readable whichever release
+ * recorded it; launch admission (codex/codex-admission.ts) alone decides what runs.
  */
-export const RECORDED_CODEX_CLI_VERSIONS = [
-    "0.154.0",
-    "0.157.1",
-    "0.159.2",
-    "0.159.3",
-    "0.160.0",
-];
+export const RECORDED_CODEX_CLI_FLOOR = "0.154.0";
+/** A stable release at or above the floor. Parts compare as digit strings, exact at any length. */
 export function isRecordedCodexCliVersion(value) {
-    return RECORDED_CODEX_CLI_VERSIONS.some((version) => version === value);
+    if (typeof value !== "string" || !/^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/.test(value))
+        return false;
+    const release = value.split("."), floor = RECORDED_CODEX_CLI_FLOOR.split(".");
+    for (const [index, part] of release.entries()) {
+        const order = part.length - floor[index].length ||
+            (part === floor[index] ? 0 : part > floor[index] ? 1 : -1);
+        if (order !== 0)
+            return order > 0;
+    }
+    return true;
 }
 /** Durable reader profile. Append new qualified profiles; never rewrite old evidence. */
 export function validActorExecutionProfile(value) {
@@ -174,7 +179,7 @@ export const CODEX_APP_SERVER_CAPABILITIES = {
     license: "open",
 };
 // Scripted browser driver (src/actors/scripted-browser/): deterministic Playwright step
-// replay against a loopback app. byoModel is false because there is NO model — the committed
+// replay against a loopback app. byoModel is false because there is no model: the committed
 // scenario steps are the whole behavior; tokenUsage on its traces records zeros by mechanism.
 export const SCRIPTED_BROWSER_CAPABILITIES = {
     headless: true,
@@ -188,12 +193,13 @@ export const SCRIPTED_BROWSER_CAPABILITIES = {
 };
 // Terminal agent (src/routes/terminal/route.ts): a real autonomous coding agent (Codex) discovering
 // and using a CLI/product from inside an E2B shell, capturing its non-interactive exec output as
-// a redacted event stream + normalized transcript. The "terminal" lane is the autonomous-agent
-// study lane (distinct from "code", the operator-machine Codex lanes). byoModel is false: the
-// agent runs its own model via the command-scoped runtime auth, not a humanish-supplied provider.
-// keyPlacement is "in-sandbox-command-scoped" — the load-bearing inversion of every existing
-// E2B route's external-key default (the agent is the keyed process and it runs INSIDE). The
-// terminal-product live route enforces the boundary before sandbox creation.
+// a redacted event stream + normalized transcript. The "terminal" run kind is the
+// autonomous-agent study run kind (distinct from "code", the operator-machine Codex
+// actors). byoModel is false: the agent runs its own model via the command-scoped runtime
+// auth, not a humanish-supplied provider. keyPlacement is "in-sandbox-command-scoped": the
+// inversion of every other E2B route's external-key default (the agent is the keyed process and it
+// runs inside the sandbox). The terminal-product live route enforces the boundary before sandbox
+// creation.
 export const TERMINAL_AGENT_CAPABILITIES = {
     headless: true,
     structuredTrace: true,

package/dist/actors/local-agent/claude-session.d.ts

@@ -34,7 +34,7 @@ export interface ClaudeSession {
 export declare function userMessage(text: string): JsonObject;
 /**
  * Start one Claude Code session and return a provider that spends it, one user message per
- * computer-use turn. Started EAGERLY (before the first screenshot) so the CLI's own boot is paid
+ * computer-use turn. Started eagerly (before the first screenshot) so the CLI's own boot is paid
  * while the sandbox is still settling rather than inside turn one.
  */
 export declare function startClaudeSession(options?: ClaudeSessionOptions): Promise<ClaudeSession>;