humanish 0.139.1 → 0.141.0

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()));
@@ -42,7 +42,7 @@ export async function admitRoute(shell) {
  * or default analysis is recorded as skipped.
  */
 export function completeRefusalAnalysis(refused, config, input) {
-    const analysis = resolveAutomaticAnalysis(config.review?.analysis);
+    const analysis = resolveAutomaticAnalysis(config.review?.analysis, config.actor);
     return completeAutomaticAnalysis(refused, undefined, analysis.ok ? analysis.config : undefined, input, { trigger: config.review?.analysis === undefined ? "default" : "explicit" });
 }
 /** A result as its route's outcome. StudyOutcome pairs each route with its result type. */

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]) {

package/dist/run/run.d.ts

@@ -3,6 +3,7 @@ import { type RunBundle } from "./bundle.js";
 import { type ExecutionFailure, type ExecutionOutcome, type OutcomePolicy } from "./judge.js";
 import { type PreparedRunArtifactPaths, type RunIdInUse } from "./paths.js";
 import { RunSecrets } from "./secrets.js";
+import { type RunStatusHandle } from "./status.js";
 import { type HostClock, type HostSuspension } from "./host-suspension.js";
 import type { RunStudyProvenance } from "./study-provenance.js";
 interface StartRunOptions {
@@ -170,7 +171,7 @@ export declare class FinishedRun {
     readonly runId: string;
     /** The paths created by startRun and validated at the start of `finish`. */
     readonly paths: PreparedRunArtifactPaths;
-    constructor(key: typeof issueKey, runId: string, paths: PreparedRunArtifactPaths, observer: ObserverTarget | undefined, outcome: RecordedOutcome, recordFailure: (failure: ExecutionFailure) => Promise<RecordedOutcome>, interrupted: () => boolean, participantsRan: () => boolean);
+    constructor(key: typeof issueKey, runId: string, paths: PreparedRunArtifactPaths, observer: ObserverTarget | undefined, outcome: RecordedOutcome, recordFailure: (failure: ExecutionFailure) => Promise<RecordedOutcome>, status: Pick<RunStatusHandle, "interrupted" | "beginAnalysis">, participantsRan: () => boolean);
     /**
      * A signal stopped this run's process: status.json and run.json record it `interrupted`. Read
      * when asked, since the signal can arrive after the bundle was published.
@@ -178,6 +179,12 @@ export declare class FinishedRun {
     get interrupted(): boolean;
     /** The route reported a participant's session started (Run.participantStarted). */
     get participantsRan(): boolean;
+    /**
+     * Automatic analysis of this run starts in this process: status.json records when, and its
+     * heartbeat runs again, so every surface can say the run is analyzing. Call the returned
+     * function with the analysis outcome's state when it ends. After an interrupt both do nothing.
+     */
+    beginAnalysis(): ReturnType<RunStatusHandle["beginAnalysis"]>;
     static isIssued(value: unknown): value is FinishedRun;
     /**
      * The run's ok and execution outcome as run.json records them: what the route passed to
@@ -195,12 +202,16 @@ export declare class FinishedRun {
 /**
  * Run `fn` as the lifetime of at most one run. When `fn` settles the scope closes synchronously,
  * so the scope and its run admit no further calls, even through references `fn` leaked into
- * timers or callbacks. It then waits for the calls it admitted and, unless the run finished,
- * finishes status.json with no outcome. The close cannot replace `fn`'s exception: admitted calls
- * are awaited settled and the status finish swallows its own write errors. `finished` is set only
+ * timers or callbacks. It then waits for the calls it admitted and, unless the run published,
+ * records status.json `interrupted` with reason `no-publish`: a run with no published bundle did
+ * not finish, so no surface shows it as passed or counts it in a study's durations. The close cannot replace `fn`'s exception: admitted calls
+ * are awaited settled and the status write swallows its own errors. `finished` is set only
  * when `Run.finish` resolved inside the scope, so a refusal cannot hand analysis another run.
  */
-export declare function runScope<T>(fn: (scope: RunScope) => Promise<T>): Promise<{
+export declare function runScope<T>(fn: (scope: RunScope) => Promise<T>, hooks?: {
+    /** The run exists: its directory and first status.json write landed. A throw is ignored. */
+    onStart?: (runId: string) => void;
+}): Promise<{
     result: T;
     finished: FinishedRun | undefined;
 }>;

package/dist/run/run.js

@@ -35,34 +35,42 @@ const issueKey = Symbol("FinishedRun");
 export class FinishedRun {
     #observer;
     #recordFailure;
-    #interrupted;
     #outcome;
     runId;
     /** The paths created by startRun and validated at the start of `finish`. */
     paths;
     #participantsRan;
-    constructor(key, runId, paths, observer, outcome, recordFailure, interrupted, participantsRan) {
+    #status;
+    constructor(key, runId, paths, observer, outcome, recordFailure, status, participantsRan) {
         if (key !== issueKey)
             throw new Error("Only Run.finish issues a FinishedRun.");
         this.runId = runId;
         this.paths = paths;
         this.#participantsRan = participantsRan;
+        this.#status = status;
         this.#observer = observer;
         this.#outcome = outcome;
         this.#recordFailure = recordFailure;
-        this.#interrupted = interrupted;
     }
     /**
      * A signal stopped this run's process: status.json and run.json record it `interrupted`. Read
      * when asked, since the signal can arrive after the bundle was published.
      */
     get interrupted() {
-        return this.#interrupted();
+        return this.#status.interrupted;
     }
     /** The route reported a participant's session started (Run.participantStarted). */
     get participantsRan() {
         return this.#participantsRan();
     }
+    /**
+     * Automatic analysis of this run starts in this process: status.json records when, and its
+     * heartbeat runs again, so every surface can say the run is analyzing. Call the returned
+     * function with the analysis outcome's state when it ends. After an interrupt both do nothing.
+     */
+    beginAnalysis() {
+        return this.#status.beginAnalysis();
+    }
     static isIssued(value) {
         return typeof value === "object" && value !== null && #observer in value;
     }
@@ -262,7 +270,7 @@ function runPublisher(args) {
             await writeBundleFiles(bundle, finishedOutcome(current), (publicBundle) => runStatus.restate(runStatusOutcome(publicBundle))).catch(() => undefined);
             return current;
         }));
-        return new FinishedRun(issueKey, runId, paths, observer, current, recordFailure, () => runStatus.interrupted, participantsRan);
+        return new FinishedRun(issueKey, runId, paths, observer, current, recordFailure, runStatus, participantsRan);
     };
     const interrupt = async (signal) => {
         interrupted = { state: "interrupted", ok: false, signal, at: new Date(now()).toISOString() };
@@ -287,12 +295,13 @@ function runPublisher(args) {
 /**
  * Run `fn` as the lifetime of at most one run. When `fn` settles the scope closes synchronously,
  * so the scope and its run admit no further calls, even through references `fn` leaked into
- * timers or callbacks. It then waits for the calls it admitted and, unless the run finished,
- * finishes status.json with no outcome. The close cannot replace `fn`'s exception: admitted calls
- * are awaited settled and the status finish swallows its own write errors. `finished` is set only
+ * timers or callbacks. It then waits for the calls it admitted and, unless the run published,
+ * records status.json `interrupted` with reason `no-publish`: a run with no published bundle did
+ * not finish, so no surface shows it as passed or counts it in a study's durations. The close cannot replace `fn`'s exception: admitted calls
+ * are awaited settled and the status write swallows its own errors. `finished` is set only
  * when `Run.finish` resolved inside the scope, so a refusal cannot hand analysis another run.
  */
-export async function runScope(fn) {
+export async function runScope(fn, hooks = {}) {
     let closed = false;
     let started = false;
     let status;
@@ -339,6 +348,12 @@ export async function runScope(fn) {
                 },
             });
             await runStatus.started;
+            try {
+                hooks.onStart?.(runId);
+            }
+            catch {
+                // An announcement cannot stop the run it announces.
+            }
             const run = openRun(options, runId, created.paths, runStatus);
             interruptBundle = run.interrupt;
             return { ok: true, run: run.run };
@@ -414,7 +429,7 @@ export async function runScope(fn) {
         }
         finally {
             if (finished === undefined)
-                await status?.finish();
+                await status?.abandon();
             unregister?.();
         }
     }

package/dist/run/status.d.ts

@@ -1,3 +1,4 @@
+import type { AutomaticAnalysisOutcome } from "../analysis/job.js";
 import type { RunBundle } from "./bundle.js";
 import { type RunStudyProvenance } from "./study-provenance.js";
 import { type PreparedOutputRoot } from "./contained-output.js";
@@ -10,11 +11,26 @@ export declare const RUN_STATUS_FILE = "status.json";
 export declare const RUN_STATUS_TOUCH_MS = 5000;
 /**
  * A `running` record whose `updatedAt` is older than this is interrupted, not alive: the process
- * died without finalizing (a dropped SSH, a killed terminal, a crash). Three touch intervals of
+ * died before the run ended (a dropped SSH, a killed terminal, a crash). Three touch intervals of
  * slack so an ordinary scheduling hiccup or a slow disk never mislabels a healthy run.
  */
 export declare const RUN_STATUS_STALE_MS: number;
 type RunStatusState = "running" | "finished" | "interrupted";
+/**
+ * Why a run is `interrupted` without a signal. `no-publish`: its process left the run without
+ * publishing a bundle, as a route that throws or returns a refusal after the run started does.
+ * `reclaimed`: `humanish reclaim` found its heartbeat stale and stopped its sandboxes.
+ */
+type RunInterruptReason = "no-publish" | "reclaimed";
+/** How automatic analysis ended, as its job records it. */
+type RunAnalysisEndState = AutomaticAnalysisOutcome["state"];
+/** Automatic analysis in the run's own process, after the run ended. */
+interface RunStatusAnalysis {
+    startedAt: string;
+    /** Absent while it runs, and on the record of a process that stopped during it. */
+    endedAt?: string;
+    state?: RunAnalysisEndState;
+}
 /** The signals the CLI's run handler records when it stops a run. */
 export type RunInterruptSignal = "SIGINT" | "SIGTERM" | "SIGHUP";
 /** The outcome summary a finalized record carries. Derived from the bundle; never authoritative. */
@@ -67,7 +83,14 @@ export interface RunStatusRecord {
     completedAt?: string;
     /** The signal that stopped the run, on an `interrupted` record. */
     signal?: RunInterruptSignal;
+    /** Why an `interrupted` record has no signal. */
+    reason?: RunInterruptReason;
     outcome?: RunStatusOutcome;
+    /**
+     * Set on a `finished` record when automatic analysis starts in the same process. While it
+     * runs, the heartbeat keeps `updatedAt` fresh; `completedAt` stays when the participants ended.
+     */
+    analysis?: RunStatusAnalysis;
 }
 export interface RunStatusHandle {
     /** Resolves once the initial record has landed on disk, and never rejects: a failed write is
@@ -75,7 +98,8 @@ export interface RunStatusHandle {
      *  it before a route can acquire a sandbox, so a run killed after its sandbox receipt lands
      *  still has a record to classify. */
     readonly started: Promise<void>;
-    /** Finalize: state `finished`, `completedAt`, and the derived outcome. Stops the cadence.
+    /** The run ended with a published bundle: state `finished`, `completedAt`, and the derived
+     *  outcome. Stops the cadence.
      *  Idempotent: a second call is a no-op, so a route with several exit paths is safe. */
     finish(outcome?: RunStatusOutcome): Promise<void>;
     /** After finish, replace the finished record's outcome with one read from a rewritten run.json,
@@ -88,6 +112,15 @@ export interface RunStatusHandle {
     interrupt(signal: RunInterruptSignal): Promise<boolean>;
     /** True from the moment `interrupt` accepts a signal, before its write lands. */
     readonly interrupted: boolean;
+    /** The run's scope closed without a publish: state `interrupted` with reason `no-publish`. A
+     *  no-op after finish or an interrupt, so it never overwrites a record that says more. */
+    abandon(): Promise<void>;
+    /**
+     * After finish, automatic analysis starts: `analysis.startedAt` is written and the heartbeat
+     * runs again until the returned function records the end and its state. Before finish or after
+     * an interrupt it writes nothing, and neither does the returned function.
+     */
+    beginAnalysis(): Promise<(state: RunAnalysisEndState) => Promise<void>>;
     /** The host suspensions the cadence saw until now, or until it stopped. */
     suspensions(): readonly HostSuspension[];
 }
@@ -114,6 +147,28 @@ export type RunLiveness = "running" | "interrupted" | "finished";
  * `nowMs` is passed in rather than read, so a classification is reproducible.
  */
 export declare function classifyRunStatus(record: Pick<RunStatusRecord, "state" | "updatedAt">, nowMs: number, staleMs?: number): RunLiveness;
+/** Automatic analysis as a status record shows it: running, ended, or stopped with its process. */
+export type RunAnalysisPhase = {
+    state: "running" | "stopped";
+    startedAt: string;
+} | {
+    state: "ended";
+    startedAt: string;
+    endedAt: string;
+    outcome?: RunAnalysisEndState;
+};
+/**
+ * The record's automatic analysis. `stopped` is an analysis with no end whose heartbeat went
+ * stale: the process ended during it. Undefined when the record has none, or one this version
+ * cannot read.
+ */
+export declare function runAnalysisPhase(record: Pick<RunStatusRecord, "updatedAt" | "analysis">, nowMs: number): RunAnalysisPhase | undefined;
+/**
+ * A `running` record whose heartbeat is stale and whose pid no process on this host holds: its
+ * owner is gone, so the run cannot still be writing. A live pid proves nothing either way (pids
+ * are reused), so such a record stays unconfirmed.
+ */
+export declare function runOwnerGone(record: Pick<RunStatusRecord, "state" | "pid" | "updatedAt">, nowMs: number, running?: (pid: number) => boolean): boolean;
 /** Shape guard for a record read off disk. Unknown extra fields are tolerated (additive contract). */
 export declare function isRunStatusRecord(value: unknown): value is RunStatusRecord;
 export {};

package/dist/run/status.js

@@ -20,7 +20,7 @@ export const RUN_STATUS_FILE = "status.json";
 export const RUN_STATUS_TOUCH_MS = 5_000;
 /**
  * A `running` record whose `updatedAt` is older than this is interrupted, not alive: the process
- * died without finalizing (a dropped SSH, a killed terminal, a crash). Three touch intervals of
+ * died before the run ended (a dropped SSH, a killed terminal, a crash). Three touch intervals of
  * slack so an ordinary scheduling hiccup or a slow disk never mislabels a healthy run.
  */
 export const RUN_STATUS_STALE_MS = RUN_STATUS_TOUCH_MS * 3;
@@ -132,6 +132,48 @@ export function beginRunStatus(runPaths, options) {
         get interrupted() {
             return interrupted;
         },
+        async abandon() {
+            if (finished)
+                return;
+            finished = true;
+            heartbeat.stop();
+            const completedAt = iso();
+            await write({
+                ...base,
+                state: "interrupted",
+                updatedAt: completedAt,
+                completedAt,
+                reason: "no-publish",
+            });
+        },
+        async beginAnalysis() {
+            const ended = async () => { };
+            if (finishedRecord === undefined || interrupted)
+                return ended;
+            const startedAt = iso();
+            finishedRecord = { ...finishedRecord, updatedAt: startedAt, analysis: { startedAt } };
+            await write(finishedRecord);
+            const analysisHeartbeat = startHeartbeat(clock, RUN_STATUS_TOUCH_MS, () => {
+                if (finishedRecord === undefined)
+                    return;
+                finishedRecord = { ...finishedRecord, updatedAt: iso() };
+                void write(finishedRecord);
+            });
+            let done = false;
+            return async (state) => {
+                if (done || finishedRecord?.analysis === undefined)
+                    return;
+                done = true;
+                analysisHeartbeat.stop();
+                const endedAt = iso();
+                finishedRecord = {
+                    ...finishedRecord,
+                    updatedAt: endedAt,
+                    analysis: { ...finishedRecord.analysis, endedAt, state },
+                };
+                await write(finishedRecord);
+            };
+        },
         suspensions: () => heartbeat.suspensions(),
     };
     return handle;
@@ -150,6 +192,50 @@ export function classifyRunStatus(record, nowMs, staleMs = RUN_STATUS_STALE_MS)
         return "interrupted";
     return nowMs - updated <= staleMs ? "running" : "interrupted";
 }
+/**
+ * The record's automatic analysis. `stopped` is an analysis with no end whose heartbeat went
+ * stale: the process ended during it. Undefined when the record has none, or one this version
+ * cannot read.
+ */
+export function runAnalysisPhase(record, nowMs) {
+    const analysis = record.analysis;
+    if (analysis === null || typeof analysis !== "object")
+        return undefined;
+    const { startedAt, endedAt, state } = analysis;
+    if (typeof startedAt !== "string" || !Number.isFinite(Date.parse(startedAt)))
+        return undefined;
+    if (typeof endedAt === "string")
+        return {
+            state: "ended",
+            startedAt,
+            endedAt,
+            ...(typeof state === "string" ? { outcome: state } : {}),
+        };
+    const updated = Date.parse(record.updatedAt);
+    return Number.isFinite(updated) && nowMs - updated <= RUN_STATUS_STALE_MS
+        ? { state: "running", startedAt }
+        : { state: "stopped", startedAt };
+}
+/** Whether `pid` names a process on this host. EPERM means one exists that this user cannot signal. */
+function processRunning(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === "EPERM";
+    }
+}
+/**
+ * A `running` record whose heartbeat is stale and whose pid no process on this host holds: its
+ * owner is gone, so the run cannot still be writing. A live pid proves nothing either way (pids
+ * are reused), so such a record stays unconfirmed.
+ */
+export function runOwnerGone(record, nowMs, running = processRunning) {
+    if (record.state !== "running" || classifyRunStatus(record, nowMs) === "running")
+        return false;
+    return record.pid !== process.pid && !running(record.pid);
+}
 /** Shape guard for a record read off disk. Unknown extra fields are tolerated (additive contract). */
 export function isRunStatusRecord(value) {
     if (value === null || typeof value !== "object")

package/dist/run/stored-runs.d.ts

@@ -1,5 +1,6 @@
 import { type ReviewSummary } from "./bundle.js";
 import { type RunDisplay } from "./display.js";
+import { type RunAnalysisPhase } from "./status.js";
 import { type VerifyResult } from "../verify/verify.js";
 declare const RUNS_SCHEMA = "humanish.runs-result.v1";
 export interface RunsResult {
@@ -13,6 +14,8 @@ export interface RunsResult {
         path: string;
         /** How the run reads (runDisplay in src/run/display.ts); absent when it has no readable run.json. */
         display?: RunDisplay;
+        /** The automatic analysis its own process started after the run ended, from status.json. */
+        analysis?: RunAnalysisPhase;
     }>;
     latest: string | null;
     error?: {

package/dist/run/stored-runs.js

@@ -6,7 +6,7 @@ import { assertPreparedSelectedOutputDirectory, bindExistingManagedHumanishOutpu
 import { RUN_BUNDLE_FILE } from "./bundle.js";
 import { isReviewSummary, isRunBundle, isRunOutcome } from "./bundle-shape.js";
 import { bundleDisplayFacts, displayedReview, runDisplay, } from "./display.js";
-import { RUN_STATUS_FILE } from "./status.js";
+import { isRunStatusRecord, RUN_STATUS_FILE, runAnalysisPhase, } from "./status.js";
 import { readLatest, readRunJsonIfExists, resolveRunPath, runJsonValue } from "./locate.js";
 import { withCuaReviewProvenance } from "./outcomes.js";
 import { displayedTraces, loadStreamTraces } from "./stream-trace.js";
@@ -106,10 +106,15 @@ async function listedRunDisplay(runPaths, bundle) {
     const displayed = displayedBundle(bundle);
     if (displayed === undefined)
         return {};
-    const status = displayed.outcome === undefined
-        ? runJsonValue(await readRunJsonIfExists(runPaths, RUN_STATUS_FILE))
+    const status = runJsonValue(await readRunJsonIfExists(runPaths, RUN_STATUS_FILE));
+    const analysis = isRunStatusRecord(status) && status.runId === displayed.runId
+        ? runAnalysisPhase(status, Date.now())
         : undefined;
-    return { display: runDisplay(bundleDisplayFacts(displayed, status)) };
+    return {
+        // A bundle with an outcome decides how the run ended; status.json only adds its analysis.
+        display: runDisplay(bundleDisplayFacts(displayed, displayed.outcome === undefined ? status : undefined)),
+        ...(analysis === undefined ? {} : { analysis }),
+    };
 }
 /** The fields runDisplay reads from an unchecked run.json; none when it does not name a run. */
 function displayedBundle(bundle) {

package/dist/study/doctor.js

@@ -1,5 +1,5 @@
 import path from "node:path";
-import { isLocalBrowserStudy } from "../substrates/local/runtime-config.js";
+import { isLocalBrowserStudy, localStudySetsScreens } from "../substrates/local/runtime-config.js";
 import { localRuntimeStatus } from "../substrates/local/runtime.js";
 import { capacityShortfall, describeCapacity, } from "../substrates/local/capacity.js";
 import { keyNamesOf, requiredKeys, requiredSubjectEnv } from "./requirements.js";
@@ -204,7 +204,7 @@ export async function studySetupChecks(args) {
     if (route === "scripted")
         checks.push(await scriptedBrowserCheck());
     checks.push(...subjectEnvChecks(requiredSubjectEnv(requirements), args));
-    const analysis = automaticAnalysisBudget(config.review?.analysis, route);
+    const analysis = automaticAnalysisBudget(config.review?.analysis, route, undefined, config.actor);
     if (analysis)
         checks.push(await analysisCheck(analysis, args, checkAccount));
     checks.push(checkScope(analysis));
@@ -231,10 +231,13 @@ async function localBrowserChecks(config, args, desktopsAtOnce) {
             media: config.execution?.desktop?.media !== undefined ||
                 config.execution?.desktop?.recording !== undefined,
         })))();
+    const screens = runtime.installed && runtime.assets?.displaySizes !== true && localStudySetsScreens(config)
+        ? "The installed local runtime starts every participant at 960×720, and this study sets other screen sizes. Omit device and resolution, use a hosted desktop, or set HUMANISH_LOCAL_RUNTIME_IMAGE to a runtime built from current source."
+        : undefined;
     checks.push({
         name: "local browser runtime",
-        ok: runtime.ok,
-        message: runtime.message,
+        ok: runtime.ok && screens === undefined,
+        message: screens ?? runtime.message,
         ...(runtime.ok && !runtime.installed ? { status: "note" } : {}),
     });
     if (runtime.capacity !== undefined && desktopsAtOnce !== undefined)
@@ -252,7 +255,9 @@ async function localBrowserChecks(config, args, desktopsAtOnce) {
     }
     return {
         checks,
-        ...(runtime.ok && runtime.installed ? {} : { next: runtime.message }),
+        ...(runtime.ok && runtime.installed && screens === undefined
+            ? {}
+            : { next: screens ?? runtime.message }),
     };
 }
 /** Whether the desktops the study runs at once fit the VM or this machine, and why. */
@@ -384,7 +389,7 @@ async function analysisCheck(analysis, args, checkAccount) {
         ...(keyed ? {} : { status: "note" }),
         message: keyed
             ? `OPENAI_API_KEY is present for the separate automatic analysis request; model access and quota are not tested. The analysis is refused before it starts if ${admissionRule(`$${analysis.maxCostUsd}`)}; this is not a billing cap. Participant readiness is independent.`
-            : "Will be skipped: OPENAI_API_KEY is missing. The participant may run, but there will be no automatic findings report. Add an OpenAI API key or set review.analysis: false deliberately.",
+            : "Will be skipped: OPENAI_API_KEY is missing. The participant may run, but there will be no automatic findings report. Add an OpenAI API key, or set review.analysis.provider: codex to have a signed-in Codex account analyze the run instead, or set review.analysis: false deliberately.",
     };
 }
 /** What doctor checked and what it did not. */

package/dist/study/init-templates.js

@@ -62,6 +62,7 @@ Studies:
 - private or machine-local studies live in ignored .humanish/studies/*.yaml or
   .humanish/local/studies/*.yaml;
 - run a study with \`${command} run <study>\`, or \`${command} watch <study>\` to stay attached;
+- a live run ends with findings from a separate analyst; \`${command} review --run latest\` shows them;
 - files under humanish/labs/ move there with \`${command} migrate\`.
 
 Format standard:
@@ -79,12 +80,17 @@ Format standard:
  */
 function tryLiveStudy(actor, localAgent = "codex") {
     const account = actor === "local-agent";
+    const analyst = localAgent === "codex"
+        ? `The analysis after the run uses the same Codex account. Set review.analysis: false to skip
+  it.`
+        : `When OPENAI_API_KEY is set, the analysis after the run bills it: humanish refuses that request
+  before it starts if its estimate is over $${DEFAULT_ANALYSIS_MAX_COST_USD}. With Codex also signed
+  in, review.analysis.provider: codex has its account analyze the run instead. Set
+  review.analysis: false to skip it.`;
     const needs = account
         ? `  Needs E2B_API_KEY and the coding agent signed in on this machine. Cost: one small task, a few
   E2B desktop minutes and the agent's account usage. humanish cannot put a dollar cap on account
-  usage, so the ten-minute session limit below bounds the run. When OPENAI_API_KEY is set, the
-  analysis after the run bills it: humanish refuses that request before it starts if its estimate
-  is over $${DEFAULT_ANALYSIS_MAX_COST_USD}. Set review.analysis: false to skip it.`
+  usage, so the ten-minute session limit below bounds the run. ${analyst}`
         : `  Needs E2B_API_KEY and OPENAI_API_KEY. Cost: one small task with a $2 cap on estimated model
   spend. The run stops before its next model request once the estimate passes $2, so the last
   request can go slightly over, and hosted desktop time is billed separately. The analysis after