humanish 0.107.0 → 0.109.0

package/dist/run/projection.d.ts

@@ -1,32 +1,32 @@
 import type { RunIndexEntry } from "./run-index.js";
-/** One lab as the labs list shows it. */
-export interface LabRollup {
-    labId: string;
-    /** Total runs attributed to this lab. */
+/** One study as the study list shows it. */
+export interface StudyRollup {
+    studyId: string;
+    /** Total runs attributed to this study. */
     runs: number;
     /** Runs whose status record is fresh right now. */
     live: number;
-    /** The newest run of this lab, whatever its state. */
+    /** The newest run of this study, whatever its state. */
     latest?: RunIndexEntry;
-    /** Live runs, newest first — the labs list shows the first one inline. */
+    /** Live runs, newest first; the labs list shows the first one inline. */
     liveRuns: RunIndexEntry[];
 }
 /**
- * Group runs by lab, newest-first within each lab and by recency between labs. Runs with no lab
- * attribution are collected under `unattributed` rather than invented into a lab — the honest
+ * Group runs by study, newest-first within each study and by recency between studies. Runs with no study
+ * attribution are collected under `unattributed` rather than invented into a study. That is the
  * home for pre-contract runs and library callers.
  */
-export declare function groupRunsByLab(entries: readonly RunIndexEntry[]): {
-    labs: LabRollup[];
+export declare function groupRunsByStudy(entries: readonly RunIndexEntry[]): {
+    studies: StudyRollup[];
     unattributed: RunIndexEntry[];
 };
 /**
- * What the launch screen may claim about a lab, and on what evidence. Every figure carries the
+ * What the launch screen may claim about a study, and on what evidence. Every figure carries the
  * number of runs it came from; `sample: 0` means there is nothing to claim and the caller must
  * say so rather than showing an empty number.
  */
-export interface LabExpectation {
-    /** How many completed runs of this lab the figures are drawn from. */
+export interface StudyExpectation {
+    /** How many completed runs of this study the figures are drawn from. */
     sample: number;
     medianDurationMs?: number;
     /** Range across the sample, so the UI can show a span instead of a false point estimate. */
@@ -35,41 +35,41 @@ export interface LabExpectation {
         max: number;
     };
     medianCostUsd?: number;
-    /** Completed runs whose cost was declared absent — excluded from the median, reported here so
+    /** Completed runs whose cost was declared absent: excluded from the median, reported here so
      *  a partial sample can never masquerade as a full one. */
     costUnknown: number;
 }
 /**
- * Derive what to expect from a lab's own history. Only finished runs count: an interrupted run's
+ * Derive what to expect from a study's own history. Only finished runs count: an interrupted run's
  * duration is the length of an accident, not of a study, and including it would quietly bias the
  * estimate the operator uses to decide whether to press Start.
  *
  * The mode matters: mixing modes produces a false figure. A dry run spends nothing and
- * takes no time, so a median over nine dry runs and one live one reports that a live run is free —
+ * takes no time, so a median over nine dry runs and one live one reports that a live run is free,
  * next to a control that spends money. Pass the mode the figure is about; omit it only for a
  * summary that is not attached to an action.
  */
-export declare function expectationFor(entries: readonly RunIndexEntry[], mode?: "dry-run" | "live"): LabExpectation;
+export declare function expectationFor(entries: readonly RunIndexEntry[], mode?: "dry-run" | "live"): StudyExpectation;
 /**
  * The one sentence the launch screen shows about time and money, with its denominator attached.
- * A lab with no history says so plainly instead of borrowing another lab's numbers or inventing
- * a range — "no runs yet" is information, and the operator can still press Start.
+ * A study with no history says so plainly instead of borrowing another study's numbers or inventing
+ * a range. "No runs yet" is information, and the operator can still press Start.
  */
-export declare function expectationLine(expectation: LabExpectation): string;
+export declare function expectationLine(expectation: StudyExpectation): string;
 /**
- * The one line a lab may say about itself, wherever it is shown.
+ * The one line a study may say about itself, wherever it is shown.
  *
  * Prefers live figures: cost and duration are what someone reads before spending, and a median
  * diluted by dry runs reports a live study as cheaper and faster than it has ever been. With no
- * live history it reports the count and claims nothing about time or money — which is why this is
+ * live history it reports the count and claims nothing about time or money. That is why this is
  * shared rather than reimplemented per surface, since the two disagreeing is the whole failure.
  */
-export declare function labSummaryLine(row: Pick<LabRow, "runs" | "declared" | "expectation" | "liveExpectation">): string;
+export declare function studySummaryLine(row: Pick<StudyRow, "runs" | "declared" | "expectation" | "liveExpectation">): string;
 /** Compact duration: seconds under a minute, then m/s, then h/m. */
 export declare function formatDuration(ms: number): string;
 export interface NormalizedThought {
     lines: string[];
-    /** True when the source text did not fit and was cut — shown, never silent. */
+    /** True when the source text did not fit and was cut; shown, never silent. */
     truncated: boolean;
 }
 /**
@@ -77,7 +77,7 @@ export interface NormalizedThought {
  * arrive with markdown section leads (`**Thinking through setup**`) and hard newlines; a terminal
  * needs plain text wrapped to a line budget.
  *
- * The text is never paraphrased or shortened by meaning — only wrapped, and cut at a word boundary
+ * The text is never paraphrased or shortened by meaning. It is only wrapped, and cut at a word boundary
  * with an ellipsis when it does not fit. `truncated` is how the surface says so.
  */
 export declare function normalizeThought(text: string, options: {
@@ -101,16 +101,16 @@ export declare function listWindow(args: {
 };
 /** The label for a run's state, in the register the surfaces share. */
 export declare function livenessLabel(entry: Pick<RunIndexEntry, "liveness" | "verdict">): string;
-/** A lab as the labs list shows it: what is declared, joined to what actually happened. */
-export interface LabRow {
+/** A study as the study list shows it: what is declared, joined to what actually happened. */
+export interface StudyRow {
     /**
-     * Stable identity for this row. A manifest's path when it has one, else the lab id, because two
+     * Stable identity for this row. A manifest's path when it has one, else the study id, because two
      * manifests can declare the same id, and keying rows by id makes them collapse into a pair of
      * indistinguishable duplicates.
      */
     key: string;
     /** The declared id. Run history attributes to this, so it is not unique across manifests. */
-    labId: string;
+    studyId: string;
     /**
      * The handle an operator would actually type. Lab resolution is by filename, so the manifest
      * `\`.humanish/labs/persona-contrast-live.yaml\`` is reached as `persona-contrast-live` even when
@@ -121,25 +121,25 @@ export interface LabRow {
     title?: string;
     /**
      * The shortest label that is unique among the rows it is listed with: the title when no other
-     * lab shares it, else the filename, else the full path. A list is only navigable if every row can
-     * be told from every other one, and a title is not guaranteed to be distinct — two manifests in
+     * study shares it, else the filename, else the full path. A list is only navigable if every row can
+     * be told from every other one, and a title is not guaranteed to be distinct: two manifests in
      * this repo carry the same title and the same declared id, differing only by filename.
      */
     label: string;
     /** The manifest's own words, for the list to say what this study is. */
     description?: string;
-    /** Repo-relative manifest path, absent for a lab known only from run history. */
+    /** Repo-relative manifest path, absent for a study known only from run history. */
     path?: string;
     origin?: "committed" | "ignored" | "explicit";
     /**
-     * False for a lab that has runs but no manifest here: renamed, deleted, or run from a path that
+     * False for a study that has runs but no manifest here: renamed, deleted, or run from a path that
      * is gone. Its runs are still evidence and must stay reachable, so it is listed and marked rather
      * than dropped.
      */
     declared: boolean;
     /**
-     * How many other manifests declare this same lab id. Above zero, the run history below is shared
-     * between them and cannot be attributed to one file — worth saying, because it is a
+     * How many other manifests declare this same study id. Above zero, the run history below is shared
+     * between them and cannot be attributed to one file. That is worth saying, because it is a
      * misconfiguration the operator almost certainly does not know about.
      */
     sharesIdWith: number;
@@ -148,11 +148,11 @@ export interface LabRow {
     latest?: RunIndexEntry;
     liveRuns: RunIndexEntry[];
     /** Across every finished run, whatever its mode. A summary, never attached to a spend decision. */
-    expectation: LabExpectation;
-    /** Live runs only — the figure that belongs beside anything that spends money. */
-    liveExpectation: LabExpectation;
+    expectation: StudyExpectation;
+    /** Live runs only: the figure that belongs beside anything that spends money. */
+    liveExpectation: StudyExpectation;
 }
-export interface DeclaredLab {
+export interface DeclaredStudy {
     id: string;
     title?: string;
     /** The manifest's own description, so a list of studies can say what each one is. */
@@ -161,24 +161,24 @@ export interface DeclaredLab {
     origin?: "committed" | "ignored" | "explicit";
 }
 /**
- * Join declared lab manifests to run history.
+ * Join declared study manifests to run history.
  *
- * Neither side alone is the truth. A fresh project has manifests and no runs — those labs are the
+ * Neither side alone is the truth. A fresh project has manifests and no runs, and those labs are the
  * whole screen, and a list built only from history would be empty on exactly the first visit that
  * matters. A long-lived project accumulates runs from labs whose manifest has since been renamed or
- * deleted — that evidence still exists on disk, so dropping those rows would make real runs
+ * deleted. That evidence still exists on disk, so dropping those rows would make real runs
  * unreachable from the surface that is supposed to list them.
  *
  * One row per manifest, not per id. The two are not the same thing: a manifest is addressed by its
  * filename while its runs attribute to the id declared inside it, so several files can legitimately
  * share an id. Collapsing them hides a real file; keying by id duplicates a row with no way to tell
- * the copies apart. Both happen in practice — this repo has exactly that pair.
+ * the copies apart. Both happen in practice: this repo has exactly that pair.
  *
- * Order puts a lab someone is working in first, then labs by how recently they ran, then declared
+ * Order puts a study someone is working in first, then studies by how recently they ran, then declared
  * labs that have never run (alphabetically by the displayed label, so the order on screen is the
  * order a reader can predict), then labs known only from history.
  */
-export declare function labRows(declared: readonly DeclaredLab[], entries: readonly RunIndexEntry[]): {
-    rows: LabRow[];
+export declare function studyRows(declared: readonly DeclaredStudy[], entries: readonly RunIndexEntry[]): {
+    rows: StudyRow[];
     unattributed: RunIndexEntry[];
 };

package/dist/run/projection.js

@@ -1,49 +1,49 @@
-// The disk→view-model projection (#455 PR 2). Pure functions, no I/O, no rendering: this is where
-// lab grouping, the trust line's arithmetic, thought normalization and list-window math live, so
+// The disk→view-model projection. Pure functions, no I/O, no rendering: this is where
+// study grouping, the trust line's arithmetic, thought normalization and list-window math live, so
 // the parts most likely to be wrong are testable without a terminal.
 //
-// The honesty rules these encode, because they are the ones a UI is most tempted to break:
+// The rules these encode, because they are the ones a UI is most tempted to break:
 //   - a statistic always carries its denominator, and says when it has none;
 //   - an unknown cost is `null` (declared absent), never 0;
 //   - truncation is reported, never silent;
 //   - a participant's reported thinking is quoted, never paraphrased or summarized.
 /**
- * Group runs by lab, newest-first within each lab and by recency between labs. Runs with no lab
- * attribution are collected under `unattributed` rather than invented into a lab — the honest
+ * Group runs by study, newest-first within each study and by recency between studies. Runs with no study
+ * attribution are collected under `unattributed` rather than invented into a study. That is the
  * home for pre-contract runs and library callers.
  */
-export function groupRunsByLab(entries) {
-    const byLab = new Map();
+export function groupRunsByStudy(entries) {
+    const byStudy = new Map();
     const unattributed = [];
     for (const entry of entries) {
-        const labId = entry.lab?.id;
-        if (labId === undefined) {
+        const studyId = entry.study?.id;
+        if (studyId === undefined) {
             unattributed.push(entry);
             continue;
         }
-        const bucket = byLab.get(labId);
+        const bucket = byStudy.get(studyId);
         if (bucket === undefined)
-            byLab.set(labId, [entry]);
+            byStudy.set(studyId, [entry]);
         else
             bucket.push(entry);
     }
-    const labs = [...byLab.entries()].map(([labId, runs]) => {
+    const studies = [...byStudy.entries()].map(([studyId, runs]) => {
         const liveRuns = runs.filter((run) => run.liveness === "running");
         return {
-            labId,
+            studyId,
             runs: runs.length,
             live: liveRuns.length,
             ...(runs[0] === undefined ? {} : { latest: runs[0] }),
             liveRuns,
         };
     });
-    // A lab someone is working in sorts first; otherwise most recently used.
-    labs.sort((left, right) => {
+    // A study someone is working in sorts first; otherwise most recently used.
+    studies.sort((left, right) => {
         if (left.live !== right.live)
             return right.live - left.live;
         return recencyOf(right.latest) - recencyOf(left.latest);
     });
-    return { labs, unattributed };
+    return { studies, unattributed };
 }
 function recencyOf(entry) {
     if (entry === undefined)
@@ -58,12 +58,12 @@ function recencyOf(entry) {
     return 0;
 }
 /**
- * Derive what to expect from a lab's own history. Only finished runs count: an interrupted run's
+ * Derive what to expect from a study's own history. Only finished runs count: an interrupted run's
  * duration is the length of an accident, not of a study, and including it would quietly bias the
  * estimate the operator uses to decide whether to press Start.
  *
  * The mode matters: mixing modes produces a false figure. A dry run spends nothing and
- * takes no time, so a median over nine dry runs and one live one reports that a live run is free —
+ * takes no time, so a median over nine dry runs and one live one reports that a live run is free,
  * next to a control that spends money. Pass the mode the figure is about; omit it only for a
  * summary that is not attached to an action.
  */
@@ -79,7 +79,7 @@ export function expectationFor(entries, mode) {
         .filter((value) => typeof value === "number" && Number.isFinite(value))
         .sort((a, b) => a - b);
     // A cost is unknown whether it was declared absent (`null`) or never recorded at all
-    // (`undefined` — every fail-closed exit finalized with no outcome). Counting only the first
+    // (`undefined`: every fail-closed exit finalized with no outcome). Counting only the first
     // reports "~$1.20 median · 3 runs" for a sample where two runs were never priced, which claims a
     // denominator the figure does not have.
     const costUnknown = finished.filter((entry) => entry.estimatedCostUsd === null || entry.estimatedCostUsd === undefined).length;
@@ -103,8 +103,8 @@ function median(sorted) {
 }
 /**
  * The one sentence the launch screen shows about time and money, with its denominator attached.
- * A lab with no history says so plainly instead of borrowing another lab's numbers or inventing
- * a range — "no runs yet" is information, and the operator can still press Start.
+ * A study with no history says so plainly instead of borrowing another study's numbers or inventing
+ * a range. "No runs yet" is information, and the operator can still press Start.
  */
 export function expectationLine(expectation) {
     if (expectation.sample === 0)
@@ -132,14 +132,14 @@ export function expectationLine(expectation) {
     return `${parts.join(" · ")} · ${sample}${unknown}`;
 }
 /**
- * The one line a lab may say about itself, wherever it is shown.
+ * The one line a study may say about itself, wherever it is shown.
  *
  * Prefers live figures: cost and duration are what someone reads before spending, and a median
  * diluted by dry runs reports a live study as cheaper and faster than it has ever been. With no
- * live history it reports the count and claims nothing about time or money — which is why this is
+ * live history it reports the count and claims nothing about time or money. That is why this is
  * shared rather than reimplemented per surface, since the two disagreeing is the whole failure.
  */
-export function labSummaryLine(row) {
+export function studySummaryLine(row) {
     if (row.runs === 0)
         return row.declared ? "never run" : "no runs";
     if (row.liveExpectation.sample > 0)
@@ -162,7 +162,7 @@ export function formatDuration(ms) {
  * arrive with markdown section leads (`**Thinking through setup**`) and hard newlines; a terminal
  * needs plain text wrapped to a line budget.
  *
- * The text is never paraphrased or shortened by meaning — only wrapped, and cut at a word boundary
+ * The text is never paraphrased or shortened by meaning. It is only wrapped, and cut at a word boundary
  * with an ellipsis when it does not fit. `truncated` is how the surface says so.
  */
 export function normalizeThought(text, options) {
@@ -240,75 +240,75 @@ export function livenessLabel(entry) {
     }
 }
 /** The addressable handle for a manifest: its filename without directory or extension. */
-function labNameFromPath(manifestPath) {
+function studyNameFromPath(manifestPath) {
     const base = manifestPath.split("/").pop() ?? manifestPath;
     return base.replace(/\.(ya?ml)$/i, "");
 }
 /**
- * Join declared lab manifests to run history.
+ * Join declared study manifests to run history.
  *
- * Neither side alone is the truth. A fresh project has manifests and no runs — those labs are the
+ * Neither side alone is the truth. A fresh project has manifests and no runs, and those labs are the
  * whole screen, and a list built only from history would be empty on exactly the first visit that
  * matters. A long-lived project accumulates runs from labs whose manifest has since been renamed or
- * deleted — that evidence still exists on disk, so dropping those rows would make real runs
+ * deleted. That evidence still exists on disk, so dropping those rows would make real runs
  * unreachable from the surface that is supposed to list them.
  *
  * One row per manifest, not per id. The two are not the same thing: a manifest is addressed by its
  * filename while its runs attribute to the id declared inside it, so several files can legitimately
  * share an id. Collapsing them hides a real file; keying by id duplicates a row with no way to tell
- * the copies apart. Both happen in practice — this repo has exactly that pair.
+ * the copies apart. Both happen in practice: this repo has exactly that pair.
  *
- * Order puts a lab someone is working in first, then labs by how recently they ran, then declared
+ * Order puts a study someone is working in first, then studies by how recently they ran, then declared
  * labs that have never run (alphabetically by the displayed label, so the order on screen is the
  * order a reader can predict), then labs known only from history.
  */
-export function labRows(declared, entries) {
-    const { labs, unattributed } = groupRunsByLab(entries);
-    const byId = new Map(labs.map((lab) => [lab.labId, lab]));
+export function studyRows(declared, entries) {
+    const { studies, unattributed } = groupRunsByStudy(entries);
+    const byId = new Map(studies.map((study) => [study.studyId, study]));
     const runsOf = new Map();
     for (const entry of entries) {
-        const labId = entry.lab?.id;
-        if (labId === undefined)
+        const studyId = entry.study?.id;
+        if (studyId === undefined)
             continue;
-        const bucket = runsOf.get(labId);
+        const bucket = runsOf.get(studyId);
         if (bucket === undefined)
-            runsOf.set(labId, [entry]);
+            runsOf.set(studyId, [entry]);
         else
             bucket.push(entry);
     }
     const idCounts = new Map();
-    for (const lab of declared)
-        idCounts.set(lab.id, (idCounts.get(lab.id) ?? 0) + 1);
-    const build = (labId, manifest, isDeclared) => {
-        const rollup = byId.get(labId);
+    for (const study of declared)
+        idCounts.set(study.id, (idCounts.get(study.id) ?? 0) + 1);
+    const build = (studyId, manifest, isDeclared) => {
+        const rollup = byId.get(studyId);
         const manifestPath = manifest?.path;
         return {
-            key: manifestPath ?? `id:${labId}`,
-            labId,
-            name: manifestPath === undefined ? labId : labNameFromPath(manifestPath),
+            key: manifestPath ?? `id:${studyId}`,
+            studyId,
+            name: manifestPath === undefined ? studyId : studyNameFromPath(manifestPath),
             ...(manifest?.title === undefined ? {} : { title: manifest.title }),
             ...(manifestPath === undefined ? {} : { path: manifestPath }),
             ...(manifest?.origin === undefined ? {} : { origin: manifest.origin }),
             declared: isDeclared,
             // Replaced by assignLabels once the whole set is known; a label is only meaningful relative
             // to the rows it sits beside.
-            label: manifest?.title ?? (manifestPath === undefined ? labId : labNameFromPath(manifestPath)),
+            label: manifest?.title ?? (manifestPath === undefined ? studyId : studyNameFromPath(manifestPath)),
             ...(manifest?.description === undefined ? {} : { description: manifest.description }),
-            sharesIdWith: Math.max(0, (idCounts.get(labId) ?? 0) - 1),
+            sharesIdWith: Math.max(0, (idCounts.get(studyId) ?? 0) - 1),
             runs: rollup?.runs ?? 0,
             live: rollup?.live ?? 0,
             ...(rollup?.latest === undefined ? {} : { latest: rollup.latest }),
             liveRuns: rollup?.liveRuns ?? [],
-            expectation: expectationFor(runsOf.get(labId) ?? []),
-            liveExpectation: expectationFor(runsOf.get(labId) ?? [], "live"),
+            expectation: expectationFor(runsOf.get(studyId) ?? []),
+            liveExpectation: expectationFor(runsOf.get(studyId) ?? [], "live"),
         };
     };
-    const declaredIds = new Set(declared.map((lab) => lab.id));
+    const declaredIds = new Set(declared.map((study) => study.id));
     const rows = [
-        ...declared.map((lab) => build(lab.id, lab, true)),
-        ...labs
-            .filter((lab) => !declaredIds.has(lab.labId))
-            .map((lab) => build(lab.labId, undefined, false)),
+        ...declared.map((study) => build(study.id, study, true)),
+        ...studies
+            .filter((study) => !declaredIds.has(study.studyId))
+            .map((study) => build(study.studyId, undefined, false)),
     ];
     // Resolve each row's label before sorting, so the list is ordered by what a reader actually sees.
     assignLabels(rows);
@@ -332,9 +332,9 @@ export function labRows(declared, entries) {
 /**
  * Give every row the shortest label that distinguishes it: title, else filename, else path.
  *
- * Falling straight back to the filename whenever a title repeats — rather than decorating the
- * duplicate with a suffix — keeps the label something the operator can act on, because the filename
- * is exactly what `humanish lab run` takes.
+ * Falling straight back to the filename whenever a title repeats, instead of decorating the
+ * duplicate with a suffix, keeps the label something the operator can act on, because the filename
+ * is exactly what `humanish run` takes.
  */
 function assignLabels(rows) {
     const count = (values) => {

package/dist/run/reclaim.d.ts

@@ -38,7 +38,7 @@ export declare function reclaimRunSandboxes(cwd: string, runInput: string, hooks
  */
 export declare function reclaimPinnedRunSandboxes(cwd: string, runPaths: PreparedRunArtifactPaths, hooks?: ReclaimHooks): Promise<ReclaimResult>;
 /**
- * Kill the sandboxes left by interrupted `humanish lab preflight` probes. A probe journals under
+ * Kill the sandboxes left by interrupted `humanish study check` probes. A probe journals under
  * .humanish/preflight/<probe-id>/ and removes the journal after a confirmed kill, so what is left
  * belongs to a probe that died or could not confirm its teardown. A journal whose probe may still
  * be running is left alone with the reason (see preflightReclaimDecision).

package/dist/run/reclaim.js

@@ -49,8 +49,8 @@ async function reclaimRun(cwd, runInput, locate, hooks) {
     const runId = runIdOf(runPaths);
     const journal = await reclaimJournal(runPaths, hooks);
     if (journal.kind === "empty") {
-        // Honest empty: nothing journaled means either no sandbox was ever created (cheap interrupt —
-        // nothing to reclaim) or the run predates receipts (0.35.x and earlier — the create-time TTL
+        // Empty: nothing journaled means either no sandbox was ever created (cheap interrupt:
+        // nothing to reclaim) or the run predates receipts (0.35.x and earlier, where the create-time TTL
         // is the only backstop for those). Either way there is no id to act on, and saying so beats
         // pretending a scan happened.
         warnings.push("No sandbox-receipts.ndjson in this run dir: either no sandbox was created before the interrupt, or the run predates create-time receipts. Nothing to reclaim by id; server-side kill-on-timeout covers anything that did exist.");
@@ -80,7 +80,7 @@ async function reclaimRun(cwd, runInput, locate, hooks) {
     return result;
 }
 /**
- * Kill the sandboxes left by interrupted `humanish lab preflight` probes. A probe journals under
+ * Kill the sandboxes left by interrupted `humanish study check` probes. A probe journals under
  * .humanish/preflight/<probe-id>/ and removes the journal after a confirmed kill, so what is left
  * belongs to a probe that died or could not confirm its teardown. A journal whose probe may still
  * be running is left alone with the reason (see preflightReclaimDecision).

package/dist/run/results.d.ts

@@ -1,14 +1,14 @@
 import type { ObserverResult } from "../observer/render.js";
 import type { RunProviderResource } from "./bundle.js";
-import type { RunLabProvenance } from "./status.js";
+import type { RunStudyProvenance } from "./study-provenance.js";
 export declare const CLEANUP_SCHEMA = "humanish.cleanup-result.v1";
 export interface RunOptions {
-    /** Which manifest produced this run (#455). */
-    lab?: RunLabProvenance;
+    /** Which manifest produced this run. */
+    study?: RunStudyProvenance;
     cwd: string;
     dryRun?: boolean;
     runId?: string;
-    simCount?: number;
+    participantCount?: number;
     /** Render the run's Observer through the finished run, opening the page when `open` is true.
      *  Without it the preview writes no observer/index.html. */
     observer?: {
@@ -30,7 +30,7 @@ export interface RunResult {
     observer?: ObserverResult;
     warnings: string[];
     error?: {
-        code: "HUMANISH_LAB_ANALYSIS_INVALID" | "HUMANISH_LAB_ANALYSIS_UNSUPPORTED" | "HUMANISH_LAB_TASKS_UNSUPPORTED" | "HUMANISH_LAB_OPTION_UNSUPPORTED" | "HUMANISH_LAB_COMMS_UNSUPPORTED" | "HUMANISH_LIVE_RUN_UNIMPLEMENTED" | "HUMANISH_INVALID_CWD" | "HUMANISH_RUN_ID_IN_USE" | "HUMANISH_INVALID_SIM_COUNT" | "HUMANISH_INVALID_PORT" | "HUMANISH_UNSUPPORTED_RERUN_FLAGS" | "HUMANISH_WATCH_OPTION_CONFLICT" | "HUMANISH_WATCH_SAFE_NOT_APPLICABLE" | "HUMANISH_APP_URL_REMOVED" | "HUMANISH_LAB_SCORER_BAD_REF" | "HUMANISH_LAB_SCORER_NOT_FOUND" | "HUMANISH_LAB_SCORER_LOAD_FAILED" | "HUMANISH_LAB_SCORER_NO_HOOKS" | "HUMANISH_LAB_SCORER_UNSUPPORTED_BACKEND";
+        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 {};