humanish 0.141.0 → 0.143.0

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,12 @@ interface LiveStudy {
 }
 /** ` --cwd <dir>`, or "" when `cwd` is the current directory. */
 export declare function cwdFlag(cwd: string): string;
+/** An analysis provider, model and effort, as a study or an analysis record names them. */
+interface Analyst {
+    provider?: string | undefined;
+    model?: string;
+    reasoningEffort?: string | undefined;
+}
 /** 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

@@ -5,7 +5,7 @@
 // starts an analysis.
 import path from "node:path";
 import { costRefusal } from "../analysis/admission.js";
-import { DEFAULT_ANALYSIS_MAX_COST_USD, resolveAutomaticAnalysis, } from "../analysis/automatic-config.js";
+import { DEFAULT_ANALYSIS_EFFORT, DEFAULT_ANALYSIS_MAX_COST_USD, DEFAULT_ANALYSIS_MODEL, resolveAutomaticAnalysis, } from "../analysis/automatic-config.js";
 import { ANALYSIS_USUALLY_TAKES } from "../analysis/analysis-limits.js";
 import { bySeverity } from "../analysis/finding-lead.js";
 import { loadAnalysis } from "../analysis/load.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,30 @@ 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 effort an analysis configuration declares; Codex configurations declare none. */
+const declaredEffort = (config) => "reasoningEffort" in config ? config.reasoningEffort : undefined;
+/** 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`;
+    if (analyst?.provider === "gemini") {
+        const model = analyst.model === undefined ? "" : ` --model ${analyst.model}`;
+        return `${run} --provider gemini${model} --max-cost ${DEFAULT_ANALYSIS_MAX_COST_USD}`;
+    }
+    // A named model or effort stays in the command, so the rerun is the same analyst. The default
+    // analyst needs neither: `analyze` without flags runs it.
+    const isDefault = (analyst?.model ?? DEFAULT_ANALYSIS_MODEL) === DEFAULT_ANALYSIS_MODEL &&
+        (analyst?.model === undefined || analyst.reasoningEffort === DEFAULT_ANALYSIS_EFFORT);
+    const flags = isDefault
+        ? ""
+        : ` --model ${analyst.model}${analyst.reasoningEffort === undefined ? "" : ` --reasoning-effort ${analyst.reasoningEffort}`}`;
+    return `${run}${flags} --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 +177,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));
+        return withoutFindings(source, "skipped", reason, `${opening} Set it with ${cli("keys set openai")}, then run the next command.`, analyzeCommand(source, source.analyst?.provider === "gemini" ? undefined : source.analyst));
     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 +220,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 +243,13 @@ 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,
+            reasoningEffort: declaredEffort(analysis.config),
+        }
+        : undefined;
 }
 /** The findings view of a run's selected analysis, or why it has none. */
 export function analysisFindings(source) {
@@ -236,7 +268,13 @@ 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,
+                    reasoningEffort: declaredEffort(analysis.config),
+                })
+                : null,
             analysisId: analysis.id,
             status: analysis.status,
             provider: analysis.provider,
@@ -259,16 +297,20 @@ 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,
+            reasoningEffort: declaredEffort(analysis.config),
+        }));
     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 +381,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 +411,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 {};

package/dist/keys/key-resolution.js

@@ -11,7 +11,7 @@
 //        GH_TOKEN     <- `gh auth token` (the gh CLI's credential chain);
 //   4. the humanish user-level store `$XDG_CONFIG_HOME/humanish/keys.env`, written only by
 //      `humanish keys set` (0600, prompted or --stdin), the fallback for vendors that ship
-//      no machine chain of their own (OpenAI, Anthropic).
+//      no machine chain of their own (OpenAI, Anthropic, Gemini).
 //
 // Every fill is announced by key name + source, never by value. The subject app's own
 // `.env`/`.env.local` are never read: those hold product credentials, a different class
@@ -34,7 +34,8 @@ import { OPENAI_EGRESS_PLACEHOLDER } from "../routes/terminal/runtime-auth.js";
  * full-file load). ANTHROPIC_API_KEY is not listed, and doctor does not report it: a Claude Code
  * participant runs on its own login and never receives it. CODEX_API_KEY is an alternative spelling
  * of the OpenAI key for terminal studies. Doctor reports AGENTMAIL_API_KEY only under `--study`, for
- * a study whose email connection names it, since a connection may name another variable.
+ * a study whose email connection names it, since a connection may name another variable, and
+ * GEMINI_API_KEY only for a study whose analysis runs on Gemini.
  */
 const PROVIDER_KEYS = [
     {
@@ -69,9 +70,33 @@ const PROVIDER_KEYS = [
     { name: "GITHUB_TOKEN", spellingOf: "GH_TOKEN" },
     { name: "CODEX_API_KEY", doctor: true },
     { name: "AGENTMAIL_API_KEY", vendor: "agentmail", listed: { order: 4, use: "email in studies" } },
+    { name: "GEMINI_API_KEY", vendor: "gemini", listed: { order: 5, use: "analysis on Gemini" } },
+    // Google's client libraries also read GOOGLE_API_KEY, and prefer it when both are set. humanish
+    // reads GEMINI_API_KEY first: a GOOGLE_API_KEY exported for Maps or Firebase must not take the
+    // place of the key `humanish keys set gemini` stored.
+    { name: "GOOGLE_API_KEY", spellingOf: "GEMINI_API_KEY" },
 ];
 const PROVIDER_KEY_SET = new Set(PROVIDER_KEYS.map((key) => key.name));
 const providerKey = (name) => PROVIDER_KEYS.find((key) => key.name === name);
+/**
+ * Every env name of the key `name` is a spelling of, in the order humanish reads them: the key's
+ * own name, then its second spellings. Discovery treats them as one key.
+ */
+function keyNames(name) {
+    const own = providerKey(name)?.spellingOf ?? name;
+    return [own, ...PROVIDER_KEYS.filter((key) => key.spellingOf === own).map((key) => key.name)];
+}
+/** The key each API analyst reads, under its first spelling. */
+const ANALYSIS_KEYS = { openai: "OPENAI_API_KEY", gemini: "GEMINI_API_KEY" };
+/** The env names an API analyst's key may have, in the order they are read. */
+export const analysisKeyNames = (vendor) => keyNames(ANALYSIS_KEYS[vendor]);
+/** An API analyst's key from `env`: the first of its names with a non-blank value, else "". */
+export function analysisApiKey(vendor, env) {
+    for (const name of analysisKeyNames(vendor))
+        if (env[name]?.trim())
+            return env[name];
+    return "";
+}
 /** The vendor aliases `humanish keys set` accepts. A raw ENV_NAME is also accepted. */
 export const KEY_VENDORS = PROVIDER_KEYS.flatMap((key) => key.vendor === undefined ? [] : [key.vendor]);
 /** The keys `humanish keys` lists, in its order, each with what humanish uses it for. */
@@ -212,8 +237,11 @@ export async function discoverProviderKeys(args) {
     const ignored = [];
     // Fill-only means presence wins, including an explicitly-set empty value: an operator who
     // exported OPENAI_API_KEY="" said "off", and a rung that "fixes" that has overridden them.
-    // Only a truly-unset name is fillable.
-    const fillable = (name) => env[name] === undefined;
+    // Only a truly-unset name is fillable, and only while no spelling of its key was set before
+    // discovery: a repo overlay's GOOGLE_API_KEY must not stand beside, and outrank, an exported
+    // GEMINI_API_KEY. Spellings that discovery itself fills may stand together.
+    const explicit = new Set(Object.keys(env).filter((name) => env[name] !== undefined));
+    const fillable = (name) => env[name] === undefined && keyNames(name).every((spelling) => !explicit.has(spelling));
     const fill = (name, value, source) => {
         env[name] = value;
         fills.push({ name, source });
@@ -259,7 +287,7 @@ export async function discoverProviderKeys(args) {
     // Rung 3c: the gh CLI's credential chain. Only consulted when neither GitHub env name is
     // present; fills GH_TOKEN (the name humanish reads first). gh runs without any provider key in
     // its environment, so the keys the rungs above just filled stay in this process.
-    if (fillable("GH_TOKEN") && fillable("GITHUB_TOKEN")) {
+    if (keyNames("GH_TOKEN").every((name) => env[name] === undefined)) {
         const exec = deps.execText ?? defaultExecText;
         const token = await exec("gh", ["auth", "token"], 3_000, withoutProviderKeys(env));
         if (token !== null)

package/dist/observer/listen.d.ts

@@ -12,5 +12,10 @@ export declare class PortInUseError extends Error {
  * that cannot decide says "other", which is the answer that suggests the safer action.
  */
 export declare function probePortHolder(port: number, fetchFn?: typeof fetch): Promise<PortHolder>;
-/** Bind on loopback only; resolve the port that was actually bound; name a taken port. */
-export declare function listenOnLoopback(server: Server, port: number, probe?: (port: number) => Promise<PortHolder>): Promise<number>;
+/**
+ * Bind on loopback; resolve the port that was actually bound; name a taken port. `allInterfaces`
+ * binds every interface instead, for the Observer of a remote run's runner sandbox: Modal's proxy
+ * cannot reach a loopback-only server, and only the provider's authenticated proxy reaches the
+ * sandbox's ports.
+ */
+export declare function listenOnLoopback(server: Server, port: number, probe?: (port: number) => Promise<PortHolder>, allInterfaces?: boolean): Promise<number>;

package/dist/observer/listen.js

@@ -61,8 +61,13 @@ async function probeRoutes(port, fetchFn) {
     }
     return "other";
 }
-/** Bind on loopback only; resolve the port that was actually bound; name a taken port. */
-export function listenOnLoopback(server, port, probe = probePortHolder) {
+/**
+ * Bind on loopback; resolve the port that was actually bound; name a taken port. `allInterfaces`
+ * binds every interface instead, for the Observer of a remote run's runner sandbox: Modal's proxy
+ * cannot reach a loopback-only server, and only the provider's authenticated proxy reaches the
+ * sandbox's ports.
+ */
+export function listenOnLoopback(server, port, probe = probePortHolder, allInterfaces = false) {
     return new Promise((resolve, reject) => {
         const onError = (error) => {
             if (error.code === "EADDRINUSE") {
@@ -72,8 +77,9 @@ export function listenOnLoopback(server, port, probe = probePortHolder) {
             reject(error);
         };
         server.once("error", onError);
-        // Never beyond loopback; exposure only ever happens through a tunnel or proxy forwarding here.
-        server.listen(port, "127.0.0.1", () => {
+        // Otherwise never beyond loopback; exposure only ever happens through a tunnel or proxy
+        // forwarding here.
+        server.listen(port, allInterfaces ? "0.0.0.0" : "127.0.0.1", () => {
             server.off("error", onError);
             const address = server.address();
             if (!address || typeof address === "string") {

package/dist/observer/render.d.ts

@@ -31,6 +31,8 @@ export interface ObserverServeOptions {
     /** Restrict history and evidence routes to the selected run. Exposed viewers always do this. */
     scope?: "run" | "library";
     exposed?: boolean;
+    /** Bind every interface: only a remote run's runner sandbox, behind its provider's proxy. */
+    allInterfaces?: boolean;
 }
 export interface ObserverServer {
     url: string;

package/dist/observer/render.js

@@ -293,7 +293,7 @@ export async function serveObserver(result, options = {}) {
     const server = createServer((request, response) => {
         void handleRequest(request, response);
     });
-    port = await listenOnLoopback(server, options.port ?? 0);
+    port = await listenOnLoopback(server, options.port ?? 0, undefined, options.allInterfaces === true);
     if (exposed) {
         hostAllowlist.add(`127.0.0.1:${port}`);
         hostAllowlist.add(`localhost:${port}`);