humanish 0.140.0 → 0.142.0

package/dist/cli/commands/analysis-signals.d.ts

@@ -1,8 +1,14 @@
 import type { RunStudyOptions } from "../../run-study.js";
+import { type HostClock } from "../../run/host-suspension.js";
 import type { CliIo } from "../io.js";
 /**
- * Post-run analysis cancellation for the CLI: while analysis runs, SIGINT, SIGTERM and SIGHUP abort
- * it. The listeners exist only during analysis; before it, the run's own handlers
- * (run-signals.ts) hold the signals and hand them over here.
+ * The CLI's run events. When the run starts, one stderr line names it and the command that
+ * follows it. While analysis runs, SIGINT, SIGTERM and SIGHUP abort it; the listeners exist only
+ * during analysis, since before it the run's own handlers (run-signals.ts) hold the signals and
+ * hand them over here. A human also gets a line when analysis starts and one with its elapsed
+ * time every 20 s; `--json` gets only the first line, on stderr, so stdout stays one result.
  */
-export declare function cliAnalysisOptions(io: Pick<CliIo, "writeErr">): Pick<RunStudyOptions, "onEvent" | "analysisSignal">;
+export declare function cliRunEventOptions(io: Pick<CliIo, "writeErr">, options?: {
+    json?: boolean;
+    clock?: HostClock;
+}): Pick<RunStudyOptions, "onEvent" | "analysisSignal">;

package/dist/cli/commands/analysis-signals.js

@@ -1,25 +1,47 @@
+import { ANALYSIS_USUALLY_TAKES } from "../../analysis/analysis-limits.js";
+import { systemHostClock } from "../../run/host-suspension.js";
+import { formatDuration } from "../../run/projection.js";
+import { cli } from "../invocation.js";
 import { handOverRunSignals } from "./run-signals.js";
+/** How often a human sees how long analysis has run: often enough to look alive, rarely enough
+ *  to read as one line per glance. */
+const ANALYSIS_PROGRESS_MS = 20_000;
 /**
- * Post-run analysis cancellation for the CLI: while analysis runs, SIGINT, SIGTERM and SIGHUP abort
- * it. The listeners exist only during analysis; before it, the run's own handlers
- * (run-signals.ts) hold the signals and hand them over here.
+ * The CLI's run events. When the run starts, one stderr line names it and the command that
+ * follows it. While analysis runs, SIGINT, SIGTERM and SIGHUP abort it; the listeners exist only
+ * during analysis, since before it the run's own handlers (run-signals.ts) hold the signals and
+ * hand them over here. A human also gets a line when analysis starts and one with its elapsed
+ * time every 20 s; `--json` gets only the first line, on stderr, so stdout stays one result.
  */
-export function cliAnalysisOptions(io) {
+export function cliRunEventOptions(io, options = {}) {
+    const clock = options.clock ?? systemHostClock;
     const controller = new AbortController();
     const cancel = () => {
         controller.abort();
     };
     const signals = ["SIGINT", "SIGTERM", "SIGHUP"];
+    let stopProgress;
     return {
         analysisSignal: controller.signal,
         onEvent: (event) => {
-            if (event.type === "analysis-started") {
-                io.writeErr("Participants finished; preparing analysis…\n");
+            if (event.type === "run-started") {
+                io.writeErr(`Run ${event.runId} started. Follow it with ${cli(`observe --run ${event.runId}`)}; ${cli("runs")} lists its state.\n`);
+            }
+            else if (event.type === "analysis-started") {
+                io.writeErr(`Participants finished. Writing findings; this usually takes ${ANALYSIS_USUALLY_TAKES}.\n`);
+                if (options.json !== true) {
+                    const startedMs = clock.now();
+                    stopProgress = clock.every(ANALYSIS_PROGRESS_MS, () => {
+                        io.writeErr(`Still writing findings: ${formatDuration(clock.now() - startedMs)} elapsed.\n`);
+                    });
+                }
                 handOverRunSignals();
                 for (const signal of signals)
                     process.on(signal, cancel);
             }
             else if (event.type === "analysis-finished") {
+                stopProgress?.();
+                stopProgress = undefined;
                 for (const signal of signals)
                     process.off(signal, cancel);
             }

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);
+}

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

@@ -6,7 +6,7 @@ import { DEFAULT_EXPORT_MAX_BYTES, exportRun, formatExportHuman } from "../../fe
 import { listRuns, readReview } from "../../run/stored-runs.js";
 import { verifyRun } from "../../verify/verify.js";
 import { reclaimPreflightSandboxes, reclaimRunSandboxes, } from "../../run/reclaim.js";
-import { runDisplay } from "../../run/display.js";
+import { analysisPhaseLabel, runDisplay } from "../../run/display.js";
 import { addRunOptions, handleRun } from "./run-command.js";
 import { applyEnvFileOption, CWD_OPTION_DESCRIPTION, DOTENV_OPTION_DESCRIPTION, dotenvPathOf, envFileAliasOption, JSON_OPTION_DESCRIPTION, parsePositiveInteger, RUN_OPTION_DESCRIPTION, writeResult, humanError, } from "../io.js";
 import { plural } from "../../run/text.js";
@@ -251,6 +251,8 @@ function formatReclaimHuman(result, cwd, preflight) {
     for (const outcome of result.outcomes) {
         lines.push(`  sandbox ${outcome.sandboxIdDigest} (${outcome.laneId}, from ${outcome.source}): ${outcome.state}${outcome.detail ? `: ${outcome.detail}` : ""}`);
     }
+    if (result.markedInterrupted === true)
+        lines.push("Its status.json had stopped updating while it still said running, so the run is now recorded as interrupted.");
     for (const warning of result.warnings)
         lines.push(`  warning: ${warning}`);
     if (result.error === undefined && result.state !== "clean")
@@ -378,6 +380,10 @@ function formatRunsHuman(result) {
     }
     return ([
         `latest: ${result.latest ?? "none"}`,
-        ...result.runs.map((run) => `- ${run.runId} ${run.mode ?? "unknown"} ${run.display?.label ?? "unreadable"} ${run.createdAt ?? "unknown"} ${run.path}`),
+        ...result.runs.map((run) => {
+            const analysis = analysisPhaseLabel(run.analysis);
+            const label = `${run.display?.label ?? "unreadable"}${analysis === undefined ? "" : `, ${analysis}`}`;
+            return `- ${run.runId} ${run.mode ?? "unknown"} ${label} ${run.createdAt ?? "unknown"} ${run.path}`;
+        }),
     ].join("\n") + "\n");
 }

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";
@@ -5,7 +6,7 @@ import { resolveStudyDryRun } from "../../study/plan.js";
 import { serveObserver } from "../../observer/render.js";
 import { startExposedObserver, validateExposure } from "../../observer/exposure.js";
 import { ServeTunnelError } from "../../observer/tunnel.js";
-import { cliAnalysisOptions } from "./analysis-signals.js";
+import { cliRunEventOptions } from "./analysis-signals.js";
 import { onRunShutdown } from "./run-signals.js";
 import { parseStudyCount, parseParticipantIds, parseObserverPort, wantsJson, writeResult, } from "../io.js";
 import { exposureRequestFromOptions, followDecision, followObserver, planObserver, showObserver, staticObserverOpen, withObserverServer, } from "../observer-follow.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) {
@@ -127,7 +137,7 @@ function prepareCuaWatch(args, settings) {
 function cuaRunOptions(args, settings, prepared, live) {
     const { finishedPlan } = prepared;
     return {
-        ...cliAnalysisOptions(args.io),
+        ...cliRunEventOptions(args.io, { json: wantsJson(args.command) }),
         cwd: args.options.cwd,
         // A followed watch opens the served Observer (or prints the phone target under --expose), so
         // its static render never opens. A non-follow watch opens what its plan says, once. Run mode
@@ -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

@@ -1,6 +1,6 @@
 import { automaticAnalysisSucceeded } from "../../analysis/automatic-completion.js";
 import { Command } from "commander";
-import { cliAnalysisOptions } from "./analysis-signals.js";
+import { cliRunEventOptions } from "./analysis-signals.js";
 import { wantsJson } from "../io.js";
 import { writeRunResult } from "../run-findings.js";
 import { showObserver } from "../observer-follow.js";
@@ -23,11 +23,12 @@ export function scriptedRouteRun(args) {
         return undefined;
     return {
         options: {
-            ...cliAnalysisOptions(args.io),
+            ...cliRunEventOptions(args.io, { json: wantsJson(args.command) }),
             cwd: args.options.cwd,
             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

@@ -3,7 +3,7 @@ import { Command } from "commander";
 import { resolveStudyDryRun } from "../../study/plan.js";
 import { serveObserver } from "../../observer/render.js";
 import { redactText } from "../../evidence/redaction.js";
-import { cliAnalysisOptions } from "./analysis-signals.js";
+import { cliRunEventOptions } from "./analysis-signals.js";
 import { parseObserverPort, wantsJson, writeResult, } from "../io.js";
 import { followDecision, followObserver, showObserver, staticObserverOpen, withObserverServer, } from "../observer-follow.js";
 import { writeRunResult } from "../run-findings.js";
@@ -65,7 +65,7 @@ export function sharedWorldRouteRun(args) {
     let observerFailure;
     return {
         options: {
-            ...cliAnalysisOptions(args.io),
+            ...cliRunEventOptions(args.io, { json: wantsJson(args.command) }),
             cwd: args.options.cwd,
             open: wantsFollow
                 ? false
@@ -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

@@ -1,6 +1,6 @@
 import { automaticAnalysisSucceeded } from "../../analysis/automatic-completion.js";
 import { Command } from "commander";
-import { cliAnalysisOptions } from "./analysis-signals.js";
+import { cliRunEventOptions } from "./analysis-signals.js";
 import { wantsJson } from "../io.js";
 import { writeRunResult } from "../run-findings.js";
 import { showObserver } from "../observer-follow.js";
@@ -23,11 +23,12 @@ export function terminalRouteRun(args) {
         return undefined;
     return {
         options: {
-            ...cliAnalysisOptions(args.io),
+            ...cliRunEventOptions(args.io, { json: wantsJson(args.command) }),
             cwd: args.options.cwd,
             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);