humanish 0.107.0 → 0.108.0

package/dist/actors/contract.d.ts

@@ -4,32 +4,32 @@ import type { TaskFunnel } from "../lab/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
+     * 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
+     * Additive + optional task funnel (humanish.task-funnel.v1): 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
+     * 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

@@ -10,20 +10,20 @@ import { isCuaProviderFailurePhase, } from "./computer-use/provider-error.js";
 // 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>;

package/dist/actors/local-agent/claude-session.js

@@ -1,20 +1,20 @@
-// ONE Claude Code process as the computer-use brain, instead of a fresh `claude -p` per turn.
+// One Claude Code process as the computer-use brain, instead of a fresh `claude -p` per turn.
 //
-// WHY (#520): `actors[].localAgent: codex` already runs through a persistent app-server thread,
-// so the participant remembers what it tried. `claude` spawned `claude -p` per turn, so EVERY
+// Why: `actors[].localAgent: codex` already runs through a persistent app-server thread,
+// so the participant remembers what it tried. `claude` spawned `claude -p` per turn, so every
 // turn started cold. Measured on the same lab with the same credentials (n=1 each): one-shot,
 // 188 actions over 90 turns and never finished; a thread that remembers, 21 actions over 8 turns
 // and goal_satisfied in 103 s. A participant that cannot remember trying the menu tries the menu
 // again. Until this existed, comparing the two agents measured the transport, not the model.
 //
-// THE MECHANISM, checked on this machine before it was written: `claude -p --input-format
+// The mechanism, checked on this machine before it was written: `claude -p --input-format
 // stream-json --output-format stream-json --verbose` is a bidirectional session over stdio. One
 // NDJSON `user` message in, a stream of `system` / `assistant` / `result` messages out, then it
 // waits for the next `user` message with the conversation intact. Two messages, one session id,
 // and a codeword given in the first turn was recalled in the second. `--allowedTools Read` keeps
 // the bound the one-shot version had: it looks at a picture, and that is all it can do.
 //
-// What this is NOT: a change to the loop, the executor, the trace, or the Observer. Only where
+// What this is not: a change to the loop, the executor, the trace, or the Observer. Only where
 // the next action comes from.
 import { spawn } from "node:child_process";
 import { randomUUID } from "node:crypto";
@@ -221,7 +221,7 @@ export function userMessage(text) {
 }
 /**
  * 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 async function startClaudeSession(options = {}) {
@@ -240,7 +240,7 @@ export async function startClaudeSession(options = {}) {
             "stream-json",
             // Required for stream-json output in -p mode; it is what makes the per-turn `result` visible.
             "--verbose",
-            // Read is the only tool it needs — the screenshot — and the only one it gets.
+            // Read is the only tool it needs (the screenshot) and the only one it gets.
             "--allowedTools",
             "Read",
             ...(options.model === undefined ? [] : ["--model", options.model]),
@@ -274,6 +274,7 @@ export async function startClaudeSession(options = {}) {
                 : `\n\nNote from the harness: ${request.contextHint}`;
             // The persona and the reply shape are in the conversation after turn one; re-sending them
             // every turn is what the one-shot version had to do, and it is most of what it cost.
+            // prose-check: model prompt (the participant model reads this, not a person)
             const text = turnIndex === 1
                 ? promptFor(request, shot)
                 : `Read the image file ${shot}. That is the CURRENT SCREEN, after your last actions took effect. ` +
@@ -316,7 +317,7 @@ export async function startClaudeSession(options = {}) {
 export function turnFromResult(result) {
     if (result.is_error === true ||
         (typeof result.subtype === "string" && result.subtype !== "success")) {
-        // A turn that errored is a BROKEN turn, never an empty one: an empty turn reads to the loop
+        // A turn that errored is a broken turn, never an empty one: an empty turn reads to the loop
         // as "the participant chose to do nothing".
         throw new Error(`Claude Code turn ended ${String(result.subtype ?? "in error")}: ${String(result.result ?? "").slice(0, 160)}`);
     }
@@ -354,7 +355,7 @@ export function turnFromResult(result) {
         ...(typeof parsed.message === "string" && parsed.message.length > 0
             ? { message: parsed.message }
             : {}),
-        // Claude Code reports its token counts per turn (#531). They are recorded as counts; the
+        // Claude Code reports its token counts per turn. They are recorded as counts; the
         // run's cost line stays "not priced", because a subscription is not a rate card.
         ...(input === undefined && output === undefined
             ? {}

package/dist/actors/local-agent/cli.d.ts

@@ -20,7 +20,7 @@ interface RawAction {
     ms?: number | null;
 }
 /**
- * Map the agent's answer onto the harness action vocabulary. Anything unrecognized is DROPPED
+ * Map the agent's answer onto the harness action vocabulary. Anything unrecognized is dropped
  * rather than guessed at: a coordinate we invented would be recorded as the participant's choice.
  */
 export declare function toCuaActions(raw: readonly RawAction[]): CuaAction[];
@@ -29,7 +29,7 @@ export declare function declaredOutcomeOf(value: unknown): ParticipantDeclaredOu
 /**
  * Pull the JSON object out of whatever the CLI printed: clean JSON, a Claude Code envelope, or an
  * answer wrapped in a ```json fence. A response with no object at all is a turn error, never an
- * empty turn — an empty turn would read to the loop as "the participant chose to do nothing".
+ * empty turn: an empty turn would read to the loop as "the participant chose to do nothing".
  */
 export declare function parseAgentJson(text: string): Record<string, unknown>;
 export interface SpawnResult {
@@ -74,7 +74,7 @@ export interface DetectedLocalAgent extends LocalAgentDescriptor {
     /** Resolved path to the binary. */
     binPath: string;
     /**
-     * Whether a credential file exists for it. EXISTENCE ONLY — never read, never parsed, never
+     * Whether a credential file exists for it. Existence only: never read, never parsed, never
      * reported beyond this boolean. Keyring storage may have no file at all.
      */
     credentialsPresent: boolean;
@@ -106,10 +106,12 @@ export declare function checkHostedCodexCompatibility(binPath: string, options?:
  *
  * This is the whole point of the feature at the surface: someone new does not have to go and make
  * an API key if the thing that can drive the study is already on their laptop. `doctor` says so,
- * and says it as a capability rather than a gate — a machine with no local agent is not broken,
+ * and says it as a capability rather than a gate: a machine with no local agent is not broken,
  * it just needs a key.
  */
 export declare function detectLocalAgents(options?: DetectLocalAgentsOptions): Promise<DetectedLocalAgent[]>;
-/** One line for `doctor`, in the register the other rows use. */
-export declare function localAgentDoctorMessage(found: readonly DetectedLocalAgent[]): string;
+/** Doctor's row when neither Codex nor Claude Code is installed. */
+export declare const NO_LOCAL_AGENT_MESSAGE = "no local coding agent found. openai-computer-use needs OPENAI_API_KEY; local-agent needs Codex or Claude Code installed and signed in. Hosted desktops also need E2B_API_KEY.";
+/** Doctor's row for one installed agent, in the register the other rows use. */
+export declare function localAgentDoctorMessage(agent: DetectedLocalAgent): string;
 export {};

package/dist/actors/local-agent/cli.js

@@ -11,22 +11,22 @@
 // The design started from a measurement: with every OPENAI_* variable unset, `codex exec --image`
 // returned a correct click on a real desktop screenshot and `claude -p` agreed within three pixels.
 //
-// WHAT THIS IS NOT: a way to avoid paying. Subscription usage consumes the operator's own plan,
-// which is why the cost line for these runs says "not priced" rather than $0 — $0 would be a lie.
+// What this is not: a way to avoid paying. Subscription usage consumes the operator's own plan,
+// which is why the cost line for these runs says "not priced": $0 would be a lie.
 // It is also not marketed as free API access, and it fails closed on a rate limit rather than
 // hammering a plan that was sold for interactive coding.
 //
-// WHERE IT IS SAFE, and this inverts the intuitive reading: the local agent only DECIDES. humanish
+// Where it is safe, and this inverts the intuitive reading: the local agent only decides. humanish
 // executes the action inside the desktop sandbox, so nothing the persona chooses ever runs on the
-// operator's machine. The same trick on the TERMINAL route would be the opposite — it would move
-// code execution out of the sandbox and onto a real disk — which is why this is a computer-use
+// operator's machine. The same trick on the terminal route would be the opposite: it would move
+// code execution out of the sandbox and onto a real disk, which is why this is a computer-use
 // provider and nothing else. Even so, these are coding agents with their own shell and file tools,
 // so each one is spawned tool-restricted, in a scratch directory, with a per-turn timeout.
 import { spawn } from "node:child_process";
 import { mkdtemp, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import path from "node:path";
-import { admittedCodexCliVersions, parseCodexCliVersion } from "../codex/qualified-versions.js";
+import { admitsCodexCliVersion, parseCodexCliVersion } from "../codex/codex-admission.js";
 import { restrictedCodexNpmTarget } from "../codex/restricted-executable.js";
 const LOCAL_AGENTS = [
     { id: "codex", bin: "codex", label: "Codex", credentialPath: ".codex/auth.json" },
@@ -38,7 +38,7 @@ const LOCAL_AGENTS = [
     },
 ];
 /**
- * Map the agent's answer onto the harness action vocabulary. Anything unrecognized is DROPPED
+ * Map the agent's answer onto the harness action vocabulary. Anything unrecognized is dropped
  * rather than guessed at: a coordinate we invented would be recorded as the participant's choice.
  */
 export function toCuaActions(raw) {
@@ -90,11 +90,11 @@ export function declaredOutcomeOf(value) {
 /**
  * Pull the JSON object out of whatever the CLI printed: clean JSON, a Claude Code envelope, or an
  * answer wrapped in a ```json fence. A response with no object at all is a turn error, never an
- * empty turn — an empty turn would read to the loop as "the participant chose to do nothing".
+ * empty turn: an empty turn would read to the loop as "the participant chose to do nothing".
  */
 export function parseAgentJson(text) {
-    // ORDER MATTERS, and a test caught it: Claude Code's envelope is valid JSON whose `result`
-    // STRING contains a ```json fence. Stripping fences first reached inside that string and
+    // Order matters, and a test caught it: Claude Code's envelope is valid JSON whose `result`
+    // string contains a ```json fence. Stripping fences first reached inside that string and
     // mangled the envelope. So: parse what we were given, and only go fence-hunting if it is not
     // already JSON.
     const attempts = [text.trim()];
@@ -167,6 +167,7 @@ export function promptFor(request, screenshotPath) {
     const shape = '{"reasoning":string,"done":boolean,"message":string|null,"outcome":"reached"|"not_reached"|"blocked"|null,' +
         '"actions":[{"kind":"click|double_click|type|keypress|scroll|wait|done",' +
         '"x":int|null,"y":int|null,"text":string|null,"keys":[string]|null,"ms":int|null}]}';
+    // prose-check: model prompt (the participant model reads this, not a person)
     return [
         request.instructions,
         "",
@@ -217,7 +218,7 @@ export function createLocalAgentProvider(options) {
                     "-p",
                     "--output-format",
                     "json",
-                    // Read is the only tool it needs — the screenshot — and the only one it gets.
+                    // Read is the only tool it needs (the screenshot) and the only one it gets.
                     "--allowedTools",
                     "Read",
                     ...(options.model === undefined ? [] : ["--model", options.model]),
@@ -339,9 +340,7 @@ export async function checkHostedCodexCompatibility(binPath, options = {}) {
         return "unsupported_platform";
     const result = await (options.probe ?? authProbe)(binPath, ["--version"], options.env ?? process.env).catch(() => ({ code: null, stdout: "", stderr: "" }));
     const version = parseCodexCliVersion(result.stdout);
-    return result.code === 0 &&
-        version !== undefined &&
-        admittedCodexCliVersions(platform, arch).some((admitted) => admitted === version)
+    return result.code === 0 && version !== undefined && admitsCodexCliVersion(version)
         ? "supported"
         : "unsupported_version";
 }
@@ -350,7 +349,7 @@ export async function checkHostedCodexCompatibility(binPath, options = {}) {
  *
  * This is the whole point of the feature at the surface: someone new does not have to go and make
  * an API key if the thing that can drive the study is already on their laptop. `doctor` says so,
- * and says it as a capability rather than a gate — a machine with no local agent is not broken,
+ * and says it as a capability rather than a gate: a machine with no local agent is not broken,
  * it just needs a key.
  */
 export async function detectLocalAgents(options = {}) {
@@ -397,17 +396,14 @@ export async function detectLocalAgents(options = {}) {
     }
     return found;
 }
-/** One line for `doctor`, in the register the other rows use. */
-export function localAgentDoctorMessage(found) {
-    if (found.length === 0) {
-        return "no local coding agent found — openai-computer-use needs OPENAI_API_KEY; local-agent needs Codex or Claude Code installed and authenticated. Hosted desktops also need E2B_API_KEY.";
-    }
-    return (found
-        .map((agent) => agent.authStatus === "authenticated"
-        ? `${agent.label} reports authenticated — actors[0].type: local-agent can use it instead of a provider API key; account access and limits are untested`
-        : agent.authStatus === "unauthenticated"
-            ? `${agent.label} reports not signed in — run \`${agent.id === "codex" ? "codex login" : "claude auth login"}\``
-            : `${agent.label} installed; authentication status could not be checked — run \`${agent.id === "codex" ? "codex login status" : "claude auth status"}\` and update the CLI if needed`)
-        .join(". ") +
-        ". Desktop and analysis requirements depend on the selected lab; run doctor --lab <lab> for its setup checks.");
+/** Doctor's row when neither Codex nor Claude Code is installed. */
+export const NO_LOCAL_AGENT_MESSAGE = "no local coding agent found. openai-computer-use needs OPENAI_API_KEY; local-agent needs Codex or Claude Code installed and signed in. Hosted desktops also need E2B_API_KEY.";
+/** Doctor's row for one installed agent, in the register the other rows use. */
+export function localAgentDoctorMessage(agent) {
+    if (agent.authStatus === "authenticated")
+        return `${agent.label} reports signed in; a lab with actors[0].type: local-agent can use it instead of a provider API key. Account access and limits are untested.`;
+    const status = agent.id === "codex" ? "codex login status" : "claude auth status";
+    return agent.authStatus === "unauthenticated"
+        ? `${agent.label} is installed and reports not signed in; run \`${agent.id === "codex" ? "codex login" : "claude auth login"}\``
+        : `${agent.label} is installed; its sign-in status could not be checked. Run \`${status}\`, and update the CLI if needed.`;
 }

package/dist/actors/local-agent/readiness.d.ts

@@ -1,7 +1,7 @@
 import { type LocalAgentId } from "./cli.js";
 /** Why a local-agent participant cannot run here. */
 export type LocalAgentRefusal = 
-/** The CLI is not on PATH. */
+/** The CLI is not on `PATH`. */
 {
     kind: "agent-missing";
     message: string;
@@ -11,7 +11,7 @@ export type LocalAgentRefusal =
     kind: "signin-required";
     message: string;
 }
-/** Hosted Codex on an unsupported platform or an unqualified CLI release. */
+/** Hosted Codex on an unsupported platform or a CLI release the launcher refuses. */
  | {
     kind: "unsupported";
     message: string;