humanish 0.140.0 → 0.141.0

package/dist/routes/computer-use/e2b-desktop/desktop.js

@@ -1,4 +1,6 @@
+import { externalHandoffReader } from "../../../substrates/e2b/desktop-handoff.js";
 import { createE2BDesktopExecutor } from "../../../substrates/e2b/desktop-executor.js";
+import { e2bShell } from "../../../substrates/e2b/shell.js";
 import { participantInbox, planParticipantComms } from "./comms.js";
 import { participantBrowserStateObserver } from "./fidelity.js";
 import { networkHooks, planParticipantNetwork } from "./network.js";
@@ -37,7 +39,7 @@ export function createE2BParticipantDesktop(spec, deps, warnings) {
     let finalization;
     async function prepare() {
         if (preparationStarted || finalization)
-            throw new Error("Participant desktop preparation can only start once, before finalization.");
+            throw new Error("Participant desktop preparation can only start once, before the desktop is released.");
         preparationStarted = true;
         const desktop = await acquireParticipantDesktop(ctx, state);
         // The device claim is verified in the sandbox, and fails closed.
@@ -52,7 +54,7 @@ export function createE2BParticipantDesktop(spec, deps, warnings) {
     async function openSession() {
         const { desktop, allocation } = state;
         if (!prepared || !desktop || !allocation || opened || finalization)
-            throw new Error("The participant desktop must be prepared and may only be opened once, before finalization.");
+            throw new Error("The participant desktop must be prepared and may only be opened once, before the desktop is released.");
         opened = true;
         await startParticipantStream(ctx, state, desktop);
         const inbox = participantInbox({
@@ -64,21 +66,29 @@ export function createE2BParticipantDesktop(spec, deps, warnings) {
         });
         // Capture that started pairs each checkpoint with the time of the read before it.
         const network = networkHooks(state.network);
-        const executor = createE2BDesktopExecutor(desktop, state.launchedBrowserFamily === "chromium"
-            ? {
-                observeBrowserState: participantBrowserStateObserver({
-                    desktop,
-                    spec,
-                    deps,
-                    targetUrl,
-                    launchIdentity: state.browserLaunchIdentity,
-                    targetId: state.browserTargetId,
-                    fidelity: state.fidelity,
-                    warnings,
-                    ...(network === undefined ? {} : { onClock: network.onClock }),
-                }),
-            }
-            : {});
+        // A web target's browser launch installs the stand-ins that write handed-off links down
+        // (desktop-handoff.ts). Without them the log is absent and every read is empty.
+        const readExternalHandoffs = state.browserLaunched
+            ? externalHandoffReader(e2bShell(desktop), { requestTimeoutMs: deps.requestTimeoutMs })
+            : undefined;
+        const executor = createE2BDesktopExecutor(desktop, {
+            ...(readExternalHandoffs === undefined ? {} : { readExternalHandoffs }),
+            ...(state.launchedBrowserFamily === "chromium"
+                ? {
+                    observeBrowserState: participantBrowserStateObserver({
+                        desktop,
+                        spec,
+                        deps,
+                        targetUrl,
+                        launchIdentity: state.browserLaunchIdentity,
+                        targetId: state.browserTargetId,
+                        fidelity: state.fidelity,
+                        warnings,
+                        ...(network === undefined ? {} : { onClock: network.onClock }),
+                    }),
+                }
+                : {}),
+        });
         return {
             executor: allocation.open(state.speech?.wrap(executor) ?? executor).executor,
             ...(inbox === undefined ? {} : { inbox }),

package/dist/routes/computer-use/e2b-desktop/teardown.js

@@ -106,7 +106,7 @@ export async function finishE2BDesktop(ctx, state, failed) {
                 await deps.receiving.finishParticipant(spec.planned.id);
             }
             catch {
-                warnings.push("Real email finalization is incomplete. Inspect communication cleanup with humanish comms recover.");
+                warnings.push("Real email cleanup is incomplete. Inspect communication cleanup with humanish comms recover.");
             }
         }
         if (ctx.comms && state.commsCatch?.deployed.ready) {

package/dist/routes/computer-use/in-process-desktop.js

@@ -12,12 +12,12 @@ export function createInProcessDesktop(deps) {
     return {
         async prepare() {
             if (preparationStarted || finalization)
-                throw new Error("Participant desktop preparation can only start once, before finalization.");
+                throw new Error("Participant desktop preparation can only start once, before the desktop is released.");
             preparationStarted = true;
         },
         async openSession() {
             if (!preparationStarted || opened || finalization)
-                throw new Error("The participant desktop must be prepared and may only be opened once, before finalization.");
+                throw new Error("The participant desktop must be prepared and may only be opened once, before the desktop is released.");
             opened = true;
             if (deps.inProcessExecutor === undefined)
                 throw new Error("The in-process route needs RunStudyOptions.inProcess.");

package/dist/routes/computer-use/live-phase.js

@@ -110,7 +110,7 @@ export async function runStudyParticipants(setup, participants) {
             await receiving?.finish();
         }
         catch {
-            receivingWarnings.push("Email finalization could not complete. Inspect humanish comms recover; provider cleanup remains unresolved.");
+            receivingWarnings.push("Email cleanup could not complete. Inspect humanish comms recover; provider cleanup remains unresolved.");
         }
         // Stop the flush timer on every exit, including a throw from the participants.
         await liveTrace.stop?.();

package/dist/routes/computer-use/setup.js

@@ -233,8 +233,8 @@ export async function startCuaRun(plan, input, admitted, scope) {
     const { cwd, descriptor, participantRuns, participantPlan, publicRepo } = admitted;
     const { appUrl } = admitted;
     // The run's status record exists from here on, so anything watching the runs directory can
-    // tell which study this is and that it is alive. The fail-closed returns below leave it finished
-    // with no outcome when the scope closes; a crash leaves it stale, which reads as interrupted.
+    // tell which study this is and that it is alive. The fail-closed returns below leave it
+    // interrupted with no outcome when the scope closes; a killed process leaves it stale.
     const started = await scope.startRun(plan, input, {
         cwd,
         prefix: "cua",

package/dist/routes/shared-world/route.js

@@ -226,7 +226,7 @@ async function runPlane(ctx, live, results, plane) {
             await ctx.receiving?.finish();
         }
         catch {
-            ctx.warnings.push("Email finalization could not complete. Inspect humanish comms recover; provider cleanup remains unresolved.");
+            ctx.warnings.push("Email cleanup could not complete. Inspect humanish comms recover; provider cleanup remains unresolved.");
         }
         // Stop the participants' flush timer on every exit, before the final write.
         await live.flush?.stop();

package/dist/run/display.d.ts

@@ -1,6 +1,6 @@
 import type { RunOutcome } from "./bundle.js";
 import type { ExecutionFailure } from "./judge.js";
-import { type RunLiveness } from "./status.js";
+import { type RunAnalysisPhase, type RunLiveness } from "./status.js";
 /** The states a run is shown in. */
 export type RunDisplayState = "running" | "interrupted" | "passed" | "failed" | "blocked" | "timed_out" | "no_verdict" | "dry_run" | "unknown";
 /** A run as a surface shows it. */
@@ -31,6 +31,11 @@ export interface RunDisplayFacts {
  * show as passed.
  */
 export declare function runDisplay(facts: RunDisplayFacts): RunDisplay;
+/**
+ * What a surface shows after a run's display while its automatic analysis runs, or once that
+ * analysis's process stopped without an end: the run's own result stays its participants'.
+ */
+export declare function analysisPhaseLabel(phase: RunAnalysisPhase | undefined): string | undefined;
 /** A state in words: "passed", "timed out", "no verdict". */
 export declare function runDisplayLabel(state: RunDisplayState): string;
 /** What bundleDisplayFacts reads from run.json; a listing reads it from an unchecked file. */

package/dist/run/display.js

@@ -61,6 +61,17 @@ export function runDisplay(facts) {
         return shown(facts.mode === "dry-run" ? "dry_run" : "no_verdict");
     return shown("unknown");
 }
+/**
+ * What a surface shows after a run's display while its automatic analysis runs, or once that
+ * analysis's process stopped without an end: the run's own result stays its participants'.
+ */
+export function analysisPhaseLabel(phase) {
+    if (phase?.state === "running")
+        return "analyzing";
+    if (phase?.state === "stopped")
+        return "analysis stopped";
+    return undefined;
+}
 /** A state in words: "passed", "timed out", "no verdict". */
 export function runDisplayLabel(state) {
     return LABELS[state];

package/dist/run/host-suspension.js

@@ -19,7 +19,10 @@ export const systemHostClock = {
 };
 /**
  * A wall-clock gap between two heartbeats this long or longer is a suspension. A shorter one is
- * most likely a busy event loop.
+ * most likely a busy event loop. It is twice RUN_STATUS_STALE_MS (src/run/status.ts) on purpose:
+ * that threshold is a reader's guess, made without the writer, so it errs early; this one is the
+ * writer's own record, and a route blames participant failures on it, so it errs late. A pause of
+ * 15 to 30 s reads as stale while it lasts and leaves no suspension on record.
  */
 const HOST_SUSPENSION_MIN_MS = 30_000;
 /** Run `onTick` every `intervalMs` on `clock`, and record each gap of 30 s or more. */

package/dist/run/preflight-receipts.d.ts

@@ -1,16 +1,7 @@
+import { type ProcessOwner } from "./process-owner.js";
 import { type PreparedSelectedOutputDirectory } from "./contained-output.js";
-/**
- * Who opened a journal. A pid means nothing outside its host and pid namespace (a probe in a
- * container writing to a bind-mounted checkout has a pid the host cannot see), so reclaim trusts
- * a dead pid only when both match its own.
- */
-interface PreflightOwner {
-    hostname: string;
-    /** `pid:[inode]` from /proc/self/ns/pid, where the platform has one. */
-    pidNamespace?: string;
-    pid: number;
-    /** Start time in clock ticks since boot (/proc/<pid>/stat), which tells a reused pid apart. */
-    startTicks?: string;
+/** Who opened a journal (src/run/process-owner.ts), when, and for how long. */
+interface PreflightOwner extends ProcessOwner {
     createdAt: string;
     /** The probe's server-side timeout. */
     leaseMs: number;

package/dist/run/preflight-receipts.js

@@ -3,11 +3,10 @@
 // removes the journal. A journal that stays means the probe's sandbox may still be running, and
 // `humanish reclaim --preflight` kills it by the recorded id once it is safe to.
 import { randomBytes } from "node:crypto";
-import { existsSync, readFileSync, readlinkSync } from "node:fs";
 import { readdir, rmdir, unlink } from "node:fs/promises";
-import { hostname } from "node:os";
 import path from "node:path";
 import { parseSandboxReceipts, SANDBOX_RECEIPTS_ARTIFACT } from "./sandbox-receipts.js";
+import { currentProcessOwner, processOwnerGone, processOwnerOf, } from "./process-owner.js";
 import { assertPreparedSelectedOutputDirectory, bindExistingManagedHumanishOutputDirectory, prepareManagedHumanishOutputDirectory, readContainedRegularFile, RUN_ARTIFACT_MAX_BYTES, writeContainedOutputFile, } from "./contained-output.js";
 const PREFLIGHT_DIR = "preflight";
 // Written when the probe finished without confirming its kill: the owner no longer holds the
@@ -15,39 +14,13 @@ const PREFLIGHT_DIR = "preflight";
 const ABANDONED_MARKER = "abandoned";
 const OWNER_FILE = "owner.json";
 const JOURNAL_NAME = /^preflight-\d+-[a-z0-9-]+$/;
-function ownerContext() {
-    let pidNamespace;
-    try {
-        pidNamespace = readlinkSync("/proc/self/ns/pid");
-    }
-    catch {
-        // No procfs: this platform has no pid namespaces to tell apart.
-    }
-    return { hostname: hostname(), ...(pidNamespace === undefined ? {} : { pidNamespace }) };
-}
-/** The process's start ticks; null when procfs says it is gone; undefined without procfs. */
-function startTicks(pid) {
-    if (!existsSync("/proc/self/stat"))
-        return undefined;
-    try {
-        const stat = readFileSync(`/proc/${pid}/stat`, "utf8");
-        // Field 22; the command name before it is parenthesized and may contain spaces.
-        return stat.slice(stat.lastIndexOf(")") + 2).split(" ")[19] ?? null;
-    }
-    catch {
-        return null;
-    }
-}
 /** Create this process's journal directory for one probe with the given lease. */
 export async function openPreflightJournal(cwd, leaseMs) {
     const stamp = new Date().toISOString().replace(/[:.]/g, "-").toLowerCase();
     const id = `preflight-${process.pid}-${stamp}-${randomBytes(4).toString("hex")}`;
     const root = await prepareManagedHumanishOutputDirectory(cwd, PREFLIGHT_DIR, id);
-    const ticks = startTicks(process.pid);
     const owner = {
-        ...ownerContext(),
-        pid: process.pid,
-        ...(typeof ticks === "string" ? { startTicks: ticks } : {}),
+        ...currentProcessOwner(),
         createdAt: new Date().toISOString(),
         leaseMs,
     };
@@ -60,19 +33,12 @@ function parseOwner(read) {
         return undefined;
     try {
         const value = JSON.parse(read.bytes.toString("utf8"));
-        if (typeof value.hostname !== "string" ||
-            typeof value.pid !== "number" ||
+        const owner = processOwnerOf(value);
+        if (owner === undefined ||
             typeof value.createdAt !== "string" ||
             typeof value.leaseMs !== "number")
             return undefined;
-        return {
-            hostname: value.hostname,
-            ...(typeof value.pidNamespace === "string" ? { pidNamespace: value.pidNamespace } : {}),
-            pid: value.pid,
-            ...(typeof value.startTicks === "string" ? { startTicks: value.startTicks } : {}),
-            createdAt: value.createdAt,
-            leaseMs: value.leaseMs,
-        };
+        return { ...owner, createdAt: value.createdAt, leaseMs: value.leaseMs };
     }
     catch {
         return undefined;
@@ -133,34 +99,8 @@ export async function preflightReclaimDecision(journal, nowMs) {
     const owner = journal.owner;
     if (owner === undefined)
         return { reclaim: false, reason: `its owner record is missing or unreadable${until}` };
-    const here = ownerContext();
-    if (owner.hostname !== here.hostname || owner.pidNamespace !== here.pidNamespace)
-        return {
-            reclaim: false,
-            reason: `it was opened on host ${owner.hostname} in another host or pid namespace, where this process cannot see whether it is still running${until}`,
-        };
-    const running = `process ${owner.pid} is still running${until}`;
-    if (owner.pid === process.pid)
-        return { reclaim: false, reason: running };
-    const ticks = startTicks(owner.pid);
-    if (ticks === null)
-        return { reclaim: true };
-    if (typeof ticks === "string") {
-        // The pid now belongs to a different process: the owner is gone.
-        return owner.startTicks !== undefined && ticks !== owner.startTicks
-            ? { reclaim: true }
-            : { reclaim: false, reason: running };
-    }
-    try {
-        process.kill(owner.pid, 0);
-        return { reclaim: false, reason: running };
-    }
-    catch (error) {
-        // EPERM: the process exists but belongs to someone else.
-        return error.code === "EPERM"
-            ? { reclaim: false, reason: running }
-            : { reclaim: true };
-    }
+    const gone = processOwnerGone(owner);
+    return gone.gone ? { reclaim: true } : { reclaim: false, reason: `${gone.reason}${until}` };
 }
 /**
  * Remove a journal whose sandbox is confirmed gone. Only the files humanish writes there and the

package/dist/run/process-owner.d.ts

@@ -0,0 +1,28 @@
+/**
+ * A process, as recorded by itself. A pid means nothing outside its host and pid namespace (a
+ * process in a container writing to a bind-mounted checkout has a pid the host cannot see), so a
+ * dead pid is trusted only when both match the reader's own.
+ */
+export interface ProcessOwner {
+    hostname: string;
+    /** `pid:[inode]` from /proc/self/ns/pid, where the platform has one. */
+    pidNamespace?: string;
+    pid: number;
+    /** Start time in clock ticks since boot (/proc/<pid>/stat), which tells a reused pid apart. */
+    startTicks?: string;
+}
+/** This process, as an owner record names it. */
+export declare function currentProcessOwner(): ProcessOwner;
+/** The owner fields of a parsed record, or undefined when `hostname` or `pid` is missing. */
+export declare function processOwnerOf(value: Record<string, unknown>): ProcessOwner | undefined;
+/**
+ * Whether `owner` is gone: it ran in this host and pid namespace, and its pid is free or now
+ * belongs to a process that started at another time. Otherwise the reason says why it may still
+ * be running.
+ */
+export declare function processOwnerGone(owner: ProcessOwner): {
+    gone: true;
+} | {
+    gone: false;
+    reason: string;
+};

package/dist/run/process-owner.js

@@ -0,0 +1,83 @@
+// Which process owns a file humanish leaves on disk, and whether that process is still running.
+// `reclaim --preflight` reads it from a probe's journal and the analysis lock from its owner file,
+// so both decide "the owner is gone" by one rule.
+import { existsSync, readFileSync, readlinkSync } from "node:fs";
+import { hostname } from "node:os";
+function ownerContext() {
+    let pidNamespace;
+    try {
+        pidNamespace = readlinkSync("/proc/self/ns/pid");
+    }
+    catch {
+        // No procfs: this platform has no pid namespaces to tell apart.
+    }
+    return { hostname: hostname(), ...(pidNamespace === undefined ? {} : { pidNamespace }) };
+}
+/** The process's start ticks; null when procfs says it is gone; undefined without procfs. */
+function startTicks(pid) {
+    if (!existsSync("/proc/self/stat"))
+        return undefined;
+    try {
+        const stat = readFileSync(`/proc/${pid}/stat`, "utf8");
+        // Field 22; the command name before it is parenthesized and may contain spaces.
+        return stat.slice(stat.lastIndexOf(")") + 2).split(" ")[19] ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+/** This process, as an owner record names it. */
+export function currentProcessOwner() {
+    const ticks = startTicks(process.pid);
+    return {
+        ...ownerContext(),
+        pid: process.pid,
+        ...(typeof ticks === "string" ? { startTicks: ticks } : {}),
+    };
+}
+/** The owner fields of a parsed record, or undefined when `hostname` or `pid` is missing. */
+export function processOwnerOf(value) {
+    if (typeof value.hostname !== "string" || typeof value.pid !== "number")
+        return undefined;
+    return {
+        hostname: value.hostname,
+        ...(typeof value.pidNamespace === "string" ? { pidNamespace: value.pidNamespace } : {}),
+        pid: value.pid,
+        ...(typeof value.startTicks === "string" ? { startTicks: value.startTicks } : {}),
+    };
+}
+/**
+ * Whether `owner` is gone: it ran in this host and pid namespace, and its pid is free or now
+ * belongs to a process that started at another time. Otherwise the reason says why it may still
+ * be running.
+ */
+export function processOwnerGone(owner) {
+    const here = ownerContext();
+    if (owner.hostname !== here.hostname || owner.pidNamespace !== here.pidNamespace)
+        return {
+            gone: false,
+            reason: `it was opened on host ${owner.hostname} in another host or pid namespace, where this process cannot see whether it is still running`,
+        };
+    const running = `process ${owner.pid} is still running`;
+    if (owner.pid === process.pid)
+        return { gone: false, reason: running };
+    const ticks = startTicks(owner.pid);
+    if (ticks === null)
+        return { gone: true };
+    if (typeof ticks === "string") {
+        // The pid now belongs to a different process: the owner is gone.
+        return owner.startTicks !== undefined && ticks !== owner.startTicks
+            ? { gone: true }
+            : { gone: false, reason: running };
+    }
+    try {
+        process.kill(owner.pid, 0);
+        return { gone: false, reason: running };
+    }
+    catch (error) {
+        // EPERM: the process exists but belongs to someone else.
+        return error.code === "EPERM"
+            ? { gone: false, reason: running }
+            : { gone: true };
+    }
+}

package/dist/run/projection.js

@@ -84,7 +84,7 @@ export function expectationFor(entries, mode) {
         .filter((value) => value !== undefined)
         .sort((a, b) => a - b);
     // A cost is unknown whether it was declared absent (`null`) or never recorded at all
-    // (`undefined`: every fail-closed exit finalized with no outcome). Counting only the first
+    // (`undefined`, as earlier versions left a run closed without a bundle). Counting only the first
     // reports "~$1.20 median · 3 runs" for a sample where two runs were never priced, which claims a
     // denominator the figure does not have.
     const costUnknown = finished.filter((entry) => entry.estimatedCostUsd === null || entry.estimatedCostUsd === undefined).length;

package/dist/run/reclaim.d.ts

@@ -25,6 +25,12 @@ export interface ReclaimResult {
      * route created none for this run. Reclaim then contacts E2B for nothing.
      */
     reason?: NoSandboxReason;
+    /**
+     * True when this reclaim found the run's status.json still `running` with a stale heartbeat and
+     * recorded it `interrupted` (reason `reclaimed`): the process is gone or no longer updating it,
+     * and its sandboxes are being stopped. Absent when it changed nothing.
+     */
+    markedInterrupted?: true;
     warnings: string[];
     error?: {
         code: "HUMANISH_RECLAIM_RUN_NOT_FOUND" | "HUMANISH_RECLAIM_E2B_DEBUG" | "HUMANISH_RECLAIM_MODULE_UNAVAILABLE" | "HUMANISH_RECLAIM_RECEIPTS_UNREADABLE";

package/dist/run/reclaim.js

@@ -12,11 +12,11 @@
 import { e2bAccount, e2bConnection } from "../substrates/e2b/connection.js";
 import { modalAccount } from "../substrates/modal/sandbox.js";
 import { E2B_DEBUG_ENV, e2bDebugMode, loadE2BDesktopModule, } from "../substrates/e2b/sdk.js";
-import { readContainedRegularFile, refusalText, RUN_ARTIFACT_MAX_BYTES, } from "./contained-output.js";
+import { readContainedRegularFile, refusalText, RUN_ARTIFACT_MAX_BYTES, writeContainedOutputFile, } from "./contained-output.js";
 import { discardPreflightJournal, listPreflightJournals, preflightReclaimDecision, } from "./preflight-receipts.js";
 import { readRunJsonIfExists, resolveRunPath, runJsonValue } from "./locate.js";
 import { RUN_BUNDLE_FILE } from "./bundle.js";
-import { RUN_STATUS_FILE } from "./status.js";
+import { classifyRunStatus, isRunStatusRecord, RUN_STATUS_FILE, } from "./status.js";
 import { isRecord } from "./type-guards.js";
 import { isRunOutcome } from "./bundle-shape.js";
 import { parseSandboxOwners, parseSandboxReceipts, SANDBOX_RECEIPTS_ARTIFACT, } from "./sandbox-receipts.js";
@@ -66,6 +66,15 @@ async function reclaimRun(cwd, runInput, locate, hooks) {
             },
         };
     }
+    // A kill by hand, not a check and not the signal handler (whose run is alive and records its
+    // own interrupt): a run whose heartbeat stopped is over once its sandboxes are stopped.
+    const marked = hooks.check !== true &&
+        hooks.creates === undefined &&
+        (await markStaleRunInterrupted(runPaths, Date.now()).catch(() => false));
+    const result = await reclaimLocated(runPaths, base, hooks, warnings);
+    return marked ? { ...result, markedInterrupted: true } : result;
+}
+async function reclaimLocated(runPaths, base, hooks, warnings) {
     const runId = runIdOf(runPaths);
     // The signal handler passes the creates it stopped and decides from what they reported.
     const reason = hooks.creates === undefined ? await recordedNoSandbox(runPaths) : undefined;
@@ -424,3 +433,24 @@ async function reclaimRoot(root, label, hooks, warnings) {
         createsInFlight,
     };
 }
+/**
+ * For `humanish reclaim`, which stops the run's sandboxes: a `running` record whose heartbeat is
+ * stale becomes `interrupted` with reason `reclaimed` and `completedAt` at its last heartbeat. A
+ * fresh record belongs to a live owner and is left alone, as is one that already ended. True when
+ * it wrote one.
+ */
+async function markStaleRunInterrupted(runPaths, nowMs) {
+    const record = runJsonValue(await readRunJsonIfExists(runPaths, RUN_STATUS_FILE));
+    if (!isRunStatusRecord(record) || record.state !== "running")
+        return false;
+    if (classifyRunStatus(record, nowMs) === "running")
+        return false;
+    const marked = {
+        ...record,
+        state: "interrupted",
+        reason: "reclaimed",
+        completedAt: record.updatedAt,
+    };
+    await writeContainedOutputFile(runPaths, RUN_STATUS_FILE, `${JSON.stringify(marked, null, 2)}\n`, "utf8");
+    return true;
+}

package/dist/run/route-shell.js

@@ -30,7 +30,7 @@ export async function admitRoute(shell) {
             // The scorer joins the input only; whatever the checks admitted stays what the run uses.
             const input = shell.withScorer?.(shell.input, scorer) ?? shell.input;
             const run = async () => {
-                const { result, finished } = await runScope((scope) => shell.runInScope(admitted, input, scope));
+                const { result, finished } = await runScope((scope) => shell.runInScope(admitted, input, scope), { onStart: (runId) => input.emit?.({ type: "run-started", runId }) });
                 return complete(input, result, finished);
             };
             return routeOutcome(shell.route, await (shell.commsSecrets ? withTransientCommsSecrets(run) : run()));

package/dist/run/run-index.d.ts

@@ -1,6 +1,6 @@
 import { AnalysisCostCache } from "./run-index-analysis.js";
 import type { RunAnalysisCost } from "./run-cost.js";
-import { type RunLiveness } from "./status.js";
+import { type RunAnalysisPhase, type RunLiveness } from "./status.js";
 import { type RunStudyProvenance } from "./study-provenance.js";
 import type { ExecutionFailure } from "./judge.js";
 declare const RUN_INDEX_SCHEMA = "humanish.run-index.v1";
@@ -42,6 +42,8 @@ export interface RunIndexEntry {
     analysisCost?: RunAnalysisCost;
     /** Wall-clock span when both ends are known; used for per-study medians. */
     durationMs?: number;
+    /** The automatic analysis the run's own process started after the run ended, from status.json. */
+    analysis?: RunAnalysisPhase;
 }
 export interface RunIndexResult {
     schema: typeof RUN_INDEX_SCHEMA;

package/dist/run/run-index.js

@@ -5,7 +5,7 @@ import { readdir, readFile, stat } from "node:fs/promises";
 import path from "node:path";
 import { runLiveness } from "./liveness.js";
 import { AnalysisCostCache, readIndexedAnalysisCost } from "./run-index-analysis.js";
-import { RUN_STATUS_FILE, classifyRunStatus, isRunStatusRecord, } from "./status.js";
+import { RUN_STATUS_FILE, classifyRunStatus, isRunStatusRecord, runAnalysisPhase, } from "./status.js";
 import { studyProvenanceOf } from "./study-provenance.js";
 import { RUN_BUNDLE_FILE } from "./bundle.js";
 import { isRunOutcome } from "./bundle-shape.js";
@@ -63,6 +63,7 @@ async function readJson(file) {
 function entryFromStatus(record, nowMs) {
     const started = Date.parse(record.startedAt);
     const ended = record.completedAt === undefined ? Number.NaN : Date.parse(record.completedAt);
+    const analysis = runAnalysisPhase(record, nowMs);
     return {
         runId: record.runId,
         derivedFrom: "status",
@@ -88,6 +89,7 @@ function entryFromStatus(record, nowMs) {
             ? { estimatedCostComplete: record.outcome.estimatedCostComplete }
             : {}),
         ...(Number.isFinite(started) && Number.isFinite(ended) ? { durationMs: ended - started } : {}),
+        ...(analysis === undefined ? {} : { analysis }),
     };
 }
 /** A status record this run can be classified from: well formed and naming this run. */
@@ -168,16 +170,8 @@ async function readEntry(runId, runDir, cache, nowMs) {
     const [statusKey, bundleKey] = await Promise.all([statKey(statusFile), statKey(bundleFile)]);
     const key = JSON.stringify([statusKey, bundleKey]);
     const cached = cache?.get(runId, key);
-    if (cached !== undefined) {
-        return cached.derivedFrom === "status" &&
-            cached.updatedAt !== undefined &&
-            cached.completedAt === undefined
-            ? {
-                ...cached,
-                liveness: classifyRunStatus({ state: "running", updatedAt: cached.updatedAt }, nowMs),
-            }
-            : cached;
-    }
+    if (cached !== undefined)
+        return withCurrentLiveness(cached, nowMs);
     const [status, raw] = await Promise.all([
         statusKey === null ? undefined : readJson(statusFile),
         bundleKey === null ? undefined : readJson(bundleFile),
@@ -196,6 +190,7 @@ async function readEntry(runId, runDir, cache, nowMs) {
                     updatedAt: metadata.updatedAt,
                     ...(metadata.completedAt === undefined ? {} : { completedAt: metadata.completedAt }),
                     ...(metadata.durationMs === undefined ? {} : { durationMs: metadata.durationMs }),
+                    ...(metadata.analysis === undefined ? {} : { analysis: metadata.analysis }),
                     ...studyEntry(metadata.study),
                 }),
             ...entryFromBundle(runId, bundle),
@@ -216,6 +211,23 @@ async function readEntry(runId, runDir, cache, nowMs) {
     cache?.set(runId, key, entry);
     return entry;
 }
+/**
+ * A cached entry read again at `nowMs`. Its file has not changed, but a live run or a running
+ * analysis goes stale with time alone, so both are classified again from the cached heartbeat.
+ */
+function withCurrentLiveness(cached, nowMs) {
+    if (cached.updatedAt === undefined)
+        return cached;
+    if (cached.derivedFrom === "status" && cached.completedAt === undefined)
+        return {
+            ...cached,
+            liveness: classifyRunStatus({ state: "running", updatedAt: cached.updatedAt }, nowMs),
+        };
+    if (cached.analysis === undefined || cached.analysis.state === "ended")
+        return cached;
+    const analysis = runAnalysisPhase({ updatedAt: cached.updatedAt, analysis: { startedAt: cached.analysis.startedAt } }, nowMs);
+    return analysis === undefined ? cached : { ...cached, analysis };
+}
 /** Newest-first ordering: the most recent thing known about a run, else its id's own timestamp. */
 function sortKey(entry) {
     for (const candidate of [entry.completedAt, entry.updatedAt, entry.startedAt]) {