humanish 0.105.0 → 0.106.1

package/dist/run/shared-world-shape.d.ts

@@ -0,0 +1,26 @@
+import { type RunBundle } from "./bundle.js";
+import { type SharedWorldEvidence } from "./shared-world-evidence.js";
+export declare const COMMAND_DIGEST_PATTERN: RegExp;
+export declare const SUBJECT_ENV_NAME_PATTERN: RegExp;
+export declare const MANDATORY_ATTRIBUTION_LIMITS: readonly ["sequential-only", "no-concurrent-races", "delta-attributed-to-turn-not-action"];
+export declare const SHARED_WORLD_CHECKPOINT_KEYS: Set<string>;
+export declare const SHARED_WORLD_STATESERIES_KEYS: Set<string>;
+/**
+ * Single-plane provenance: every item shares ONE (commit, seedDigest), and that pair matches
+ * sharedWorld.plane. Only the first item that diverges from the plane is reported. The shape guard
+ * has already typed both fields as strings (commit may be absent).
+ */
+export declare function planeProvenanceFindings(items: readonly Record<string, unknown>[], plane: unknown, labels: {
+    items: string;
+    item: string;
+    run: string;
+}): string[];
+/** Common shape findings shared by both topologyMode branches. */
+export declare function sharedWorldCommonFindings(bundle: RunBundle, sw: SharedWorldEvidence): string[];
+/**
+ * Tolerant SHAPE guard for the shared-world evidence block (#164). Validates required fields +
+ * types but TOLERATES extra keys (additive): the strict value-shape/timeline checks are
+ * sharedWorldEvidenceFindings' job (an injected value-shaped checkpoint field must pass the shape
+ * guard so verify can catch it fail-closed, not silently bounce off isRunBundle).
+ */
+export declare function isSharedWorldEvidence(value: unknown): value is SharedWorldEvidence;

package/dist/run/shared-world-shape.js

@@ -0,0 +1,181 @@
+import {} from "./bundle.js";
+import { SHARED_WORLD_SCHEMA } from "./shared-world-evidence.js";
+import { isNonNegativeSafeInteger, isRecord } from "./type-guards.js";
+// The promptDigest convention: sha256 hex, first 16 chars. A "seeded" record without a real
+// digest cannot pin "same recipe" across bundles, so verify treats it as a hollow claim.
+export const COMMAND_DIGEST_PATTERN = /^[0-9a-f]{16}$/;
+// Env var NAME shape (mirrors ENV_NAME_PATTERN in src/lab/parse/values.ts). externalEnvNames
+// must hold NAMES only — a value sneaking into the list trips this check (a free secret tripwire).
+export const SUBJECT_ENV_NAME_PATTERN = /^[A-Z][A-Z0-9_]*$/;
+// SEQUENTIAL: the three disclosures a sequential shared-world bundle MUST pin (verify fails closed
+// if any is absent — omission overclaims): sequential turns only, no concurrency/races handled, and
+// a checkpoint delta is attributed to the TURN it followed, not a specific action (correlation).
+export const MANDATORY_ATTRIBUTION_LIMITS = [
+    "sequential-only",
+    "no-concurrent-races",
+    "delta-attributed-to-turn-not-action",
+];
+// A shared-world checkpoint record persists DIGEST-ONLY: exactly these keys, nothing value-shaped.
+export const SHARED_WORLD_CHECKPOINT_KEYS = new Set(["kind", "name", "digest", "deltaFromPrev"]);
+// CONCURRENT stateSeries record is DIGEST-ONLY too (FIX-7): permit ONLY a numeric timestamp + the
+// sha256-16 digest; any other key is a value-shaped leak / a smuggled per-delta→actor field.
+export const SHARED_WORLD_STATESERIES_KEYS = new Set(["timestamp", "digest"]);
+/**
+ * Single-plane provenance: every item shares ONE (commit, seedDigest), and that pair matches
+ * sharedWorld.plane. Only the first item that diverges from the plane is reported. The shape guard
+ * has already typed both fields as strings (commit may be absent).
+ */
+export function planeProvenanceFindings(items, plane, labels) {
+    const text = (value) => (typeof value === "string" ? value : "");
+    const findings = [];
+    const keys = new Set(items.map((item) => `${text(item.commit)}::${text(item.seedDigest)}`));
+    if (keys.size > 1) {
+        findings.push(`${labels.items} reference divergent plane provenance (commit/seedDigest) — a ${labels.run} run drives ONE plane`);
+    }
+    if (!isRecord(plane))
+        return findings;
+    for (const item of items) {
+        if (text(item.seedDigest) !== text(plane.seedDigest) ||
+            text(item.commit) !== text(plane.commit)) {
+            const roleId = typeof item.roleId === "string" ? item.roleId : "(unnamed)";
+            findings.push(`${labels.item} "${roleId}" plane provenance diverges from sharedWorld.plane`);
+            break;
+        }
+    }
+    return findings;
+}
+/** Common shape findings shared by both topologyMode branches. */
+export function sharedWorldCommonFindings(bundle, sw) {
+    const findings = [];
+    if (sw.schema !== SHARED_WORLD_SCHEMA) {
+        findings.push(`sharedWorld.schema must be ${String(SHARED_WORLD_SCHEMA)}`);
+    }
+    if (bundle.attributionClass !== "shared-world") {
+        findings.push("a sharedWorld evidence block requires attributionClass: shared-world");
+    }
+    const plane = sw.plane;
+    if (!isRecord(plane) ||
+        typeof plane.seedDigest !== "string" ||
+        !COMMAND_DIGEST_PATTERN.test(plane.seedDigest)) {
+        findings.push("sharedWorld.plane.seedDigest must be a sha256-16 value");
+    }
+    if (isRecord(plane) && Array.isArray(plane.envNames)) {
+        for (const name of plane.envNames) {
+            if (typeof name !== "string" || !SUBJECT_ENV_NAME_PATTERN.test(name)) {
+                // Does NOT echo the entry: a malformed entry may BE a value.
+                findings.push("sharedWorld.plane.envNames carries an entry that is not an env var NAME shape (values must never appear in evidence)");
+            }
+        }
+    }
+    return findings;
+}
+/**
+ * Tolerant SHAPE guard for the shared-world evidence block (#164). Validates required fields +
+ * types but TOLERATES extra keys (additive): the strict value-shape/timeline checks are
+ * sharedWorldEvidenceFindings' job (an injected value-shaped checkpoint field must pass the shape
+ * guard so verify can catch it fail-closed, not silently bounce off isRunBundle).
+ */
+export function isSharedWorldEvidence(value) {
+    if (!isRecord(value))
+        return false;
+    if (value.schema !== SHARED_WORLD_SCHEMA)
+        return false;
+    if (value.topology !== "shared-world")
+        return false;
+    if (!isNonNegativeSafeInteger(value.roleCount))
+        return false;
+    const plane = value.plane;
+    if (!isRecord(plane))
+        return false;
+    if (plane.commit !== undefined && typeof plane.commit !== "string")
+        return false;
+    if (typeof plane.seedDigest !== "string")
+        return false;
+    if (!(Array.isArray(plane.envNames) && plane.envNames.every((name) => typeof name === "string")))
+        return false;
+    if (plane.hostDigest !== undefined && typeof plane.hostDigest !== "string")
+        return false;
+    if (plane.exposure !== undefined && typeof plane.exposure !== "string")
+        return false;
+    if (plane.publicOriginDigest !== undefined && typeof plane.publicOriginDigest !== "string")
+        return false;
+    if (plane.declaredOriginDigest !== undefined && typeof plane.declaredOriginDigest !== "string")
+        return false;
+    if (value.planeClass !== undefined && typeof value.planeClass !== "string")
+        return false;
+    if (value.lobbyConvergenceDigest !== undefined &&
+        typeof value.lobbyConvergenceDigest !== "string")
+        return false;
+    if (!(Array.isArray(value.attributionLimits) &&
+        value.attributionLimits.every((limit) => typeof limit === "string")))
+        return false;
+    // Tolerant: validate the TYPE of each present field only (the coherence + topologyMode dispatch
+    // are the job of sharedWorldEvidenceFindings — an injected value-shaped field must pass this
+    // guard so verify catches it fail-closed). A bundle must carry at least one of the two shapes.
+    if (value.sequence !== undefined &&
+        !(Array.isArray(value.sequence) && value.sequence.every((id) => typeof id === "string")))
+        return false;
+    if (value.timeline !== undefined &&
+        !(Array.isArray(value.timeline) && value.timeline.every(isSharedWorldTimelineEntry)))
+        return false;
+    if (value.laneWindows !== undefined &&
+        !(Array.isArray(value.laneWindows) && value.laneWindows.every(isSharedWorldLaneWindow)))
+        return false;
+    if (value.stateSeries !== undefined &&
+        !(Array.isArray(value.stateSeries) && value.stateSeries.every(isSharedWorldStateSnapshot)))
+        return false;
+    if (value.outcomes !== undefined &&
+        !(Array.isArray(value.outcomes) && value.outcomes.every(isSharedWorldOutcome)))
+        return false;
+    if (value.timeline === undefined && value.laneWindows === undefined)
+        return false;
+    return true;
+}
+function isSharedWorldTimelineEntry(value) {
+    if (!isRecord(value))
+        return false;
+    if (value.kind === "checkpoint") {
+        return (typeof value.name === "string" &&
+            typeof value.digest === "string" &&
+            typeof value.deltaFromPrev === "boolean");
+    }
+    if (value.kind === "turn") {
+        return (typeof value.roleId === "string" &&
+            typeof value.simId === "string" &&
+            typeof value.streamId === "string" &&
+            typeof value.seedDigest === "string" &&
+            (value.commit === undefined || typeof value.commit === "string"));
+    }
+    return false;
+}
+// Tolerant shape guards for the CONCURRENT series (extra keys tolerated — the digest-only /
+// allowed-keys tripwires are the strict job of sharedWorldEvidenceFindings).
+function isSharedWorldLaneWindow(value) {
+    return (isRecord(value) &&
+        typeof value.roleId === "string" &&
+        (value.actorType === undefined || typeof value.actorType === "string") &&
+        (value.surface === undefined || typeof value.surface === "string") &&
+        (value.caseGroup === undefined || typeof value.caseGroup === "string") &&
+        typeof value.simId === "string" &&
+        typeof value.streamId === "string" &&
+        typeof value.startedAt === "number" &&
+        typeof value.endedAt === "number" &&
+        typeof value.verdict === "string" &&
+        typeof value.routeHostDigest === "string" &&
+        typeof value.seedDigest === "string" &&
+        (value.commit === undefined || typeof value.commit === "string"));
+}
+function isSharedWorldStateSnapshot(value) {
+    return isRecord(value) && typeof value.timestamp === "number" && typeof value.digest === "string";
+}
+function isSharedWorldOutcome(value) {
+    return (isRecord(value) &&
+        typeof value.roleId === "string" &&
+        (value.actorType === undefined || typeof value.actorType === "string") &&
+        (value.surface === undefined || typeof value.surface === "string") &&
+        (value.caseGroup === undefined || typeof value.caseGroup === "string") &&
+        typeof value.simId === "string" &&
+        typeof value.streamId === "string" &&
+        typeof value.status === "string" &&
+        typeof value.ok === "boolean");
+}

package/dist/run/stats.d.ts

@@ -0,0 +1,82 @@
+import { type StudyCosts, type StudyCostRow } from "./costs.js";
+declare const STATS_SCHEMA = "humanish.stats.v1";
+interface StatsParticipants {
+    total: number;
+    reachedGoal: number;
+    reportedFriction: number;
+}
+interface StatsLabRow {
+    lab: string;
+    runs: number;
+    live: number;
+    dryRun: number;
+    /** Runs whose bundle carries a verdict; the denominator for passRate. */
+    judged: number;
+    passed: number;
+    /** passed / judged, absent when judged is 0. */
+    passRate?: number;
+    /** Over live runs with both timestamps. */
+    medianDurationMs?: number;
+    durationSamples: number;
+    /** Participant and desktop median over runs with a known estimate; excludes analysis. */
+    medianCostUsd?: number;
+    costSamples: number;
+    /** Runs with no estimate: a subscription brain, an interrupted run, an old bundle. Never zero. */
+    unpricedRuns: number;
+    participants: StatsParticipants;
+    costs: StudyCosts;
+}
+interface StatsDayRow {
+    day: string;
+    runs: number;
+    live: number;
+    /** Participant and desktop subtotal; `costs` also includes retained analysis. */
+    estimatedSpendUsd: number;
+    unpricedRuns: number;
+    costs: StudyCosts;
+}
+export interface StatsResult {
+    schema: typeof STATS_SCHEMA;
+    ok: true;
+    cwd: string;
+    since?: string;
+    lab?: string;
+    totals: {
+        runs: number;
+        live: number;
+        dryRun: number;
+        running: number;
+        /** Participant and desktop subtotal. costs.estimatedTotalUsd also includes retained analysis. */
+        estimatedSpendUsd: number;
+        unpricedRuns: number;
+        participants: StatsParticipants;
+        verdicts: Record<string, number>;
+        costs: StudyCosts;
+    };
+    labs: StatsLabRow[];
+    days: StatsDayRow[];
+    /** Same selected runs; individual accounting gaps are inspectable without reading private evidence. */
+    costsByRun: StudyCostRow[];
+    /** Directories that could not be read, by name — surfaced, never silently dropped. */
+    unreadable: string[];
+    note: string;
+}
+export interface StatsOptions {
+    /** ISO date or datetime; runs that started before it are excluded. */
+    since?: string;
+    /** Lab id; runs from other labs are excluded. */
+    lab?: string;
+    nowMs?: number;
+}
+export interface StatsFailure {
+    schema: typeof STATS_SCHEMA;
+    ok: false;
+    cwd: string;
+    error: {
+        code: "HUMANISH_STATS_INVALID_SINCE";
+        message: string;
+    };
+}
+export declare function computeStats(cwdInput: string, options?: StatsOptions): Promise<StatsResult | StatsFailure>;
+export declare function formatStatsHuman(result: StatsResult | StatsFailure): string;
+export {};

package/dist/run/stats.js

@@ -0,0 +1,258 @@
+// `humanish stats`: what a directory of studies cost and how they came out. It rolls up per-bundle
+// numbers under the per-run rules: an estimate is labelled an estimate, a run whose cost is unknown
+// counts as unknown and never as zero, and every rate has a denominator next to it.
+import path from "node:path";
+import { readRunIndex } from "./run-index.js";
+import { addStudyCosts, emptyStudyCosts, readStudyCosts, } from "./costs.js";
+import { round6 } from "./pricing.js";
+const STATS_SCHEMA = "humanish.stats.v1";
+const STATS_NOTE = "Every dollar figure is a retained rate-table estimate, never a provider charge. " +
+    "Known spend includes participant/desktop estimates and all distinct recorded analysis attempts; reuse is counted once. " +
+    "Unknown amounts are excluded, not $0. Missing historical attempts cannot be reconstructed. " +
+    "Analysis is attributed to its run's start date, including later reruns. " +
+    "JSON estimatedSpendUsd and medianCostUsd retain their participant/desktop-only meaning; costs includes analysis.";
+function median(values) {
+    if (values.length === 0)
+        return undefined;
+    const sorted = [...values].sort((a, b) => a - b);
+    const mid = Math.floor(sorted.length / 2);
+    return sorted.length % 2 === 1 ? sorted[mid] : (sorted[mid - 1] + sorted[mid]) / 2;
+}
+function emptyParticipants() {
+    return { total: 0, reachedGoal: 0, reportedFriction: 0 };
+}
+function addParticipants(into, entry) {
+    if (entry.participants === undefined)
+        return;
+    into.total += entry.participants.total;
+    into.reachedGoal += entry.participants.reachedGoal;
+    into.reportedFriction += entry.participants.reportedFriction ?? 0;
+}
+function entryTime(entry) {
+    return entry.startedAt ?? entry.completedAt ?? entry.updatedAt;
+}
+function addToLabRow(labs, entry, priced, costs) {
+    const labId = entry.lab?.id ?? "(no lab)";
+    let row = labs.get(labId);
+    if (row === undefined) {
+        row = {
+            lab: labId,
+            runs: 0,
+            live: 0,
+            dryRun: 0,
+            judged: 0,
+            passed: 0,
+            durationSamples: 0,
+            costSamples: 0,
+            unpricedRuns: 0,
+            participants: emptyParticipants(),
+            durations: [],
+            costs: emptyStudyCosts(),
+            runCosts: [],
+        };
+        labs.set(labId, row);
+    }
+    row.runs += 1;
+    if (entry.mode === "live")
+        row.live += 1;
+    if (entry.mode === "dry-run")
+        row.dryRun += 1;
+    if (entry.verdict !== undefined) {
+        row.judged += 1;
+        if (entry.verdict === "pass")
+            row.passed += 1;
+    }
+    if (entry.mode === "live" && entry.durationMs !== undefined)
+        row.durations.push(entry.durationMs);
+    if (priced)
+        row.runCosts.push(entry.estimatedCostUsd);
+    else
+        row.unpricedRuns += 1;
+    addParticipants(row.participants, entry);
+    addStudyCosts(row.costs, costs);
+}
+function addToDayRow(days, entry, priced, costs) {
+    const at = entryTime(entry);
+    const day = at === undefined ? "(undated)" : at.slice(0, 10);
+    let dayRow = days.get(day);
+    if (dayRow === undefined) {
+        dayRow = {
+            day,
+            runs: 0,
+            live: 0,
+            estimatedSpendUsd: 0,
+            unpricedRuns: 0,
+            costs: emptyStudyCosts(),
+        };
+        days.set(day, dayRow);
+    }
+    dayRow.runs += 1;
+    if (entry.mode === "live")
+        dayRow.live += 1;
+    if (priced)
+        dayRow.estimatedSpendUsd += entry.estimatedCostUsd;
+    else
+        dayRow.unpricedRuns += 1;
+    addStudyCosts(dayRow.costs, costs);
+}
+export async function computeStats(cwdInput, options = {}) {
+    const cwd = path.resolve(cwdInput);
+    let sinceMs;
+    if (options.since !== undefined) {
+        sinceMs = Date.parse(options.since);
+        if (Number.isNaN(sinceMs)) {
+            return {
+                schema: STATS_SCHEMA,
+                ok: false,
+                cwd,
+                error: {
+                    code: "HUMANISH_STATS_INVALID_SINCE",
+                    message: `--since must be an ISO date or datetime, got "${options.since}".`,
+                },
+            };
+        }
+    }
+    const index = await readRunIndex(cwd, options.nowMs === undefined ? {} : { nowMs: options.nowMs });
+    // Corrupt source metadata must not hide separately retained paid analysis receipts.
+    // These directories cannot be attributed to a lab/date, so scoped filters exclude them.
+    const indexedIds = new Set(index.runs.map((entry) => entry.runId));
+    const entries = [
+        ...index.runs,
+        ...index.unreadable
+            .filter((id) => !indexedIds.has(id))
+            .map((runId) => ({
+            runId,
+            derivedFrom: "directory",
+            liveness: "interrupted",
+        })),
+    ];
+    const selected = entries.filter((entry) => {
+        if (options.lab !== undefined && entry.lab?.id !== options.lab)
+            return false;
+        if (sinceMs !== undefined) {
+            const at = entryTime(entry);
+            if (at === undefined)
+                return false;
+            const atMs = Date.parse(at);
+            if (Number.isNaN(atMs) || atMs < sinceMs)
+                return false;
+        }
+        return true;
+    });
+    const totals = {
+        runs: 0,
+        live: 0,
+        dryRun: 0,
+        running: 0,
+        estimatedSpendUsd: 0,
+        unpricedRuns: 0,
+        participants: emptyParticipants(),
+        verdicts: {},
+        costs: emptyStudyCosts(),
+    };
+    const labs = new Map();
+    const days = new Map();
+    const costsByRun = [];
+    for (const entry of selected) {
+        const accounting = await readStudyCosts(cwd, entry);
+        costsByRun.push(accounting);
+        addStudyCosts(totals.costs, accounting.costs);
+        totals.runs += 1;
+        if (entry.mode === "live")
+            totals.live += 1;
+        if (entry.mode === "dry-run")
+            totals.dryRun += 1;
+        if (entry.liveness === "running")
+            totals.running += 1;
+        const priced = typeof entry.estimatedCostUsd === "number" &&
+            Number.isFinite(entry.estimatedCostUsd) &&
+            entry.estimatedCostUsd >= 0;
+        if (priced)
+            totals.estimatedSpendUsd += entry.estimatedCostUsd;
+        else
+            totals.unpricedRuns += 1;
+        addParticipants(totals.participants, entry);
+        if (entry.verdict !== undefined)
+            totals.verdicts[entry.verdict] = (totals.verdicts[entry.verdict] ?? 0) + 1;
+        addToLabRow(labs, entry, priced, accounting.costs);
+        addToDayRow(days, entry, priced, accounting.costs);
+    }
+    const labRows = [...labs.values()]
+        .map(({ durations, runCosts, ...row }) => ({
+        ...row,
+        ...(row.judged === 0 ? {} : { passRate: round6(row.passed / row.judged) }),
+        ...(durations.length === 0 ? {} : { medianDurationMs: Math.round(median(durations)) }),
+        durationSamples: durations.length,
+        ...(runCosts.length === 0 ? {} : { medianCostUsd: round6(median(runCosts)) }),
+        costSamples: runCosts.length,
+    }))
+        .sort((a, b) => b.runs - a.runs || a.lab.localeCompare(b.lab));
+    return {
+        schema: STATS_SCHEMA,
+        ok: true,
+        cwd,
+        ...(options.since === undefined ? {} : { since: options.since }),
+        ...(options.lab === undefined ? {} : { lab: options.lab }),
+        totals: { ...totals, estimatedSpendUsd: round6(totals.estimatedSpendUsd) },
+        labs: labRows,
+        days: [...days.values()]
+            .map((row) => ({ ...row, estimatedSpendUsd: round6(row.estimatedSpendUsd) }))
+            .sort((a, b) => a.day.localeCompare(b.day)),
+        costsByRun,
+        unreadable: index.unreadable,
+        note: STATS_NOTE,
+    };
+}
+function money(value) {
+    return `$${value.toFixed(2)}`;
+}
+function knownMoney(value) {
+    return value === null ? "no retained estimate" : money(value);
+}
+function minutes(ms) {
+    return `${(ms / 60_000).toFixed(1)}m`;
+}
+export function formatStatsHuman(result) {
+    if (!result.ok)
+        return `${result.error.code}: ${result.error.message}\n`;
+    const t = result.totals;
+    const scope = [
+        result.lab === undefined ? undefined : `lab ${result.lab}`,
+        result.since === undefined ? undefined : `since ${result.since}`,
+    ].filter((part) => part !== undefined);
+    const lines = [
+        `humanish stats${scope.length === 0 ? "" : ` (${scope.join(", ")})`}`,
+        `runs: ${t.runs} (${t.live} live, ${t.dryRun} dry-run${t.running > 0 ? `, ${t.running} running` : ""})`,
+        `known estimated spend: ${knownMoney(t.costs.estimatedTotalUsd)}`,
+        `participants + desktops: ${knownMoney(t.costs.runEstimatedUsd)}; ${t.costs.incompleteRunEstimates} run(s) with incomplete accounting`,
+        `analysis: ${knownMoney(t.costs.analysisEstimatedUsd)} over ${t.costs.analysisAttempts} recorded attempt(s); ${t.costs.analysisUnpricedAttempts} unpriced, ${t.costs.analysisUnresolvedAttempts} unresolved`,
+        `analysis history: ${t.costs.analysisHistoryUncertainRuns} run(s) missing or uncertain; use --json for per-run accounting`,
+        `participants: ${t.participants.reachedGoal}/${t.participants.total} recorded goal completions, ${t.participants.reportedFriction} reported friction`,
+        `verdicts: ${Object.entries(t.verdicts)
+            .map(([verdict, count]) => `${verdict} ${count}`)
+            .join(", ") || "none recorded"}`,
+    ];
+    if (result.labs.length > 0) {
+        lines.push("", "per lab:");
+        for (const row of result.labs) {
+            const rate = row.passRate === undefined ? "no verdicts" : `${row.passed}/${row.judged} pass`;
+            const duration = row.medianDurationMs === undefined
+                ? "no timed live runs"
+                : `median ${minutes(row.medianDurationMs)} over ${row.durationSamples}`;
+            const cost = row.medianCostUsd === undefined
+                ? "no priced participant/desktop runs"
+                : `participant/desktop median ${money(row.medianCostUsd)} over ${row.costSamples}`;
+            lines.push(`- ${row.lab}: ${row.runs} run(s), ${row.live} live; ${rate}; ${duration}; known study spend ${knownMoney(row.costs.estimatedTotalUsd)}; ${cost}; ${row.unpricedRuns} unpriced runs, ${row.costs.analysisUnpricedAttempts} unpriced analyses`);
+        }
+    }
+    if (result.days.length > 0) {
+        lines.push("", "by day:");
+        for (const row of result.days) {
+            lines.push(`- ${row.day}: ${row.runs} run(s), ${row.live} live, known study spend ${knownMoney(row.costs.estimatedTotalUsd)}, ${row.unpricedRuns} unpriced runs, ${row.costs.analysisUnpricedAttempts} unpriced analyses`);
+        }
+    }
+    if (result.unreadable.length > 0)
+        lines.push("", `unreadable run directories: ${result.unreadable.join(", ")}`);
+    lines.push("", result.note);
+    return `${lines.join("\n")}\n`;
+}

package/dist/run/status.d.ts

@@ -0,0 +1,111 @@
+import type { RunBundle } from "./bundle.js";
+import { type PreparedOutputRoot } from "./contained-output.js";
+import type { ExecutionOutcome } from "./judge.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";
+}
+type RunStatusState = "running" | "finished";
+/** The outcome summary a finalized record carries. Derived from the bundle; never authoritative. */
+interface RunStatusOutcome {
+    /** `review.verdict` verbatim. */
+    verdict?: string;
+    /** True when the run's own envelope reported success: the result's ok, recorded after finish. */
+    ok?: boolean;
+    /** Whether the run worked as an execution, apart from its verdict; recorded after finish. */
+    execution?: ExecutionOutcome;
+    /** `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;
+}
+/** The outcome a finalized status record carries, read from the bundle that was just written. */
+export declare function runStatusOutcome(bundle: RunBundle): RunStatusOutcome;
+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 checks. */
+    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, and never rejects: a failed write is
+     *  swallowed, so a run is never failed by its own index. `startRun` (`src/run/run.ts`) awaits
+     *  it before a route can acquire a sandbox, so a run killed after its sandbox receipt lands
+     *  still has a record to classify. */
+    readonly started: Promise<void>;
+    /** Finalize: state `finished`, `completedAt`, and the derived outcome. Stops the cadence.
+     *  Idempotent — a second call is a no-op, so a backend with several exit paths is safe. */
+    finish(outcome?: RunStatusOutcome): Promise<void>;
+    /** After finish, add the result's ok and execution outcome to the finished record, so status.json
+     *  and the result agree. Before finish it does nothing. */
+    settle(result: {
+        ok: boolean;
+        execution: ExecutionOutcome;
+    }): Promise<void>;
+}
+export interface BeginRunStatusOptions {
+    runId: string;
+    mode: "dry-run" | "live";
+    lab?: RunLabProvenance;
+}
+/**
+ * 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 (the removed meta-lab wrote `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;
+export {};