humanish 0.109.1 → 0.110.1

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

@@ -1,20 +1,27 @@
 // The run command's signal handling outside post-run analysis. The first interrupt, terminate or
-// hangup signal marks each unfinished run in this process interrupted, kills the E2B sandboxes
-// its create-time receipts name, runs the registered shutdown cleanups (watch's Observer server
-// and tunnel) and exits 128+n, all within one deadline; a second signal exits at once. Routes
-// take no abort signal, so the bundle is not finished, but the record ends at once and no
-// journaled sandbox waits for its timeout. Analysis has its own cancel handlers
+// hangup signal prints one line saying humanish is stopping, refuses any further sandbox create,
+// marks each unfinished run in this process interrupted, reclaims its sandboxes (by receipt, by
+// the ids its in-flight creates report, and by its E2B tags), runs the registered shutdown
+// cleanups (watch's Observer server and tunnel) and exits 128+n, all within one deadline. A
+// second signal prints the reclaim command for each run not yet reclaimed and exits at once.
+// Routes take no abort signal, so the bundle is not finished, but the record ends at once and no
+// sandbox the run created waits for its timeout. Analysis has its own cancel handlers
 // (analysis-signals.ts) and takes over when it starts.
 import path from "node:path";
 import { activeRuns } from "../../run/active-runs.js";
 import { LATEST_RUN_ALIAS } from "../../run/locate.js";
 import { reclaimPinnedRunSandboxes, } from "../../run/reclaim.js";
+import { stopSandboxCreates } from "../../run/sandbox-creates.js";
 import { SANDBOX_RECEIPTS_ARTIFACT } from "../../run/sandbox-receipts.js";
+import { plural } from "../../run/text.js";
+import { shellArg } from "../../substrates/shell.js";
 import { exitCodeForSignal } from "../observer-follow.js";
 /** How long the handler waits for interrupt, reclaim and cleanups before it exits anyway. */
 const INTERRUPT_RECLAIM_DEADLINE_MS = 10_000;
-/** Each kill's own request timeout, inside the deadline. */
+/** Each kill's own request timeout, inside the deadline. Kills run concurrently. */
 const KILL_REQUEST_TIMEOUT_MS = 8_000;
+/** How long reclaim waits for in-flight creates before it searches E2B by tag anyway. */
+const CREATES_WAIT_MS = 6_000;
 const SIGNALS = ["SIGINT", "SIGTERM", "SIGHUP"];
 let current;
 const shutdownCleanups = new Set();
@@ -39,7 +46,7 @@ export function beginRunSignalPhase(io, options = {}) {
             process.exit(code);
         });
     const handlers = new Map();
-    let stopping = false;
+    let stopping;
     const end = () => {
         for (const [signal, handler] of handlers)
             target.removeListener(signal, handler);
@@ -48,16 +55,23 @@ export function beginRunSignalPhase(io, options = {}) {
             current = undefined;
     };
     const release = () => {
-        if (!stopping)
+        if (stopping === undefined)
             end();
     };
     const onSignal = (signal) => {
-        if (stopping) {
+        if (stopping !== undefined) {
+            const open = stopping.filter((stop) => stop.report !== null && stop.report?.clean !== true);
+            for (const stop of open)
+                say(io, `humanish: second ${signal}: exiting before run ${stop.run.runId}'s sandboxes were confirmed stopped; ${recovery(stop.run)} to stop what is left.`);
+            if (open.length === 0)
+                say(io, `humanish: second ${signal}: exiting.`);
             exit(exitCodeForSignal(signal));
             return;
         }
-        stopping = true;
-        void stopActiveRuns(io, signal, options)
+        // Synchronous, before anything is awaited: no create can start after this point.
+        stopping = activeRuns().map((run) => ({ run, creates: stopSandboxCreates(run.paths) }));
+        say(io, stoppingLine(signal, stopping, options.deadlineMs ?? INTERRUPT_RECLAIM_DEADLINE_MS));
+        void stopActiveRuns(io, signal, stopping, options)
             .catch(() => undefined)
             .finally(() => exit(exitCodeForSignal(signal)));
     };
@@ -74,48 +88,65 @@ export function beginRunSignalPhase(io, options = {}) {
 export function handOverRunSignals() {
     current?.release();
 }
+function say(io, line) {
+    try {
+        io.writeErr(`${line}\n`);
+    }
+    catch {
+        // A hung-up terminal cannot take the line; the status record and reclaim receipt hold it.
+    }
+}
+function stoppingLine(signal, stopping, deadlineMs) {
+    const again = `a second ${signal} exits without waiting`;
+    if (stopping.length === 0)
+        return `humanish: ${signal}: stopping; no run had started.`;
+    const runs = stopping.map((stop) => stop.run.runId).join(", ");
+    return `humanish: ${signal}: stopping run ${runs} and reclaiming its sandboxes (up to ${deadlineMs / 1000} s); ${again}.`;
+}
 /**
  * Interrupt, reclaim and the registered cleanups all run inside one deadline that starts before
  * the first status write is awaited, so a stalled write or kill still ends in a bounded exit.
  */
-async function stopActiveRuns(io, signal, options) {
+async function stopActiveRuns(io, signal, stopping, options) {
     const deadlineMs = options.deadlineMs ?? INTERRUPT_RECLAIM_DEADLINE_MS;
-    const runs = activeRuns();
-    // Absent: still pending at the deadline. Null: the run had finished, so there is nothing to say.
-    const reports = new Map();
     const work = Promise.all([
-        ...runs.map(async (run) => {
+        ...stopping.map(async (stop) => {
             // False when the run had already finished: its route released what it held.
-            if (!(await run.status.interrupt(signal))) {
-                reports.set(run, null);
+            if (!(await stop.run.status.interrupt(signal))) {
+                stop.report = null;
                 return;
             }
-            const reclaimed = await reclaimPinnedRunSandboxes(run.cwd, run.paths, {
+            const reclaimed = await reclaimPinnedRunSandboxes(stop.run.cwd, stop.run.paths, {
                 requestTimeoutMs: KILL_REQUEST_TIMEOUT_MS,
+                createsWaitMs: Math.min(CREATES_WAIT_MS, deadlineMs / 2),
                 ...options.reclaim,
+                creates: stop.creates,
             }).catch(() => undefined);
-            reports.set(run, reclaimSummary(run, reclaimed));
+            stop.report = reclaimSummary(stop.run, reclaimed);
         }),
         ...[...shutdownCleanups].map((cleanup) => cleanup().catch(() => undefined)),
     ]);
-    const finished = await withDeadline(work, deadlineMs);
-    for (const run of runs) {
-        const report = reports.get(run);
-        if (report === null)
+    const finished = await withDeadline(work, deadlineMs, options.deadline);
+    for (const stop of stopping) {
+        if (stop.report === null)
             continue;
-        const text = report ??
-            (finished === "deadline"
-                ? `stopping did not finish within ${deadlineMs / 1000} s; ${recovery(run)}.`
-                : `reclaim failed; ${recovery(run)}.`);
-        try {
-            io.writeErr(`humanish: ${signal}: run ${run.runId} marked interrupted; ${text}\n`);
-        }
-        catch {
-            // A hung-up terminal cannot take the line; the status record and reclaim receipt hold it.
-        }
+        const text = stop.report?.text ?? deadlineText(stop, finished, deadlineMs);
+        say(io, `humanish: ${signal}: run ${stop.run.runId} marked interrupted; ${text}`);
     }
 }
-function withDeadline(work, ms) {
+function deadlineText(stop, finished, deadlineMs) {
+    if (finished !== "deadline")
+        return `reclaim failed; sandboxes unknown; ${recovery(stop.run)}.`;
+    const inFlight = stop.creates.inFlight();
+    const creates = inFlight === 0 ? "" : ` Still waiting on E2B: ${plural(inFlight, "sandbox create")}.`;
+    return `stopping did not finish within ${deadlineMs / 1000} s; sandboxes unknown.${creates} ${capitalize(recovery(stop.run))}; it also finds sandboxes by this run's E2B tags.`;
+}
+function capitalize(text) {
+    return text.charAt(0).toUpperCase() + text.slice(1);
+}
+function withDeadline(work, ms, wait) {
+    if (wait !== undefined)
+        return Promise.race([work, wait(ms).then(() => "deadline")]);
     let timer;
     const deadline = new Promise((resolve) => {
         timer = setTimeout(() => resolve("deadline"), ms);
@@ -127,20 +158,41 @@ function withDeadline(work, ms) {
  * to reclaim, which would resolve the newest run instead, so it gets its receipts path.
  */
 function recovery(run) {
-    return run.runId === LATEST_RUN_ALIAS
-        ? `its id is \`${LATEST_RUN_ALIAS}\`, which \`humanish reclaim --run\` reads as the newest run, so kill the ids in ${path.join(run.paths.relativeRunRoot, SANDBOX_RECEIPTS_ARTIFACT)} by hand`
-        : `run \`humanish reclaim --run ${run.runId}\``;
+    if (run.runId === LATEST_RUN_ALIAS)
+        return `its id is \`${LATEST_RUN_ALIAS}\`, which \`humanish reclaim --run\` reads as the newest run, so kill the ids in ${path.join(run.paths.relativeRunRoot, SANDBOX_RECEIPTS_ARTIFACT)} by hand`;
+    const cwd = path.resolve(run.cwd) === process.cwd() ? "" : ` --cwd ${shellArg(run.cwd)}`;
+    return `run \`humanish reclaim --run ${shellArg(run.runId)}${cwd}\``;
 }
 function reclaimSummary(run, reclaimed) {
     if (reclaimed === undefined)
-        return `reclaim failed; ${recovery(run)}.`;
+        return { text: `reclaim failed; sandboxes unknown; ${recovery(run)}.`, clean: false };
     if (reclaimed.error !== undefined)
-        return reclaimed.error.message;
-    if (reclaimed.outcomes.length === 0)
-        return "no sandbox receipts to reclaim.";
+        return {
+            text: `${reclaimed.error.message} Sandboxes unknown; ${recovery(run)}.`,
+            clean: false,
+        };
     const counts = new Map();
     for (const outcome of reclaimed.outcomes)
         counts.set(outcome.state, (counts.get(outcome.state) ?? 0) + 1);
-    const tally = [...counts].map(([state, count]) => `${count} ${state}`).join(", ");
-    return reclaimed.ok ? `sandboxes: ${tally}.` : `sandboxes: ${tally}; ${recovery(run)} to retry.`;
+    const tally = counts.size === 0
+        ? "none created"
+        : [...counts].map(([state, count]) => `${count} ${state}`).join(", ");
+    switch (reclaimed.state) {
+        case "clean":
+            return {
+                text: `sandboxes clean: ${tally}; E2B lists none still tagged with this run.`,
+                clean: true,
+            };
+        case "unconfirmed":
+            return { text: `sandboxes unconfirmed: ${tally}; ${recovery(run)} to retry.`, clean: false };
+        default: {
+            const why = reclaimed.createsInFlight > 0
+                ? `${plural(reclaimed.createsInFlight, "sandbox create")} still waiting on E2B`
+                : `the E2B tag search ${reclaimed.tagSearch.status}${reclaimed.tagSearch.detail === undefined ? "" : ` (${reclaimed.tagSearch.detail})`}`;
+            return {
+                text: `sandboxes unknown: ${tally}, but ${why}; ${recovery(run)}.`,
+                clean: false,
+            };
+        }
+    }
 }

package/dist/cli/commands/runs.d.ts

@@ -2,6 +2,11 @@ import { Command } from "commander";
 import { type CliIo } from "../io.js";
 export declare function registerRunCommand(parent: Command, io: CliIo): void;
 export declare function registerVerifyCommand(parent: Command, io: CliIo): void;
+/**
+ * The deprecated `cleanup`, hidden from help: one warning, then exactly `reclaim --check`, with
+ * its output and exit code. The old command read only what computer-use runs recorded and passed
+ * when it found no record; the check asks E2B.
+ */
 export declare function registerCleanupCommand(parent: Command, io: CliIo): void;
 export declare function registerReviewCommand(parent: Command, io: CliIo): void;
 export declare function registerExportCommand(parent: Command, io: CliIo): void;

package/dist/cli/commands/runs.js

@@ -1,14 +1,16 @@
 import path from "node:path";
 import { Command, Option } from "commander";
-import { shellQuote } from "../../substrates/shell.js";
+import { shellArg } from "../../substrates/shell.js";
 import { computeStats, formatStatsHuman } from "../../run/stats.js";
 import { DEFAULT_EXPORT_MAX_BYTES, exportRun, formatExportHuman } from "../../feedback/export.js";
-import { cleanupRun, listRuns, readReview } from "../../run/stored-runs.js";
+import { 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 { applyEnvFileOption, CWD_OPTION_DESCRIPTION, ENV_FILE_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";
+import { warnAndQueue } from "../deprecations.js";
+import { formatFindings, readRunFindings } from "../findings.js";
 export function registerRunCommand(parent, io) {
     addRunOptions(parent
         .command("run")
@@ -30,30 +32,40 @@ export function registerVerifyCommand(parent, io) {
         io.setExitCode(result.ok ? 0 : 2);
     });
 }
+const CLEANUP_RENAMED = "`cleanup` is now `reclaim --check`; `cleanup` is removed in 0.112.0.";
+/**
+ * The deprecated `cleanup`, hidden from help: one warning, then exactly `reclaim --check`, with
+ * its output and exit code. The old command read only what computer-use runs recorded and passed
+ * when it found no record; the check asks E2B.
+ */
 export function registerCleanupCommand(parent, io) {
     parent
-        .command("cleanup")
-        .description("Check a run's recorded resources and write cleanup.json. It stops nothing; humanish reclaim stops leftover sandboxes.")
-        .summary("Check that a run's resources were stopped.")
-        .option("--run <id>", RUN_OPTION_DESCRIPTION, "latest")
+        .command("cleanup", { hidden: true })
+        .description(`Deprecated: ${CLEANUP_RENAMED}`)
         .option("--cwd <path>", CWD_OPTION_DESCRIPTION, ".")
+        .option("--run <id>", RUN_OPTION_DESCRIPTION, "latest")
+        .option("--dotenv <path>", DOTENV_OPTION_DESCRIPTION)
+        .addOption(envFileAliasOption())
         .option("--json", JSON_OPTION_DESCRIPTION)
         .action(async (options, command) => {
-        const result = await cleanupRun(options.cwd, options.run);
-        writeResult(command, io, result, (value) => formatCleanupHuman(value, options.cwd));
-        io.setExitCode(result.ok ? 0 : 2);
+        warnAndQueue(command, io, CLEANUP_RENAMED);
+        await runReclaimCommand(io, command, { ...options, check: true });
     });
 }
 export function registerReviewCommand(parent, io) {
     parent
         .command("review")
-        .description("Show a run's review: verdict, summary and gaps.")
-        .summary("Build a review packet from verified run evidence.")
+        .description("Show a run's review: verdict, summary, gaps and the findings of its analysis, with the evidence each one cites.")
+        .summary("Show a run's outcome and analysis findings.")
         .option("--run <id>", RUN_OPTION_DESCRIPTION, "latest")
         .option("--cwd <path>", CWD_OPTION_DESCRIPTION, ".")
         .option("--json", JSON_OPTION_DESCRIPTION)
         .action(async (options, command) => {
-        const result = await readReview(options.cwd, options.run);
+        const review = await readReview(options.cwd, options.run);
+        // The verified run's exact id, so a run that moves `latest` meanwhile cannot swap the analysis.
+        const result = "verdict" in review
+            ? { ...review, analysis: await readRunFindings(options.cwd, review.runId) }
+            : review;
         writeResult(command, io, result, formatReviewHuman);
         io.setExitCode("ok" in result && result.ok === false ? 2 : 0);
     });
@@ -165,34 +177,57 @@ 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 or in --env-file.")
-        .summary("Stop an interrupted run's leftover sandboxes.")
+        .description("Kill an interrupted run's sandboxes: the exact ids journaled in its sandbox-receipts.ndjson, and any sandbox E2B lists with this run's owner tags (a sandbox whose id never reached a receipt). It lists only sandboxes that match every tag of this run. --check asks E2B whether each still exists and kills nothing. Needs E2B_API_KEY in the environment or in --dotenv.")
+        .summary("Stop or check an interrupted run's 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("--env-file <path>", ENV_FILE_OPTION_DESCRIPTION)
+        .option("--check", "Ask E2B whether each sandbox still exists; kill nothing and write nothing. Exits 0 only when all are gone.")
+        .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: options.envFile, io })))
-            return;
-        const result = options.preflight
-            ? await reclaimPreflightSandboxes(options.cwd)
-            : await reclaimRunSandboxes(options.cwd, options.run);
-        writeResult(command, io, result, formatReclaimHuman);
-        io.setExitCode(result.ok ? 0 : 2);
-    });
+        .action((options, command) => runReclaimCommand(io, command, options));
+}
+/** `reclaim`, and the deprecated `cleanup`, which runs it with `check`. */
+async function runReclaimCommand(io, command, options) {
+    // 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 hooks = { check: options.check === true };
+    const result = options.preflight
+        ? await reclaimPreflightSandboxes(options.cwd, hooks)
+        : await reclaimRunSandboxes(options.cwd, options.run, hooks);
+    writeResult(command, io, result, (value) => formatReclaimHuman(value, options.cwd, options.preflight === true));
+    io.setExitCode(result.ok ? 0 : 2);
 }
-function formatReclaimHuman(result) {
+/** The command that finishes what a reclaim left open, with --cwd when it was given. */
+function reclaimCommand(result, cwd, preflight) {
+    const target = preflight ? "--preflight" : `--run ${shellArg(result.runId)}`;
+    return `humanish reclaim ${target}${cwd === "." ? "" : ` --cwd ${shellArg(cwd)}`}`;
+}
+function formatReclaimHuman(result, cwd, preflight) {
     const lines = [];
-    lines.push(`Reclaim ${result.runId}: ${result.ok ? "ok" : "failed"}, ${plural(result.receiptCount, "sandbox receipt")}.`);
+    const check = result.mode === "check";
+    const search = result.tagSearch.status === "done"
+        ? `E2B lists ${plural(result.tagSearch.found, "more sandbox", "more sandboxes")} tagged with it`
+        : `E2B tag search ${result.tagSearch.status}`;
+    lines.push(`${check ? "Reclaim check" : "Reclaim"} ${result.runId}: ${result.state}. ${plural(result.receiptCount, "sandbox receipt")}; ${search}.`);
     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}, from ${outcome.source}): ${outcome.state}${outcome.detail ? `: ${outcome.detail}` : ""}`);
     }
     for (const warning of result.warnings)
         lines.push(`  warning: ${warning}`);
-    const stdout = lines.join("\n");
-    return result.error === undefined ? stdout : { stdout: `${stdout}\n`, error: result.error };
+    if (result.error === undefined && result.state !== "clean")
+        lines.push(result.state === "running"
+            ? `To stop them, run ${reclaimCommand(result, cwd, preflight)}.`
+            : `Run ${reclaimCommand(result, cwd, preflight)} again once E2B is reachable; each sandbox's create-time timeout is the backstop.`);
+    const stdout = `${lines.join("\n")}\n`;
+    return result.error === undefined ? stdout : { stdout, error: result.error };
 }
 const REVIEW_VERDICTS = {
     // A dry run, or a live run with no participant result; review's result does not carry the mode.
@@ -202,7 +237,10 @@ const REVIEW_VERDICTS = {
     blocked: "blocked",
     timed_out: "timed out",
 };
-/** A run's review: its verdict, summary and gaps, and where review.json is. */
+/**
+ * A run's review: its verdict, summary and gaps, its analysis findings, and where review.json is.
+ * A pass verdict on a run whose own ok is false leads with how the run ended (runDisplay), then why.
+ */
 function formatReviewHuman(result) {
     if (!("verdict" in result)) {
         // A run that did not pass verify has no review to show; verify says why.
@@ -219,12 +257,19 @@ function formatReviewHuman(result) {
             }
             : humanError(error);
     }
+    const verdict = REVIEW_VERDICTS[result.verdict];
+    const display = result.display;
+    const headline = result.verdict === "pass" && display !== undefined && display.state !== "passed"
+        ? `${display.label} (verdict pass)`
+        : verdict;
     return ([
-        `humanish review ${result.runId}: ${REVIEW_VERDICTS[result.verdict]}`,
+        `humanish review ${result.runId}: ${headline}`,
+        ...(display?.reason === undefined ? [] : [`why: ${display.reason}`]),
         "",
         result.summary,
         ...(result.gaps.length === 0 ? [] : ["", "gaps:", ...result.gaps.map((gap) => `- ${gap}`)]),
         "",
+        ...formatFindings(result.analysis),
         `review: ${result.path}`,
     ].join("\n") + "\n");
 }
@@ -240,6 +285,12 @@ function shareSafetyLines(result) {
         .filter((reason) => reason.code !== "VERIFY_FAILED")
         .map((reason) => `share-safety: ${reason.code}: ${reason.message}`);
 }
+/** For a run that is not finished, its liveness and sandbox state, so the line leads with them. */
+function unfinishedNote(result) {
+    return result.unfinished === undefined
+        ? ""
+        : ` (${result.unfinished.liveness}, sandboxes ${result.unfinished.sandboxes})`;
+}
 /**
  * One line for a pass. A failure lists only the failing checks. `--verbose` prints every check.
  * A run that does not exist prints only that.
@@ -248,12 +299,13 @@ function formatVerifyHuman(result) {
     if (result.error?.code === "HUMANISH_RUN_NOT_FOUND")
         return humanError(result.error);
     const runId = verifiedRunId(result);
+    const named = `${runId}${unfinishedNote(result)}`;
     const total = result.checks.length;
     const failed = result.checks.filter((check) => !check.ok);
     const lines = result.ok
-        ? [`verified ${runId} · ${result.shareSafety.status} · ${total} checks passed`]
+        ? [`verified ${named} · ${result.shareSafety.status} · ${total} checks passed`]
         : [
-            `verify failed: ${runId} · ${result.shareSafety.status} · ${failed.length} of ${total} checks failed`,
+            `verify failed: ${named} · ${result.shareSafety.status} · ${failed.length} of ${total} checks failed`,
             ...failed.map((check) => `- ${check.message}`),
         ];
     lines.push(...shareSafetyLines(result), ...result.warnings.map((warning) => `warning: ${warning}`));
@@ -267,43 +319,13 @@ function formatVerifyVerbose(result) {
         return humanError(result.error);
     return ([
         `humanish verify ${result.ok ? "passed" : "failed"}`,
-        `run: ${verifiedRunId(result)}`,
+        `run: ${verifiedRunId(result)}${unfinishedNote(result)}`,
         `share-safety: ${result.shareSafety.status}`,
         ...result.shareSafety.reasons.map((reason) => `share-safety reason: ${reason.code}: ${reason.message}`),
         ...result.checks.map((check) => `- ${check.ok ? "ok" : "fail"} ${check.name}: ${check.message}`),
         ...result.warnings.map((warning) => `warning: ${warning}`),
     ].join("\n") + "\n");
 }
-/** A command-line argument, single-quoted only when the shell would split or expand it. */
-function shellArg(value) {
-    return /^[\w@%+=:,./-]+$/.test(value) ? value : shellQuote(value);
-}
-/**
- * Cleanup only reads evidence and never stops a sandbox. A failed resource is an E2B sandbox not
- * recorded as stopped, which reclaim can stop from the run's sandbox receipts, so the last line
- * names it. A skipped resource is a provider reclaim does not handle, so it gets no line. `cwd` is
- * the --cwd the command was given, since cleanup's result masks it.
- */
-function reclaimPointer(result, cwd) {
-    if (result.runId === undefined || result.summary.failed === 0)
-        return [];
-    const cwdFlag = cwd === "." ? "" : ` --cwd ${shellArg(cwd)}`;
-    return [
-        `To stop leftover sandboxes, run humanish reclaim --run ${shellArg(result.runId)}${cwdFlag}.`,
-    ];
-}
-function formatCleanupHuman(result, cwd) {
-    if (!result.ok && result.error)
-        return humanError(result.error);
-    return ([
-        `humanish cleanup ${result.ok ? "passed" : "failed"}`,
-        `run: ${result.runId ?? result.run}`,
-        `resources: already-clean ${result.summary.alreadyClean}, skipped ${result.summary.skipped}, failed ${result.summary.failed}`,
-        ...(result.cleanupPath ? [`cleanup: ${result.cleanupPath}`] : []),
-        ...result.warnings.map((warning) => `warning: ${warning}`),
-        ...reclaimPointer(result, cwd),
-    ].join("\n") + "\n");
-}
 function formatRunsHuman(result) {
     if (!result.ok)
         return humanError(result.error);
@@ -312,6 +334,6 @@ function formatRunsHuman(result) {
     }
     return ([
         `latest: ${result.latest ?? "none"}`,
-        ...result.runs.map((run) => `- ${run.runId} ${run.mode ?? "unknown"} ${run.createdAt ?? "unknown"} ${run.path}`),
+        ...result.runs.map((run) => `- ${run.runId} ${run.mode ?? "unknown"} ${run.display?.label ?? "unreadable"} ${run.createdAt ?? "unknown"} ${run.path}`),
     ].join("\n") + "\n");
 }

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-route-computer-use.js

@@ -9,6 +9,7 @@ import { cliAnalysisOptions } from "./analysis-signals.js";
 import { onRunShutdown } from "./run-signals.js";
 import { parseStudyCount, parseParticipantIds, parseObserverPort, wantsJson, writeResult, } from "../io.js";
 import { exposureRequestFromOptions, followObserver, planObserver, showObserver, staticObserverOpen, withObserverServer, } from "../observer-follow.js";
+import { writeRunFindings } from "../findings.js";
 import { formatCuaStudyHuman } from "./study-format.js";
 import { resolveRouteShouldOpen } from "./study-route-open.js";
 import { studyResultIdentity } from "../../run/study-result.js";
@@ -237,6 +238,7 @@ async function reportCuaRun(args, prepared, result, live) {
     }
     writeResult(args.command, args.io, output, formatCuaStudyHuman);
     args.io.setExitCode(result.ok && automaticAnalysisSucceeded(result) ? 0 : 2);
+    await writeRunFindings(args.command, args.io, args.options.cwd, result);
     if (server && (result.observer?.ok || attachedObserver)) {
         const followResult = output.observer?.ok
             ? output.observer

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

@@ -2,6 +2,7 @@ import { automaticAnalysisSucceeded } from "../../analysis/automatic-completion.
 import { Command } from "commander";
 import { cliAnalysisOptions } from "./analysis-signals.js";
 import { wantsJson, writeResult } from "../io.js";
+import { writeRunFindings } from "../findings.js";
 import { showObserver } from "../observer-follow.js";
 import { formatScriptedStudyHuman } from "./study-format.js";
 import { observerOpen, resolveRouteShouldOpen, watchFinishedPlan } from "./study-route-open.js";
@@ -35,6 +36,7 @@ export function scriptedRouteRun(args) {
             const result = outcome.result;
             writeResult(args.command, args.io, result, formatScriptedStudyHuman);
             args.io.setExitCode(result.ok && automaticAnalysisSucceeded(result) ? 0 : 2);
+            await writeRunFindings(args.command, args.io, args.options.cwd, result);
             // Watch mode serves the Observer the route rendered through its finished run.
             if (finishedPlan !== undefined && result.ok && result.observer !== undefined) {
                 await showObserver({