humanish 0.48.0 → 0.50.0

package/dist/run-status.d.ts

@@ -0,0 +1,139 @@
+import { type PreparedOutputRoot } from "./selected-output-paths.js";
+export declare const RUN_STATUS_SCHEMA = "humanish.run-status.v1";
+/** The file, relative to the run directory. */
+export declare const RUN_STATUS_FILE = "status.json";
+/** How often a live run touches `updatedAt`. */
+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
+ * slack so an ordinary scheduling hiccup or a slow disk never mislabels a healthy run.
+ */
+export declare const RUN_STATUS_STALE_MS: number;
+/** Which manifest a run came from, when it came from one. */
+export interface RunLabProvenance {
+    /** The lab id as declared in its manifest (`config.id`). */
+    id: string;
+    /** Repo-relative manifest path, when the run came from a file on disk. */
+    path?: string;
+    /** `committed` = humanish/labs, `ignored` = a local overlay, `explicit` = a path the operator passed. */
+    origin?: "committed" | "ignored" | "explicit";
+}
+export type RunStatusState = "running" | "finished";
+/** The outcome summary a finalized record carries. Derived from the bundle; never authoritative. */
+export interface RunStatusOutcome {
+    /** `review.verdict` verbatim. */
+    verdict?: string;
+    /** True when the run's own envelope reported success. */
+    ok?: boolean;
+    /** `review.participants` counts, when the run recorded any. */
+    participants?: {
+        total: number;
+        reachedGoal: number;
+        reportedFriction?: number;
+    };
+    /** The run-level estimate, `null` when declared absent (never coerced to 0). */
+    estimatedCostUsd?: number | null;
+    durationMs?: number;
+}
+export interface RunStatusRecord {
+    schema: typeof RUN_STATUS_SCHEMA;
+    runId: string;
+    state: RunStatusState;
+    mode: "dry-run" | "live";
+    /** Absent when the run did not come from a lab manifest (a library caller, a bare `run`). */
+    lab?: RunLabProvenance;
+    /** The pid that owns the run, for local liveness and (later) cancellation. */
+    pid: number;
+    startedAt: string;
+    /** Refreshed on a fixed cadence while the run is alive; the staleness signal. */
+    updatedAt: string;
+    completedAt?: string;
+    outcome?: RunStatusOutcome;
+}
+export interface RunStatusHandle {
+    /** Resolves once the initial record has landed on disk. The write itself is fire-and-forget —
+     *  starting a run must never block on its own index — but a caller that needs the record to
+     *  exist before proceeding (a test, or a launcher that hands the run id to another process)
+     *  can await this instead of polling. */
+    readonly started: Promise<void>;
+    /** Write `updatedAt` now. Called by the internal cadence; exposed for tests and for backends
+     *  that want to mark a phase boundary. Never throws. */
+    touch(): Promise<void>;
+    /** Finalize: state `finished`, `completedAt`, and the derived outcome. Stops the cadence.
+     *  Idempotent — a second call is a no-op, so a backend with several exit paths is safe. */
+    finish(outcome?: RunStatusOutcome): Promise<void>;
+    /**
+     * Stop the cadence WITHOUT claiming an outcome. For a path that is abandoning the run: the record
+     * stays `running` and goes stale, which is the honest reading.
+     *
+     * Resolves when any IN-FLIGHT write has settled, so a caller that is about to delete the run
+     * directory can be sure nothing is still writing into it. Clearing the interval alone is not
+     * enough — a write started microseconds earlier is still on its way to disk.
+     */
+    stop(): Promise<void>;
+}
+export interface BeginRunStatusOptions {
+    runId: string;
+    mode: "dry-run" | "live";
+    lab?: RunLabProvenance;
+    /** Injectable clock (tests freeze it; the repo's `now()` convention). */
+    now?: () => number;
+    /** Injectable pid so a test never depends on the real process id. */
+    pid?: number;
+    /** Cadence override; 0 disables the interval entirely (tests drive `touch()` themselves). */
+    touchMs?: number;
+}
+/** A no-op handle, so a caller that cannot write status still has a uniform interface. */
+export declare function inertRunStatus(): RunStatusHandle;
+/**
+ * Bind a run's status records to the lifetime of the run itself.
+ *
+ * WHY THIS IS NOT A `finally` AT EACH BACKEND. A run function does not have one exit — the lab
+ * backends have 18 early `return`s between opening the record and finalizing it, every one of them
+ * a fail-closed path (bad subject, packing failure, missing key). Relying on each of those to
+ * remember the record is the same per-call-site discipline that already failed once on this
+ * contract, and the failure is silent: the run is over, the cadence keeps ticking, and the record
+ * keeps saying `running` — a listing surface then shows a dead run as alive for as long as the
+ * process lives. CI caught it as a deleted run directory racing a still-live writer.
+ *
+ * So the scope owns the lifetime. Control returning from the run function IS the run ending,
+ * whatever path it took, and any record still open at that moment is finalized with NO outcome:
+ * the run ended and we have no verdict to report. That is honest and it is different from both
+ * neighbours — a backend that finalized properly carries its real outcome, and a process that
+ * CRASHED never reaches here at all, leaving a `running` record to go stale and read as
+ * `interrupted`, which is exactly what happened.
+ */
+export declare function withRunStatusScope<T>(fn: () => Promise<T>): Promise<T>;
+/**
+ * Start a run's status record and keep it fresh. Fire-and-forget by design: a status write that
+ * fails must never fail the run it describes, so every write swallows its error. The interval is
+ * `unref`'d — this file can never be the reason a process stays alive.
+ */
+export declare function beginRunStatus(runPaths: PreparedOutputRoot, options: BeginRunStatusOptions): RunStatusHandle;
+/** The three ways a run reads from disk. `interrupted` is a `running` record gone stale. */
+export type RunLiveness = "running" | "interrupted" | "finished";
+/**
+ * Classify a status record. Pure, so the TUI, the CLI and tests share one definition of "alive".
+ * `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;
+/** Shape guard for a record read off disk. Unknown extra fields are tolerated (additive contract). */
+export declare function isRunStatusRecord(value: unknown): value is RunStatusRecord;
+/**
+ * The legacy bridge: infer a lab id for a bundle written BEFORE this contract, where the only
+ * attribution was the `lab:<id>` convention on persona/scenario source strings. Deliberately
+ * conservative — it reads the convention and nothing else, and a `lab:` prefix with an empty
+ * remainder is not an id. Ids may contain colons (`oss:meta`), so only the FIRST segment is
+ * stripped. Returns undefined when the bundle carries no such marker.
+ */
+export declare function inferLegacyLabId(bundle: {
+    persona?: {
+        source?: string;
+    };
+    scenario?: {
+        source?: string;
+    };
+}): string | undefined;
+/** A monotonic elapsed-ms helper for callers that need a duration without trusting wall clocks. */
+export declare function elapsedMsSince(startNs: bigint): number;

package/dist/run-status.js

@@ -0,0 +1,218 @@
+// Run identity + liveness on disk (#455/#475): one small record per run that says WHICH LAB the
+// run belongs to and WHETHER IT IS STILL ALIVE, written by every backend.
+//
+// Why it exists. Two questions could not be answered from the filesystem before this:
+//   1. "which lab produced this run?" — the bundle carried no lab field; attribution rode a string
+//      convention (`persona.source = "lab:<id>"`) that is not universal.
+//   2. "is this run still going?" — the mid-run bundle flush is gated on an interactive-observer
+//      callback, so a run launched by an agent (`lab run --json`) or detached wrote nothing at all
+//      until it completed. Anything watching the directory could not tell running from abandoned.
+//
+// EVIDENCE VS INDEX (the honesty rule that makes this safe). `run.json` remains the
+// evidence-of-record; this file is a DERIVED INDEX + LIVENESS RECORD. `verify` never gates on it,
+// nothing here is a claim about what a participant did, and when the two disagree `run.json` wins
+// and this file is rebuildable from it. It exists so a reader can list and classify runs without
+// parsing every bundle (a 25-run tree measured 152ms warm that way), and so a live run is
+// recognizable while it is live.
+//
+// PUBLIC-SAFETY. Only public-safe fields: the run id, the lab id/path/origin (author-chosen names,
+// the same strings `humanish lab list` already prints), the mode, a local pid, and timestamps.
+// Deliberately NOT the hostname or any user/path identity — this file sits inside a run directory
+// that an operator may share, so it must carry nothing a share-safety gate would have to strip.
+import { AsyncLocalStorage } from "node:async_hooks";
+import { hrtime } from "node:process";
+import { writeContainedOutputFile } from "./selected-output-paths.js";
+export const RUN_STATUS_SCHEMA = "humanish.run-status.v1";
+/** The file, relative to the run directory. */
+export const RUN_STATUS_FILE = "status.json";
+/** How often a live run touches `updatedAt`. */
+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
+ * 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;
+/** A no-op handle, so a caller that cannot write status still has a uniform interface. */
+export function inertRunStatus() {
+    return { started: Promise.resolve(), touch: async () => { }, finish: async () => { }, stop: async () => { } };
+}
+/**
+ * The set of handles opened inside the currently-running run, so the run's own return finalizes
+ * them. Scoped rather than global: labs can run concurrently in one process, and each must clean up
+ * only what it opened.
+ */
+const runStatusScope = new AsyncLocalStorage();
+/**
+ * Bind a run's status records to the lifetime of the run itself.
+ *
+ * WHY THIS IS NOT A `finally` AT EACH BACKEND. A run function does not have one exit — the lab
+ * backends have 18 early `return`s between opening the record and finalizing it, every one of them
+ * a fail-closed path (bad subject, packing failure, missing key). Relying on each of those to
+ * remember the record is the same per-call-site discipline that already failed once on this
+ * contract, and the failure is silent: the run is over, the cadence keeps ticking, and the record
+ * keeps saying `running` — a listing surface then shows a dead run as alive for as long as the
+ * process lives. CI caught it as a deleted run directory racing a still-live writer.
+ *
+ * So the scope owns the lifetime. Control returning from the run function IS the run ending,
+ * whatever path it took, and any record still open at that moment is finalized with NO outcome:
+ * the run ended and we have no verdict to report. That is honest and it is different from both
+ * neighbours — a backend that finalized properly carries its real outcome, and a process that
+ * CRASHED never reaches here at all, leaving a `running` record to go stale and read as
+ * `interrupted`, which is exactly what happened.
+ */
+export async function withRunStatusScope(fn) {
+    const scope = new Set();
+    try {
+        return await runStatusScope.run(scope, fn);
+    }
+    finally {
+        // `finish` swallows its own write errors and is idempotent, so this can neither throw over the
+        // run's own error nor overwrite an outcome a backend already recorded.
+        await Promise.all([...scope].map((handle) => handle.finish()));
+    }
+}
+/**
+ * Start a run's status record and keep it fresh. Fire-and-forget by design: a status write that
+ * fails must never fail the run it describes, so every write swallows its error. The interval is
+ * `unref`'d — this file can never be the reason a process stays alive.
+ */
+export function beginRunStatus(runPaths, options) {
+    const now = options.now ?? (() => Date.now());
+    const iso = () => new Date(now()).toISOString();
+    const startedAt = iso();
+    const base = {
+        schema: RUN_STATUS_SCHEMA,
+        runId: options.runId,
+        state: "running",
+        mode: options.mode,
+        ...(options.lab === undefined ? {} : { lab: options.lab }),
+        pid: options.pid ?? process.pid,
+        startedAt,
+        updatedAt: startedAt
+    };
+    let finished = false;
+    let writing = Promise.resolve();
+    const write = (record) => {
+        // Serialized: two overlapping atomic writes of the same path would be a coin flip over which
+        // record survives, and a `running` record landing after a `finished` one would resurrect it.
+        writing = writing
+            .then(() => writeContainedOutputFile(runPaths, RUN_STATUS_FILE, `${JSON.stringify(record, null, 2)}\n`, "utf8"))
+            .catch(() => {
+            // Deliberately swallowed: the index is a convenience, the bundle is the evidence.
+        });
+        return writing;
+    };
+    const started = write(base);
+    const touchMs = options.touchMs ?? RUN_STATUS_TOUCH_MS;
+    let timer;
+    if (touchMs > 0) {
+        timer = setInterval(() => {
+            if (finished)
+                return;
+            void write({ ...base, updatedAt: iso() });
+        }, touchMs);
+        timer.unref?.();
+    }
+    const stop = () => {
+        if (timer !== undefined) {
+            clearInterval(timer);
+            timer = undefined;
+        }
+        // `writing` is the tail of the serialized write chain, so awaiting it awaits everything queued.
+        return writing.catch(() => undefined);
+    };
+    const scope = runStatusScope.getStore();
+    const handle = {
+        started,
+        async touch() {
+            if (finished)
+                return;
+            await write({ ...base, updatedAt: iso() });
+        },
+        async finish(outcome) {
+            if (finished)
+                return;
+            finished = true;
+            void stop();
+            scope?.delete(handle);
+            const completedAt = iso();
+            await write({
+                ...base,
+                state: "finished",
+                updatedAt: completedAt,
+                completedAt,
+                ...(outcome === undefined ? {} : { outcome })
+            });
+        },
+        stop() {
+            scope?.delete(handle);
+            return stop();
+        }
+    };
+    // The enclosing run now owns this record's lifetime; see `withRunStatusScope`. A caller outside a
+    // scope (a direct library import) simply gets the old behavior.
+    scope?.add(handle);
+    return handle;
+}
+/**
+ * Classify a status record. Pure, so the TUI, the CLI and tests share one definition of "alive".
+ * `nowMs` is passed in rather than read, so a classification is reproducible.
+ */
+export function classifyRunStatus(record, nowMs, staleMs = RUN_STATUS_STALE_MS) {
+    if (record.state === "finished")
+        return "finished";
+    const updated = Date.parse(record.updatedAt);
+    if (!Number.isFinite(updated))
+        return "interrupted";
+    return nowMs - updated <= staleMs ? "running" : "interrupted";
+}
+/** 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")
+        return false;
+    const record = value;
+    if (record.schema !== RUN_STATUS_SCHEMA)
+        return false;
+    if (typeof record.runId !== "string" || record.runId === "")
+        return false;
+    if (record.state !== "running" && record.state !== "finished")
+        return false;
+    if (record.mode !== "dry-run" && record.mode !== "live")
+        return false;
+    if (typeof record.pid !== "number")
+        return false;
+    if (typeof record.startedAt !== "string" || typeof record.updatedAt !== "string")
+        return false;
+    if (record.lab !== undefined) {
+        if (record.lab === null || typeof record.lab !== "object")
+            return false;
+        if (typeof record.lab.id !== "string")
+            return false;
+    }
+    return true;
+}
+/**
+ * The legacy bridge: infer a lab id for a bundle written BEFORE this contract, where the only
+ * attribution was the `lab:<id>` convention on persona/scenario source strings. Deliberately
+ * conservative — it reads the convention and nothing else, and a `lab:` prefix with an empty
+ * remainder is not an id. Ids may contain colons (`oss:meta`), so only the FIRST segment is
+ * stripped. Returns undefined when the bundle carries no such marker.
+ */
+export function inferLegacyLabId(bundle) {
+    for (const source of [bundle.persona?.source, bundle.scenario?.source]) {
+        if (typeof source !== "string")
+            continue;
+        if (!source.startsWith("lab:"))
+            continue;
+        const id = source.slice("lab:".length).trim();
+        if (id !== "")
+            return id;
+    }
+    return undefined;
+}
+/** A monotonic elapsed-ms helper for callers that need a duration without trusting wall clocks. */
+export function elapsedMsSince(startNs) {
+    return Number((hrtime.bigint() - startNs) / 1000000n);
+}
+//# sourceMappingURL=run-status.js.map

package/dist/run-status.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-status.js","sourceRoot":"","sources":["../src/run-status.ts"],"names":[],"mappings":"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"}

package/dist/run.d.ts

@@ -4,6 +4,7 @@ import type { TaskFunnel } from "./tasks.js";
 import { type CapturedGitState } from "./core/git-state.js";
 import type { E2BDesktopModule } from "./e2b-desktop-launch.js";
 import { type PreparedRunArtifactPaths } from "./run-paths.js";
+import { type RunLabProvenance } from "./run-status.js";
 export declare const RUN_BUNDLE_SCHEMA = "humanish.run-bundle.v1";
 export declare const SHARED_WORLD_SCHEMA = "humanish.shared-world.v1";
 export declare const REVIEW_SCHEMA = "humanish.review.v1";
@@ -13,6 +14,8 @@ export declare const DOCTOR_SCHEMA = "humanish.doctor-result.v1";
 export declare const CLEANUP_SCHEMA = "humanish.cleanup-result.v1";
 export declare const PUBLIC_TARGET_CWD = "[target-cwd]";
 export interface RunOptions {
+    /** Which manifest produced this run (#455). */
+    lab?: RunLabProvenance;
     cwd: string;
     actor?: string;
     actorCommand?: string[];
@@ -744,6 +747,13 @@ export interface RunBundle {
      * resource lease. Optional + additive; core never enumerates provider accounts.
      */
     providerResources?: RunProviderResource[];
+    /**
+     * Which lab manifest produced this run (#455). Optional + additive: absent on every bundle
+     * written before this contract and on library callers who pass a LabConfig directly (the run is
+     * then honestly lab-less rather than guessed). For older bundles a reader may fall back to
+     * `inferLegacyLabId`, which reads only the historical `persona.source = "lab:<id>"` convention.
+     */
+    lab?: RunLabProvenance;
     /**
      * OPTIONAL, ADDITIVE run-level cost ESTIMATE (humanish.run-cost-summary.v1): the sum of every
      * lane's model-token estimate PLUS the E2B desktop-minute estimate, carrying the SAME
@@ -1037,6 +1047,11 @@ export interface DoctorResult {
         message: string;
     }>;
 }
+/**
+ * The synthetic/local backends. The body runs inside a status scope so that returning from it —
+ * by any of its exits, including the fail-closed ones — finalizes whatever status records it
+ * opened. See `withRunStatusScope`.
+ */
 export declare function runDryRun(options: RunOptions): Promise<RunResult>;
 type LocalActorTerminalStatus = Extract<RunSimulationStatus, "passed" | "failed" | "blocked" | "timed_out">;
 /**

package/dist/run.js

@@ -2,6 +2,7 @@ import { randomUUID } from "node:crypto";
 import { spawn } from "node:child_process";
 import { lstat, readdir, readFile, realpath, stat } from "node:fs/promises";
 import os from "node:os";
+import { existsSync } from "node:fs";
 import path from "node:path";
 import { parse as parseYaml } from "yaml";
 // The deterministic browser-persona driver lives in the scripted-browser-actor leaf module
@@ -21,6 +22,9 @@ import { parseResolvedPersona, personaToDirectives, renderPersonaPromptSection }
 import { round6 } from "./pricing.js";
 import { containsSensitive, digestText, redactText, redactToSecretLabel, tailText } from "./redaction.js";
 import { bindExistingRunArtifactPaths, RUNS_RELATIVE_ROOT, isSafeRunIdSegment, prepareRunArtifactPaths, resolveExistingRunDirectory, resolveLatestRunDirectory, resolveRunsRoot, validatePreparedRunArtifactPaths } from "./run-paths.js";
+import { probeKeySources } from "./key-resolution.js";
+import { beginRunStatus, withRunStatusScope } from "./run-status.js";
+import { TUI_MIN_NODE_MAJOR, nodeSupportsTui, tuiBundleUrl } from "./tui-contract.js";
 import { assertPreparedSelectedOutputDirectory, assertSafeOutputPathSegment, bindExistingManagedHumanishOutputDirectory, prepareContainedOutputDirectory, prepareContainedOutputDirectoryRoot, prepareContainedOutputFile, prepareSelectedOutputDirectory, readContainedRegularFile, writeContainedOutputFile, writePreparedRunLatestPointer } from "./selected-output-paths.js";
 export const RUN_BUNDLE_SCHEMA = "humanish.run-bundle.v1";
 export const SHARED_WORLD_SCHEMA = "humanish.shared-world.v1";
@@ -164,7 +168,15 @@ const builtinScenario = {
     source: "builtin:first-run-smoke",
     sourceDigest: "builtin"
 };
+/**
+ * The synthetic/local backends. The body runs inside a status scope so that returning from it —
+ * by any of its exits, including the fail-closed ones — finalizes whatever status records it
+ * opened. See `withRunStatusScope`.
+ */
 export async function runDryRun(options) {
+    return withRunStatusScope(() => runDryRunInScope(options));
+}
+async function runDryRunInScope(options) {
     const cwd = path.resolve(options.cwd);
     const cwdError = await validateCwd(cwd);
     const warnings = [];
@@ -261,6 +273,13 @@ export async function runDryRun(options) {
     const selection = await loadDryRunSelection(projectRoot, humanishSource);
     await assertPreparedSelectedOutputDirectory(projectRoot);
     const runPaths = await prepareRunArtifactPaths(cwd, runId);
+    // Identity + liveness on disk (#455): uniform across every route, so a reader classifies any
+    // run from one small file instead of parsing bundles.
+    const runStatus = beginRunStatus(runPaths, {
+        runId,
+        mode: options.dryRun ? "dry-run" : "live",
+        ...(options.lab === undefined ? {} : { lab: options.lab })
+    });
     const artifactRoot = runPaths.relativeRunRoot;
     if (humanishSource === "missing") {
         warnings.push("Committed humanish/ source was not found; using built-in synthetic dry-run defaults.");
@@ -280,6 +299,7 @@ export async function runDryRun(options) {
         createdAt,
         cwd,
         artifactRoot,
+        ...(options.lab === undefined ? {} : { lab: options.lab }),
         source,
         persona: selection.persona,
         scenario: selection.scenario,
@@ -322,7 +342,7 @@ export async function runDryRun(options) {
         review: createReviewSummary(),
         feedbackCandidates: []
     };
-    await writeRunBundleArtifacts(runPaths, bundle);
+    await writeRunBundleArtifacts(runPaths, bundle, runStatus);
     await writePreparedRunLatestPointer(runPaths, `${JSON.stringify({
         schema: "humanish.latest-run.v1",
         runId,
@@ -380,6 +400,13 @@ async function runBrowserAppProof(options) {
     const selection = await loadDryRunSelection(options.projectRoot, humanishSource);
     await assertPreparedSelectedOutputDirectory(options.projectRoot);
     const runPaths = await prepareRunArtifactPaths(options.cwd, runId);
+    // Identity + liveness on disk (#455): uniform across every route, so a reader classifies any
+    // run from one small file instead of parsing bundles.
+    const runStatus = beginRunStatus(runPaths, {
+        runId,
+        mode: options.dryRun ? "dry-run" : "live",
+        ...(options.lab === undefined ? {} : { lab: options.lab })
+    });
     const artifactRoot = runPaths.relativeRunRoot;
     if (selection.browserJourneyFailure) {
         return {
@@ -425,6 +452,7 @@ async function runBrowserAppProof(options) {
         createdAt,
         cwd: options.cwd,
         artifactRoot,
+        ...(options.lab === undefined ? {} : { lab: options.lab }),
         source,
         persona: {
             id: selection.persona.id,
@@ -548,7 +576,7 @@ async function runBrowserAppProof(options) {
         review,
         feedbackCandidates: []
     };
-    await writeRunBundleArtifacts(runPaths, bundle);
+    await writeRunBundleArtifacts(runPaths, bundle, runStatus);
     await writePreparedRunLatestPointer(runPaths, `${JSON.stringify({
         schema: "humanish.latest-run.v1",
         runId,
@@ -701,6 +729,13 @@ async function runLocalCodexTui(options) {
     const selection = await loadDryRunSelection(options.projectRoot, humanishSource);
     await assertPreparedSelectedOutputDirectory(options.projectRoot);
     const runPaths = await prepareRunArtifactPaths(options.cwd, runId);
+    // Identity + liveness on disk (#455): uniform across every route, so a reader classifies any
+    // run from one small file instead of parsing bundles.
+    const runStatus = beginRunStatus(runPaths, {
+        runId,
+        mode: options.dryRun ? "dry-run" : "live",
+        ...(options.lab === undefined ? {} : { lab: options.lab })
+    });
     const artifactRoot = runPaths.relativeRunRoot;
     if (humanishSource === "missing") {
         warnings.push("Committed humanish/ source was not found; using built-in synthetic local actor defaults.");
@@ -749,6 +784,7 @@ async function runLocalCodexTui(options) {
             createdAt,
             cwd: options.cwd,
             artifactRoot,
+            ...(options.lab === undefined ? {} : { lab: options.lab }),
             source,
             persona: selection.persona,
             scenario: selection.scenario,
@@ -889,6 +925,7 @@ async function runLocalCodexTui(options) {
         createdAt,
         cwd: options.cwd,
         artifactRoot,
+        ...(options.lab === undefined ? {} : { lab: options.lab }),
         source,
         persona: selection.persona,
         scenario: selection.scenario,
@@ -976,7 +1013,7 @@ async function runLocalCodexTui(options) {
         review: createLocalActorReviewSummary("Codex TUI", status, verdictReason),
         feedbackCandidates: []
     };
-    await writeRunBundleArtifacts(runPaths, bundle);
+    await writeRunBundleArtifacts(runPaths, bundle, runStatus);
     await writePreparedRunLatestPointer(runPaths, `${JSON.stringify({
         schema: "humanish.latest-run.v1",
         runId,
@@ -1116,6 +1153,13 @@ async function runLocalCodexExec(options) {
     const selection = await loadDryRunSelection(options.projectRoot, humanishSource);
     await assertPreparedSelectedOutputDirectory(options.projectRoot);
     const runPaths = await prepareRunArtifactPaths(options.cwd, runId);
+    // Identity + liveness on disk (#455): uniform across every route, so a reader classifies any
+    // run from one small file instead of parsing bundles.
+    const runStatus = beginRunStatus(runPaths, {
+        runId,
+        mode: options.dryRun ? "dry-run" : "live",
+        ...(options.lab === undefined ? {} : { lab: options.lab })
+    });
     const artifactRoot = runPaths.relativeRunRoot;
     if (humanishSource === "missing") {
         warnings.push("Committed humanish/ source was not found; using built-in synthetic local actor defaults.");
@@ -1315,7 +1359,7 @@ async function runLocalCodexExec(options) {
         events,
         review: createLocalActorReviewSummary(options.simCount === 1 ? "Codex exec" : "Codex exec fanout", status, verdictReason)
     });
-    await writeRunBundleArtifacts(runPaths, bundle);
+    await writeRunBundleArtifacts(runPaths, bundle, runStatus);
     await writePreparedRunLatestPointer(runPaths, `${JSON.stringify({
         schema: "humanish.latest-run.v1",
         runId,
@@ -1469,6 +1513,13 @@ async function runLocalCodexAppServer(options) {
     const selection = await loadDryRunSelection(options.projectRoot, humanishSource);
     await assertPreparedSelectedOutputDirectory(options.projectRoot);
     const runPaths = await prepareRunArtifactPaths(options.cwd, runId);
+    // Identity + liveness on disk (#455): uniform across every route, so a reader classifies any
+    // run from one small file instead of parsing bundles.
+    const runStatus = beginRunStatus(runPaths, {
+        runId,
+        mode: options.dryRun ? "dry-run" : "live",
+        ...(options.lab === undefined ? {} : { lab: options.lab })
+    });
     const artifactRoot = runPaths.relativeRunRoot;
     if (humanishSource === "missing") {
         warnings.push("Committed humanish/ source was not found; using built-in synthetic Codex app-server actor defaults.");
@@ -1646,7 +1697,7 @@ async function runLocalCodexAppServer(options) {
         events,
         review: createLocalActorReviewSummary(options.simCount === 1 ? "Codex app-server" : "Codex app-server fanout", status, verdictReason)
     });
-    await writeRunBundleArtifacts(runPaths, bundle);
+    await writeRunBundleArtifacts(runPaths, bundle, runStatus);
     await writePreparedRunLatestPointer(runPaths, `${JSON.stringify({
         schema: "humanish.latest-run.v1",
         runId,
@@ -2979,6 +3030,46 @@ export async function doctor(cwdInput) {
                     ? "optional peer @e2b/desktop is installed; live desktop lanes can launch"
                     : "optional peer @e2b/desktop is NOT installed — dry runs work, but any live desktop lane will fail closed. Install it with `npm i -D @e2b/desktop`."
             };
+        })(),
+        // The stakeholder surface (#455). Reported as capability, never as a gate: the TUI is optional,
+        // and `doctor` is itself mostly run by agents through a pipe, where a TTY requirement says
+        // nothing about whether the PROJECT is ready. So this row is always ok and its job is to tell a
+        // human the surface exists and whether this machine can host it.
+        (() => {
+            const supported = nodeSupportsTui();
+            const bundlePresent = existsSync(tuiBundleUrl(import.meta.url));
+            return {
+                name: "terminal surface",
+                ok: true,
+                message: !supported
+                    ? `\`humanish tui\` needs Node ${TUI_MIN_NODE_MAJOR}+ (this is ${process.version}); every other command works here`
+                    : bundlePresent
+                        ? "`humanish tui` is available in an interactive terminal"
+                        : "`humanish tui` bundle is not built in this checkout — run `pnpm build` (installed packages ship it prebuilt)"
+            };
+        })(),
+        // Provider-key discovery (#436): which source supplies each live-run key, through the same
+        // chain a live command resolves (env/--env-file, project overlay, vendor stores, the
+        // humanish user store). Values never appear; sources and fill commands do.
+        ...await (async () => {
+            const probes = await probeKeySources(["OPENAI_API_KEY", "E2B_API_KEY", "GH_TOKEN"], {
+                cwd,
+                env: process.env
+            });
+            return probes.map((probe) => {
+                const present = probe.source !== null;
+                // GH_TOKEN is needed only for private clone subjects, so its absence is informational.
+                const required = probe.name !== "GH_TOKEN";
+                return {
+                    name: `key ${probe.name}`,
+                    ok: present || !required,
+                    message: present
+                        ? `supplied by ${probe.source}`
+                        : required
+                            ? `missing from every source — ${probe.hint}`
+                            : `missing (needed only for private clone subjects) — ${probe.hint}`
+                };
+            });
         })()
     ];
     return {
@@ -3374,12 +3465,30 @@ async function readTextIfExists(filePath) {
         throw error;
     }
 }
-async function writeRunBundleArtifacts(runPaths, bundle) {
+async function writeRunBundleArtifacts(runPaths, bundle, 
+/** Pass ONLY when this write is the run's final one: the shared writer is also used for
+ *  mid-run in-progress snapshots, and finalizing there would declare a live run finished (#455). */
+finalizeStatus) {
     const publicBundle = {
         ...bundle,
         cwd: PUBLIC_TARGET_CWD
     };
     await writeContainedOutputFile(runPaths, "run.json", `${JSON.stringify(publicBundle, null, 2)}\n`, "utf8");
+    await finalizeStatus?.finish({
+        ...(publicBundle.review?.verdict === undefined ? {} : { verdict: publicBundle.review.verdict }),
+        ...(publicBundle.review?.participants === undefined
+            ? {}
+            : {
+                participants: {
+                    total: publicBundle.review.participants.total,
+                    reachedGoal: publicBundle.review.participants.reachedGoal,
+                    ...(publicBundle.review.participants.reportedFriction === undefined
+                        ? {}
+                        : { reportedFriction: publicBundle.review.participants.reportedFriction })
+                }
+            }),
+        ...(publicBundle.cost?.estimatedTotalUsd === undefined ? {} : { estimatedCostUsd: publicBundle.cost.estimatedTotalUsd })
+    });
     await writeContainedOutputFile(runPaths, "review.json", `${JSON.stringify(publicBundle.review, null, 2)}\n`, "utf8");
     await writeContainedOutputFile(runPaths, "review.md", renderReviewMarkdown(publicBundle), "utf8");
     await writeContainedOutputFile(runPaths, "events.ndjson", `${publicBundle.events.map((event) => JSON.stringify(event)).join("\n")}\n`, "utf8");