humanish 0.143.0 → 0.144.0

package/CHANGELOG.md

@@ -8,6 +8,17 @@ The Unreleased section holds the full notes for the next version until it is tag
 
 ## Unreleased
 
+## 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/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,45 @@
 import type { Command } from "commander";
 import { type RemoteOutcome } 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 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,125 @@
 // `--remote` on run and watch: plan here, refuse what cannot run remotely, then launch and follow
 // the run in a runner sandbox (src/remote/launch.ts). The result and exit code are the run's own.
 import path from "node:path";
-import { launchRemoteRun } from "../../remote/launch.js";
+import { forwardedEnv, launchRemoteRun, 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 forwarded = {
+        provider: args.remote.provider,
+        keys: Object.keys(forwardedEnv(args.remote, process.env)).sort(),
+    };
+    io.writeErr(`The runner receives ${forwarded.keys.join(", ") || "no keys"} from this machine, in your own ${forwarded.provider === "modal" ? "Modal" : "E2B"} account. Run with --local to keep the study on this machine.\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 run options a remote run does not carry to the runner yet. */
 function localOnlyFlags(options) {
@@ -90,28 +134,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/remote/launch.d.ts

@@ -45,8 +45,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 +59,10 @@ export interface Signals {
  * running; the runner ends it at its deadline.
  */
 export declare function watchSignals(): Signals;
+/**
+ * The names and values 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.
+ */
+export declare function forwardedEnv(remote: Pick<RemotePlan, "envNames" | "alternatives">, env: Readonly<Record<string, string | undefined>>): Record<string, string>;
+/** Whether this humanish runs from a built package, which a runner can install. */
+export declare function runsFromPackage(): boolean;

package/dist/remote/launch.js

@@ -56,6 +56,8 @@ 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);
@@ -71,7 +73,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 +95,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: forwardedEnv(remote, launch.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();
@@ -152,8 +163,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 +178,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 +317,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 +341,7 @@ export function watchSignals() {
         get exitCode() {
             return exitCode;
         },
+        received,
         dispose() {
             process.off("SIGINT", interrupt);
             process.off("SIGTERM", terminate);
@@ -330,6 +349,21 @@ export function watchSignals() {
         },
     };
 }
+/**
+ * The names and values 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.
+ */
+export function forwardedEnv(remote, env) {
+    const set = (name) => (env[name]?.trim() ?? "") !== "";
+    const unread = new Set(remote.alternatives.flatMap((names) => names.filter(set).slice(1)));
+    return Object.fromEntries(remote.envNames.flatMap((name) => (set(name) && !unread.has(name) ? [[name, env[name]]] : [])));
+}
+/** 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 +371,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/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/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/package.json

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

package/skills/humanish/SKILL.md

@@ -553,6 +553,14 @@ 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 runner received.
 - 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.