humanish 0.106.1 → 0.108.0

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 lane 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;

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

@@ -1,8 +1,8 @@
 // Whether a local-agent participant can run on this machine before anything is acquired: its CLI
-// is on PATH and signed in, a hosted Codex CLI is a qualified release on a supported platform, and
+// is on `PATH` and signed in, a hosted Codex CLI is a qualified release on a supported platform, and
 // a ChatGPT-account Codex is not asked to enforce a dollar cap it has no price for. Each route maps
 // the refusal's kind to its own error code.
-import { describeQualifiedCodexCliVersions } from "../codex/qualified-versions.js";
+import { describeCodexCliAdmission } from "../codex/codex-admission.js";
 import { checkHostedCodexCompatibility, detectLocalAgents } from "./cli.js";
 export async function localAgentRefusal(args) {
     const { agent, env, caps } = args;
@@ -19,7 +19,7 @@ export async function localAgentRefusal(args) {
         return {
             kind: "signin-required",
             message: chosen.authStatus === "unauthenticated"
-                ? `${chosen.label} reports not signed in — run \`${chosen.id === "codex" ? "codex login" : "claude auth login"}\`, then retry.`
+                ? `${chosen.label} reports it is not signed in; run \`${chosen.id === "codex" ? "codex login" : "claude auth login"}\`, then retry.`
                 : `${chosen.label} authentication status could not be checked. Run \`${chosen.id === "codex" ? "codex login status" : "claude auth status"}\` and update the CLI if needed. No desktop was launched.`,
         };
     }
@@ -31,7 +31,7 @@ export async function localAgentRefusal(args) {
             kind: "unsupported",
             message: compatibility === "unsupported_platform"
                 ? `Hosted Codex participants require Linux or macOS on x64 or arm64. This host is ${process.platform}/${process.arch}; no desktop was launched.`
-                : `Hosted Codex participants require a qualified Codex CLI (${describeQualifiedCodexCliVersions()}). Run \`codex --version\` and install a qualified version before retrying; no desktop was launched.`,
+                : `Hosted Codex participants need a Codex CLI release humanish runs: ${describeCodexCliAdmission()}. Run \`humanish doctor\` for the release it found and the command that replaces it; no desktop was launched.`,
         };
     }
     if (chosen.billing === "account-unknown" &&

package/dist/actors/reasoning-effort.js

@@ -1,19 +1,19 @@
 // The provider-declared reasoning-effort vocabulary, kept in its own module so the lab schema and
 // the OpenAI provider can share it without the schema depending on a provider.
 //
-// WHY THIS EXISTS AT ALL: effort was reachable in the provider and unreachable from a lab. Every
-// computer-use run humanish had ever done was therefore the provider default — not by decision but
-// by omission (#497). Effort changes who the PARTICIPANT is, the same way a persona prompt does
+// Why this exists: effort was reachable in the provider and unreachable from a lab. Every
+// computer-use run humanish had ever done was therefore the provider default, not by decision but
+// by omission. Effort changes who the participant is, the same way a persona prompt does
 // (docs/principles/actor-fidelity.md: capability settings are recruiting decisions), so pinning it
 // invisibly meant every persona finding was really a finding about that persona at medium, with the
 // second half unsaid.
 //
-// SUPPORT IS MODEL-DEPENDENT. OpenAI documents the vocabulary below as the union across models and
+// Support is model-dependent. OpenAI documents the vocabulary below as the union across models and
 // states plainly that "supported values are model-dependent"; there is no offline way to know which
 // subset a given model id accepts. So this module refuses to pretend: it validates that a lab asked
-// for a REAL effort level, and a model that does not support the one it was asked for fails on the
+// for a real effort level, and a model that does not support the one it was asked for fails on the
 // first turn with the provider's own message rather than being silently downgraded. Silent
-// downgrade is the worse failure — it would record an effort the run did not actually use.
+// downgrade is the worse failure: it would record an effort the run did not actually use.
 /** The documented vocabulary, ordered from least to most reasoning. */
 export const REASONING_EFFORTS = [
     "none",

package/dist/actors/registry.d.ts

@@ -27,27 +27,27 @@ export interface TerminalActorDescriptor extends ActorDescriptorBase {
 }
 export type ActorDescriptor = CodexActorDescriptor | CuaActorDescriptor | ScriptedBrowserActorDescriptor | TerminalActorDescriptor;
 /**
- * REGISTRY CONTRACT: an actor whose capabilities include the "computer-use" lane is a
- * CuaActorDescriptor — its runSession takes CuaActorSessionOptions and returns a CuaLoopResult.
+ * Registry contract: an actor whose capabilities include the "computer-use" run kind is a
+ * CuaActorDescriptor: its runSession takes CuaActorSessionOptions and returns a CuaLoopResult.
  * Any future computer-use provider (e.g. stagehand-cua) must keep that session signature and add
  * its id to CuaActorDescriptor["id"], so code narrowed by this guard can still tell the ids apart.
  * This guard is what lets the lab dispatch on capabilities rather than on hardcoded actor ids.
  */
 export declare function isCuaActorDescriptor(descriptor: ActorDescriptor): descriptor is CuaActorDescriptor;
 /**
- * REGISTRY CONTRACT (mirror of isCuaActorDescriptor): an actor whose capabilities include the
- * "scripted-browser" lane IS a ScriptedBrowserActorDescriptor — runSession takes
+ * Registry contract (mirror of isCuaActorDescriptor): an actor whose capabilities include the
+ * "scripted-browser" run kind is a ScriptedBrowserActorDescriptor; runSession takes
  * ScriptedBrowserSessionOptions and returns ScriptedBrowserSessionResult (trace fully formed,
- * like the CUA shape — no separate toActorTrace). Any future scripted driver (e.g. a HAR
+ * like the CUA shape; no separate toActorTrace). Any future scripted driver (e.g. a HAR
  * replayer) must keep this signature; it is what lets the lab dispatch on capabilities, not ids.
  */
 export declare function isScriptedBrowserActorDescriptor(descriptor: ActorDescriptor): descriptor is ScriptedBrowserActorDescriptor;
 /**
- * REGISTRY CONTRACT (mirror of isCuaActorDescriptor / isScriptedBrowserActorDescriptor): an actor
- * whose capabilities include the "terminal" lane IS a TerminalActorDescriptor. This is the guard
- * the terminal-product lab uses for route selection and capability enforcement. The current
- * descriptor's direct runSession is intentionally unsupported; live execution is route-owned.
- * Any future terminal actor must declare keyPlacement honestly and integrate with that lifecycle.
+ * Registry contract (mirror of isCuaActorDescriptor / isScriptedBrowserActorDescriptor): an actor
+ * whose capabilities include the "terminal" run kind is a TerminalActorDescriptor. This is the
+ * guard the terminal-product route uses for route selection and capability enforcement. The current
+ * descriptor's direct runSession is intentionally unsupported; live execution is route-owned. Any
+ * future terminal actor must declare the keyPlacement it uses and integrate with that lifecycle.
  */
 export declare function isTerminalActorDescriptor(descriptor: ActorDescriptor): descriptor is TerminalActorDescriptor;
 export declare const actorRegistry: Record<ActorId, ActorDescriptor>;

package/dist/actors/registry.js

@@ -6,8 +6,8 @@ import { LOCAL_AGENT_CAPABILITIES } from "./local-agent/cli.js";
 import { OPENAI_RESPONSES_CU_CAPABILITIES } from "./computer-use/openai-provider.js";
 import { runScriptedBrowserSession, } from "./scripted-browser/actor.js";
 /**
- * REGISTRY CONTRACT: an actor whose capabilities include the "computer-use" lane is a
- * CuaActorDescriptor — its runSession takes CuaActorSessionOptions and returns a CuaLoopResult.
+ * Registry contract: an actor whose capabilities include the "computer-use" run kind is a
+ * CuaActorDescriptor: its runSession takes CuaActorSessionOptions and returns a CuaLoopResult.
  * Any future computer-use provider (e.g. stagehand-cua) must keep that session signature and add
  * its id to CuaActorDescriptor["id"], so code narrowed by this guard can still tell the ids apart.
  * This guard is what lets the lab dispatch on capabilities rather than on hardcoded actor ids.
@@ -16,21 +16,21 @@ export function isCuaActorDescriptor(descriptor) {
     return descriptor.capabilities.lanes.includes("computer-use");
 }
 /**
- * REGISTRY CONTRACT (mirror of isCuaActorDescriptor): an actor whose capabilities include the
- * "scripted-browser" lane IS a ScriptedBrowserActorDescriptor — runSession takes
+ * Registry contract (mirror of isCuaActorDescriptor): an actor whose capabilities include the
+ * "scripted-browser" run kind is a ScriptedBrowserActorDescriptor; runSession takes
  * ScriptedBrowserSessionOptions and returns ScriptedBrowserSessionResult (trace fully formed,
- * like the CUA shape — no separate toActorTrace). Any future scripted driver (e.g. a HAR
+ * like the CUA shape; no separate toActorTrace). Any future scripted driver (e.g. a HAR
  * replayer) must keep this signature; it is what lets the lab dispatch on capabilities, not ids.
  */
 export function isScriptedBrowserActorDescriptor(descriptor) {
     return descriptor.capabilities.lanes.includes("scripted-browser");
 }
 /**
- * REGISTRY CONTRACT (mirror of isCuaActorDescriptor / isScriptedBrowserActorDescriptor): an actor
- * whose capabilities include the "terminal" lane IS a TerminalActorDescriptor. This is the guard
- * the terminal-product lab uses for route selection and capability enforcement. The current
- * descriptor's direct runSession is intentionally unsupported; live execution is route-owned.
- * Any future terminal actor must declare keyPlacement honestly and integrate with that lifecycle.
+ * Registry contract (mirror of isCuaActorDescriptor / isScriptedBrowserActorDescriptor): an actor
+ * whose capabilities include the "terminal" run kind is a TerminalActorDescriptor. This is the
+ * guard the terminal-product route uses for route selection and capability enforcement. The current
+ * descriptor's direct runSession is intentionally unsupported; live execution is route-owned. Any
+ * future terminal actor must declare the keyPlacement it uses and integrate with that lifecycle.
  */
 export function isTerminalActorDescriptor(descriptor) {
     return descriptor.capabilities.lanes.includes("terminal");
@@ -43,13 +43,14 @@ export const actorRegistry = {
         runSession: runCodexAppServerSession,
         toActorTrace: codexResultToActorTrace,
     },
-    // The ActorId names the actor slot (keeps the lane open for a future stagehand-cua provider);
-    // the trace's `provider` string stays "openai-responses-cu" (the concrete model adapter).
-    // The operator's own signed-in coding agent as the computer-use brain (Codex on a ChatGPT plan,
-    // Claude Code on a Max plan). Same lane, same loop, same evidence — the only difference is where
-    // the next action comes from, which is exactly why it is a provider swap and not a new lane.
-    // It exists so someone new can watch a persona drive a real desktop without first going to find
-    // an API key; the machine they are on very often already has one of these signed in.
+    // The ActorId names the actor slot (keeps the slot open for a future stagehand-cua
+    // provider); the trace's `provider` string stays "openai-responses-cu" (the concrete model
+    // adapter). The operator's own signed-in coding agent as the computer-use brain (Codex on a
+    // ChatGPT plan, Claude Code on a Max plan). Same run kind, same loop, same evidence; the only
+    // difference is where the next action comes from, which is exactly why it is a provider swap and
+    // not a new run kind. It exists so someone new can watch a persona drive a real desktop
+    // without first going to find an API key; the machine they are on very often already has one of
+    // these signed in.
     "local-agent": {
         id: "local-agent",
         label: "Local coding agent (operator-authenticated)",

package/dist/actors/scripted-browser/actor.d.ts

@@ -10,10 +10,10 @@ export interface ScriptedBrowserSessionOptions {
     urlPolicy?: ScriptedBrowserEvidenceUrlPolicy;
     /** Parsed + validated by the backend (scenario.ref is consumed there, fail-closed). */
     journey: BrowserPersonaJourney;
-    /** ONE session per surface lane. */
+    /** One session per surface. */
     surface: BrowserSurface;
     /** id = actors[0].persona ?? "scripted-journey"; promptDigest = journey.sourceDigest prefix
-     *  (the step manifest IS the "prompt" — no model prompt exists on this lane). */
+     *  (the step manifest is the "prompt"; no model prompt exists on this route). */
     persona: ActorPersonaRef;
     /** Journey wall-clock budget in ms; the lab route passes execution.timeoutMs or 300_000. */
     timeoutMs: number;
@@ -30,19 +30,19 @@ export interface ScriptedBrowserSessionResult extends ActorSessionResult {
     capture: BrowserSurfaceCapture;
 }
 /**
- * Run the scripted journey for ONE surface and return native capture + ActorTrace projection.
+ * Run the scripted journey for one surface and return native capture + ActorTrace projection.
  *
  * Completion semantics (the contract the projection tests pin):
  * - every step executed, every assertion passed, HTTP probe ok -> passed / goal_satisfied
- *   (the scenario's expect blocks ARE the success predicate; a pass claims "the app still
+ *   (the scenario's expect blocks are the success predicate; a pass claims "the app still
  *   affords this exact journey", nothing about user behavior);
  * - a step's expectation evaluated false, a step target missing/unactionable, or an
- *   unreachable subject -> failed / step_failed (the harness executed faithfully; the SUBJECT
- *   did not satisfy the script — distinct from actor_error/harness_error);
+ *   unreachable subject -> failed / step_failed (the harness executed faithfully; the subject
+ *   did not satisfy the script, distinct from actor_error/harness_error);
  * - journey exceeded timeoutMs -> timed_out / timed_out;
  * - browser launch/import crash -> failed / harness_error;
- * - gave_up / blocked_approval are UNREACHABLE from this actor (no persona patience, no
- *   approvals exist on a deterministic replay) — asserted in tests.
+ * - gave_up / blocked_approval are unreachable from this actor (no persona patience, no
+ *   approvals exist on a deterministic replay), asserted in tests.
  */
 export declare function runScriptedBrowserSession(options: ScriptedBrowserSessionOptions): Promise<ScriptedBrowserSessionResult>;
 /** Internal lab seam: the run root is already prepared and must stay bound to that identity. */