humanish 0.111.0 → 0.111.2

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

@@ -7,20 +7,46 @@ import { asArray, asRecord, inputMessage, openAiActionToCua } from "./openai-wir
 // The Responses API pairs items: every computer_call needs its computer_call_output, and a
 // reasoning item travels with the item it preceded. The conversation is therefore cut only at
 // exchange boundaries: one reply's output items together with the items that answered them.
-// When the estimate passes the budget, the opening screenshot goes first, then the oldest
-// exchanges become lines of a progress note that keeps their reasoning summaries, messages and
-// actions as text. The note is an assistant message, so text the model wrote (which can quote a
-// web page) keeps the trust it had when the model wrote it. The newest MIN_KEPT_EXCHANGES
-// exchanges are never collapsed, so a request passes the budget when they alone exceed it; the
-// trace's per-request estimate shows when that happens.
-/** The estimated input a carried conversation may reach before its oldest turns are summarized. */
+// When the estimate passes the budget, the conversation is cut down to half the budget in one
+// step: the opening screenshot goes first, then the oldest exchanges become lines of a progress
+// note that keeps their reasoning summaries, messages and actions, and the text that answered
+// them, such as a note that an action was not run. The note is an assistant message, so text the
+// model wrote (which can quote a web page) keeps the trust it had when the model wrote it. The newest MIN_KEPT_EXCHANGES exchanges are never collapsed, so a
+// request passes the budget when they alone exceed it; the trace's per-request estimate shows when
+// that happens.
+//
+// A cut rewrites the start of the prompt, so the provider's prompt cache misses on the request
+// after it. Between cuts nothing already sent changes: each request starts with the whole of the
+// previous request, which the cache can serve. A cut of one exchange per turn would rewrite
+// the note on every request past the budget, and each of those requests would be billed in full.
+/** The estimated input a carried conversation may reach before it is cut. */
 export const CONTEXT_TOKEN_BUDGET = 64_000;
+/**
+ * The share of the budget a cut brings the carried conversation down to. The rest is the growth
+ * the cache serves until the next cut: about 19 turns of 1280x800 screenshots, or 12 at
+ * 1920x1080.
+ */
+const CUT_TARGET_SHARE = 0.5;
 /** Exchanges always carried whole, so the model sees its latest actions with their screens. */
 const MIN_KEPT_EXCHANGES = 2;
-/** The progress note's length cap; past it, the oldest lines are counted instead of shown. */
-const NOTE_CHAR_LIMIT = 16_000;
-/** One note line's cap, so a reply with many actions cannot push the note past its own cap. */
-const LINE_CHAR_LIMIT = 1_200;
+/**
+ * The progress note's length cap, about 8,000 tokens. Past it, the oldest lines after the first
+ * NOTE_HEAD_LINES are counted instead of shown. The note sits in the cached prefix between cuts,
+ * so its size costs little after the request that writes it.
+ */
+const NOTE_CHAR_LIMIT = 32_000;
+/**
+ * Note lines kept whatever the note's length. A session's first turns are where it usually learns
+ * what it must carry to the end, such as an account, an address or a code, and the newest lines
+ * hold its latest progress, so the note gives up the turns between them.
+ */
+const NOTE_HEAD_LINES = 4;
+/**
+ * One note line's cap, so a reply with many actions cannot push the note past its own cap. It
+ * leaves room for the clipped thought, message and hint text plus about 1,000 characters of
+ * actions, such as several typed form fields.
+ */
+const LINE_CHAR_LIMIT = 2_000;
 /**
  * Image input tokens per 32-pixel patch. The gpt-5.x and gpt-6 models bill 1.2 per patch, and at
  * the default (auto) detail gpt-5.6 and gpt-6 keep the screenshot's own size. Models that resize
@@ -36,7 +62,11 @@ export class CarriedConversation {
     /** The latest accepted reply's output items, which the next request answers. */
     pending;
     notes = [];
-    notesDropped = 0;
+    /**
+     * The turns whose note lines were dropped to keep the note under its cap. Lines are dropped in
+     * turn order from just after the head, so they are one run of consecutive turns.
+     */
+    elided;
     collapsedTurns = 0;
     constructor(budget = CONTEXT_TOKEN_BUDGET) {
         this.budget = budget;
@@ -76,7 +106,10 @@ export class CarriedConversation {
         };
     }
     trim() {
-        while (estimateTokens(this.carried()) > this.budget) {
+        if (estimateTokens(this.carried()) <= this.budget)
+            return;
+        const target = Math.floor(this.budget * CUT_TARGET_SHARE);
+        while (estimateTokens(this.carried()) > target) {
             if (this.opening !== undefined && imagesOf(this.opening).length > 0) {
                 this.opening = withoutImages(this.opening);
                 continue;
@@ -84,30 +117,56 @@ export class CarriedConversation {
             if (this.exchanges.length <= MIN_KEPT_EXCHANGES)
                 return;
             const oldest = this.exchanges.shift();
-            this.notes.push(describeExchange(oldest));
+            this.notes.push({ turn: oldest.turn, text: describeExchange(oldest) });
             this.collapsedTurns += 1;
-            while (this.notes.join("\n").length > NOTE_CHAR_LIMIT && this.notes.length > 1) {
-                this.notes.shift();
-                this.notesDropped += 1;
-            }
+            this.capNote();
+        }
+    }
+    capNote() {
+        while (this.noteText().length > NOTE_CHAR_LIMIT && this.notes.length > NOTE_HEAD_LINES + 1) {
+            const [dropped] = this.notes.splice(NOTE_HEAD_LINES, 1);
+            this.elided = { first: this.elided?.first ?? dropped.turn, last: dropped.turn };
+        }
+    }
+    noteText() {
+        const lines = this.notes.map((line) => line.text);
+        if (this.elided !== undefined) {
+            const { first, last } = this.elided;
+            const which = first === last ? `Turn ${first} is` : `Turns ${first} to ${last} are`;
+            lines.splice(NOTE_HEAD_LINES, 0, `(${which} not listed.)`);
         }
+        return lines.join("\n");
     }
     noteItem() {
         if (this.notes.length === 0)
             return undefined;
         const lead = `My notes on my earlier turns in this session, oldest first. Their screenshots are no ` +
-            `longer shown; this is what I thought, said and did.` +
-            (this.notesDropped === 0 ? "" : ` (${this.notesDropped} earlier turns are not listed.)`);
+            `longer shown; this is what I thought, said and did, and what I was told after.`;
         return inputMessage("assistant", [
-            { type: "output_text", text: `${lead}\n${this.notes.join("\n")}` },
+            { type: "output_text", text: `${lead}\n${this.noteText()}` },
         ]);
     }
 }
-/** One exchange as a progress-note line: its reasoning summary, message and actions. */
+/**
+ * One exchange as a progress-note line: its reasoning summary, message and actions, and the text
+ * that came back with their screenshot, such as a note that an action was not run.
+ */
 function describeExchange(exchange) {
     const thought = [];
     const said = [];
     const did = [];
+    const told = [];
+    // The answers are the call outputs, whose content is a screenshot, and hint messages.
+    for (const raw of exchange.answers) {
+        const item = asRecord(raw);
+        if (item.type === "computer_call_output")
+            continue;
+        for (const entry of asArray(item.content)) {
+            const text = asRecord(entry).text;
+            if (typeof text === "string" && text.length > 0)
+                told.push(text);
+        }
+    }
     for (const raw of exchange.output) {
         const item = asRecord(raw);
         if (item.type === "reasoning")
@@ -131,13 +190,19 @@ function describeExchange(exchange) {
             }
         }
     }
-    const parts = [
+    const lead = `Turn ${exchange.turn}: `;
+    const before = [
         thought.length > 0 ? `thought: ${clip(thought.join(" "), 400)}` : undefined,
         said.length > 0 ? `said: ${clip(said.join(" "), 300)}` : undefined,
-        did.length > 0 ? `did: ${did.join(", ")}` : undefined,
     ].filter((part) => part !== undefined);
-    const line = `Turn ${exchange.turn}: ${parts.length > 0 ? parts.join("; ") : "no recorded output"}`;
-    return `${clip(line, LINE_CHAR_LIMIT - 1)}.`;
+    const after = told.length > 0 ? [`was told: ${clip(told.join(" "), 300)}`] : [];
+    // The hint can say an action did not run, so the actions give up whatever room it needs.
+    const fixed = [...before, ...after].reduce((length, part) => length + part.length + 2, 0);
+    const room = LINE_CHAR_LIMIT - 1 - lead.length - fixed - "did: ".length;
+    const actions = did.length > 0 ? [`did: ${clip(did.join(", "), room)}`] : [];
+    const parts = [...before, ...actions, ...after];
+    const line = clip(`${lead}${parts.length > 0 ? parts.join("; ") : "no recorded output"}`, LINE_CHAR_LIMIT - 1);
+    return /[.!?]$/.test(line) ? line : `${line}.`;
 }
 function describeAction(action) {
     switch (action.kind) {

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

@@ -175,17 +175,51 @@ export function namedProviderErrorCode(bodyText) {
 // by switching to explicit-context mode) from any other non-ok status. It never
 // carries the apiKey or the response body.
 class ZdrError extends Error {
-    constructor() {
-        super("OpenAI Responses rejected server-side state (zero data retention)");
+    rejection;
+    constructor(rejection) {
+        super(rejection === "stored_item"
+            ? "OpenAI Responses could not find an item the request referenced: the server keeps none for this organization (zero data retention)"
+            : "OpenAI Responses rejected server-side state (zero data retention)");
+        this.rejection = rejection;
         this.name = "ZdrError";
     }
 }
-// A 400 whose body mentions any of these means the account/org cannot use
-// server-side response state, so we must fall back to explicit-context mode.
-function isZdrRejection(bodyText) {
-    return (bodyText.includes("Zero Data Retention") ||
-        bodyText.includes("zero data retention") ||
-        bodyText.includes("previous_response_id"));
+/** The message of a 404 for an item the server never kept, as the wire sends it. */
+const STORED_ITEM_NOT_FOUND = /Item with id '?[A-Za-z0-9_-]+'? not found/;
+/**
+ * Error codes that name a failure of their own. Their messages can echo request text, such as a
+ * model name or the prompt, so the words below must not turn them into a retention answer.
+ */
+const OTHER_FAILURE_CODES = new Set([
+    "invalid_prompt",
+    "model_not_found",
+    "context_length_exceeded",
+    "rate_limit_exceeded",
+    "insufficient_quota",
+    "invalid_image",
+    "invalid_image_format",
+    "invalid_base64_image",
+    "invalid_image_url",
+    "image_too_large",
+    "image_parse_error",
+    "image_content_policy_violation",
+]);
+// A 400 or 404 whose body says the organization cannot use server-side response state, so the
+// provider must carry the conversation itself (explicit-context mode). A 404 counts only with the
+// stored-item message. Captured bodies are in tests/fixtures/openai-store-less/.
+function zdrRejection(status, bodyText) {
+    const code = namedProviderErrorCode(bodyText);
+    if (code !== undefined && OTHER_FAILURE_CODES.has(code))
+        return undefined;
+    if (status === 404)
+        return STORED_ITEM_NOT_FOUND.test(bodyText) ? "stored_item" : undefined;
+    if (/zero[ -]data[ -]retention/i.test(bodyText))
+        return "zero_data_retention";
+    if (bodyText.includes("previous_response_id"))
+        return "previous_response";
+    if (STORED_ITEM_NOT_FOUND.test(bodyText))
+        return "stored_item";
+    return undefined;
 }
 // A typed error so nextTurn can latch reasoning summaries off and retry the turn
 // (an org not verified for summaries, or a model without a summarizer, 400s the
@@ -307,11 +341,20 @@ async function postResponse(transport, body, signal, retries, interaction, spend
             return parsed;
         }
         lastStatus = res.status;
+        if (res.status === 404) {
+            // A store-less organization answers a reference to an item it never kept with 404.
+            const bodyText = await res.text().catch(() => "");
+            const rejection = zdrRejection(404, bodyText);
+            if (rejection !== undefined)
+                throw new ZdrError(rejection);
+            const code = namedProviderErrorCode(bodyText);
+            throw new Error(`OpenAI Responses 404${code === undefined ? "" : ` ${code}`}`);
+        }
         if (res.status === 400) {
             const bodyText = await res.text();
-            if (isZdrRejection(bodyText)) {
-                throw new ZdrError();
-            }
+            const rejection = zdrRejection(400, bodyText);
+            if (rejection !== undefined)
+                throw new ZdrError(rejection);
             if (isSummaryRejection(bodyText)) {
                 throw new SummaryRejectionError();
             }
@@ -415,7 +458,7 @@ export function createOpenAiResponsesProvider(options) {
                     continue;
                 }
                 if (error instanceof ZdrError && state.mode !== "explicit_context") {
-                    record.switched();
+                    record.switched(error.rejection);
                     state.mode = "explicit_context";
                     continue;
                 }

package/dist/actors/computer-use/openai-requests.d.ts

@@ -48,13 +48,14 @@ export declare function acceptReply(state: OpenAiConversationState, parsed: Pars
 export declare class ConversationRecord {
     private readonly now;
     private explicitReason;
+    private rejection;
     private switchedAt;
     private switchedAtRequest;
     private summarizedTurns;
     private readonly requests;
     constructor(configured: boolean, now: () => number);
     /** The organization rejected server-side state, so the request being sent is explicit_context. */
-    switched(): void;
+    switched(rejection: NonNullable<ActorConversation["rejection"]>): void;
     /** A participant request just went out with `sent` after the carried conversation. */
     requested(state: OpenAiConversationState, sent: readonly unknown[]): void;
     snapshot(state: OpenAiConversationState): ActorConversation;

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

@@ -94,6 +94,7 @@ export function acceptReply(state, parsed, closing, sent) {
 export class ConversationRecord {
     now;
     explicitReason;
+    rejection;
     switchedAt;
     switchedAtRequest;
     summarizedTurns = 0;
@@ -104,8 +105,9 @@ export class ConversationRecord {
             this.explicitReason = "configured";
     }
     /** The organization rejected server-side state, so the request being sent is explicit_context. */
-    switched() {
+    switched(rejection) {
         this.explicitReason = "zdr_rejection";
+        this.rejection = rejection;
         this.switchedAt = new Date(this.now()).toISOString();
         // Counted like requests[], which includes replies set aside at their output limit.
         this.switchedAtRequest = this.requests.length + 1;
@@ -130,6 +132,7 @@ export class ConversationRecord {
         return {
             mode: state.mode === "explicit_context" ? "explicit_context" : "threaded",
             ...(this.explicitReason === undefined ? {} : { explicitReason: this.explicitReason }),
+            ...(this.rejection === undefined ? {} : { rejection: this.rejection }),
             ...(this.switchedAt === undefined ? {} : { switchedAt: this.switchedAt }),
             ...(this.switchedAtRequest === undefined
                 ? {}

package/dist/actors/contract.d.ts

@@ -206,13 +206,19 @@ export interface ActorRuntimeProvenance {
  * How a provider carried the conversation between its requests. `threaded`: the provider's server
  * kept it (OpenAI previous_response_id). `explicit_context`: the server kept none (a
  * zero-data-retention org, or zeroDataRetention set), so each request carried it from the client
- * within a token budget, with the oldest turns summarized as text once it passed the budget.
+ * within a token budget, with the oldest turns summarized as text at each cut past the budget.
  */
 export interface ActorConversation {
     /** The mode of the session's last request. */
     mode: "threaded" | "explicit_context";
     /** Why the session used explicit_context: configured, or the org rejected server-side state. */
     explicitReason?: "configured" | "zdr_rejection";
+    /**
+     * With `zdr_rejection`, the answer that made the switch: the error named zero data retention, it
+     * refused or could not find the previous response, or it could not find a stored item that the
+     * request referenced.
+     */
+    rejection?: "zero_data_retention" | "previous_response" | "stored_item";
     /** When a threaded session switched to explicit_context (ISO-8601), and on which request. */
     switchedAt?: string;
     switchedAtRequest?: number;

package/dist/browser-control/client.js

@@ -23,7 +23,7 @@ export function createBrowserControlClient(options) {
     // The transport closes synchronously when its stream is already unusable, so its close handler
     // takes the state that exists before the transport does.
     const session = Object.assign(state, {
-        transport: new BrowserControlTransport(options.transport, (value) => acceptReply(session, value), (code) => closeClient(state, code)),
+        transport: new BrowserControlTransport(options.transport, (value) => acceptReply(session, value), (code, diagnostic) => closeClient(state, code, diagnostic)),
     });
     const executor = {
         stallRecovery: "fail_closed",
@@ -41,13 +41,13 @@ export function createBrowserControlClient(options) {
         },
     };
 }
-function closeClient(state, code) {
+function closeClient(state, code, diagnostic) {
     state.closed = true;
     const operation = state.pending;
     state.pending = undefined;
     if (operation) {
         operation.dispose();
-        operation.reject(new ComputerUseExecutorError(code, operation.written ? "outcome_uncertain" : "not_dispatched"));
+        operation.reject(new ComputerUseExecutorError(code, operation.written ? "outcome_uncertain" : "not_dispatched", { diagnostic }));
     }
 }
 /** Settles the pending exchange once both its reply has arrived and its request write finished. */
@@ -63,12 +63,12 @@ function finishExchange(session) {
     else if (operation.reply.ok)
         operation.resolve(operation.reply);
     else {
-        const { code, disposition } = operation.reply.error;
+        const { code, disposition, reason, diagnostic } = operation.reply.error;
         if (operation.request.operation !== "EXECUTE" ||
             code !== "action_rejected" ||
             disposition !== "not_dispatched")
             session.transport.close(code);
-        operation.reject(new ComputerUseExecutorError(code, disposition));
+        operation.reject(new ComputerUseExecutorError(code, disposition, { reason, diagnostic }));
     }
 }
 /** Matches a reply frame to the pending request; any mismatch closes the channel. */

package/dist/browser-control/protocol.d.ts

@@ -1,7 +1,8 @@
 import { z } from "zod";
 import type { CuaAction, CuaObservation } from "../actors/computer-use/loop.js";
 import { type HeardSpeech } from "../actors/computer-use/speech.js";
-import { type CuaExecutorErrorCode } from "../actors/computer-use/executor-error.js";
+import { type CuaExecutorErrorCode, type CuaRejectionReason } from "../actors/computer-use/executor-error.js";
+import { type CuaExecutorDiagnostic } from "../actors/computer-use/executor-diagnostic.js";
 export declare const BROWSER_CONTROL_VERSION = 1;
 export declare const BROWSER_CONTROL_LIMITS: Readonly<{
     frameBytes: number;
@@ -471,6 +472,32 @@ declare const replySchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
             not_dispatched: "not_dispatched";
             outcome_uncertain: "outcome_uncertain";
         }>;
+        reason: z.ZodOptional<z.ZodEnum<{
+            extra_tab: "extra_tab";
+        }>>;
+        diagnostic: z.ZodOptional<z.ZodObject<{
+            step: z.ZodEnum<{
+                cdp_detach: "cdp_detach";
+                cdp_session: "cdp_session";
+                channel: "channel";
+                channel_write: "channel_write";
+                focus_probe: "focus_probe";
+                frame_tree: "frame_tree";
+                insert_text: "insert_text";
+                isolated_world: "isolated_world";
+                owner_window_check: "owner_window_check";
+                text_port: "text_port";
+            }>;
+            category: z.ZodEnum<{
+                channel_closed: "channel_closed";
+                detached: "detached";
+                navigation: "navigation";
+                protocol_error: "protocol_error";
+                target_closed: "target_closed";
+                timeout: "timeout";
+                unknown: "unknown";
+            }>;
+        }, z.core.$strict>>;
     }, z.core.$strict>;
 }, z.core.$strict>], "ok">;
 export type BrowserControlRequest = z.infer<typeof requestSchema>;
@@ -488,5 +515,7 @@ export declare function decodeBrowserControlObservation(value: unknown): CuaObse
 export declare function safeBrowserControlFailure(error: unknown, dispatched: boolean): {
     code: CuaExecutorErrorCode;
     disposition: "not_dispatched" | "outcome_uncertain";
+    reason?: CuaRejectionReason;
+    diagnostic?: CuaExecutorDiagnostic;
 };
 export {};

package/dist/browser-control/protocol.js

@@ -1,7 +1,8 @@
 import { PNG } from "pngjs";
 import { z } from "zod";
 import { CUA_SPEECH_LIMITS } from "../actors/computer-use/speech.js";
-import { ComputerUseExecutorError, isComputerUseExecutorError, } from "../actors/computer-use/executor-error.js";
+import { ComputerUseExecutorError, CUA_REJECTION_REASONS, isComputerUseExecutorError, } from "../actors/computer-use/executor-error.js";
+import { CUA_DIAGNOSTIC_CATEGORIES, CUA_DIAGNOSTIC_STEPS, } from "../actors/computer-use/executor-diagnostic.js";
 import { desktopRecordingMetadataSchema } from "../evidence/desktop-recording-types.js";
 export const BROWSER_CONTROL_VERSION = 1;
 export const BROWSER_CONTROL_LIMITS = Object.freeze({
@@ -194,6 +195,11 @@ const errorCode = z.enum([
     "action_rejected",
     "execution_failed",
 ]);
+// Two fixed words; a reply never carries browser error text.
+const diagnosticSchema = z.strictObject({
+    step: z.enum(CUA_DIAGNOSTIC_STEPS),
+    category: z.enum(CUA_DIAGNOSTIC_CATEGORIES),
+});
 const replyBase = {
     ...common,
     type: z.literal("reply"),
@@ -213,6 +219,8 @@ const replySchema = z.discriminatedUnion("ok", [
         error: z.strictObject({
             code: errorCode,
             disposition: z.enum(["not_dispatched", "outcome_uncertain"]),
+            reason: z.enum(CUA_REJECTION_REASONS).optional(),
+            diagnostic: diagnosticSchema.optional(),
         }),
     }),
 ]);
@@ -243,6 +251,9 @@ export function parseBrowserControlReply(value) {
         throw new ComputerUseExecutorError("invalid_response", "outcome_uncertain");
     const reply = parsed.data;
     if ((reply.operation === "EXECUTE") !== (reply.actionId !== undefined) ||
+        (!reply.ok &&
+            reply.error.reason !== undefined &&
+            (reply.error.code !== "action_rejected" || reply.error.disposition !== "not_dispatched")) ||
         (reply.ok &&
             ((reply.operation === "OBSERVE") !== (reply.observation !== undefined) ||
                 (reply.operation === "FINISH_RECORDING") !== (reply.recording !== undefined))))
@@ -351,8 +362,14 @@ export function decodeBrowserControlObservation(value) {
     };
 }
 export function safeBrowserControlFailure(error, dispatched) {
+    // Only a declared error's fixed diagnostic crosses; an arbitrary exception's text never does.
     if (isComputerUseExecutorError(error))
-        return { code: error.code, disposition: error.disposition };
+        return {
+            code: error.code,
+            disposition: error.disposition,
+            ...(error.reason === undefined ? {} : { reason: error.reason }),
+            ...(error.diagnostic === undefined ? {} : { diagnostic: { ...error.diagnostic } }),
+        };
     return {
         code: "action_rejected",
         disposition: dispatched ? "outcome_uncertain" : "not_dispatched",

package/dist/browser-control/transport.d.ts

@@ -1,5 +1,6 @@
 import type { Duplex } from "node:stream";
 import { type CuaExecutorErrorCode } from "../actors/computer-use/executor-error.js";
+import { type CuaExecutorDiagnostic } from "../actors/computer-use/executor-diagnostic.js";
 /** Owned byte channel only. This module never discovers endpoints or reconnects. */
 export declare class BrowserControlTransport {
     private readonly stream;
@@ -15,7 +16,7 @@ export declare class BrowserControlTransport {
     private pendingWrite;
     private frameTimer;
     private readonly decoder;
-    constructor(stream: Duplex, onFrame: (value: unknown) => void, onClose: (code: CuaExecutorErrorCode) => void);
+    constructor(stream: Duplex, onFrame: (value: unknown) => void, onClose: (code: CuaExecutorErrorCode, diagnostic: CuaExecutorDiagnostic | undefined) => void);
     get closed(): boolean;
     private data;
     /** Relinquish the live byte stream synchronously after a complete frame. */
@@ -23,5 +24,5 @@ export declare class BrowserControlTransport {
     private error;
     private end;
     send(value: unknown, beforeWrite?: () => void): Promise<void>;
-    close(code?: CuaExecutorErrorCode): void;
+    close(code?: CuaExecutorErrorCode, diagnostic?: CuaExecutorDiagnostic): void;
 }

package/dist/browser-control/transport.js

@@ -1,6 +1,7 @@
 import { TextDecoder } from "node:util";
 import { BROWSER_CONTROL_LIMITS } from "./protocol.js";
 import { ComputerUseExecutorError, } from "../actors/computer-use/executor-error.js";
+import { classifyExecutorFailure, } from "../actors/computer-use/executor-diagnostic.js";
 /** Owned byte channel only. This module never discovers endpoints or reconnects. */
 export class BrowserControlTransport {
     stream;
@@ -104,11 +105,15 @@ export class BrowserControlTransport {
         this.stream.off("error", this.error);
         return this.stream;
     }
-    error = () => {
-        this.close("transport_failed");
+    error = (error) => {
+        this.close("transport_failed", classifyExecutorFailure("channel", error));
     };
     end = () => {
-        this.close(this.payload || this.headerUsed ? "invalid_response" : "transport_failed");
+        const partial = this.payload !== undefined || this.headerUsed > 0;
+        this.close(partial ? "invalid_response" : "transport_failed", {
+            step: "channel",
+            category: "channel_closed",
+        });
     };
     send(value, beforeWrite = () => { }) {
         if (this.ended || this.handedOff)
@@ -149,7 +154,7 @@ export class BrowserControlTransport {
                 }
                 this.stream.write(frame, (error) => {
                     if (error) {
-                        this.close("transport_failed");
+                        this.close("transport_failed", classifyExecutorFailure("channel_write", error));
                         return;
                     }
                     done();
@@ -160,7 +165,7 @@ export class BrowserControlTransport {
             }
         });
     }
-    close(code = "executor_closed") {
+    close(code = "executor_closed", diagnostic) {
         if (this.ended || this.handedOff)
             return;
         this.ended = true;
@@ -178,12 +183,12 @@ export class BrowserControlTransport {
             this.stream.off("close", releaseListeners);
         };
         this.stream.once("close", releaseListeners);
-        this.pendingWrite?.(new ComputerUseExecutorError(code, "outcome_uncertain"));
+        this.pendingWrite?.(new ComputerUseExecutorError(code, "outcome_uncertain", { diagnostic }));
         this.stream.destroy();
         // A stream whose close event already happened will not emit it again. `closed`
         // can also precede queued error/close events, so defer removal past native ticks.
         if (this.stream.closed)
             setImmediate(releaseListeners);
-        this.onClose(code);
+        this.onClose(code, diagnostic);
     }
 }

package/dist/cli/commands/study-route-computer-use.js

@@ -13,7 +13,7 @@ import { writeRunFindings } from "../findings.js";
 import { formatCuaStudyHuman } from "./study-format.js";
 import { resolveRouteShouldOpen } from "./study-route-open.js";
 import { studyResultIdentity } from "../../run/study-result.js";
-import { actorOf, declaredParticipantCount } from "../../study/study-fields.js";
+import { declaredParticipantCount } from "../../study/study-fields.js";
 /**
  * The computer-use route's CLI setup: its settings, the watch and exposure plan, the runStudyWith options
  * with the live Observer hook, and how it presents the outcome or a run error. Undefined when
@@ -55,7 +55,7 @@ function refuseCua(args, dryRun, code, message) {
         ...studyResultIdentity("computer-use", args.config.id),
         ok: false,
         cwd: args.options.cwd,
-        actor: actorOf(args.config)?.type ?? "",
+        actor: args.config.actor?.type ?? "",
         appUrl: "",
         dryRun,
         runId: args.options.runId ?? "not-created",

package/dist/cli/commands/study-route-shared-world.js

@@ -10,7 +10,7 @@ import { writeRunFindings } from "../findings.js";
 import { formatConcurrentSharedWorldStudyHuman } from "./study-format.js";
 import { resolveRouteShouldOpen, watchFinishedPlan } from "./study-route-open.js";
 import { studyResultIdentity } from "../../run/study-result.js";
-import { actorOf, participantList } from "../../study/study-fields.js";
+import { participantList } from "../../study/study-fields.js";
 /**
  * The shared-world route's CLI setup: dry run, open and follow semantics, the live Observer server
  * the run attaches, and how it presents the outcome. Undefined when setup has already written its
@@ -34,7 +34,7 @@ export function sharedWorldRouteRun(args) {
             ...studyResultIdentity("shared-world", args.config.id),
             ok: false,
             cwd: args.options.cwd,
-            actor: actorOf(args.config)?.type ?? "",
+            actor: args.config.actor?.type ?? "",
             topology: "shared-world",
             topologyMode: "concurrent",
             roleCount: participantList(args.config)?.length ?? 0,

package/dist/cli/commands/study.js

@@ -4,7 +4,6 @@ import { Command, Option } from "commander";
 import { inspectStudyManifest, listStudyManifests } from "../../study/discover.js";
 import { runStudyPreflight, } from "../../study/preflight.js";
 import { applyEnvFileOption, CWD_OPTION_DESCRIPTION, DOTENV_OPTION_DESCRIPTION, dotenvPathOf, envFileAliasOption, JSON_OPTION_DESCRIPTION, parsePositiveInteger, writeResult, humanError, } from "../io.js";
-import { actorOf } from "../../study/study-fields.js";
 export function registerStudyCommands(parent, io) {
     const study = parent
         .command("study")
@@ -115,7 +114,7 @@ function formatStudyShowHuman(result) {
         `id: ${config.id}`,
         `subject: ${config.subject.source}`,
         ...(config.execution?.target ? [`execution: ${config.execution.target}`] : []),
-        `actor: ${actorOf(config)?.type ?? ""}`,
+        `actor: ${config.actor?.type ?? ""}`,
         ...(config.title ? [`title: ${config.title}`] : []),
         ...(config.description ? [`description: ${config.description}`] : []),
         ...(result.path ? [`path: ${result.path}`] : []),

package/dist/cli/doctor.js

@@ -336,6 +336,17 @@ function keyChecks(probes, receivingKey, setup, keyUsers) {
         const hint = probe.name === receivingKey
             ? `provide ${probe.name} through process env or --dotenv`
             : probe.hint;
+        if (probe.placeholder) {
+            // A participant in a terminal study's sandbox reads this row. It names the placeholder so the
+            // participant is not told it holds a key.
+            const required = setup?.keys.includes(probe.name) === true;
+            return {
+                name: `key ${probe.name}`,
+                ok: !required,
+                ...(required ? {} : { status: "note" }),
+                message: `not a key: ${probe.name} holds the placeholder humanish sets in a terminal study's sandbox, so no usable ${probe.name} is available here; ${hint}`,
+            };
+        }
         if (!setup) {
             const users = keyUsers?.get(probe.name) ?? [];
             const usedBy = users.length > 0 ? `used by ${studyList(users)}` : undefined;