humanish 0.109.1 → 0.110.1

package/dist/actors/local-agent/cli.js

@@ -21,13 +21,15 @@
 // operator's machine. The same trick on the terminal route would be the opposite: it would move
 // code execution out of the sandbox and onto a real disk, which is why this is a computer-use
 // provider and nothing else. Even so, these are coding agents with their own shell and file tools,
-// so each one is spawned tool-restricted, in a scratch directory, with a per-turn timeout.
+// so each one is spawned tool-restricted, in a scratch directory, with a per-turn timeout. Claude
+// Code's flags, environment and stream checks are in claude-participant.ts.
 import { spawn } from "node:child_process";
-import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { mkdtemp, realpath, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import path from "node:path";
 import { admitsCodexCliVersion, parseCodexCliVersion } from "../codex/codex-admission.js";
 import { restrictedCodexNpmTarget } from "../codex/restricted-executable.js";
+import { ClaudeStreamGuard, admitsClaudeCodeVersion, claudeCodeVersionMessage, claudeParticipantEnv, claudeParticipantFlags, parseClaudeCodeVersion, } from "./claude-participant.js";
 const LOCAL_AGENTS = [
     { id: "codex", bin: "codex", label: "Codex", credentialPath: ".codex/auth.json" },
     {
@@ -120,9 +122,14 @@ export function parseAgentJson(text) {
     throw new Error("the local agent did not return a JSON object");
 }
 const defaultSpawn = async (bin, args, options) => await new Promise((resolve) => {
-    const child = spawn(bin, [...args], { cwd: options.cwd, stdio: ["ignore", "pipe", "pipe"] });
+    const child = spawn(bin, [...args], {
+        cwd: options.cwd,
+        env: options.env,
+        stdio: ["ignore", "pipe", "pipe"],
+    });
     let stdout = "";
     let stderr = "";
+    let scanned = 0;
     const timer = setTimeout(() => child.kill("SIGKILL"), options.timeoutMs);
     // Stopping a run must stop the thinking too: a local agent mid-turn can hold a terminal for
     // minutes, and a Stop that leaves it running is not a stop.
@@ -136,6 +143,12 @@ const defaultSpawn = async (bin, args, options) => await new Promise((resolve) =
     };
     child.stdout?.on("data", (chunk) => {
         stdout += chunk.toString("utf8");
+        for (let end = stdout.indexOf("\n", scanned); end >= 0; end = stdout.indexOf("\n", scanned)) {
+            const line = stdout.slice(scanned, end);
+            scanned = end + 1;
+            if (options.onLine?.(line) === true)
+                child.kill("SIGKILL");
+        }
     });
     child.stderr?.on("data", (chunk) => {
         stderr += chunk.toString("utf8");
@@ -214,35 +227,33 @@ export function createLocalAgentProvider(options) {
                 const screenshotPath = path.join(work, "screen.png");
                 await writeFile(screenshotPath, frame);
                 const prompt = promptFor(request, screenshotPath);
-                const args = [
-                    "-p",
-                    "--output-format",
-                    "json",
-                    // Read is the only tool it needs (the screenshot) and the only one it gets.
-                    "--allowedTools",
-                    "Read",
-                    ...(options.model === undefined ? [] : ["--model", options.model]),
-                    // `--allowedTools` takes a list, so a prompt placed right after it is read as a tool
-                    // name and Claude Code exits 1 with "Input must be provided". Three of three one-shot
-                    // runs failed on turn one that way on 2026-09-01 (Claude Code 2.1.257); `--` ends the
-                    // options so the prompt is the prompt.
-                    "--",
-                    prompt,
-                ];
-                const result = await spawnFn(descriptor.bin, args, {
+                const folders = [work, await realpath(work).catch(() => work)];
+                const watch = new ClaudeStreamGuard(folders);
+                const result = await spawnFn(descriptor.bin, claudeOneShotArgs(prompt, options.model), {
                     cwd: work,
+                    env: claudeParticipantEnv(options.env ?? process.env),
                     timeoutMs,
                     ...(signal === undefined ? {} : { signal }),
+                    // Stops the process as soon as a line is refused; the full scan below decides the turn.
+                    onLine: (line) => inspectLine(watch, line) !== undefined,
                 });
+                const { refusal, result: final } = scanClaudeStream(result.stdout, folders);
+                if (refusal !== undefined)
+                    throw refusal;
                 if (result.code !== 0) {
                     // Fail loud with the CLI's own words. A rate-limited plan says so here, and that is a
                     // sentence the operator can act on, unlike "turn failed".
                     const detail = (result.stderr || result.stdout).trim().slice(-400);
                     throw new Error(`${descriptor.label} exited ${result.code ?? "on a signal"}: ${detail}`);
                 }
-                // Claude Code returns an envelope on stdout whose `result` field holds the text.
-                const envelope = parseAgentJson(result.stdout);
-                const payload = typeof envelope.result === "string" ? envelope.result : result.stdout;
+                if (final === undefined)
+                    throw new Error(`${descriptor.label} returned no result message`);
+                if (final.is_error === true) {
+                    const ending = typeof final.subtype === "string" ? final.subtype : "in error";
+                    const said = typeof final.result === "string" ? final.result.slice(0, 160) : "";
+                    throw new Error(`${descriptor.label} turn ended ${ending}: ${said}`);
+                }
+                const payload = typeof final.result === "string" ? final.result : "";
                 const turn = parseAgentJson(payload);
                 const actions = toCuaActions(Array.isArray(turn.actions) ? turn.actions : []);
                 const done = turn.done === true || (actions.length === 0 && typeof turn.message === "string");
@@ -268,6 +279,53 @@ export function createLocalAgentProvider(options) {
         },
     };
 }
+/** The one-shot argv: stream-json out so every message can be checked, then the prompt after `--`. */
+function claudeOneShotArgs(prompt, model) {
+    return [
+        "-p",
+        "--output-format",
+        "stream-json",
+        // Required for stream-json output in -p mode.
+        "--verbose",
+        ...claudeParticipantFlags(model),
+        // `--tools` takes a list, so a prompt placed right after it would be read as a tool name.
+        // `--` ends the options so the prompt is the prompt.
+        "--",
+        prompt,
+    ];
+}
+/** The refusal one stdout line proves, if any. A line that is not JSON proves nothing. */
+function inspectLine(guard, line) {
+    let message;
+    try {
+        message = JSON.parse(line);
+    }
+    catch {
+        return undefined;
+    }
+    return message !== null && typeof message === "object" && !Array.isArray(message)
+        ? guard.inspect(message)
+        : undefined;
+}
+/** The first refusal in a finished one-shot stream, and its last `result` message. */
+function scanClaudeStream(stdout, folders) {
+    const guard = new ClaudeStreamGuard(folders);
+    let result;
+    for (const line of stdout.split("\n")) {
+        const refusal = inspectLine(guard, line);
+        if (refusal !== undefined)
+            return { refusal };
+        try {
+            const message = JSON.parse(line);
+            if (message?.type === "result")
+                result = message;
+        }
+        catch {
+            // not a message
+        }
+    }
+    return result === undefined ? {} : { result };
+}
 /** No shell, prompts or model request. Bound time and output even for a broken CLI. */
 async function authProbe(bin, args, env) {
     return await new Promise((resolve) => {
@@ -375,7 +433,10 @@ export async function detectLocalAgents(options = {}) {
                 .catch(() => false);
         });
     const found = [];
+    const probe = options.authProbe ?? authProbe;
     for (const descriptor of LOCAL_AGENTS) {
+        if (options.only !== undefined && descriptor.id !== options.only)
+            continue;
         const binPath = await which(descriptor.bin);
         if (binPath === undefined)
             continue;
@@ -384,24 +445,42 @@ export async function detectLocalAgents(options = {}) {
             : descriptor.id === "claude" && env.CLAUDE_CONFIG_DIR
                 ? path.join(env.CLAUDE_CONFIG_DIR, ".credentials.json")
                 : path.join(home, descriptor.credentialPath);
-        const status = await (options.authProbe ?? authProbe)(binPath, descriptor.id === "codex" ? ["login", "status"] : ["auth", "status"], env)
+        // Claude Code is asked with the participant's own environment, so a login that only works
+        // through a dropped variable (ANTHROPIC_API_KEY, CLAUDE_CODE_OAUTH_TOKEN) reads as signed out.
+        const probeEnv = descriptor.id === "claude" ? claudeParticipantEnv(env) : env;
+        const status = await probe(binPath, descriptor.id === "codex" ? ["login", "status"] : ["auth", "status"], probeEnv)
             .then((result) => classifyAuth(descriptor.id, result))
             .catch(() => ({ authStatus: "unknown" }));
+        const version = descriptor.id === "claude"
+            ? await probe(binPath, ["--version"], probeEnv)
+                .then((result) => result.code === 0 ? parseClaudeCodeVersion(result.stdout) : undefined)
+                .catch(() => undefined)
+            : undefined;
         found.push({
             ...descriptor,
             binPath,
             credentialsPresent: await exists(file).catch(() => false),
             ...status,
+            ...(version === undefined ? {} : { version }),
         });
     }
     return found;
 }
 /** Doctor's row when neither Codex nor Claude Code is installed. */
 export const NO_LOCAL_AGENT_MESSAGE = "no local coding agent found. openai-computer-use needs OPENAI_API_KEY; local-agent needs Codex or Claude Code installed and signed in. Hosted desktops also need E2B_API_KEY.";
+/** Whether a signed-in agent can still not run participants here: an old Claude Code. */
+export function localAgentVersionRefusal(agent) {
+    return agent.id === "claude" && !admitsClaudeCodeVersion(agent.version)
+        ? claudeCodeVersionMessage(agent.version)
+        : undefined;
+}
 /** Doctor's row for one installed agent, in the register the other rows use. */
 export function localAgentDoctorMessage(agent) {
+    const outdated = localAgentVersionRefusal(agent);
+    if (agent.authStatus === "authenticated" && outdated !== undefined)
+        return `${agent.label} reports signed in, but cannot run participants yet. ${outdated}`;
     if (agent.authStatus === "authenticated")
-        return `${agent.label} reports signed in; a study with actors[0].type: local-agent can use it instead of a provider API key. Account access and limits are untested.`;
+        return `${agent.label}${agent.version === undefined ? "" : ` ${agent.version}`} reports signed in; a study with actor.type: local-agent can use it instead of a provider API key. Account access and limits are untested.`;
     const status = agent.id === "codex" ? "codex login status" : "claude auth status";
     return agent.authStatus === "unauthenticated"
         ? `${agent.label} is installed and reports not signed in; run \`${agent.id === "codex" ? "codex login" : "claude auth login"}\``

package/dist/actors/local-agent/readiness.d.ts

@@ -11,12 +11,12 @@ export type LocalAgentRefusal =
     kind: "signin-required";
     message: string;
 }
-/** Hosted Codex on an unsupported platform or a CLI release the launcher refuses. */
+/** Hosted Codex on an unsupported platform or release, or a Claude Code older than the floor. */
  | {
     kind: "unsupported";
     message: string;
 }
-/** A ChatGPT-account Codex with execution.caps, which it cannot price. */
+/** A ChatGPT-account Codex with a dollar cap in `caps`, which it cannot price. */
  | {
     kind: "unpriced-cap";
     message: string;

package/dist/actors/local-agent/readiness.js

@@ -1,30 +1,37 @@
 // Whether a local-agent participant can run on this machine before anything is acquired: its CLI
-// is on `PATH` and signed in, a hosted Codex CLI is a qualified release on a supported platform, and
-// a ChatGPT-account Codex is not asked to enforce a dollar cap it has no price for. Each route maps
-// the refusal's kind to its own error code.
+// is on `PATH` and signed in, a hosted Codex CLI is a qualified release on a supported platform, a
+// Claude Code CLI has the flags that restrict a participant, and a ChatGPT-account Codex is not
+// asked to enforce a dollar cap it has no price for. Each route maps the refusal's kind to its own
+// error code.
 import { describeCodexCliAdmission } from "../codex/codex-admission.js";
-import { checkHostedCodexCompatibility, detectLocalAgents } from "./cli.js";
+import { checkHostedCodexCompatibility, detectLocalAgents, localAgentVersionRefusal, } from "./cli.js";
 export async function localAgentRefusal(args) {
     const { agent, env, caps } = args;
-    const available = await detectLocalAgents({ env });
+    const available = await detectLocalAgents({ env, only: agent });
     const chosen = available.find((candidate) => candidate.id === agent);
     if (chosen === undefined) {
         return {
             kind: "agent-missing",
-            message: `actors[0].type: local-agent needs the ${agent} CLI on PATH and signed in. ` +
-                `Install it, or set OPENAI_API_KEY and use actors[0].type: openai-computer-use instead.`,
+            message: `actor.type: local-agent needs the ${agent} CLI on PATH and signed in. ` +
+                `Install it, or set OPENAI_API_KEY and use actor.type: openai-computer-use instead.`,
         };
     }
     if (chosen.authStatus !== "authenticated") {
         return {
             kind: "signin-required",
             message: chosen.authStatus === "unauthenticated"
-                ? `${chosen.label} reports it is not signed in; run \`${chosen.id === "codex" ? "codex login" : "claude auth login"}\`, then retry.`
+                ? chosen.id === "codex"
+                    ? "Codex reports it is not signed in; run `codex login`, then retry."
+                    : `Claude Code reports it is not signed in with the environment a participant gets, which keeps its own login but not ANTHROPIC_API_KEY or CLAUDE_CODE_OAUTH_TOKEN. Run \`claude auth login\`, then retry.`
                 : `${chosen.label} authentication status could not be checked. Run \`${chosen.id === "codex" ? "codex login status" : "claude auth status"}\` and update the CLI if needed. No desktop was launched.`,
         };
     }
-    if (chosen.id !== "codex")
-        return undefined;
+    if (chosen.id === "claude") {
+        const outdated = localAgentVersionRefusal(chosen);
+        return outdated === undefined
+            ? undefined
+            : { kind: "unsupported", message: `${outdated} No desktop was launched.` };
+    }
     const compatibility = await checkHostedCodexCompatibility(chosen.binPath, { env });
     if (compatibility !== "supported") {
         return {
@@ -38,7 +45,7 @@ export async function localAgentRefusal(args) {
         (caps.maxUsd !== undefined || caps.maxTotalUsd !== undefined)) {
         return {
             kind: "unpriced-cap",
-            message: "A ChatGPT-account Codex participant has no API-dollar price, so execution.caps.maxUsd/maxTotalUsd cannot be enforced. Remove the dollar cap and use finite execution timeout/step limits, or use an API-backed participant; no desktop was launched.",
+            message: "A ChatGPT-account Codex participant has no API-dollar price, so caps.maxUsd/maxTotalUsd cannot be enforced. Remove the dollar cap and use finite execution timeout/step limits, or use an API-backed participant; no desktop was launched.",
         };
     }
     return undefined;

package/dist/cli/commands/analyze.js

@@ -5,7 +5,8 @@ import { analyzeRun, correctAnalysis, dryRunBundleRefusal, showAnalysis, } from
 import { listAnalyses } from "../../analysis/store.js";
 import { listAnalysisExecutions } from "../../analysis/store-executions.js";
 import { resolveRunPath } from "../../run/locate.js";
-import { CWD_OPTION_DESCRIPTION, discoverCliKeys, JSON_OPTION_DESCRIPTION, RUN_OPTION_DESCRIPTION, writeResult, humanError, } from "../io.js";
+import { CWD_OPTION_DESCRIPTION, discoverCliKeys, JSON_OPTION_DESCRIPTION, RUN_OPTION_DESCRIPTION, writeResult, humanError, wantsJson, } from "../io.js";
+import { analysisFindings, formatFindings, missingRunFindings, readRunAnalysis, } from "../findings.js";
 import { resolvePhysicalCwd } from "../../run/paths.js";
 /** Commander may collect a shared flag on the parent; only explicit values override leaf defaults. */
 function analysisSelection(options, command) {
@@ -46,7 +47,7 @@ export function registerAnalyzeCommand(parent, io) {
         .action((options, command) => handleAnalyzeList(io, options, command));
     analyze
         .command("show")
-        .description("Read validated analysis and correction history. Defaults to the latest usable version.")
+        .description("Print a run's analysis findings with the evidence each one cites. --json prints the validated analysis record and its correction history. Defaults to the latest usable version.")
         .option("--run <id>", RUN_OPTION_DESCRIPTION, "latest")
         .option("--id <id>", "Exact analysis version.")
         .option("--cwd <path>", CWD_OPTION_DESCRIPTION, ".")
@@ -180,9 +181,24 @@ async function handleAnalyzeList(io, options, command) {
 }
 async function handleAnalyzeShow(io, options, command) {
     options = analysisSelection(options, command);
-    const result = await showAnalysis(options.cwd, options.run, options.id);
-    writeResult(command, io, result, (value) => forTerminal(JSON.stringify(value, null, 2) + "\n"));
-    io.setExitCode(result.state === "invalid" ? 2 : 0);
+    if (wantsJson(command)) {
+        const result = await showAnalysis(options.cwd, options.run, options.id);
+        writeResult(command, io, result, () => "");
+        io.setExitCode(result.state === "invalid" ? 2 : 0);
+        return;
+    }
+    const source = await readRunAnalysis(options.cwd, options.run, options.id);
+    const findings = source ? analysisFindings(source) : missingRunFindings(options.cwd, options.run);
+    writeResult(command, io, findings, formatAnalysisShowHuman);
+    // The exit code the --json form gives for the same record.
+    io.setExitCode(source === null || source.loaded.state === "invalid" ? 2 : 0);
+}
+/**
+ * `analyze show` without --json: the findings, or why there are none and the command that gets
+ * them.
+ */
+function formatAnalysisShowHuman(findings) {
+    return ([`humanish analyze show ${findings.runId}`, "", ...formatFindings(findings)].join("\n") + "\n");
 }
 async function handleAnalyzeCorrect(io, options, command) {
     options = analysisSelection(options, command);

package/dist/cli/commands/comms.js

@@ -9,7 +9,7 @@ import { resolveReceivingConnection } from "../../comms/receiving-runtime.js";
 import { resolveStudyManifest } from "../../study/discover.js";
 import { runCommsCatchHost } from "../../comms/catch-host.js";
 import { DEFAULT_SANDBOX_CATCH_PORT } from "../../comms/sandbox-catch.js";
-import { applyEnvFileOption, CWD_OPTION_DESCRIPTION, ENV_FILE_OPTION_DESCRIPTION, JSON_OPTION_DESCRIPTION, PORT_OPTION_DESCRIPTION, writeResult, messageOutput, } from "../io.js";
+import { applyEnvFileOption, CWD_OPTION_DESCRIPTION, DOTENV_OPTION_DESCRIPTION, dotenvPathOf, envFileAliasOption, JSON_OPTION_DESCRIPTION, PORT_OPTION_DESCRIPTION, writeResult, messageOutput, } from "../io.js";
 export function registerCommsCommands(parent, io) {
     const comms = parent
         .command("comms")
@@ -27,7 +27,8 @@ export function registerCommsCommands(parent, io) {
         .command("list")
         .description("Show saved connections and local credential status; does not authenticate with a provider.")
         .option("--cwd <path>", CWD_OPTION_DESCRIPTION, ".")
-        .option("--env-file <path>", ENV_FILE_OPTION_DESCRIPTION)
+        .option("--dotenv <path>", DOTENV_OPTION_DESCRIPTION)
+        .addOption(envFileAliasOption())
         .option("--json", JSON_OPTION_DESCRIPTION)
         .action((options, command) => handleCommsList(io, options, command));
     connections
@@ -46,7 +47,8 @@ export function registerCommsCommands(parent, io) {
         .option("--connection <name>", "Saved connection name.", "agentmail")
         .option("--study <path>", "Check the connection this study selects.")
         .option("--online", "Make a read-only provider authentication request.")
-        .option("--env-file <path>", ENV_FILE_OPTION_DESCRIPTION)
+        .option("--dotenv <path>", DOTENV_OPTION_DESCRIPTION)
+        .addOption(envFileAliasOption())
         .option("--json", JSON_OPTION_DESCRIPTION)
         .action((options, command) => handleCommsCheck(io, options, command));
     comms
@@ -65,7 +67,8 @@ export function registerCommsCommands(parent, io) {
         .option("--cwd <path>", CWD_OPTION_DESCRIPTION, ".")
         .option("--run <id>", "One run to inspect or recover.")
         .option("--apply", "Recover the selected inactive run and verify mailbox deletion.")
-        .option("--env-file <path>", ENV_FILE_OPTION_DESCRIPTION)
+        .option("--dotenv <path>", DOTENV_OPTION_DESCRIPTION)
+        .addOption(envFileAliasOption())
         .option("--json", JSON_OPTION_DESCRIPTION)
         .action((options, command) => handleCommsRecover(io, options, command));
     comms
@@ -89,7 +92,12 @@ function handleCommsProviders(io, _options, command) {
     writeResult(command, io, result, () => COMMS_PROVIDERS.map((provider) => `${provider.label}: ${provider.limitation}\nKey: ${provider.keyEnv}\nSetup: ${provider.setupUrl}\n`).join("\n"));
 }
 async function handleCommsList(io, options, command) {
-    if (!(await applyEnvFileOption({ command, cwd: options.cwd, envFile: options.envFile, io })))
+    if (!(await applyEnvFileOption({
+        command,
+        cwd: options.cwd,
+        envFile: dotenvPathOf(options, command, io),
+        io,
+    })))
         return;
     const result = await readCommsSetup(resolve(options.cwd), process.env);
     writeResult(command, io, result, (value) => `${value.message}\nAgentMail key: ${value.credential.present ? "present" : "missing"}\n${value.connections.map((connection) => `${connection.name}: ${connection.provider} (${connection.apiKeyEnv})\n`).join("")}`);
@@ -106,7 +114,12 @@ async function handleCommsAdd(io, name, options, command) {
     io.setExitCode(result.ok ? 0 : 2);
 }
 async function handleCommsCheck(io, options, command) {
-    if (!(await applyEnvFileOption({ command, cwd: options.cwd, envFile: options.envFile, io })))
+    if (!(await applyEnvFileOption({
+        command,
+        cwd: options.cwd,
+        envFile: dotenvPathOf(options, command, io),
+        io,
+    })))
         return;
     let connection = options.connection;
     const study = options.study;
@@ -150,7 +163,12 @@ async function handleCommsConfigure(io, options, command) {
     io.setExitCode(result.ok ? 0 : 2);
 }
 async function handleCommsRecover(io, options, command) {
-    if (!(await applyEnvFileOption({ command, cwd: options.cwd, envFile: options.envFile, io })))
+    if (!(await applyEnvFileOption({
+        command,
+        cwd: options.cwd,
+        envFile: dotenvPathOf(options, command, io),
+        io,
+    })))
         return;
     const cwd = resolve(options.cwd);
     try {

package/dist/cli/commands/observe.js

@@ -352,8 +352,10 @@ function hiddenRunLines(groups) {
         const reasons = group.reasons.length > 0 ? ` (${group.reasons.join(", ")})` : "";
         lines.push(`  ${runs(group.runs)} ${group.status}${reasons}`);
     }
-    if (groups.some((group) => group.reasons.join(",") === "RAW_SCREENSHOTS"))
-        lines.push("share: a run held back only for RAW_SCREENSHOTS can be copied with blurred screenshots: `humanish export --run <id> --format bundle --redact-screenshots --out <dir>`, then `humanish observe --all --safe --cwd <dir>`");
+    // Export clears both: it blurs screenshots and writes no raw sandbox id.
+    const exportable = new Set(["RAW_SCREENSHOTS", "RAW_SANDBOX_ID"]);
+    if (groups.some((group) => group.reasons.length > 0 && group.reasons.every((reason) => exportable.has(reason))))
+        lines.push("share: a run held back only for RAW_SCREENSHOTS or RAW_SANDBOX_ID can be copied with blurred screenshots and no sandbox ids: `humanish export --run <id> --format bundle --redact-screenshots --out <dir>`, then `humanish observe --all --safe --cwd <dir>`");
     lines.push("why: `humanish verify --run <id>` explains each reason");
     return lines;
 }

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

@@ -1,6 +1,6 @@
 import { runDryRun } from "../../run/dry-run.js";
 import { runStudyCommand } from "./study-run.js";
-import { applyEnvFileOption, CWD_OPTION_DESCRIPTION, ENV_FILE_OPTION_DESCRIPTION, formatRunHuman, freePortOption, JSON_OPTION_DESCRIPTION, parsePositiveInteger, writeResult, } from "../io.js";
+import { applyEnvFileOption, CWD_OPTION_DESCRIPTION, DOTENV_OPTION_DESCRIPTION, dotenvPathOf, envFileAliasOption, formatRunHuman, freePortOption, JSON_OPTION_DESCRIPTION, parsePositiveInteger, writeResult, } from "../io.js";
 /** The flags a run takes, whichever command starts it. */
 export function addRunOptions(command) {
     return command
@@ -14,7 +14,8 @@ export function addRunOptions(command) {
         .option("--participants <ids>", "With --rerun-failed-from: comma-separated ids of the participants to rerun. The study's participants decide who takes part; ids are their id, or lane-01, lane-02, … by position.")
         .option("--scorer <path>", "Score with this .mjs module, a path inside the repo, in place of review.scorer.ref. It runs as code, so review it first. Terminal, computer-use and shared-world studies only.")
         .option("--cwd <path>", CWD_OPTION_DESCRIPTION, ".")
-        .option("--env-file <path>", ENV_FILE_OPTION_DESCRIPTION)
+        .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("--json", JSON_OPTION_DESCRIPTION);
 }
@@ -52,7 +53,7 @@ export async function handleRun(io, named, options, command) {
     const loaded = await applyEnvFileOption({
         command,
         cwd: options.cwd,
-        envFile: options.envFile,
+        envFile: dotenvPathOf(options, command, io),
         io,
         // runStudyCommand discovers keys for a live study; a preview without a study needs none.
         discoverKeys: false,

package/dist/cli/commands/run-signals.d.ts

@@ -11,6 +11,8 @@ export interface RunSignalOptions {
     exit?: (code: number) => void;
     reclaim?: ReclaimHooks;
     deadlineMs?: number;
+    /** Resolves when the deadline has passed; defaults to a timer of `deadlineMs`. */
+    deadline?: (ms: number) => Promise<void>;
 }
 /**
  * Register work a committed shutdown finishes before it exits, such as closing watch's Observer