humanish 0.107.0 → 0.109.0

package/dist/run/run-cost.js

@@ -0,0 +1,105 @@
+/** The accounting's analysis spend, or null when the run sent no analysis request. */
+export function analysisCostOf(accounting) {
+    const requests = accounting.dispatched + accounting.unresolved;
+    if (requests === 0)
+        return null;
+    const historyWhole = accounting.warnings.every((warning) => warning === "ANALYSIS_HISTORY_NOT_RECORDED");
+    return {
+        requests,
+        estimatedUsd: accounting.estimatedUsd,
+        complete: accounting.unpriced === 0 && historyWhole,
+        providers: [...accounting.providers],
+    };
+}
+export function runCost(subtotal, analysis) {
+    if (subtotal === null || subtotal === undefined)
+        return { run: null, analysis: null, total: null };
+    const run = {
+        usd: typeof subtotal.estimatedTotalUsd === "number" ? subtotal.estimatedTotalUsd : null,
+        complete: subtotal.fullyEstimated === undefined ? null : subtotal.fullyEstimated,
+        ratesAsOf: subtotal.ratesAsOf ?? null,
+        placeholder: subtotal.placeholder === true,
+    };
+    const spent = analysis ?? null;
+    const known = [run.usd, spent?.estimatedUsd].filter((usd) => typeof usd === "number");
+    if (known.length === 0)
+        return { run, analysis: spent, total: null };
+    const lowerBound = run.usd === null || run.complete === false || spent?.complete === false;
+    return {
+        run,
+        analysis: spent,
+        total: {
+            usd: round6(known.reduce((sum, usd) => sum + usd, 0)),
+            complete: lowerBound ? false : run.complete,
+        },
+    };
+}
+/**
+ * A run index entry's cost: its participants-and-desktops figure, complete or a lower bound when
+ * the status record says which, plus its analyses.
+ */
+export function indexedRunCost(entry) {
+    return runCost({
+        estimatedTotalUsd: entry.estimatedCostUsd ?? null,
+        ...(entry.estimatedCostComplete === undefined
+            ? {}
+            : { fullyEstimated: entry.estimatedCostComplete }),
+    }, entry.analysisCost);
+}
+/** Six decimals, as the run cost summary rounds, so sums of small estimates do not drift. */
+function round6(value) {
+    return Math.round(value * 1e6) / 1e6;
+}
+/** An estimate, saying so when some of the spend has no price and is not in it. */
+function estimateText(usd, complete) {
+    return `est. ~$${usd.toFixed(2)}${complete === false ? " plus unpriced usage" : ""}`;
+}
+function analysesNoun(requests) {
+    return requests === 1 ? "analysis" : `${requests} analyses`;
+}
+function billedBy(providers) {
+    const names = providers.map((provider) => provider === "openai" ? "OpenAI API key" : "Codex account");
+    return names.length === 0 ? "" : ` (${names.join(" and ")})`;
+}
+/**
+ * The cost as separate parts: participants and desktops, then the analysis and the total when the
+ * run sent an analysis request. Empty when the run has no cost summary.
+ */
+export function runCostParts(cost) {
+    if (cost.run === null)
+        return [];
+    const rates = `rates as of ${cost.run.ratesAsOf}${cost.run.placeholder ? ", placeholder" : ""}`;
+    const parts = [
+        cost.run.usd === null
+            ? "Participants + desktops: cost not estimated"
+            : `Participants + desktops: ${estimateText(cost.run.usd, cost.run.complete)} (${rates})`,
+    ];
+    const analysis = cost.analysis;
+    if (analysis === null)
+        return parts;
+    const noun = analysesNoun(analysis.requests);
+    const label = noun.charAt(0).toUpperCase() + noun.slice(1);
+    if (analysis.estimatedUsd === null)
+        parts.push(analysis.providers.length === 1 && analysis.providers[0] === "codex"
+            ? `${label}: Codex account, dollar cost unknown`
+            : `${label}: cost not estimated${billedBy(analysis.providers)}`);
+    else
+        parts.push(`${label}: ${estimateText(analysis.estimatedUsd, analysis.complete)}${billedBy(analysis.providers)}`);
+    if (cost.total !== null)
+        parts.push(`Total: ${estimateText(cost.total.usd, cost.total.complete)}`);
+    return parts;
+}
+/**
+ * The cost in one short label for a list row: the total, and how many analyses it includes.
+ * Undefined when the run has no cost summary.
+ */
+export function runCostLabel(cost) {
+    if (cost.run === null)
+        return undefined;
+    const amount = cost.total === null
+        ? "cost not estimated"
+        : `~$${cost.total.usd.toFixed(2)} est.${cost.total.complete === false ? " plus unpriced usage" : ""}`;
+    return cost.analysis === null
+        ? amount
+        : `${amount}, with ${analysesNoun(cost.analysis.requests)}`;
+}

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

@@ -0,0 +1,15 @@
+import { type RunAnalysisCost } from "./run-cost.js";
+/** Per-run analysis costs, keyed on their fingerprint. Nothing here is authoritative. */
+export declare class AnalysisCostCache {
+    private readonly slots;
+    get(runId: string, fingerprint: string): {
+        cost: RunAnalysisCost | undefined;
+    } | undefined;
+    set(runId: string, fingerprint: string, cost: RunAnalysisCost | undefined): void;
+    retain(keep: Set<string>): void;
+}
+/**
+ * The run's analysis spend for its index entry, read with the same reader stats uses. Undefined
+ * when the run sent no analysis request or its run directory cannot be bound.
+ */
+export declare function readIndexedAnalysisCost(cwd: string, runId: string, cache: AnalysisCostCache | undefined): Promise<RunAnalysisCost | undefined>;

package/dist/run/run-index-analysis.js

@@ -0,0 +1,77 @@
+import { readdir, stat } from "node:fs/promises";
+import path from "node:path";
+import { AUTOMATIC_ANALYSIS_DIRECTORY } from "../analysis/job.js";
+import { ANALYSIS_DIRECTORY, ANALYSIS_EXECUTION_DIRECTORY } from "../analysis/store.js";
+import { readAnalysisAccounting } from "./costs.js";
+import { bindExistingRunArtifactPaths } from "./paths.js";
+import { analysisCostOf } from "./run-cost.js";
+// A run's analysis is written after its status record and bundle are final, so the index keys a
+// run's analysis cost on a fingerprint of the analysis directories, not on the status record. A
+// receipt lands inside an attempt directory that already exists, which changes that directory's
+// mtime and not its parent's, so each attempt directory is part of the fingerprint.
+/** Stat signatures of everything an analysis write changes; null when the run has no analysis. */
+async function analysisFingerprint(runDir) {
+    const signatures = [];
+    for (const directory of [ANALYSIS_EXECUTION_DIRECTORY, ANALYSIS_DIRECTORY]) {
+        const root = path.join(runDir, directory);
+        const rootSignature = await signature(root);
+        if (rootSignature === null)
+            continue;
+        signatures.push(`${directory}:${rootSignature}`);
+        const children = await readdir(root).catch(() => []);
+        for (const child of children.sort((left, right) => left.localeCompare(right)))
+            signatures.push(`${directory}/${child}:${await signature(path.join(root, child))}`);
+    }
+    const job = await signature(path.join(runDir, AUTOMATIC_ANALYSIS_DIRECTORY, "job.json"));
+    if (job !== null)
+        signatures.push(`job:${job}`);
+    return signatures.length === 0 ? null : signatures.join("|");
+}
+async function signature(file) {
+    try {
+        const stats = await stat(file);
+        return `${Number(stats.ino)}:${stats.mtimeMs}:${stats.ctimeMs}:${stats.size}`;
+    }
+    catch {
+        return null;
+    }
+}
+/** Per-run analysis costs, keyed on their fingerprint. Nothing here is authoritative. */
+export class AnalysisCostCache {
+    slots = new Map();
+    get(runId, fingerprint) {
+        const slot = this.slots.get(runId);
+        return slot?.fingerprint === fingerprint ? { cost: slot.cost } : undefined;
+    }
+    set(runId, fingerprint, cost) {
+        this.slots.set(runId, { fingerprint, cost });
+    }
+    retain(keep) {
+        for (const runId of this.slots.keys())
+            if (!keep.has(runId))
+                this.slots.delete(runId);
+    }
+}
+/**
+ * The run's analysis spend for its index entry, read with the same reader stats uses. Undefined
+ * when the run sent no analysis request or its run directory cannot be bound.
+ */
+export async function readIndexedAnalysisCost(cwd, runId, cache) {
+    const fingerprint = await analysisFingerprint(path.join(cwd, ".humanish", "runs", runId));
+    if (fingerprint === null)
+        return undefined;
+    const cached = cache?.get(runId, fingerprint);
+    if (cached !== undefined)
+        return cached.cost;
+    let prepared;
+    try {
+        prepared = await bindExistingRunArtifactPaths(cwd, runId);
+    }
+    catch {
+        // Not cached: a directory that cannot be bound now may bind on the next refresh.
+        return undefined;
+    }
+    const cost = analysisCostOf(await readAnalysisAccounting(prepared)) ?? undefined;
+    cache?.set(runId, fingerprint, cost);
+    return cost;
+}

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

@@ -1,4 +1,7 @@
-import { type RunLabProvenance, type RunLiveness, type RunStatusRecord } from "./status.js";
+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";
 declare const RUN_INDEX_SCHEMA = "humanish.run-index.v1";
 export interface RunIndexEntry {
     runId: string;
@@ -12,7 +15,7 @@ export interface RunIndexEntry {
      * one run's record carries that pid.
      */
     pid?: number;
-    lab?: RunLabProvenance;
+    study?: RunStudyProvenance;
     startedAt?: string;
     updatedAt?: string;
     completedAt?: string;
@@ -22,8 +25,13 @@ export interface RunIndexEntry {
         reachedGoal: number;
         reportedFriction?: number;
     };
+    /** Participants and desktops only; analysis bills separately and is in `analysisCost`. */
     estimatedCostUsd?: number | null;
-    /** Wall-clock span when both ends are known; used for per-lab medians. */
+    /** False when that figure is a lower bound; absent when unknown (a status record before 0.109). */
+    estimatedCostComplete?: boolean;
+    /** The run's analysis requests, every attempt counted once; absent when it sent none. */
+    analysisCost?: RunAnalysisCost;
+    /** Wall-clock span when both ends are known; used for per-study medians. */
     durationMs?: number;
 }
 export interface RunIndexResult {
@@ -31,7 +39,7 @@ export interface RunIndexResult {
     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. */
+    /** 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. */
@@ -48,6 +56,8 @@ interface CacheKey {
  */
 export declare class RunIndexCache {
     private readonly slots;
+    /** Analysis costs, keyed on their own fingerprint: analysis lands after the status record. */
+    readonly analysis: AnalysisCostCache;
     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. */
@@ -59,7 +69,8 @@ interface BundleFacts {
     runId?: string;
     mode?: string;
     createdAt?: string;
-    lab?: RunLabProvenance;
+    study?: unknown;
+    lab?: unknown;
     persona?: {
         source?: string;
     };
@@ -79,6 +90,7 @@ interface BundleFacts {
     };
     cost?: {
         estimatedTotalUsd?: number | null;
+        fullyEstimated?: unknown;
     };
 }
 /**
@@ -95,8 +107,8 @@ export interface ReadRunIndexOptions {
     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. */
+    /** Cap the number of runs returned (newest first). The full directory is still enumerated;
+     *  the cap limits reads, and the count reflects what was read. */
     limit?: number;
 }
 /**

package/dist/run/run-index.js

@@ -1,21 +1,23 @@
-// The run index (#455 PR 2): list and classify every run in a project without parsing bundles.
+// The run index: list and classify every run in a project without parsing bundles.
 //
-// The existing `listRuns` walks each run tree — screenshots included — validating symlinks and
+// 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:
+// 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.
+//     a bundle means finished, receipts without a bundle mean interrupted. That is the
+//     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 { AnalysisCostCache, readIndexedAnalysisCost } from "./run-index-analysis.js";
+import { RUN_STATUS_FILE, classifyRunStatus, isRunStatusRecord, } from "./status.js";
+import { studyProvenanceOf } from "./study-provenance.js";
 import { RUN_BUNDLE_FILE } from "./bundle.js";
 const RUN_INDEX_SCHEMA = "humanish.run-index.v1";
 /**
@@ -25,6 +27,8 @@ const RUN_INDEX_SCHEMA = "humanish.run-index.v1";
  */
 export class RunIndexCache {
     slots = new Map();
+    /** Analysis costs, keyed on their own fingerprint: analysis lands after the status record. */
+    analysis = new AnalysisCostCache();
     get(runId, key) {
         const slot = this.slots.get(runId);
         if (slot === undefined)
@@ -45,6 +49,7 @@ export class RunIndexCache {
             if (!keep.has(runId))
                 this.slots.delete(runId);
         }
+        this.analysis.retain(keep);
     }
     get size() {
         return this.slots.size;
@@ -78,7 +83,7 @@ function entryFromStatus(record, nowMs) {
         liveness: classifyRunStatus(record, nowMs),
         mode: record.mode,
         ...(typeof record.pid === "number" ? { pid: record.pid } : {}),
-        ...(record.lab === undefined ? {} : { lab: record.lab }),
+        ...studyEntry(studyProvenanceOf(record)),
         startedAt: record.startedAt,
         updatedAt: record.updatedAt,
         ...(record.completedAt === undefined ? {} : { completedAt: record.completedAt }),
@@ -89,6 +94,9 @@ function entryFromStatus(record, nowMs) {
         ...(record.outcome?.estimatedCostUsd === undefined
             ? {}
             : { estimatedCostUsd: record.outcome.estimatedCostUsd }),
+        ...(typeof record.outcome?.estimatedCostComplete === "boolean"
+            ? { estimatedCostComplete: record.outcome.estimatedCostComplete }
+            : {}),
         ...(Number.isFinite(started) && Number.isFinite(ended) ? { durationMs: ended - started } : {}),
     };
 }
@@ -98,9 +106,9 @@ function usableStatusRecord(raw, 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
+ * 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
+ * simulations `running`. With no status record there is no freshness to judge, and the
  * reading of "it started, and nothing here says it finished" is interrupted, not finished.
  */
 function bundleLiveness(bundle) {
@@ -117,18 +125,16 @@ export function runLiveness(runId, status, bundle, nowMs) {
         ? { liveness: classifyRunStatus(status, nowMs), record: status }
         : { liveness: bundleLiveness(bundle) };
 }
+function studyEntry(study) {
+    return study === undefined ? {} : { study };
+}
 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 } }),
+        ...studyEntry(studyProvenanceOf(bundle)),
         ...(bundle.createdAt === undefined ? {} : { startedAt: bundle.createdAt }),
         ...(bundle.review?.verdict === undefined ? {} : { verdict: bundle.review.verdict }),
         ...(bundle.review?.participants === undefined
@@ -137,6 +143,9 @@ function entryFromBundle(runId, bundle) {
         ...(bundle.cost?.estimatedTotalUsd === undefined
             ? {}
             : { estimatedCostUsd: bundle.cost.estimatedTotalUsd }),
+        ...(typeof bundle.cost?.fullyEstimated === "boolean"
+            ? { estimatedCostComplete: bundle.cost.fullyEstimated }
+            : {}),
     };
 }
 /**
@@ -160,58 +169,15 @@ export async function readRunIndex(cwdInput, options = {}) {
     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) {
-                // A running record's liveness is time-dependent, so it is recomputed even on a cache hit:
-                // an unchanged record can still have gone stale. An ended record (finished or
-                // interrupted, both with completedAt) keeps the liveness it was cached with.
-                runs.push(cached.derivedFrom === "status" &&
-                    cached.updatedAt !== undefined &&
-                    cached.completedAt === undefined
-                    ? {
-                        ...cached,
-                        liveness: classifyRunStatus({ state: "running", 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;
-            }
+        const entry = await readEntry(runId, path.join(runsRoot, runId), cache, nowMs);
+        if (entry === "unreadable") {
             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" });
+        const analysisCost = entry.derivedFrom === "directory"
+            ? undefined
+            : await readIndexedAnalysisCost(cwd, runId, cache?.analysis);
+        runs.push(analysisCost === undefined ? entry : { ...entry, analysisCost });
     }
     cache?.retain(runIds);
     runs.sort((left, right) => sortKey(right) - sortKey(left));
@@ -222,6 +188,53 @@ export async function readRunIndex(cwdInput, options = {}) {
         unreadable,
     };
 }
+/** One run's entry, cheapest source first, or "unreadable" when its bundle cannot be parsed. */
+async function readEntry(runId, runDir, cache, nowMs) {
+    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) {
+            // A running record's liveness is time-dependent, so it is recomputed even on a cache hit:
+            // an unchanged record can still have gone stale. An ended record (finished or
+            // interrupted, both with completedAt) keeps the liveness it was cached with.
+            return cached.derivedFrom === "status" &&
+                cached.updatedAt !== undefined &&
+                cached.completedAt === undefined
+                ? {
+                    ...cached,
+                    liveness: classifyRunStatus({ state: "running", updatedAt: cached.updatedAt }, nowMs),
+                }
+                : cached;
+        }
+        const raw = await readJson(statusFile);
+        if (usableStatusRecord(raw, runId)) {
+            const entry = entryFromStatus(raw, nowMs);
+            cache?.set(runId, statusKey, entry);
+            return entry;
+        }
+    }
+    // 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)
+            return cached;
+        const raw = await readJson(bundleFile);
+        if (raw === null || typeof raw !== "object")
+            return "unreadable";
+        const entry = entryFromBundle(runId, raw);
+        cache?.set(runId, bundleKey, entry);
+        return entry;
+    }
+    // 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.
+    return { runId, derivedFrom: "directory", liveness: "interrupted" };
+}
 /** 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]) {

package/dist/run/run-not-found.d.ts

@@ -0,0 +1,5 @@
+/**
+ * The message for a run that is not there: how to start one when the project has no runs, or how
+ * to list them when it has. Only the runs directory's entry names are read.
+ */
+export declare function runNotFoundMessage(cwdInput: string, runInput: string): Promise<string>;

package/dist/run/run-not-found.js

@@ -0,0 +1,15 @@
+import { readdir } from "node:fs/promises";
+import path from "node:path";
+import { resolveRunsRoot } from "./paths.js";
+/**
+ * The message for a run that is not there: how to start one when the project has no runs, or how
+ * to list them when it has. Only the runs directory's entry names are read.
+ */
+export async function runNotFoundMessage(cwdInput, runInput) {
+    const cwd = path.resolve(cwdInput);
+    const entries = await readdir(resolveRunsRoot(cwd)).catch(() => []);
+    const hasRun = entries.some((name) => !name.startsWith(".") && !name.endsWith(".json"));
+    return hasRun
+        ? `No run ${runInput}; humanish runs lists them.`
+        : `No runs in ${cwd} yet; start one with humanish run first-run.`;
+}

package/dist/run/run.d.ts

@@ -2,7 +2,8 @@ import { renderObserver, type ObserverResult } from "../observer/render.js";
 import { type RunBundle } from "./bundle.js";
 import type { ExecutionOutcome } from "./judge.js";
 import { type PreparedRunArtifactPaths, type RunIdInUse } from "./paths.js";
-import { type RunLabProvenance, type RunStatusHandle } from "./status.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. */
     cwd: string;
@@ -10,10 +11,10 @@ interface StartRunOptions {
     runId?: string | undefined;
     mintRunId: () => string;
     mode: "dry-run" | "live";
-    lab?: RunLabProvenance | undefined;
+    study?: RunStudyProvenance | undefined;
     /** review.md for the published bundle. */
     renderReview: (bundle: RunBundle) => string;
-    /** Used by `FinishedRun.renderObserver`; `render` is the `LabDeps.renderObserver` seam. */
+    /** Used by `FinishedRun.renderObserver`; `render` is the `StudyDeps.renderObserver` seam. */
     observer?: {
         open: boolean;
         render?: typeof renderObserver | undefined;
@@ -25,8 +26,8 @@ interface Run {
     readonly runId: string;
     readonly createdAt: string;
     readonly mode: "dry-run" | "live";
-    /** The manifest the run came from (#455); bundleHead copies it into the bundle. */
-    readonly lab?: RunLabProvenance;
+    /** The manifest the run came from; bundleHead copies it into the bundle. */
+    readonly study?: RunStudyProvenance;
     /** Routes write their evidence files through these and hand them to participants. */
     readonly paths: PreparedRunArtifactPaths;
     /**

package/dist/run/run.js

@@ -9,7 +9,7 @@ import {} from "./results.js";
 import { createRunArtifactPaths, validatePreparedRunArtifactPaths, } from "./paths.js";
 import { registerActiveRun } from "./active-runs.js";
 import { writeContainedOutputFile, writePreparedRunLatestPointer } from "./contained-output.js";
-import { beginRunStatus, runStatusOutcome, } from "./status.js";
+import { beginRunStatus, runStatusOutcome } from "./status.js";
 /** An entry point called in a state that does not admit it. */
 class RunLifecycleError extends Error {
     name = "RunLifecycleError";
@@ -88,7 +88,7 @@ export async function runScope(fn) {
             const created = await createRunArtifactPaths(options.cwd, runId);
             if (!created.ok)
                 return created;
-            // beginRunStatus reads only the mode and the lab provenance from the run's options.
+            // beginRunStatus reads only the mode and the study provenance from the run's options.
             status = beginRunStatus(created.paths, { ...options, runId });
             // Registered before the first write lands: a signal while it is still settling reaches
             // the handle, whose interrupt queues behind that write.
@@ -156,7 +156,7 @@ export async function runScope(fn) {
             runId,
             createdAt,
             mode: options.mode,
-            ...(options.lab === undefined ? {} : { lab: options.lab }),
+            ...(options.study === undefined ? {} : { study: options.study }),
             paths,
             writeSnapshot(bundle) {
                 if (closed)

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

@@ -9,7 +9,7 @@ export interface SandboxReceipt {
     /** Who allocated the sandbox. Receipts written before this field existed have none. */
     provider?: SandboxProviderId;
     sandboxId: string;
-    /** The create-time sandbox TTL (ms), when known — how long the server-side backstop runs. */
+    /** The create-time sandbox TTL (ms), when known: how long the server-side backstop runs. */
     timeoutMs?: number;
 }
 /**
@@ -22,7 +22,7 @@ export interface ParsedSandboxReceipt extends Omit<SandboxReceipt, "provider"> {
 }
 /**
  * Append one receipt. Best-effort by design: the receipt exists to protect the run, so a failed
- * receipt write must never fail the participant — the only cost of a miss is that `reclaim` cannot see
+ * receipt write must never fail the participant. The only cost of a miss is that `reclaim` cannot see
  * this id and the TTL backstop covers it instead. Containment is the same prepare step every
  * artifact write uses; append (not atomic-replace) keeps racing participants' receipts intact.
  */

package/dist/run/sandbox-receipts.js

@@ -6,7 +6,7 @@ import { prepareContainedOutputFile } from "./contained-output.js";
 export const SANDBOX_RECEIPTS_ARTIFACT = "sandbox-receipts.ndjson";
 /**
  * Append one receipt. Best-effort by design: the receipt exists to protect the run, so a failed
- * receipt write must never fail the participant — the only cost of a miss is that `reclaim` cannot see
+ * receipt write must never fail the participant. The only cost of a miss is that `reclaim` cannot see
  * this id and the TTL backstop covers it instead. Containment is the same prepare step every
  * artifact write uses; append (not atomic-replace) keeps racing participants' receipts intact.
  */
@@ -16,7 +16,7 @@ export async function appendSandboxReceipt(root, receipt) {
         await appendFile(filePath, `${JSON.stringify(receipt)}\n`, "utf8");
     }
     catch {
-        // Swallowed on purpose — see the contract above.
+        // Swallowed on purpose; see the contract above.
     }
 }
 /** Parse a receipts file leniently: a torn final line (crash mid-append) drops, valid lines keep. */
@@ -42,7 +42,7 @@ export function parseSandboxReceipts(text) {
             }
         }
         catch {
-            // torn line — skip
+            // A torn line: skip it.
         }
     }
     return receipts;