humanish 0.107.0 → 0.109.0

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
-// turn started cold. Measured on the same lab with the same credentials (n=1 each): one-shot,
+// 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 study 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";
@@ -22,7 +22,7 @@ import { mkdtemp, rm, unlink, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import path from "node:path";
 import readline from "node:readline";
-import { CuaProviderError } from "../computer-use/provider-error.js";
+import { ComputerUseProviderError } from "../computer-use/provider-error.js";
 import { declaredOutcomeOf, parseAgentJson, promptFor, toCuaActions, LOCAL_AGENT_CAPABILITIES, } from "./cli.js";
 /** How long Claude Code may take to acknowledge an interrupt before the session is ended. */
 const INTERRUPT_RECEIPT_TIMEOUT_MS = 5_000;
@@ -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. ` +
@@ -288,7 +289,7 @@ export async function startClaudeSession(options = {}) {
                 usageIncomplete = true;
                 if (error instanceof ClaudeSessionDesyncError) {
                     // The stream no longer pairs results with turns, so no later turn can trust it.
-                    throw new CuaProviderError("protocol_error", {
+                    throw new ComputerUseProviderError("protocol_error", {
                         dispatched: "unknown",
                         usageComplete: false,
                         cleanup: "unconfirmed",
@@ -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 {
@@ -49,7 +49,7 @@ export interface LocalAgentProviderOptions {
     timeoutMs?: number;
     /**
      * Recorded in the trace's model settings. Low by default: a computer-use run is sixty turns, and
-     * a high-effort answer per turn costs minutes. The lab can raise it.
+     * a high-effort answer per turn costs minutes. The study can raise it.
      */
     reasoningEffort?: ReasoningEffort;
     /** Model override passed to the CLI (`--model`). Absent = the CLI's own default. */
@@ -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 study 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 provider-declared reasoning-effort vocabulary, kept in its own module so the study 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 study. 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
+// subset a given model id accepts. So this module refuses to pretend: it validates that a study asked
+// 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.
+ * This guard is what lets humanish 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
- * replayer) must keep this signature; it is what lets the lab dispatch on capabilities, not ids.
+ * like the CUA shape; no separate toActorTrace). Any future scripted driver (e.g. a HAR
+ * replayer) must keep this signature; it is what lets humanish dispatch on capabilities.
  */
 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,31 +6,31 @@ 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.
+ * This guard is what lets humanish dispatch on capabilities rather than on hardcoded actor ids.
  */
 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
- * replayer) must keep this signature; it is what lets the lab dispatch on capabilities, not ids.
+ * like the CUA shape; no separate toActorTrace). Any future scripted driver (e.g. a HAR
+ * replayer) must keep this signature; it is what lets humanish dispatch on capabilities.
  */
 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)",
@@ -73,7 +74,7 @@ export const actorRegistry = {
     },
     // The ActorId names the terminal-product dispatch slot; the live route records the concrete
     // provider as "codex". keyPlacement "in-sandbox-command-scoped" is registry-declared and
-    // enforced by runTerminalProductLab before it creates a sandbox, which is where this actor runs.
+    // enforced by runTerminalProductStudy before it creates a sandbox, which is where this actor runs.
     "codex-exec": {
         id: "codex-exec",
         label: "Codex Exec (autonomous terminal agent, in-sandbox)",

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

@@ -10,12 +10,12 @@ export interface ScriptedBrowserSessionOptions {
     urlPolicy?: ScriptedBrowserEvidenceUrlPolicy;
     /** Parsed + validated by the backend (scenario.ref is consumed there, fail-closed). */
     journey: BrowserPersonaJourney;
-    /** ONE session per surface. */
+    /** 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 route). */
+     *  (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. */
+    /** Journey wall-clock budget in ms; the route passes execution.timeoutMs or 300_000. */
     timeoutMs: number;
     /** Absolute; the session writes screenshots/ and traces/<surface>.json beneath it. */
     artifactRoot: string;
@@ -30,20 +30,20 @@ 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. */
+/** Internal route seam: the run root is already prepared and must stay bound to that identity. */
 export declare function runScriptedBrowserSessionInPreparedRoot(options: ScriptedBrowserSessionOptions, preparedArtifactRoot: PreparedOutputRoot): Promise<ScriptedBrowserSessionResult>;

package/dist/actors/scripted-browser/actor.js

@@ -9,12 +9,12 @@
 // The step executor's `page` is typed as the narrow structural ScriptedPageLike instead of
 // playwright's Page (browserPersonaPageState already took { evaluate, url }; E2BDesktopLike is
 // the same seam pattern). playwright's real Page satisfies it; tests inject fakes and run
-// the REAL step executor at $0 with zero browser dependence. playwright-core stays the lazy
+// the real step executor at $0 with zero browser dependence. playwright-core stays the lazy
 // production default behind launchPlaywrightChromium.
 //
-// Spend posture: nothing in this module can spend provider money — no provider client is
+// Spend posture: nothing in this module can spend provider money: no provider client is
 // importable from this code path. tokenUsage on every projected trace records zeros as an
-// affirmative $0 declaration that is TRUE by mechanism.
+// affirmative $0 declaration that is true by mechanism.
 import { stat } from "node:fs/promises";
 import path from "node:path";
 import { CHROMIUM_EVIDENCE_HYGIENE_FLAGS } from "../../evidence/browser-hygiene.js";
@@ -24,7 +24,7 @@ import { ACTOR_TRACE_SCHEMA, SCRIPTED_BROWSER_CAPABILITIES, } from "../contract.
 import { buildBlockedBrowserPersonaSteps, buildBrowserTrace, captureBlockedStepScreenshot, compactBrowserError, executeBrowserPersonaStep, probeAppUrl, sanitizeBrowserEvidenceUrl, screenshotPathForBrowserStep, surfaceScreenshotPath, tracePathForBrowserSurface, } from "./steps.js";
 import { LOOPBACK_EVIDENCE_URL_POLICY, } from "./types.js";
 /** Production default: lazy playwright-core import + chromium.launch, exactly as the driver
- *  always did. Kept in ONE place so the optional peer is touched by exactly one code path. */
+ *  always did. Kept in one place so the optional peer is touched by exactly one code path. */
 async function launchPlaywrightChromium(args) {
     const { chromium } = await import("playwright-core");
     const browser = await chromium.launch({
@@ -50,26 +50,26 @@ class ScriptedJourneyTimeoutError extends Error {
     }
 }
 /**
- * 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 async function runScriptedBrowserSession(options) {
     assertScriptedSessionPathIds(options);
     const preparedArtifactRoot = await prepareSelectedOutputDirectory(process.cwd(), options.artifactRoot);
     return runScriptedBrowserSessionInPreparedRoot(options, preparedArtifactRoot);
 }
-/** Internal lab seam: the run root is already prepared and must stay bound to that identity. */
+/** Internal route seam: the run root is already prepared and must stay bound to that identity. */
 export async function runScriptedBrowserSessionInPreparedRoot(options, preparedArtifactRoot) {
     assertScriptedSessionPathIds(options);
     await prepareContainedOutputDirectory(preparedArtifactRoot, "screenshots");
@@ -107,7 +107,7 @@ export async function runScriptedBrowserSessionInPreparedRoot(options, preparedA
             trace,
         };
     };
-    // Launch FIRST: a browser that cannot start is a harness failure, never subject evidence.
+    // Launch first: a browser that cannot start is a harness failure, never subject evidence.
     let browser;
     try {
         browser = await launch({ browserCommand, timeoutMs: options.timeoutMs });
@@ -289,7 +289,7 @@ async function runScriptedJourney(args) {
     };
 }
 /** Race one step against the journey's remaining wall-clock budget. A hanging step rejects
- *  with the timeout error; the journey's catch path then records honest blocked steps. */
+ *  with the timeout error; the journey's catch path then records the remaining steps as blocked. */
 async function withJourneyDeadline(promise, deadline, timeoutMs) {
     const remaining = deadline - Date.now();
     if (remaining <= 0) {
@@ -353,7 +353,7 @@ async function persistScriptedFailureCapture(args) {
     };
 }
 /** Project one surface capture into humanish.actor-trace.v1. screenshotRefs are attached only
- *  for frames that actually exist on disk (honest counts; blocked-not-executed steps name a
+ *  for frames that actually exist on disk (so counts match disk; blocked-not-executed steps name a
  *  path that was never written). */
 async function projectScriptedActorTrace(args) {
     const writtenScreenshots = new Set();
@@ -371,7 +371,7 @@ async function projectScriptedActorTrace(args) {
     const items = args.capture.steps.map((step) => {
         const assertions = step.assertions ?? [];
         assertionCount += assertions.length;
-        const assertionLines = assertions.map((assertion) => `${assertion.id}: ${assertion.status} — ${assertion.reason}`);
+        const assertionLines = assertions.map((assertion) => `${assertion.id}: ${assertion.status} (${assertion.reason})`);
         return {
             id: step.id,
             kind: "ui_action",
@@ -401,7 +401,7 @@ async function projectScriptedActorTrace(args) {
         status: args.status,
         completionReason: args.completionReason,
         reason: redactText(args.reason),
-        // No session/model ids exist on a deterministic replay — absence declared by omission.
+        // No session/model ids exist on a deterministic replay; absence declared by omission.
         ids: {},
         counts: {
             steps: args.journey.steps.length,
@@ -412,7 +412,7 @@ async function projectScriptedActorTrace(args) {
             screenshots: writtenScreenshots.size,
         },
         items,
-        // Affirmative $0 declaration, TRUE by mechanism: no provider client is importable from
+        // Affirmative $0 declaration, true by mechanism: no provider client is importable from
         // this code path, so zeros are a recorded fact, not an estimate.
         tokenUsage: { input: 0, output: 0, total: 0, costUsd: 0 },
         capabilities: SCRIPTED_BROWSER_CAPABILITIES,