humanish 0.140.0 → 0.142.0

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 {
@@ -10,6 +11,12 @@ interface StartRunOptions {
     cwd: string;
     /** Caller-supplied id (`--run-id`, library `runId`); `mintRunId` runs when it is absent. */
     runId?: string | undefined;
+    /**
+     * The run key every sandbox of this run carries (16 lowercase hex), in place of the one derived
+     * from the run directory. A remote run's launcher chooses it, so its own directory and the
+     * remote one name the same sandboxes.
+     */
+    ownerKey?: string | undefined;
     mintRunId: () => string;
     mode: "dry-run" | "live";
     study?: RunStudyProvenance | undefined;
@@ -43,6 +50,8 @@ interface StartRunPlan {
 interface StartRunInput {
     /** Caller-supplied id (`--run-id`, library `runId`); one is minted from the prefix when absent. */
     readonly runId?: string | undefined;
+    /** The run key its sandboxes carry; see StartRunOptions.ownerKey. */
+    readonly ownerKey?: string | undefined;
     /** Open the Observer page once it renders. */
     readonly open?: boolean | undefined;
     /**
@@ -170,7 +179,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 +187,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,13 +210,22 @@ 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;
 }>;
+/**
+ * Make `runId` the project's latest run. A published run does it as it finishes, and a remote run's
+ * launcher once the run is copied back; this is the only writer of the pointer.
+ */
+export declare function pointLatestRunAt(paths: PreparedRunArtifactPaths, runId: string, now?: () => number): Promise<void>;
 export {};

package/dist/run/run.js

@@ -20,6 +20,7 @@ import { RunSecrets } from "./secrets.js";
 import { RUN_STATUS_FILE, beginRunStatus, runStatusOutcome, } from "./status.js";
 import { readRunJsonIfExists, runJsonValue } from "./locate.js";
 import { hostSuspensionEvents, systemHostClock, } from "./host-suspension.js";
+import { pinRunOwnerKey } from "./sandbox-creates.js";
 import { splitStreamTraces } from "./stream-trace.js";
 /** An entry point called in a state that does not admit it. */
 class RunLifecycleError extends Error {
@@ -35,34 +36,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;
     }
@@ -195,13 +204,7 @@ function runPublisher(args) {
         return written;
     };
     const writePointer = async () => {
-        const pointer = {
-            schema: "humanish.latest-run.v1",
-            runId,
-            path: paths.relativeRunRoot,
-            updatedAt: new Date(now()).toISOString(),
-        };
-        await writePreparedRunLatestPointer(paths, json(pointer), "utf8");
+        await pointLatestRunAt(paths, runId, now);
         pointerWritten = true;
     };
     // Each running participant's items so far, appended to its live file as the flushes arrive.
@@ -262,7 +265,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 +290,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;
@@ -317,6 +321,8 @@ export async function runScope(fn) {
             const created = await createRunArtifactPaths(options.cwd, runId);
             if (!created.ok)
                 return created;
+            if (options.ownerKey !== undefined)
+                await pinRunOwnerKey(created.paths, options.ownerKey);
             // beginRunStatus reads only the mode, the study provenance, the sandboxes field and the
             // clock from the run's options.
             const runStatus = beginRunStatus(created.paths, { ...options, runId });
@@ -339,6 +345,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,17 +426,31 @@ export async function runScope(fn) {
         }
         finally {
             if (finished === undefined)
-                await status?.finish();
+                await status?.abandon();
             unregister?.();
         }
     }
     return { result: outcome.result, finished };
 }
+/**
+ * Make `runId` the project's latest run. A published run does it as it finishes, and a remote run's
+ * launcher once the run is copied back; this is the only writer of the pointer.
+ */
+export async function pointLatestRunAt(paths, runId, now = Date.now) {
+    const pointer = {
+        schema: "humanish.latest-run.v1",
+        runId,
+        path: paths.relativeRunRoot,
+        updatedAt: new Date(now()).toISOString(),
+    };
+    await writePreparedRunLatestPointer(paths, json(pointer), "utf8");
+}
 /** Start a recorded route's run through `start`, the scope's own form, then capture its source. */
 async function startRecordedRun(start, plan, input, route) {
     const started = await start({
         cwd: route.cwd,
         runId: input.runId,
+        ownerKey: input.ownerKey,
         mintRunId: () => mintRunId(route.prefix),
         mode: plan.dryRun ? "dry-run" : "live",
         study: plan.study,

package/dist/run/sandbox-creates.d.ts

@@ -1,4 +1,4 @@
-import type { PreparedOutputRoot } from "./contained-output.js";
+import { type PreparedOutputRoot } from "./contained-output.js";
 import type { SandboxOwnerTags, SandboxProviderId } from "./sandbox-receipts.js";
 /** Refuses a sandbox create for a run directory whose process is stopping. */
 export declare class SandboxCreateRefusedError extends Error {
@@ -17,10 +17,17 @@ export interface CreatedSandbox {
  * The E2B metadata that ties a sandbox to the directory that journals it. `runId` is the
  * directory's name: the run id, or a preflight probe's id. `runKey` is a digest of the directory's
  * inode and creation time, so two projects that both use `--run-id smoke` never match each other's
- * sandboxes, and a renamed project directory still matches its own. `tool` is the owner tag every
- * route already sets.
+ * sandboxes, and a renamed project directory still matches its own. A directory whose run was given
+ * a key (pinRunOwnerKey) uses that key instead, so two directories on different machines, a remote
+ * run's and its launcher's, name the same sandboxes. `tool` is the owner tag every route already
+ * sets.
  */
 export declare function sandboxOwnerTags(root: PreparedOutputRoot): SandboxOwnerTags;
+/**
+ * Give a new run directory the run key `key` (16 lowercase hex characters) before it creates any
+ * sandbox. The file is created once and never replaced.
+ */
+export declare function pinRunOwnerKey(root: PreparedOutputRoot, key: string): Promise<void>;
 /** A create in progress; the acquire step in src/substrates/e2b/sandbox.ts holds one per create. */
 export interface SandboxCreateTicket {
     /** Whether the directory's process has started stopping; checked before each attempt. */

package/dist/run/sandbox-creates.js

@@ -8,7 +8,9 @@
 // sandbox as soon as its id arrives. The tags let `humanish reclaim` find a sandbox whose id
 // never reached this process at all.
 import { createHash } from "node:crypto";
+import { closeSync, constants, openSync, readSync } from "node:fs";
 import path from "node:path";
+import { createContainedOutputFile } from "./contained-output.js";
 /** Refuses a sandbox create for a run directory whose process is stopping. */
 export class SandboxCreateRefusedError extends Error {
     constructor() {
@@ -59,21 +61,61 @@ function idle(entry) {
         entry.inFlight.size === 0 &&
         [...entry.created.values()].every((sandbox) => sandbox.released));
 }
+/** The file in a run directory that holds a run key its launcher chose. */
+const OWNER_KEY_FILE = "owner-key";
+const OWNER_KEY = /^[0-9a-f]{16}$/;
 /**
  * The E2B metadata that ties a sandbox to the directory that journals it. `runId` is the
  * directory's name: the run id, or a preflight probe's id. `runKey` is a digest of the directory's
  * inode and creation time, so two projects that both use `--run-id smoke` never match each other's
- * sandboxes, and a renamed project directory still matches its own. `tool` is the owner tag every
- * route already sets.
+ * sandboxes, and a renamed project directory still matches its own. A directory whose run was given
+ * a key (pinRunOwnerKey) uses that key instead, so two directories on different machines, a remote
+ * run's and its launcher's, name the same sandboxes. `tool` is the owner tag every route already
+ * sets.
  */
 export function sandboxOwnerTags(root) {
     const { where, identity } = identityOf(root);
-    const runKey = createHash("sha256")
-        .update(`${identity.ino}:${identity.birthtimeNs}`)
-        .digest("hex")
-        .slice(0, 16);
+    const runKey = pinnedOwnerKey(where) ??
+        createHash("sha256")
+            .update(`${identity.ino}:${identity.birthtimeNs}`)
+            .digest("hex")
+            .slice(0, 16);
     return { tool: "humanish", runId: path.basename(where), runKey };
 }
+/**
+ * The key pinned in the run directory at `where`, if any. The file is opened without following a
+ * link, as every other file in a run directory is; a missing or malformed file pins nothing.
+ */
+function pinnedOwnerKey(where) {
+    let fd;
+    try {
+        fd = openSync(path.join(where, OWNER_KEY_FILE), constants.O_RDONLY | constants.O_NOFOLLOW);
+    }
+    catch {
+        return undefined;
+    }
+    try {
+        const buffer = Buffer.alloc(64);
+        const length = readSync(fd, buffer, 0, buffer.length, 0);
+        const key = buffer.subarray(0, length).toString("utf8").trim();
+        return OWNER_KEY.test(key) ? key : undefined;
+    }
+    catch {
+        return undefined;
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+/**
+ * Give a new run directory the run key `key` (16 lowercase hex characters) before it creates any
+ * sandbox. The file is created once and never replaced.
+ */
+export async function pinRunOwnerKey(root, key) {
+    if (!OWNER_KEY.test(key))
+        throw new Error("A run's owner key is 16 lowercase hexadecimal characters.");
+    await createContainedOutputFile(root, OWNER_KEY_FILE, `${key}\n`);
+}
 /** Register a create for `root`. Throws SandboxCreateRefusedError once the directory is stopping. */
 export function beginSandboxCreate(root, participantId, provider) {
     const directory = directoryFor(root);

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/run-study.d.ts

@@ -81,6 +81,11 @@ interface RunStudyInternals {
     scorerProvenance?: RunScorerProvenance;
     /** The local VM study's desktop, analysis gate and signal, for a local browser study. */
     localVm?: LocalVmInput;
+    /**
+     * The run key its sandboxes carry, chosen by the process that launched this run on a remote
+     * machine (the CLI's hidden `--owner-key`). Requires `runId`.
+     */
+    ownerKey?: string;
 }
 /** A run's result and the route it ran on. */
 interface RouteOutcome<R extends StudyRoute, T> {

package/dist/study/doctor.js

@@ -12,6 +12,7 @@ import { externalCatchHealthy } from "../comms/sandbox-catch.js";
 import { receivingRequiredKey } from "../comms/setup.js";
 import { classifyCodexInstallation, codexInstallAdvice, codexVersionRecovery, } from "../actors/codex/codex-admission.js";
 import { cli } from "../cli/invocation.js";
+import { analysisKeyNames } from "../keys/key-resolution.js";
 /** A ready row's message, with the schema values the launch recorded. */
 function readyMessage(message, readiness) {
     const additions = protocolAdditionsWarning(readiness.cliVersion, readiness.protocolAdditions);
@@ -365,7 +366,7 @@ function subjectEnvChecks(names, args) {
             : "missing declared subject environment variable; provide it with --dotenv",
     }));
 }
-/** The post-run analysis: the Codex account, or the OpenAI key and the analysis cost limit. */
+/** The post-run analysis: the Codex account, or the OpenAI or Gemini key and the cost limit. */
 async function analysisCheck(analysis, args, checkAccount) {
     if (analysis.provider === "codex") {
         const readiness = await checkAccount();
@@ -382,6 +383,18 @@ async function analysisCheck(analysis, args, checkAccount) {
                 : `Codex account analysis is unavailable (${readiness.errorCode ?? "codex_unavailable"}). ${recovery} No API fallback is used; participant readiness is independent.`,
         };
     }
+    if (analysis.provider === "gemini") {
+        const names = analysisKeyNames("gemini");
+        const geminiKeyed = names.some(args.keyPresent);
+        return {
+            name: "post-run analysis",
+            ok: true,
+            ...(geminiKeyed ? {} : { status: "note" }),
+            message: geminiKeyed
+                ? `A Gemini API key is present for the separate automatic analysis request, which sends the evidence and captures to Google; 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: ${names.join(" and ")} are missing. The participant may run, but there will be no automatic findings report. Add it with ${cli("keys set gemini")}, or set review.analysis: false deliberately.`,
+        };
+    }
     const keyed = args.keyPresent("OPENAI_API_KEY");
     return {
         name: "post-run analysis",

package/dist/study/requirements.d.ts

@@ -10,7 +10,7 @@ export declare function requiredSubjectEnv(requirements: readonly Requirement[])
 /**
  * The provider keys a live run of `plan` is known to read: its `key` and `key-one-of` names, its
  * subject env, the external catch's token variable, ANTHROPIC_API_KEY for a Claude Code
- * participant, and OPENAI_API_KEY when automatic analysis runs on OpenAI. `run` prints a
+ * participant, and the analyst's key when automatic analysis runs on OpenAI or Gemini. `run` prints a
  * key-source line for these only. Discovery still fills every key it finds: other readers, such as
  * a declared scorer's host code, are not in the plan.
  */