humanish 0.140.0 → 0.142.0

package/dist/cli/findings.d.ts

@@ -1,4 +1,5 @@
 import type { AnalysisArtifact, LoadedAnalysis } from "../analysis/types.js";
+import { type RunAnalysisPhase } from "../run/status.js";
 import { type RunStudyProvenance } from "../run/study-provenance.js";
 export declare const ANALYSIS_FINDINGS_SCHEMA = "humanish.analysis-findings.v1";
 type Finding = NonNullable<AnalysisArtifact["result"]>["findings"][number];
@@ -116,11 +117,35 @@ 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.
      */
     codexSignedIn?: boolean;
+    /**
+     * Where the run is before its findings, from status.json: its participants still running, or
+     * the automatic analysis its own process started. Undefined once neither applies.
+     */
+    progress?: {
+        stage: "participants";
+    }
+    /** The run ended while a participant stream was still running: nothing complete to analyze. */
+     | {
+        stage: "cut-off";
+        running: number;
+        streams: number;
+    } | {
+        stage: "analysis";
+        phase: RunAnalysisPhase;
+        /** status.json's last heartbeat. */
+        updatedAt: string;
+        /** The analyst the run's study gets, read only for an analysis whose process stopped. */
+        analyst?: Analyst;
+    };
+    /** When the view was built, for how long an analysis has run. */
+    nowMs?: number;
 }
 /** A study `run` can start live after a dry run. */
 interface LiveStudy {
@@ -133,6 +158,11 @@ interface LiveStudy {
 }
 /** ` --cwd <dir>`, or "" when `cwd` is the current directory. */
 export declare function cwdFlag(cwd: string): string;
+/** An analysis provider and model, as a study or an analysis record names them. */
+interface Analyst {
+    provider?: string | undefined;
+    model?: string;
+}
 /** The findings view of a run's selected analysis, or why it has none. */
 export declare function analysisFindings(source: FindingsSource): AnalysisFindings;
 /**

package/dist/cli/findings.js

@@ -5,11 +5,15 @@
 // starts an analysis.
 import path from "node:path";
 import { costRefusal } from "../analysis/admission.js";
-import { DEFAULT_ANALYSIS_MAX_COST_USD } from "../analysis/automatic-config.js";
+import { DEFAULT_ANALYSIS_MAX_COST_USD, 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";
 import { projectShareCheckedAnalysis } from "../analysis/sharing.js";
-import { loadRunBundlePrepared, resolveRunPath } from "../run/locate.js";
+import { loadRunBundlePrepared, readRunJsonIfExists, resolveRunPath, runJsonValue, } from "../run/locate.js";
+import { classifyRunStatus, isRunStatusRecord, RUN_STATUS_FILE, runAnalysisPhase, } from "../run/status.js";
+import { TERMINAL_SIMULATION_STATUSES } from "../run/streams.js";
+import { formatDuration } from "../run/projection.js";
 import { resolvePhysicalCwd, runIdOf } from "../run/paths.js";
 import { studyProvenanceOf } from "../run/study-provenance.js";
 import { resolveStudyManifest } from "../study/discover.js";
@@ -18,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) {
@@ -25,11 +30,20 @@ export function cwdFlag(cwd) {
         return "";
     return ` --cwd ${/^[\w@%+=:,./-]+$/.test(cwd) ? cwd : shellQuote(cwd)}`;
 }
-function analyzeCommand(source, provider) {
+/** The skip reasons for an analysis whose API key was missing, one per API analyst. */
+const KEY_MISSING_REASONS = new Set([
+    "AUTOMATIC_ANALYSIS_KEY_MISSING",
+    "AUTOMATIC_ANALYSIS_GEMINI_KEY_MISSING",
+]);
+/** The `analyze` command that runs `analyst` on the run; undefined is the OpenAI default. */
+function analyzeCommand(source, analyst) {
     const run = cli(`analyze --run ${source.runId}${source.cwdFlag}`);
-    return provider === "codex"
-        ? `${run} --provider codex`
-        : `${run} --max-cost ${DEFAULT_ANALYSIS_MAX_COST_USD}`;
+    if (analyst?.provider === "codex")
+        return `${run} --provider codex`;
+    const gemini = analyst?.provider === "gemini"
+        ? ` --provider gemini${analyst.model === undefined ? "" : ` --model ${analyst.model}`}`
+        : "";
+    return `${run}${gemini} --max-cost ${DEFAULT_ANALYSIS_MAX_COST_USD}`;
 }
 /** The cited items the analysis evidence resolves, each once, in citation order. */
 function citedEvidence(ids, analysis, runRoot) {
@@ -153,16 +167,75 @@ function dryRunFindings(source) {
     return withoutFindings(source, "dry_run", null, `${opening} Findings come from live runs: ${howLive}`, cli(`run ${live.run}${source.cwdFlag}`));
 }
 /**
- * An analysis skipped because OPENAI_API_KEY is not set. With Codex signed in, the next step is the
+ * An analysis skipped because its API key is not set. For OpenAI with Codex signed in, the next step is the
  * Codex account analyst, named as an opt-in: the study chose the OpenAI analyst, and switching
  * the account that pays for it is the operator's choice.
  */
 function missingKeyFindings(source, reason) {
+    // The skip reason records which analyst's key was missing; the study file only adds its model.
+    if (reason === "AUTOMATIC_ANALYSIS_GEMINI_KEY_MISSING")
+        return withoutFindings(source, "skipped", reason, `The automatic analysis was skipped because ${analysisKeyNames("gemini").join(" and ")} are not set. Store the key with ${cli("keys set gemini")}, then run the next command.`, analyzeCommand(source, {
+            provider: "gemini",
+            ...(source.analyst?.provider === "gemini" ? { model: source.analyst.model } : {}),
+        }));
     const opening = "The automatic analysis was skipped because OPENAI_API_KEY is not set.";
     if (source.codexSignedIn !== true)
         return withoutFindings(source, "skipped", reason, `${opening} Set it with ${cli("keys set openai")}, then run the next command.`, analyzeCommand(source, undefined));
     const file = source.study?.path === undefined ? "the study file" : source.study.path;
-    return withoutFindings(source, "skipped", reason, `${opening} Codex is signed in on this machine, so its ChatGPT account can analyze the run instead, sending the evidence to OpenAI under that account. The next command does it once; review.analysis.provider: codex in ${file} makes it this study's analyst.`, analyzeCommand(source, "codex"));
+    return withoutFindings(source, "skipped", reason, `${opening} Codex is signed in on this machine, so its ChatGPT account can analyze the run instead, sending the evidence to OpenAI under that account. The next command does it once; review.analysis.provider: codex in ${file} makes it this study's analyst.`, analyzeCommand(source, { provider: "codex" }));
+}
+/**
+ * The view of a run whose findings are not written yet: participants still running, an analysis
+ * running, or an analysis whose process stopped before it finished. Undefined otherwise.
+ */
+function pendingFindings(source, job) {
+    const again = cli(`review --run ${source.runId}${source.cwdFlag}`);
+    const progress = source.progress;
+    if (progress?.stage === "participants" && job === undefined)
+        return withoutFindings(source, "running", null, source.analysisOffIn === undefined
+            ? "Participants are still running in this run, so no analysis has started. Automatic analysis starts when they finish, and the findings follow it."
+            : "Participants are still running in this run. Analysis is turned off in its study, so none starts when they finish.", again);
+    if (progress?.stage === "cut-off" && job === undefined)
+        return withoutFindings(source, "skipped", "ANALYSIS_RUN_INCOMPLETE", `This run ended while ${progress.running} of ${progress.streams} participant streams were still running, so its recording is incomplete and no analysis ran. Run the study again with the next command.`, cli(`run ${source.study?.id ?? "<study>"}${source.cwdFlag}`));
+    const phase = progress?.stage === "analysis" ? progress.phase : undefined;
+    const jobPending = job?.state === "queued" || job?.state === "running";
+    if (jobPending || (job === undefined && phase?.state === "running")) {
+        const since = phase === undefined
+            ? ""
+            : ` It started at ${phase.startedAt}, ${formatDuration(Math.max(0, (source.nowMs ?? Date.now()) - Date.parse(phase.startedAt)))} ago.`;
+        return withoutFindings(source, "running", null, `The automatic analysis is running.${since} Findings usually take ${ANALYSIS_USUALLY_TAKES}; check again then.`, again);
+    }
+    const stopped = (job?.state === "unknown" && job.reason === "AUTOMATIC_ANALYSIS_STOPPED") ||
+        (job === undefined && phase?.state === "stopped");
+    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.analyst : undefined));
+}
+/**
+ * A run that ended, by a signal, a process that left without publishing, or a heartbeat that
+ * stopped, while some participant stream was still running. Undefined for any other run.
+ */
+function cutOff(bundle, record, nowMs) {
+    if (bundle === undefined || bundle.outcome?.state === "finished")
+        return undefined;
+    if (bundle.outcome === undefined &&
+        (record === null || classifyRunStatus(record, nowMs) !== "interrupted"))
+        return undefined;
+    const running = bundle.streams.filter((stream) => !TERMINAL_SIMULATION_STATUSES.has(stream.status) || stream.liveActor !== undefined).length;
+    return running === 0 ? undefined : { stage: "cut-off", running, streams: bundle.streams.length };
+}
+/** The analyst the run's study gets, when its file still names the same study. */
+async function studyAnalyst(cwd, study) {
+    if (study?.path === undefined)
+        return undefined;
+    const resolved = await resolveStudyManifest(cwd, study.path).catch(() => null);
+    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 !== undefined
+        ? { provider: analysis.config.provider, model: analysis.config.model }
+        : undefined;
 }
 /** The findings view of a run's selected analysis, or why it has none. */
 export function analysisFindings(source) {
@@ -181,7 +254,9 @@ export function analysisFindings(source) {
             message: stale
                 ? `The run's evidence changed after analysis ${analysis.id}, so its findings may not match the run.`
                 : `Analysis ${analysis.id} is ${analysis.status}, with ${plural(result.findings.length, "finding")}.`,
-            next: stale ? analyzeCommand(source, analysis.provider) : null,
+            next: stale
+                ? analyzeCommand(source, { provider: analysis.provider, model: analysis.config.model })
+                : null,
             analysisId: analysis.id,
             status: analysis.status,
             provider: analysis.provider,
@@ -200,19 +275,20 @@ export function analysisFindings(source) {
     if (loaded.warnings.includes("ANALYSIS_SENSITIVE_TEXT_QUARANTINED"))
         return withoutFindings(source, "unavailable", "ANALYSIS_SENSITIVE_TEXT_QUARANTINED", `The analysis text matched a sensitive-text pattern, so it is not printed. ${cli(`analyze show --run ${source.runId}${source.cwdFlag} --json`)} prints the raw record.`, null);
     const job = loaded.automatic;
-    if (job?.state === "queued" || job?.state === "running")
-        return withoutFindings(source, "running", null, "The automatic analysis is still running. Check again when it finishes.", cli(`review --run ${source.runId}${source.cwdFlag}`));
+    const pending = pendingFindings(source, job);
+    if (pending !== undefined)
+        return pending;
     if (analysis && analysis.result === null)
-        return withoutFindings(source, "failed", analysis.error, `Analysis attempt ${analysis.id} ${analysis.status === "cancelled" ? "was cancelled" : "failed"}${analysis.error ? ` (${analysis.error})` : ""} and left no findings.`, analyzeCommand(source, analysis.provider));
+        return withoutFindings(source, "failed", analysis.error, `Analysis attempt ${analysis.id} ${analysis.status === "cancelled" ? "was cancelled" : "failed"}${analysis.error ? ` (${analysis.error})` : ""} and left no findings.`, analyzeCommand(source, { provider: analysis.provider, model: analysis.config.model }));
     if (job?.state === "failed" || job?.state === "cancelled") {
         const outcome = analysisOutcomeText(job);
-        return withoutFindings(source, "failed", job.reason, `The automatic analysis ${outcome.startsWith("failed") ? "" : "was "}${outcome}.`, analyzeCommand(source, job.reason === "AUTOMATIC_ANALYSIS_CODEX_UNAVAILABLE" ? "codex" : undefined));
+        return withoutFindings(source, "failed", job.reason, `The automatic analysis ${outcome.startsWith("failed") ? "" : "was "}${outcome}.`, analyzeCommand(source, job.reason === "AUTOMATIC_ANALYSIS_CODEX_UNAVAILABLE" ? { provider: "codex" } : undefined));
     }
     if (job?.state === "skipped" && job.admission) {
         const refusal = costRefusal(job.admission, `--run ${source.runId}${source.cwdFlag}`, cli);
         return withoutFindings(source, "skipped", job.reason, `The automatic analysis was refused before it started. ${refusal.text}`, refusal.command);
     }
-    if (job?.state === "skipped" && job.reason === "AUTOMATIC_ANALYSIS_KEY_MISSING")
+    if (job?.state === "skipped" && job.reason !== null && KEY_MISSING_REASONS.has(job.reason))
         return missingKeyFindings(source, job.reason);
     if (job?.state === "skipped") {
         const refused = job.reason === "AUTOMATIC_ANALYSIS_ADMISSION_REFUSED";
@@ -278,7 +354,27 @@ export async function readRunAnalysis(cwd, run, analysisId, deps = {}) {
     const analysisOffIn = mode === "live" ? await studyAnalysisOff(physical, study) : undefined;
     const liveStudy = mode !== undefined && mode !== "live" ? await liveStudyAfterDryRun(physical, study) : undefined;
     const loaded = await loadAnalysis(prepared, analysisId);
-    const codexSignedIn = loaded.automatic?.reason === "AUTOMATIC_ANALYSIS_KEY_MISSING"
+    const nowMs = Date.now();
+    const status = runJsonValue(await readRunJsonIfExists(prepared, RUN_STATUS_FILE));
+    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 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,
+            ...(analyst === undefined ? {} : { analyst }),
+        }
+        : bundle?.bundle.outcome === undefined &&
+            record !== null &&
+            classifyRunStatus(record, nowMs) === "running"
+            ? { stage: "participants" }
+            : cutOff(bundle?.bundle, record, nowMs);
+    const codexSignedIn = missingKeyReason === "AUTOMATIC_ANALYSIS_KEY_MISSING"
         ? await (deps.codexSignedIn ?? codexSignedInHere)().catch(() => false)
         : undefined;
     return {
@@ -293,6 +389,9 @@ 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,
     };
 }
 async function codexSignedInHere() {

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",
@@ -315,6 +316,7 @@ const ANALYSIS_REASON_TEXT = {
     AUTOMATIC_ANALYSIS_CANCELLATION_UNAVAILABLE: "outcome unknown: a cancellation could not be recorded",
     AUTOMATIC_ANALYSIS_STORAGE_UNAVAILABLE: "outcome unknown: analysis storage is unavailable",
     AUTOMATIC_ANALYSIS_OUTCOME_UNKNOWN: "outcome unknown",
+    AUTOMATIC_ANALYSIS_STOPPED: "outcome unknown: the process running it stopped before it finished",
 };
 export function analysisOutcomeText(analysis) {
     if (analysis.reason === null)

package/dist/evidence/browser-hygiene.d.ts

@@ -4,4 +4,15 @@
  * place so browser-backed routes can prefer product pixels over browser UI.
  */
 export declare const CHROMIUM_EVIDENCE_HYGIENE_FLAGS: readonly ["--disable-background-networking", "--disable-component-update", "--disable-default-apps", "--disable-domain-reliability", "--disable-extensions", "--disable-sync", "--no-default-browser-check", "--no-first-run", "--password-store=basic", "--use-mock-keychain"];
-export declare function chromiumEvidenceProfilePreferencesJson(): string;
+/**
+ * The profile preference that lets a web `targetUrl`'s origin open the external app schemes
+ * without Chrome's prompt: the "always allow" choice Chrome stores per origin, which needs no root
+ * and no managed policy. Links from other origins still prompt. Undefined for any other target.
+ */
+export declare function externalAppPreferences(targetUrl: string | undefined): {
+    protocol_handler: {
+        allowed_origin_protocol_pairs: Record<string, Record<string, true>>;
+    };
+} | undefined;
+/** The profile's Preferences file, with externalAppPreferences for a web `targetUrl`. */
+export declare function chromiumEvidenceProfilePreferencesJson(targetUrl?: string): string;

package/dist/evidence/browser-hygiene.js

@@ -37,6 +37,49 @@ const CHROMIUM_EVIDENCE_PROFILE_PREFERENCES = {
         password_manager_enabled: false,
     },
 };
-export function chromiumEvidenceProfilePreferencesJson() {
-    return JSON.stringify(CHROMIUM_EVIDENCE_PROFILE_PREFERENCES);
+/**
+ * Schemes whose links Chrome hands to another app after asking "Open xdg-open?". The desktop's
+ * stand-ins answer them (src/substrates/e2b/desktop-handoff.ts), so the prompt is browser chrome
+ * a person on their own computer would not see for that app. Chrome never asks for mailto.
+ */
+const EXTERNAL_APP_SCHEMES = [
+    "callto",
+    "facetime",
+    "facetime-audio",
+    "geo",
+    "maps",
+    "mms",
+    "msteams",
+    "sip",
+    "skype",
+    "slack",
+    "sms",
+    "tel",
+    "webcal",
+    "whatsapp",
+    "zoommtg",
+];
+/**
+ * The profile preference that lets a web `targetUrl`'s origin open the external app schemes
+ * without Chrome's prompt: the "always allow" choice Chrome stores per origin, which needs no root
+ * and no managed policy. Links from other origins still prompt. Undefined for any other target.
+ */
+export function externalAppPreferences(targetUrl) {
+    const target = targetUrl === undefined ? null : URL.parse(targetUrl);
+    if (target === null || !/^https?:$/.test(target.protocol))
+        return undefined;
+    return {
+        protocol_handler: {
+            allowed_origin_protocol_pairs: {
+                [target.origin]: Object.fromEntries(EXTERNAL_APP_SCHEMES.map((scheme) => [scheme, true])),
+            },
+        },
+    };
+}
+/** The profile's Preferences file, with externalAppPreferences for a web `targetUrl`. */
+export function chromiumEvidenceProfilePreferencesJson(targetUrl) {
+    return JSON.stringify({
+        ...CHROMIUM_EVIDENCE_PROFILE_PREFERENCES,
+        ...externalAppPreferences(targetUrl),
+    });
 }

package/dist/feedback/export-bundle.js

@@ -47,7 +47,7 @@ function omittedReason(relative) {
         return "automatic execution intent and liveness do not transfer to a derivative";
     if (isAnalysisRecordPath(relative))
         return "analysis records bind original evidence hashes; reanalyze the derivative";
-    if (relative.startsWith(".analysis-lock/"))
+    if (relative.startsWith(".analysis-lock"))
         return "local analysis execution lock";
     return (OMITTED.get(relative) ??
         (["feedback/draft.json", "feedback/issue.md"].includes(relative)

package/dist/guest/external-links.d.ts

@@ -0,0 +1,14 @@
+import type { CuaExecutor } from "../actors/computer-use/loop.js";
+/** Where the image keeps the stand-ins. */
+export declare const GUEST_EXTERNAL_LINK_BIN = "/opt/humanish/control/bin";
+/**
+ * Write the browser profile's Preferences before the first launch, so the initial app's origin
+ * opens tel:, sms: and the other app schemes without Chromium's prompt. No initial URL, no file.
+ */
+export declare function prepareGuestBrowserProfile(profileDir: string, initialUrl: string | undefined): Promise<void>;
+/**
+ * The executor with each observation carrying the links appended to `log` since the previous
+ * observation, at most EXTERNAL_HANDOFF_LIMITS.perObservation. A line still being written waits
+ * for the next observation. Every other property of the executor is kept.
+ */
+export declare function withExternalHandoffs(executor: CuaExecutor, log: string): CuaExecutor;

package/dist/guest/external-links.js

@@ -0,0 +1,48 @@
+// Links the guest browser hands to another app (mailto:, tel:, sms:). The guest has no email,
+// phone or messaging app. The image's stand-ins for xdg-open and xdg-email, first on the guest's
+// search path, append each such link to a log in the runtime directory, and every observation the
+// executor returns carries the links appended since the previous one.
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { EXTERNAL_HANDOFF_LIMITS, externalHandoffOf, } from "../actors/computer-use/external-handoff.js";
+import { externalAppPreferences } from "../evidence/browser-hygiene.js";
+/** Where the image keeps the stand-ins. */
+export const GUEST_EXTERNAL_LINK_BIN = "/opt/humanish/control/bin";
+/**
+ * Write the browser profile's Preferences before the first launch, so the initial app's origin
+ * opens tel:, sms: and the other app schemes without Chromium's prompt. No initial URL, no file.
+ */
+export async function prepareGuestBrowserProfile(profileDir, initialUrl) {
+    const preferences = externalAppPreferences(initialUrl);
+    if (preferences === undefined)
+        return;
+    await mkdir(`${profileDir}/Default`, { recursive: true, mode: 0o700 });
+    await writeFile(`${profileDir}/Default/Preferences`, JSON.stringify(preferences), {
+        mode: 0o600,
+        flag: "wx",
+    });
+}
+/**
+ * The executor with each observation carrying the links appended to `log` since the previous
+ * observation, at most EXTERNAL_HANDOFF_LIMITS.perObservation. A line still being written waits
+ * for the next observation. Every other property of the executor is kept.
+ */
+export function withExternalHandoffs(executor, log) {
+    let consumed = 0;
+    return {
+        ...executor,
+        observe: async () => {
+            const observation = await executor.observe();
+            const text = await readFile(log, "utf8").catch(() => "");
+            const lines = text
+                .split("\n")
+                .slice(0, -1)
+                .slice(consumed, consumed + EXTERNAL_HANDOFF_LIMITS.perObservation);
+            consumed += lines.length;
+            const externalHandoffs = lines.flatMap((line) => {
+                const handoff = externalHandoffOf(line);
+                return handoff === undefined ? [] : [handoff];
+            });
+            return externalHandoffs.length === 0 ? observation : { ...observation, externalHandoffs };
+        },
+    };
+}

package/dist/guest/runtime-desktop.js

@@ -14,6 +14,7 @@ import { GUEST_BOOTSTRAP_LIMITS, validateGuestInitialUrl } from "./bootstrap.js"
 import { startDesktopMedia, } from "./desktop-media.js";
 import { startDesktopRecorder } from "../evidence/desktop-recorder.js";
 import { createGuestProcesses, setupFailed } from "./runtime-processes.js";
+import { GUEST_EXTERNAL_LINK_BIN, prepareGuestBrowserProfile, withExternalHandoffs, } from "./external-links.js";
 /** The guest image's fixed layout. Tests derive guest paths from it rather than spelling them. */
 export const GUEST_RUNTIME_PATHS = Object.freeze({
     root: "/opt/humanish/control",
@@ -21,7 +22,8 @@ export const GUEST_RUNTIME_PATHS = Object.freeze({
     home: "/home/humanish",
 });
 const GUEST_RUNTIME_ENV = Object.freeze({
-    PATH: "/usr/bin:/bin",
+    // The stand-ins come first, so the browser hands a mailto: or tel: link to them.
+    PATH: `${GUEST_EXTERNAL_LINK_BIN}:/usr/bin:/bin`,
     HOME: "/home/humanish",
     USER: "humanish",
     LOGNAME: "humanish",
@@ -390,6 +392,7 @@ export async function createGuestRuntimeDesktop(options) {
         progress("layout");
         check();
         await verifyGuestLayout(check);
+        await prepareGuestBrowserProfile(`${GUEST_RUNTIME_PATHS.home}/browser`, options.initialUrl);
         progress("xauthority");
         await authorizeDisplay(processes, check);
         progress("display");
@@ -434,7 +437,7 @@ export async function createGuestRuntimeDesktop(options) {
             await openGuestFixture(browser.page, check);
         }
         return {
-            executor: state.media?.wrap(executor) ?? executor,
+            executor: withExternalHandoffs(state.media?.wrap(executor) ?? executor, `${GUEST_RUNTIME_ENV.XDG_RUNTIME_DIR}/humanish-links.log`),
             close,
             ...(options.recording === undefined
                 ? {}

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/data.d.ts

@@ -23,6 +23,10 @@ export interface ObserverData {
         state: "running" | "finished" | "interrupted" | "unknown";
         observedAt: string;
         source: "local-run-status";
+        /** Present while the run's own process analyzes it after the run ended: when it started. */
+        analysis?: {
+            startedAt: string;
+        };
     };
     run: {
         runId: string;

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") {