humanish 0.108.0 → 0.109.0

package/dist/run/results.d.ts

@@ -4,7 +4,7 @@ import type { RunStudyProvenance } from "./study-provenance.js";
 export declare const CLEANUP_SCHEMA = "humanish.cleanup-result.v1";
 export interface RunOptions {
     /** Which manifest produced this run. */
-    lab?: RunStudyProvenance;
+    study?: RunStudyProvenance;
     cwd: string;
     dryRun?: boolean;
     runId?: string;
@@ -30,7 +30,7 @@ export interface RunResult {
     observer?: ObserverResult;
     warnings: string[];
     error?: {
-        code: "HUMANISH_STUDY_ANALYSIS_INVALID" | "HUMANISH_STUDY_ANALYSIS_UNSUPPORTED" | "HUMANISH_STUDY_TASKS_UNSUPPORTED" | "HUMANISH_STUDY_OPTION_UNSUPPORTED" | "HUMANISH_STUDY_COMMS_UNSUPPORTED" | "HUMANISH_LIVE_RUN_UNIMPLEMENTED" | "HUMANISH_INVALID_CWD" | "HUMANISH_RUN_ID_IN_USE" | "HUMANISH_INVALID_PARTICIPANT_COUNT" | "HUMANISH_INVALID_PORT" | "HUMANISH_UNSUPPORTED_RERUN_FLAGS" | "HUMANISH_WATCH_OPTION_CONFLICT" | "HUMANISH_WATCH_SAFE_NOT_APPLICABLE" | "HUMANISH_RUN_OPTION_CONFLICT" | "HUMANISH_OBSERVE_OPTION_CONFLICT" | "HUMANISH_STUDY_SCORER_BAD_REF" | "HUMANISH_STUDY_SCORER_NOT_FOUND" | "HUMANISH_STUDY_SCORER_LOAD_FAILED" | "HUMANISH_STUDY_SCORER_NO_HOOKS" | "HUMANISH_STUDY_SCORER_UNSUPPORTED_BACKEND";
+        code: "HUMANISH_STUDY_ANALYSIS_INVALID" | "HUMANISH_STUDY_ANALYSIS_UNSUPPORTED" | "HUMANISH_STUDY_TASKS_UNSUPPORTED" | "HUMANISH_STUDY_OPTION_UNSUPPORTED" | "HUMANISH_STUDY_V2_UNSUPPORTED" | "HUMANISH_STUDY_COMMS_UNSUPPORTED" | "HUMANISH_LIVE_RUN_UNIMPLEMENTED" | "HUMANISH_INVALID_CWD" | "HUMANISH_RUN_ID_IN_USE" | "HUMANISH_INVALID_PARTICIPANT_COUNT" | "HUMANISH_INVALID_PORT" | "HUMANISH_UNSUPPORTED_RERUN_FLAGS" | "HUMANISH_WATCH_OPTION_CONFLICT" | "HUMANISH_WATCH_SAFE_NOT_APPLICABLE" | "HUMANISH_RUN_OPTION_CONFLICT" | "HUMANISH_OBSERVE_OPTION_CONFLICT" | "HUMANISH_STUDY_SCORER_BAD_REF" | "HUMANISH_STUDY_SCORER_NOT_FOUND" | "HUMANISH_STUDY_SCORER_LOAD_FAILED" | "HUMANISH_STUDY_SCORER_NO_HOOKS" | "HUMANISH_STUDY_SCORER_UNSUPPORTED_BACKEND";
         message: string;
     };
 }

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

@@ -0,0 +1,53 @@
+import type { RunCostSummary } from "./bundle.js";
+import type { AnalysisAccounting } from "./costs.js";
+import type { RunIndexEntry } from "./run-index.js";
+/** The fields of run.json's `cost` that the run cost reads. Completeness is unknown when absent. */
+export type RunCostSubtotal = Pick<RunCostSummary, "estimatedTotalUsd"> & Partial<Pick<RunCostSummary, "fullyEstimated" | "ratesAsOf" | "placeholder">>;
+/** A run's analysis spend, every attempt counted once, as `readAnalysisAccounting` reads it. */
+export interface RunAnalysisCost {
+    /** Requests the run's analyses sent, or may have sent. */
+    requests: number;
+    /** Their known estimated dollars; null when none has a price. */
+    estimatedUsd: number | null;
+    /** True when every request has a complete price and the history was read whole. */
+    complete: boolean;
+    /** Who billed the requests that recorded usage. */
+    providers: Array<"openai" | "codex">;
+}
+/** Complete, a lower bound, or unknown (`null`) when only the subtotal's dollars are at hand. */
+type Completeness = boolean | null;
+export interface RunCost {
+    /** Participants and desktops; null when the run has no cost summary, as in a dry run. */
+    run: {
+        usd: number | null;
+        complete: Completeness;
+        ratesAsOf: string | null;
+        placeholder: boolean;
+    } | null;
+    /** The run's analysis requests; null when it sent none. */
+    analysis: RunAnalysisCost | null;
+    /** The known dollars of both; null when neither has a figure. */
+    total: {
+        usd: number;
+        complete: Completeness;
+    } | null;
+}
+/** The accounting's analysis spend, or null when the run sent no analysis request. */
+export declare function analysisCostOf(accounting: Pick<AnalysisAccounting, "dispatched" | "unresolved" | "unpriced" | "estimatedUsd" | "providers" | "warnings">): RunAnalysisCost | null;
+export declare function runCost(subtotal: RunCostSubtotal | null | undefined, analysis?: RunAnalysisCost | null): RunCost;
+/**
+ * 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 declare function indexedRunCost(entry: Pick<RunIndexEntry, "estimatedCostUsd" | "estimatedCostComplete" | "analysisCost">): RunCost;
+/**
+ * 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 declare function runCostParts(cost: RunCost): string[];
+/**
+ * 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 declare function runCostLabel(cost: RunCost): string | undefined;
+export {};

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,3 +1,5 @@
+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";
@@ -23,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 {
@@ -49,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. */
@@ -81,6 +90,7 @@ interface BundleFacts {
     };
     cost?: {
         estimatedTotalUsd?: number | null;
+        fullyEstimated?: unknown;
     };
 }
 /**

package/dist/run/run-index.js

@@ -15,6 +15,7 @@
 //   - One unreadable run directory degrades that run, never the listing.
 import { readdir, readFile, stat } from "node:fs/promises";
 import path from "node:path";
+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";
@@ -26,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)
@@ -46,6 +49,7 @@ export class RunIndexCache {
             if (!keep.has(runId))
                 this.slots.delete(runId);
         }
+        this.analysis.retain(keep);
     }
     get size() {
         return this.slots.size;
@@ -90,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 } : {}),
     };
 }
@@ -136,6 +143,9 @@ function entryFromBundle(runId, bundle) {
         ...(bundle.cost?.estimatedTotalUsd === undefined
             ? {}
             : { estimatedCostUsd: bundle.cost.estimatedTotalUsd }),
+        ...(typeof bundle.cost?.fullyEstimated === "boolean"
+            ? { estimatedCostComplete: bundle.cost.fullyEstimated }
+            : {}),
     };
 }
 /**
@@ -159,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));
@@ -221,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.d.ts

@@ -11,10 +11,10 @@ interface StartRunOptions {
     runId?: string | undefined;
     mintRunId: () => string;
     mode: "dry-run" | "live";
-    lab?: RunStudyProvenance | 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;
@@ -27,7 +27,7 @@ interface Run {
     readonly createdAt: string;
     readonly mode: "dry-run" | "live";
     /** The manifest the run came from; bundleHead copies it into the bundle. */
-    readonly lab?: RunStudyProvenance;
+    readonly study?: RunStudyProvenance;
     /** Routes write their evidence files through these and hand them to participants. */
     readonly paths: PreparedRunArtifactPaths;
     /**

package/dist/run/run.js

@@ -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/shared-world-evidence.d.ts

@@ -15,7 +15,7 @@ export interface SharedWorldPlane {
      * (the first-class provisioned-subject target every actor drove). A digest replaces the
      * raw URL: a getHost URL embeds the (live) sandbox id and matches the publish-safety e2b-URL
      * redaction, so, like the stream URL and sandbox ids, it never lands raw in a published
-     * bundle (the raw tokenless URL is surfaced only on the ephemeral lab result). The orchestrator
+     * bundle (the raw tokenless URL is surfaced only on the ephemeral study result). The orchestrator
      * confirms the URL is tokenless (no authKey, so no secret reaches the bundle) before digesting.
      * verify proves every actor drove this host by digest equality. Absent on the sequential route.
      */

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

@@ -4,7 +4,7 @@ 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
+// Env var name shape (mirrors ENV_NAME_PATTERN in src/study/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

package/dist/run/stats.d.ts

@@ -5,7 +5,7 @@ interface StatsParticipants {
     reachedGoal: number;
     reportedFriction: number;
 }
-interface StatsLabRow {
+interface StatsStudyRow {
     /** The study's `id`. */
     study: string;
     runs: number;
@@ -55,7 +55,7 @@ export interface StatsResult {
         verdicts: Record<string, number>;
         costs: CostTotals;
     };
-    studies: StatsLabRow[];
+    studies: StatsStudyRow[];
     days: StatsDayRow[];
     /** Same selected runs; individual accounting gaps are inspectable without reading private evidence. */
     costsByRun: CostRow[];
@@ -67,7 +67,7 @@ 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;
+    study?: string;
     nowMs?: number;
 }
 export interface StatsFailure {

package/dist/run/stats.js

@@ -40,12 +40,12 @@ function runEstimateUsd(entry) {
 function entryTime(entry) {
     return entry.startedAt ?? entry.completedAt ?? entry.updatedAt;
 }
-function addToLabRow(labs, entry, runUsd, costs) {
-    const labId = entry.study?.id ?? "(no study)";
-    let row = labs.get(labId);
+function addToStudyRow(studies, entry, runUsd, costs) {
+    const studyId = entry.study?.id ?? "(no study)";
+    let row = studies.get(studyId);
     if (row === undefined) {
         row = {
-            study: labId,
+            study: studyId,
             runs: 0,
             live: 0,
             dryRun: 0,
@@ -59,7 +59,7 @@ function addToLabRow(labs, entry, runUsd, costs) {
             costs: emptyCostTotals(),
             runCosts: [],
         };
-        labs.set(labId, row);
+        studies.set(studyId, row);
     }
     row.runs += 1;
     if (entry.mode === "live")
@@ -123,7 +123,7 @@ export async function computeStats(cwdInput, options = {}) {
     }
     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.
+    // These directories cannot be attributed to a study or date, so scoped filters exclude them.
     const indexedIds = new Set(index.runs.map((entry) => entry.runId));
     const entries = [
         ...index.runs,
@@ -136,7 +136,7 @@ export async function computeStats(cwdInput, options = {}) {
         })),
     ];
     const selected = entries.filter((entry) => {
-        if (options.lab !== undefined && entry.study?.id !== options.lab)
+        if (options.study !== undefined && entry.study?.id !== options.study)
             return false;
         if (sinceMs !== undefined) {
             const at = entryTime(entry);
@@ -159,7 +159,7 @@ export async function computeStats(cwdInput, options = {}) {
         verdicts: {},
         costs: emptyCostTotals(),
     };
-    const labs = new Map();
+    const studies = new Map();
     const days = new Map();
     const costsByRun = [];
     for (const entry of selected) {
@@ -181,10 +181,10 @@ export async function computeStats(cwdInput, options = {}) {
         addParticipants(totals.participants, entry);
         if (entry.verdict !== undefined)
             totals.verdicts[entry.verdict] = (totals.verdicts[entry.verdict] ?? 0) + 1;
-        addToLabRow(labs, entry, runUsd, accounting.costs);
+        addToStudyRow(studies, entry, runUsd, accounting.costs);
         addToDayRow(days, entry, runUsd, accounting.costs);
     }
-    const labRows = [...labs.values()]
+    const studyRows = [...studies.values()]
         .map(({ durations, runCosts, ...row }) => ({
         ...row,
         ...(row.judged === 0 ? {} : { passRate: round6(row.passed / row.judged) }),
@@ -199,9 +199,9 @@ export async function computeStats(cwdInput, options = {}) {
         ok: true,
         cwd,
         ...(options.since === undefined ? {} : { since: options.since }),
-        ...(options.lab === undefined ? {} : { study: options.lab }),
+        ...(options.study === undefined ? {} : { study: options.study }),
         totals: { ...totals, estimatedSpendUsd: round6(totals.estimatedSpendUsd) },
-        studies: labRows,
+        studies: studyRows,
         days: [...days.values()]
             .map((row) => ({ ...row, estimatedSpendUsd: round6(row.estimatedSpendUsd) }))
             .sort((a, b) => a.day.localeCompare(b.day)),
@@ -282,7 +282,7 @@ export function formatStatsHuman(result) {
         return { error: result.error };
     const t = result.totals;
     const scope = [
-        result.study === undefined ? undefined : `lab ${result.study}`,
+        result.study === undefined ? undefined : `study ${result.study}`,
         result.since === undefined ? undefined : `since ${result.since}`,
     ].filter((part) => part !== undefined);
     const lines = [
@@ -295,7 +295,7 @@ export function formatStatsHuman(result) {
     if (reportable) {
         lines.push(...totalsLines(t));
         if (result.studies.length > 0)
-            lines.push("", "per lab:", ...result.studies.map((row) => {
+            lines.push("", "per study:", ...result.studies.map((row) => {
                 const rate = row.passRate === undefined ? "no verdicts" : `${row.passed} of ${row.judged} passed`;
                 const duration = row.medianDurationMs === undefined
                     ? "no timed live runs"