humanish 0.141.0 → 0.142.0

package/dist/analysis/image-tokens.js

@@ -1,22 +1,40 @@
+/** An input image the analysis providers accept; 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})$/;
 /**
- * Input tokens one image costs at `detail: "high"`, which is what the provider request sends.
+ * Input tokens one image costs at the detail the provider request sends: `detail: "high"` on
+ * OpenAI, MEDIA_RESOLUTION_HIGH on Gemini.
  *
  * OpenAI's vision guide (https://developers.openai.com/api/docs/guides/images-vision, read
  * 2026-09-30) prices these patch-based models by 32 px patches: ceil(width / 32) × ceil(height /
  * 32), scaled down to the model's high-detail patch budget, then ceil(patches × multiplier).
  * Scaling down only removes patches, so min(patches, budget) bounds the billed count from above.
  * The guide lists a 2,500-patch high budget and a 1.2 multiplier for each model below; its own
- * examples are 1024×1024 → 1,229 tokens and 2048×2048 → 3,000.
+ * examples are 1024×1024 → 1,229 tokens and 2048×2048 → 3,000. It does not list gpt-6-luna or
+ * gpt-6.1-sol (read 2026-10-21). Their entries copy gpt-6-astra's because OpenAI billed the same
+ * image tokens on all three on 2026-10-21, within the guide's one-token rounding.
  */
 const HIGH_DETAIL_SIZING = Object.freeze({
     "gpt-6-astra": { patchBudget: 2500, multiplierTenths: 12 },
+    "gpt-6.1-sol": { patchBudget: 2500, multiplierTenths: 12 },
+    "gpt-6-luna": { patchBudget: 2500, multiplierTenths: 12 },
     "gpt-5.6-sol": { patchBudget: 2500, multiplierTenths: 12 },
     "gpt-5.6-terra": { patchBudget: 2500, multiplierTenths: 12 },
     "gpt-5.6-luna": { patchBudget: 2500, multiplierTenths: 12 },
     "gpt-5.5": { patchBudget: 2500, multiplierTenths: 12 },
 });
 /** 2,500 patches × 1.2: what any image costs on these models when its size is unknown. */
-export const HIGH_DETAIL_IMAGE_TOKEN_CEILING = 3000;
+const HIGH_DETAIL_IMAGE_TOKEN_CEILING = 3000;
+/**
+ * Gemini bills an image by its media resolution, not its size. The provider sends every capture at
+ * MEDIA_RESOLUTION_HIGH, which the media-resolution guide
+ * (ai.google.dev/gemini-api/docs/media-resolution, read 2026-10-21) gives as at most 1,120 tokens
+ * for an image on Gemini 3 and Gemini 4 models. A 1x1 PNG at that setting was billed 1,089.
+ */
+const GEMINI_HIGH_RESOLUTION_IMAGE_TOKENS = Object.freeze({
+    "gemini-3.8-flash": 1120,
+});
+/** The most one image can cost on `model`, whatever its size. */
+export const imageTokenCeiling = (model) => GEMINI_HIGH_RESOLUTION_IMAGE_TOKENS[model] ?? HIGH_DETAIL_IMAGE_TOKEN_CEILING;
 const PNG_SIGNATURE = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
 /** Width and height from a PNG data URL's IHDR chunk; undefined for anything else. */
 function pngDimensions(dataUrl) {
@@ -31,6 +49,9 @@ function pngDimensions(dataUrl) {
     return width > 0 && height > 0 ? { width, height } : undefined;
 }
 export function highDetailImageTokens(model, dataUrl) {
+    const fixed = GEMINI_HIGH_RESOLUTION_IMAGE_TOKENS[model];
+    if (fixed !== undefined)
+        return fixed;
     const sizing = HIGH_DETAIL_SIZING[model];
     const size = sizing === undefined ? undefined : pngDimensions(dataUrl);
     if (sizing === undefined || size === undefined)

package/dist/analysis/job.d.ts

@@ -53,6 +53,7 @@ declare const jobSchema: z.ZodObject<{
         AUTOMATIC_ANALYSIS_CLEANUP_UNCONFIRMED: "AUTOMATIC_ANALYSIS_CLEANUP_UNCONFIRMED";
         AUTOMATIC_ANALYSIS_CODEX_UNAVAILABLE: "AUTOMATIC_ANALYSIS_CODEX_UNAVAILABLE";
         AUTOMATIC_ANALYSIS_FAILED: "AUTOMATIC_ANALYSIS_FAILED";
+        AUTOMATIC_ANALYSIS_GEMINI_KEY_MISSING: "AUTOMATIC_ANALYSIS_GEMINI_KEY_MISSING";
         AUTOMATIC_ANALYSIS_KEY_MISSING: "AUTOMATIC_ANALYSIS_KEY_MISSING";
         AUTOMATIC_ANALYSIS_LIMITATIONS: "AUTOMATIC_ANALYSIS_LIMITATIONS";
         AUTOMATIC_ANALYSIS_NO_PARTICIPANT_EVIDENCE: "AUTOMATIC_ANALYSIS_NO_PARTICIPANT_EVIDENCE";

package/dist/analysis/job.js

@@ -35,6 +35,7 @@ const reasons = [
     "AUTOMATIC_ANALYSIS_OUTCOME_UNKNOWN",
     "AUTOMATIC_ANALYSIS_SOURCE_UNAVAILABLE",
     "AUTOMATIC_ANALYSIS_KEY_MISSING",
+    "AUTOMATIC_ANALYSIS_GEMINI_KEY_MISSING",
     "AUTOMATIC_ANALYSIS_CODEX_UNAVAILABLE",
     "AUTOMATIC_ANALYSIS_ADMISSION_REFUSED",
     "AUTOMATIC_ANALYSIS_BUSY",

package/dist/analysis/openai-wire.d.ts

@@ -0,0 +1,5 @@
+import type { AnalysisProviderResult, AnalysisWire } from "./provider.js";
+/** Text and usage wire shapes reuse the captured closing-report contract; refusal fails closed. */
+export declare function parseAnalysisResponse(raw: unknown): AnalysisProviderResult;
+/** One stateless request: no stored response, no tools, high reasoning effort, strict schema. */
+export declare const openaiWire: AnalysisWire;

package/dist/analysis/openai-wire.js

@@ -0,0 +1,101 @@
+// The OpenAI Responses API wire format of one analysis request: what the request body says and how
+// a response becomes an AnalysisProviderResult. provider.ts owns the transport around it.
+import { OPENAI_RESPONSES_URL } from "../actors/openai-endpoint.js";
+import { isRecord } from "../run/type-guards.js";
+const record = (value) => (isRecord(value) ? value : {});
+const count = (value) => Number.isSafeInteger(value) && value >= 0 && value <= 1e12;
+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" };
+    }
+}
+/** One stateless request: no stored response, no tools, high reasoning effort, strict schema. */
+export const openaiWire = {
+    url: () => OPENAI_RESPONSES_URL,
+    headers: (apiKey) => ({ Authorization: `Bearer ${apiKey}`, "Content-Type": "application/json" }),
+    body: (request) => ({
+        model: request.model,
+        instructions: request.instructions,
+        input: [
+            {
+                role: "user",
+                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" },
+                    ]),
+                ],
+            },
+        ],
+        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 },
+        },
+    }),
+    parse: parseAnalysisResponse,
+};

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/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.js

@@ -1,5 +1,6 @@
 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 { realpath } from "node:fs/promises";
 import path from "node:path";
@@ -55,7 +56,7 @@ const messages = {
     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, 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.",
@@ -285,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, {

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/cli/commands/analyze.js

@@ -1,8 +1,10 @@
-import { analysisRequestsText, resolveAutomaticAnalysis, DEFAULT_ANALYSIS_MODEL, DEFAULT_ANALYSIS_TIMEOUT_MS, } from "../../analysis/automatic-config.js";
+import { analysisRequestsText, resolveAutomaticAnalysis, DEFAULT_ANALYSIS_MODEL, DEFAULT_ANALYSIS_TIMEOUT_MS, DEFAULT_GEMINI_ANALYSIS_MODEL, } from "../../analysis/automatic-config.js";
 import { Command, Option } from "commander";
 import { forTerminal } from "../../routes/terminal/encoding.js";
 import { analyzeRun, correctAnalysis, dryRunBundleRefusal, showAnalysis, } from "../../analysis/service.js";
 import { admissionRule } from "../../analysis/admission.js";
+import { GEMINI_ANALYSIS_MODELS, SUPPORTED_ANALYSIS_MODELS, } from "../../analysis/execute.js";
+import { CODEX_ANALYSIS_MODEL } from "../../analysis/codex-config.js";
 import { listAnalyses } from "../../analysis/store.js";
 import { listAnalysisExecutions } from "../../analysis/store-executions.js";
 import { resolveRunPath } from "../../run/locate.js";
@@ -30,12 +32,12 @@ export function registerAnalyzeCommand(parent, io) {
         .summary("Analyze a live run into evidence-linked findings.")
         .option("--run <id>", RUN_OPTION_DESCRIPTION, "latest")
         .option("--cwd <path>", CWD_OPTION_DESCRIPTION, ".")
-        .option("--provider <name>", "Analyst: openai (default) or restricted codex account. No provider fallback.")
-        .option("--max-cost <usd>", `Required for OpenAI, also with --dry-run: an analysis is refused before it sends anything if ${admissionRule("this")}. It does not limit billing. Unsupported for Codex.`)
-        .option("--model <id>", "Supported vision model. OpenAI uses high effort; qualified Codex account analysis uses low effort.", DEFAULT_ANALYSIS_MODEL)
+        .option("--provider <name>", "Analyst: openai (default), gemini (sends the evidence and captures to Google), or restricted codex account. No provider fallback.")
+        .option("--max-cost <usd>", `Required for OpenAI and Gemini, also with --dry-run: an analysis is refused before it sends anything if ${admissionRule("this")}. It does not limit billing. Unsupported for Codex.`)
+        .option("--model <id>", `OpenAI analysis model, at high effort: ${SUPPORTED_ANALYSIS_MODELS.join(", ")}; ${DEFAULT_ANALYSIS_MODEL} when omitted. Gemini analysis model, at high thinking: ${GEMINI_ANALYSIS_MODELS.join(", ")}; ${DEFAULT_GEMINI_ANALYSIS_MODEL} when omitted. Codex account analysis runs ${CODEX_ANALYSIS_MODEL} at low effort.`)
         .option("--question <text>", "Additional reviewer question; does not change participant instructions.")
         .option("--timeout-ms <ms>", "Request timeout, at most 600000 ms.", String(DEFAULT_ANALYSIS_TIMEOUT_MS))
-        .option("--max-output-tokens <n>", "OpenAI response-token limit including reasoning, 256–32768. Omit for admission-based sizing. Unsupported for Codex.")
+        .option("--max-output-tokens <n>", "OpenAI or Gemini response-token limit including reasoning, 256–32768. Omit for admission-based sizing. Unsupported for Codex.")
         .option("--dry-run", "Capture and validate local input and estimate admission; no request or analysis artifact.")
         .option("--rerun", "Create a new immutable version even when the same input and configuration were analyzed.")
         .option("--json", JSON_OPTION_DESCRIPTION)
@@ -73,7 +75,7 @@ export function registerAnalyzeCommand(parent, io) {
 async function handleAnalyze(io, options, command) {
     const selected = resolveAutomaticAnalysis({
         ...(options.provider === undefined ? {} : { provider: options.provider }),
-        model: options.model,
+        ...(options.model === undefined ? {} : { model: options.model }),
         ...(options.question === undefined ? {} : { question: options.question }),
         timeoutMs: Number(options.timeoutMs),
         ...(options.provider === "codex" && options.maxCost === undefined
@@ -106,7 +108,7 @@ async function handleAnalyze(io, options, command) {
         io.setExitCode(2);
         return;
     }
-    // Only a live OpenAI analysis sends OPENAI_API_KEY. A dry run and the Codex account analyst
+    // Only a live OpenAI or Gemini analysis sends an API key. A dry run and the Codex account analyst
     // read no provider key, so they skip discovery and its `gh auth token` spawn.
     if (options.dryRun !== true && selected.config.provider !== "codex")
         await discoverCliKeys({ io, cwd: options.cwd });

package/dist/cli/commands/observe.js

@@ -1,9 +1,12 @@
+import { resolve } from "node:path";
 import { Command, Option } from "commander";
 import { openTarget, renderObserver, serveObserver } from "../../observer/render.js";
 import { SERVE_SCHEMA, serveObserverLibrary } from "../../observer/serve.js";
 import { startExposedObserver, validateExposure } from "../../observer/exposure.js";
 import { ServeTunnelError } from "../../observer/tunnel.js";
-import { collectRepeated, CWD_OPTION_DESCRIPTION, formatRunHuman, freePortOption, JSON_OPTION_DESCRIPTION, parseObserverPort, RUN_OPTION_DESCRIPTION, wantsJson, writeResult, } from "../io.js";
+import { reattachRemoteRun, remoteRunHere } from "../../remote/reattach.js";
+import { reportRemoteOutcome } from "./study-remote.js";
+import { collectRepeated, CWD_OPTION_DESCRIPTION, discoverCliKeys, formatRunHuman, freePortOption, JSON_OPTION_DESCRIPTION, parseObserverPort, RUN_OPTION_DESCRIPTION, wantsJson, writeResult, } from "../io.js";
 import { exitCodeForSignal, formatObserverHuman, personAtTerminal, unattendedObserverWarning, } from "../observer-follow.js";
 export function registerObserveCommand(parent, io) {
     addLibraryOptions(parent
@@ -116,6 +119,12 @@ async function observeRun(io, options, command) {
         io.setExitCode(2);
         return;
     }
+    // A remote run that is not copied back yet has no bundle here: follow it on its runner.
+    const remote = options.run === "latest" ? undefined : await remoteRunHere(options.cwd, options.run);
+    if (remote !== undefined) {
+        await observeRemoteRun(io, command, options.cwd, remote, port);
+        return;
+    }
     const rendered = await renderObserver(options.cwd, options.run, { open: false });
     if (!rendered.ok || !rendered.observerPath) {
         writeResult(command, io, rendered, formatObserverHuman);
@@ -405,3 +414,19 @@ function formatServeHuman(result) {
     }
     return lines.join("\n") + "\n";
 }
+async function observeRemoteRun(io, command, cwd, remote, port) {
+    await discoverCliKeys({ io, cwd });
+    const say = (line) => io.writeErr(`${line}\n`);
+    let outcome;
+    try {
+        outcome = await reattachRemoteRun({ cwd: resolve(cwd), env: process.env, say }, remote, port);
+    }
+    catch (error) {
+        outcome = {
+            runId: remote.runId,
+            exitCode: 2,
+            error: `could not reach its runner: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+    reportRemoteOutcome(command, io, resolve(cwd), outcome);
+}