humanish 0.140.0 → 0.142.0

package/ARCHITECTURE.md

@@ -86,6 +86,7 @@ the analysis of the run:
 | `src/actors/`              | The actor contract, the registry and each actor's session code                                                                  | `src/actors/registry.ts`            |
 | `src/subject/`             | Subject provisioning over a `Shell`: clone, local tree, desktop CLI, serve                                                      | `src/subject/serve.ts`              |
 | `src/substrates/`          | Provider primitives: E2B in `e2b/`, Firecracker and Lima VMs in `local/`, the `Shell`                                           | `src/substrates/desktop-session.ts` |
+| `src/remote/`              | `--remote`: plan a run for a runner sandbox, launch and follow it there, copy it back                                           | `src/remote/launch.ts`              |
 | `src/run/`                 | Run lifecycle, bundle types, bundle guards, paths, status, receipts, reclaim                                                    | `src/run/run.ts`                    |
 | `src/verify/`              | `humanish verify`: evidence checks, share-safety grades, cost and rerun checks                                                  | `src/verify/verify.ts`              |
 | `src/evidence/`            | Redaction, screenshot checks and desktop recordings                                                                             | `src/evidence/redaction.ts`         |

package/CHANGELOG.md

@@ -8,6 +8,29 @@ The Unreleased section holds the full notes for the next version until it is tag
 
 ## Unreleased
 
+## 0.142.0: Remote runs, Gemini and GPT-6 analysis models, and a view-only live stream (2026-10-21)
+
+humanish 0.142.0 can run a study remotely: `humanish run <study> --remote` puts the study's own
+process in a sandbox, so a long study keeps going after this machine sleeps, and `observe --run
+<id>` reconnects to it. Study analysis can run on `gpt-6.1-sol` and `gpt-6-luna` as well as the
+default `gpt-6-astra`, and on Google's Gemini API with `humanish keys set gemini`. A hosted
+desktop's live stream is now view-only on the VNC server itself: before, anyone holding a
+participant's stream URL could type into that desktop.
+
+[Release notes](https://github.com/danielgwilson/humanish/releases/tag/v0.142.0)
+
+## 0.141.0: A run says when it is writing findings, and email links no longer open a dialog (2026-10-21)
+
+humanish 0.141.0 says when a run is writing its findings: the CLI prints progress with the
+elapsed time, `humanish runs` and the TUI show `analyzing`, and the Observer's Findings tab shows a
+pending state from the moment analysis starts. A run cut off before it publishes is recorded as
+interrupted, `reclaim` marks a dead run, a killed analysis no longer blocks the next one, and
+`run` prints the run id as soon as it exists. On hosted and local desktops, a `mailto:`, `tel:`
+or `sms:` link no longer opens an app chooser or a browser prompt that participants reported as an
+app fault: humanish records the link and tells the participant that nothing was sent.
+
+[Release notes](https://github.com/danielgwilson/humanish/releases/tag/v0.141.0)
+
 ## 0.140.0: One local study can test phone, tablet and desktop, and every run ends with findings (2026-10-21)
 
 humanish 0.140.0 lets a local browser study give each participant its own device. One study with

package/README.md

@@ -242,6 +242,8 @@ beside Participants in Observer, with evidence links and separate participant
 feedback. You can explicitly select a restricted Codex account analyst with
 `npx humanish analyze --run latest --provider codex`; it uses remote inference,
 requires the qualified CLI and account login, and reports dollar cost as unknown.
+`npx humanish analyze --run latest --provider gemini --max-cost 2` sends the same
+evidence to Google's Gemini API instead, with the key from `npx humanish keys set gemini`.
 A study whose participant is a Codex `local-agent` uses that analyst by default. See the [analysis contract](docs/contracts/study-analysis.md) for
 coverage limits, estimated cost controls, corrections and sharing behavior.
 

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

@@ -42,7 +42,7 @@ function deferred() {
     return { promise, resolve, reject };
 }
 // prose-check: model prompt (Codex reads this tool description, not a person)
-const toolDescription = (speechEnabled, { maxWaitMs, watchMaxMs, idleWaitMs, }) => `Act on the participant's browser through humanish. Submit one to four UI actions${speechEnabled ? ", including speak when you need to reply aloud," : ""} and a short public comment; never private reasoning. humanish returns a JSON STRING with execution acknowledgments${speechEnabled ? ", speech heard from the actual participant speaker sink," : ""} and a fresh screenshot. In Code Mode use: const r = JSON.parse(await tools.humanish_ui({narration: "...", actions: [...]})); text({acknowledgments: r.acknowledgments${speechEnabled ? ", heardSpeech: r.heardSpeech" : ""}, contextHint: r.contextHint, closing: r.closing}); image(r.imageUrl). Call serially and inspect each returned screenshot${speechEnabled ? " and heardSpeech array" : ""} before deciding what to do next. A call whose actions are only waits and that asks for some wait time asks to wait its waits' ms together; an ask under ${idleWaitMs} ms counts as ${idleWaitMs} ms, and named ms count up to ${watchMaxMs} ms${speechEnabled ? ". It returns when speech is heard" : ""}. contextHint says how long it waited and why it returned. A wait among other actions lasts its ms, at most ${maxWaitMs} ms.${speechEnabled ? " Use speak only after the visible UI shows that you joined the call and your microphone is unmuted; it sends audio into that call." : ""} Acknowledged input does not prove an application outcome. If closing is true, stop calling tools and give your final account.`;
+const toolDescription = (speechEnabled, { maxWaitMs, watchMaxMs, idleWaitMs, }) => `Act on the participant's browser through humanish. Submit one to four UI actions${speechEnabled ? ", including speak when you need to reply aloud," : ""} and a short public comment; never private reasoning. humanish returns a JSON STRING with execution acknowledgments${speechEnabled ? ", speech heard from the actual participant speaker sink," : ""} and a fresh screenshot. In Code Mode use: const r = JSON.parse(await tools.humanish_ui({narration: "...", actions: [...]})); text({acknowledgments: r.acknowledgments${speechEnabled ? ", heardSpeech: r.heardSpeech" : ""}, contextHint: r.contextHint, closing: r.closing}); image(r.imageUrl). Call serially and inspect each returned screenshot${speechEnabled ? " and heardSpeech array" : ""} before deciding what to do next. A call whose actions are only waits and that asks for some wait time asks to wait its waits' ms together; an ask under ${idleWaitMs} ms counts as ${idleWaitMs} ms, and named ms count up to ${watchMaxMs} ms${speechEnabled ? ". It returns when speech is heard" : ""}. contextHint says how long it waited and why it returned, and what happened outside the browser, such as a link that opened another app. A wait among other actions lasts its ms, at most ${maxWaitMs} ms.${speechEnabled ? " Use speak only after the visible UI shows that you joined the call and your microphone is unmuted; it sends audio into that call." : ""} Acknowledged input does not prove an application outcome. If closing is true, stop calling tools and give your final account.`;
 const participantInstructions = (prompt, speechEnabled) => `${prompt}\n\nYou are the study participant throughout this conversation, including its closing account. Use only the supplied screenshots and humanish_ui tool to interact. The tool returns a JSON string: parse it, inspect acknowledgments${speechEnabled ? " and heardSpeech captured from the actual participant speaker sink" : ""}, and display imageUrl with Code Mode image(). Do not print the image data URL as text. Keep your persona and earlier observations throughout the session.${speechEnabled ? " A speak action plays into the participant microphone; use it only after the visible UI shows that you joined the call and the microphone is unmuted." : ""} Speak publicly about your experience, never reveal private reasoning. Completed inputs do not prove application outcomes; verify on the next screenshot. When the task ends, return only the required final JSON with outcome, summary, frictionReports and impressions. Report observed confusion and recovered mistakes as well as blockers. ${IMPRESSIONS_ASK} Do not invent observations.`;
 /** Turns and failures from the native run, handed in order to the next provider request. */
 class ParticipantEvents {

package/dist/actors/computer-use/external-handoff.d.ts

@@ -0,0 +1,22 @@
+/** A link handed to another app, as the run keeps it. */
+export interface ExternalHandoff {
+    /** The link's scheme in lowercase, without the colon. */
+    readonly scheme: string;
+    /** A mailto link's recipient addresses: its path, to, cc and bcc. */
+    readonly recipients?: readonly string[];
+}
+/** How much of one link, and how many links per observation, a desktop hands on. */
+export declare const EXTERNAL_HANDOFF_LIMITS: Readonly<{
+    recipients: 10;
+    addressLength: 254;
+    perObservation: 20;
+}>;
+/** The handoff a link makes, or undefined for a link the browser opens itself. */
+export declare function externalHandoffOf(url: string): ExternalHandoff | undefined;
+/** The trace's record of a handoff: the scheme and any recipients. */
+export declare function externalHandoffSummary(handoff: ExternalHandoff): string;
+/**
+ * What the participant is told on its next turn. Its next screenshot shows no app window, so the
+ * note says the link worked and why the page did not change.
+ */
+export declare function externalHandoffNote(handoff: ExternalHandoff): string;

package/dist/actors/computer-use/external-handoff.js

@@ -0,0 +1,83 @@
+// A link the participant's browser hands to another app: mailto:, tel:, sms: and the like. The study
+// desktop has no mail, phone or messaging app, so it writes the link down instead of opening one
+// (src/substrates/e2b/desktop-handoff.ts), and the participant loop records the handoff and tells
+// the participant what happened. The recipients of a mailto link are all the run keeps of it: a
+// prefilled subject or body can hold anything the page put there.
+/** How much of one link, and how many links per observation, a desktop hands on. */
+export const EXTERNAL_HANDOFF_LIMITS = Object.freeze({
+    recipients: 10,
+    addressLength: 254,
+    perObservation: 20,
+});
+const SCHEME = /^([a-z][a-z0-9+.-]{0,31}):/i;
+// The browser opens these itself, so a desktop never hands one to another app.
+const BROWSER_SCHEMES = new Set(["http", "https", "file"]);
+const ADDRESS = /^[^\s@<>()[\]",;:\\]+@[^\s@<>()[\]",;:\\]+\.[^\s@<>()[\]",;:\\]+$/;
+const RECIPIENT_FIELDS = new Set(["to", "cc", "bcc"]);
+/** The handoff a link makes, or undefined for a link the browser opens itself. */
+export function externalHandoffOf(url) {
+    const scheme = SCHEME.exec(url.trim())?.[1]?.toLowerCase();
+    if (scheme === undefined || BROWSER_SCHEMES.has(scheme))
+        return undefined;
+    if (scheme !== "mailto")
+        return { scheme };
+    return { scheme, recipients: mailtoRecipients(url.trim().slice(scheme.length + 1)) };
+}
+/** RFC 6068: addresses in the path and in to, cc and bcc fields, comma-separated and percent-encoded. */
+function mailtoRecipients(link) {
+    const queryAt = link.indexOf("?");
+    const fields = [queryAt === -1 ? link : link.slice(0, queryAt)];
+    if (queryAt !== -1)
+        for (const pair of link.slice(queryAt + 1).split("&")) {
+            const equals = pair.indexOf("=");
+            if (equals === -1)
+                continue;
+            if (RECIPIENT_FIELDS.has(decoded(pair.slice(0, equals)).toLowerCase()))
+                fields.push(pair.slice(equals + 1));
+        }
+    const recipients = new Set();
+    for (const field of fields)
+        for (const part of decoded(field).split(",")) {
+            const address = (/<([^<>]*)>/.exec(part)?.[1] ?? part).trim();
+            if (address.length <= EXTERNAL_HANDOFF_LIMITS.addressLength && ADDRESS.test(address))
+                recipients.add(address);
+        }
+    return [...recipients].slice(0, EXTERNAL_HANDOFF_LIMITS.recipients);
+}
+function decoded(text) {
+    try {
+        return decodeURIComponent(text);
+    }
+    catch {
+        return text;
+    }
+}
+/** The trace's record of a handoff: the scheme and any recipients. */
+export function externalHandoffSummary(handoff) {
+    const recipients = handoff.recipients ?? [];
+    return recipients.length === 0
+        ? `${handoff.scheme}:`
+        : `${handoff.scheme}: ${recipients.join(", ")}`;
+}
+/**
+ * What the participant is told on its next turn. Its next screenshot shows no app window, so the
+ * note says the link worked and why the page did not change.
+ */
+export function externalHandoffNote(handoff) {
+    const recipients = handoff.recipients ?? [];
+    const unseen = "This computer does not show that app, so the page stays as it was";
+    switch (handoff.scheme) {
+        case "mailto":
+            return recipients.length === 0
+                ? `The email link worked: your email app started a new blank message. ${unseen}, and nothing was sent.`
+                : `The email link worked: your email app started a new message to ${recipients.join(", ")}. ${unseen}, and nothing was sent.`;
+        case "tel":
+        case "callto":
+            return `The phone link worked: your phone app started a call to the number. ${unseen}, and no call was placed.`;
+        case "sms":
+        case "mms":
+            return `The message link worked: your messaging app started a new message. ${unseen}, and nothing was sent.`;
+        default:
+            return `The link asked to open another app for a ${handoff.scheme}: link. This computer has no app for it, so nothing opened.`;
+    }
+}

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

@@ -22,6 +22,8 @@ export declare class DesktopObserver {
     heardNewSpeech: boolean;
     private readonly seenSpeechIds;
     private pendingHeardSpeech;
+    /** Notes about links handed to another app, for the next turn the participant takes. */
+    private pendingHandoffNotes;
     private dwellDone;
     constructor(session: LoopSession);
     /**
@@ -68,6 +70,11 @@ export declare class DesktopObserver {
      * the observation it records.
      */
     private observeBounded;
+    /**
+     * Record each link the browser handed to another app, and keep its note for the next turn. The
+     * desktop showed nothing for it, so without the note the participant reads a dead link.
+     */
+    private noteHandoffs;
     private observeOrRetry;
     /**
      * The observation with every utterance heard since the provider last saw one. New utterances are

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

@@ -1,5 +1,6 @@
 import { evaluateStopWhen } from "../../stop-conditions.js";
 import { ComputerUseExecutorError, isComputerUseExecutorError } from "../executor-error.js";
+import { externalHandoffNote, externalHandoffSummary } from "../external-handoff.js";
 import { CUA_SPEECH_LIMITS } from "../speech.js";
 import { tracePage } from "../../../evidence/trace-page.js";
 import { dwellCompleted, missingFrame, stopWhenMatched } from "./ending.js";
@@ -22,6 +23,8 @@ export class DesktopObserver {
     heardNewSpeech = false;
     seenSpeechIds = new Set();
     pendingHeardSpeech = [];
+    /** Notes about links handed to another app, for the next turn the participant takes. */
+    pendingHandoffNotes = [];
     dwellDone = false;
     constructor(session) {
         this.session = session;
@@ -76,7 +79,9 @@ export class DesktopObserver {
         if (match) {
             return { stop: stopWhenMatched(match, observation, (text) => session.redactNarration(text)) };
         }
-        return { observation, hint };
+        const notes = [...this.pendingHandoffNotes, ...(hint === undefined ? [] : [hint])];
+        this.pendingHandoffNotes = [];
+        return { observation, hint: notes.length === 0 ? undefined : notes.join(" ") };
     }
     /**
      * Hand an observation the next turn may react to to the runtime hooks, and note whether it
@@ -169,12 +174,23 @@ export class DesktopObserver {
     async observeBounded(label) {
         const observation = await this.observeOrRetry(label);
         const { session } = this;
+        this.noteHandoffs(observation);
         session.finalPage =
             session.settings.recordPages === false
                 ? undefined
                 : tracePage(observation.url, (text) => session.redactNarration(text));
         return observation;
     }
+    /**
+     * Record each link the browser handed to another app, and keep its note for the next turn. The
+     * desktop showed nothing for it, so without the note the participant reads a dead link.
+     */
+    noteHandoffs(observation) {
+        for (const handoff of observation.externalHandoffs ?? []) {
+            this.session.trace.record("notice", () => notice("ok", "link opened another app", this.session.redactNarration(externalHandoffSummary(handoff))));
+            this.pendingHandoffNotes.push(externalHandoffNote(handoff));
+        }
+    }
     // An executor without stallRecovery "fail_closed" gets one retry of a stalled observe.
     // One that cannot safely replay a pending request opts out, so even a shorter outer bound stops
     // without retrying.

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

@@ -1,3 +1,4 @@
+import type { ExternalHandoff } from "../external-handoff.js";
 import type { HeardSpeech } from "../speech.js";
 import type { ActorCapabilities, ActorConversation, ActorExecutionProfile, ActorPersonaRef, ActorSessionResult, ActorTokenUsage, ActorTrace, ActorTraceItem, ParticipantClosingReport, ParticipantDeclaredOutcome, ParticipantImpression, ProviderRequestReceipt } from "../../contract.js";
 import type { RedactionHooks } from "../../../evidence/redaction.js";
@@ -117,6 +118,11 @@ export interface CuaObservation {
     text?: string;
     /** Finalized speech captured from the participant's speaker sink. */
     heardSpeech?: HeardSpeech[];
+    /**
+     * Links the browser handed to another app since the previous observation, oldest first. The
+     * desktop opens no app for them; the loop records each and tells the participant on its next turn.
+     */
+    externalHandoffs?: readonly ExternalHandoff[];
 }
 /**
  * A safety check the model raised. The triple is preserved verbatim from the

package/dist/analysis/admission.d.ts

@@ -1,4 +1,10 @@
 import type { ModelRate } from "../run/pricing.js";
+/**
+ * How many times that expectation an API analyst writes. The OpenAI figures above come from its
+ * billed analyses. A gemini-3.8-flash analysis of one participant at high thinking wrote 24,246
+ * output tokens against 13,000 expected, so Gemini's expectation is doubled. That rests on one run.
+ */
+export declare const EXPECTED_OUTPUT_SCALE: Readonly<Record<"openai" | "gemini", number>>;
 /**
  * When admission refuses a request, in words, for the cap as the sentence names it: `$3`, or `this`
  * in the help of the option that sets it. Admission compares the smaller of the worst case and the
@@ -21,6 +27,8 @@ interface AnalysisRequestSize {
 export interface AnalysisRequests {
     cohorts: readonly AnalysisRequestSize[];
     mergeTextBytes: number;
+    /** The analyst's EXPECTED_OUTPUT_SCALE; 1 when omitted. */
+    outputScale?: number;
 }
 export interface AnalysisCostEstimate {
     inputTokens: number;

package/dist/analysis/admission.js

@@ -15,6 +15,15 @@ const FRAMING_TOKENS = 2048;
  */
 const EXPECTED_OUTPUT_TOKENS = 12_000;
 const EXPECTED_OUTPUT_TOKENS_PER_PARTICIPANT = 1_000;
+/**
+ * How many times that expectation an API analyst writes. The OpenAI figures above come from its
+ * billed analyses. A gemini-3.8-flash analysis of one participant at high thinking wrote 24,246
+ * output tokens against 13,000 expected, so Gemini's expectation is doubled. That rests on one run.
+ */
+export const EXPECTED_OUTPUT_SCALE = {
+    openai: 1,
+    gemini: 2,
+};
 /** Admission compares the expected cost times this margin with the cap. */
 const ADMISSION_MARGIN = 1.1;
 const MARGIN_PERCENT = Math.round((ADMISSION_MARGIN - 1) * 100);
@@ -38,12 +47,13 @@ function requestCost(rate, inputTokens, outputTokens) {
         outputTokens * rate.outputUsdPerToken * (long ? rate.longContext.outputMultiplier : 1));
 }
 /** One request's input and costs. `reportTokens` are earlier requests' reports it reads. */
-function estimateRequest(rate, size, reportTokens = 0) {
+function estimateRequest(rate, size, outputScale, reportTokens = 0) {
     const inputTokens = Math.ceil(size.textBytes / BYTES_PER_INPUT_TOKEN) +
         FRAMING_TOKENS +
         size.imageTokens +
         reportTokens;
-    const expectedOutputTokens = Math.min(size.outputAllowance, EXPECTED_OUTPUT_TOKENS + EXPECTED_OUTPUT_TOKENS_PER_PARTICIPANT * size.participants);
+    const expectedOutputTokens = Math.min(size.outputAllowance, outputScale *
+        (EXPECTED_OUTPUT_TOKENS + EXPECTED_OUTPUT_TOKENS_PER_PARTICIPANT * size.participants));
     return {
         inputTokens,
         expectedOutputTokens,
@@ -58,14 +68,15 @@ function estimateRequest(rate, size, reportTokens = 0) {
  */
 export function estimateAnalysisCost(rate, requests) {
     const { cohorts } = requests;
-    const estimates = cohorts.map((size) => estimateRequest(rate, size));
+    const scale = requests.outputScale ?? 1;
+    const estimates = cohorts.map((size) => estimateRequest(rate, size, scale));
     if (cohorts.length > 1)
         estimates.push(estimateRequest(rate, {
             textBytes: requests.mergeTextBytes,
             imageTokens: 0,
             participants: cohorts.reduce((total, size) => total + size.participants, 0),
             outputAllowance: Math.max(...cohorts.map((size) => size.outputAllowance)),
-        }, cohorts.reduce((total, size) => total + size.outputAllowance, 0)));
+        }, scale, cohorts.reduce((total, size) => total + size.outputAllowance, 0)));
     const sum = (key) => estimates.reduce((total, estimate) => total + estimate[key], 0);
     // Each request's cost is a whole number of micro-dollars, so rounding the sum to the nearest one
     // only removes the addition's float noise.

package/dist/analysis/analysis-limits.d.ts

@@ -64,4 +64,10 @@ interface RevisionFields {
  * version without a study-evidence revision number requires none of them.
  */
 export declare function hasRevisionFields(promptVersion: string, result: RevisionFields): boolean;
+/**
+ * How long automatic analysis usually takes, for a person deciding whether to wait. The 247
+ * automatic analyses recorded in the maintainer's run directories by October 2026 took 18 s to
+ * 6 min from claim to result, median 100 s; four in five took 40 s to 3 min 10 s.
+ */
+export declare const ANALYSIS_USUALLY_TAKES = "1 to 4 minutes";
 export {};

package/dist/analysis/analysis-limits.js

@@ -77,3 +77,9 @@ export function hasRevisionFields(promptVersion, result) {
         (result.designFindings !== undefined &&
             result.findings.every((finding) => finding.headline !== undefined && finding.experience !== undefined)));
 }
+/**
+ * How long automatic analysis usually takes, for a person deciding whether to wait. The 247
+ * automatic analyses recorded in the maintainer's run directories by October 2026 took 18 s to
+ * 6 min from claim to result, median 100 s; four in five took 40 s to 3 min 10 s.
+ */
+export const ANALYSIS_USUALLY_TAKES = "1 to 4 minutes";

package/dist/analysis/analysis-lock.d.ts

@@ -0,0 +1,8 @@
+import { type PreparedRunArtifactPaths } from "../run/paths.js";
+/**
+ * Run `action` holding the run's analysis lock. A lock left by a process that is gone is taken
+ * over, and `warn` receives a sentence saying whose it was. Throws ANALYSIS_BUSY when another live
+ * owner, or an owner this process cannot check, holds it, and ANALYSIS_UNAVAILABLE when the lock
+ * cannot be made.
+ */
+export declare function withAnalysisLock<T>(prepared: PreparedRunArtifactPaths, action: () => Promise<T>, warn?: (message: string) => void): Promise<T>;

package/dist/analysis/analysis-lock.js

@@ -0,0 +1,129 @@
+// One analysis or correction writer per run: a `.analysis-lock` directory in the run, holding an
+// owner record that names the process that took it (src/run/process-owner.ts). A lock whose owner
+// is still running, or cannot be shown to be gone, refuses the next writer with ANALYSIS_BUSY. A
+// lock whose owner is gone, as a killed analysis leaves one, passes to the next writer, which says so.
+import { randomUUID } from "node:crypto";
+import { lstat, mkdir, readdir, rename, rmdir, unlink } from "node:fs/promises";
+import path from "node:path";
+import { readContainedRegularFile, writeContainedOutputFile } from "../run/contained-output.js";
+import { validatePreparedRunRootIdentity } from "../run/paths.js";
+import { currentProcessOwner, processOwnerGone, processOwnerOf, } from "../run/process-owner.js";
+const LOCK = ".analysis-lock";
+const OWNER_FILE = "owner.json";
+const OWNER_SCHEMA = "humanish.analysis-lock-owner.v1";
+const MAX_OWNER_BYTES = 4096;
+/**
+ * Run `action` holding the run's analysis lock. A lock left by a process that is gone is taken
+ * over, and `warn` receives a sentence saying whose it was. Throws ANALYSIS_BUSY when another live
+ * owner, or an owner this process cannot check, holds it, and ANALYSIS_UNAVAILABLE when the lock
+ * cannot be made.
+ */
+export async function withAnalysisLock(prepared, action, warn) {
+    await validatePreparedRunRootIdentity(prepared);
+    const target = path.join(prepared.physicalRunRoot, LOCK);
+    const identity = await acquire(prepared, target, warn);
+    try {
+        await validatePreparedRunRootIdentity(prepared);
+        return await action();
+    }
+    finally {
+        // Only remove our own unchanged directory, and only the files the lock writes into it.
+        try {
+            await validatePreparedRunRootIdentity(prepared);
+            if (sameDirectory(await lstat(target, { bigint: true }), identity))
+                await removeLock(target);
+        }
+        catch {
+            /* Leave ambiguous storage in place for explicit operator inspection. */
+        }
+    }
+}
+async function acquire(prepared, target, warn) {
+    for (let attempt = 0;; attempt += 1) {
+        try {
+            await mkdir(target, { mode: 0o700 });
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw new Error("ANALYSIS_UNAVAILABLE");
+            // One takeover per call: a second EEXIST means another writer took the lock meanwhile.
+            if (attempt === 0 && (await takeOverStale(prepared, target, warn)))
+                continue;
+            throw new Error("ANALYSIS_BUSY");
+        }
+        const identity = await lstat(target, { bigint: true });
+        if (!identity.isDirectory() || identity.isSymbolicLink())
+            throw new Error("ANALYSIS_UNAVAILABLE");
+        const owner = {
+            schema: OWNER_SCHEMA,
+            ...currentProcessOwner(),
+            createdAt: new Date().toISOString(),
+        };
+        try {
+            await writeContainedOutputFile(prepared, `${LOCK}/${OWNER_FILE}`, `${JSON.stringify(owner)}\n`, "utf8");
+        }
+        catch {
+            await removeLock(target).catch(() => undefined);
+            throw new Error("ANALYSIS_UNAVAILABLE");
+        }
+        return identity;
+    }
+}
+/** The lock's owner, or undefined when its record is missing, refused or malformed. */
+async function readOwner(prepared) {
+    try {
+        const read = await readContainedRegularFile(prepared, `${LOCK}/${OWNER_FILE}`, MAX_OWNER_BYTES);
+        if (read.status !== "read")
+            return undefined;
+        const value = JSON.parse(read.bytes.toString("utf8"));
+        return value.schema === OWNER_SCHEMA ? processOwnerOf(value) : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Move a lock whose owner is gone out of the way, so the next mkdir can take it. A lock with no
+ * readable owner, as humanish 0.139.1 and earlier left one and as a lock looks between its mkdir
+ * and its owner write, is never taken. The rename is atomic, so of two writers that both judged
+ * the lock stale only one moves it. True when this call moved it.
+ */
+async function takeOverStale(prepared, target, warn) {
+    const before = await lstat(target, { bigint: true }).catch(() => null);
+    if (before === null || !before.isDirectory() || before.isSymbolicLink())
+        return false;
+    const owner = await readOwner(prepared);
+    if (owner === undefined || !processOwnerGone(owner).gone)
+        return false;
+    const aside = path.join(prepared.physicalRunRoot, `${LOCK}-stale-${randomUUID()}`);
+    try {
+        await rename(target, aside);
+    }
+    catch {
+        return false;
+    }
+    if (!sameDirectory(await lstat(aside, { bigint: true }), before)) {
+        // Another writer replaced the stale lock between the check and the rename, so this moved a
+        // live one: put it back. If that fails, its owner finds its lock gone and leaves the moved one.
+        await rename(aside, target).catch(() => undefined);
+        return false;
+    }
+    await removeLock(aside).catch(() => undefined);
+    warn?.(`This run's analysis lock belonged to process ${owner.pid}, which is no longer running, so this analysis took it over.`);
+    return true;
+}
+function sameDirectory(current, identity) {
+    return (current.isDirectory() &&
+        !current.isSymbolicLink() &&
+        current.dev === identity.dev &&
+        current.ino === identity.ino &&
+        current.birthtimeNs === identity.birthtimeNs);
+}
+/** Remove the owner record and any write the lock's owner left half done, then the directory. */
+async function removeLock(directory) {
+    for (const entry of await readdir(directory)) {
+        if (entry === OWNER_FILE || entry.startsWith(".humanish-write-"))
+            await unlink(path.join(directory, entry));
+    }
+    await rmdir(directory);
+}

package/dist/analysis/automatic-completion.js

@@ -37,6 +37,9 @@ export async function completeAutomaticAnalysis(result, finished, config, input,
     const seams = input?.deps?.analysis;
     const signal = input?.analysisSignal;
     let started = false;
+    // From here status.json says the run is analyzing, and its heartbeat runs until the end below.
+    const endAnalysis = await finished.beginAnalysis();
+    let ended = "unknown";
     try {
         // The CLI prints "Participants finished" on analysis-started. A run where no participant's
         // session started (it failed before, such as at E2B login) still records its analysis
@@ -49,6 +52,7 @@ export async function completeAutomaticAnalysis(result, finished, config, input,
             await validatePreparedRunRootIdentity(prepared);
         }
         catch {
+            ended = "failed";
             return {
                 ...result,
                 ...origin,
@@ -64,9 +68,11 @@ export async function completeAutomaticAnalysis(result, finished, config, input,
             ...(trigger === "default" ? { defaultRequest: true } : {}),
             expectedRun: prepared,
         });
+        ended = automaticAnalysis.state;
         return { ...result, ...origin, automaticAnalysis };
     }
     catch {
+        ended = "failed";
         // Preserve the producer result. Never put a hook exception or provider response in the envelope.
         return {
             ...result,
@@ -75,6 +81,7 @@ export async function completeAutomaticAnalysis(result, finished, config, input,
         };
     }
     finally {
+        await endAnalysis(ended);
         try {
             if (started)
                 input?.emit?.({ type: "analysis-finished" });

package/dist/analysis/automatic-config.d.ts

@@ -2,6 +2,9 @@ import type { StudyRoute } from "../study/plan.js";
 import type { AnalysisConfig } from "./types.js";
 export declare const DEFAULT_ANALYSIS_TIMEOUT_MS = 600000;
 export declare const DEFAULT_ANALYSIS_MODEL = "gpt-6-astra";
+/** The model a Gemini analysis uses when the study or command names none: Google's current
+ * stable Flash model. */
+export declare const DEFAULT_GEMINI_ANALYSIS_MODEL = "gemini-3.8-flash";
 interface StudyAnalysisSettings {
     model?: string;
     question?: string;
@@ -9,7 +12,7 @@ interface StudyAnalysisSettings {
 }
 /** The study's review.analysis: a provider selection for a separate review after a live run. */
 export type StudyAnalysis = StudyAnalysisSettings & ({
-    provider?: "openai";
+    provider?: "openai" | "gemini";
     maxCostUsd: number;
     maxOutputTokens?: number;
 } | {
@@ -37,7 +40,7 @@ export declare function resolveAutomaticAnalysis(raw: unknown, participant?: Ana
     message: string;
 };
 export interface AutomaticAnalysisBudget {
-    provider?: "openai" | "codex";
+    provider?: "openai" | "gemini" | "codex";
     billing?: "api-estimate" | "account-unknown";
     model: string;
     maxCostUsd: number | null;

package/dist/analysis/automatic-config.js

@@ -7,6 +7,9 @@ import { scanEncodedText } from "../evidence/encoded-text.js";
 export const DEFAULT_ANALYSIS_TIMEOUT_MS = 600_000;
 const MAX_ANALYSIS_TIMEOUT_MS = 600_000;
 export const DEFAULT_ANALYSIS_MODEL = "gpt-6-astra";
+/** The model a Gemini analysis uses when the study or command names none: Google's current
+ * stable Flash model. */
+export const DEFAULT_GEMINI_ANALYSIS_MODEL = "gemini-3.8-flash";
 const FIELDS = new Set([
     "provider",
     "maxCostUsd",
@@ -60,8 +63,11 @@ export function resolveAutomaticAnalysis(raw, participant) {
         };
     }
     const value = raw;
-    if (value.provider !== undefined && value.provider !== "openai" && value.provider !== "codex") {
-        return { ok: false, message: "review.analysis.provider must be openai or codex." };
+    if (value.provider !== undefined &&
+        value.provider !== "openai" &&
+        value.provider !== "gemini" &&
+        value.provider !== "codex") {
+        return { ok: false, message: "review.analysis.provider must be openai, gemini or codex." };
     }
     if (value.provider === "codex") {
         const model = value.model === undefined ? CODEX_ANALYSIS_MODEL : value.model;
@@ -93,7 +99,12 @@ export function resolveAutomaticAnalysis(raw, participant) {
         };
     }
     const { maxCostUsd } = value;
-    const model = value.model === undefined ? DEFAULT_ANALYSIS_MODEL : value.model;
+    const vendor = value.provider === "gemini" ? "gemini" : "openai";
+    const model = value.model !== undefined
+        ? value.model
+        : vendor === "gemini"
+            ? DEFAULT_GEMINI_ANALYSIS_MODEL
+            : DEFAULT_ANALYSIS_MODEL;
     const question = value.question === undefined ? null : value.question;
     const timeoutMs = value.timeoutMs === undefined ? DEFAULT_ANALYSIS_TIMEOUT_MS : value.timeoutMs;
     const maxOutputTokens = value.maxOutputTokens === undefined
@@ -104,7 +115,7 @@ export function resolveAutomaticAnalysis(raw, participant) {
         maxCostUsd <= 0 ||
         maxCostUsd > 1000 ||
         typeof model !== "string" ||
-        !isSupportedAnalysisModel(model) ||
+        !isSupportedAnalysisModel(model, vendor) ||
         !validTimeout(timeoutMs) ||
         typeof maxOutputTokens !== "number" ||
         !Number.isSafeInteger(maxOutputTokens) ||
@@ -113,7 +124,7 @@ export function resolveAutomaticAnalysis(raw, participant) {
         !validQuestion(value.question)) {
         return {
             ok: false,
-            message: `review.analysis requires a positive maxCostUsd up to 1000, a supported analysis model, timeoutMs 1–${MAX_ANALYSIS_TIMEOUT_MS}, maxOutputTokens 256–${MAX_ANALYSIS_OUTPUT_TOKENS}, and an optional question of at most 4000 characters.`,
+            message: `review.analysis requires a positive maxCostUsd up to 1000, a supported ${vendor === "gemini" ? "Gemini" : "OpenAI"} analysis model, timeoutMs 1–${MAX_ANALYSIS_TIMEOUT_MS}, maxOutputTokens 256–${MAX_ANALYSIS_OUTPUT_TOKENS}, and an optional question of at most 4000 characters.`,
         };
     }
     if (question !== null && scanEncodedText(question).sensitive)
@@ -121,7 +132,8 @@ export function resolveAutomaticAnalysis(raw, participant) {
     return {
         ok: true,
         config: {
-            ...(value.provider === undefined ? {} : { provider: "openai" }),
+            // An omitted provider stays omitted: it is the OpenAI contract, and its hash predates the field.
+            ...(value.provider === undefined ? {} : { provider: vendor }),
             model,
             maxCostUsd,
             timeoutMs,
@@ -148,7 +160,9 @@ export function automaticAnalysisBudget(raw, route, participants, participant) {
     return {
         ...(config.provider === "codex"
             ? { provider: "codex", billing: "account-unknown" }
-            : {}),
+            : config.provider === "gemini"
+                ? { provider: "gemini" }
+                : {}),
         model: config.model,
         maxCostUsd: config.maxCostUsd,
         trigger: raw === undefined ? "default" : "explicit",
@@ -179,5 +193,6 @@ export function formatAutomaticAnalysisBudget(budget) {
     const refused = budget.refusedFromUsd === undefined || who === undefined
         ? `refused before it starts if ${rule}`
         : `refused before it starts for ${who} even with no evidence (expected $${budget.refusedFromUsd.toFixed(2)}), since ${rule}`;
-    return `After live runs: ${budget.trigger} analysis · ${budget.model}${range} · ${refused}; this is not a billing cap. Set review.analysis: false to disable.`;
+    const where = budget.provider === "gemini" ? " on Gemini, which sends the evidence to Google" : "";
+    return `After live runs: ${budget.trigger} analysis${where} · ${budget.model}${range} · ${refused}; this is not a billing cap. Set review.analysis: false to disable.`;
 }