humanish 0.106.0 → 0.107.0

package/dist/substrates/e2b/desktop-cdp.d.ts

@@ -2,17 +2,17 @@ import { type ChromeMobileEmulationRequest } from "./cdp-probe.js";
 import type { RunDesktopGeometry } from "../../run/streams.js";
 import type { E2BDesktopSandbox } from "./sdk.js";
 /**
- * Runtime-only CDP endpoint attribution for the exact chromium this lane launched. Port
+ * Runtime-only CDP endpoint attribution for the exact chromium this participant launched. Port
  * resolution at OBSERVE time: the cached launch-time `cdpPort` wins; absent that, the observer
  * probe re-reads `profileDir`'s DevToolsActivePort marker (a slow cold start can publish it
- * after the launch-time poll gave up); absent both it uses 9222, the port every lane launches
+ * after the launch-time poll gave up); absent both it uses 9222, the port every participant launches
  * Chrome with, where a dead endpoint degrades into a warning that names the cause.
  */
 export interface ChromeCdpEndpoint {
     cdpPort?: number;
     /** The launched profile dir; lets observers re-read DevToolsActivePort at observe time. */
     profileDir?: string;
-    /** The URL this lane opened; attributes the CDP page when no target id is pinned yet. */
+    /** The URL this participant opened; attributes the CDP page when no target id is pinned yet. */
     targetUrl: string;
 }
 /**
@@ -20,7 +20,7 @@ export interface ChromeCdpEndpoint {
  * after the launch page, so a tab the participant opens later should lay out at the phone width
  * too. The first observation on each new target reads that page's own report; a target that
  * reports the requested width is recorded through `onCovered`, and one that does not (or cannot be
- * read) fires `onDrift` once, so a phone-labelled lane that spent part of its session at desktop
+ * read) fires `onDrift` once, so a phone-labelled participant that spent part of its session at desktop
  * layout says so with the number the page gave.
  */
 export interface ChromeEmulationDrift {
@@ -44,7 +44,7 @@ export interface ChromeEmulationDrift {
  * reading the old tab forever).
  *
  * `onUnavailable` fires ONCE, on the first probe that could not read the page, with the reason.
- * The observer still degrades to `{}` for the loop; the callback is how a lane says out loud that
+ * The observer still degrades to `{}` for the loop; the callback is how a participant says out loud that
  * url/text criteria are not being measured, instead of letting the funnel report 0/N (#514).
  */
 export declare function makeChromeBrowserStateObserver(desktop: E2BDesktopSandbox, requestTimeoutMs: number, endpoint: ChromeCdpEndpoint, options?: {
@@ -59,10 +59,10 @@ export declare function makeChromeBrowserStateObserver(desktop: E2BDesktopSandbo
     text?: string;
     scrollY?: number;
 }>;
-/** The user agent a mobile-emulated lane presents unless the lab sets its own. */
+/** The user agent a mobile-emulated participant presents unless the lab sets its own. */
 export declare const DEFAULT_MOBILE_USER_AGENT = "Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.0 Mobile/15E148 Safari/604.1";
 /**
- * Apply mobile emulation (#221) to the lane's launch page and read back what the page reports.
+ * Apply mobile emulation (#221) to the participant's launch page and read back what the page reports.
  * Fails CLOSED: a request that cannot be applied throws, because a desktop run labelled mobile is
  * the over-trust this feature exists to prevent. A read-back that cannot be taken is a warning
  * (the emulation was applied; only the proof is missing).

package/dist/substrates/e2b/desktop-cdp.js

@@ -14,7 +14,7 @@ import { e2bShell } from "./shell.js";
  * reading the old tab forever).
  *
  * `onUnavailable` fires ONCE, on the first probe that could not read the page, with the reason.
- * The observer still degrades to `{}` for the loop; the callback is how a lane says out loud that
+ * The observer still degrades to `{}` for the loop; the callback is how a participant says out loud that
  * url/text criteria are not being measured, instead of letting the funnel report 0/N (#514).
  */
 export function makeChromeBrowserStateObserver(desktop, requestTimeoutMs, endpoint, options = {}) {
@@ -97,10 +97,10 @@ export function makeChromeBrowserStateObserver(desktop, requestTimeoutMs, endpoi
         };
     };
 }
-/** The user agent a mobile-emulated lane presents unless the lab sets its own. */
+/** The user agent a mobile-emulated participant presents unless the lab sets its own. */
 export const DEFAULT_MOBILE_USER_AGENT = "Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.0 Mobile/15E148 Safari/604.1";
 /**
- * Apply mobile emulation (#221) to the lane's launch page and read back what the page reports.
+ * Apply mobile emulation (#221) to the participant's launch page and read back what the page reports.
  * Fails CLOSED: a request that cannot be applied throws, because a desktop run labelled mobile is
  * the over-trust this feature exists to prevent. A read-back that cannot be taken is a warning
  * (the emulation was applied; only the proof is missing).
@@ -129,7 +129,7 @@ export async function applyMobileEmulation(desktop, requestTimeoutMs, endpoint,
     };
     // The UA / touch / DPR overrides are bound to the DevTools session that set them and lapse the
     // moment its socket closes (measured: only the viewport width survived a one-shot apply). So the
-    // applier stays attached for the lane's whole life as a detached process; the sandbox teardown
+    // applier stays attached for the participant's whole life as a detached process; the sandbox teardown
     // ends it. Its first stdout line says what was applied.
     const holderName = `mobile-emulation-${Date.now().toString(36)}`;
     await startDetachedProcess(shell, {

package/dist/substrates/e2b/desktop-geometry.d.ts

@@ -19,9 +19,9 @@ export declare function declaredScreenForRender(preset: DevicePreset, presetName
     preset: string;
 } | undefined;
 /**
- * Verify the desktop screen geometry IN-SANDBOX (the per-lane device claim is checked, never
+ * Verify the desktop screen geometry IN-SANDBOX (the participant's device claim is checked, never
  * assumed). A parseable mismatch fails closed. Unavailable/unparseable evidence is returned as
- * an explicit warning: the lane may still run, but its bundle records only the requested screen
+ * an explicit warning: the participant may still run, but its bundle records only the requested screen
  * and never upgrades that request into a verified measurement.
  */
 export declare function inspectDesktopScreenGeometry(args: {
@@ -57,7 +57,7 @@ export declare function makeChromeDesktopGeometryObserver(desktop: E2BDesktopSan
 }) | undefined>;
 /** Root-relative physical client bounds from xwininfo's C-locale stats. */
 export declare function parseXwininfoGeometry(output: string): RunDesktopGeometry["browserWindow"] | undefined;
-/** Hosted-browser geometry capture shared by the per-lane and shared-world routes. */
+/** Hosted-browser geometry capture shared by the computer-use and shared-world routes. */
 export declare function captureDesktopBrowserGeometry(args: {
     desktop: E2BDesktopSandbox;
     browserFamily: DesktopBrowserFamily;
@@ -67,7 +67,7 @@ export declare function captureDesktopBrowserGeometry(args: {
     pagePreference?: ChromeCdpPagePreference;
     browserWindowId?: string;
     participantId: string;
-    /** Runtime-only lane target URL (attributes the CDP page); never persisted by this capture. */
+    /** Runtime-only participant target URL (attributes the CDP page); never persisted by this capture. */
     targetUrl: string;
     requestedScreen: readonly [number, number];
     requestTimeoutMs: number;

package/dist/substrates/e2b/desktop-geometry.js

@@ -22,9 +22,9 @@ export function declaredScreenForRender(preset, presetName, rendered) {
     return { width: preset.width, height: preset.height, preset: presetName };
 }
 /**
- * Verify the desktop screen geometry IN-SANDBOX (the per-lane device claim is checked, never
+ * Verify the desktop screen geometry IN-SANDBOX (the participant's device claim is checked, never
  * assumed). A parseable mismatch fails closed. Unavailable/unparseable evidence is returned as
- * an explicit warning: the lane may still run, but its bundle records only the requested screen
+ * an explicit warning: the participant may still run, but its bundle records only the requested screen
  * and never upgrades that request into a verified measurement.
  */
 export async function inspectDesktopScreenGeometry(args) {
@@ -229,7 +229,7 @@ async function fitBrowserWindowWithinDesktop(desktop, windowId, resolution, requ
     }
     return resized;
 }
-/** Hosted-browser geometry capture shared by the per-lane and shared-world routes. */
+/** Hosted-browser geometry capture shared by the computer-use and shared-world routes. */
 export async function captureDesktopBrowserGeometry(args) {
     const warnings = [];
     let browserWindowId = args.browserWindowId;

package/dist/substrates/e2b/desktop-media.js

@@ -81,7 +81,7 @@ export async function startE2BDesktopMedia(options) {
         },
     });
 }
-/** Where a lane's synthetic camera feed lives inside the sandbox: a tmpfs the sandbox user can
+/** Where a participant's synthetic camera feed lives inside the sandbox: a tmpfs the sandbox user can
  *  write, and a path that contains neither /tmp/ nor /home/, which the public-safety scan reads
  *  as an operator's local path (this one is the harness's own and belongs in the bundle). */
 const SANDBOX_MEDIA_DIR = "/dev/shm/humanish-media";
@@ -101,7 +101,7 @@ export async function prepareDesktopMedia(desktop, media, permission, cwd, reque
             throw new Error("Microphone source-file injection is unsupported; use source: speech.");
         if (media.camera !== undefined)
             throw new Error("Hosted synthetic cameras cannot be combined with speech.");
-        // The lane starts and admits the speech worker before launching the browser.
+        // The participant's setup starts and admits the speech worker before launching the browser.
         return {
             microphone: { source: "speech" },
             permission,

package/dist/substrates/e2b/sandbox.d.ts

@@ -48,6 +48,8 @@ export declare function readE2BRelease(result: DesktopReleaseResult, options: {
     scrub: (text: string) => string;
     costSpan?: boolean;
 }): E2BReleaseReading;
+/** A release_unavailable result as one lowercase line, for routes and reclaim that report it. */
+export declare function releaseUnavailableDetail(detail: string | undefined): string;
 /** Reclaim's persisted outcome; run/reclaim.ts writes these strings. */
 export type E2BSandboxDestroyOutcome = {
     state: "killed" | "already-gone";

package/dist/substrates/e2b/sandbox.js

@@ -7,7 +7,7 @@
 import { redactText, toErrorMessage } from "../../evidence/redaction.js";
 import { appendSandboxReceipt } from "../../run/sandbox-receipts.js";
 import { ownDesktopAllocation, } from "../desktop-session.js";
-import { E2BDesktopStartupError, isSandboxNotFoundError, } from "./sdk.js";
+import { E2B_DEBUG_KILL_DETAIL, E2BDesktopStartupError, e2bDebugMode, isSandboxNotFoundError, } from "./sdk.js";
 /** A desktop sandbox, on the stock `desktop` template or a named one. */
 export function acquireE2BDesktopSandbox(request) {
     return acquire(request, request.template);
@@ -27,7 +27,7 @@ async function acquire(request, template) {
         if (request.receipt !== null) {
             const { root, participantId, now = Date.now } = request.receipt;
             // Best effort by contract: a failed write leaves the TTL as the only backstop and never
-            // fails the lane.
+            // fails the participant.
             await appendSandboxReceipt(root, {
                 at: new Date(now()).toISOString(),
                 laneId: participantId,
@@ -56,13 +56,22 @@ function boundKill(module) {
  * The SDK resolves false for an id it no longer knows (a 404), and a SandboxNotFoundError,
  * recognized by type, means the same. Every other throw is unconfirmed, whatever its message
  * says: the SDK answers a 404 with false before it throws, so "not found" or "404" in a thrown
- * message comes from some other failure, such as a trace id. Never list the account.
+ * message comes from some other failure, such as a trace id. A true in debug mode sent no
+ * request, so it confirms nothing. Never list the account.
  */
 async function killById(kill, sandboxId, options) {
     if (kill === undefined)
         return { status: "unconfirmed", reason: "release_unavailable" };
+    // The SDK reads the variable when the call starts, so read it at the same point.
+    const debug = e2bDebugMode();
     try {
         const result = await kill(sandboxId, options);
+        if (result === true && debug)
+            return {
+                status: "unconfirmed",
+                reason: "release_unavailable",
+                detail: E2B_DEBUG_KILL_DETAIL,
+            };
         if (result === true)
             return { status: "released", reason: "terminated" };
         if (result === false)
@@ -105,7 +114,9 @@ export function readE2BRelease(result, options) {
         case "release_unavailable":
             return {
                 released: false,
-                warning: `Installed @e2b/desktop SDK does not expose Sandbox.kill; server-side kill-on-timeout will reclaim the ${label.toLowerCase()}.`,
+                warning: result.detail === undefined
+                    ? `Installed @e2b/desktop SDK does not expose Sandbox.kill; server-side kill-on-timeout will reclaim the ${label.toLowerCase()}.`
+                    : `${label} release is unconfirmed: ${result.detail}. If it exists, server-side kill-on-timeout will reclaim it.`,
             };
         case "release_failed":
             return {
@@ -119,6 +130,12 @@ export function readE2BRelease(result, options) {
             };
     }
 }
+/** A release_unavailable result as one lowercase line, for routes and reclaim that report it. */
+export function releaseUnavailableDetail(detail) {
+    return detail === undefined
+        ? "installed @e2b/desktop SDK does not expose Sandbox.kill; server-side kill-on-timeout will reclaim the sandbox"
+        : `${detail}; if the sandbox exists, server-side kill-on-timeout will reclaim it`;
+}
 /**
  * Kill one sandbox by its exact recorded id, for reclaim, and map the shared release result onto
  * reclaim's persisted outcome. It never lists the account.
@@ -129,10 +146,7 @@ export async function destroyE2BSandbox(module, sandboxId, options) {
         return { state: released.reason === "terminated" ? "killed" : "already-gone" };
     switch (released.reason) {
         case "release_unavailable":
-            return {
-                state: "kill-failed",
-                detail: "installed @e2b/desktop SDK does not expose Sandbox.kill; server-side kill-on-timeout will reclaim the sandbox",
-            };
+            return { state: "kill-failed", detail: releaseUnavailableDetail(released.detail) };
         case "invalid_result":
             return {
                 state: "kill-failed",

package/dist/substrates/e2b/sdk.d.ts

@@ -165,7 +165,8 @@ type DesktopCreateCleanup = "killed" | "already_gone" | "unconfirmed";
 /** Startup failed after this call acquired a handle. No credentials/options are included here. */
 export declare class E2BDesktopStartupError extends Error {
     readonly cleanup: DesktopCreateCleanup;
-    constructor(error: unknown, cleanup: DesktopCreateCleanup);
+    readonly cleanupDetail?: string | undefined;
+    constructor(error: unknown, cleanup: DesktopCreateCleanup, cleanupDetail?: string | undefined);
 }
 /**
  * Preserve ownership before the desktop SDK starts Xvfb/XFCE (#581). Its public generic create
@@ -191,4 +192,14 @@ export declare function guardDesktopSandboxCreate(module: E2BDesktopModule): E2B
  * that the exact sandbox humanish created is gone (confirmed reclaimed), never a re-list.
  */
 export declare function isSandboxNotFoundError(error: unknown): boolean;
+/** The variable that puts the E2B SDK in debug mode. */
+export declare const E2B_DEBUG_ENV = "E2B_DEBUG";
+/**
+ * Whether the E2B SDK runs in debug mode, read the way the SDK reads it when a call starts. In
+ * debug mode `Sandbox.kill` returns true without sending a request to E2B, so a true confirms
+ * nothing.
+ */
+export declare function e2bDebugMode(env?: NodeJS.ProcessEnv): boolean;
+/** Why a kill that returned true in debug mode is unconfirmed. */
+export declare const E2B_DEBUG_KILL_DETAIL = "E2B_DEBUG=true makes the E2B SDK return true from Sandbox.kill without contacting E2B";
 export {};

package/dist/substrates/e2b/sdk.js

@@ -2,8 +2,8 @@
 // real @e2b/desktop Sandbox. Every desktop route launches through this one seam; the peer dep is
 // optional and lazily loaded, so it stays out of the published tarball and CI.
 //
-// E2BDesktopSandbox is the command, file, stream, launch and input subset the lanes use; `open` is
-// optional because older SDKs lack it (the computer-use lane then falls back to launch). It
+// E2BDesktopSandbox is the command, file, stream, launch and input subset the participants use; `open` is
+// optional because older SDKs lack it (the computer-use route then falls back to launch). It
 // satisfies the executor's E2BDesktopLike port (src/substrates/e2b/desktop-executor.ts) as is.
 import { sep } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -29,15 +29,17 @@ export const DESKTOP_CREATE_CLEANUP_TIMEOUT_MS = 10_000;
 /** Startup failed after this call acquired a handle. No credentials/options are included here. */
 export class E2BDesktopStartupError extends Error {
     cleanup;
-    constructor(error, cleanup) {
+    cleanupDetail;
+    constructor(error, cleanup, cleanupDetail) {
         const detail = error instanceof Error ? error.message : String(error);
         const cleanupNote = cleanup === "killed"
             ? "the allocated sandbox was reclaimed"
             : cleanup === "already_gone"
                 ? "the allocated sandbox was already gone"
-                : "cleanup of the allocated sandbox was not confirmed; no retry is allowed and its provider timeout remains the backstop";
+                : `cleanup of the allocated sandbox was not confirmed${cleanupDetail === undefined ? "" : ` (${cleanupDetail})`}; no retry is allowed and its provider timeout remains the backstop`;
         super(`Desktop startup failed after allocation; ${cleanupNote}. ${detail}`, { cause: error });
         this.cleanup = cleanup;
+        this.cleanupDetail = cleanupDetail;
         this.name = "E2BDesktopStartupError";
     }
 }
@@ -78,7 +80,7 @@ export function guardDesktopSandboxCreate(module) {
                     // SDK 2.4 calls this method before create rejects. Keep its boolean contract while
                     // recording unconfirmed cleanup independently of the SDK's catch-and-discard path.
                     this.kill = async () => {
-                        const cleanup = await reclaim();
+                        const { cleanup } = await reclaim();
                         if (cleanup === "unconfirmed")
                             throw new Error("Desktop startup cleanup was not confirmed");
                         return cleanup === "killed";
@@ -103,8 +105,8 @@ export function guardDesktopSandboxCreate(module) {
             catch (error) {
                 if (cleanupOwned === undefined)
                     throw error;
-                const cleanup = await cleanupOwned();
-                throw new E2BDesktopStartupError(error, cleanup);
+                const { cleanup, detail } = await cleanupOwned();
+                throw new E2BDesktopStartupError(error, cleanup, detail);
             }
         }
     }
@@ -113,6 +115,8 @@ export function guardDesktopSandboxCreate(module) {
 async function reclaimFailedDesktopCreate(kill, timeoutMs) {
     const controller = new AbortController();
     let timer;
+    // The SDK reads the variable when the call starts, so read it at the same point.
+    const debug = e2bDebugMode();
     try {
         const result = await Promise.race([
             kill({ requestTimeoutMs: timeoutMs, signal: controller.signal }),
@@ -123,12 +127,17 @@ async function reclaimFailedDesktopCreate(kill, timeoutMs) {
                 }, timeoutMs);
             }),
         ]);
+        // A true in debug mode sent no request, so it confirms nothing.
+        if (result === true && debug)
+            return { cleanup: "unconfirmed", detail: E2B_DEBUG_KILL_DETAIL };
         // The installed SDK documents false as an exact-id 404: already absent is also reclaimed.
-        return result === true ? "killed" : result === false ? "already_gone" : "unconfirmed";
+        if (result === true)
+            return { cleanup: "killed" };
+        return { cleanup: result === false ? "already_gone" : "unconfirmed" };
     }
     catch {
         // Do not serialize cleanup options, connection state, or provider errors that may echo auth.
-        return "unconfirmed";
+        return { cleanup: "unconfirmed" };
     }
     finally {
         if (timer !== undefined)
@@ -166,3 +175,15 @@ export function isSandboxNotFoundError(error) {
     const value = error;
     return (value.name === "SandboxNotFoundError" || value.constructor?.name === "SandboxNotFoundError");
 }
+/** The variable that puts the E2B SDK in debug mode. */
+export const E2B_DEBUG_ENV = "E2B_DEBUG";
+/**
+ * Whether the E2B SDK runs in debug mode, read the way the SDK reads it when a call starts. In
+ * debug mode `Sandbox.kill` returns true without sending a request to E2B, so a true confirms
+ * nothing.
+ */
+export function e2bDebugMode(env = process.env) {
+    return env[E2B_DEBUG_ENV]?.toLowerCase() === "true";
+}
+/** Why a kill that returned true in debug mode is unconfirmed. */
+export const E2B_DEBUG_KILL_DETAIL = `${E2B_DEBUG_ENV}=true makes the E2B SDK return true from Sandbox.kill without contacting E2B`;

package/dist/substrates/local/runtime-host.d.ts

@@ -16,6 +16,8 @@ export declare function runtimeExec(file: string, args: string[], options?: Runt
     stdout: string;
     stderr: string;
 }>;
+/** The shell command an operator runs for `docker <args>` on this host, as runtimeDocker runs it. */
+export declare function dockerCommandLine(args: string[], options?: RuntimeHostOptions): string;
 export declare function runtimeDocker(args: string[], options?: RuntimeHostOptions, timeout?: number): Promise<{
     stdout: string;
     stderr: string;

package/dist/substrates/local/runtime-host.js

@@ -30,6 +30,12 @@ export async function runtimeExec(file, args, options = {}, timeout = 15_000) {
         ? hostExec("limactl", ["shell", "--workdir", "/", LIMA_INSTANCE, "--", file, ...args], options, timeout)
         : hostExec(file, args, options, timeout);
 }
+/** The shell command an operator runs for `docker <args>` on this host, as runtimeDocker runs it. */
+export function dockerCommandLine(args, options = {}) {
+    return usesLima(options)
+        ? `limactl shell ${LIMA_INSTANCE} -- sudo docker --host unix:///var/run/docker.sock ${args.join(" ")}`
+        : `docker ${args.join(" ")}`;
+}
 export async function runtimeDocker(args, options = {}, timeout = 15_000) {
     return usesLima(options)
         ? runtimeExec("sudo", ["-n", "docker", "--host", "unix:///var/run/docker.sock", ...args], options, timeout)

package/dist/tui/actions.d.ts

@@ -29,11 +29,13 @@ export declare function createTuiObserverSession(cwdInput: string, options?: {
  * has children: the CLI, and whatever it spawned to reach the sandbox. Signalling only the parent
  * leaves those orphaned and still working.
  *
- * SIGTERM, never SIGKILL: the run's own handlers get the chance to finalize its record and release
- * what it holds. A killed run leaves a `running` record to go stale, which reads as interrupted —
- * true, but strictly less informative than a run that was told to stop.
+ * SIGTERM, never SIGKILL, so the run's handler gets to act. Outside post-run analysis the run
+ * command (src/cli/commands/run-signals.ts) marks the run `interrupted` in status.json, kills the
+ * E2B sandboxes its receipts name, writes reclaim-receipt.json and exits; run.json keeps its last
+ * live flush. During analysis the signal cancels analysis instead. A local VM's container exits
+ * when the run's process goes.
  *
- * This stops the PROCESS. Sandboxes it created are a separate resource with their own receipts, and
- * `Reclaim` is what stops those — the run screen offers it as soon as this succeeds.
+ * `Reclaim` stays on offer: it retries by id any kill the handler could not confirm within its
+ * 10 s deadline. Each sandbox's create-time timeout is the backstop.
  */
 export declare function stopRun(cwd: string, runId: string, intent?: "run" | "analysis"): Promise<TuiActionResult>;

package/dist/tui/actions.js

@@ -1,4 +1,4 @@
-import { requestAutomaticStudyAnalysisCancellation } from "../analysis/automatic.js";
+import { requestAutomaticAnalysisCancellation } from "../analysis/automatic.js";
 // The two things a run card can DO (#455 rev 8).
 //
 // The mock's run screen is an outcome CARD with actions, not a field list, and an action that does
@@ -108,18 +108,20 @@ export function createTuiObserverSession(cwdInput, options = {}) {
  * has children: the CLI, and whatever it spawned to reach the sandbox. Signalling only the parent
  * leaves those orphaned and still working.
  *
- * SIGTERM, never SIGKILL: the run's own handlers get the chance to finalize its record and release
- * what it holds. A killed run leaves a `running` record to go stale, which reads as interrupted —
- * true, but strictly less informative than a run that was told to stop.
+ * SIGTERM, never SIGKILL, so the run's handler gets to act. Outside post-run analysis the run
+ * command (src/cli/commands/run-signals.ts) marks the run `interrupted` in status.json, kills the
+ * E2B sandboxes its receipts name, writes reclaim-receipt.json and exits; run.json keeps its last
+ * live flush. During analysis the signal cancels analysis instead. A local VM's container exits
+ * when the run's process goes.
  *
- * This stops the PROCESS. Sandboxes it created are a separate resource with their own receipts, and
- * `Reclaim` is what stops those — the run screen offers it as soon as this succeeds.
+ * `Reclaim` stays on offer: it retries by id any kill the handler could not confirm within its
+ * 10 s deadline. Each sandbox's create-time timeout is the backstop.
  */
 export async function stopRun(cwd, runId, intent = "run") {
     // The selected action carries its authority. Never infer permission to signal a process from
     // mutable status metadata after the operator asked only to cancel analysis.
     if (intent === "analysis") {
-        const analysis = await requestAutomaticStudyAnalysisCancellation(cwd, runId);
+        const analysis = await requestAutomaticAnalysisCancellation(cwd, runId);
         return {
             schema: TUI_ACTION_SCHEMA,
             ok: analysis.requested,
@@ -153,7 +155,7 @@ export async function stopRun(cwd, runId, intent = "run") {
         };
     }
     if (record.state === "finished") {
-        const analysis = await requestAutomaticStudyAnalysisCancellation(cwd, runId);
+        const analysis = await requestAutomaticAnalysisCancellation(cwd, runId);
         if (analysis.requested)
             return {
                 schema: TUI_ACTION_SCHEMA,
@@ -162,6 +164,13 @@ export async function stopRun(cwd, runId, intent = "run") {
             };
         return { schema: TUI_ACTION_SCHEMA, ok: false, message: "this run already finished" };
     }
+    if (record.state === "interrupted") {
+        return {
+            schema: TUI_ACTION_SCHEMA,
+            ok: false,
+            message: `this run already stopped (${record.signal ?? "interrupted"}); Reclaim releases any sandbox it left`,
+        };
+    }
     const pid = record.pid;
     if (typeof pid !== "number" || !Number.isInteger(pid) || pid <= 1) {
         // pid 1 and below are never a run of ours, and signalling them would be catastrophic.
@@ -198,6 +207,6 @@ export async function stopRun(cwd, runId, intent = "run") {
     return {
         schema: TUI_ACTION_SCHEMA,
         ok: true,
-        message: "asked the run to stop — its sandboxes are separate, so Reclaim them once it reports interrupted",
+        message: "asked the run to stop; it marks itself interrupted and kills its E2B sandboxes, and Reclaim retries any kill it could not confirm",
     };
 }