humanish 0.140.0 → 0.142.0

package/dist/analysis/provider.d.ts

@@ -13,7 +13,7 @@ export interface AnalysisProviderRequest {
     timeoutMs: number;
     signal?: AbortSignal;
 }
-interface AnalysisTokenUsage {
+export interface AnalysisTokenUsage {
     input: number;
     output: number;
     cachedInput?: number;
@@ -40,10 +40,6 @@ export interface AnalysisProviderResult {
     protocolAdditions?: readonly string[];
 }
 export type AnalysisProvider = (request: AnalysisProviderRequest) => Promise<AnalysisProviderResult>;
-/** An input image the provider accepts; the groups are the image type and its base64 bytes. */
-export declare const INPUT_IMAGE_DATA_URL: RegExp;
-/** Text and usage wire shapes reuse the captured closing-report contract; refusal fails closed. */
-export declare function parseAnalysisResponse(raw: unknown): AnalysisProviderResult;
 /** The part of fetch this provider uses; undici's fetch and test doubles both satisfy it. */
 export type AnalysisFetch = (url: string, init: {
     method: "POST";
@@ -62,9 +58,21 @@ export type AnalysisFetch = (url: string, init: {
     status: number;
     body: ReadableStream<Uint8Array> | null;
 }>;
-/** No alternate endpoint or env-derived base URL: evidence and credentials have one destination. */
+/** The analysts humanish calls over HTTP with an API key. Codex runs through its own CLI. */
+export type AnalysisApiVendor = "openai" | "gemini";
+/** One vendor's wire format. The transport sends `body` to `url` with `headers` and gives `parse`
+ * the response JSON only after a 2xx status, within the byte cap and the deadline. */
+export interface AnalysisWire {
+    /** A fixed endpoint: never derived from env, so evidence and credentials have one destination. */
+    url(model: string): string;
+    headers(apiKey: string): Record<string, string>;
+    body(request: AnalysisProviderRequest): unknown;
+    parse(raw: unknown): AnalysisProviderResult;
+}
+/** One request to the vendor's fixed endpoint, never retried and never sent elsewhere. */
 export declare function createAnalysisProvider(options: {
     apiKey: string;
+    /** Omitted is OpenAI, the analyst humanish has always called. */
+    vendor?: AnalysisApiVendor;
     fetchFn?: AnalysisFetch;
 }): AnalysisProvider;
-export {};

package/dist/analysis/provider.js

@@ -1,13 +1,17 @@
+// The analysis provider seam and the HTTP transport its API adapters share. Each API vendor owns
+// only its wire format (gemini-wire.ts, openai-wire.ts): the endpoint, the request body, and how a
+// response becomes a result. The transport owns what must hold for every vendor: one fixed endpoint
+// per vendor, request and response byte caps, the caller's wall-clock deadline, no retry, and a
+// closed error vocabulary that never carries provider error prose. The Codex account analyst is
+// the third adapter at the same seam (restricted-codex.ts).
 import { Agent, fetch as undiciFetch } from "undici";
-import { OPENAI_RESPONSES_URL } from "../actors/openai-endpoint.js";
+import { isRecord } from "../run/type-guards.js";
+import { INPUT_IMAGE_DATA_URL } from "./image-tokens.js";
+import { geminiWire } from "./gemini-wire.js";
+import { openaiWire } from "./openai-wire.js";
 const MAX_RESPONSE_BYTES = 2 * 1024 * 1024;
 const MAX_REQUEST_BYTES = 32 * 1024 * 1024;
-/** An input image the provider accepts; the groups are the image type and its base64 bytes. */
-export const INPUT_IMAGE_DATA_URL = /^data:image\/(png|jpeg|webp);base64,([A-Za-z0-9+/]+={0,2})$/;
-const record = (value) => value !== null && typeof value === "object" && !Array.isArray(value)
-    ? value
-    : {};
-const count = (value) => Number.isSafeInteger(value) && value >= 0 && value <= 1e12;
+const record = (value) => (isRecord(value) ? value : {});
 /** Undici's fetch has a separate response-header deadline. The caller's wall-clock
  * deadline must govern this one request, including uploads and body reads, without
  * changing transport behavior for other requests in the process. The agent is used with
@@ -41,72 +45,14 @@ function networkErrorCode(error) {
     }
     return "provider_network_error";
 }
-function usageOf(raw) {
-    const usage = record(record(raw).usage);
-    const details = record(usage.input_tokens_details);
-    const input = usage.input_tokens;
-    const output = usage.output_tokens;
-    const cachedInput = details.cached_tokens;
-    const cacheWriteInput = details.cache_write_tokens;
-    if (!count(input) ||
-        !count(output) ||
-        (cachedInput !== undefined && !count(cachedInput)) ||
-        (cacheWriteInput !== undefined && !count(cacheWriteInput)) ||
-        (cachedInput ?? 0) + (cacheWriteInput ?? 0) >
-            input)
-        return null;
-    return {
-        input,
-        output,
-        ...(cachedInput === undefined ? {} : { cachedInput: cachedInput }),
-        ...(cacheWriteInput === undefined ? {} : { cacheWriteInput: cacheWriteInput }),
-    };
-}
-/** Text and usage wire shapes reuse the captured closing-report contract; refusal fails closed. */
-export function parseAnalysisResponse(raw) {
-    const root = record(raw);
-    const usage = usageOf(raw);
-    const output = Array.isArray(root.output) ? root.output : [];
-    const contents = output
-        .filter((item) => record(item).type === "message")
-        .flatMap((item) => Array.isArray(record(item).content) ? record(item).content : []);
-    const base = { output: null, usage, dispatched: true };
-    if (contents.some((item) => record(item).type === "refusal")) {
-        return { ...base, status: "refused", errorCode: "refusal" };
-    }
-    if (root.status === "incomplete")
-        return { ...base, status: "incomplete", errorCode: "output_incomplete" };
-    if (root.status !== "completed" ||
-        output.some((item) => !["message", "reasoning"].includes(String(record(item).type)))) {
-        return { ...base, status: "failed", errorCode: "invalid_response" };
-    }
-    // A single JSON answer is expected. Do not concatenate multiple answer objects or expose a
-    // refusal, reasoning item, or incomplete message as the report's prose.
-    const messages = output.filter((item) => record(item).type === "message");
-    const texts = contents.filter((item) => record(item).type === "output_text");
-    if (messages.length !== 1 ||
-        record(messages[0]).status !== "completed" ||
-        record(messages[0]).role !== "assistant" ||
-        texts.length !== 1 ||
-        contents.length !== 1 ||
-        typeof record(texts[0]).text !== "string") {
-        return { ...base, status: "failed", errorCode: "invalid_response" };
-    }
-    try {
-        return {
-            ...base,
-            status: "completed",
-            output: JSON.parse(record(texts[0]).text),
-            errorCode: null,
-        };
-    }
-    catch {
-        return { ...base, status: "failed", errorCode: "invalid_response" };
-    }
-}
-/** No alternate endpoint or env-derived base URL: evidence and credentials have one destination. */
+const WIRES = {
+    openai: openaiWire,
+    gemini: geminiWire,
+};
+/** One request to the vendor's fixed endpoint, never retried and never sent elsewhere. */
 export function createAnalysisProvider(options) {
     const fetchFn = options.fetchFn ?? undiciFetch;
+    const wire = WIRES[options.vendor ?? "openai"];
     return async (request) => {
         const failure = (errorCode, dispatched, status = "failed") => ({
             status,
@@ -130,33 +76,7 @@ export function createAnalysisProvider(options) {
             request.images.some((image) => !INPUT_IMAGE_DATA_URL.test(image.dataUrl))) {
             return failure("invalid_request", false);
         }
-        const content = [
-            { type: "input_text", text: request.evidence },
-            ...request.images.flatMap((image) => [
-                { type: "input_text", text: JSON.stringify({ captureEvidenceId: image.evidenceId }) },
-                { type: "input_image", image_url: image.dataUrl, detail: "high" },
-            ]),
-        ];
-        const body = JSON.stringify({
-            model: request.model,
-            instructions: request.instructions,
-            input: [{ role: "user", content }],
-            store: false,
-            tools: [],
-            tool_choice: "none",
-            truncation: "disabled",
-            service_tier: "default",
-            reasoning: { effort: "high" },
-            max_output_tokens: request.maxOutputTokens,
-            text: {
-                format: {
-                    type: "json_schema",
-                    name: "study_analysis",
-                    strict: true,
-                    schema: request.schema,
-                },
-            },
-        });
+        const body = JSON.stringify(wire.body(request));
         if (Buffer.byteLength(body) > MAX_REQUEST_BYTES)
             return failure("invalid_request", false);
         const controller = new AbortController();
@@ -173,11 +93,11 @@ export function createAnalysisProvider(options) {
             if (request.signal?.aborted)
                 return failure("cancelled", false, "cancelled");
             dispatched = true;
-            const response = await fetchFn(OPENAI_RESPONSES_URL, {
+            const response = await fetchFn(wire.url(request.model), {
                 method: "POST",
                 redirect: "error",
                 signal: controller.signal,
-                headers: { Authorization: `Bearer ${options.apiKey}`, "Content-Type": "application/json" },
+                headers: wire.headers(options.apiKey),
                 body,
                 dispatcher,
                 timeout: false,
@@ -211,7 +131,7 @@ export function createAnalysisProvider(options) {
             if (controller.signal.aborted)
                 return failure(timedOut ? "timeout" : "cancelled", true, timedOut ? "timed_out" : "cancelled");
             try {
-                return parseAnalysisResponse(JSON.parse(Buffer.concat(chunks).toString("utf8")));
+                return wire.parse(JSON.parse(Buffer.concat(chunks).toString("utf8")));
             }
             catch {
                 return failure("invalid_response", true);

package/dist/analysis/recording-ended.d.ts

@@ -0,0 +1,16 @@
+import { type RunStatusRecord } from "../run/status.js";
+/** What the gate reads: the run's status record, when it has one, and its streams. */
+export interface RecordingFacts {
+    runId: string;
+    status: RunStatusRecord | undefined;
+    /** How many of the bundle's streams are still running or still hold live items. */
+    runningStreams: number;
+    streams: number;
+}
+/**
+ * Throws the refusal for a recording that has not ended. A `finished` record, an `interrupted`
+ * one, and a stale `running` one whose process is gone from this host have ended; analysis then
+ * also needs every stream ended. A fresh `running` record is a live run, and a stale one whose pid
+ * is still in use cannot be told apart from a live run, so both are refused.
+ */
+export declare function assertRecordingEnded(facts: RecordingFacts, nowMs?: number, processRunning?: (pid: number) => boolean): void;

package/dist/analysis/recording-ended.js

@@ -0,0 +1,29 @@
+// Whether a run's recording has ended, so analysis can read it: the completion gate's reading of
+// status.json and the bundle's streams. A refusal says what the run is doing and the command that
+// moves it on, since "wait" helps only a run that is still alive.
+import { cli } from "../cli/invocation.js";
+import { classifyRunStatus, runOwnerGone } from "../run/status.js";
+import { studyProvenanceOf } from "../run/study-provenance.js";
+import { AnalysisSourceRefusedError } from "./source.js";
+/**
+ * Throws the refusal for a recording that has not ended. A `finished` record, an `interrupted`
+ * one, and a stale `running` one whose process is gone from this host have ended; analysis then
+ * also needs every stream ended. A fresh `running` record is a live run, and a stale one whose pid
+ * is still in use cannot be told apart from a live run, so both are refused.
+ */
+export function assertRecordingEnded(facts, nowMs = Date.now(), processRunning) {
+    const { runId, status } = facts;
+    const runs = `\`${cli("runs")}\``;
+    if (status?.state === "running") {
+        if (classifyRunStatus(status, nowMs) === "running")
+            throw new AnalysisSourceRefusedError("ANALYSIS_RUN_ACTIVE", `Participants are still running in this run, so its recording has not ended. Automatic analysis starts when they finish; ${runs} shows when the run is analyzing.`);
+        if (!runOwnerGone(status, nowMs, processRunning))
+            throw new AnalysisSourceRefusedError("ANALYSIS_RUN_UNCONFIRMED", `This run's process stopped updating status.json at ${status.updatedAt}, but pid ${status.pid} is still in use on this machine, so humanish cannot tell whether the run is still writing. If the run is gone, \`${cli(`reclaim --run ${runId}`)}\` stops its sandboxes and marks it interrupted; then analyze it again.`);
+    }
+    if (facts.runningStreams === 0)
+        return;
+    if (status?.state === "finished")
+        throw new AnalysisSourceRefusedError("ANALYSIS_RUN_ACTIVE", `${facts.runningStreams} of ${facts.streams} participant streams in this run have not ended. ${runs} shows the run's state.`);
+    const study = status === undefined ? undefined : studyProvenanceOf(status)?.id;
+    throw new AnalysisSourceRefusedError("ANALYSIS_RUN_INCOMPLETE", `This run ended while ${facts.runningStreams} of ${facts.streams} participant streams were still running, so its recording is incomplete and is not analyzed. Run the study again with \`${cli(`run ${study ?? "<study>"}`)}\`.`);
+}

package/dist/analysis/responses.d.ts

@@ -15,5 +15,8 @@ export declare function checkProviderAnalysis(input: AnalysisInput, value: unkno
  * each response as its own request, since the long-context tier re-prices one request at a time.
  */
 export declare function recordProviderUsage(artifact: AnalysisArtifact, config: AnalysisConfig, responses: readonly AnalysisProviderResult[]): void;
+/** The HTTP status an API analyst answered, for the attempt's warnings. The status code is the only
+ * part of the answer kept: the provider's error text may echo evidence or credentials. */
+export declare function httpStatusWarning(config: AnalysisConfig, response: AnalysisProviderResult): string | undefined;
 /** The warnings a Codex response carries about its CLI release and protocol. */
 export declare function codexWarnings(config: AnalysisConfig, response: AnalysisProviderResult): string[];

package/dist/analysis/responses.js

@@ -185,6 +185,25 @@ export function recordProviderUsage(artifact, config, responses) {
     usage.estimatedCostUsd = priced.estimatedCostUsd;
     usage.ratesAsOf = priced.ratesAsOf;
 }
+/** What an HTTP status from an analysis API most likely means, by status. */
+const HTTP_STATUS_MEANINGS = {
+    400: "it refused the request as invalid",
+    401: "it refused the key",
+    403: "the key has no access to this model",
+    404: "it does not know this model",
+    429: "a rate or quota limit of the key's plan was reached",
+    500: "a server error; a later attempt can succeed",
+    503: "the model is overloaded or unavailable; a later attempt can succeed",
+};
+/** The HTTP status an API analyst answered, for the attempt's warnings. The status code is the only
+ * part of the answer kept: the provider's error text may echo evidence or credentials. */
+export function httpStatusWarning(config, response) {
+    if (response.httpStatus === undefined)
+        return undefined;
+    const api = config.provider === "gemini" ? "Gemini" : "OpenAI";
+    const meaning = HTTP_STATUS_MEANINGS[response.httpStatus];
+    return `The ${api} API answered HTTP ${response.httpStatus}${meaning === undefined ? "" : ` (${meaning})`}. humanish does not retry an analysis request; run the command again to retry.`;
+}
 /** The warnings a Codex response carries about its CLI release and protocol. */
 export function codexWarnings(config, response) {
     if (config.provider !== "codex")

package/dist/analysis/service.d.ts

@@ -58,9 +58,7 @@ export declare function resolveAnalysisRun(cwd: string, run: string, expectedRun
 export declare function dryRunBundleRefusal(cwd: string, run: string, dryRun: boolean, expectedRun?: PreparedRunArtifactPaths): Promise<AnalyzeResult | null>;
 /** Re-render the run's Observer after an analysis write. False when it could not be refreshed. */
 export declare function refreshObserver(cwd: string, runId: string, prepared: PreparedRunArtifactPaths): Promise<boolean>;
-/** One analysis or correction writer per run. Never steal a lock based on an untrusted PID. */
-export declare function withAnalysisLock<T>(prepared: PreparedRunArtifactPaths, action: () => Promise<T>): Promise<T>;
-/** The completion gate: the run verifies, is live and finished, and has participants. */
+/** The completion gate: the run verifies, is live, its recording ended, and it has participants. */
 export declare function readCompletedAnalysisSource(cwd: string, prepared: PreparedRunArtifactPaths): Promise<Buffer>;
 export declare function analyzeRun(cwdInput: string, run: string, options: AnalyzeOptions, deps?: AnalyzeDeps): Promise<AnalyzeResult>;
 export declare function showAnalysis(cwd: string, run: string, id?: string): Promise<LoadedAnalysis>;

package/dist/analysis/service.js

@@ -1,7 +1,8 @@
 import { defaultCodexCliVersion, describeCodexCliAdmission, } from "../actors/codex/codex-admission.js";
 import { validCodexAnalysisConfig } from "./codex-config.js";
+import { analysisApiKey, analysisKeyNames, missingKeyHint } from "../keys/key-resolution.js";
 import { randomUUID } from "node:crypto";
-import { lstat, mkdir, realpath, rmdir } from "node:fs/promises";
+import { realpath } from "node:fs/promises";
 import path from "node:path";
 import { renderObserver } from "../observer/render.js";
 import { containsSensitive } from "../evidence/redaction.js";
@@ -11,6 +12,8 @@ import { verifyRunPrepared } from "../verify/verify.js";
 import { loadRunBundlePrepared, resolveRunPath } from "../run/locate.js";
 import { physicalCwdOf, runIdOf, resolvePhysicalCwd, validatePreparedRunRootIdentity, } from "../run/paths.js";
 import { isRunStatusRecord, RUN_STATUS_FILE } from "../run/status.js";
+import { assertRecordingEnded } from "./recording-ended.js";
+import { withAnalysisLock } from "./analysis-lock.js";
 import { captureEvidence, EVIDENCE_LIMITS } from "./evidence.js";
 import { AnalysisSourceRefusedError, runFileTooLarge, throwAsAnalysisRefusal } from "./source.js";
 import { pathMissing, readBoundedFile, readBoundedFileResult } from "../run/evidence-files.js";
@@ -46,14 +49,14 @@ export async function resolveAnalysisRun(cwd, run, expectedRun) {
 const messages = {
     ANALYSIS_RUN_NOT_FOUND: "The selected run is unavailable or its storage is unsafe.",
     ANALYSIS_VERIFY_FAILED: "The run must pass verification before analysis.",
-    ANALYSIS_RUN_ACTIVE: "Analysis requires a completed recording. Wait for the study to finish.",
+    ANALYSIS_RUN_ACTIVE: "This run's status.json is missing, unreadable or names another run, so humanish cannot tell whether its recording has ended. `humanish verify` checks the run's files.",
     ANALYSIS_NO_PARTICIPANTS: "This run contains no participant evidence to analyze.",
     ANALYSIS_REQUIRES_LIVE_RUN: "A dry run has no participant behavior to analyze. Select a completed live run.",
     ANALYSIS_SOURCE_UNAVAILABLE: "The source recording is missing or unsafe.",
     ANALYSIS_SOURCE_CHANGED: "The source recording changed during analysis. The result cannot be published against different evidence.",
-    ANALYSIS_BUSY: "Another analysis holds this run's .analysis-lock directory. If it was interrupted, confirm it has stopped before removing that empty directory.",
+    ANALYSIS_BUSY: "Another analysis holds this run's .analysis-lock directory, and its process is still running or humanish cannot check it (another host, or a lock written by humanish 0.139.1 or earlier). Wait for it to finish; if no humanish process is running for this run, remove that directory.",
     ANALYSIS_HISTORY_UNAVAILABLE: "Analysis history is unavailable or full. No request was sent. Inspect this run's analysis and analysis-attempts storage before retrying.",
-    ANALYSIS_CONFIG_INVALID: "OpenAI analysis needs a supported model, positive USD admission limit and 256–32768 output tokens. Codex account analysis uses its qualified model and null dollar/output-token caps. Both require timeout 1–600000 ms.",
+    ANALYSIS_CONFIG_INVALID: "OpenAI and Gemini analysis need a supported model of that provider, a positive USD admission limit and 256–32768 output tokens. Codex account analysis uses its qualified model and null dollar/output-token caps. All require timeout 1–600000 ms.",
     ANALYSIS_QUESTION_UNSAFE: "The reviewer question matched a sensitive-text pattern. Remove sensitive details before retrying.",
     ANALYSIS_API_KEY_MISSING: "Set OPENAI_API_KEY to run analysis. --dry-run checks admission without a key or provider request.",
     ANALYSIS_CANCELLED: "Analysis was cancelled before dispatch.",
@@ -109,43 +112,7 @@ export async function refreshObserver(cwd, runId, prepared) {
         return false;
     }
 }
-/** One analysis or correction writer per run. Never steal a lock based on an untrusted PID. */
-export async function withAnalysisLock(prepared, action) {
-    await validatePreparedRunRootIdentity(prepared);
-    const target = path.join(prepared.physicalRunRoot, ".analysis-lock");
-    try {
-        await mkdir(target, { mode: 0o700 });
-    }
-    catch (error) {
-        if (error.code === "EEXIST")
-            throw new Error("ANALYSIS_BUSY");
-        throw new Error("ANALYSIS_UNAVAILABLE");
-    }
-    const identity = await lstat(target, { bigint: true });
-    try {
-        await validatePreparedRunRootIdentity(prepared);
-        if (!identity.isDirectory() || identity.isSymbolicLink())
-            throw new Error("ANALYSIS_UNAVAILABLE");
-        return await action();
-    }
-    finally {
-        // Only remove our empty, unchanged directory. No recursive deletion and no replacement authority.
-        try {
-            await validatePreparedRunRootIdentity(prepared);
-            const current = await lstat(target, { bigint: true });
-            if (current.isDirectory() &&
-                !current.isSymbolicLink() &&
-                current.dev === identity.dev &&
-                current.ino === identity.ino &&
-                current.birthtimeNs === identity.birthtimeNs)
-                await rmdir(target);
-        }
-        catch {
-            /* Leave ambiguous storage in place for explicit operator inspection. */
-        }
-    }
-}
-/** The completion gate: the run verifies, is live and finished, and has participants. */
+/** The completion gate: the run verifies, is live, its recording ended, and it has participants. */
 export async function readCompletedAnalysisSource(cwd, prepared) {
     const read = await readBoundedFileResult(prepared, RUN_BUNDLE_FILE, EVIDENCE_LIMITS.sourceBytes);
     if (read.state === "limit")
@@ -170,18 +137,19 @@ export async function readCompletedAnalysisSource(cwd, prepared) {
         if (!missing)
             throw new Error("ANALYSIS_RUN_ACTIVE");
     }
+    let status;
     if (statusBytes) {
-        const status = JSON.parse(statusBytes.toString("utf8"));
-        // An old heartbeat is unknown, not proof that a process stopped writing evidence.
-        if (!isRunStatusRecord(status) ||
-            status.runId !== loaded.bundle.runId ||
-            status.state !== "finished") {
+        const record = JSON.parse(statusBytes.toString("utf8"));
+        if (!isRunStatusRecord(record) || record.runId !== loaded.bundle.runId)
             throw new Error("ANALYSIS_RUN_ACTIVE");
-        }
-    }
-    if (loaded.bundle.streams.some((stream) => !TERMINAL_SIMULATION_STATUSES.has(stream.status) || stream.liveActor !== undefined)) {
-        throw new Error("ANALYSIS_RUN_ACTIVE");
+        status = record;
     }
+    assertRecordingEnded({
+        runId: loaded.bundle.runId,
+        status,
+        runningStreams: loaded.bundle.streams.filter((stream) => !TERMINAL_SIMULATION_STATUSES.has(stream.status) || stream.liveActor !== undefined).length,
+        streams: loaded.bundle.streams.length,
+    });
     return bytes;
 }
 /** The refusal code for a configuration analyzeRun cannot run, before any run file is read. */
@@ -318,9 +286,16 @@ async function executeAnalysis(attempt) {
     // An unreadable inventory is not evidence of an absent prior result.
     // Check readable history capacity before any new paid attempt.
     await assertAnalysisPublicationCapacity(prepared);
-    const apiKey = config.provider === "codex" ? "" : (deps.apiKey ?? process.env.OPENAI_API_KEY ?? "");
+    const apiKey = config.provider === "codex"
+        ? ""
+        : (deps.apiKey ?? analysisApiKey(config.provider ?? "openai", process.env));
     if (config.provider !== "codex" && !apiKey.trim())
-        return { ...fail(input.runId, false, "ANALYSIS_API_KEY_MISSING"), admission };
+        return {
+            ...fail(input.runId, false, "ANALYSIS_API_KEY_MISSING", config.provider === "gemini"
+                ? `Gemini analysis needs ${analysisKeyNames("gemini").join(" or ")}: ${missingKeyHint(analysisKeyNames("gemini")[0])}. --dry-run checks admission without a key or provider request.`
+                : undefined),
+            admission,
+        };
     let finalizeExecution;
     const rejection = {};
     const analysis = await runAnalysis(input, config, {
@@ -384,7 +359,13 @@ export async function analyzeRun(cwdInput, run, options, deps = {}) {
         if (deps.expectedRun !== undefined)
             cwd = physicalCwdOf(prepared);
         const execute = () => executeAnalysis({ cwd, run, prepared, config, options, deps, dryRun });
-        return dryRun ? await execute() : await withAnalysisLock(prepared, execute);
+        if (dryRun)
+            return await execute();
+        const tookOver = [];
+        const result = await withAnalysisLock(prepared, execute, (warning) => tookOver.push(warning));
+        return tookOver.length === 0
+            ? result
+            : { ...result, warnings: [...tookOver, ...result.warnings] };
     }
     catch (error) {
         if (error instanceof AnalysisSourceRefusedError)

package/dist/analysis/source.d.ts

@@ -7,7 +7,7 @@ import type { RunStream, StoredRunStream } from "../run/streams.js";
  */
 export declare class AnalysisSourceRefusedError extends Error {
     readonly reason: string;
-    constructor(code: "ANALYSIS_SOURCE_TOO_LARGE" | "ANALYSIS_SOURCE_INVALID", reason: string);
+    constructor(code: "ANALYSIS_SOURCE_TOO_LARGE" | "ANALYSIS_SOURCE_INVALID" | "ANALYSIS_RUN_ACTIVE" | "ANALYSIS_RUN_INCOMPLETE" | "ANALYSIS_RUN_UNCONFIRMED", reason: string);
 }
 /** The refusal of a run.json of `size` bytes, more than the `max` analysis reads of it. */
 export declare function runFileTooLarge(size: number | bigint, max: number): AnalysisSourceRefusedError;

package/dist/analysis/types.d.ts

@@ -161,6 +161,10 @@ interface OpenAIAnalysisConfig {
     timeoutMs: number;
     maxOutputTokens: number;
 }
+/** The Gemini API analyst: the same billed, capped request as OpenAI's, sent to Google. */
+interface GeminiAnalysisConfig extends Omit<OpenAIAnalysisConfig, "provider"> {
+    provider: "gemini";
+}
 /** Required, qualified execution profile, confirmed by the launcher before a turn.
  * A failed pre-dispatch artifact does not prove this CLI/model was observed.
  * These settings participate in cache and immutable attempt identity. */
@@ -184,7 +188,9 @@ export interface CodexAnalysisConfig {
     identity: CodexAnalysisIdentity;
 }
 /** Omitted provider remains the historical OpenAI API contract, including its exact hash. */
-export type AnalysisConfig = OpenAIAnalysisConfig | CodexAnalysisConfig;
+export type AnalysisConfig = OpenAIAnalysisConfig | GeminiAnalysisConfig | CodexAnalysisConfig;
+/** Who analyzed: an API billed by key (openai, gemini) or the restricted Codex account. */
+export type AnalysisProviderName = "openai" | "gemini" | "codex";
 export interface AnalysisUsage {
     inputTokens: number | null;
     outputTokens: number | null;
@@ -209,7 +215,7 @@ export interface AnalysisArtifact {
     configDigest: string;
     config: AnalysisConfig;
     promptVersion: string;
-    provider: "openai" | "codex";
+    provider: AnalysisProviderName;
     usage: AnalysisUsage;
     participants: AnalysisParticipantInput[];
     coverage: AnalysisCoverage;

package/dist/analysis/validation.d.ts

@@ -233,6 +233,7 @@ declare const analysisExecutionReceiptSchema: z.ZodObject<{
     promptVersion: z.ZodString;
     provider: z.ZodEnum<{
         codex: "codex";
+        gemini: "gemini";
         openai: "openai";
     }>;
     usage: z.ZodObject<{

package/dist/analysis/validation.js

@@ -196,6 +196,15 @@ const analysisParticipantProvenanceSchema = z
         .nullable(),
 })
     .strict();
+/** The configuration of an analyst billed by API key. Stored artifacts keep the bounds of every
+ * release that wrote them; admission checks the current ones before a request. */
+const apiAnalysisConfigSchema = z.object({
+    model: label,
+    question: text(4000).nullable(),
+    maxCostUsd: z.number().positive().max(1000),
+    timeoutMs: z.number().int().positive().max(3600000),
+    maxOutputTokens: z.number().int().positive().max(128000),
+});
 const analysisArtifactSchema = z
     .object({
     schema: z.literal(ANALYSIS_SCHEMA),
@@ -209,16 +218,8 @@ const analysisArtifactSchema = z
     inputDigest: digest,
     configDigest: digest,
     config: z.union([
-        z
-            .object({
-            provider: z.literal("openai").optional(),
-            model: label,
-            question: text(4000).nullable(),
-            maxCostUsd: z.number().positive().max(1000),
-            timeoutMs: z.number().int().positive().max(3600000),
-            maxOutputTokens: z.number().int().positive().max(128000),
-        })
-            .strict(),
+        apiAnalysisConfigSchema.extend({ provider: z.literal("openai").optional() }).strict(),
+        apiAnalysisConfigSchema.extend({ provider: z.literal("gemini") }).strict(),
         z
             .object({
             provider: z.literal("codex"),
@@ -243,7 +244,7 @@ const analysisArtifactSchema = z
             .strict(),
     ]),
     promptVersion: label,
-    provider: z.enum(["openai", "codex"]),
+    provider: z.enum(["openai", "gemini", "codex"]),
     usage: z
         .object({
         cacheWriteInputTokens: z.number().int().min(0).max(1e12).nullable(),
@@ -547,7 +548,7 @@ export function validateAnalysisExecutionReceipt(value) {
     const parsed = analysisExecutionReceiptSchema.safeParse(value);
     if (!parsed.success || Date.parse(parsed.data.completedAt) < Date.parse(parsed.data.createdAt))
         throw new Error("ANALYSIS_RECEIPT_INVALID");
-    if ((parsed.data.provider === "openai" && parsed.data.maxCostUsd === null) ||
+    if ((parsed.data.provider !== "codex" && parsed.data.maxCostUsd === null) ||
         (parsed.data.provider === "codex" &&
             (parsed.data.maxCostUsd !== null ||
                 parsed.data.usage.estimatedCostUsd !== null ||

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

@@ -287,6 +287,10 @@ declare const observationSchema: z.ZodObject<{
         text: z.ZodString;
         durationMs: z.ZodNumber;
     }, z.core.$strict>>>;
+    externalHandoffs: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        scheme: z.ZodString;
+        recipients: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>>;
 }, z.core.$strict>;
 type WireObservation = z.infer<typeof observationSchema>;
 declare const requestSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
@@ -503,6 +507,10 @@ declare const replySchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
             text: z.ZodString;
             durationMs: z.ZodNumber;
         }, z.core.$strict>>>;
+        externalHandoffs: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            scheme: z.ZodString;
+            recipients: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$strict>>>;
     }, z.core.$strict>>;
     recording: z.ZodOptional<z.ZodObject<{
         mimeType: z.ZodLiteral<"video/mp4">;

package/dist/browser-control/protocol.js

@@ -1,6 +1,7 @@
 import { PNG } from "pngjs";
 import { z } from "zod";
 import { CUA_SPEECH_LIMITS } from "../actors/computer-use/speech.js";
+import { EXTERNAL_HANDOFF_LIMITS } from "../actors/computer-use/external-handoff.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";
@@ -152,6 +153,17 @@ const heardSpeechListSchema = z
     .min(1)
     .max(BROWSER_CONTROL_LIMITS.heardSpeech)
     .refine((rows) => new Set(rows.map((row) => row.id)).size === rows.length);
+// The guest sends a handoff as externalHandoffOf made it: a scheme and a mailto link's recipients.
+const externalHandoffListSchema = z
+    .array(z.strictObject({
+    scheme: z.string().regex(/^[a-z][a-z0-9+.-]{0,31}$/),
+    recipients: z
+        .array(z.string().min(3).max(EXTERNAL_HANDOFF_LIMITS.addressLength))
+        .max(EXTERNAL_HANDOFF_LIMITS.recipients)
+        .optional(),
+}))
+    .min(1)
+    .max(EXTERNAL_HANDOFF_LIMITS.perObservation);
 const observationSchema = z.strictObject({
     png: z
         .string()
@@ -165,6 +177,7 @@ const observationSchema = z.strictObject({
     text: text.optional(),
     scrollY: coordinate.optional(),
     heardSpeech: heardSpeechListSchema.optional(),
+    externalHandoffs: externalHandoffListSchema.optional(),
 });
 const common = {
     version: z.literal(BROWSER_CONTROL_VERSION),
@@ -344,6 +357,9 @@ export function encodeBrowserControlObservation(observation) {
         ...(observation.text !== undefined ? { text: observation.text } : {}),
         ...(observation.scrollY !== undefined ? { scrollY: observation.scrollY } : {}),
         ...(observation.heardSpeech !== undefined ? { heardSpeech: observation.heardSpeech } : {}),
+        ...(observation.externalHandoffs !== undefined
+            ? { externalHandoffs: observation.externalHandoffs }
+            : {}),
     });
     if (!parsed.success)
         throw new ComputerUseExecutorError("invalid_response", "outcome_uncertain");
@@ -366,6 +382,11 @@ export function decodeBrowserControlObservation(value) {
         ...(state.text !== undefined ? { text: state.text } : {}),
         ...(state.scrollY !== undefined ? { scrollY: state.scrollY } : {}),
         ...(state.heardSpeech !== undefined ? { heardSpeech: state.heardSpeech } : {}),
+        ...(state.externalHandoffs !== undefined
+            ? {
+                externalHandoffs: state.externalHandoffs.map(({ scheme, recipients }) => recipients === undefined ? { scheme } : { scheme, recipients }),
+            }
+            : {}),
     };
 }
 export function safeBrowserControlFailure(error, dispatched) {