humanish 0.141.0 → 0.142.0

package/dist/cli/commands/run-command.d.ts

@@ -1,4 +1,4 @@
-import type { Command } from "commander";
+import { type Command } from "commander";
 import { type CliIo, type StudyCommandOptions as RunOptions } from "../io.js";
 /** The parsed flags of `run` and `watch`. */
 export type { RunOptions };

package/dist/cli/commands/run-command.js

@@ -1,3 +1,6 @@
+// The one runner. `run` and `watch` register a run's flags through addRunOptions, so the two
+// commands cannot drift apart.
+import { Option } from "commander";
 import { runDryRun } from "../../run/dry-run.js";
 import { runStudyCommand } from "./study-run.js";
 import { applyEnvFileOption, CWD_OPTION_DESCRIPTION, DOTENV_OPTION_DESCRIPTION, dotenvPathOf, envFileAliasOption, formatRunHuman, freePortOption, JSON_OPTION_DESCRIPTION, parsePositiveInteger, writeResult, } from "../io.js";
@@ -17,8 +20,17 @@ export function addRunOptions(command) {
         .option("--dotenv <path>", DOTENV_OPTION_DESCRIPTION)
         .addOption(envFileAliasOption())
         .option("--run-id <id>", "Explicit run id for deterministic fixture tests; refused when that run already exists.")
+        .option("--remote", "Run the study's own process in a sandbox on its participants' provider (E2B or Modal), so it keeps going when this machine sleeps. This machine follows it, serves its live Observer and copies the run back. Computer-use studies with hosted desktops and an app-url subject.")
+        .addOption(ownerKeyOption())
         .option("--json", JSON_OPTION_DESCRIPTION);
 }
+/**
+ * Hidden: set by the process that launches a run on a remote machine, so that machine's run
+ * directory and the launcher's own name the same sandboxes.
+ */
+function ownerKeyOption() {
+    return new Option("--owner-key <key>").hideHelp();
+}
 /** The flags that only a study file can use, as typed on the command line, when they are set. */
 export function studyOnlyFlags(options) {
     return [

package/dist/cli/commands/study-remote.d.ts

@@ -0,0 +1,13 @@
+import type { Command } from "commander";
+import { type RemoteOutcome } from "../../remote/launch.js";
+import type { StudyConfig } from "../../study/types.js";
+import { type CliIo, type StudyCommandOptions } from "../io.js";
+export declare function runRemoteStudy(args: {
+    command: Command;
+    io: CliIo;
+    options: StudyCommandOptions;
+    config: StudyConfig;
+    studyPath: string;
+}): Promise<void>;
+/** The command's result and exit code for a remote run that ended, stopped or detached. */
+export declare function reportRemoteOutcome(command: Command, io: CliIo, cwd: string, outcome: RemoteOutcome): void;

package/dist/cli/commands/study-remote.js

@@ -0,0 +1,125 @@
+// `--remote` on run and watch: plan here, refuse what cannot run remotely, then launch and follow
+// the run in a runner sandbox (src/remote/launch.ts). The result and exit code are the run's own.
+import path from "node:path";
+import { launchRemoteRun } from "../../remote/launch.js";
+import { planRemoteRun } from "../../remote/plan.js";
+import { planStudy } from "../../study/plan.js";
+import { concurrentSandboxes, sandboxCeiling } from "../../substrates/e2b/lifetime.js";
+import { MODAL_MAX_SANDBOX_MS } from "../../substrates/modal/sdk.js";
+import { formatRunHuman, parseObserverPort, wantsJson, writeResult, } from "../io.js";
+export async function runRemoteStudy(args) {
+    const { io, options, config } = args;
+    const cwd = path.resolve(options.cwd);
+    const refuse = (code, message, runId) => {
+        const result = {
+            schema: "humanish.run-result.v1",
+            ok: false,
+            cwd,
+            ...(runId === undefined ? {} : { runId }),
+            warnings: [],
+            error: { code, message },
+        };
+        writeResult(args.command, io, result, formatRunHuman);
+        io.setExitCode(2);
+    };
+    if (options.dryRun === true) {
+        refuse("HUMANISH_REMOTE_REFUSED", "--remote runs live studies; a dry run needs no runner.");
+        return;
+    }
+    const local = localOnlyFlags(options);
+    if (local.length > 0) {
+        refuse("HUMANISH_REMOTE_REFUSED", `${local.join(", ")} ${local.length === 1 ? "does" : "do"} not run remotely yet; run without --remote to use ${local.length === 1 ? "it" : "them"}.`);
+        return;
+    }
+    const planned = planStudy(config, { cwd, dryRun: false });
+    if (!planned.ok) {
+        refuse("HUMANISH_REMOTE_REFUSED", planned.refusal.message);
+        return;
+    }
+    const plan = planned.planned.plan;
+    const e2bCeiling = sandboxCeiling(process.env);
+    const provider = plan.route === "computer-use" && plan.runner.desktop === "e2b-desktop"
+        ? plan.runner.provider
+        : "e2b";
+    const ceilingMs = provider === "modal" ? MODAL_MAX_SANDBOX_MS : e2bCeiling.ok ? e2bCeiling.ms : 0;
+    const sandboxes = concurrentSandboxes(process.env);
+    const remote = planRemoteRun({
+        config,
+        plan,
+        cwd,
+        studyPath: args.studyPath,
+        ceilingMs,
+        concurrentSandboxes: sandboxes.ok ? sandboxes.count : 1,
+    });
+    if (!remote.ok) {
+        refuse("HUMANISH_REMOTE_REFUSED", `This study cannot run remotely: ${remote.reason}`);
+        return;
+    }
+    const port = parseObserverPort(options.port ?? "0");
+    if (port === null) {
+        refuse("HUMANISH_REMOTE_REFUSED", "--port must be an integer between 0 and 65535.");
+        return;
+    }
+    let outcome;
+    try {
+        outcome = await launchRemoteRun({
+            cwd,
+            study: path.relative(cwd, path.resolve(cwd, args.studyPath)).split(path.sep).join("/"),
+            remote: remote.plan,
+            env: process.env,
+            port,
+            say: (line) => io.writeErr(`${line}\n`),
+        });
+    }
+    catch (error) {
+        refuse("HUMANISH_REMOTE_FAILED", error instanceof Error ? error.message : String(error));
+        return;
+    }
+    reportRemoteOutcome(args.command, io, cwd, outcome);
+}
+/** The run options a remote run does not carry to the runner yet. */
+function localOnlyFlags(options) {
+    return [
+        options.scorer === undefined ? [] : ["--scorer"],
+        options.count === undefined ? [] : ["--count"],
+        options.rerunFailedFrom === undefined ? [] : ["--rerun-failed-from"],
+        options.participants === undefined ? [] : ["--participants"],
+        options.expose === true || options.tunnel !== undefined || options.publicUrl !== undefined
+            ? ["--expose"]
+            : [],
+    ].flat();
+}
+/** The command's result and exit code for a remote run that ended, stopped or detached. */
+export function reportRemoteOutcome(command, io, cwd, outcome) {
+    if (outcome.detached === true) {
+        io.writeErr(`The terminal closed, so run ${outcome.runId} goes on in its runner without this machine. Watch it again with humanish observe --run ${outcome.runId}, or stop it and its sandboxes with humanish reclaim --run ${outcome.runId}\n`);
+        return;
+    }
+    if (outcome.result === undefined || typeof outcome.result !== "object") {
+        const failed = {
+            schema: "humanish.run-result.v1",
+            ok: false,
+            cwd,
+            runId: outcome.runId,
+            warnings: [],
+            error: {
+                code: "HUMANISH_REMOTE_FAILED",
+                message: `Run ${outcome.runId} ${outcome.error ?? "ended without a result"}.`,
+            },
+        };
+        writeResult(command, io, failed, formatRunHuman);
+        io.setExitCode(outcome.exitCode === 0 ? 2 : outcome.exitCode);
+        return;
+    }
+    const result = { ...outcome.result, cwd };
+    if (outcome.error !== undefined)
+        result.warnings = [...(result.warnings ?? []), outcome.error];
+    if (wantsJson(command))
+        io.writeOut(`${JSON.stringify(result, null, 2)}\n`);
+    else {
+        if (outcome.error !== undefined)
+            io.writeErr(`warning: ${outcome.error}\n`);
+        io.writeErr(`Run ${outcome.runId} ${result.ok && outcome.exitCode === 0 ? "passed" : "did not pass"}; its evidence (${outcome.files ?? 0} files) is in .humanish/runs/${outcome.runId}. Next: humanish review --run ${outcome.runId}\n`);
+    }
+    io.setExitCode(outcome.exitCode);
+}

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

@@ -1,3 +1,4 @@
+import { rename, writeFile } from "node:fs/promises";
 import { automaticAnalysisSucceeded } from "../../analysis/automatic-completion.js";
 import { Command } from "commander";
 import {} from "../../run-study.js";
@@ -90,7 +91,16 @@ function resolveCuaSettings(args) {
         refuseCua(args, dryRun, "HUMANISH_WATCH_OPTION_CONFLICT", "--port must be an integer between 0 and 65535.");
         return undefined;
     }
-    return { wantsMachine, shouldOpen, participantIds, count, dryRun, port, wantsFollow };
+    return {
+        wantsMachine,
+        shouldOpen,
+        participantIds,
+        count,
+        dryRun,
+        port,
+        wantsFollow,
+        allInterfaces: args.options.allInterfaces === true,
+    };
 }
 /** Validates exposure and plans the finished-run Observer, or returns undefined after refusing. */
 function prepareCuaWatch(args, settings) {
@@ -147,6 +157,7 @@ function cuaRunOptions(args, settings, prepared, live) {
             }
             : {}),
         ...(args.options.runId === undefined ? {} : { runId: args.options.runId }),
+        ...(args.options.ownerKey === undefined ? {} : { ownerKey: args.options.ownerKey }),
         ...(args.options.rerunFailedFrom === undefined
             ? {}
             : {
@@ -191,6 +202,7 @@ async function attachLiveObserver(io, settings, exposure, live, observer) {
             open: settings.shouldOpen && !exposure.exposed,
             port: settings.port,
             exposed: exposure.exposed,
+            allInterfaces: settings.allInterfaces,
         });
         // A signal that stops the run closes the server and any tunnel before the process exits.
         live.releaseShutdown ??= onRunShutdown(() => closeLiveAttachment(io, live));
@@ -237,7 +249,10 @@ async function reportCuaRun(args, prepared, result, live) {
         };
     }
     await writeRunResult(args.command, args.io, args.options.cwd, output, (value) => formatCuaStudyHuman(value, args.config.subject));
-    args.io.setExitCode(result.ok && automaticAnalysisSucceeded(result) ? 0 : 2);
+    const exitCode = result.ok && automaticAnalysisSucceeded(result) ? 0 : 2;
+    args.io.setExitCode(exitCode);
+    if (args.options.resultFile !== undefined)
+        await writeResultFile(args.options.resultFile, { exitCode, result: output });
     if (server && (result.observer?.ok || attachedObserver)) {
         const followResult = output.observer?.ok
             ? output.observer
@@ -261,3 +276,12 @@ async function reportCuaRun(args, prepared, result, live) {
         });
     }
 }
+/**
+ * Write `value` to `file` as JSON in one rename, so a reader polling for it never sees it half
+ * written. A remote run's launcher reads it while this process keeps serving the Observer.
+ */
+async function writeResultFile(file, value) {
+    const partial = `${file}.partial`;
+    await writeFile(partial, `${JSON.stringify(value)}\n`, { mode: 0o600 });
+    await rename(partial, file);
+}

package/dist/cli/commands/study-route-scripted.js

@@ -28,6 +28,7 @@ export function scriptedRouteRun(args) {
             open: observerOpen(args.mode, finishedPlan, shouldOpen),
             ...(args.options.dryRun === undefined ? {} : { dryRun: args.options.dryRun }),
             ...(args.options.runId === undefined ? {} : { runId: args.options.runId }),
+            ...(args.options.ownerKey === undefined ? {} : { ownerKey: args.options.ownerKey }),
         },
         present: async (outcome) => {
             if (outcome.route !== "scripted") {

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

@@ -88,6 +88,7 @@ export function sharedWorldRouteRun(args) {
                 }
                 : {}),
             ...(args.options.runId === undefined ? {} : { runId: args.options.runId }),
+            ...(args.options.ownerKey === undefined ? {} : { ownerKey: args.options.ownerKey }),
         },
         onRunError: async (error) => {
             await server?.close().catch((cleanupError) => {

package/dist/cli/commands/study-route-terminal.js

@@ -28,6 +28,7 @@ export function terminalRouteRun(args) {
             open: observerOpen(args.mode, finishedPlan, shouldOpen),
             ...(args.options.dryRun === undefined ? {} : { dryRun: args.options.dryRun }),
             ...(args.options.runId === undefined ? {} : { runId: args.options.runId }),
+            ...(args.options.ownerKey === undefined ? {} : { ownerKey: args.options.ownerKey }),
         },
         present: async (outcome) => {
             if (outcome.route !== "terminal") {

package/dist/cli/commands/study-run.js

@@ -15,11 +15,25 @@ import { sharedWorldRouteRun } from "./study-route-shared-world.js";
 import { previewRouteRun } from "./study-route-preview.js";
 import { terminalRouteRun } from "./study-route-terminal.js";
 import { maybeLoadAdapterScorer } from "./study-scorer.js";
+import { runRemoteStudy } from "./study-remote.js";
 import { discoverCliKeys, formatRunHuman, noteRunFacts, writeResult, } from "../io.js";
 import { watchExposeRequested } from "../observer-follow.js";
 import { beginRunSignalPhase } from "./run-signals.js";
 import { WATCH_SAFE_NOT_APPLICABLE_MESSAGE } from "../../observer/exposure.js";
 export async function runStudyCommand(args) {
+    const ownerKeyRefusal = ownerKeyConflict(args.options);
+    if (ownerKeyRefusal !== undefined) {
+        const result = {
+            schema: "humanish.run-result.v1",
+            ok: false,
+            cwd: resolve(args.options.cwd),
+            warnings: [],
+            error: { code: "HUMANISH_RUN_OPTION_CONFLICT", message: ownerKeyRefusal },
+        };
+        writeResult(args.command, args.io, result, formatRunHuman);
+        args.io.setExitCode(2);
+        return;
+    }
     const resolved = await resolveStudyManifest(args.options.cwd, args.study);
     if (!resolved.ok) {
         writeResult(args.command, args.io, resolved, formatStudyResolveFailureHuman);
@@ -98,6 +112,16 @@ export async function runStudyCommand(args) {
             ...(announced === undefined ? {} : { announced }),
         });
     }
+    if (args.options.remote === true) {
+        await runRemoteStudy({
+            command: args.command,
+            io: args.io,
+            options: args.options,
+            config,
+            studyPath: resolved.path,
+        });
+        return;
+    }
     // The route's CLI setup refuses bad options, runStudyWith's plan refuses bad labs, and the route's local
     // checks (keys, runtime auth, subject env, the local agent, caps) refuse this machine, all before
     // the scorer loads, so none imports the scorer's host code. The scripted route's checks and the
@@ -191,3 +215,13 @@ function formatStudyResolveFailureHuman(result) {
     const warnings = result.warnings.map((warning) => `warning: ${warning}\n`).join("");
     return { ...(warnings ? { stdout: warnings } : {}), error: result.error };
 }
+/** Why `--owner-key` cannot be used as given, or undefined when it can. */
+function ownerKeyConflict(options) {
+    if (options.ownerKey === undefined)
+        return undefined;
+    if (options.runId === undefined)
+        return "--owner-key needs --run-id.";
+    if (!/^[0-9a-f]{16}$/.test(options.ownerKey))
+        return "--owner-key is 16 lowercase hexadecimal characters.";
+    return undefined;
+}

package/dist/cli/commands/watch.js

@@ -28,6 +28,11 @@ export function registerWatchCommand(parent, io) {
         // Hidden: watch rejects --safe with a pointer to the library filter and to edge auth, which
         // a bare "unknown option" would lose.
         .addOption(new Option("--safe").hideHelp())
+        // Hidden: a remote run's launcher starts its runner's watch with these. The runner's Observer
+        // is reached only through the provider's authenticated proxy, and the launcher reads the
+        // result from the file while the Observer keeps serving.
+        .addOption(new Option("--all-interfaces").hideHelp())
+        .addOption(new Option("--result-file <path>").hideHelp())
         .addHelpText("after", [
         "",
         "Without a study or --run, watch starts a synthetic run of 4 participants; --count changes it.",

package/dist/cli/doctor.js

@@ -2,7 +2,7 @@ import { readFile, readdir } from "node:fs/promises";
 import { homedir } from "node:os";
 import { existsSync } from "node:fs";
 import path from "node:path";
-import { DOCTOR_KEYS, probeKeySources, } from "../keys/key-resolution.js";
+import { DOCTOR_KEYS, analysisKeyNames, probeKeySources, } from "../keys/key-resolution.js";
 import { desktopPeerAdvice, humanishInstall, } from "../substrates/e2b/peer-install.js";
 import { concurrentSandboxes, describeConcurrentSandboxes, describeSandboxCeiling, sandboxCeiling, } from "../substrates/e2b/lifetime.js";
 import { nodeSupportsTui, terminalSurfaceMessage, TUI_BUNDLE_URL } from "../tui/contract.js";
@@ -304,7 +304,8 @@ function versionCheck(env) {
         },
     ];
 }
-/** Probes the live-run keys, plus the receiving-email key a real-comms study names. */
+/** Probes the live-run keys, plus the receiving-email key a real-comms study names and the Gemini
+ * key a study analyzed on Gemini reads. */
 async function probeDoctorKeys(cwd, env, study, keyDeps, dotenv) {
     const keyNames = new Set(DOCTOR_KEYS);
     let receivingKey = null;
@@ -315,6 +316,10 @@ async function probeDoctorKeys(cwd, env, study, keyDeps, dotenv) {
         if (resolved.ok && resolved.config.execution?.target === "modal-terminal")
             for (const name of ["MODAL_TOKEN_ID", "MODAL_TOKEN_SECRET"])
                 keyNames.add(name);
+        // A study analyzed on Gemini reads the Gemini key, which no other study needs.
+        const analysis = resolved.ok ? resolved.config.review?.analysis : undefined;
+        if (typeof analysis === "object" && analysis !== null && analysis.provider === "gemini")
+            keyNames.add(analysisKeyNames("gemini")[0]);
         if (resolved.ok && resolved.config.comms?.email?.kind === "real") {
             const { receivingRequiredKey } = await import("../comms/setup.js");
             receivingKey = await receivingRequiredKey(cwd, resolved.config.comms.email.connection);

package/dist/cli/findings.d.ts

@@ -117,6 +117,8 @@ interface FindingsSource {
     liveStudy?: LiveStudy;
     /** The run's study, from its bundle. */
     study?: Pick<RunStudyProvenance, "id" | "path">;
+    /** The analyst the run's study gets, read only for an analysis skipped for a missing key. */
+    analyst?: Analyst;
     /**
      * Whether Codex is signed in with a ChatGPT account on this machine, read only for an analysis
      * skipped for a missing OpenAI key, whose next step it picks.
@@ -140,7 +142,7 @@ interface FindingsSource {
         /** status.json's last heartbeat. */
         updatedAt: string;
         /** The analyst the run's study gets, read only for an analysis whose process stopped. */
-        provider?: string;
+        analyst?: Analyst;
     };
     /** When the view was built, for how long an analysis has run. */
     nowMs?: number;
@@ -156,6 +158,11 @@ interface LiveStudy {
 }
 /** ` --cwd <dir>`, or "" when `cwd` is the current directory. */
 export declare function cwdFlag(cwd: string): string;
+/** An analysis provider and model, as a study or an analysis record names them. */
+interface Analyst {
+    provider?: string | undefined;
+    model?: string;
+}
 /** The findings view of a run's selected analysis, or why it has none. */
 export declare function analysisFindings(source: FindingsSource): AnalysisFindings;
 /**

package/dist/cli/findings.js

@@ -22,6 +22,7 @@ import { plural } from "../run/text.js";
 import { shellQuote } from "../substrates/shell.js";
 import { analysisOutcomeText } from "./io.js";
 import { cli } from "./invocation.js";
+import { analysisKeyNames } from "../keys/key-resolution.js";
 export const ANALYSIS_FINDINGS_SCHEMA = "humanish.analysis-findings.v1";
 /** ` --cwd <dir>`, or "" when `cwd` is the current directory. */
 export function cwdFlag(cwd) {
@@ -29,11 +30,20 @@ export function cwdFlag(cwd) {
         return "";
     return ` --cwd ${/^[\w@%+=:,./-]+$/.test(cwd) ? cwd : shellQuote(cwd)}`;
 }
-function analyzeCommand(source, provider) {
+/** The skip reasons for an analysis whose API key was missing, one per API analyst. */
+const KEY_MISSING_REASONS = new Set([
+    "AUTOMATIC_ANALYSIS_KEY_MISSING",
+    "AUTOMATIC_ANALYSIS_GEMINI_KEY_MISSING",
+]);
+/** The `analyze` command that runs `analyst` on the run; undefined is the OpenAI default. */
+function analyzeCommand(source, analyst) {
     const run = cli(`analyze --run ${source.runId}${source.cwdFlag}`);
-    return provider === "codex"
-        ? `${run} --provider codex`
-        : `${run} --max-cost ${DEFAULT_ANALYSIS_MAX_COST_USD}`;
+    if (analyst?.provider === "codex")
+        return `${run} --provider codex`;
+    const gemini = analyst?.provider === "gemini"
+        ? ` --provider gemini${analyst.model === undefined ? "" : ` --model ${analyst.model}`}`
+        : "";
+    return `${run}${gemini} --max-cost ${DEFAULT_ANALYSIS_MAX_COST_USD}`;
 }
 /** The cited items the analysis evidence resolves, each once, in citation order. */
 function citedEvidence(ids, analysis, runRoot) {
@@ -157,16 +167,22 @@ function dryRunFindings(source) {
     return withoutFindings(source, "dry_run", null, `${opening} Findings come from live runs: ${howLive}`, cli(`run ${live.run}${source.cwdFlag}`));
 }
 /**
- * An analysis skipped because OPENAI_API_KEY is not set. With Codex signed in, the next step is the
+ * An analysis skipped because its API key is not set. For OpenAI with Codex signed in, the next step is the
  * Codex account analyst, named as an opt-in: the study chose the OpenAI analyst, and switching
  * the account that pays for it is the operator's choice.
  */
 function missingKeyFindings(source, reason) {
+    // The skip reason records which analyst's key was missing; the study file only adds its model.
+    if (reason === "AUTOMATIC_ANALYSIS_GEMINI_KEY_MISSING")
+        return withoutFindings(source, "skipped", reason, `The automatic analysis was skipped because ${analysisKeyNames("gemini").join(" and ")} are not set. Store the key with ${cli("keys set gemini")}, then run the next command.`, analyzeCommand(source, {
+            provider: "gemini",
+            ...(source.analyst?.provider === "gemini" ? { model: source.analyst.model } : {}),
+        }));
     const opening = "The automatic analysis was skipped because OPENAI_API_KEY is not set.";
     if (source.codexSignedIn !== true)
         return withoutFindings(source, "skipped", reason, `${opening} Set it with ${cli("keys set openai")}, then run the next command.`, analyzeCommand(source, undefined));
     const file = source.study?.path === undefined ? "the study file" : source.study.path;
-    return withoutFindings(source, "skipped", reason, `${opening} Codex is signed in on this machine, so its ChatGPT account can analyze the run instead, sending the evidence to OpenAI under that account. The next command does it once; review.analysis.provider: codex in ${file} makes it this study's analyst.`, analyzeCommand(source, "codex"));
+    return withoutFindings(source, "skipped", reason, `${opening} Codex is signed in on this machine, so its ChatGPT account can analyze the run instead, sending the evidence to OpenAI under that account. The next command does it once; review.analysis.provider: codex in ${file} makes it this study's analyst.`, analyzeCommand(source, { provider: "codex" }));
 }
 /**
  * The view of a run whose findings are not written yet: participants still running, an analysis
@@ -194,7 +210,7 @@ function pendingFindings(source, job) {
     if (!stopped)
         return undefined;
     const at = job?.updatedAt ?? (progress?.stage === "analysis" ? progress.updatedAt : undefined);
-    return withoutFindings(source, "failed", "AUTOMATIC_ANALYSIS_STOPPED", `The automatic analysis stopped before it wrote findings: the process running it stopped updating its record${at === undefined ? "" : ` at ${at}`}, most likely because it ended. Analyze the run again with the next command.`, analyzeCommand(source, progress?.stage === "analysis" ? progress.provider : undefined));
+    return withoutFindings(source, "failed", "AUTOMATIC_ANALYSIS_STOPPED", `The automatic analysis stopped before it wrote findings: the process running it stopped updating its record${at === undefined ? "" : ` at ${at}`}, most likely because it ended. Analyze the run again with the next command.`, analyzeCommand(source, progress?.stage === "analysis" ? progress.analyst : undefined));
 }
 /**
  * A run that ended, by a signal, a process that left without publishing, or a heartbeat that
@@ -217,7 +233,9 @@ async function studyAnalyst(cwd, study) {
     if (!resolved?.ok || resolved.config.id !== study.id)
         return undefined;
     const analysis = resolveAutomaticAnalysis(resolved.config.review?.analysis, resolved.config.actor);
-    return analysis.ok ? analysis.config?.provider : undefined;
+    return analysis.ok && analysis.config !== undefined
+        ? { provider: analysis.config.provider, model: analysis.config.model }
+        : undefined;
 }
 /** The findings view of a run's selected analysis, or why it has none. */
 export function analysisFindings(source) {
@@ -236,7 +254,9 @@ export function analysisFindings(source) {
             message: stale
                 ? `The run's evidence changed after analysis ${analysis.id}, so its findings may not match the run.`
                 : `Analysis ${analysis.id} is ${analysis.status}, with ${plural(result.findings.length, "finding")}.`,
-            next: stale ? analyzeCommand(source, analysis.provider) : null,
+            next: stale
+                ? analyzeCommand(source, { provider: analysis.provider, model: analysis.config.model })
+                : null,
             analysisId: analysis.id,
             status: analysis.status,
             provider: analysis.provider,
@@ -259,16 +279,16 @@ export function analysisFindings(source) {
     if (pending !== undefined)
         return pending;
     if (analysis && analysis.result === null)
-        return withoutFindings(source, "failed", analysis.error, `Analysis attempt ${analysis.id} ${analysis.status === "cancelled" ? "was cancelled" : "failed"}${analysis.error ? ` (${analysis.error})` : ""} and left no findings.`, analyzeCommand(source, analysis.provider));
+        return withoutFindings(source, "failed", analysis.error, `Analysis attempt ${analysis.id} ${analysis.status === "cancelled" ? "was cancelled" : "failed"}${analysis.error ? ` (${analysis.error})` : ""} and left no findings.`, analyzeCommand(source, { provider: analysis.provider, model: analysis.config.model }));
     if (job?.state === "failed" || job?.state === "cancelled") {
         const outcome = analysisOutcomeText(job);
-        return withoutFindings(source, "failed", job.reason, `The automatic analysis ${outcome.startsWith("failed") ? "" : "was "}${outcome}.`, analyzeCommand(source, job.reason === "AUTOMATIC_ANALYSIS_CODEX_UNAVAILABLE" ? "codex" : undefined));
+        return withoutFindings(source, "failed", job.reason, `The automatic analysis ${outcome.startsWith("failed") ? "" : "was "}${outcome}.`, analyzeCommand(source, job.reason === "AUTOMATIC_ANALYSIS_CODEX_UNAVAILABLE" ? { provider: "codex" } : undefined));
     }
     if (job?.state === "skipped" && job.admission) {
         const refusal = costRefusal(job.admission, `--run ${source.runId}${source.cwdFlag}`, cli);
         return withoutFindings(source, "skipped", job.reason, `The automatic analysis was refused before it started. ${refusal.text}`, refusal.command);
     }
-    if (job?.state === "skipped" && job.reason === "AUTOMATIC_ANALYSIS_KEY_MISSING")
+    if (job?.state === "skipped" && job.reason !== null && KEY_MISSING_REASONS.has(job.reason))
         return missingKeyFindings(source, job.reason);
     if (job?.state === "skipped") {
         const refused = job.reason === "AUTOMATIC_ANALYSIS_ADMISSION_REFUSED";
@@ -339,20 +359,22 @@ export async function readRunAnalysis(cwd, run, analysisId, deps = {}) {
     const record = isRunStatusRecord(status) && status.runId === runIdOf(prepared) ? status : null;
     const phase = record === null ? undefined : runAnalysisPhase(record, nowMs);
     const stopped = phase?.state === "stopped" || loaded.automatic?.reason === "AUTOMATIC_ANALYSIS_STOPPED";
-    const provider = stopped ? await studyAnalyst(physical, study) : undefined;
+    const missingKeyReason = loaded.automatic?.reason ?? null;
+    const keyMissing = missingKeyReason !== null && KEY_MISSING_REASONS.has(missingKeyReason);
+    const analyst = stopped || keyMissing ? await studyAnalyst(physical, study) : undefined;
     const progress = phase !== undefined && record !== null
         ? {
             stage: "analysis",
             phase,
             updatedAt: record.updatedAt,
-            ...(provider === undefined ? {} : { provider }),
+            ...(analyst === undefined ? {} : { analyst }),
         }
         : bundle?.bundle.outcome === undefined &&
             record !== null &&
             classifyRunStatus(record, nowMs) === "running"
             ? { stage: "participants" }
             : cutOff(bundle?.bundle, record, nowMs);
-    const codexSignedIn = loaded.automatic?.reason === "AUTOMATIC_ANALYSIS_KEY_MISSING"
+    const codexSignedIn = missingKeyReason === "AUTOMATIC_ANALYSIS_KEY_MISSING"
         ? await (deps.codexSignedIn ?? codexSignedInHere)().catch(() => false)
         : undefined;
     return {
@@ -367,6 +389,7 @@ export async function readRunAnalysis(cwd, run, analysisId, deps = {}) {
             ? {}
             : { study: { id: study.id, ...(study.path === undefined ? {} : { path: study.path }) } }),
         ...(codexSignedIn === undefined ? {} : { codexSignedIn }),
+        ...(keyMissing && analyst !== undefined ? { analyst } : {}),
         ...(progress === undefined ? {} : { progress }),
         nowMs,
     };

package/dist/cli/io.d.ts

@@ -45,6 +45,14 @@ export interface StudyCommandOptions {
     port?: string | undefined;
     rerunFailedFrom?: string | undefined;
     runId?: string | undefined;
+    /** Run the study in a runner sandbox on its participants' provider. */
+    remote?: boolean | undefined;
+    /** Hidden: the run key the run's sandboxes carry, chosen by a remote run's launcher. */
+    ownerKey?: string | undefined;
+    /** Hidden, watch only: bind the served Observer on every interface (a remote run's runner). */
+    allInterfaces?: boolean | undefined;
+    /** Hidden, watch only: also write the run's result and exit code to this file as JSON. */
+    resultFile?: string | undefined;
     /** watch only: serve and follow the Observer even without an interactive terminal. */
     serve?: boolean | undefined;
     /** Repo-relative path to an adopter scorer module; overrides review.scorer.ref when set. */

package/dist/cli/io.js

@@ -2,7 +2,7 @@ import { automaticAnalysisSucceeded, } from "../analysis/automatic-completion.js
 import { costRefusal, refusedCost } from "../analysis/admission.js";
 import { Command, Option } from "commander";
 import { loadEnvFile, recordDotenvNames } from "../keys/env-file.js";
-import { discoverProviderKeys } from "../keys/key-resolution.js";
+import { analysisKeyNames, discoverProviderKeys } from "../keys/key-resolution.js";
 import { deriveRunFacts } from "./telemetry.js";
 import { warnAndQueue, withQueuedWarnings } from "./deprecations.js";
 import { forTerminal } from "../routes/terminal/encoding.js";
@@ -297,6 +297,7 @@ export function wantsJson(command) {
 const ANALYSIS_REASON_TEXT = {
     AUTOMATIC_ANALYSIS_DRY_RUN: "skipped for dry runs",
     AUTOMATIC_ANALYSIS_KEY_MISSING: "skipped because OPENAI_API_KEY is not set",
+    AUTOMATIC_ANALYSIS_GEMINI_KEY_MISSING: `skipped because ${analysisKeyNames("gemini").join(" and ")} are not set`,
     AUTOMATIC_ANALYSIS_NO_PARTICIPANT_EVIDENCE: "skipped because no participant left evidence",
     AUTOMATIC_ANALYSIS_ACTOR_CANCELLED: "skipped because the run stopped before its participants finished",
     AUTOMATIC_ANALYSIS_SOURCE_UNAVAILABLE: "skipped because the run's evidence could not be read",

package/dist/keys/key-resolution.d.ts

@@ -1,3 +1,12 @@
+/** The key each API analyst reads, under its first spelling. */
+declare const ANALYSIS_KEYS: {
+    readonly openai: "OPENAI_API_KEY";
+    readonly gemini: "GEMINI_API_KEY";
+};
+/** The env names an API analyst's key may have, in the order they are read. */
+export declare const analysisKeyNames: (vendor: keyof typeof ANALYSIS_KEYS) => readonly string[];
+/** An API analyst's key from `env`: the first of its names with a non-blank value, else "". */
+export declare function analysisApiKey(vendor: keyof typeof ANALYSIS_KEYS, env: Readonly<Record<string, string | undefined>>): string;
 /** The vendor aliases `humanish keys set` accepts. A raw ENV_NAME is also accepted. */
 export declare const KEY_VENDORS: string[];
 /** The keys `humanish keys` lists, in its order, each with what humanish uses it for. */
@@ -77,3 +86,4 @@ export declare function setUserKey(name: string, value: string, env: NodeJS.Proc
 export declare function unsetUserKey(name: string, env: NodeJS.ProcessEnv, deps?: KeyResolutionDeps): boolean;
 /** The names (never values) currently in the user store. */
 export declare function listUserKeys(env: NodeJS.ProcessEnv, deps?: KeyResolutionDeps): string[];
+export {};