humanish 0.141.0 → 0.143.0

package/dist/analysis/responses.js

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

package/dist/analysis/service.js

@@ -1,5 +1,6 @@
 import { defaultCodexCliVersion, describeCodexCliAdmission, } from "../actors/codex/codex-admission.js";
 import { validCodexAnalysisConfig } from "./codex-config.js";
+import { analysisApiKey, analysisKeyNames, missingKeyHint } from "../keys/key-resolution.js";
 import { randomUUID } from "node:crypto";
 import { realpath } from "node:fs/promises";
 import path from "node:path";
@@ -55,7 +56,7 @@ const messages = {
     ANALYSIS_SOURCE_CHANGED: "The source recording changed during analysis. The result cannot be published against different evidence.",
     ANALYSIS_BUSY: "Another analysis holds this run's .analysis-lock directory, and its process is still running or humanish cannot check it (another host, or a lock written by humanish 0.139.1 or earlier). Wait for it to finish; if no humanish process is running for this run, remove that directory.",
     ANALYSIS_HISTORY_UNAVAILABLE: "Analysis history is unavailable or full. No request was sent. Inspect this run's analysis and analysis-attempts storage before retrying.",
-    ANALYSIS_CONFIG_INVALID: "OpenAI analysis needs a supported model, positive USD admission limit and 256–32768 output tokens. Codex account analysis uses its qualified model and null dollar/output-token caps. Both require timeout 1–600000 ms.",
+    ANALYSIS_CONFIG_INVALID: "OpenAI and Gemini analysis need a supported model of that provider, a positive USD admission limit and 256–32768 output tokens. Codex account analysis uses its qualified model and null dollar/output-token caps. All require timeout 1–600000 ms.",
     ANALYSIS_QUESTION_UNSAFE: "The reviewer question matched a sensitive-text pattern. Remove sensitive details before retrying.",
     ANALYSIS_API_KEY_MISSING: "Set OPENAI_API_KEY to run analysis. --dry-run checks admission without a key or provider request.",
     ANALYSIS_CANCELLED: "Analysis was cancelled before dispatch.",
@@ -285,9 +286,16 @@ async function executeAnalysis(attempt) {
     // An unreadable inventory is not evidence of an absent prior result.
     // Check readable history capacity before any new paid attempt.
     await assertAnalysisPublicationCapacity(prepared);
-    const apiKey = config.provider === "codex" ? "" : (deps.apiKey ?? process.env.OPENAI_API_KEY ?? "");
+    const apiKey = config.provider === "codex"
+        ? ""
+        : (deps.apiKey ?? analysisApiKey(config.provider ?? "openai", process.env));
     if (config.provider !== "codex" && !apiKey.trim())
-        return { ...fail(input.runId, false, "ANALYSIS_API_KEY_MISSING"), admission };
+        return {
+            ...fail(input.runId, false, "ANALYSIS_API_KEY_MISSING", config.provider === "gemini"
+                ? `Gemini analysis needs ${analysisKeyNames("gemini").join(" or ")}: ${missingKeyHint(analysisKeyNames("gemini")[0])}. --dry-run checks admission without a key or provider request.`
+                : undefined),
+            admission,
+        };
     let finalizeExecution;
     const rejection = {};
     const analysis = await runAnalysis(input, config, {

package/dist/analysis/types.d.ts

@@ -1,5 +1,6 @@
 import type { ActorStatus, ActorCompletionReason, ActorStopCause, ParticipantDeclaredOutcome } from "../actors/contract.js";
 import type { CuaEndpointSource } from "../actors/goal-source.js";
+import type { ReasoningEffort } from "../actors/reasoning-effort.js";
 import type { AutomaticAnalysisView } from "./job.js";
 import type { RunAnalysisCost } from "../run/run-cost.js";
 /** Independent interpretation of retained evidence; never a participant or harness verdict. */
@@ -160,6 +161,13 @@ interface OpenAIAnalysisConfig {
     maxCostUsd: number;
     timeoutMs: number;
     maxOutputTokens: number;
+    /** Present only when the study or command declared it, so an omitted effort keeps the hash of
+     * every configuration before the field. An analysis without it ran at high (models.ts). */
+    reasoningEffort?: ReasoningEffort | undefined;
+}
+/** The Gemini API analyst: the same billed, capped request as OpenAI's, sent to Google. */
+interface GeminiAnalysisConfig extends Omit<OpenAIAnalysisConfig, "provider"> {
+    provider: "gemini";
 }
 /** Required, qualified execution profile, confirmed by the launcher before a turn.
  * A failed pre-dispatch artifact does not prove this CLI/model was observed.
@@ -184,7 +192,9 @@ export interface CodexAnalysisConfig {
     identity: CodexAnalysisIdentity;
 }
 /** Omitted provider remains the historical OpenAI API contract, including its exact hash. */
-export type AnalysisConfig = OpenAIAnalysisConfig | CodexAnalysisConfig;
+export type AnalysisConfig = OpenAIAnalysisConfig | GeminiAnalysisConfig | CodexAnalysisConfig;
+/** Who analyzed: an API billed by key (openai, gemini) or the restricted Codex account. */
+export type AnalysisProviderName = "openai" | "gemini" | "codex";
 export interface AnalysisUsage {
     inputTokens: number | null;
     outputTokens: number | null;
@@ -209,7 +219,7 @@ export interface AnalysisArtifact {
     configDigest: string;
     config: AnalysisConfig;
     promptVersion: string;
-    provider: "openai" | "codex";
+    provider: AnalysisProviderName;
     usage: AnalysisUsage;
     participants: AnalysisParticipantInput[];
     coverage: AnalysisCoverage;

package/dist/analysis/validation.d.ts

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

package/dist/analysis/validation.js

@@ -3,6 +3,7 @@ import { createHash } from "node:crypto";
 import { z } from "zod";
 import { ACTOR_STATUSES, ACTOR_STOP_CAUSES } from "../actors/contract.js";
 import { CUA_ENDPOINT_SOURCES } from "../actors/goal-source.js";
+import { REASONING_EFFORTS } from "../actors/reasoning-effort.js";
 import { ANALYSIS_LIMITS, EVIDENCE_LIMITS, MAX_ANALYSIS_COHORTS, hasControlCharacter, hasRevisionFields, } from "./analysis-limits.js";
 import { SHA256_HEX_PATTERN, ACTION_CAPTURE_VERSION, ANALYSIS_SCHEMA, ANALYSIS_CORRECTION_SCHEMA, } from "./types.js";
 const text = (max) => z
@@ -196,6 +197,16 @@ const analysisParticipantProvenanceSchema = z
         .nullable(),
 })
     .strict();
+/** The configuration of an analyst billed by API key. Stored artifacts keep the bounds of every
+ * release that wrote them; admission checks the current ones before a request. */
+const apiAnalysisConfigSchema = z.object({
+    model: label,
+    question: text(4000).nullable(),
+    maxCostUsd: z.number().positive().max(1000),
+    timeoutMs: z.number().int().positive().max(3600000),
+    maxOutputTokens: z.number().int().positive().max(128000),
+    reasoningEffort: z.enum(REASONING_EFFORTS).optional(),
+});
 const analysisArtifactSchema = z
     .object({
     schema: z.literal(ANALYSIS_SCHEMA),
@@ -209,16 +220,8 @@ const analysisArtifactSchema = z
     inputDigest: digest,
     configDigest: digest,
     config: z.union([
-        z
-            .object({
-            provider: z.literal("openai").optional(),
-            model: label,
-            question: text(4000).nullable(),
-            maxCostUsd: z.number().positive().max(1000),
-            timeoutMs: z.number().int().positive().max(3600000),
-            maxOutputTokens: z.number().int().positive().max(128000),
-        })
-            .strict(),
+        apiAnalysisConfigSchema.extend({ provider: z.literal("openai").optional() }).strict(),
+        apiAnalysisConfigSchema.extend({ provider: z.literal("gemini") }).strict(),
         z
             .object({
             provider: z.literal("codex"),
@@ -243,7 +246,7 @@ const analysisArtifactSchema = z
             .strict(),
     ]),
     promptVersion: label,
-    provider: z.enum(["openai", "codex"]),
+    provider: z.enum(["openai", "gemini", "codex"]),
     usage: z
         .object({
         cacheWriteInputTokens: z.number().int().min(0).max(1e12).nullable(),
@@ -360,8 +363,7 @@ export function checkAnalysisResult(input, value) {
         if (!distinct(observation.evidenceIds) ||
             refs.some((ref) => !ref || !included.has(ref.streamId)))
             errors.add("ANALYSIS_OBSERVATION_REFERENCE_INVALID");
-        if (observation.basis === "visual" &&
-            !refs.some((ref) => ref?.capture !== null && ref?.capture !== undefined))
+        if (observation.basis === "visual" && !refs.some((ref) => ref?.capture))
             errors.add("ANALYSIS_VISUAL_WITHOUT_CAPTURE");
         if (observation.basis === "action" &&
             !refs.some((ref) => ref &&
@@ -393,7 +395,7 @@ export function checkAnalysisResult(input, value) {
         const refs = finding.evidenceIds.map((ref) => evidence.get(ref));
         if (!distinct(finding.evidenceIds) || refs.some((ref) => !ref || !included.has(ref.streamId)))
             errors.add("ANALYSIS_DESIGN_REFERENCE_INVALID");
-        if (!refs.some((ref) => ref?.capture !== null && ref?.capture !== undefined))
+        if (!refs.some((ref) => ref?.capture))
             errors.add("ANALYSIS_DESIGN_WITHOUT_CAPTURE");
         // Seen by means a cited capture of that participant shows the problem.
         const captured = new Set(refs.flatMap((ref) => (ref?.capture ? [ref.streamId] : [])));
@@ -547,7 +549,7 @@ export function validateAnalysisExecutionReceipt(value) {
     const parsed = analysisExecutionReceiptSchema.safeParse(value);
     if (!parsed.success || Date.parse(parsed.data.completedAt) < Date.parse(parsed.data.createdAt))
         throw new Error("ANALYSIS_RECEIPT_INVALID");
-    if ((parsed.data.provider === "openai" && parsed.data.maxCostUsd === null) ||
+    if ((parsed.data.provider !== "codex" && parsed.data.maxCostUsd === null) ||
         (parsed.data.provider === "codex" &&
             (parsed.data.maxCostUsd !== null ||
                 parsed.data.usage.estimatedCostUsd !== null ||

package/dist/cli/commands/analyze.js

@@ -1,8 +1,10 @@
-import { analysisRequestsText, resolveAutomaticAnalysis, DEFAULT_ANALYSIS_MODEL, DEFAULT_ANALYSIS_TIMEOUT_MS, } from "../../analysis/automatic-config.js";
+import { analysisRequestsText, resolveAutomaticAnalysis, DEFAULT_ANALYSIS_EFFORT, 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/models.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,13 @@ 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: ${SUPPORTED_ANALYSIS_MODELS.join(", ")}; ${DEFAULT_ANALYSIS_MODEL} at ${DEFAULT_ANALYSIS_EFFORT} effort when omitted. Gemini analysis model: ${GEMINI_ANALYSIS_MODELS.join(", ")}; ${DEFAULT_GEMINI_ANALYSIS_MODEL} when omitted. Codex account analysis runs ${CODEX_ANALYSIS_MODEL} at low effort.`)
+        .option("--reasoning-effort <level>", `OpenAI reasoning.effort or Gemini thinking level, from none, minimal, low, medium, high, xhigh and max; each model takes only the levels its provider documents for it, and others are refused before any request. When omitted: ${DEFAULT_ANALYSIS_EFFORT} for the default OpenAI analyst, high with --model or --provider gemini. Unsupported for Codex.`)
         .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 +76,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
@@ -82,6 +85,7 @@ async function handleAnalyze(io, options, command) {
         ...(options.maxOutputTokens === undefined
             ? {}
             : { maxOutputTokens: Number(options.maxOutputTokens) }),
+        ...(options.reasoningEffort === undefined ? {} : { reasoningEffort: options.reasoningEffort }),
     });
     if (!selected.ok || !selected.config) {
         const refusal = await dryRunBundleRefusal(await resolvePhysicalCwd(options.cwd), options.run, options.dryRun === true);
@@ -106,7 +110,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/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.",