humanish 0.109.0 → 0.110.0

package/CHANGELOG.md

@@ -8,6 +8,26 @@ The Unreleased section holds the full notes for the next version until it is tag
 
 ## Unreleased
 
+## 0.110.0: --dotenv, and sandbox ids only in receipts (2026-10-03)
+
+humanish 0.110.0 renames `--env-file` to `--dotenv`, so a missing file reaches humanish's exit 2
+result where Node exited 9 first. `--env-file` stays as a hidden alias until 0.111.0. Raw sandbox
+ids live only in a run's `sandbox-receipts.ndjson`: every other record, output and export copy names
+a sandbox as `[redacted-sandbox-id]` with a digest, and `humanish verify` grades a run that still
+holds a raw id `local_only` with `RAW_SANDBOX_ID`. The release notes list each changed field and
+what to read instead.
+
+[Release notes](https://github.com/danielgwilson/humanish/releases/tag/v0.110.0)
+
+## 0.109.1: Current option names in messages, reclaim --env-file (2026-10-03)
+
+humanish 0.109.1 is a patch. Library refusals and warnings name `RunStudyOptions`, which 0.109.0
+exports, where they named the removed `RunLabOptions`. `humanish export --format bundle` no longer
+copies sandbox ids into its redacted workspace. `humanish reclaim` takes `--env-file`, and
+`humanish migrate` removes a `labs/` directory that its moves emptied.
+
+[Release notes](https://github.com/danielgwilson/humanish/releases/tag/v0.109.1)
+
 ## 0.109.0: Lab names removed, v2 study files refused (2026-10-03)
 
 humanish 0.109.0 removes what 0.108.0 deprecated. A `humanish.lab.v2` file, or any study file in a

package/README.md

@@ -285,7 +285,7 @@ why. A hosted participant on a release humanish has not tested records a warning
 the first of these sources that has it. It prints the name and source of a key it
 fills from sources 2 to 4, never the value:
 
-1. the process environment, including a file passed with `--env-file`;
+1. the process environment, including a file passed with `--dotenv`;
 2. `.humanish/local/provider.env`;
 3. the vendor's own store: `~/.e2b/config.json` for `E2B_API_KEY`, and
    `gh auth token` for `GH_TOKEN`;

package/dist/analysis/automatic-config.d.ts

@@ -7,7 +7,7 @@ interface StudyAnalysisSettings {
     question?: string;
     timeoutMs?: number;
 }
-/** The study's review.analysis: a provider selection for a separate review after a live study. */
+/** The study's review.analysis: a provider selection for a separate review after a live run. */
 export type StudyAnalysis = StudyAnalysisSettings & ({
     provider?: "openai";
     maxCostUsd: number;

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/migrate.js

@@ -4,8 +4,11 @@ function formatValue(value) {
     const text = JSON.stringify(value);
     return text.length > 80 ? `${text.slice(0, 77)}...` : text;
 }
-/** Each file's source, destination, moved keys and dropped keys, printed before any write. */
-function formatMigratePlan(files) {
+/**
+ * Each file's source, destination, moved keys and dropped keys, and each labs/ directory the moves
+ * empty, printed before any write.
+ */
+function formatMigratePlan(files, emptied) {
     const lines = [];
     for (const file of files) {
         if (file.action === "skip") {
@@ -22,6 +25,9 @@ function formatMigratePlan(files) {
                 lines.push(`    its comment: ${key.comments.replace(/\n/g, " ")}`);
         }
     }
+    for (const directory of emptied) {
+        lines.push(`${directory}/: removed after the move, since nothing else is in it`);
+    }
     return lines.length > 0 ? `${lines.join("\n")}\n` : "No study files to convert.\n";
 }
 function formatMigrateOutcome(result) {
@@ -33,7 +39,12 @@ function formatMigrateOutcome(result) {
     const files = written === 1 ? "1 study file" : `${written} study files`;
     if (result.dryRun)
         return `Dry run: nothing was written. ${files} would change.\n`;
-    return written === 0 ? "No v2 study files to convert.\n" : `Converted ${files}.\n`;
+    if (written === 0)
+        return "No v2 study files to convert.\n";
+    const removed = result.removedDirectories ?? [];
+    return removed.length === 0
+        ? `Converted ${files}.\n`
+        : `Converted ${files}. Removed ${removed.map((directory) => `${directory}/`).join(", ")}, which the move emptied.\n`;
 }
 /** `humanish migrate`. */
 export function registerMigrateCommand(parent, io) {
@@ -57,7 +68,7 @@ export function registerMigrateCommand(parent, io) {
             dryRun: options.dryRun === true,
             // The plan is printed before anything is written; with --json it goes to stderr, so stdout
             // stays one JSON document.
-            onPlan: (files) => (json ? io.writeErr : io.writeOut)(formatMigratePlan(files)),
+            onPlan: (files, emptied) => (json ? io.writeErr : io.writeOut)(formatMigratePlan(files, emptied)),
         });
         writeResult(command, io, result, formatMigrateOutcome);
         io.setExitCode(result.ok ? 0 : 2);

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/runs.js

@@ -7,7 +7,7 @@ import { cleanupRun, listRuns, readReview } from "../../run/stored-runs.js";
 import { verifyRun } from "../../verify/verify.js";
 import { reclaimPreflightSandboxes, reclaimRunSandboxes, } from "../../run/reclaim.js";
 import { addRunOptions, handleRun } from "./run-command.js";
-import { CWD_OPTION_DESCRIPTION, JSON_OPTION_DESCRIPTION, RUN_OPTION_DESCRIPTION, writeResult, humanError, } from "../io.js";
+import { applyEnvFileOption, CWD_OPTION_DESCRIPTION, DOTENV_OPTION_DESCRIPTION, dotenvPathOf, envFileAliasOption, JSON_OPTION_DESCRIPTION, RUN_OPTION_DESCRIPTION, writeResult, humanError, } from "../io.js";
 import { plural } from "../../run/text.js";
 export function registerRunCommand(parent, io) {
     addRunOptions(parent
@@ -165,13 +165,23 @@ export function registerRuntimeCommands(parent, io) {
 export function registerReclaimCommand(parent, io) {
     parent
         .command("reclaim")
-        .description("Kill an interrupted run's sandboxes by the exact ids journaled in its sandbox-receipts.ndjson; never enumerates the E2B account. Needs E2B_API_KEY in the environment.")
+        .description("Kill an interrupted run's sandboxes by the exact ids journaled in its sandbox-receipts.ndjson; never enumerates the E2B account. Needs E2B_API_KEY in the environment or in --dotenv.")
         .summary("Stop an interrupted run's leftover sandboxes.")
         .option("--cwd <path>", CWD_OPTION_DESCRIPTION, ".")
         .option("--run <id>", RUN_OPTION_DESCRIPTION, "latest")
         .addOption(new Option("--preflight", "Reclaim sandboxes left by interrupted `humanish study check` probes (journaled in .humanish/preflight) instead of a run's.").conflicts("run"))
+        .option("--dotenv <path>", DOTENV_OPTION_DESCRIPTION)
+        .addOption(envFileAliasOption())
         .option("--json", JSON_OPTION_DESCRIPTION)
         .action(async (options, command) => {
+        // The kill calls read E2B_API_KEY from the environment: the env file, then discovered keys.
+        if (!(await applyEnvFileOption({
+            command,
+            cwd: options.cwd,
+            envFile: dotenvPathOf(options, command, io),
+            io,
+        })))
+            return;
         const result = options.preflight
             ? await reclaimPreflightSandboxes(options.cwd)
             : await reclaimRunSandboxes(options.cwd, options.run);
@@ -183,7 +193,7 @@ function formatReclaimHuman(result) {
     const lines = [];
     lines.push(`Reclaim ${result.runId}: ${result.ok ? "ok" : "failed"}, ${plural(result.receiptCount, "sandbox receipt")}.`);
     for (const outcome of result.outcomes) {
-        lines.push(`  ${outcome.sandboxId} (${outcome.laneId}): ${outcome.state}${outcome.detail ? ` — ${outcome.detail}` : ""}`);
+        lines.push(`  sandbox ${outcome.sandboxIdDigest} (${outcome.laneId}): ${outcome.state}${outcome.detail ? ` — ${outcome.detail}` : ""}`);
     }
     for (const warning of result.warnings)
         lines.push(`  warning: ${warning}`);

package/dist/cli/commands/setup.js

@@ -4,7 +4,7 @@ import { promptSecret } from "../secret-prompt.js";
 import { runInit } from "../../study/init.js";
 import { buildPayload, disabledByEnvironment, readTelemetryState, telemetryStatePath, writeTelemetryState, } from "../telemetry.js";
 import { doctor } from "../doctor.js";
-import { applyEnvFileOption, CLI_VERSION, CWD_OPTION_DESCRIPTION, ENV_FILE_OPTION_DESCRIPTION, JSON_OPTION_DESCRIPTION, markInvocationEnvelopeWritten, wantsJson, writeResult, formatCliError, } from "../io.js";
+import { applyEnvFileOption, CLI_VERSION, CWD_OPTION_DESCRIPTION, DOTENV_OPTION_DESCRIPTION, dotenvPathOf, envFileAliasOption, JSON_OPTION_DESCRIPTION, markInvocationEnvelopeWritten, wantsJson, writeResult, formatCliError, } from "../io.js";
 import { plural } from "../../run/text.js";
 export function registerInitCommand(parent, io) {
     parent
@@ -51,13 +51,27 @@ export function registerDoctorCommand(parent, io) {
         .summary("Check what this project and machine need for a run.")
         .option("--cwd <path>", CWD_OPTION_DESCRIPTION, ".")
         .option("--study <study>", "Check the study's desktop, participant authentication and separate analysis requirements; no provider calls.")
-        .option("--env-file <path>", ENV_FILE_OPTION_DESCRIPTION)
+        .option("--dotenv <path>", DOTENV_OPTION_DESCRIPTION)
+        .addOption(envFileAliasOption())
         .option("--json", JSON_OPTION_DESCRIPTION)
         .action(async (options, command) => {
-        if (options.envFile &&
-            !(await applyEnvFileOption({ command, cwd: options.cwd, envFile: options.envFile, io })))
+        const dotenv = dotenvPathOf(options, command, io);
+        let loaded;
+        if (dotenv &&
+            !(await applyEnvFileOption({
+                command,
+                cwd: options.cwd,
+                envFile: dotenv,
+                io,
+                onLoaded: (load) => {
+                    loaded = load;
+                },
+            })))
             return;
-        const result = await doctor(options.cwd, options.study ? { study: options.study } : {});
+        const result = await doctor(options.cwd, {
+            ...(options.study ? { study: options.study } : {}),
+            ...(loaded === undefined ? {} : { dotenv: loaded }),
+        });
         writeResult(command, io, result, formatDoctorHuman);
         // Behavioral change: was exit 1, every other structured command uses 2.
         io.setExitCode(result.ok ? 0 : 2);

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

@@ -15,6 +15,21 @@ function withError(error, lines) {
     const stdout = `${lines.join("\n")}\n`;
     return error === undefined ? stdout : { stdout, error };
 }
+/** How a summary names a sandbox: by digest. The raw id is only in the run's receipts. */
+function sandboxName(sandbox) {
+    return sandbox.sandboxIdDigest !== undefined
+        ? `[redacted-sandbox-id ${sandbox.sandboxIdDigest}]`
+        : sandbox.sandboxId;
+}
+/**
+ * One line per run naming the file that holds its raw sandbox ids, for the operator, when the
+ * result names a sandbox at all (each one carries a digest).
+ */
+function sandboxIdsLine(result) {
+    return result.runId && JSON.stringify(result).includes('"sandboxIdDigest"')
+        ? [`sandbox ids: .humanish/runs/${result.runId}/sandbox-receipts.ndjson`]
+        : [];
+}
 /** A participant's status in words: a dry run's placeholder status says that nothing ran live. */
 function participantStatus(status) {
     return status === "contract_proof_only" ? "dry run, nothing ran live" : status;
@@ -37,9 +52,10 @@ export function formatConcurrentSharedWorldStudyHuman(result) {
         ...result.roles.map((participant) => `persona ${participant.id} (${participant.persona}): ${participantStatus(participant.status)}${participant.session ? ` (${participant.session.completionReason})` : ""}${participant.ok ? "" : ", not ok"}`),
         ...(result.subjectSandbox
             ? [
-                `subject sandbox: ${result.subjectSandbox.sandboxId} killed=${result.subjectSandbox.killed ? "yes" : "no"}`,
+                `subject sandbox: ${sandboxName(result.subjectSandbox)} killed=${result.subjectSandbox.killed ? "yes" : "no"}`,
             ]
             : []),
+        ...sandboxIdsLine(result),
         ...(result.observer?.observerPath ? [`observer: ${result.observer.observerPath}`] : []),
         ...(result.observer?.opened === undefined
             ? []
@@ -53,6 +69,10 @@ export function formatTerminalStudyHuman(result) {
         `run: ${result.runId}`,
         `actor: ${result.actor}`,
         `product: ${result.product}`,
+        ...(result.sandbox
+            ? [`sandbox: ${sandboxName(result.sandbox)} killed=${result.sandbox.killed ? "yes" : "no"}`]
+            : []),
+        ...sandboxIdsLine(result),
         ...(result.observer?.observerPath ? [`observer: ${result.observer.observerPath}`] : []),
         ...(result.observer?.opened === undefined
             ? []
@@ -72,6 +92,12 @@ export function formatScriptedStudyHuman(result) {
             ]
             : []),
         ...result.sessions.map((session) => `session ${session.surface}: ${session.status} (${session.completionReason}) · ${session.reason} [${session.screenshots} screenshot${session.screenshots === 1 ? "" : "s"}]`),
+        ...(result.subjectSandbox
+            ? [
+                `subject sandbox: ${sandboxName(result.subjectSandbox)} killed=${result.subjectSandbox.killed ? "yes" : "no"}`,
+            ]
+            : []),
+        ...sandboxIdsLine(result),
         ...(result.observer?.observerPath ? [`observer: ${result.observer.observerPath}`] : []),
         ...(result.observer?.opened === undefined
             ? []
@@ -105,9 +131,10 @@ export function formatCuaStudyHuman(result) {
             : []),
         ...(result.sandbox
             ? [
-                `sandbox: ${result.sandbox.sandboxId} stream=${result.sandbox.streamUrlPresent ? "connected" : "missing"} killed=${result.sandbox.killed ? "yes" : "no"}`,
+                `sandbox: ${sandboxName(result.sandbox)} stream=${result.sandbox.streamUrlPresent ? "connected" : "missing"} killed=${result.sandbox.killed ? "yes" : "no"}`,
             ]
             : []),
+        ...sandboxIdsLine(result),
         ...(result.observer?.observerPath ? [`observer: ${result.observer.observerPath}`] : []),
         ...(result.observer?.opened === undefined
             ? []

package/dist/cli/commands/study.js

@@ -3,7 +3,7 @@ import { resolve } from "node:path";
 import { Command, Option } from "commander";
 import { inspectStudyManifest, listStudyManifests } from "../../study/discover.js";
 import { runStudyPreflight, } from "../../study/preflight.js";
-import { applyEnvFileOption, CWD_OPTION_DESCRIPTION, ENV_FILE_OPTION_DESCRIPTION, JSON_OPTION_DESCRIPTION, parsePositiveInteger, writeResult, humanError, } from "../io.js";
+import { applyEnvFileOption, CWD_OPTION_DESCRIPTION, DOTENV_OPTION_DESCRIPTION, dotenvPathOf, envFileAliasOption, JSON_OPTION_DESCRIPTION, parsePositiveInteger, writeResult, humanError, } from "../io.js";
 export function registerStudyCommands(parent, io) {
     const study = parent
         .command("study")
@@ -36,7 +36,8 @@ function checkCommand(command, io) {
         .choices(["metadata", "public-preview", "sandbox-loopback", "prepared-host"])
         .default("metadata"))
         .option("--timeout-ms <ms>", "Target reachability timeout.", String(30_000))
-        .option("--env-file <path>", ENV_FILE_OPTION_DESCRIPTION)
+        .option("--dotenv <path>", DOTENV_OPTION_DESCRIPTION)
+        .addOption(envFileAliasOption())
         .option("--json", JSON_OPTION_DESCRIPTION)
         .action((name, options, command) => handleStudyCheck(io, name, options, command));
 }
@@ -54,7 +55,7 @@ async function handleStudyCheck(io, name, options, command) {
     if (!(await applyEnvFileOption({
         command,
         cwd: options.cwd,
-        envFile: options.envFile,
+        envFile: dotenvPathOf(options, command, io),
         io,
     }))) {
         return;

package/dist/cli/commands/tui.js

@@ -19,7 +19,7 @@ import { readRunDetail } from "../../run/detail.js";
 import { launchRun, readLaunchLogTail } from "../../tui/launch.js";
 import { TUI_MIN_NODE_MAJOR, nodeSupportsTui, TUI_BUNDLE_URL, } from "../../tui/contract.js";
 import { detectAgentSession } from "../../actors/agent-session.js";
-import { applyEnvFileOption, CLI_VERSION, CWD_OPTION_DESCRIPTION, ENV_FILE_OPTION_DESCRIPTION, JSON_OPTION_DESCRIPTION, markInvocationEnvelopeWritten, wantsJson, } from "../io.js";
+import { applyEnvFileOption, CLI_VERSION, CWD_OPTION_DESCRIPTION, DOTENV_OPTION_DESCRIPTION, dotenvPathOf, envFileAliasOption, JSON_OPTION_DESCRIPTION, markInvocationEnvelopeWritten, wantsJson, } from "../io.js";
 export const defaultTuiRuntime = {
     checkComms: checkCommsConnection,
     promptSecret,
@@ -59,7 +59,8 @@ export function registerTuiCommand(parent, io, runtime = defaultTuiRuntime) {
         .description("Browse studies and runs in an interactive terminal UI. It refuses detected agent sessions and non-TTY input or output; agents use humanish study list --json, humanish study show <study> --json and humanish runs --json.")
         .summary("Browse studies and runs in a terminal UI for people.")
         .option("--cwd <path>", CWD_OPTION_DESCRIPTION, ".")
-        .option("--env-file <path>", ENV_FILE_OPTION_DESCRIPTION)
+        .option("--dotenv <path>", DOTENV_OPTION_DESCRIPTION)
+        .addOption(envFileAliasOption())
         .option("--force", "Open it anyway in a session that looks like an agent's.")
         .option("--json", JSON_OPTION_DESCRIPTION)
         .action((options, command) => handleTui(io, runtime, options, command));
@@ -89,7 +90,7 @@ async function handleTui(io, runtime, options, command) {
     if (!(await applyEnvFileOption({
         command,
         cwd: options.cwd,
-        envFile: options.envFile,
+        envFile: dotenvPathOf(options, command, io),
         io,
         env: runtime.env,
         onDiscovered: (names) => names.forEach((name) => discoveredKeys.add(name)),

package/dist/cli/commands/watch.js

@@ -4,7 +4,7 @@ import { WATCH_SAFE_NOT_APPLICABLE_MESSAGE } from "../../observer/exposure.js";
 import { runDryRun } from "../../run/dry-run.js";
 import { runStudyCommand } from "./study-run.js";
 import { addRunOptions, studyOnlyFlags } from "./run-command.js";
-import { applyEnvFileOption, collectRepeated, formatRunHuman, parseObserverPort, parsePositiveInteger, wantsJson, writeResult, } from "../io.js";
+import { applyEnvFileOption, collectRepeated, dotenvPathOf, formatRunHuman, parseObserverPort, parsePositiveInteger, wantsJson, writeResult, } from "../io.js";
 import { followObserver, formatObserverHuman, watchExposeRequested } from "../observer-follow.js";
 export function registerWatchCommand(parent, io) {
     // A run's flags come from addRunOptions, the helper `run` uses, so the two cannot drift.
@@ -59,7 +59,7 @@ async function handleWatch(io, named, parsed, command) {
     if (!(await applyEnvFileOption({
         command,
         cwd: options.cwd,
-        envFile: options.envFile,
+        envFile: dotenvPathOf(options, command, io),
         io,
         // runStudyCommand discovers keys for a live study; a preview run needs none.
         discoverKeys: false,

package/dist/cli/doctor.d.ts

@@ -1,4 +1,4 @@
-import { type KeyResolutionDeps } from "../keys/key-resolution.js";
+import { type KeyResolutionDeps, type DotenvLoad } from "../keys/key-resolution.js";
 import { type DetectLocalAgentsOptions } from "../actors/local-agent/cli.js";
 import { type StudySetupCheckArgs } from "../study/doctor.js";
 declare const DOCTOR_SCHEMA = "humanish.doctor-result.v1";
@@ -48,5 +48,7 @@ export declare function doctor(cwdInput: string, options?: {
     keyDeps?: KeyResolutionDeps;
     /** The hosted Codex participant's operator handshake; tests replace it. */
     codexParticipantReadiness?: StudySetupCheckArgs["codexParticipantReadiness"];
+    /** What `--dotenv` loaded, so a key row names the file that supplied it. */
+    dotenv?: DotenvLoad;
 }): Promise<DoctorResult>;
 export {};

package/dist/cli/doctor.js

@@ -65,7 +65,7 @@ export async function doctor(cwdInput, options = {}) {
     }
     const env = options.env ?? process.env;
     const agents = await detectLocalAgents({ ...options.localAgents, env });
-    const { probes, receivingKey } = await probeDoctorKeys(cwd, env, options.study, options.keyDeps);
+    const { probes, receivingKey } = await probeDoctorKeys(cwd, env, options.study, options.keyDeps, options.dotenv);
     const keyPresent = (name) => probes.some((probe) => probe.name === name && probe.source !== null);
     const setup = options.study
         ? await studySetupChecks({
@@ -237,7 +237,7 @@ function terminalSurfaceCheck() {
     };
 }
 /** Probes the live-run keys, plus the receiving-email key a real-comms study names. */
-async function probeDoctorKeys(cwd, env, study, keyDeps) {
+async function probeDoctorKeys(cwd, env, study, keyDeps, dotenv) {
     const keyNames = new Set(["OPENAI_API_KEY", "E2B_API_KEY", "GH_TOKEN", "CODEX_API_KEY"]);
     let receivingKey = null;
     if (study) {
@@ -254,6 +254,7 @@ async function probeDoctorKeys(cwd, env, study, keyDeps) {
         cwd,
         env,
         ...(keyDeps === undefined ? {} : { deps: keyDeps }),
+        ...(dotenv === undefined ? {} : { dotenv }),
     });
     return { probes, receivingKey };
 }
@@ -281,7 +282,7 @@ function studyList(studies) {
 }
 /**
  * Provider-key discovery: which source supplies each live-run key, through the same
- * chain a live command resolves (env/--env-file, project overlay, vendor stores, the
+ * chain a live command resolves (env/--dotenv, project overlay, vendor stores, the
  * humanish user store). Values never appear; sources and fill commands do.
  *
  * With --study, a key the selected route requires fails when missing. Without it, `keyUsers` maps
@@ -292,7 +293,7 @@ function keyChecks(probes, receivingKey, setup, keyUsers) {
     return probes.map((probe) => {
         const present = probe.source !== null;
         const hint = probe.name === receivingKey
-            ? `provide ${probe.name} through process env or --env-file`
+            ? `provide ${probe.name} through process env or --dotenv`
             : probe.hint;
         if (!setup) {
             const users = keyUsers?.get(probe.name) ?? [];

package/dist/cli/io.d.ts

@@ -1,5 +1,5 @@
 import { Command, Option } from "commander";
-import { discoverProviderKeys } from "../keys/key-resolution.js";
+import { discoverProviderKeys, type DotenvLoad } from "../keys/key-resolution.js";
 import { type TelemetryProperties } from "./telemetry.js";
 import type { RunResult } from "../run/results.js";
 export declare const CLI_RESPONSE_SCHEMA = "humanish.cli-response.v1";
@@ -13,7 +13,18 @@ export interface CliIo {
 export declare const JSON_OPTION_DESCRIPTION = "Print a machine-readable JSON response.";
 export declare const CWD_OPTION_DESCRIPTION = "Project directory.";
 export declare const RUN_OPTION_DESCRIPTION = "Run id, or latest.";
-export declare const ENV_FILE_OPTION_DESCRIPTION = "Load unset variables from this env file. Values are never printed or saved.";
+export declare const DOTENV_OPTION_DESCRIPTION = "Load unset variables from this dotenv file. Values are never printed or saved.";
+/**
+ * The hidden `--env-file <path>` that `--dotenv` replaced. Node scans the whole argv for
+ * `--env-file` before a script runs, and stops only at `--` (src/node_dotenv.cc), so a missing file
+ * exits 9 through Node and never reaches humanish. `--dotenv` does not collide. Removed in 0.111.0.
+ */
+export declare function envFileAliasOption(): Option;
+/** The dotenv path a command was given: `--dotenv`, or the `--env-file` alias with its warning. */
+export declare function dotenvPathOf(options: {
+    dotenv?: string | undefined;
+    envFile?: string | undefined;
+}, command: Command, io: CliIo): string | undefined;
 export declare const PORT_OPTION_DESCRIPTION = "Port to listen on at 127.0.0.1.";
 /** `--port` for a loopback server whose default, 0, lets the OS pick a free port. */
 export declare function freePortOption(): Option;
@@ -22,6 +33,7 @@ export interface StudyCommandOptions {
     cwd: string;
     detach?: boolean | undefined;
     dryRun?: boolean | undefined;
+    dotenv?: string | undefined;
     envFile?: string | undefined;
     json?: boolean | undefined;
     open?: boolean | undefined;
@@ -50,13 +62,15 @@ export declare function applyEnvFileOption(args: {
     io: CliIo;
     env?: NodeJS.ProcessEnv;
     onDiscovered?: (names: string[]) => void;
+    /** Called with the dotenv path and the names it set, which were unset before. */
+    onLoaded?: (load: DotenvLoad) => void;
     /** False for the study-running commands, which discover only once the study resolves to live. */
     discoverKeys?: boolean;
 }): Promise<boolean>;
 /**
  * Provider-key discovery: fill still-missing keys from the documented project overlay, the
  * owning vendors' native stores, and the humanish user store. It is fill-only (an explicit
- * --env-file or process env always wins), and each fill is announced by name and source on
+ * --dotenv or process env always wins), and each fill is announced by name and source on
  * stderr, never by value. HUMANISH_STRICT_KEYS=1 restores env-only behavior.
  */
 export declare function discoverCliKeys(args: {

package/dist/cli/io.js

@@ -7,7 +7,7 @@ import { Command, Option } from "commander";
 import { loadEnvFile } from "../keys/env-file.js";
 import { discoverProviderKeys } from "../keys/key-resolution.js";
 import { deriveRunFacts } from "./telemetry.js";
-import { withQueuedWarnings } from "./deprecations.js";
+import { warnAndQueue, withQueuedWarnings } from "./deprecations.js";
 import { forTerminal } from "../routes/terminal/encoding.js";
 export const CLI_RESPONSE_SCHEMA = "humanish.cli-response.v1";
 function readCliVersion() {
@@ -23,7 +23,23 @@ export const CLI_VERSION = readCliVersion();
 export const JSON_OPTION_DESCRIPTION = "Print a machine-readable JSON response.";
 export const CWD_OPTION_DESCRIPTION = "Project directory.";
 export const RUN_OPTION_DESCRIPTION = "Run id, or latest.";
-export const ENV_FILE_OPTION_DESCRIPTION = "Load unset variables from this env file. Values are never printed or saved.";
+export const DOTENV_OPTION_DESCRIPTION = "Load unset variables from this dotenv file. Values are never printed or saved.";
+const ENV_FILE_RENAMED = "`--env-file` is now `--dotenv`; `--env-file` is removed in 0.111.0.";
+/**
+ * The hidden `--env-file <path>` that `--dotenv` replaced. Node scans the whole argv for
+ * `--env-file` before a script runs, and stops only at `--` (src/node_dotenv.cc), so a missing file
+ * exits 9 through Node and never reaches humanish. `--dotenv` does not collide. Removed in 0.111.0.
+ */
+export function envFileAliasOption() {
+    return new Option("--env-file <path>").hideHelp().conflicts("dotenv");
+}
+/** The dotenv path a command was given: `--dotenv`, or the `--env-file` alias with its warning. */
+export function dotenvPathOf(options, command, io) {
+    if (options.envFile === undefined)
+        return options.dotenv;
+    warnAndQueue(command, io, ENV_FILE_RENAMED);
+    return options.envFile;
+}
 export const PORT_OPTION_DESCRIPTION = "Port to listen on at 127.0.0.1.";
 /** `--port` for a loopback server whose default, 0, lets the OS pick a free port. */
 export function freePortOption() {
@@ -74,6 +90,7 @@ export async function applyEnvFileOption(args) {
         }
         for (const name of result.loaded)
             env[name] = stagedEnv[name];
+        args.onLoaded?.({ path: args.envFile, names: result.loaded });
     }
     if (args.discoverKeys !== false) {
         await discoverCliKeys({
@@ -88,7 +105,7 @@ export async function applyEnvFileOption(args) {
 /**
  * Provider-key discovery: fill still-missing keys from the documented project overlay, the
  * owning vendors' native stores, and the humanish user store. It is fill-only (an explicit
- * --env-file or process env always wins), and each fill is announced by name and source on
+ * --dotenv or process env always wins), and each fill is announced by name and source on
  * stderr, never by value. HUMANISH_STRICT_KEYS=1 restores env-only behavior.
  */
 export async function discoverCliKeys(args) {

package/dist/comms/receiving-runtime.js

@@ -29,7 +29,7 @@ export async function resolveReceivingConnection(cwd, name, env, keyDeps) {
     });
     const apiKey = resolved[connection.apiKeyEnv]?.trim();
     if (!apiKey)
-        throw new Error("Email connection credential is missing. Add it in Connections, or provide the configured key with --env-file.");
+        throw new Error("Email connection credential is missing. Add it in Connections, or provide the configured key with --dotenv.");
     return { connection, apiKey, adapter: createReceivingAdapter(connection, apiKey) };
 }
 export async function prepareReceivingRun(args) {

package/dist/comms/setup.js

@@ -53,7 +53,7 @@ export async function checkCommsConnection(args) {
                 ...base,
                 ready: false,
                 code: "credential_missing",
-                message: "The configured credential is missing. Add it in Connections or provide it with --env-file.",
+                message: "The configured credential is missing. Add it in Connections or provide it with --dotenv.",
             };
         base.credentialPresent = true;
         if (!args.online)