humanish 0.104.3 → 0.106.0

package/dist/run/reclaim.js

@@ -0,0 +1,183 @@
+// `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.
+import { loadE2BDesktopModule } from "../substrates/e2b/sdk.js";
+import { containedPathAbsent, readContainedRegularFile, writeContainedOutputFile, } 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 { 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 async function reclaimRunSandboxes(cwd, runInput, hooks = {}) {
+    const warnings = [];
+    const base = {
+        schema: RECLAIM_RESULT_SCHEMA,
+        cwd,
+        runId: runInput,
+        receiptCount: 0,
+        outcomes: [],
+        warnings,
+    };
+    const runPaths = await resolveRunPath(cwd, runInput);
+    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).`,
+            },
+        };
+    }
+    const runId = runIdOf(runPaths);
+    const journal = await reclaimJournal(runPaths, hooks);
+    if (journal.kind === "empty") {
+        // Honest 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 — 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") {
+        return {
+            ...base,
+            runId,
+            receiptCount: journal.receiptCount,
+            ok: false,
+            error: { code: "HUMANISH_RECLAIM_MODULE_UNAVAILABLE", message: journal.message },
+        };
+    }
+    if (journal.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;
+}
+/**
+ * Kill the sandboxes left by interrupted `humanish lab preflight` probes. A probe journals under
+ * .humanish/preflight/<probe-id>/ and removes the journal after a confirmed kill, so what is left
+ * belongs to a probe that died or could not confirm its teardown. A journal whose probe may still
+ * be running is left alone with the reason (see preflightReclaimDecision).
+ */
+export async function reclaimPreflightSandboxes(cwd, hooks = {}) {
+    const warnings = [];
+    const outcomes = [];
+    let receiptCount = 0;
+    let unreadable = false;
+    const base = { schema: RECLAIM_RESULT_SCHEMA, cwd, runId: "preflight", warnings };
+    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.");
+    }
+    for (const journal of journals) {
+        const decision = await preflightReclaimDecision(journal, Date.now());
+        if (!decision.reclaim) {
+            warnings.push(`Preflight ${journal.id} left alone: ${decision.reason}.`);
+            continue;
+        }
+        const reclaimed = await reclaimJournal(journal.root, hooks);
+        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}`);
+            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;
+            }
+        }
+        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 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) {
+    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.
+    let e2b;
+    try {
+        if (receipts.some((receipt) => receipt.provider === "e2b"))
+            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))}`,
+        };
+    }
+    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();
+    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");
+    }
+    catch (error) {
+        warnings.push(`Reclaim ran but its receipt could not be written: ${redactText(toErrorMessage(error))}`);
+    }
+}

package/dist/run/results.d.ts

@@ -0,0 +1,88 @@
+import type { ObserverResult } from "../observer/render.js";
+import type { RunProviderResource } from "./bundle.js";
+import type { RunLabProvenance } from "./status.js";
+export declare const CLEANUP_SCHEMA = "humanish.cleanup-result.v1";
+export interface RunOptions {
+    /** Which manifest produced this run (#455). */
+    lab?: RunLabProvenance;
+    cwd: string;
+    dryRun?: boolean;
+    runId?: string;
+    simCount?: number;
+    /** Render the run's Observer through the finished run, opening the page when `open` is true.
+     *  Without it the preview writes no observer/index.html. */
+    observer?: {
+        open: boolean;
+    };
+}
+export interface RunResult {
+    schema: "humanish.run-result.v1";
+    ok: boolean;
+    runId?: string;
+    mode?: "dry-run" | "live";
+    simCount?: number;
+    cwd: string;
+    artifactRoot?: string;
+    bundlePath?: string;
+    reviewPath?: string;
+    latestPath?: string;
+    /** The Observer rendered for this run, when `RunOptions.observer` asked for one. */
+    observer?: ObserverResult;
+    warnings: string[];
+    error?: {
+        code: "HUMANISH_LAB_ANALYSIS_INVALID" | "HUMANISH_LAB_ANALYSIS_UNSUPPORTED" | "HUMANISH_LAB_TASKS_UNSUPPORTED" | "HUMANISH_LAB_OPTION_CONFLICT" | "HUMANISH_LAB_OPTION_UNSUPPORTED" | "HUMANISH_LAB_COMMS_UNSUPPORTED" | "HUMANISH_LIVE_RUN_UNIMPLEMENTED" | "HUMANISH_INVALID_CWD" | "HUMANISH_RUN_ID_IN_USE" | "HUMANISH_INVALID_SIM_COUNT" | "HUMANISH_INVALID_PORT" | "HUMANISH_UNSUPPORTED_RERUN_FLAGS" | "HUMANISH_WATCH_OPTION_CONFLICT" | "HUMANISH_WATCH_SAFE_NOT_APPLICABLE" | "HUMANISH_APP_URL_REMOVED" | "HUMANISH_LAB_SCORER_BAD_REF" | "HUMANISH_LAB_SCORER_NOT_FOUND" | "HUMANISH_LAB_SCORER_LOAD_FAILED" | "HUMANISH_LAB_SCORER_NO_HOOKS" | "HUMANISH_LAB_SCORER_UNSUPPORTED_BACKEND";
+        message: string;
+    };
+}
+export interface CleanupResourceResult {
+    provider: RunProviderResource["provider"];
+    kind: RunProviderResource["kind"];
+    id: string;
+    /** Cleanup reads recorded evidence and never kills a sandbox, so it never writes `killed`. */
+    status: "already_clean" | "failed" | "skipped";
+    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 {
+    schema: typeof CLEANUP_SCHEMA;
+    ok: boolean;
+    cwd: string;
+    run: string;
+    runId?: string;
+    bundlePath?: string;
+    cleanupPath?: string;
+    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[];
+    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";
+    runId: string;
+    path: string;
+    updatedAt: string;
+}

package/dist/run/results.js

@@ -0,0 +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.
+export const CLEANUP_SCHEMA = "humanish.cleanup-result.v1";

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

@@ -0,0 +1,107 @@
+import { type RunLabProvenance, type RunLiveness, type RunStatusRecord } from "./status.js";
+declare const RUN_INDEX_SCHEMA = "humanish.run-index.v1";
+export interface RunIndexEntry {
+    runId: string;
+    /** Where the entry's facts came from: the status record, the bundle, or the directory alone. */
+    derivedFrom: "status" | "bundle" | "directory";
+    liveness: RunLiveness;
+    mode?: "dry-run" | "live";
+    /**
+     * The pid that owns a run, when it recorded one. This is how a surface identifies the run IT just
+     * started without minting an id or guessing at a new directory: it spawned a process, and exactly
+     * one run's record carries that pid.
+     */
+    pid?: number;
+    lab?: RunLabProvenance;
+    startedAt?: string;
+    updatedAt?: string;
+    completedAt?: string;
+    verdict?: string;
+    participants?: {
+        total: number;
+        reachedGoal: number;
+        reportedFriction?: number;
+    };
+    estimatedCostUsd?: number | null;
+    /** Wall-clock span when both ends are known; used for per-lab medians. */
+    durationMs?: number;
+}
+export interface RunIndexResult {
+    schema: typeof RUN_INDEX_SCHEMA;
+    cwd: string;
+    /** Newest first, by the best timestamp each entry has. */
+    runs: RunIndexEntry[];
+    /** Directories that could not be read at all, by name — surfaced, never silently dropped. */
+    unreadable: string[];
+}
+/** What a cached entry was derived from, so a changed file invalidates exactly that entry. */
+interface CacheKey {
+    file: string;
+    mtimeMs: number;
+    size: number;
+    ino: number;
+}
+/**
+ * A process-lifetime cache. Deliberately explicit rather than module-global state: a caller that
+ * refreshes on a cadence keeps one and passes it back, and a caller that wants a cold read passes
+ * nothing. Nothing here is authoritative, so a stale slot can only ever cost a re-read.
+ */
+export declare class RunIndexCache {
+    private readonly slots;
+    get(runId: string, key: CacheKey): RunIndexEntry | undefined;
+    set(runId: string, key: CacheKey, entry: RunIndexEntry): void;
+    /** Drop entries for runs that no longer exist, so a long-lived surface cannot leak. */
+    retain(runIds: Iterable<string>): void;
+    get size(): number;
+}
+/** The legacy shape this reads out of a bundle. Narrow on purpose: only listing facts. */
+interface BundleFacts {
+    runId?: string;
+    mode?: string;
+    createdAt?: string;
+    lab?: RunLabProvenance;
+    persona?: {
+        source?: string;
+    };
+    scenario?: {
+        source?: string;
+    };
+    simulations?: {
+        status?: string;
+    }[];
+    review?: {
+        verdict?: string;
+        participants?: {
+            total: number;
+            reachedGoal: number;
+            reportedFriction?: number;
+        };
+    };
+    cost?: {
+        estimatedTotalUsd?: number | null;
+    };
+}
+/**
+ * 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): {
+    liveness: RunLiveness;
+    record?: RunStatusRecord;
+};
+export interface ReadRunIndexOptions {
+    /** Reused across refreshes so unchanged runs are not re-read. */
+    cache?: RunIndexCache;
+    /** Injectable clock, so liveness classification is reproducible in tests. */
+    nowMs?: number;
+    /** Cap the number of runs returned (newest first). The full directory is still enumerated —
+     *  a cap on reads, not on truth — and the count reflects what was read. */
+    limit?: number;
+}
+/**
+ * Read every run in `.humanish/runs`, cheapest source first. Never throws for a bad run directory;
+ * an unreadable one is named in `unreadable`.
+ */
+export declare function readRunIndex(cwdInput: string, options?: ReadRunIndexOptions): Promise<RunIndexResult>;
+export {};

package/dist/run/run-index.js

@@ -0,0 +1,243 @@
+// The run index (#455 PR 2): list and classify every run in a project WITHOUT parsing bundles.
+//
+// The existing `listRuns` walks each run tree — screenshots included — validating symlinks and
+// then parses each `run.json`: measured 197ms cold / 152ms warm at 25 runs. That is fine for a
+// command that prints once and exits, and much too hot for a surface that refreshes on a cadence
+// over SSH. This module reads the small `status.json` record each run now writes (586 bytes beside
+// a 92KB bundle) and caches per-run entries keyed on the stat of the file each was derived from.
+//
+// HONESTY RULES, unchanged from the record itself:
+//   - `run.json` is the evidence-of-record. Every field here is a projection for listing and
+//     classification; nothing here is a claim about what a participant did.
+//   - A run with no status record is NOT assumed finished. It is classified from what is on disk:
+//     a bundle means finished, receipts without a bundle mean interrupted. That is the honest
+//     reading of a run whose process died — and, before this contract existed, of every run.
+//   - One unreadable run directory degrades that run, never the listing.
+import { readdir, readFile, stat } from "node:fs/promises";
+import path from "node:path";
+import { RUN_STATUS_FILE, classifyRunStatus, inferLegacyLabId, isRunStatusRecord, } from "./status.js";
+import { RUN_BUNDLE_FILE } from "./bundle.js";
+const RUN_INDEX_SCHEMA = "humanish.run-index.v1";
+/**
+ * A process-lifetime cache. Deliberately explicit rather than module-global state: a caller that
+ * refreshes on a cadence keeps one and passes it back, and a caller that wants a cold read passes
+ * nothing. Nothing here is authoritative, so a stale slot can only ever cost a re-read.
+ */
+export class RunIndexCache {
+    slots = new Map();
+    get(runId, key) {
+        const slot = this.slots.get(runId);
+        if (slot === undefined)
+            return undefined;
+        const same = slot.key.file === key.file &&
+            slot.key.mtimeMs === key.mtimeMs &&
+            slot.key.size === key.size &&
+            slot.key.ino === key.ino;
+        return same ? slot.entry : undefined;
+    }
+    set(runId, key, entry) {
+        this.slots.set(runId, { key, entry });
+    }
+    /** Drop entries for runs that no longer exist, so a long-lived surface cannot leak. */
+    retain(runIds) {
+        const keep = new Set(runIds);
+        for (const runId of this.slots.keys()) {
+            if (!keep.has(runId))
+                this.slots.delete(runId);
+        }
+    }
+    get size() {
+        return this.slots.size;
+    }
+}
+async function statKey(file) {
+    try {
+        const stats = await stat(file);
+        return { file, mtimeMs: stats.mtimeMs, size: stats.size, ino: Number(stats.ino) };
+    }
+    catch {
+        return null;
+    }
+}
+async function readJson(file) {
+    try {
+        return JSON.parse(await readFile(file, "utf8"));
+    }
+    catch {
+        // A torn read cannot happen (writes are tmp+rename), so this is a genuinely absent or
+        // malformed file: the caller degrades that run rather than the listing.
+        return null;
+    }
+}
+function entryFromStatus(record, nowMs) {
+    const started = Date.parse(record.startedAt);
+    const ended = record.completedAt === undefined ? Number.NaN : Date.parse(record.completedAt);
+    return {
+        runId: record.runId,
+        derivedFrom: "status",
+        liveness: classifyRunStatus(record, nowMs),
+        mode: record.mode,
+        ...(typeof record.pid === "number" ? { pid: record.pid } : {}),
+        ...(record.lab === undefined ? {} : { lab: record.lab }),
+        startedAt: record.startedAt,
+        updatedAt: record.updatedAt,
+        ...(record.completedAt === undefined ? {} : { completedAt: record.completedAt }),
+        ...(record.outcome?.verdict === undefined ? {} : { verdict: record.outcome.verdict }),
+        ...(record.outcome?.participants === undefined
+            ? {}
+            : { participants: record.outcome.participants }),
+        ...(record.outcome?.estimatedCostUsd === undefined
+            ? {}
+            : { estimatedCostUsd: record.outcome.estimatedCostUsd }),
+        ...(Number.isFinite(started) && Number.isFinite(ended) ? { durationMs: ended - started } : {}),
+    };
+}
+/** A status record this run can be classified from: well formed and naming this run. */
+function usableStatusRecord(raw, runId) {
+    return isRunStatusRecord(raw) && raw.runId === runId;
+}
+/**
+ * The bundle-only reading, for a run with no usable status record. A bundle on disk USUALLY means
+ * the run reached its final write. But a live run now flushes an IN-PROGRESS bundle as it goes (so
+ * anything asking what a participant is doing has something to read), and that bundle marks its
+ * simulations `running`. With no status record there is no freshness to judge, and the honest
+ * reading of "it started, and nothing here says it finished" is interrupted, not finished.
+ */
+function bundleLiveness(bundle) {
+    const inProgress = (bundle.simulations ?? []).some((simulation) => simulation?.status === "running");
+    return inProgress ? "interrupted" : "finished";
+}
+/**
+ * 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 function runLiveness(runId, status, bundle, nowMs) {
+    return usableStatusRecord(status, runId)
+        ? { liveness: classifyRunStatus(status, nowMs), record: status }
+        : { liveness: bundleLiveness(bundle) };
+}
+function entryFromBundle(runId, bundle) {
+    const legacyLabId = bundle.lab === undefined ? inferLegacyLabId(bundle) : undefined;
+    return {
+        runId,
+        derivedFrom: "bundle",
+        liveness: bundleLiveness(bundle),
+        ...(bundle.mode === "dry-run" || bundle.mode === "live" ? { mode: bundle.mode } : {}),
+        ...(bundle.lab !== undefined
+            ? { lab: bundle.lab }
+            : legacyLabId === undefined
+                ? {}
+                : { lab: { id: legacyLabId } }),
+        ...(bundle.createdAt === undefined ? {} : { startedAt: bundle.createdAt }),
+        ...(bundle.review?.verdict === undefined ? {} : { verdict: bundle.review.verdict }),
+        ...(bundle.review?.participants === undefined
+            ? {}
+            : { participants: bundle.review.participants }),
+        ...(bundle.cost?.estimatedTotalUsd === undefined
+            ? {}
+            : { estimatedCostUsd: bundle.cost.estimatedTotalUsd }),
+    };
+}
+/**
+ * Read every run in `.humanish/runs`, cheapest source first. Never throws for a bad run directory;
+ * an unreadable one is named in `unreadable`.
+ */
+export async function readRunIndex(cwdInput, options = {}) {
+    const cwd = path.resolve(cwdInput);
+    const runsRoot = path.join(cwd, ".humanish", "runs");
+    const nowMs = options.nowMs ?? Date.now();
+    const cache = options.cache;
+    let dirents;
+    try {
+        dirents = await readdir(runsRoot, { withFileTypes: true });
+    }
+    catch {
+        // No runs directory yet is an ordinary empty state, not a failure.
+        return { schema: RUN_INDEX_SCHEMA, cwd, runs: [], unreadable: [] };
+    }
+    const runIds = dirents.filter((entry) => entry.isDirectory()).map((entry) => entry.name);
+    const runs = [];
+    const unreadable = [];
+    for (const runId of runIds) {
+        const runDir = path.join(runsRoot, runId);
+        const statusFile = path.join(runDir, RUN_STATUS_FILE);
+        const bundleFile = path.join(runDir, RUN_BUNDLE_FILE);
+        // Cheapest source first: the status record. Its stat is the cache key, so a live run whose
+        // record ticks every 5s re-reads 586 bytes and nothing else.
+        const statusKey = await statKey(statusFile);
+        if (statusKey !== null) {
+            const cached = cache?.get(runId, statusKey);
+            if (cached !== undefined) {
+                // Liveness is time-dependent, so it is recomputed even on a cache hit — a record that has
+                // not changed can still have gone stale since the last read.
+                runs.push(cached.derivedFrom === "status" && cached.updatedAt !== undefined
+                    ? {
+                        ...cached,
+                        liveness: classifyRunStatus({
+                            state: cached.completedAt === undefined ? "running" : "finished",
+                            updatedAt: cached.updatedAt,
+                        }, nowMs),
+                    }
+                    : cached);
+                continue;
+            }
+            const raw = await readJson(statusFile);
+            if (usableStatusRecord(raw, runId)) {
+                const entry = entryFromStatus(raw, nowMs);
+                cache?.set(runId, statusKey, entry);
+                runs.push(entry);
+                continue;
+            }
+        }
+        // No usable status record: fall back to the bundle. This is every run written before the
+        // contract existed, and it is why an old project still lists correctly.
+        const bundleKey = await statKey(bundleFile);
+        if (bundleKey !== null) {
+            const cached = cache?.get(runId, bundleKey);
+            if (cached !== undefined) {
+                runs.push(cached);
+                continue;
+            }
+            const raw = await readJson(bundleFile);
+            if (raw !== null && typeof raw === "object") {
+                const entry = entryFromBundle(runId, raw);
+                cache?.set(runId, bundleKey, entry);
+                runs.push(entry);
+                continue;
+            }
+            unreadable.push(runId);
+            continue;
+        }
+        // Neither record nor bundle: receipts without an outcome. That is precisely an interrupted
+        // run — the shape a dropped connection leaves — and saying so is more useful than hiding it.
+        runs.push({ runId, derivedFrom: "directory", liveness: "interrupted" });
+    }
+    cache?.retain(runIds);
+    runs.sort((left, right) => sortKey(right) - sortKey(left));
+    return {
+        schema: RUN_INDEX_SCHEMA,
+        cwd,
+        runs: options.limit === undefined ? runs : runs.slice(0, Math.max(0, options.limit)),
+        unreadable,
+    };
+}
+/** Newest-first ordering: the most recent thing known about a run, else its id's own timestamp. */
+function sortKey(entry) {
+    for (const candidate of [entry.completedAt, entry.updatedAt, entry.startedAt]) {
+        if (candidate === undefined)
+            continue;
+        const parsed = Date.parse(candidate);
+        if (Number.isFinite(parsed))
+            return parsed;
+    }
+    // Run ids embed an ISO-ish stamp (`cua-2026-08-19T07-44-13-489Z-…`); recover it when present so
+    // a directory-only entry still sorts sensibly instead of sinking to the bottom.
+    const match = /(\d{4}-\d{2}-\d{2})T(\d{2})-(\d{2})-(\d{2})-(\d{3})Z/.exec(entry.runId);
+    if (match) {
+        const parsed = Date.parse(`${match[1]}T${match[2]}:${match[3]}:${match[4]}.${match[5]}Z`);
+        if (Number.isFinite(parsed))
+            return parsed;
+    }
+    return 0;
+}