humanish 0.106.1 → 0.108.0

package/dist/actors/codex/restricted-turn.js

@@ -1,17 +1,11 @@
 // One restricted Codex request's turn: the notifications and tool requests the app-server sends
 // while the turn runs. Each is checked against the tool policy, the turn's identity and the output
-// limits, and any violation stops the request's deadline with a refusal code.
+// limits, and any violation stops the request's deadline with a refusal code. A policy violation
+// goes through the session, which records it when the request can no longer report it.
 import { CODEX_MAX_OUTPUT_BYTES, CODEX_MAX_REQUEST_BYTES, codexRecord, restrictedCodexUsage, toolPolicyViolation, } from "./restricted-policy.js";
 import { RestrictedCodexStop, } from "./restricted-transport.js";
+import { ANALYST_ITEM_TYPES, ANALYST_RAW_ITEM_TYPES, KNOWN_CODEX_NOTIFICATIONS, PARTICIPANT_ITEM_TYPES, PARTICIPANT_RAW_ITEM_TYPES, itemPolicyOf, } from "./restricted-notifications.js";
 const rawCompactionTypes = ["compaction", "compaction_summary", "context_compaction"];
-const analystRawItemTypes = ["message", "reasoning", ...rawCompactionTypes];
-const participantRawItemTypes = [
-    ...analystRawItemTypes,
-    "custom_tool_call",
-    "custom_tool_call_output",
-    "function_call",
-    "function_call_output",
-];
 function hasScopedIdentity(method, params, threadId, turnId) {
     if (method === "turn/started" || method === "turn/completed") {
         const id = codexRecord(params.turn).id;
@@ -28,8 +22,10 @@ function hasScopedIdentity(method, params, threadId, turnId) {
             typeof params.turnId === "string" &&
             params.turnId.length > 0 &&
             (turnId === undefined || params.turnId === turnId));
+    // Before the turn's id is known, an event that names a turn waits in the early buffer, and
+    // handleTurnEvent checks it again against the acknowledged id.
     return ((params.threadId === undefined || params.threadId === threadId) &&
-        (params.turnId === undefined || params.turnId === turnId));
+        (params.turnId === undefined || turnId === undefined || params.turnId === turnId));
 }
 function usageDelta(total, baseline) {
     const delta = {
@@ -44,9 +40,10 @@ function usageDelta(total, baseline) {
         : null;
 }
 /**
- * Drain: every notification and tool request of one turn. Nothing is handled before `dispatched`;
- * events that arrive before turn/start's reply wait until acknowledge() and are then checked in
- * order. `finished` resolves only with a completed, validated final answer.
+ * Drain: every notification and tool request of one turn. Before `dispatched`, notifications go
+ * to the session's idle handler; events that arrive after dispatch but before turn/start's reply
+ * pass the item policy at once, then wait until acknowledge() and are checked in order.
+ * `finished` resolves only with a completed, validated final answer.
  */
 export class RestrictedCodexTurn {
     context;
@@ -70,7 +67,9 @@ export class RestrictedCodexTurn {
     constructor(context) {
         this.context = context;
         this.inferenceUsage = context.participant ? [] : null;
-        this.allowedRawItemTypes = context.participant ? participantRawItemTypes : analystRawItemTypes;
+        this.allowedRawItemTypes = context.participant
+            ? PARTICIPANT_RAW_ITEM_TYPES
+            : ANALYST_RAW_ITEM_TYPES;
         this.finished = new Promise((resolve) => {
             this.resolveFinished = resolve;
         });
@@ -94,8 +93,21 @@ export class RestrictedCodexTurn {
     }
     onNotification = (method, params) => {
         const { deadline } = this.context;
-        if (!this.dispatched)
+        if (!this.dispatched) {
+            this.context.idle(method, params);
             return;
+        }
+        // The single tool-policy check, first: an event that also fails the identity or delta checks
+        // below still has its items recorded. Tool requests must fail even if the turn-start
+        // acknowledgment is lost, and every event reaches handleTurnEvent only from here, directly or
+        // through the early buffer, so no event skips it. Every item is checked, whatever the method
+        // that carries it and wherever the schema nests it.
+        const items = itemPolicyOf(method, params, this.context.policy);
+        if (toolPolicyViolation(method, codexRecord(params.item), this.allowedRawItemTypes) ||
+            items === "violation") {
+            this.context.refuse("codex_tool_call");
+            return;
+        }
         if (!hasScopedIdentity(method, params, this.context.threadId(), this.turnId ?? this.earlyTurnId)) {
             deadline.stop("codex_protocol_error");
             return;
@@ -111,13 +123,8 @@ export class RestrictedCodexTurn {
                 return;
             }
         }
-        // The single tool-policy check. Tool requests must fail even if the turn-start
-        // acknowledgment is lost, and every event reaches handleTurnEvent only from here, directly
-        // or through the early buffer, so no event skips it.
-        if (toolPolicyViolation(method, codexRecord(params.item), this.allowedRawItemTypes)) {
-            deadline.stop("codex_tool_call");
-            return;
-        }
+        if (items === "none" && !KNOWN_CODEX_NOTIFICATIONS.has(method))
+            this.context.recordUnknown(method);
         if (method === "turn/started") {
             const value = codexRecord(params.turn).id;
             if (typeof value !== "string" ||
@@ -137,7 +144,10 @@ export class RestrictedCodexTurn {
     onRequest = async (method, params) => {
         const { deadline, participant, toolCallIds } = this.context;
         const callId = params.callId;
-        if (!participant ||
+        // A request before turn/start is sent, or after the turn completed, is outside the turn.
+        if (!this.dispatched ||
+            this.completed ||
+            !participant ||
             method !== "item/tool/call" ||
             params.threadId !== this.context.threadId() ||
             typeof params.turnId !== "string" ||
@@ -150,13 +160,13 @@ export class RestrictedCodexTurn {
             callId.length > 200 ||
             toolCallIds.has(callId) ||
             this.toolRequestPending)
-            throw new RestrictedCodexStop("codex_tool_call");
+            this.refuseRequest();
         // Mark the request outstanding before waiting for a same-chunk turn/start
         // acknowledgment, so an early completion can never be accepted.
         this.toolRequestPending = true;
         const activeTurnId = this.turnId ?? this.earlyTurnId ?? (await deadline.wait(this.turnReady));
         if (params.turnId !== activeTurnId)
-            throw new RestrictedCodexStop("codex_tool_call");
+            this.refuseRequest();
         toolCallIds.add(callId);
         deadline.pause();
         const text = await deadline.wait(this.context.tool().call(params.arguments));
@@ -170,6 +180,11 @@ export class RestrictedCodexTurn {
         }
         return { success: true, contentItems: [{ type: "inputText", text }] };
     };
+    /** Refuses a tool request: the session records the refusal, and the transport answers it. */
+    refuseRequest() {
+        this.context.refuse("codex_tool_call");
+        throw new RestrictedCodexStop("codex_tool_call");
+    }
     onRequestComplete = () => {
         this.toolRequestPending = false;
     };
@@ -220,11 +235,9 @@ export class RestrictedCodexTurn {
     /** The item allowlist, the participant's one dynamic tool and the final answer's shape. */
     admitsItem(method, item) {
         const { deadline, participant } = this.context;
-        const allowedItems = participant
-            ? ["userMessage", "agentMessage", "reasoning", "contextCompaction", "dynamicToolCall"]
-            : ["userMessage", "agentMessage", "reasoning", "contextCompaction"];
+        const allowedItems = participant ? PARTICIPANT_ITEM_TYPES : ANALYST_ITEM_TYPES;
         if (!allowedItems.includes(String(item.type))) {
-            deadline.stop("codex_tool_call");
+            this.context.refuse("codex_tool_call");
             return false;
         }
         if (item.type === "dynamicToolCall" &&
@@ -232,7 +245,7 @@ export class RestrictedCodexTurn {
                 item.namespace !== null ||
                 (method === "item/started" && item.status !== "inProgress") ||
                 (method === "item/completed" && (item.status !== "completed" || item.success !== true)))) {
-            deadline.stop("codex_tool_call");
+            this.context.refuse("codex_tool_call");
             return false;
         }
         if (item.type === "agentMessage" &&

package/dist/actors/computer-use/actor.d.ts

@@ -6,11 +6,11 @@ import { type RedactionHooks } from "../../evidence/redaction.js";
 import type { DwellWindow, StopWhen } from "../stop-conditions.js";
 import type { LabTask } from "../../lab/tasks.js";
 export interface CuaActorSessionOptions {
-    /** The composed mission (persona + scenario/lane instruction) handed to the model. */
+    /** The composed mission (persona + scenario/participant instruction) handed to the model. */
     instructions: string;
     /** Provenance of the persona this actor embodies (id + applied traits + prompt digest). */
     persona: ActorPersonaRef;
-    /** Hard wall-clock runaway guard — the only count-free hard stop the loop honors. */
+    /** Hard wall-clock runaway guard: the only count-free hard stop the loop honors. */
     timeoutMs: number;
     signal?: AbortSignal;
     /** Live provider construction (used when `provider` is not injected). */
@@ -19,10 +19,10 @@ export interface CuaActorSessionOptions {
     desktop?: E2BDesktopLike;
     executorOptions?: E2BDesktopExecutorOptions;
     /**
-     * DI seams — inject to bypass live construction (CI uses these for zero-spend tests; library
-     * callers use them to drive a state-driven, non-vision flow). NOTE: a STATE executor (one
-     * whose observe() returns no screenshot — see CuaObservation.screenshot optional) MUST be
-     * paired with a NON-vision provider (requiresFrame falsey). The default OpenAI provider is
+     * DI seams: inject to bypass live construction (CI uses these for zero-spend tests; library
+     * callers use them to drive a state-driven, non-vision flow). NOTE: a state executor (one
+     * whose observe() returns no screenshot; see CuaObservation.screenshot optional) must be
+     * paired with a non-vision provider (requiresFrame falsey). The default OpenAI provider is
      * vision-based and would fail closed against a screenshot-less observation. See
      * docs/architecture/state-driven-executor.md.
      */
@@ -39,7 +39,7 @@ export interface CuaActorSessionOptions {
     idleSteps?: number;
     noProgressSteps?: number;
     /**
-     * Redact persisted screenshots (blur+downscale). Default FALSE — full fidelity for local use.
+     * Redact persisted screenshots (blur+downscale). Default `false`: full fidelity for local use.
      * Set true for unowned subjects or share-as-is bundles. The provider always sees raw frames.
      */
     redactScreenshots?: boolean;
@@ -49,29 +49,29 @@ export interface CuaActorSessionOptions {
     writeScreenshot?: (name: string, bytes: Buffer) => Promise<string>;
     /** Deterministic harness-owned stop guards evaluated between model turns. */
     stopWhen?: StopWhen;
-    /** A declared observation window (#510), forwarded to the loop. */
+    /** A declared observation window, forwarded to the loop. */
     dwell?: DwellWindow;
-    /** The lab's declared protocol; the loop records a corroborated task funnel on the trace (#414).
-     *  Only the `success` criteria are read here — the participant-facing goals are already composed
+    /** The lab's declared protocol; the loop records a corroborated task funnel on the trace.
+     *  Only the `success` criteria are read here; the participant-facing goals are already composed
      *  into `instructions` upstream, and the criteria never reach the prompt. */
     tasks?: readonly LabTask[];
-    /** FAIL-CLOSED spend cap (USD) threaded to the loop; absent = uncapped. See CuaLoopOptions.maxUsd. */
+    /** Fail-closed spend cap (USD) threaded to the loop; absent = uncapped. See CuaLoopOptions.maxUsd. */
     maxUsd?: number;
     /** Injected pure per-turn cost estimator paired with `maxUsd`. See CuaLoopOptions.estimateTurnCostUsd. */
     estimateTurnCostUsd?: (usage: ActorTokenUsage) => number | null;
-    /** RUN-LEVEL spend guard threaded to the loop (#299). See CuaLoopOptions.overRunBudget. */
+    /** Run-level spend guard threaded to the loop. See CuaLoopOptions.overRunBudget. */
     overRunBudget?: (usage: ActorTokenUsage) => string | null;
     /** Stricter unknown-usage policy for capped sessions (see CuaLoopOptions); it also makes the
      *  OpenAI provider send one HTTP dispatch per turn. Library-only. */
     requireReportedUsageForSpendCap?: boolean;
-    /** RUNTIME-ONLY observed-URL callback threaded to the loop; see CuaLoopOptions.onObservedUrl. Used by
-     *  the concurrent shared-world handoff barrier to latch a host seat's live /lobby/CODE URL. */
+    /** Runtime-only observed-URL callback threaded to the loop; see CuaLoopOptions.onObservedUrl. Used by
+     *  the concurrent shared-world handoff barrier to latch a host's live /lobby/CODE URL. */
     onObservedUrl?: (url: string | undefined) => void;
-    /** RUNTIME-ONLY per-turn narration callback threaded to the loop; see CuaLoopOptions.onMessage. */
+    /** Runtime-only per-turn narration callback threaded to the loop; see CuaLoopOptions.onMessage. */
     onMessage?: (text: string) => void;
-    /** RUNTIME-ONLY per-turn raw-frame callback threaded to the loop; see CuaLoopOptions.onScreenshot. */
+    /** Runtime-only per-turn raw-frame callback threaded to the loop; see CuaLoopOptions.onScreenshot. */
     onScreenshot?: (frame: Buffer) => void;
-    /** Per-turn trace snapshot callback threaded to the loop (#441); see CuaLoopOptions.onTrace. */
+    /** Per-turn trace snapshot callback threaded to the loop; see CuaLoopOptions.onTrace. */
     onTrace?: (items: readonly ActorTraceItem[], usage: ActorTokenUsage, metadata?: CuaLiveMetadata) => void;
 }
 export declare function runCuaActorSession(options: CuaActorSessionOptions): Promise<CuaLoopResult>;

package/dist/actors/computer-use/actor.js

@@ -1,12 +1,12 @@
 // The registry-facing wrapper for the OpenAI Computer Use (CUA) actor. runComputerUseLoop needs
 // fully-constructed provider/executor instances; exposing that raw through the actor registry
 // would leak adapter construction to every call site. So runCuaActorSession takes intent-level
-// fields and constructs the provider/executor internally — with DI seams (provider/executor/now)
+// fields and constructs the provider/executor internally, with DI seams (provider/executor/now)
 // so CI can drive the real loop with fakes and zero network/zero spend (mirrors how the Claude
 // adapter injects its queryFn).
 //
 // The loop already returns a fully-formed ActorTrace at result.trace, so there is no separate
-// toActorTrace mapper — runCuaActorSession returns the CuaLoopResult unchanged.
+// toActorTrace mapper: runCuaActorSession returns the CuaLoopResult unchanged.
 import { runComputerUseLoop, } from "./loop.js";
 import { createE2BDesktopExecutor, } from "../../substrates/e2b/desktop-executor.js";
 import { createOpenAiResponsesProvider, } from "./openai-provider.js";
@@ -18,8 +18,8 @@ export async function runCuaActorSession(options) {
     }
     const strictSpend = options.requireReportedUsageForSpendCap === true &&
         (options.maxUsd !== undefined || options.overRunBudget !== undefined);
-    const provider = options.provider ?? buildProvider(options.openai, strictSpend);
-    const executor = options.executor ?? buildExecutor(options.desktop, options.executorOptions);
+    const provider = options.provider ?? defaultProvider(options.openai, strictSpend);
+    const executor = options.executor ?? defaultExecutor(options.desktop, options.executorOptions);
     const loopOptions = {
         instructions: options.instructions,
         provider,
@@ -61,7 +61,7 @@ export async function runCuaActorSession(options) {
     }
     return result;
 }
-function buildProvider(openai, strictSpend = false) {
+function defaultProvider(openai, strictSpend = false) {
     if (!openai) {
         throw new Error("runCuaActorSession requires either `provider` (injected) or `openai` provider options.");
     }
@@ -70,7 +70,7 @@ function buildProvider(openai, strictSpend = false) {
         ...(strictSpend ? { singleDispatch: true } : {}),
     });
 }
-function buildExecutor(desktop, executorOptions) {
+function defaultExecutor(desktop, executorOptions) {
     if (!desktop) {
         throw new Error("runCuaActorSession requires either `executor` (injected) or `desktop` to build one.");
     }

package/dist/actors/computer-use/admission-limit.d.ts

@@ -1,5 +1,5 @@
 /**
- * A caller's adapter refused this request BEFORE provider dispatch because a configured
+ * A caller's adapter refused this request before provider dispatch because a configured
  * local control limit was reached. This is an adapter declaration, not a provider response
  * or independent transport/billing attestation. Never use it for a dispatched request whose
  * outcome or usage is unknown. Import this class from the same humanish installation as the

package/dist/actors/computer-use/admission-limit.js

@@ -1,6 +1,6 @@
 const admissionLimits = new WeakSet();
 /**
- * A caller's adapter refused this request BEFORE provider dispatch because a configured
+ * A caller's adapter refused this request before provider dispatch because a configured
  * local control limit was reached. This is an adapter declaration, not a provider response
  * or independent transport/billing attestation. Never use it for a dispatched request whose
  * outcome or usage is unknown. Import this class from the same humanish installation as the

package/dist/actors/computer-use/loop/actions.d.ts

@@ -3,10 +3,10 @@ import type { CuaAction, CuaTurnRequest } from "./types.js";
 /** A public-safe one-line action label. Never includes raw typed text. */
 export declare function describeCuaAction(action: CuaAction): string;
 /**
- * A public-safe fingerprint of ONE turn's actions, used only in memory to tell "trying the same
- * thing again" from "trying something new" (#383).
+ * A public-safe fingerprint of one turn's actions, used only in memory to tell "trying the same
+ * thing again" from "trying something new".
  *
- * Never includes typed text or key contents — a `type` contributes its LENGTH, exactly as
+ * Never includes typed text or key contents: a `type` contributes its length, exactly as
  * describeCuaAction does, so this can never become a keylogger. Coordinates are bucketed so that
  * re-clicking the same control counts as a repeat while moving to a different control does not.
  */

package/dist/actors/computer-use/loop/actions.js

@@ -47,10 +47,10 @@ function describeAction(action) {
     }
 }
 /**
- * A public-safe fingerprint of ONE turn's actions, used only in memory to tell "trying the same
- * thing again" from "trying something new" (#383).
+ * A public-safe fingerprint of one turn's actions, used only in memory to tell "trying the same
+ * thing again" from "trying something new".
  *
- * Never includes typed text or key contents — a `type` contributes its LENGTH, exactly as
+ * Never includes typed text or key contents: a `type` contributes its length, exactly as
  * describeCuaAction does, so this can never become a keylogger. Coordinates are bucketed so that
  * re-clicking the same control counts as a repeat while moving to a different control does not.
  */
@@ -121,8 +121,8 @@ export async function runActionBatch(session, actions) {
         if (actionHistory.recentActionTitles.length > RECENT_ACTION_TITLES)
             actionHistory.recentActionTitles.shift();
         trace.bump("actions");
-        // Classify BEFORE execute, mirroring counts.actions: the record is of what the actor
-        // CHOSE, so an action that then fails to actuate is still an honest record of the route
+        // Classify before execute, mirroring counts.actions: the record is of what the actor
+        // chose, so an action that then fails to actuate is still a record of the route
         // it reached for.
         actionHistory.affordances.push(classifyCuaAction(action));
         session.phase = `executing ${title}`;
@@ -153,7 +153,7 @@ export async function runActionBatch(session, actions) {
             if (isCuaExecutorError(error) || !isCommandExitError(error))
                 throw error;
             // A skipped action changes nothing on screen, so a persistently-failing run makes no
-            // progress and still terminates honestly via the idle/no-progress backstop (gave_up),
+            // progress and still terminates via the idle/no-progress backstop (gave_up),
             // never a silent actor_error and never an infinite loop.
             recordCommandFailure(session, title, error);
             continue;
@@ -164,8 +164,8 @@ export async function runActionBatch(session, actions) {
             lifecycle: "completed",
             title,
             ...(action.kind === "speak" ? { text: session.redactNarration(action.text) } : {}),
-            // Structured pin coordinates (#441), exactly the click classes the Observer
-            // pins render — recorded fact instead of a title re-parse downstream.
+            // Structured pin coordinates, exactly the click classes the Observer
+            // pins render: recorded fact instead of a title re-parse downstream.
             ...(action.kind === "click" || action.kind === "double_click"
                 ? { coord: { x: action.x, y: action.y } }
                 : {}),
@@ -180,9 +180,9 @@ function countAttempt(session, action, title, status) {
     session.trace.counts.materialActions += 1;
 }
 /**
- * Execute one action. Idle actions only look (#480): a `wait` that hangs inside the SDK has in
+ * Execute one action. Idle actions only look: a `wait` that hangs inside the SDK has in
  * effect waited, so a stalled one is skipped with a notice and loses nothing the participant
- * chose. An action is recorded as completed only after execute() resolves (#248).
+ * chose. An action is recorded as completed only after execute() resolves.
  */
 async function dispatchAction(session, action, title) {
     if (!isIdleAction(action)) {

package/dist/actors/computer-use/loop/backstop.d.ts

@@ -2,10 +2,10 @@ import type { CuaAction, CuaObservation } from "./types.js";
 /**
  * A deterministic, bounded, sorted-key projection of an appState object, used as the friction
  * loop's progress key. Two structurally-equal states (regardless of key insertion order) map
- * to the SAME string, so key reordering can never fabricate a progress delta; two different
+ * to the same string, so key reordering can never fabricate a progress delta; two different
  * states map to different strings (within the caps).
  *
- * Correctness-load-bearing: it MUST NOT throw on a cyclic or huge input. Cycles are detected
+ * Correctness depends on this: it must not throw on a cyclic or huge input. Cycles are detected
  * with a seen-set (a back-edge degrades to the marker "[Circular]"); depth, key count, array
  * length, string length, and total output length are all capped so an adversarial or merely
  * large appState degrades to a bounded value rather than crashing the loop. Pure: it never
@@ -14,7 +14,7 @@ import type { CuaAction, CuaObservation } from "./types.js";
 export declare function stableProgressKey(appState: Record<string, unknown>): string;
 export interface Backstop {
     readonly progressKey: string;
-    /** The last few turns' action fingerprints, in memory only, for the #383 corroboration rule. */
+    /** The last few turns' action fingerprints, in memory only, for the corroboration rule below. */
     readonly recentFingerprints: readonly string[];
     readonly consecutiveIdle: number;
     readonly consecutiveNoProgress: number;

package/dist/actors/computer-use/loop/backstop.js

@@ -4,9 +4,9 @@ import { actionFingerprint, isIdleTurn } from "./actions.js";
 // streak (turns that neither change the UI state nor try something new). It is a pure fold over
 // turns, never a turn budget.
 const IDLE_PROGRESS_FORGIVENESS_STEPS = 2;
-/** How many recent turns the repetition check looks back over (#383). */
+/** How many recent turns the repetition check looks back over. */
 const ACTION_REPEAT_WINDOW = 3;
-/** Pixels of vertical scroll per progress bucket (#393): a real scroll step (typically >=100px)
+/** Pixels of vertical scroll per progress bucket: a real scroll step (typically >=100px)
  *  crosses a bucket and counts as progress; sub-bucket jiggle does not, so an actor nudging the
  *  same dead panel cannot stay "progressing" forever. */
 const SCROLL_PROGRESS_BUCKET_PX = 200;
@@ -22,10 +22,10 @@ const STABLE_KEY_MAX_TOTAL = 8192;
 /**
  * A deterministic, bounded, sorted-key projection of an appState object, used as the friction
  * loop's progress key. Two structurally-equal states (regardless of key insertion order) map
- * to the SAME string, so key reordering can never fabricate a progress delta; two different
+ * to the same string, so key reordering can never fabricate a progress delta; two different
  * states map to different strings (within the caps).
  *
- * Correctness-load-bearing: it MUST NOT throw on a cyclic or huge input. Cycles are detected
+ * Correctness depends on this: it must not throw on a cyclic or huge input. Cycles are detected
  * with a seen-set (a back-edge degrades to the marker "[Circular]"); depth, key count, array
  * length, string length, and total output length are all capped so an adversarial or merely
  * large appState degrades to a bounded value rather than crashing the loop. Pure: it never
@@ -107,8 +107,8 @@ function progressKeyOf(observation) {
     const base = observation.appState !== undefined
         ? stableProgressKey(observation.appState)
         : observation.stateSignature;
-    // Scroll position is state (#393): a scroll-pinned section keeps the frame hash constant while
-    // the participant genuinely advances, so the offset rides the key — bucketed, never raw.
+    // Scroll position is state: a scroll-pinned section keeps the frame hash constant while
+    // the participant genuinely advances, so the offset rides the key, bucketed, never raw.
     return observation.scrollY === undefined
         ? base
         : `${base}#s${Math.round(observation.scrollY / SCROLL_PROGRESS_BUCKET_PX)}`;
@@ -127,23 +127,23 @@ export function advanceBackstop(previous, turn, limits) {
     const idle = isIdleTurn(turn.actions);
     const progressKey = progressKeyOf(turn.observation);
     const frameChanged = progressKey !== previous.progressKey;
-    // CORROBORATION (#383). A stale frame alone is NOT evidence of a stuck agent. The frame hash is
+    // Corroboration. A stale frame alone is not evidence of a stuck agent. The frame hash is
     // a coarse whole-screen measure, and on a light-themed web app it can miss a renamed row, a new
-    // list item, or an opened panel — a measured run had 9 visibly different consecutive frames hash
-    // identically while the agent was a foreign key away from finishing. Ending a lane on that
+    // list item, or an opened panel: a measured run had 9 visibly different consecutive frames hash
+    // identically while the agent was a foreign key away from finishing. Ending a participant on that
     // signal alone recorded working sessions as `gave_up`, capping every browser run at roughly
     // noProgressSteps turns and writing harness artifacts into evidence as actor behavior.
     //
-    // So a no-progress turn now requires BOTH a stale frame AND the agent repeating something it
+    // So a no-progress turn now requires both a stale frame and the agent repeating something it
     // just tried. An agent doing varied work is never counted stuck, however blind the hash is;
-    // an agent re-clicking the same dead control trips it as fast as it did before — arguably
+    // an agent re-clicking the same dead control trips it as fast as it did before, arguably
     // faster, since that is the actual signature of being stuck.
     const fingerprint = actionFingerprint(turn.actions);
     const repeatingRecentAction = fingerprint.length > 0 && previous.recentFingerprints.includes(fingerprint);
     const recentFingerprints = [...previous.recentFingerprints, fingerprint].slice(-ACTION_REPEAT_WINDOW);
-    // Corroboration governs the FRAME-STALENESS backstop only. The idle backstop below is a direct
+    // Corroboration governs the frame-staleness backstop only. The idle backstop below is a direct
     // behavioral signal already (the agent took nothing but screenshots and waits), so it keeps
-    // reading the frame on its own — a repeated screenshot is exactly what an idle streak IS, and
+    // reading the frame on its own: a repeated screenshot is exactly what an idle streak is, and
     // feeding repetition into it would grant an extra forgiveness step for being idle.
     const observedProgress = frameChanged || turn.heardNewSpeech;
     const progressed = observedProgress || !repeatingRecentAction;
@@ -172,11 +172,13 @@ export function advanceBackstop(previous, turn, limits) {
     const hints = [];
     if (consecutiveNoProgress >= noProgressRecoverySteps &&
         consecutiveNoProgress < limits.noProgressSteps) {
+        // prose-check: model prompt (the participant model reads this hint, not a person)
         hints.push(`No visible progress for ${consecutiveNoProgress} step(s). ` +
             "If your task calls for waiting for another participant or a pending transition, you may continue waiting. " +
             "Choose whether to continue or stop based on your situation and what you observe.");
     }
     if (consecutiveIdle >= idleRecoverySteps && consecutiveIdle < limits.idleSteps) {
+        // prose-check: model prompt (the participant model reads this hint, not a person)
         hints.push(`You are only waiting or taking screenshots for ${consecutiveIdle} step(s). ` +
             "If your task calls for waiting, you may continue within the remaining session time. " +
             "When the relevant controls become actionable, continue your task; describe any blocker you actually encounter.");

package/dist/actors/computer-use/loop/ending.d.ts

@@ -18,25 +18,25 @@ export interface Stop {
     readonly debriefTrigger?: DebriefTrigger;
 }
 /**
- * Read the fixed closing line the prompt asks for (#570): the FIRST non-empty line of the
+ * Read the fixed closing line the prompt asks for: the first non-empty line of the
  * participant's last message, exactly one of three phrases, punctuation and case forgiven. Anything
  * else is absence, never a guess. Exported for tests.
  */
 export declare function declaredOutcomeFromClosingLine(message: string | undefined): ParticipantDeclaredOutcome | undefined;
-/** The participant's own word for how it ended: a schema field first, then the closing line (#570). */
+/** The participant's own word for how it ended: a schema field first, then the closing line. */
 export declare function declaredOutcomeOf(turn: CuaTurn): ParticipantDeclaredOutcome | undefined;
 /**
  * The participant reported a natural endpoint. "not_reached" is a participant who stopped without
  * finishing: gave_up, which tallies as abandoned. "blocked" keeps goal_satisfied here (the actor
- * did stop on purpose) and the lane's credibility read turns it into a blocked participant, the
+ * did stop on purpose) and the route's credibility read turns it into a blocked participant, the
  * same path a narrated blocker takes.
  */
 export declare function participantEnded(turn: CuaTurn, declaredOutcome: ParticipantDeclaredOutcome | undefined, redactNarration: (text: string) => string): Stop;
 export declare const harnessAborted: Stop;
 /**
  * The wall-clock deadline. A session that took at least one material (non-idle) action before the
- * cap reached its BUDGET rather than stalling; a deadline hit with zero material actions is still
- * an honest failure (timed_out).
+ * cap reached its budget rather than stalling; a deadline hit with zero material actions is still
+ * recorded as a failure (timed_out).
  */
 export declare function timeLimit(session: LoopSession): Stop;
 /**
@@ -47,7 +47,7 @@ export declare function timeLimit(session: LoopSession): Stop;
 export declare function spendLimit(session: LoopSession, estimate: number, maxUsd: number): Stop;
 export declare const nonFiniteEstimate: Stop;
 /** A study-level stop is a recruiting decision hitting its limit, not this participant's runaway. */
-export declare function studySpendLimit(reason: string): Stop;
+export declare function runSpendLimit(reason: string): Stop;
 export declare const accountBilledCaps: Stop;
 export declare const adapterLimit: Stop;
 export declare const usageUnreported: Stop;
@@ -67,7 +67,7 @@ export declare function providerStalledTwice(turnNumber: number, afterMs: number
 export declare function providerInterrupted(interruption: NonNullable<CuaTurn["interruption"]>): Stop;
 /**
  * Safety-check categories are provider-defined enums (e.g. "malicious_instructions"), not free
- * text; the evidence records them (redacted for defense-in-depth) so it shows WHY the run paused.
+ * text; the evidence records them (redacted for defense-in-depth) so it shows why the run paused.
  */
 export declare function blockedOnSafetyChecks(checks: string): Stop;
 /**

package/dist/actors/computer-use/loop/ending.js

@@ -3,7 +3,7 @@ import { isCuaPromptRefusedError, isCuaProviderError } from "../provider-error.j
 import { CuaAbortError, CuaDeadlineError } from "./race.js";
 import { notice } from "./trace.js";
 /**
- * Read the fixed closing line the prompt asks for (#570): the FIRST non-empty line of the
+ * Read the fixed closing line the prompt asks for: the first non-empty line of the
  * participant's last message, exactly one of three phrases, punctuation and case forgiven. Anything
  * else is absence, never a guess. Exported for tests.
  */
@@ -25,14 +25,14 @@ export function declaredOutcomeFromClosingLine(message) {
         return "blocked";
     return undefined;
 }
-/** The participant's own word for how it ended: a schema field first, then the closing line (#570). */
+/** The participant's own word for how it ended: a schema field first, then the closing line. */
 export function declaredOutcomeOf(turn) {
     return turn.outcome ?? declaredOutcomeFromClosingLine(turn.message);
 }
 /**
  * The participant reported a natural endpoint. "not_reached" is a participant who stopped without
  * finishing: gave_up, which tallies as abandoned. "blocked" keeps goal_satisfied here (the actor
- * did stop on purpose) and the lane's credibility read turns it into a blocked participant, the
+ * did stop on purpose) and the route's credibility read turns it into a blocked participant, the
  * same path a narrated blocker takes.
  */
 export function participantEnded(turn, declaredOutcome, redactNarration) {
@@ -51,8 +51,8 @@ export const harnessAborted = {
 };
 /**
  * The wall-clock deadline. A session that took at least one material (non-idle) action before the
- * cap reached its BUDGET rather than stalling; a deadline hit with zero material actions is still
- * an honest failure (timed_out).
+ * cap reached its budget rather than stalling; a deadline hit with zero material actions is still
+ * recorded as a failure (timed_out).
  */
 export function timeLimit(session) {
     const { timeoutMs } = session;
@@ -86,8 +86,8 @@ export function spendLimit(session, estimate, maxUsd) {
     return {
         completionReason: "budget_reached",
         reason: materialActions > 0
-            ? `${spend} crossed execution.caps.maxUsd=$${maxUsd} after productive activity (${materialActions} material action(s), ${turns} turn(s)); aborted fail-closed before the next model turn`
-            : `${spend} crossed execution.caps.maxUsd=$${maxUsd} with no material progress; aborted fail-closed before the next model turn`,
+            ? `Stopped before the next model turn: ${spend} passed execution.caps.maxUsd=$${maxUsd} after productive activity (${materialActions} material action(s), ${turns} turn(s))`
+            : `Stopped before the next model turn: ${spend} passed execution.caps.maxUsd=$${maxUsd} with no material progress`,
         stopCause: "spend_limit",
     };
 }
@@ -98,7 +98,7 @@ export const nonFiniteEstimate = {
     reason: "the injected estimateTurnCostUsd returned a non-finite estimate while execution.caps.maxUsd is set; the estimator receives one ActorTokenUsage object. Failing closed instead of running uncapped.",
 };
 /** A study-level stop is a recruiting decision hitting its limit, not this participant's runaway. */
-export function studySpendLimit(reason) {
+export function runSpendLimit(reason) {
     return { completionReason: "budget_reached", reason, stopCause: "study_spend_limit" };
 }
 // A host-authenticated provider may learn its account billing class during startup. Never price
@@ -178,7 +178,7 @@ export function providerInterrupted(interruption) {
 }
 /**
  * Safety-check categories are provider-defined enums (e.g. "malicious_instructions"), not free
- * text; the evidence records them (redacted for defense-in-depth) so it shows WHY the run paused.
+ * text; the evidence records them (redacted for defense-in-depth) so it shows why the run paused.
  */
 export function blockedOnSafetyChecks(checks) {
     return {

package/dist/actors/computer-use/loop/observation.d.ts

@@ -23,8 +23,8 @@ export declare class DesktopObserver {
     checkpoint(turnNumber: number): Promise<Checkpoint>;
     /**
      * Hand an observation the next turn may react to to the runtime hooks, and note whether it
-     * carried app state. Runtime-only: the seat's live location.href goes back to the orchestrator
-     * and is never persisted.
+     * carried app state. Runtime-only: the participant's live location.href goes back to the
+     * orchestrator and is never persisted.
      */
     private handToHooks;
     /**