humanish 0.109.1 → 0.110.1

package/dist/run/reclaim.js

@@ -1,18 +1,23 @@
-// `humanish reclaim`: kill an interrupted run's sandboxes by the exact ids the run journaled at
-// create time (sandbox-receipts.ndjson), and report what happened to each. It reads one file inside
-// the managed run dir, kills by id, and never lists the account: an account-wide operation once
-// destroyed unrelated infrastructure. Without it, orphaned sandboxes run until the server-side
-// create-time TTL.
+// `humanish reclaim`: stop an interrupted run's sandboxes and report what happened to each. It
+// finds them three ways: the exact ids the run journaled at create time (sandbox-receipts.ndjson),
+// the ids a create in this process reported before its receipt landed (the signal handler only),
+// and E2B's list of sandboxes tagged with the run's owner tags (sandboxOwnerTags), which covers a
+// sandbox whose id never reached the run. The list is filtered server-side by the run's tags and
+// each result is checked against every tag again, so it can only return this run's sandboxes; an
+// account-wide operation once destroyed unrelated infrastructure. Kills run concurrently, and
+// reclaim-receipt.json is written before the first kill and after each one, so an exit at any
+// point leaves a record of every sandbox not yet confirmed gone. `--check` asks E2B the same
+// questions and kills nothing.
 import { E2B_DEBUG_ENV, e2bDebugMode, loadE2BDesktopModule, } from "../substrates/e2b/sdk.js";
-import { containedPathAbsent, readContainedRegularFile, writeContainedOutputFile, } from "./contained-output.js";
+import { containedPathAbsent, readContainedRegularFile, } from "./contained-output.js";
 import { discardPreflightJournal, listPreflightJournals, preflightReclaimDecision, } from "./preflight-receipts.js";
 import { resolveRunPath } from "./locate.js";
-import { parseSandboxReceipts, SANDBOX_RECEIPTS_ARTIFACT, } from "./sandbox-receipts.js";
-import { destroyE2BSandbox } from "../substrates/e2b/sandbox.js";
+import { parseSandboxOwners, parseSandboxReceipts, SANDBOX_RECEIPTS_ARTIFACT, } from "./sandbox-receipts.js";
+import { sandboxOwnerTags, } from "./sandbox-creates.js";
+import { earlierOutcomes, GONE, RECLAIM_RECEIPT_ARTIFACT, RECLAIM_RESULT_SCHEMA, receiptWriter, rootState, searchTagSets, settledWithin, targetSet, } from "./reclaim-outcomes.js";
 import { redactText, toErrorMessage } from "../evidence/redaction.js";
 import { runIdOf } from "./paths.js";
-const RECLAIM_RESULT_SCHEMA = "humanish.reclaim-result.v1";
-export const RECLAIM_RECEIPT_ARTIFACT = "reclaim-receipt.json";
+export { RECLAIM_RECEIPT_ARTIFACT };
 export function reclaimRunSandboxes(cwd, runInput, hooks = {}) {
     return reclaimRun(cwd, runInput, () => resolveRunPath(cwd, runInput), hooks);
 }
@@ -23,23 +28,30 @@ export function reclaimRunSandboxes(cwd, runInput, hooks = {}) {
 export function reclaimPinnedRunSandboxes(cwd, runPaths, hooks = {}) {
     return reclaimRun(cwd, runIdOf(runPaths), () => Promise.resolve(runPaths), hooks);
 }
-async function reclaimRun(cwd, runInput, locate, hooks) {
-    const warnings = [];
-    const base = {
+function emptyResult(cwd, runId, hooks, warnings) {
+    return {
         schema: RECLAIM_RESULT_SCHEMA,
+        ok: false,
+        state: "unknown",
+        mode: hooks.check === true ? "check" : "kill",
         cwd,
-        runId: runInput,
+        runId,
         receiptCount: 0,
         outcomes: [],
+        tagSearch: { status: "not-run", found: 0 },
+        createsInFlight: 0,
         warnings,
     };
+}
+async function reclaimRun(cwd, runInput, locate, hooks) {
+    const warnings = [];
+    const base = emptyResult(cwd, runInput, hooks, warnings);
     if (e2bDebugMode())
-        return { ...base, ok: false, error: E2B_DEBUG_REFUSAL };
+        return { ...base, error: E2B_DEBUG_REFUSAL };
     const runPaths = await locate();
     if (!runPaths) {
         return {
             ...base,
-            ok: false,
             error: {
                 code: "HUMANISH_RECLAIM_RUN_NOT_FOUND",
                 message: `No run found for "${runInput}" (use \`humanish runs\` to list runs).`,
@@ -47,37 +59,31 @@ async function reclaimRun(cwd, runInput, locate, hooks) {
         };
     }
     const runId = runIdOf(runPaths);
-    const journal = await reclaimJournal(runPaths, hooks);
-    if (journal.kind === "empty") {
-        // Empty: nothing journaled means either no sandbox was ever created (cheap interrupt:
-        // nothing to reclaim) or the run predates receipts (0.35.x and earlier, where the create-time TTL
-        // is the only backstop for those). Either way there is no id to act on, and saying so beats
-        // pretending a scan happened.
-        warnings.push("No sandbox-receipts.ndjson in this run dir: either no sandbox was created before the interrupt, or the run predates create-time receipts. Nothing to reclaim by id; server-side kill-on-timeout covers anything that did exist.");
-        return { ...base, runId, ok: true };
-    }
-    if (journal.kind === "module-unavailable") {
+    const reclaimed = await reclaimRoot(runPaths, runId, hooks, warnings);
+    if (reclaimed.kind === "module-unavailable")
         return {
             ...base,
             runId,
-            receiptCount: journal.receiptCount,
-            ok: false,
-            error: { code: "HUMANISH_RECLAIM_MODULE_UNAVAILABLE", message: journal.message },
+            receiptCount: reclaimed.receiptCount,
+            error: { code: "HUMANISH_RECLAIM_MODULE_UNAVAILABLE", message: reclaimed.message },
         };
-    }
-    if (journal.kind === "unreadable") {
+    if (reclaimed.kind === "unreadable")
         return {
             ...base,
             runId,
-            ok: false,
             error: { code: "HUMANISH_RECLAIM_RECEIPTS_UNREADABLE", message: UNREADABLE_MESSAGE },
         };
-    }
-    const { receiptCount, outcomes } = journal;
-    const result = { ...base, runId, receiptCount, outcomes, ok: allGone(outcomes) };
-    // Keep the reclaim record next to the run it cleaned: what was attempted, what happened, when.
-    await writeReclaimReceipt(runPaths, runId, receiptCount, outcomes, warnings);
-    return result;
+    const { state, receiptCount, outcomes, tagSearch, createsInFlight } = reclaimed;
+    return {
+        ...base,
+        ok: state === "clean",
+        state,
+        runId,
+        receiptCount,
+        outcomes,
+        tagSearch,
+        createsInFlight,
+    };
 }
 /**
  * Kill the sandboxes left by interrupted `humanish study check` probes. A probe journals under
@@ -87,52 +93,71 @@ async function reclaimRun(cwd, runInput, locate, hooks) {
  */
 export async function reclaimPreflightSandboxes(cwd, hooks = {}) {
     const warnings = [];
+    const base = emptyResult(cwd, "preflight", hooks, warnings);
+    if (e2bDebugMode())
+        return { ...base, error: E2B_DEBUG_REFUSAL };
     const outcomes = [];
     let receiptCount = 0;
-    let unreadable = false;
-    const base = { schema: RECLAIM_RESULT_SCHEMA, cwd, runId: "preflight", warnings };
-    if (e2bDebugMode())
-        return { ...base, ok: false, receiptCount, outcomes, error: E2B_DEBUG_REFUSAL };
+    const states = [];
+    // Not run until a journal is reclaimed; then done unless one journal's search was not.
+    const tagSearch = { status: "not-run", found: 0 };
     const journals = await listPreflightJournals(cwd);
     if (journals.length === 0) {
-        warnings.push("No preflight journals in .humanish/preflight: every probe's teardown was confirmed, or no probe ran here. Nothing to reclaim by id.");
+        warnings.push("No preflight journals in .humanish/preflight: every probe's teardown was confirmed, or no probe ran here. Nothing to reclaim.");
     }
     for (const journal of journals) {
         const decision = await preflightReclaimDecision(journal, Date.now());
         if (!decision.reclaim) {
             warnings.push(`Preflight ${journal.id} left alone: ${decision.reason}.`);
+            states.push("unknown");
             continue;
         }
-        const reclaimed = await reclaimJournal(journal.root, hooks);
+        const reclaimed = await reclaimRoot(journal.root, journal.id, hooks, warnings);
         if (reclaimed.kind === "unreadable") {
             // The receipt may name a live sandbox; the journal stays for a later reclaim.
-            unreadable = true;
             warnings.push(`Preflight ${journal.id} left alone: ${UNREADABLE_MESSAGE}`);
+            states.push("unknown");
             continue;
         }
         if (reclaimed.kind === "module-unavailable") {
             return {
                 ...base,
-                ok: false,
                 receiptCount: receiptCount + reclaimed.receiptCount,
                 outcomes,
                 error: { code: "HUMANISH_RECLAIM_MODULE_UNAVAILABLE", message: reclaimed.message },
             };
         }
-        if (reclaimed.kind === "done") {
-            receiptCount += reclaimed.receiptCount;
-            outcomes.push(...reclaimed.outcomes);
-            if (!allGone(reclaimed.outcomes)) {
-                // The journal stays so a later reclaim can try again; the receipt says what happened.
-                await writeReclaimReceipt(journal.root, journal.id, reclaimed.receiptCount, reclaimed.outcomes, warnings);
-                continue;
-            }
+        receiptCount += reclaimed.receiptCount;
+        outcomes.push(...reclaimed.outcomes);
+        const { state } = reclaimed;
+        states.push(state);
+        tagSearch.found += reclaimed.tagSearch.found;
+        if (tagSearch.status === "not-run" || reclaimed.tagSearch.status !== "done") {
+            tagSearch.status = reclaimed.tagSearch.status;
+            if (reclaimed.tagSearch.detail !== undefined)
+                tagSearch.detail = reclaimed.tagSearch.detail;
+        }
+        // The journal stays until its sandboxes are known to be gone, so a later reclaim can try
+        // again; its receipt says what happened. Elapsed time alone never removes it: a probe can
+        // create later than its journal says, and a journal from before owner lines cannot show that
+        // nothing it made is still running. A check never removes it.
+        if (state !== "clean" || hooks.check === true) {
+            if (state === "unknown" && reclaimed.exhausted && hooks.check !== true)
+                warnings.push(`Preflight ${journal.id} is kept: humanish cannot rule out a sandbox it made. Once the E2B dashboard shows no sandbox for it, delete .humanish/preflight/${journal.id}.`);
+            continue;
         }
         await discardPreflightJournal(journal, [RECLAIM_RECEIPT_ARTIFACT]).catch((error) => {
             warnings.push(`Preflight ${journal.id} was reclaimed but its journal could not be removed: ${redactText(toErrorMessage(error))}`);
         });
     }
-    return { ...base, ok: !unreadable && allGone(outcomes), receiptCount, outcomes };
+    const state = combinedState(states);
+    return { ...base, ok: state === "clean", state, receiptCount, outcomes, tagSearch };
+}
+function combinedState(states) {
+    for (const worst of ["running", "unconfirmed", "unknown"])
+        if (states.includes(worst))
+            return worst;
+    return "clean";
 }
 // In debug mode the SDK returns true from Sandbox.kill without contacting E2B, so every receipt
 // would read killed and preflight journals would be discarded for sandboxes that may still run.
@@ -141,63 +166,112 @@ const E2B_DEBUG_REFUSAL = {
     message: `${E2B_DEBUG_ENV}=true puts the E2B SDK in debug mode, where Sandbox.kill reports success without contacting E2B. Nothing was killed and the receipts were kept; unset ${E2B_DEBUG_ENV} and run reclaim again.`,
 };
 const UNREADABLE_MESSAGE = "sandbox-receipts.ndjson is present but could not be read safely (not a single regular file, or a read error). Nothing was killed and the receipts were kept; check the file, then run reclaim again.";
-/** Kill every sandbox one receipts journal records, once per sandbox, by exact id. */
-async function reclaimJournal(root, hooks) {
+/**
+ * Find and stop (or, for `--check`, look up) every sandbox one directory owns: its receipts, the
+ * creates this process reported, and E2B's tagged list, each once by exact id.
+ */
+async function reclaimRoot(root, label, hooks, warnings) {
     const bytes = await readContainedRegularFile(root, SANDBOX_RECEIPTS_ARTIFACT);
-    if (bytes === null)
-        return (await containedPathAbsent(root, SANDBOX_RECEIPTS_ARTIFACT))
-            ? { kind: "empty" }
-            : { kind: "unreadable" };
-    const receipts = parseSandboxReceipts(bytes.toString("utf8"));
-    // Load the E2B SDK only when an E2B receipt needs it.
+    if (bytes === null && !(await containedPathAbsent(root, SANDBOX_RECEIPTS_ARTIFACT)))
+        return { kind: "unreadable" };
+    const journal = bytes === null ? "" : bytes.toString("utf8");
+    const receipts = parseSandboxReceipts(journal);
+    const owners = parseSandboxOwners(journal, label);
+    const check = hooks.check === true;
+    const requestTimeoutMs = hooks.requestTimeoutMs ?? 60_000;
+    // The SDK lists by tag as well as killing by id, so it is needed even with no receipt. Without
+    // it, an E2B receipt cannot be acted on; with no E2B receipt, only the tag search is lost.
     let e2b;
+    let moduleError;
     try {
-        if (receipts.some((receipt) => receipt.provider === "e2b"))
-            e2b = await (hooks.loadModule ?? loadE2BDesktopModule)();
+        e2b = await (hooks.loadModule ?? loadE2BDesktopModule)();
     }
     catch (error) {
-        return {
-            kind: "module-unavailable",
-            receiptCount: receipts.length,
-            message: `Cannot load @e2b/desktop to kill by id: ${redactText(toErrorMessage(error))}`,
-        };
+        moduleError = `Cannot load @e2b/desktop to reach E2B: ${redactText(toErrorMessage(error))}`;
+        if (receipts.some((receipt) => receipt.provider === "e2b") || hooks.creates !== undefined)
+            return { kind: "module-unavailable", receiptCount: receipts.length, message: moduleError };
     }
-    const requestTimeoutMs = hooks.requestTimeoutMs ?? 60_000;
-    const destroy = async (receipt) => {
-        switch (receipt.provider) {
-            case "e2b":
-                return destroyE2BSandbox(e2b, receipt.sandboxId, { requestTimeoutMs });
-            default:
-                return {
-                    state: "unsupported-provider",
-                    detail: `provider ${JSON.stringify(receipt.provider)} is not supported by this humanish version; nothing was attempted, and that provider's own timeout is the backstop`,
-                };
-        }
-    };
-    const outcomes = [];
-    const seen = new Set();
+    // An earlier reclaim may have killed a sandbox no receipt names (the signal handler's creates
+    // and tag finds). Its outcome is carried forward, so a later reclaim never erases that record.
+    const earlier = check ? [] : await earlierOutcomes(root, label);
+    const set = targetSet({
+        e2b,
+        check,
+        requestTimeoutMs,
+        earlier,
+        persist: receiptWriter(root, label, receipts.length, check, warnings),
+    });
+    // The watch replays the creates reported so far, synchronously, then each one an in-flight
+    // create reports, until reclaim returns. The replayed ones are matched to receipts first, so a
+    // sandbox the route already released is skipped whichever record names it.
+    const replayed = new Map();
+    let replaying = true;
+    const unwatch = hooks.creates?.watch((sandbox) => {
+        if (replaying)
+            replayed.set(sandbox.sandboxId, sandbox);
+        else
+            set.add("e2b", sandbox.sandboxId, sandbox.participantId, "create", sandbox.released);
+    });
+    replaying = false;
     for (const receipt of receipts) {
-        // One attempt per sandbox, however many receipts raced.
-        const key = JSON.stringify([receipt.provider, receipt.sandboxId]);
-        if (seen.has(key))
-            continue;
-        seen.add(key);
-        outcomes.push({
-            sandboxId: receipt.sandboxId,
-            laneId: receipt.laneId,
-            ...(await destroy(receipt)),
-        });
-    }
-    return { kind: "done", receiptCount: receipts.length, outcomes };
-}
-function allGone(outcomes) {
-    return outcomes.every((outcome) => outcome.state === "killed" || outcome.state === "already-gone");
-}
-async function writeReclaimReceipt(root, runId, receiptCount, outcomes, warnings) {
-    try {
-        await writeContainedOutputFile(root, RECLAIM_RECEIPT_ARTIFACT, `${JSON.stringify({ schema: RECLAIM_RESULT_SCHEMA, at: new Date().toISOString(), runId, receiptCount, outcomes }, null, 2)}\n`, "utf8");
+        const released = receipt.provider === "e2b" && replayed.get(receipt.sandboxId)?.released;
+        set.add(receipt.provider, receipt.sandboxId, receipt.laneId, "receipt", released === true);
     }
-    catch (error) {
-        warnings.push(`Reclaim ran but its receipt could not be written: ${redactText(toErrorMessage(error))}`);
+    for (const sandbox of replayed.values())
+        set.add("e2b", sandbox.sandboxId, sandbox.participantId, "create", sandbox.released);
+    await set.start();
+    if (hooks.creates !== undefined)
+        await settledWithin(hooks.creates.settled, hooks.createsWaitMs);
+    // The tags the run recorded before each create, and this directory's own: a copied or moved
+    // run directory computes other tags than the ones its sandboxes carry.
+    const search = await searchTagSets(e2b, [...owners, sandboxOwnerTags(root)], {
+        requestTimeoutMs,
+        unavailable: moduleError ?? "no E2B SDK",
+    });
+    let found = 0;
+    for (const listed of search.sandboxes) {
+        const metadata = listed.metadata ?? {};
+        const participant = metadata.participantId ?? metadata.kind ?? "unknown";
+        if (set.add("e2b", listed.sandboxId, participant, "tag"))
+            found += 1;
     }
+    const tagSearch = {
+        status: search.status,
+        found,
+        ...(search.detail === undefined ? {} : { detail: search.detail }),
+    };
+    if (search.status !== "done")
+        warnings.push(`Could not search E2B for sandboxes tagged with ${label}: ${search.detail ?? search.status}. A sandbox whose id never reached a receipt would not be found.`);
+    // A create that reports its id while the search or a kill is still running is killed too.
+    await set.drain();
+    unwatch?.();
+    const createsInFlight = hooks.creates?.inFlight() ?? 0;
+    // An empty search proves nothing for a run that never recorded its tags: one from humanish
+    // 0.110.0 or earlier, or whose owner lines were lost. The process that made the creates knows.
+    const provenance = owners.length > 0 || hooks.creates !== undefined;
+    if (!provenance)
+        warnings.push(`${label} records no owner tags, so a sandbox whose id never reached a receipt cannot be ruled out: the run is from humanish 0.110.0 or earlier, it created no sandbox, or its journal lost those lines. Each sandbox's create-time timeout is the backstop.`);
+    // A carried sandbox from a create or a tag search carries this run's tags; if the finished
+    // search, with the tags the run recorded, no longer lists it, it is gone. One from an older
+    // receipt, or from a run with no recorded tags, is left as it was recorded.
+    const covered = provenance && tagSearch.status === "done";
+    const outcomes = set.snapshot(earlier.map((outcome) => GONE.has(outcome.state) || outcome.source === "receipt" || !covered
+        ? outcome
+        : {
+            ...outcome,
+            state: "already-gone",
+            detail: "an earlier reclaim left it unconfirmed, and E2B no longer lists it with this run's tags",
+        }));
+    const searched = tagSearch.status === "done" && createsInFlight === 0;
+    const state = rootState(outcomes, check, searched && provenance);
+    await set.finish(outcomes, state);
+    return {
+        kind: "done",
+        state,
+        exhausted: searched && outcomes.every((outcome) => GONE.has(outcome.state)),
+        receiptCount: receipts.length,
+        outcomes,
+        tagSearch,
+        createsInFlight,
+    };
 }

package/dist/run/results.d.ts

@@ -34,24 +34,26 @@ export interface RunResult {
         message: string;
     };
 }
-export interface CleanupResourceResult {
+/**
+ * A resource line of cleanup.json. `humanish cleanup` wrote the file through 0.110.0, and verify
+ * still reads one a run kept. v0.12.23 through v0.15.0 killed sandboxes and wrote `killed`.
+ */
+export interface StoredCleanupResourceResult {
     provider: RunProviderResource["provider"];
     kind: RunProviderResource["kind"];
+    /** "[redacted-sandbox-id]" from 0.110; earlier files hold the raw id. */
     id: string;
-    /** Cleanup reads recorded evidence and never kills a sandbox, so it never writes `killed`. */
-    status: "already_clean" | "failed" | "skipped";
+    idDigest?: string;
+    status: "already_clean" | "failed" | "skipped" | "killed";
     message: string;
 }
-/** A resource line as a stored cleanup.json holds it. v0.12.23 through v0.15.0 killed sandboxes. */
-export interface StoredCleanupResourceResult extends Omit<CleanupResourceResult, "status"> {
-    status: CleanupResourceResult["status"] | "killed";
-}
 export interface CleanupAdapterResult {
     id: string;
     ok: boolean;
     message: string;
 }
-export interface CleanupResult {
+/** cleanup.json as any release through 0.110.0 wrote it. */
+export interface StoredCleanupResult {
     schema: typeof CLEANUP_SCHEMA;
     ok: boolean;
     cwd: string;
@@ -62,23 +64,14 @@ export interface CleanupResult {
     checkedAt: string;
     summary: {
         resources: number;
-        /** Always 0 now; written so readers from earlier releases still accept the file. */
         killed: number;
         alreadyClean: number;
         failed: number;
         skipped: number;
     };
-    resources: CleanupResourceResult[];
+    resources: StoredCleanupResourceResult[];
     adapterResults: CleanupAdapterResult[];
     warnings: string[];
-    error?: {
-        code: "HUMANISH_RUN_NOT_FOUND" | "HUMANISH_INVALID_RUN_BUNDLE";
-        message: string;
-    };
-}
-/** cleanup.json as any release wrote it; see StoredCleanupResourceResult. */
-export interface StoredCleanupResult extends Omit<CleanupResult, "resources"> {
-    resources: StoredCleanupResourceResult[];
 }
 export interface RunPointer {
     schema: "humanish.latest-run.v1";

package/dist/run/results.js

@@ -1,3 +1,3 @@
-// The run command's options and result, the cleanup result (cleanup.json) and the latest-run
-// pointer (latest.json). None of them are stored in run.json.
+// The run command's options and result, the cleanup.json shape releases through 0.110.0 wrote, and
+// the latest-run pointer (latest.json). None of them are stored in run.json.
 export const CLEANUP_SCHEMA = "humanish.cleanup-result.v1";

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

@@ -2,6 +2,7 @@ import { AnalysisCostCache } from "./run-index-analysis.js";
 import type { RunAnalysisCost } from "./run-cost.js";
 import { type RunLiveness, type RunStatusRecord } 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";
 export interface RunIndexEntry {
     runId: string;
@@ -20,6 +21,14 @@ export interface RunIndexEntry {
     updatedAt?: string;
     completedAt?: string;
     verdict?: string;
+    /**
+     * The run's own ok, from run.json's outcome as status.json copies it, or from the status record
+     * alone for a run recorded before run.json carried one. Absent when the run recorded none.
+     * runDisplay (src/run/display.ts) reads it with `verdict` and `liveness`.
+     */
+    ok?: boolean;
+    /** The first execution failure that failed the run, beside `ok`. */
+    failure?: ExecutionFailure;
     participants?: {
         total: number;
         reachedGoal: number;
@@ -92,13 +101,14 @@ interface BundleFacts {
         estimatedTotalUsd?: number | null;
         fullyEstimated?: unknown;
     };
+    outcome?: unknown;
 }
 /**
  * One run's liveness from files already read: its status record when usable, else its bundle.
  * `readRunIndex` reads in the same order; `humanish verify` calls this with both in hand. `record`
  * is the status record the liveness came from, when there was one.
  */
-export declare function runLiveness(runId: string, status: unknown, bundle: Pick<BundleFacts, "simulations">, nowMs: number): {
+export declare function runLiveness(runId: string, status: unknown, bundle: Pick<BundleFacts, "simulations" | "outcome">, nowMs: number): {
     liveness: RunLiveness;
     record?: RunStatusRecord;
 };

package/dist/run/run-index.js

@@ -19,6 +19,7 @@ import { AnalysisCostCache, readIndexedAnalysisCost } from "./run-index-analysis
 import { RUN_STATUS_FILE, classifyRunStatus, isRunStatusRecord, } from "./status.js";
 import { studyProvenanceOf } from "./study-provenance.js";
 import { RUN_BUNDLE_FILE } from "./bundle.js";
+import { isRunOutcome } from "./bundle-shape.js";
 const RUN_INDEX_SCHEMA = "humanish.run-index.v1";
 /**
  * A process-lifetime cache. Deliberately explicit rather than module-global state: a caller that
@@ -88,6 +89,10 @@ function entryFromStatus(record, nowMs) {
         updatedAt: record.updatedAt,
         ...(record.completedAt === undefined ? {} : { completedAt: record.completedAt }),
         ...(record.outcome?.verdict === undefined ? {} : { verdict: record.outcome.verdict }),
+        ...(typeof record.outcome?.ok === "boolean" ? { ok: record.outcome.ok } : {}),
+        ...(record.outcome?.execution?.failures[0] === undefined
+            ? {}
+            : { failure: record.outcome.execution.failures[0] }),
         ...(record.outcome?.participants === undefined
             ? {}
             : { participants: record.outcome.participants }),
@@ -112,6 +117,8 @@ function usableStatusRecord(raw, runId) {
  * reading of "it started, and nothing here says it finished" is interrupted, not finished.
  */
 function bundleLiveness(bundle) {
+    if (isRunOutcome(bundle.outcome))
+        return bundle.outcome.state;
     const inProgress = (bundle.simulations ?? []).some((simulation) => simulation?.status === "running");
     return inProgress ? "interrupted" : "finished";
 }
@@ -129,6 +136,8 @@ function studyEntry(study) {
     return study === undefined ? {} : { study };
 }
 function entryFromBundle(runId, bundle) {
+    const outcome = isRunOutcome(bundle.outcome) ? bundle.outcome : undefined;
+    const failure = outcome?.state === "finished" ? outcome.execution.failures[0] : undefined;
     return {
         runId,
         derivedFrom: "bundle",
@@ -137,6 +146,8 @@ function entryFromBundle(runId, bundle) {
         ...studyEntry(studyProvenanceOf(bundle)),
         ...(bundle.createdAt === undefined ? {} : { startedAt: bundle.createdAt }),
         ...(bundle.review?.verdict === undefined ? {} : { verdict: bundle.review.verdict }),
+        ...(outcome === undefined ? {} : { ok: outcome.ok }),
+        ...(failure === undefined ? {} : { failure }),
         ...(bundle.review?.participants === undefined
             ? {}
             : { participants: bundle.review.participants }),

package/dist/run/run.d.ts

@@ -1,8 +1,7 @@
 import { renderObserver, type ObserverResult } from "../observer/render.js";
 import { type RunBundle } from "./bundle.js";
-import type { ExecutionOutcome } from "./judge.js";
+import { type ExecutionFailure, type ExecutionOutcome, type OutcomePolicy } from "./judge.js";
 import { type PreparedRunArtifactPaths, type RunIdInUse } from "./paths.js";
-import { type RunStatusHandle } from "./status.js";
 import type { RunStudyProvenance } from "./study-provenance.js";
 interface StartRunOptions {
     /** Project directory, in the form the route resolved it. */
@@ -22,6 +21,19 @@ interface StartRunOptions {
     /** Clock for `createdAt` and the latest pointer. */
     now?: (() => number) | undefined;
 }
+/** How a run ended as an execution, as run.json records it: the result's ok and execution outcome. */
+interface RecordedOutcome {
+    ok: boolean;
+    execution: ExecutionOutcome;
+}
+/** What a route hands Run.finish about how its run ended, before the Observer renders. */
+export interface FinishOutcome extends RecordedOutcome {
+    /**
+     * The route's entry in OUTCOME_POLICIES. FinishedRun.renderObserver records an Observer that
+     * did not render under it, as a failure or a warning.
+     */
+    policy: OutcomePolicy;
+}
 interface Run {
     readonly runId: string;
     readonly createdAt: string;
@@ -41,14 +53,16 @@ interface Run {
      */
     writeSnapshot(bundle: RunBundle): Promise<void>;
     /**
-     * The one final publication: run.json, then the status outcome, then review.json, review.md,
-     * events.ndjson, observer/observer-data.json, and last the latest pointer. The status goes
-     * after run.json so the index never gets ahead of the evidence, and the pointer goes last so
-     * `latest` never selects a run whose projections are incomplete. Rejects before writing on a
-     * second call, after the scope closed, or when the bundle names another run or mode. A
-     * rejection partway leaves the files written so far and issues no FinishedRun.
+     * The one final publication: run.json with `outcome` set from `outcome`, then the status
+     * outcome copied from it, then review.json, review.md, events.ndjson,
+     * observer/observer-data.json, and last the latest pointer. The status goes after run.json so
+     * the index never gets ahead of the evidence, and the pointer goes last so `latest` never
+     * selects a run whose projections are incomplete. Every projection reads the outcome, so none
+     * shows a pass for a run whose ok is false. Rejects before writing on a second call, after the
+     * scope closed, or when the bundle names another run or mode. A rejection partway leaves the
+     * files written so far and issues no FinishedRun.
      */
-    finish(bundle: RunBundle): Promise<FinishedRun>;
+    finish(bundle: RunBundle, outcome: FinishOutcome): Promise<FinishedRun>;
 }
 export interface RunScope {
     /**
@@ -78,18 +92,20 @@ 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, status: RunStatusHandle);
+    constructor(key: typeof issueKey, runId: string, paths: PreparedRunArtifactPaths, observer: ObserverTarget | undefined, outcome: RecordedOutcome, recordFailure: (failure: ExecutionFailure) => Promise<RecordedOutcome>);
     static isIssued(value: unknown): value is FinishedRun;
-    /** Render the Observer for exactly these paths, never a directory re-resolved by name. */
-    renderObserver(): Promise<ObserverResult>;
     /**
-     * Record the result's ok and execution outcome in status.json. A route calls it once, after the
-     * Observer render, with the values its result returns, so the two agree.
+     * The run's ok and execution outcome as run.json records them: what the route passed to
+     * finish, plus an Observer that did not render. A route's result reads them from here.
+     */
+    get outcome(): RecordedOutcome;
+    /**
+     * Render the Observer for exactly these paths, never a directory re-resolved by name. An
+     * Observer that did not render is an `evidence` failure: it is added to run.json's outcome and
+     * status.json under the route's policy before this resolves. No page exists then that could
+     * show the run without it. A render that throws records nothing and rejects.
      */
-    recordOutcome(result: {
-        ok: boolean;
-        execution: ExecutionOutcome;
-    }): Promise<void>;
+    renderObserver(): Promise<ObserverResult>;
 }
 /**
  * Run `fn` as the lifetime of at most one run. When `fn` settles the scope closes synchronously,