humanish 0.110.0 → 0.110.2

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,50 @@ 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;
+}
+/**
+ * Whether an installed agent can run participants here: it reports signed in under the
+ * participant's environment, and a Claude Code is at or above the floor. Doctor's rows decide their
+ * status from this, so a row whose message says the agent cannot run participants is never "ok".
+ */
+export function localAgentReady(agent) {
+    return agent.authStatus === "authenticated" && localAgentVersionRefusal(agent) === 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,44 +1,52 @@
 // 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";
+import { cli } from "../../cli/invocation.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 {
             kind: "unsupported",
             message: compatibility === "unsupported_platform"
                 ? `Hosted Codex participants require Linux or macOS on x64 or arm64. This host is ${process.platform}/${process.arch}; no desktop was launched.`
-                : `Hosted Codex participants need a Codex CLI release humanish runs: ${describeCodexCliAdmission()}. Run \`humanish doctor\` for the release it found and the command that replaces it; no desktop was launched.`,
+                : `Hosted Codex participants need a Codex CLI release humanish runs: ${describeCodexCliAdmission()}. Run \`${cli("doctor")}\` for the release it found and the command that replaces it; no desktop was launched.`,
         };
     }
     if (chosen.billing === "account-unknown" &&
         (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/observe.js

@@ -4,7 +4,7 @@ import { SERVE_SCHEMA, serveObserverLibrary } from "../../observer/serve.js";
 import { startExposedObserver, validateExposure } from "../../observer/exposure.js";
 import { ServeTunnelError } from "../../observer/tunnel.js";
 import { collectRepeated, CWD_OPTION_DESCRIPTION, formatRunHuman, freePortOption, JSON_OPTION_DESCRIPTION, parseObserverPort, RUN_OPTION_DESCRIPTION, wantsJson, writeResult, } from "../io.js";
-import { exitCodeForSignal, formatObserverHuman, } from "../observer-follow.js";
+import { exitCodeForSignal, formatObserverHuman, personAtTerminal, unattendedObserverWarning, } from "../observer-follow.js";
 export function registerObserveCommand(parent, io) {
     addLibraryOptions(parent
         .command("observe")
@@ -16,6 +16,7 @@ export function registerObserveCommand(parent, io) {
         .option("--cwd <path>", CWD_OPTION_DESCRIPTION, ".")
         .option("--open", "Open the Observer in the default browser.")
         .option("--no-open", "Serve without opening a browser.")
+        .option("--serve", "Serve one run until Ctrl-C even without an interactive terminal; by default an agent's shell or a pipe gets the Observer path and an exit.")
         .option("--json", JSON_OPTION_DESCRIPTION))
         .addHelpText("after", [
         "",
@@ -32,6 +33,8 @@ export function registerObserveCommand(parent, io) {
         "The server binds 127.0.0.1 only. One run exposes just that run's bundle directory; --all",
         "serves the run library. It stays attached until Ctrl-C; file:// security policy and live",
         "refresh are why loopback http is preferred over opening the index.html path directly.",
+        "Without an interactive terminal, as in an agent's shell or a pipe, observe for one run",
+        "prints the Observer path and exits; --serve keeps it serving.",
         "",
         "--safe, --expose, --tunnel, --tunnel-domain, --oauth, --allow-email, --allow-domain and",
         "--public-url need --all. Exposure only ever happens through an authenticated edge (ngrok",
@@ -119,9 +122,19 @@ async function observeRun(io, options, command) {
         io.setExitCode(2);
         return;
     }
+    const wantsMachine = wantsJson(command);
+    if (options.serve !== true && !personAtTerminal()) {
+        // Nobody can press Ctrl-C here, so a server would wait forever: print the path and exit.
+        const result = {
+            ...rendered,
+            warnings: [...rendered.warnings, unattendedObserverWarning("observe")],
+        };
+        writeResult(command, io, result, formatObserverHuman);
+        io.setExitCode(0);
+        return;
+    }
     // Reuse the contained current-data projection, scoped to this run. A raw static
     // server would miss runtime status and could replay stored iframe grants.
-    const wantsMachine = wantsJson(command);
     const shouldOpen = options.open === false
         ? false
         : options.open === true

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

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

@@ -1,20 +1,30 @@
 // 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), sweeps the interrupted runs' files of their raw
+// sandbox ids as Run.finish does for a finished run, 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 { scrubRunSandboxIds } from "../../run/sandbox-ids.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";
+import { cli } from "../invocation.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 +49,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 +58,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 +91,71 @@ 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)
+    ]).then(() => 
+    // Last, so it also covers what the route recorded while reclaim ran, such as a desktop
+    // startup error that quotes the sandbox the kill cut short. A run stopped by the deadline is
+    // not swept; verify grades a file that names a receipt's id local_only.
+    Promise.all(stopping
+        .filter((stop) => stop.report !== null)
+        .map((stop) => scrubRunSandboxIds(stop.run.paths).catch(() => undefined))));
+    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 +167,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 \`${cli("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 \`${cli(`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;