humanish 0.142.0 → 0.144.0

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

@@ -158,10 +158,11 @@ interface LiveStudy {
 }
 /** ` --cwd <dir>`, or "" when `cwd` is the current directory. */
 export declare function cwdFlag(cwd: string): string;
-/** An analysis provider and model, as a study or an analysis record names them. */
+/** An analysis provider, model and effort, as a study or an analysis record names them. */
 interface Analyst {
     provider?: string | undefined;
     model?: string;
+    reasoningEffort?: string | undefined;
 }
 /** The findings view of a run's selected analysis, or why it has none. */
 export declare function analysisFindings(source: FindingsSource): AnalysisFindings;

package/dist/cli/findings.js

@@ -5,7 +5,7 @@
 // starts an analysis.
 import path from "node:path";
 import { costRefusal } from "../analysis/admission.js";
-import { DEFAULT_ANALYSIS_MAX_COST_USD, resolveAutomaticAnalysis, } from "../analysis/automatic-config.js";
+import { DEFAULT_ANALYSIS_EFFORT, DEFAULT_ANALYSIS_MAX_COST_USD, DEFAULT_ANALYSIS_MODEL, resolveAutomaticAnalysis, } from "../analysis/automatic-config.js";
 import { ANALYSIS_USUALLY_TAKES } from "../analysis/analysis-limits.js";
 import { bySeverity } from "../analysis/finding-lead.js";
 import { loadAnalysis } from "../analysis/load.js";
@@ -35,15 +35,25 @@ const KEY_MISSING_REASONS = new Set([
     "AUTOMATIC_ANALYSIS_KEY_MISSING",
     "AUTOMATIC_ANALYSIS_GEMINI_KEY_MISSING",
 ]);
+/** The effort an analysis configuration declares; Codex configurations declare none. */
+const declaredEffort = (config) => "reasoningEffort" in config ? config.reasoningEffort : undefined;
 /** The `analyze` command that runs `analyst` on the run; undefined is the OpenAI default. */
 function analyzeCommand(source, analyst) {
     const run = cli(`analyze --run ${source.runId}${source.cwdFlag}`);
     if (analyst?.provider === "codex")
         return `${run} --provider codex`;
-    const gemini = analyst?.provider === "gemini"
-        ? ` --provider gemini${analyst.model === undefined ? "" : ` --model ${analyst.model}`}`
-        : "";
-    return `${run}${gemini} --max-cost ${DEFAULT_ANALYSIS_MAX_COST_USD}`;
+    if (analyst?.provider === "gemini") {
+        const model = analyst.model === undefined ? "" : ` --model ${analyst.model}`;
+        return `${run} --provider gemini${model} --max-cost ${DEFAULT_ANALYSIS_MAX_COST_USD}`;
+    }
+    // A named model or effort stays in the command, so the rerun is the same analyst. The default
+    // analyst needs neither: `analyze` without flags runs it.
+    const isDefault = (analyst?.model ?? DEFAULT_ANALYSIS_MODEL) === DEFAULT_ANALYSIS_MODEL &&
+        (analyst?.model === undefined || analyst.reasoningEffort === DEFAULT_ANALYSIS_EFFORT);
+    const flags = isDefault
+        ? ""
+        : ` --model ${analyst.model}${analyst.reasoningEffort === undefined ? "" : ` --reasoning-effort ${analyst.reasoningEffort}`}`;
+    return `${run}${flags} --max-cost ${DEFAULT_ANALYSIS_MAX_COST_USD}`;
 }
 /** The cited items the analysis evidence resolves, each once, in citation order. */
 function citedEvidence(ids, analysis, runRoot) {
@@ -180,7 +190,7 @@ function missingKeyFindings(source, reason) {
         }));
     const opening = "The automatic analysis was skipped because OPENAI_API_KEY is not set.";
     if (source.codexSignedIn !== true)
-        return withoutFindings(source, "skipped", reason, `${opening} Set it with ${cli("keys set openai")}, then run the next command.`, analyzeCommand(source, undefined));
+        return withoutFindings(source, "skipped", reason, `${opening} Set it with ${cli("keys set openai")}, then run the next command.`, analyzeCommand(source, source.analyst?.provider === "gemini" ? undefined : source.analyst));
     const file = source.study?.path === undefined ? "the study file" : source.study.path;
     return withoutFindings(source, "skipped", reason, `${opening} Codex is signed in on this machine, so its ChatGPT account can analyze the run instead, sending the evidence to OpenAI under that account. The next command does it once; review.analysis.provider: codex in ${file} makes it this study's analyst.`, analyzeCommand(source, { provider: "codex" }));
 }
@@ -234,7 +244,11 @@ async function studyAnalyst(cwd, study) {
         return undefined;
     const analysis = resolveAutomaticAnalysis(resolved.config.review?.analysis, resolved.config.actor);
     return analysis.ok && analysis.config !== undefined
-        ? { provider: analysis.config.provider, model: analysis.config.model }
+        ? {
+            provider: analysis.config.provider,
+            model: analysis.config.model,
+            reasoningEffort: declaredEffort(analysis.config),
+        }
         : undefined;
 }
 /** The findings view of a run's selected analysis, or why it has none. */
@@ -255,7 +269,11 @@ export function analysisFindings(source) {
                 ? `The run's evidence changed after analysis ${analysis.id}, so its findings may not match the run.`
                 : `Analysis ${analysis.id} is ${analysis.status}, with ${plural(result.findings.length, "finding")}.`,
             next: stale
-                ? analyzeCommand(source, { provider: analysis.provider, model: analysis.config.model })
+                ? analyzeCommand(source, {
+                    provider: analysis.provider,
+                    model: analysis.config.model,
+                    reasoningEffort: declaredEffort(analysis.config),
+                })
                 : null,
             analysisId: analysis.id,
             status: analysis.status,
@@ -279,7 +297,11 @@ export function analysisFindings(source) {
     if (pending !== undefined)
         return pending;
     if (analysis && analysis.result === null)
-        return withoutFindings(source, "failed", analysis.error, `Analysis attempt ${analysis.id} ${analysis.status === "cancelled" ? "was cancelled" : "failed"}${analysis.error ? ` (${analysis.error})` : ""} and left no findings.`, analyzeCommand(source, { provider: analysis.provider, model: analysis.config.model }));
+        return withoutFindings(source, "failed", analysis.error, `Analysis attempt ${analysis.id} ${analysis.status === "cancelled" ? "was cancelled" : "failed"}${analysis.error ? ` (${analysis.error})` : ""} and left no findings.`, analyzeCommand(source, {
+            provider: analysis.provider,
+            model: analysis.config.model,
+            reasoningEffort: declaredEffort(analysis.config),
+        }));
     if (job?.state === "failed" || job?.state === "cancelled") {
         const outcome = analysisOutcomeText(job);
         return withoutFindings(source, "failed", job.reason, `The automatic analysis ${outcome.startsWith("failed") ? "" : "was "}${outcome}.`, analyzeCommand(source, job.reason === "AUTOMATIC_ANALYSIS_CODEX_UNAVAILABLE" ? { provider: "codex" } : undefined));

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

@@ -38,12 +38,20 @@ export declare function followRemoteRun(args: {
     signals: Signals;
     proxyUrl: string;
 }): Promise<RemoteOutcome>;
-/** Two sandbox journals as one: every line of each, in order, one per line. */
+/**
+ * Two sandbox journals as one: every line of each, in order, once. A copy that runs again adds
+ * nothing it already added.
+ */
 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;
 }
 /**
@@ -51,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;