humanish 0.143.0 → 0.145.0

package/CHANGELOG.md

@@ -8,6 +8,28 @@ The Unreleased section holds the full notes for the next version until it is tag
 
 ## Unreleased
 
+## 0.145.0: A remote runner's keys stay in E2B's proxy (2026-10-22)
+
+humanish 0.145.0 keeps the OpenAI, Gemini and E2B keys out of a remote E2B runner's environment.
+E2B's egress proxy adds each key to the runner's requests on its fixed host, and the runner holds
+placeholders; code in the runner can still read the keys back through the E2B API, and a Modal
+runner still receives them as environment variables. Study analysis with `gpt-6-luna` sends low
+text verbosity, which made it about four times faster on the benchmark recordings, and an
+observation of what a participant said may now also cite the capture they spoke about.
+
+[Release notes](https://github.com/danielgwilson/humanish/releases/tag/v0.145.0)
+
+## 0.144.0: Hosted studies run remotely by default (2026-10-22)
+
+humanish 0.144.0 runs a hosted computer-use study remotely by default. A study on
+`e2b-desktop` or `modal-desktop` with a public `app-url` runs its own process in a sandbox in your
+E2B or Modal account, so it keeps going when this machine sleeps; the command follows it, serves
+the live Observer here and copies the evidence back. Before the runner starts, the command names
+the keys it sends. Pass `--local` for one run, or set `execution.remote: false` in a study, to keep
+it on this machine.
+
+[Release notes](https://github.com/danielgwilson/humanish/releases/tag/v0.144.0)
+
 ## 0.143.0: Analysis costs about one seventh as much: gpt-6.1-sol at medium effort is the default (2026-10-22)
 
 humanish 0.143.0 analyzes studies with `gpt-6.1-sol` at medium reasoning effort by default, in

package/dist/analysis/models.d.ts

@@ -1,6 +1,8 @@
 import type { ReasoningEffort } from "../actors/reasoning-effort.js";
 import type { AnalysisApiVendor } from "./provider.js";
 import type { AnalysisConfig } from "./types.js";
+/** The `text.verbosity` an OpenAI analysis with `model` asks for, or undefined for the default. */
+export declare const openaiTextVerbosity: (model: string) => "low" | undefined;
 export declare const SUPPORTED_ANALYSIS_MODELS: readonly string[];
 export declare const GEMINI_ANALYSIS_MODELS: readonly string[];
 /** Whether the API analyst `provider` (omitted is OpenAI) analyzes with `model`. */

package/dist/analysis/models.js

@@ -14,6 +14,21 @@ const OPENAI_MODELS = {
     "gpt-5.6-terra": ["none", "low", "medium", "high", "xhigh", "max"],
     "gpt-5.6-luna": ["none", "low", "medium", "high", "xhigh", "max"],
 };
+/**
+ * The `text.verbosity` the OpenAI wire sends for a model; a model not listed gets the API default,
+ * `medium`. The Responses API takes `low`, `medium` or `high` beside a json_schema `text.format`
+ * (developers.openai.com/api/reference/resources/responses/methods/create, read 2026-10-22). On
+ * the benchmark recordings, gpt-6-luna at low verbosity decoded about three times faster and its
+ * analyses passed the evidence checks more often, with the same findings: see
+ * docs/evidence/benchmark/2026-10-22-luna-verbosity.md.
+ */
+const OPENAI_TEXT_VERBOSITY = {
+    "gpt-6-luna": "low",
+};
+/** The `text.verbosity` an OpenAI analysis with `model` asks for, or undefined for the default. */
+export const openaiTextVerbosity = (model) => Object.hasOwn(OPENAI_TEXT_VERBOSITY, model)
+    ? OPENAI_TEXT_VERBOSITY[model]
+    : undefined;
 /**
  * Gemini models that completed a live analysis, with the `thinkingLevel` values the thinking guide
  * lists for each (ai.google.dev/gemini-api/docs/generate-content/thinking, read 2026-10-21):

package/dist/analysis/openai-wire.d.ts

@@ -2,5 +2,5 @@ import type { AnalysisProviderResult, AnalysisWire } from "./provider.js";
 /** Text and usage wire shapes reuse the captured closing-report contract; refusal fails closed. */
 export declare function parseAnalysisResponse(raw: unknown): AnalysisProviderResult;
 /** One stateless request: no stored response, no tools, the analysis's reasoning effort, strict
- * schema. */
+ * schema, and the model's text verbosity from models.ts. */
 export declare const openaiWire: AnalysisWire;

package/dist/analysis/openai-wire.js

@@ -2,6 +2,7 @@
 // a response becomes an AnalysisProviderResult. provider.ts owns the transport around it.
 import { OPENAI_RESPONSES_URL } from "../actors/openai-endpoint.js";
 import { isRecord } from "../run/type-guards.js";
+import { openaiTextVerbosity } from "./models.js";
 const record = (value) => (isRecord(value) ? value : {});
 const count = (value) => Number.isSafeInteger(value) && value >= 0 && value <= 1e12;
 function usageOf(raw) {
@@ -68,35 +69,44 @@ export function parseAnalysisResponse(raw) {
     }
 }
 /** One stateless request: no stored response, no tools, the analysis's reasoning effort, strict
- * schema. */
+ * schema, and the model's text verbosity from models.ts. */
 export const openaiWire = {
     url: () => OPENAI_RESPONSES_URL,
     headers: (apiKey) => ({ Authorization: `Bearer ${apiKey}`, "Content-Type": "application/json" }),
-    body: (request) => ({
-        model: request.model,
-        instructions: request.instructions,
-        input: [
-            {
-                role: "user",
-                content: [
-                    { type: "input_text", text: request.evidence },
-                    ...request.images.flatMap((image) => [
-                        { type: "input_text", text: JSON.stringify({ captureEvidenceId: image.evidenceId }) },
-                        { type: "input_image", image_url: image.dataUrl, detail: "high" },
-                    ]),
-                ],
+    body: (request) => {
+        const verbosity = openaiTextVerbosity(request.model);
+        return {
+            model: request.model,
+            instructions: request.instructions,
+            input: [
+                {
+                    role: "user",
+                    content: [
+                        { type: "input_text", text: request.evidence },
+                        ...request.images.flatMap((image) => [
+                            { type: "input_text", text: JSON.stringify({ captureEvidenceId: image.evidenceId }) },
+                            { type: "input_image", image_url: image.dataUrl, detail: "high" },
+                        ]),
+                    ],
+                },
+            ],
+            store: false,
+            tools: [],
+            tool_choice: "none",
+            truncation: "disabled",
+            service_tier: "default",
+            reasoning: { effort: request.reasoningEffort },
+            max_output_tokens: request.maxOutputTokens,
+            text: {
+                format: {
+                    type: "json_schema",
+                    name: "study_analysis",
+                    strict: true,
+                    schema: request.schema,
+                },
+                ...(verbosity === undefined ? {} : { verbosity }),
             },
-        ],
-        store: false,
-        tools: [],
-        tool_choice: "none",
-        truncation: "disabled",
-        service_tier: "default",
-        reasoning: { effort: request.reasoningEffort },
-        max_output_tokens: request.maxOutputTokens,
-        text: {
-            format: { type: "json_schema", name: "study_analysis", strict: true, schema: request.schema },
-        },
-    }),
+        };
+    },
     parse: parseAnalysisResponse,
 };

package/dist/analysis/validation.js

@@ -369,7 +369,7 @@ export function checkAnalysisResult(input, value) {
             !refs.some((ref) => ref &&
                 ["ui_action", "command", "tool_call", "file_change", "approval"].includes(ref.kind)))
             errors.add("ANALYSIS_ACTION_SOURCE_INVALID");
-        if (observation.basis === "participant_statement" && refs.some((ref) => !ref?.quoteEligible))
+        if (observation.basis === "participant_statement" && !refs.some((ref) => ref?.quoteEligible))
             errors.add("ANALYSIS_STATEMENT_SOURCE_INVALID");
         return new Set(refs.flatMap((ref) => (ref ? [ref.streamId] : [])));
     };

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

@@ -20,7 +20,8 @@ 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(new Option("--remote", "Require a remote run: the study's own process runs in a sandbox on its participants' provider, so it keeps going when this machine sleeps. A study that can is run this way by default; this refuses one that cannot, with the reason.").conflicts("local"))
+        .option("--local", "Run the study on this machine even when it could run remotely. It then stops if this machine sleeps.")
         .addOption(ownerKeyOption())
         .option("--json", JSON_OPTION_DESCRIPTION);
 }

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

@@ -1,13 +1,47 @@
 import type { Command } from "commander";
-import { type RemoteOutcome } from "../../remote/launch.js";
+import { type RemoteOutcome, type RunnerKeys } from "../../remote/launch.js";
+import { type RemotePlan } from "../../remote/plan.js";
+import type { RunResult } from "../../run/results.js";
 import type { StudyConfig } from "../../study/types.js";
 import { type CliIo, type StudyCommandOptions } from "../io.js";
+type RemoteErrorCode = "HUMANISH_REMOTE_REFUSED" | "HUMANISH_REMOTE_FAILED";
+/** Where a study's run executes, decided before anything is created. */
+export type RunPlacement = {
+    kind: "local";
+    note?: string;
+} | {
+    kind: "remote";
+    plan: RemotePlan;
+} | {
+    kind: "refused";
+    message: string;
+};
+/**
+ * Whether this run executes here or in a runner sandbox. A hosted study runs remotely by default
+ * when it can; `--local` or `execution.remote: false` keeps it here, and `--remote` or
+ * `execution.remote: true` requires a remote run, refused with the reason when the study cannot
+ * have one. `--local` and `--remote` win over the study's field.
+ */
+export declare function placeRun(args: {
+    options: StudyCommandOptions;
+    config: StudyConfig;
+    studyPath: string;
+    env?: Readonly<Record<string, string | undefined>>;
+    /** Whether this humanish is a built package a runner can install; read from the module when absent. */
+    packaged?: boolean;
+}): RunPlacement;
+/** A refused placement as the command's result. */
+export declare function refuseRemote(command: Command, io: CliIo, cwd: string, message: string, code?: RemoteErrorCode, forwarded?: NonNullable<RunResult["remote"]>): void;
+/** Launch `remote` in a runner sandbox and report how it ended. */
 export declare function runRemoteStudy(args: {
     command: Command;
     io: CliIo;
     options: StudyCommandOptions;
-    config: StudyConfig;
     studyPath: string;
+    remote: RemotePlan;
 }): Promise<void>;
+/** The line that says, before the runner exists, where each of this machine's keys goes. */
+export declare function runnerKeysLine(provider: RemotePlan["provider"], keys: Pick<RunnerKeys, "held" | "sent">): string;
 /** 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;
+export declare function reportRemoteOutcome(command: Command, io: CliIo, cwd: string, outcome: RemoteOutcome, forwarded?: NonNullable<RunResult["remote"]>): void;
+export {};

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

@@ -1,81 +1,140 @@
 // `--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 { launchRemoteRun, runnerKeys, runsFromPackage, } from "../../remote/launch.js";
 import { planRemoteRun } from "../../remote/plan.js";
-import { planStudy } from "../../study/plan.js";
+import { INSIDE_RUNNER_ENV } from "../../remote/runner.js";
+import { planStudy, resolveStudyDryRun } 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;
+/**
+ * Whether this run executes here or in a runner sandbox. A hosted study runs remotely by default
+ * when it can; `--local` or `execution.remote: false` keeps it here, and `--remote` or
+ * `execution.remote: true` requires a remote run, refused with the reason when the study cannot
+ * have one. `--local` and `--remote` win over the study's field.
+ */
+export function placeRun(args) {
+    const { options, config } = args;
+    if ((args.env ?? process.env)[INSIDE_RUNNER_ENV] === "1")
+        return options.remote === true
+            ? {
+                kind: "refused",
+                message: "This run is already inside a runner sandbox, so it runs here.",
+            }
+            : { kind: "local" };
+    const declared = config.execution?.remote;
+    if (options.local === true || (options.remote !== true && declared === false))
+        return { kind: "local" };
+    const required = options.remote === true || declared === true;
+    // A dry run creates no sandbox, so it never needs a runner, whatever asked for one.
+    if (resolveStudyDryRun(config, options.dryRun, true) !== false)
+        return required
+            ? { kind: "local", note: "A dry run creates no sandbox, so it runs here, not remotely." }
+            : { kind: "local" };
+    const local = (reason) => required
+        ? { kind: "refused", message: `This study cannot run remotely: ${reason}` }
+        : movable(config)
+            ? {
+                kind: "local",
+                note: `Not running remotely: ${reason} A run on this machine stops if it sleeps.`,
+            }
+            : { kind: "local" };
+    const flags = localOnlyFlags(options);
+    if (flags.length > 0)
+        return local(`${flags.join(", ")} ${flags.length === 1 ? "does" : "do"} not run remotely yet.`);
     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;
-    }
+    // A study that does not plan is refused by its route with the plan's own message.
+    if (!planned.ok)
+        return required ? { kind: "refused", message: planned.refusal.message } : { kind: "local" };
     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 e2bCeiling = sandboxCeiling(process.env);
     const sandboxes = concurrentSandboxes(process.env);
     const remote = planRemoteRun({
         config,
         plan,
         cwd,
         studyPath: args.studyPath,
-        ceilingMs,
+        ceilingMs: provider === "modal" ? MODAL_MAX_SANDBOX_MS : e2bCeiling.ok ? e2bCeiling.ms : 0,
         concurrentSandboxes: sandboxes.ok ? sandboxes.count : 1,
     });
-    if (!remote.ok) {
-        refuse("HUMANISH_REMOTE_REFUSED", `This study cannot run remotely: ${remote.reason}`);
-        return;
-    }
+    if (!remote.ok)
+        return local(remote.reason);
+    // Checked last, so a study that could not run remotely anyway gives its own reason.
+    if (!(args.packaged ?? runsFromPackage()))
+        return local("this humanish runs from source, which a runner cannot install. Build it with pnpm build and run node dist/cli.js to run remotely.");
+    return { kind: "remote", plan: remote.plan };
+}
+/**
+ * Whether the study is of a kind that runs remotely, so a reason it does not this time is worth
+ * saying: a computer-use study on hosted desktops. Other routes never run remotely yet.
+ */
+function movable(config) {
+    const target = config.execution?.target;
+    return (config.route === "computer-use" && (target === "e2b-desktop" || target === "modal-desktop"));
+}
+/** A refused placement as the command's result. */
+export function refuseRemote(command, io, cwd, message, code = "HUMANISH_REMOTE_REFUSED", forwarded) {
+    const result = {
+        schema: "humanish.run-result.v1",
+        ok: false,
+        cwd: path.resolve(cwd),
+        warnings: [],
+        ...(forwarded === undefined ? {} : { remote: forwarded }),
+        error: { code, message },
+    };
+    writeResult(command, io, result, formatRunHuman);
+    io.setExitCode(2);
+}
+/** Launch `remote` in a runner sandbox and report how it ended. */
+export async function runRemoteStudy(args) {
+    const { io, options } = args;
+    const cwd = path.resolve(options.cwd);
     const port = parseObserverPort(options.port ?? "0");
     if (port === null) {
-        refuse("HUMANISH_REMOTE_REFUSED", "--port must be an integer between 0 and 65535.");
+        refuseRemote(args.command, io, cwd, "--port must be an integer between 0 and 65535.");
         return;
     }
+    const keys = runnerKeys(args.remote, process.env);
+    const forwarded = {
+        provider: args.remote.provider,
+        keys: [...keys.held, ...keys.sent].sort(),
+    };
+    io.writeErr(`${runnerKeysLine(args.remote.provider, keys)}\n`);
     let outcome;
     try {
         outcome = await launchRemoteRun({
             cwd,
             study: path.relative(cwd, path.resolve(cwd, args.studyPath)).split(path.sep).join("/"),
-            remote: remote.plan,
+            remote: args.remote,
             env: process.env,
             port,
             say: (line) => io.writeErr(`${line}\n`),
         });
     }
     catch (error) {
-        refuse("HUMANISH_REMOTE_FAILED", error instanceof Error ? error.message : String(error));
+        refuseRemote(args.command, io, cwd, error instanceof Error ? error.message : String(error), "HUMANISH_REMOTE_FAILED", forwarded);
         return;
     }
-    reportRemoteOutcome(args.command, io, cwd, outcome);
+    reportRemoteOutcome(args.command, io, cwd, outcome, forwarded);
+}
+/** The line that says, before the runner exists, where each of this machine's keys goes. */
+export function runnerKeysLine(provider, keys) {
+    const list = (names) => names.join(", ");
+    const local = "Run with --local to keep the study on this machine.";
+    if (provider === "modal")
+        return `The runner runs in your own Modal account and receives ${list(keys.sent) || "no keys"} as environment variables, since Modal has no egress proxy that could hold them. ${local}`;
+    const held = keys.held.length === 0
+        ? ""
+        : ` E2B's egress proxy holds ${list(keys.held)} and adds them to the runner's requests, so the runner's environment holds placeholders.`;
+    const sent = keys.sent.length === 0
+        ? ""
+        : ` The runner receives ${list(keys.sent)} as environment variables.`;
+    return `The runner runs in your own E2B account.${held}${sent} ${local}`;
 }
 /** The run options a remote run does not carry to the runner yet. */
 function localOnlyFlags(options) {
@@ -90,28 +149,35 @@ function localOnlyFlags(options) {
     ].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") {
+export function reportRemoteOutcome(command, io, cwd, outcome, forwarded) {
+    const remote = forwarded === undefined ? {} : { remote: forwarded };
+    if (outcome.detached === true ||
+        outcome.result === undefined ||
+        typeof outcome.result !== "object") {
+        const detached = outcome.detached === true;
         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"}.`,
-            },
+            ...remote,
+            error: detached
+                ? {
+                    code: "HUMANISH_REMOTE_DETACHED",
+                    message: `The terminal closed, so run ${outcome.runId} goes on in its runner without this machine. Follow it and copy it back with humanish observe --run ${outcome.runId}, or stop it and its sandboxes with humanish reclaim --run ${outcome.runId}.`,
+                }
+                : {
+                    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);
+        // A detached run exits as a hung-up local command does; it is not finished, so not 0.
+        io.setExitCode(detached ? 129 : outcome.exitCode === 0 ? 2 : outcome.exitCode);
         return;
     }
-    const result = { ...outcome.result, cwd };
+    const result = { ...outcome.result, cwd, ...remote };
     if (outcome.error !== undefined)
         result.warnings = [...(result.warnings ?? []), outcome.error];
     if (wantsJson(command))

package/dist/cli/commands/study-route-run.d.ts

@@ -12,8 +12,9 @@ export interface RouteRun {
  * only for a plan that will run: it loads the scorer, or writes its own refusal and returns
  * undefined, so a refused study never imports the scorer's host code. `afterRun` runs once runStudyWith
  * has returned or thrown, before presentation, which may hold its own signal handlers (watch's
- * Observer and tunnel).
+ * Observer and tunnel). `elsewhere`, when given, runs an admitted study somewhere else instead of
+ * here: the route's own checks have refused anything this machine would refuse first.
  */
 export declare function runRoute(config: StudyConfig, run: RouteRun, beforeRun?: () => Promise<{
     scorer?: LoadedAdapterScorer;
-} | undefined>, afterRun?: () => void): Promise<void>;
+} | undefined>, afterRun?: () => void, elsewhere?: () => Promise<void>): Promise<void>;

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

@@ -6,12 +6,17 @@ import { prepareStudy } from "../../run-study.js";
  * only for a plan that will run: it loads the scorer, or writes its own refusal and returns
  * undefined, so a refused study never imports the scorer's host code. `afterRun` runs once runStudyWith
  * has returned or thrown, before presentation, which may hold its own signal handlers (watch's
- * Observer and tunnel).
+ * Observer and tunnel). `elsewhere`, when given, runs an admitted study somewhere else instead of
+ * here: the route's own checks have refused anything this machine would refuse first.
  */
-export async function runRoute(config, run, beforeRun = () => Promise.resolve({}), afterRun = () => undefined) {
+export async function runRoute(config, run, beforeRun = () => Promise.resolve({}), afterRun = () => undefined, elsewhere) {
     let outcome;
     try {
         const prepared = await prepareStudy(config, run.options);
+        if (prepared.ok && elsewhere !== undefined) {
+            await elsewhere();
+            return;
+        }
         if (prepared.ok) {
             const ready = await beforeRun();
             if (ready === undefined)

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

@@ -15,7 +15,7 @@ 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 { placeRun, refuseRemote, 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";
@@ -112,16 +112,13 @@ 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,
-        });
+    const placement = placeRun({ options: args.options, config, studyPath: resolved.path });
+    if (placement.kind === "refused") {
+        refuseRemote(args.command, args.io, args.options.cwd, placement.message);
         return;
     }
+    if (placement.kind === "local" && placement.note !== undefined)
+        args.io.writeErr(`${placement.note}\n`);
     // 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
@@ -131,6 +128,19 @@ export async function runStudyCommand(args) {
         return;
     // Every route's runStudyWith options carry the study's provenance, from here only.
     const run = { ...routeRun, options: { ...routeRun.options, study } };
+    // A remote run passes the same checks here first, so a study this machine would refuse is refused
+    // before any runner exists. The launcher holds its own signal handlers.
+    if (placement.kind === "remote") {
+        const remote = placement.plan;
+        await runRoute(config, run, undefined, undefined, () => runRemoteStudy({
+            command: args.command,
+            io: args.io,
+            options: args.options,
+            studyPath: resolved.path,
+            remote,
+        }));
+        return;
+    }
     // From here a signal marks the run interrupted and reclaims its sandboxes (run-signals.ts).
     const signals = beginRunSignalPhase(args.io);
     try {

package/dist/cli/io.d.ts

@@ -47,6 +47,8 @@ export interface StudyCommandOptions {
     runId?: string | undefined;
     /** Run the study in a runner sandbox on its participants' provider. */
     remote?: boolean | undefined;
+    /** Run the study on this machine even when it could run remotely. */
+    local?: 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). */

package/dist/keys/key-resolution.js

@@ -25,7 +25,7 @@ import { parse as parseToml } from "smol-toml";
 import { loadEnvFile } from "./env-file.js";
 import { cli } from "../cli/invocation.js";
 import { humanishConfigFile } from "../cli/user-config.js";
-import { OPENAI_EGRESS_PLACEHOLDER } from "../routes/terminal/runtime-auth.js";
+import { EGRESS_PLACEHOLDER } from "../substrates/e2b/egress-keys.js";
 /**
  * The provider keys, in the order `humanish keys set` names their vendors. Implicit discovery fills
  * only these names and the user store holds only these. Everything else in an overlay or store file
@@ -355,7 +355,7 @@ export async function probeKeySources(names, args) {
     // A terminal study's sandbox sets CODEX_API_KEY to an inert placeholder so Codex starts; the key
     // itself stays in the host-side egress proxy. The placeholder is no key, so it counts as unset and
     // discovery may still find a real one.
-    const placeholder = (name) => args.env[name]?.trim() === OPENAI_EGRESS_PLACEHOLDER;
+    const placeholder = (name) => args.env[name]?.trim() === EGRESS_PLACEHOLDER;
     const scratch = { ...args.env };
     for (const name of names)
         if (placeholder(name))

package/dist/remote/launch.d.ts

@@ -1,4 +1,5 @@
 import { type PreparedRunArtifactPaths } from "../run/paths.js";
+import type { E2BNetworkOptions } from "../substrates/e2b/sdk.js";
 import type { RemotePlan } from "./plan.js";
 import { type Runner } from "./runner.js";
 /** What following a remote run needs from its caller: the project, its env and a progress line. */
@@ -45,8 +46,13 @@ export declare function followRemoteRun(args: {
 export declare function joinJournals(...journals: string[]): string;
 export interface Signals {
     readonly requested: "stop" | "detach" | undefined;
-    /** The exit code a local run gives for the stop signal received: 130 for SIGINT, 143 for SIGTERM. */
+    /**
+     * The exit code for the first signal received: 130 for SIGINT and 143 for SIGTERM, as a local
+     * run gives, and 129 for a closed terminal.
+     */
     readonly exitCode: number;
+    /** Settles when the first signal arrives, so a long step can stop waiting for itself. */
+    readonly received: Promise<void>;
     dispose(): void;
 }
 /**
@@ -54,3 +60,27 @@ export interface Signals {
  * running; the runner ends it at its deadline.
  */
 export declare function watchSignals(): Signals;
+/** What the runner gets from this machine's env, and how each key reaches it. */
+export interface RunnerKeys {
+    /** The run command's env: each forwarded name, with a placeholder for each key E2B holds. */
+    env: Record<string, string>;
+    /**
+     * The runner's network: its URLs answer only with its traffic token, and on E2B its header
+     * transforms carry the held keys. It holds key values: never log or persist it.
+     */
+    network: E2BNetworkOptions;
+    /** Names whose values stay in E2B's egress proxy; the runner sees a placeholder. */
+    held: string[];
+    /** Names whose values enter the runner as environment variables. */
+    sent: string[];
+}
+/**
+ * The keys the runner's run receives: each of the plan's names that is set here, and of names the
+ * run reads only the first of, only the first one set. On E2B, each key that travels as a header
+ * to a fixed host stays in an E2B header transform, and the run gets a placeholder and the system
+ * CA bundle that holds E2B's proxy CA, which Node does not read by default. Modal has no such
+ * transform, so a Modal runner receives every key as an environment variable.
+ */
+export declare function runnerKeys(remote: Pick<RemotePlan, "provider" | "envNames" | "alternatives">, env: Readonly<Record<string, string | undefined>>): RunnerKeys;
+/** Whether this humanish runs from a built package, which a runner can install. */
+export declare function runsFromPackage(): boolean;

package/dist/remote/launch.js

@@ -15,6 +15,7 @@ import { pointLatestRunAt } from "../run/run.js";
 import { appendSandboxOwner, SANDBOX_RECEIPTS_ARTIFACT } from "../run/sandbox-receipts.js";
 import { loadE2BBaseModule } from "../substrates/e2b/base-module.js";
 import { e2bConnection } from "../substrates/e2b/connection.js";
+import { E2B_SYSTEM_CA_BUNDLE, holdKeysInEgress } from "../substrates/e2b/egress-keys.js";
 import { acquireE2BShellSandbox } from "../substrates/e2b/sandbox.js";
 import { loadModalShellModule } from "../substrates/modal/sandbox.js";
 import { serveObserverProxy } from "./observer-proxy.js";
@@ -56,9 +57,12 @@ export async function launchRemoteRun(launch) {
     try {
         const tarball = await packThisHumanish();
         tarballDir = tarball.dir;
+        if (signals.requested !== undefined)
+            return { runId, exitCode: signals.exitCode, error: "stopped before the runner was created" };
         const where = remote.provider === "modal" ? "a Modal sandbox" : "an E2B sandbox";
         say(`Running this study on ${where} as run ${runId}; creating the runner.`);
-        const runner = runnerOf((await acquireRunner(launch, paths)).sandbox);
+        const keys = runnerKeys(remote, launch.env);
+        const runner = runnerOf((await acquireRunner(launch, paths, keys.network)).sandbox);
         if (signals.requested !== undefined)
             return await endRun(launch, runId, {
                 exitCode: signals.exitCode,
@@ -71,7 +75,17 @@ export async function launchRemoteRun(launch) {
         });
         // Bound before the run starts, so a taken --port fails before any participant exists.
         proxy = await serveObserverProxy(await runner.sandbox.portAccess(RUNNER_OBSERVER_PORT), launch.port);
-        const version = await installHumanish(runner, tarball.bytes, [await peerSpec(remote.provider)]);
+        // Installing can take minutes; a signal stops waiting for it, and the reclaim below stops the
+        // runner, and the install with it.
+        const installing = installHumanish(runner, tarball.bytes, [await peerSpec(remote.provider)]);
+        // An install left behind by a signal fails once its runner is gone; that is expected.
+        installing.catch(() => undefined);
+        const version = await Promise.race([installing, signals.received.then(() => "")]);
+        if (signals.requested !== undefined)
+            return await endRun(launch, runId, {
+                exitCode: signals.exitCode,
+                error: "stopped before the run started",
+            });
         say(`Installed humanish ${version} in the runner; uploading the study.`);
         await uploadProject(runner, cwd, remote.uploads, remote.uploadDirectories);
         if (signals.requested !== undefined)
@@ -83,16 +97,15 @@ export async function launchRemoteRun(launch) {
             study: launch.study,
             runId,
             ownerKey,
-            env: Object.fromEntries(remote.envNames.flatMap((name) => {
-                const value = launch.env[name];
-                return value === undefined || value === "" ? [] : [[name, value]];
-            })),
+            env: keys.env,
         });
         return await followRemoteRun({ launch, runner, paths, runId, signals, proxyUrl: proxy.url });
     }
     catch (error) {
-        await reclaimRunSandboxes(cwd, runId, { env: launch.env }).catch(() => undefined);
-        throw error;
+        const reclaimed = await reclaimRunSandboxes(cwd, runId, { env: launch.env }).then((result) => result.ok, () => false);
+        if (reclaimed)
+            throw error;
+        throw new Error(`${message(error)}; its sandboxes were not confirmed stopped, so run humanish reclaim --run ${runId}`, { cause: error });
     }
     finally {
         signals.dispose();
@@ -101,7 +114,7 @@ export async function launchRemoteRun(launch) {
             await rm(tarballDir, { recursive: true, force: true });
     }
 }
-async function acquireRunner(launch, paths) {
+async function acquireRunner(launch, paths, network) {
     const { provider, runnerMs } = launch.remote;
     const module = provider === "modal" ? await loadModalShellModule(launch.env) : await loadE2BBaseModule();
     // A Modal module takes its connection from launch.env and ignores these two.
@@ -114,7 +127,7 @@ async function acquireRunner(launch, paths) {
             ...account,
             timeoutMs: runnerMs,
             metadata: { participantId: "runner" },
-            network: { allowPublicTraffic: false },
+            network,
         },
         receipt: { root: paths, participantId: "runner" },
     });
@@ -152,8 +165,10 @@ export async function followRemoteRun(args) {
             say("The run ended; copying its evidence back.");
             const copied = await copy().then((files) => ({ files }), (error) => ({ error }));
             // The run reclaimed its participants as it ended; only the runner is left, and it holds the
-            // only whole copy of the evidence until a copy succeeds.
-            if ("error" in copied && stopAt === undefined)
+            // only whole copy of the evidence until a copy succeeds. It is kept only then: a run that
+            // refused before its run directory existed has nothing to keep, and its own result says why.
+            // Its result is not reported as the run's own, since the evidence is not here.
+            if ("error" in copied && stopAt === undefined && run.state !== undefined)
                 return {
                     runId,
                     exitCode: 2,
@@ -165,7 +180,9 @@ export async function followRemoteRun(args) {
                 result: run.result.result,
                 ...("files" in copied
                     ? { files: copied.files }
-                    : { error: `copying the evidence back failed: ${message(copied.error)}` }),
+                    : run.state === undefined
+                        ? {}
+                        : { error: `copying the evidence back failed: ${message(copied.error)}` }),
             });
         }
         if (signals.requested === "detach")
@@ -302,17 +319,20 @@ async function writeRemoteRecord(paths, record) {
 export function watchSignals() {
     let requested;
     let exitCode = 130;
-    const interrupt = () => {
-        requested ??= "stop";
-    };
-    const terminate = () => {
-        if (requested === undefined)
-            exitCode = 143;
-        requested ??= "stop";
-    };
-    const detach = () => {
-        requested ??= "detach";
+    let signalled;
+    const received = new Promise((resolve) => {
+        signalled = resolve;
+    });
+    const first = (kind, code) => {
+        if (requested !== undefined)
+            return;
+        requested = kind;
+        exitCode = code;
+        signalled();
     };
+    const interrupt = () => first("stop", 130);
+    const terminate = () => first("stop", 143);
+    const detach = () => first("detach", 129);
     process.on("SIGINT", interrupt);
     process.on("SIGTERM", terminate);
     process.on("SIGHUP", detach);
@@ -323,6 +343,7 @@ export function watchSignals() {
         get exitCode() {
             return exitCode;
         },
+        received,
         dispose() {
             process.off("SIGINT", interrupt);
             process.off("SIGTERM", terminate);
@@ -330,6 +351,38 @@ export function watchSignals() {
         },
     };
 }
+/**
+ * The keys the runner's run receives: each of the plan's names that is set here, and of names the
+ * run reads only the first of, only the first one set. On E2B, each key that travels as a header
+ * to a fixed host stays in an E2B header transform, and the run gets a placeholder and the system
+ * CA bundle that holds E2B's proxy CA, which Node does not read by default. Modal has no such
+ * transform, so a Modal runner receives every key as an environment variable.
+ */
+export function runnerKeys(remote, env) {
+    const set = (name) => (env[name]?.trim() ?? "") !== "";
+    const unread = new Set(remote.alternatives.flatMap((names) => names.filter(set).slice(1)));
+    const forwarded = Object.fromEntries(remote.envNames.flatMap((name) => (set(name) && !unread.has(name) ? [[name, env[name]]] : [])));
+    const routing = { allowPublicTraffic: false };
+    if (remote.provider === "modal")
+        return { env: forwarded, network: routing, held: [], sent: Object.keys(forwarded).sort() };
+    const held = holdKeysInEgress(forwarded, { domain: forwarded.E2B_DOMAIN, existing: routing });
+    return {
+        env: held.held.length === 0
+            ? held.env
+            : { ...held.env, NODE_EXTRA_CA_CERTS: E2B_SYSTEM_CA_BUNDLE },
+        network: held.network,
+        held: held.held,
+        sent: Object.keys(forwarded)
+            .filter((name) => !held.held.includes(name))
+            .sort(),
+    };
+}
+/** Whether this humanish runs from a built package, which a runner can install. */
+export function runsFromPackage() {
+    const here = fileURLToPath(import.meta.url);
+    const root = path.resolve(path.dirname(here), "..", "..");
+    return path.relative(root, here).split(path.sep)[0] === "dist";
+}
 /**
  * This machine's humanish as an npm tarball, so the runner runs exactly the same code. A run from
  * source has no built package to pack.
@@ -337,7 +390,7 @@ export function watchSignals() {
 async function packThisHumanish() {
     const here = fileURLToPath(import.meta.url);
     const root = path.resolve(path.dirname(here), "..", "..");
-    if (path.relative(root, here).split(path.sep)[0] !== "dist")
+    if (!runsFromPackage())
         throw new Error("A remote run installs this humanish in the runner, and a run from source has no built package. Run `pnpm build`, then `node dist/cli.js`, or use an installed humanish.");
     const dir = await mkdtemp(path.join(tmpdir(), "humanish-pack-"));
     const { stdout } = await promisify(execFile)("npm", ["pack", "--ignore-scripts", "--json", "--pack-destination", dir, root], { maxBuffer: 16 * 1024 * 1024 });

package/dist/remote/plan.d.ts

@@ -11,6 +11,8 @@ export interface RemotePlan {
     readonly uploadDirectories: readonly string[];
     /** The environment names the runner's run may receive, and nothing else. */
     readonly envNames: readonly string[];
+    /** Names of which only the first one set is sent, as the run reads only that one. */
+    readonly alternatives: readonly (readonly string[])[];
 }
 export type RemotePlanResult = {
     ok: true;

package/dist/remote/plan.js

@@ -2,6 +2,7 @@
 // long it must live, which files it must receive and which keys it may hold. A pure function of the
 // study and its plan, so a refusal happens before anything is created.
 import path from "node:path";
+import { analysisKeyNames } from "../keys/key-resolution.js";
 import { keyNamesOf } from "../study/requirements.js";
 import { participantList } from "../study/study-fields.js";
 /** Time the runner needs before the study starts: create, Node and humanish install, uploads. */
@@ -46,6 +47,8 @@ export function planRemoteRun(args) {
         return refuse("it loads a scorer module, which does not run remotely yet.");
     if (plan.rerun !== undefined)
         return refuse("a rerun reads a run on this machine.");
+    if (config.comms !== undefined)
+        return refuse("its email setup reads files and connections on this machine.");
     const study = inside(cwd, args.studyPath);
     if (study === undefined)
         return refuse("the study file is outside the project directory.");
@@ -72,6 +75,7 @@ export function planRemoteRun(args) {
             envNames: [
                 ...new Set([...keyNamesOf(plan), ...PROVIDER_KEYS[runner.provider], ...PLAN_SETTINGS]),
             ].sort(),
+            alternatives: analystKeyNames(plan),
         },
     };
 }
@@ -112,3 +116,11 @@ function servedHere(appUrl) {
         (a === 192 && b === 168) ||
         (a === 169 && b === 254));
 }
+/** The analyst's key names, when it reads the first one set of several. */
+function analystKeyNames(plan) {
+    const analyst = plan.analysis?.config.provider;
+    if (analyst === undefined || analyst === "codex")
+        return [];
+    const names = analysisKeyNames(analyst);
+    return names.length > 1 ? [names] : [];
+}

package/dist/remote/runner.d.ts

@@ -1,5 +1,10 @@
 import type { E2BDesktopSandbox } from "../substrates/e2b/sdk.js";
 import { type Shell } from "../substrates/shell.js";
+/**
+ * Set in the runner's run, so any humanish there runs locally even when its study could run
+ * remotely: a runner that launched a runner would repeat without end.
+ */
+export declare const INSIDE_RUNNER_ENV = "HUMANISH_INSIDE_RUNNER";
 /** The port the runner's Observer listens on. */
 export declare const RUNNER_OBSERVER_PORT = 7000;
 /** A runner sandbox and the shell into it. */

package/dist/remote/runner.js

@@ -11,6 +11,11 @@ import { tailOf } from "../substrates/shell.js";
 const RUNNER_PROJECT = "project";
 /** Where the runner keeps the launcher's own files: the result file and the run's output. */
 const RUNNER_STATE = ".humanish-remote";
+/**
+ * Set in the runner's run, so any humanish there runs locally even when its study could run
+ * remotely: a runner that launched a runner would repeat without end.
+ */
+export const INSIDE_RUNNER_ENV = "HUMANISH_INSIDE_RUNNER";
 /** The port the runner's Observer listens on. */
 export const RUNNER_OBSERVER_PORT = 7000;
 /**
@@ -115,13 +120,20 @@ export async function startRemoteRun(runner, start) {
         start.runId,
         "--owner-key",
         start.ownerKey,
+        // The runner's run is the remote run: it must not launch a runner of its own.
+        "--local",
     ];
     const line = [
         `cd "$HOME/${RUNNER_PROJECT}"`,
         `export PATH="$HOME/${RUNNER_STATE}/node/bin:$PATH"`,
         `exec ${args.map((arg) => (arg.startsWith("$HOME") ? `"${arg}"` : shellQuote(arg))).join(" ")} > "$HOME/${RUNNER_STATE}/watch.out" 2> "$HOME/${RUNNER_STATE}/watch.err"`,
     ].join("; ");
-    const env = { ...start.env, DO_NOT_TRACK: "1", HUMANISH_TELEMETRY_DISABLED: "1" };
+    const env = {
+        ...start.env,
+        DO_NOT_TRACK: "1",
+        HUMANISH_TELEMETRY_DISABLED: "1",
+        [INSIDE_RUNNER_ENV]: "1",
+    };
     const result = await runner.shell.start(`bash -c ${shellQuote(line)}`, {
         env,
         timeoutMs: 60_000,

package/dist/routes/terminal/credentials.js

@@ -1,4 +1,5 @@
-import { DEFAULT_RUNTIME_AUTH, E2B_SYSTEM_CA_BUNDLE, OPENAI_EGRESS_PLACEHOLDER, } from "./runtime-auth.js";
+import { DEFAULT_RUNTIME_AUTH } from "./runtime-auth.js";
+import { E2B_SYSTEM_CA_BUNDLE, EGRESS_PLACEHOLDER } from "../../substrates/e2b/egress-keys.js";
 import { TERMINAL_PRODUCT_STUDY_PROVIDER_METADATA } from "./types.js";
 /**
  * Where the study's runtime auth puts the key, as a sentence for the missing-key refusal. Typed
@@ -71,7 +72,7 @@ export function buildRuntimeAuth(args) {
     const envs = mode === "openai-egress"
         ? // Codex documents this verified-TLS trust channel. The stock image's default OpenSSL CA
             // file can be absent even though E2B has installed its proxy CA in the system bundle.
-            { CODEX_API_KEY: OPENAI_EGRESS_PLACEHOLDER, CODEX_CA_CERTIFICATE: E2B_SYSTEM_CA_BUNDLE }
+            { CODEX_API_KEY: EGRESS_PLACEHOLDER, CODEX_CA_CERTIFICATE: E2B_SYSTEM_CA_BUNDLE }
         : keyName === "OPENAI_API_KEY"
             ? { CODEX_API_KEY: keyValue, OPENAI_API_KEY: keyValue }
             : { [keyName]: keyValue };

package/dist/routes/terminal/live-sandbox.js

@@ -15,7 +15,7 @@ import { loadModalShellModule } from "../../substrates/modal/sandbox.js";
 import { e2bAccount } from "../../substrates/e2b/connection.js";
 import { E2BDesktopStartupError, loadE2BDesktopModule, } from "../../substrates/e2b/sdk.js";
 import { shellQuote } from "../../substrates/shell.js";
-import { buildOpenAiEgressNetwork } from "./runtime-auth.js";
+import { holdKeysInEgress } from "../../substrates/e2b/egress-keys.js";
 import { TERMINAL_RUNTIME_VERSION_TIMEOUT_MS, buildRuntimeExecPrefix, buildRuntimeVersionCommand, parseTerminalRuntimeVersion, } from "./runtime.js";
 import { runWithWallClock, teardownSandbox } from "./sandbox.js";
 import { DEFAULT_REQUEST_TIMEOUT_MS, PRODUCT_SETUP_TIMEOUT_MS, SANDBOX_WORKDIR, UPLOAD_MAX_BYTES, } from "./types.js";
@@ -73,7 +73,7 @@ export class LiveTerminalSandbox {
             ? undefined
             : { allowOut: [...egressAllow], denyOut: ["0.0.0.0/0"] };
         const network = runtimeEnv.mode === "openai-egress"
-            ? buildOpenAiEgressNetwork(runtimeEnv.keyValue, routing)
+            ? holdKeysInEgress({ OPENAI_API_KEY: runtimeEnv.keyValue }, { existing: routing }).network
             : routing;
         const options = {
             apiKey: e2bApiKey,

package/dist/routes/terminal/runtime-auth.d.ts

@@ -1,18 +1,6 @@
 import type { StudyRuntimeAuth } from "../../study/types.js";
-import type { E2BNetworkOptions } from "../../substrates/e2b/sdk.js";
 /**
  * The runtime auth a study gets when it declares none. A shell agent can read its own command env,
  * so the raw key stays in the host-side E2B request unless a study declares openai-env.
  */
 export declare const DEFAULT_RUNTIME_AUTH: StudyRuntimeAuth;
-/** E2B envd installs the sandbox-specific proxy CA into this system bundle before routing. */
-export declare const E2B_SYSTEM_CA_BUNDLE = "/etc/ssl/certs/ca-certificates.crt";
-/** An inert nonsecret value satisfies Codex exec's auth prerequisite. E2B replaces the header. */
-export declare const OPENAI_EGRESS_PLACEHOLDER = "humanish-egress-auth-placeholder";
-/**
- * Keep the runtime key in the host-side E2B request, outside sandbox env/files. The installed
- * E2B SDK declares that transform headers override existing request headers. This adds no routing
- * restrictions: every sandbox process can still spend via the provider proxy. Never log the
- * returned options. An adopter's existing exact-host rule must not be silently overwritten.
- */
-export declare function buildOpenAiEgressNetwork(keyValue: string, existing?: E2BNetworkOptions): E2BNetworkOptions;

package/dist/routes/terminal/runtime-auth.js

@@ -3,26 +3,3 @@
  * so the raw key stays in the host-side E2B request unless a study declares openai-env.
  */
 export const DEFAULT_RUNTIME_AUTH = "openai-egress";
-const OPENAI_EGRESS_HOST = "api.openai.com";
-/** E2B envd installs the sandbox-specific proxy CA into this system bundle before routing. */
-export const E2B_SYSTEM_CA_BUNDLE = "/etc/ssl/certs/ca-certificates.crt";
-/** An inert nonsecret value satisfies Codex exec's auth prerequisite. E2B replaces the header. */
-export const OPENAI_EGRESS_PLACEHOLDER = "humanish-egress-auth-placeholder";
-/**
- * Keep the runtime key in the host-side E2B request, outside sandbox env/files. The installed
- * E2B SDK declares that transform headers override existing request headers. This adds no routing
- * restrictions: every sandbox process can still spend via the provider proxy. Never log the
- * returned options. An adopter's existing exact-host rule must not be silently overwritten.
- */
-export function buildOpenAiEgressNetwork(keyValue, existing) {
-    if (Object.keys(existing?.rules ?? {}).some((host) => host.toLowerCase().replace(/\.$/, "") === OPENAI_EGRESS_HOST)) {
-        throw new Error("openai-egress conflicts with an existing api.openai.com network rule; refusing to overwrite it.");
-    }
-    return {
-        ...existing,
-        rules: {
-            ...existing?.rules,
-            [OPENAI_EGRESS_HOST]: [{ transform: { headers: { Authorization: `Bearer ${keyValue}` } } }],
-        },
-    };
-}

package/dist/run/results.d.ts

@@ -31,8 +31,16 @@ export interface RunResult {
     /** The Observer rendered for this run, when `RunOptions.observer` asked for one. */
     observer?: ObserverResult;
     warnings: string[];
+    /**
+     * Set when the run executed in a runner sandbox: the provider, and the names of the keys this
+     * machine sent to the runner, in the operator's own account.
+     */
+    remote?: {
+        provider: string;
+        keys: string[];
+    };
     error?: {
-        code: "HUMANISH_STUDY_ANALYSIS_INVALID" | "HUMANISH_STUDY_ANALYSIS_UNSUPPORTED" | "HUMANISH_STUDY_TASKS_UNSUPPORTED" | "HUMANISH_STUDY_OPTION_UNSUPPORTED" | "HUMANISH_STUDY_V2_UNSUPPORTED" | "HUMANISH_STUDY_INVALID" | "HUMANISH_STUDY_COMMS_UNSUPPORTED" | "HUMANISH_LIVE_RUN_UNIMPLEMENTED" | "HUMANISH_INVALID_CWD" | "HUMANISH_RUN_ID_IN_USE" | "HUMANISH_INVALID_PARTICIPANT_COUNT" | "HUMANISH_INVALID_PORT" | "HUMANISH_UNSUPPORTED_RERUN_FLAGS" | "HUMANISH_WATCH_OPTION_CONFLICT" | "HUMANISH_WATCH_SAFE_NOT_APPLICABLE" | "HUMANISH_RUN_OPTION_CONFLICT" | "HUMANISH_OBSERVE_OPTION_CONFLICT" | "HUMANISH_REMOTE_REFUSED" | "HUMANISH_REMOTE_FAILED" | "HUMANISH_STUDY_SCORER_BAD_REF" | "HUMANISH_STUDY_SCORER_NOT_FOUND" | "HUMANISH_STUDY_SCORER_LOAD_FAILED" | "HUMANISH_STUDY_SCORER_NO_HOOKS" | "HUMANISH_STUDY_SCORER_UNSUPPORTED_BACKEND";
+        code: "HUMANISH_STUDY_ANALYSIS_INVALID" | "HUMANISH_STUDY_ANALYSIS_UNSUPPORTED" | "HUMANISH_STUDY_TASKS_UNSUPPORTED" | "HUMANISH_STUDY_OPTION_UNSUPPORTED" | "HUMANISH_STUDY_V2_UNSUPPORTED" | "HUMANISH_STUDY_INVALID" | "HUMANISH_STUDY_COMMS_UNSUPPORTED" | "HUMANISH_LIVE_RUN_UNIMPLEMENTED" | "HUMANISH_INVALID_CWD" | "HUMANISH_RUN_ID_IN_USE" | "HUMANISH_INVALID_PARTICIPANT_COUNT" | "HUMANISH_INVALID_PORT" | "HUMANISH_UNSUPPORTED_RERUN_FLAGS" | "HUMANISH_WATCH_OPTION_CONFLICT" | "HUMANISH_WATCH_SAFE_NOT_APPLICABLE" | "HUMANISH_RUN_OPTION_CONFLICT" | "HUMANISH_OBSERVE_OPTION_CONFLICT" | "HUMANISH_REMOTE_REFUSED" | "HUMANISH_REMOTE_FAILED" | "HUMANISH_REMOTE_DETACHED" | "HUMANISH_STUDY_SCORER_BAD_REF" | "HUMANISH_STUDY_SCORER_NOT_FOUND" | "HUMANISH_STUDY_SCORER_LOAD_FAILED" | "HUMANISH_STUDY_SCORER_NO_HOOKS" | "HUMANISH_STUDY_SCORER_UNSUPPORTED_BACKEND";
         message: string;
     };
 }

package/dist/study/keys.d.ts

@@ -174,6 +174,7 @@ export declare const ACTOR: {
 };
 export declare const EXECUTION: {
     target: true;
+    remote: true;
     runtime: {
         version: true;
     };

package/dist/study/keys.js

@@ -112,6 +112,7 @@ export const ACTOR = {
 };
 export const EXECUTION = {
     target: true,
+    remote: true,
     runtime: { version: true },
     runtimeAuth: true,
     concurrency: true,

package/dist/study/parse/execution.js

@@ -23,6 +23,11 @@ export function parseExecution(raw) {
         }
         execution.target = target;
     }
+    if (raw.remote !== undefined) {
+        if (typeof raw.remote !== "boolean")
+            return invalid("`execution.remote` must be true or false.");
+        execution.remote = raw.remote;
+    }
     const timeoutMs = posInt(raw.timeoutMs);
     if (timeoutMs !== undefined)
         execution.timeoutMs = timeoutMs;

package/dist/study/types.d.ts

@@ -581,6 +581,12 @@ export type StudyNetworkCapture = boolean | {
 };
 export interface StudyExecution {
     target?: StudyExecutionTarget;
+    /**
+     * Where the study's own process runs. Unset: in a runner sandbox on the participants' provider
+     * when the study can, so it outlives this machine; false: always on this machine; true: only
+     * remotely, refused when the study cannot. `--local` and `--remote` override it for one run.
+     */
+    remote?: boolean;
     /** Actor session wall-clock budget. Consumed on the app-url route. */
     timeoutMs?: number;
     /** Forward-declared: no route reads it yet, so a set value warns. */

package/dist/substrates/e2b/egress-keys.d.ts

@@ -0,0 +1,22 @@
+import type { E2BNetworkOptions } from "./sdk.js";
+/** An inert nonsecret value that satisfies a client's "key is set" check. E2B replaces the header. */
+export declare const EGRESS_PLACEHOLDER = "humanish-egress-auth-placeholder";
+/** E2B envd installs the sandbox-specific proxy CA into this system bundle before routing. */
+export declare const E2B_SYSTEM_CA_BUNDLE = "/etc/ssl/certs/ca-certificates.crt";
+/**
+ * Hold every key in `keys` that travels as a header to a fixed host in an E2B header transform on
+ * `existing`, and give the env a placeholder for it. Other names pass through unchanged. The
+ * installed E2B SDK declares that transform headers override the request's own. The returned
+ * network carries the key values: never log or persist it. E2B's sandbox info endpoint returns
+ * the transforms as given, so a process that can call the E2B API for this sandbox can read them.
+ * An existing rule for a held key's host is refused, never overwritten.
+ */
+export declare function holdKeysInEgress(keys: Readonly<Record<string, string>>, options?: {
+    /** The account's E2B_DOMAIN; the E2B API host is `api.<domain>`. */
+    domain?: string | undefined;
+    existing?: E2BNetworkOptions | undefined;
+}): {
+    network: E2BNetworkOptions;
+    env: Record<string, string>;
+    held: string[];
+};

package/dist/substrates/e2b/egress-keys.js

@@ -0,0 +1,59 @@
+/** An inert nonsecret value that satisfies a client's "key is set" check. E2B replaces the header. */
+export const EGRESS_PLACEHOLDER = "humanish-egress-auth-placeholder";
+/** E2B envd installs the sandbox-specific proxy CA into this system bundle before routing. */
+export const E2B_SYSTEM_CA_BUNDLE = "/etc/ssl/certs/ca-certificates.crt";
+const GEMINI = {
+    host: "generativelanguage.googleapis.com",
+    header: "x-goog-api-key",
+    value: (key) => key,
+};
+/**
+ * Where each key name humanish sends as a header goes. Every host is fixed in the code that calls
+ * it: src/actors/openai-endpoint.ts, src/analysis/gemini-wire.ts, and the E2B SDK's
+ * `https://api.<E2B_DOMAIN>` with its `X-API-KEY` header.
+ */
+function headerKey(name, domain) {
+    if (name === "OPENAI_API_KEY")
+        return { host: "api.openai.com", header: "Authorization", value: (key) => `Bearer ${key}` };
+    if (name === "GEMINI_API_KEY" || name === "GOOGLE_API_KEY")
+        return GEMINI;
+    if (name === "E2B_API_KEY")
+        return { host: `api.${domain}`, header: "X-API-Key", value: (key) => key };
+    return undefined;
+}
+const sameHost = (a, b) => a.toLowerCase().replace(/\.$/, "") === b.toLowerCase().replace(/\.$/, "");
+/**
+ * Hold every key in `keys` that travels as a header to a fixed host in an E2B header transform on
+ * `existing`, and give the env a placeholder for it. Other names pass through unchanged. The
+ * installed E2B SDK declares that transform headers override the request's own. The returned
+ * network carries the key values: never log or persist it. E2B's sandbox info endpoint returns
+ * the transforms as given, so a process that can call the E2B API for this sandbox can read them.
+ * An existing rule for a held key's host is refused, never overwritten.
+ */
+export function holdKeysInEgress(keys, options = {}) {
+    const { existing } = options;
+    const domain = options.domain?.trim() || "e2b.app";
+    const rules = {};
+    const env = {};
+    const held = [];
+    for (const [name, value] of Object.entries(keys)) {
+        const placed = headerKey(name, domain);
+        if (placed === undefined) {
+            env[name] = value;
+            continue;
+        }
+        const taken = [...Object.keys(existing?.rules ?? {}), ...Object.keys(rules)].some((host) => sameHost(host, placed.host));
+        if (taken)
+            throw new Error(`${name} would be held in a header transform on ${placed.host}, which already has a network rule; refusing to overwrite it.`);
+        rules[placed.host] = [{ transform: { headers: { [placed.header]: placed.value(value) } } }];
+        env[name] = EGRESS_PLACEHOLDER;
+        held.push(name);
+    }
+    if (held.length === 0)
+        return { network: { ...existing }, env, held };
+    return {
+        network: { ...existing, rules: { ...existing?.rules, ...rules } },
+        env,
+        held: held.sort(),
+    };
+}

package/dist/tui/launch.js

@@ -104,6 +104,9 @@ export async function launchRun(options) {
         cwd,
         "--json",
         "--no-open",
+        // The TUI follows and stops a run through its local status record, which a remote run does
+        // not have until it is copied back.
+        "--local",
         ...(options.mode === "dry-run" ? ["--dry-run"] : []),
         // `--` ends option parsing, so the handle can only ever be read as the positional argument.
         "--",

package/docs/contracts/study-analysis.md

@@ -461,6 +461,19 @@ that screen is a strong design finding. Validation is unchanged. A design findin
 least one cited capture, so an impression plus the capture of its screen makes a design finding,
 and an impression alone supports only a finding about what the participant said.
 
+## Participant statement citations
+
+An observation with basis `participant_statement` must cite at least one quote-eligible entry
+(`analysis_validation_failed_statement_source_invalid` otherwise). It may also cite captures or
+actions, as an `action` observation may cite more than its one required action. The prompt still
+asks for statements that cite only quote-eligible entries; validation accepts an analyst that adds
+the capture the participant spoke about. Validation does not check that the observation's wording
+matches the quote. Entries of kind `reasoning` are quote-eligible, so a claim drawn from a
+participant's private reasoning also passes as a statement. Before this rule, any non-quote
+citation failed the whole analysis, which caused nearly all `gpt-6-luna` rejections on the
+2026-10-22 benchmark recordings
+([participant statements that cite captures](https://github.com/danielgwilson/humanish/blob/main/docs/evidence/benchmark/2026-10-22-statement-rule.md)).
+
 ## Durable records
 
 The `humanish.observer-data.v3` schema is unchanged by analysis. A companion

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "humanish",
-  "version": "0.143.0",
+  "version": "0.145.0",
   "description": "Synthetic user research for apps, CLIs, and agent-facing product flows.",
   "keywords": [
     "cli",

package/skills/humanish/SKILL.md

@@ -553,6 +553,15 @@ has finished. A participant with `endAfterMs` can keep a study running for up to
 analysis usually adds 1 to 4 minutes after the last participant ends. A shell timeout that sends
 SIGTERM stops the run: humanish marks it interrupted and stops its sandboxes.
 
+- A computer-use study on `e2b-desktop` or `modal-desktop` with a public `app-url` runs remotely
+  by default: its own process runs in a sandbox on that provider, so a sleeping machine does not
+  stop it. `run` still blocks and exits with the run's code; SIGTERM still stops the run. Until its
+  bundle is copied back it is not in `runs --json`; `npx humanish observe --run <id>` follows it.
+  If its terminal closes, the command exits 129 with `HUMANISH_REMOTE_DETACHED` and the run goes
+  on; `observe --run <id>` copies it back. `--local` keeps one run on this machine,
+  `execution.remote: false` every run of a study. The JSON result's `remote.keys` names the keys
+  the run used. On E2B the OpenAI, Gemini and E2B keys stay in E2B's egress proxy and the runner
+  holds placeholders; a Modal runner receives them as environment variables.
 - Start a study that can outlive your shell call in tmux, for example
   `tmux new -d -s study 'npx humanish run <study> --json --no-open > run-result.json 2> run.log'`.
   `--detach` only skips the Observer server at the end; it does not move the run to the background.