humanish 0.107.0 → 0.109.0

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

@@ -1,6 +1,6 @@
 import type { ParticipantIds } from "./participant-records.js";
 export declare const SHARED_WORLD_SCHEMA = "humanish.shared-world.v1";
-/** The shared service-plane provenance for a shared-world run (#164): single commit + a
+/** The shared service-plane provenance for a shared-world run: single commit + a
  *  seed-recipe digest + the provisioned env names (never values). */
 export interface SharedWorldPlane {
     /** The cloned commit SHA of the shared plane (when the clone resolved one). */
@@ -11,13 +11,13 @@ export interface SharedWorldPlane {
     /** Declared env names provisioned for the shared plane (values never surface). */
     envNames: string[];
     /**
-     * Concurrent route only (#164 phase 2): sha256-16 of the harness-minted `getHost` URL's origin
-     * (the first-class provisioned-subject target every actor drove, per invariant 2). A digest replaces the
+     * Concurrent route only: sha256-16 of the harness-minted `getHost` URL's origin
+     * (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 like sandbox ids — it never lands raw in a published
-     * bundle (the raw tokenless URL is surfaced only on the ephemeral lab result). The orchestrator
-     * confirms the URL is tokenless (no authKey, per invariant 1) before digesting. verify proves every
-     * actor drove this host by digest equality. Absent on the sequential route.
+     * 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 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.
      */
     hostDigest?: string;
     /**
@@ -30,17 +30,17 @@ export interface SharedWorldPlane {
      */
     exposure?: "synthetic";
     /**
-     * External-public plane class only (#164 phase 2): sha256-16 of the observed origin the seats
+     * External-public plane class only: sha256-16 of the observed origin the participants
      * converged on. It is the counterpart of hostDigest with a weaker, disclosed claim: the harness only
-     * observes that each seat reached this origin and never minted it. It is derived from what the
-     * seats actually reached; the declared appUrl does not feed it. verify proves every laneWindow.routeHostDigest
-     * (that seat's CDP-observed final URL origin) equals it, which shows inter-seat convergence on one observed
-     * origin, not harness control of the plane. A digest, not the raw origin (kept consistent with
-     * hostDigest hygiene). Absent on getHost.
+     * observes that each participant reached this origin and never minted it. It is derived from what
+     * the participants actually reached; the declared appUrl does not feed it. verify proves every
+     * laneWindow.routeHostDigest (that participant's CDP-observed final URL origin) equals it, which
+     * shows cross-participant convergence on one observed origin, not harness control of the plane. A
+     * digest, not the raw origin (kept consistent with hostDigest hygiene). Absent on getHost.
      */
     publicOriginDigest?: string;
     /**
-     * EXTERNAL-PUBLIC plane class only: sha256-16 of the operator-DECLARED origin (from subject.appUrl),
+     * External-public plane class only: sha256-16 of the operator-declared origin (from subject.appUrl),
      * recorded for reference/evidence only. It is never asserted equal to publicOriginDigest: a normal
      * cross-origin redirect (apex->www, http->https) makes the observed origin differ from the declared
      * one, which is expected. Operator ownership rests on the subject.publicTarget.authorized attestation
@@ -49,7 +49,7 @@ export interface SharedWorldPlane {
     declaredOriginDigest?: string;
 }
 /**
- * Concurrent shape (#164 phase 2): one actor's harness-clocked activity window against the one
+ * Concurrent shape: one actor's harness-clocked activity window against the one
  * shared plane. Overlapping windows mechanically prove ≥2 personas were active simultaneously.
  * `laneWindows` and `stateSeries` are independent series. There is deliberately no per-delta→actor
  * field, because under concurrency the evidence cannot say which actor caused a state change.
@@ -68,9 +68,9 @@ export interface SharedWorldParticipantWindow {
     endedAt: number;
     /** The actor's terminal session verdict (per-persona). */
     verdict: string;
-    /** sha256-16 of the origin of the getHost seat URL this actor drove. verify confirms it equals
-     *  plane.hostDigest, so the actor drove exactly the harness-minted host (invariant 2).
-     *  A digest, not the raw URL (a getHost URL is not publish-safe — see SharedWorldPlane.hostDigest). */
+    /** sha256-16 of the origin of the getHost participant URL this actor drove. verify confirms it
+     *  equals plane.hostDigest, so the actor drove exactly the harness-minted host. A digest, not the
+     *  raw URL (a getHost URL is not publish-safe; see SharedWorldPlane.hostDigest). */
     routeHostDigest: string;
     /** The shared plane's commit this actor observed (omitted when unresolved). */
     commit?: string;
@@ -109,19 +109,19 @@ export declare function sharedWorldParticipantKeys(ids: ParticipantIds, particip
     readonly caseGroup?: string;
 }): Pick<SharedWorldOutcome, "roleId" | "actorType" | "surface" | "caseGroup" | "simId" | "streamId">;
 /** A timeline checkpoint: a read-only digest probe of the shared plane at one moment. Persisted
- *  DIGEST-ONLY — `digest` is sha256-16(scrub+redact(stdout)); no raw value ever lands. */
+ *  digest-only: `digest` is sha256-16(scrub+redact(stdout)); no raw value ever lands. */
 export interface SharedWorldCheckpoint {
     kind: "checkpoint";
     /** "cp-baseline" for the baseline snapshot; "cp-after-<roleId>" after each role's turn. */
     name: string;
     /** sha256-16 of the (scrubbed, redacted) combined probe output at this snapshot. */
     digest: string;
-    /** True when this snapshot's digest differs from the previous checkpoint's — the observed
+    /** True when this snapshot's digest differs from the previous checkpoint's, meaning the observed
      *  state changed across the intervening turn (the delta is attributed to the whole turn). */
     deltaFromPrev: boolean;
 }
-/** A timeline turn: one role's seat session against the shared plane. Carries the plane
- *  provenance it observed (identical across turns by construction — the single-plane proof). */
+/** A timeline turn: one participant's session against the shared plane. Carries the plane
+ *  provenance it observed (identical across turns by construction: the single-plane proof). */
 interface SharedWorldTurn {
     kind: "turn";
     roleId: string;
@@ -135,8 +135,8 @@ interface SharedWorldTurn {
     seedDigest: string;
 }
 type SharedWorldTimelineEntry = SharedWorldCheckpoint | SharedWorldTurn;
-/** Declared seats that were never started after one executed sequential role stopped the run.
- * The executed timeline plus this ordered tail must account for every declared sim/stream. */
+/** Declared participants that were never started after one executed sequential role stopped the
+ * run. The executed timeline plus this ordered tail must account for every declared sim/stream. */
 interface SharedWorldSkippedTail {
     afterRoleId: string;
     roles: Array<{
@@ -156,10 +156,10 @@ interface SharedWorldSkippedTail {
  * - Sequential (`topologyMode: "sequential"`): `sequence` + an alternating `timeline`
  *   (cp-baseline → turn → cp → … → cp); limits `sequential-only` etc. No route writes it since
  *   0.106.0; verify still reads it so older bundles keep verifying.
- * - Concurrent (`topologyMode: "concurrent"`, #164 phase 2): `laneWindows` + `stateSeries` +
+ * - Concurrent (`topologyMode: "concurrent"`): `laneWindows` + `stateSeries` +
  *   `outcomes`; limits `concurrent` etc. No `timeline`.
  *
- * Additive + optional on `humanish.run-bundle.v1` — absent on every non-shared-world bundle.
+ * Additive + optional on `humanish.run-bundle.v1`: absent on every non-shared-world bundle.
  * The mandatory `attributionLimits` are verify-enforced (fail closed on a missing required or a
  * present forbidden limit).
  */
@@ -169,26 +169,27 @@ export interface SharedWorldEvidence {
     /** The substrate discriminator. Branched on first by sharedWorldEvidenceFindings. */
     topologyMode: "sequential" | "concurrent";
     /**
-     * Concurrent route only (#164 phase 2): the plane-class discriminator. Absent == the historical
-     * "provisioned-getHost" plane (a clone/local-tree subject served + getHost-exposed in-sandbox — the
+     * Concurrent route only: the plane-class discriminator. Absent == the historical
+     * "provisioned-getHost" plane (a clone/local-tree subject served + getHost-exposed in-sandbox; the
      * harness minted the host; synthetic-seeded attestation + authoritative in-sandbox checkpoint
      * stateSeries). "external-public" == a real operator-owned public deployment used directly as the
      * plane (no getHost/clone/seed; the operator attests it and the harness does not control it; no authoritative
-     * shared-state proof — concurrency evidenced by temporal co-occupancy + observed lobby convergence).
+     * shared-state proof: concurrency evidenced by temporal co-occupancy + observed lobby convergence).
      * verify gates every getHost-specific assertion on this discriminator; existing bundles omit it and
      * default to provisioned-getHost, byte-stable.
      */
     planeClass?: "provisioned-getHost" | "external-public";
-    /** The declared number of role seats. */
+    /** The declared number of participants. */
     roleCount: number;
     plane: SharedWorldPlane;
     /** The pinned, verify-enforced attribution ceiling (the set differs per topologyMode/planeClass). */
     attributionLimits: string[];
     /**
-     * EXTERNAL-PUBLIC plane class only (#164 phase 2, optional-but-strong): sha256-16 of the shared
-     * `/lobby/CODE` path every seat's CDP-observed URL converged on: the concrete "they were in one
-     * shared world" proof, observation-derived and needing no subject change. Digest-only (the raw
-     * 6-char lobby code and full URLs are runtime-only and never land). Absent when seats did not converge.
+     * External-public plane class only (optional-but-strong): sha256-16 of the shared
+     * `/lobby/CODE` path every participant's CDP-observed URL converged on: the concrete "they were
+     * in one shared world" proof, observation-derived and needing no subject change. Digest-only (the
+     * raw 6-char lobby code and full URLs are runtime-only and never land). Absent when participants
+     * did not converge.
      */
     lobbyConvergenceDigest?: string;
     /** The role ids that actually took a turn, in declared order. */
@@ -210,8 +211,8 @@ interface ParticipantWindow {
 }
 /**
  * What a shared-world run shows about concurrency, as verify's pass gate and the judge both read
- * it: whether two or more seats were live at once, and, when the plane keeps a state series (the
- * provisioned plane), whether the state changed at or after the first overlap started.
+ * it: whether two or more participants were live at once, and, when the plane keeps a state series
+ * (the provisioned plane), whether the state changed at or after the first overlap started.
  */
 export declare function concurrencyFacts(windows: readonly ParticipantWindow[], stateSeries: readonly SharedWorldStateSnapshot[] | undefined): {
     overlap: boolean;

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

@@ -1,5 +1,5 @@
-// The sharedWorld block of run.json (humanish.shared-world.v1): the one shared plane, each seat's
-// window, state snapshots and the interleaved timeline of checkpoints and turns.
+// The sharedWorld block of run.json (humanish.shared-world.v1): the one shared plane, each
+// participant's window, state snapshots and the interleaved timeline of checkpoints and turns.
 export const SHARED_WORLD_SCHEMA = "humanish.shared-world.v1";
 /**
  * The fields a window and an outcome start with, in the saved order: the participant id saved as
@@ -30,8 +30,8 @@ function overlapStarts(windows) {
 }
 /**
  * What a shared-world run shows about concurrency, as verify's pass gate and the judge both read
- * it: whether two or more seats were live at once, and, when the plane keeps a state series (the
- * provisioned plane), whether the state changed at or after the first overlap started.
+ * it: whether two or more participants were live at once, and, when the plane keeps a state series
+ * (the provisioned plane), whether the state changed at or after the first overlap started.
  */
 export function concurrencyFacts(windows, stateSeries) {
     const starts = overlapStarts(windows);

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

@@ -18,7 +18,7 @@ export declare function planeProvenanceFindings(items: readonly Record<string, u
 /** Common shape findings shared by both topologyMode branches. */
 export declare function sharedWorldCommonFindings(bundle: RunBundle, sw: SharedWorldEvidence): string[];
 /**
- * Tolerant shape guard for the shared-world evidence block (#164). Validates required fields +
+ * Tolerant shape guard for the shared-world evidence block. Validates required fields +
  * types and tolerates extra keys (additive): the strict value-shape/timeline checks are
  * sharedWorldEvidenceFindings' job (an injected value-shaped checkpoint field must pass the shape
  * guard so verify can catch it fail-closed, not silently bounce off isRunBundle).

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

@@ -4,18 +4,18 @@ 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
-// if any is absent — omission overclaims): sequential turns only, no concurrency/races handled, and
+// if any is absent, because omission overclaims): sequential turns only, no concurrency/races handled, and
 // a checkpoint delta is attributed to the turn it followed, never a specific action (correlation).
 export const MANDATORY_ATTRIBUTION_LIMITS = [
     "sequential-only",
     "no-concurrent-races",
     "delta-attributed-to-turn-not-action",
 ];
-// A shared-world checkpoint record persists DIGEST-ONLY: exactly these keys, nothing value-shaped.
+// A shared-world checkpoint record persists digest-only: exactly these keys, nothing value-shaped.
 export const SHARED_WORLD_CHECKPOINT_KEYS = new Set(["kind", "name", "digest", "deltaFromPrev"]);
 // A concurrent stateSeries record is digest-only too: it permits a numeric timestamp + the
 // sha256-16 digest; any other key is a value-shaped leak / a smuggled per-delta→actor field.
@@ -30,7 +30,7 @@ export function planeProvenanceFindings(items, plane, labels) {
     const findings = [];
     const keys = new Set(items.map((item) => `${text(item.commit)}::${text(item.seedDigest)}`));
     if (keys.size > 1) {
-        findings.push(`${labels.items} reference divergent plane provenance (commit/seedDigest) — a ${labels.run} run drives ONE plane`);
+        findings.push(`${labels.items} reference different plane provenance (commit or seedDigest), but a ${labels.run} run uses one plane`);
     }
     if (!isRecord(plane))
         return findings;
@@ -63,14 +63,14 @@ export function sharedWorldCommonFindings(bundle, sw) {
         for (const name of plane.envNames) {
             if (typeof name !== "string" || !SUBJECT_ENV_NAME_PATTERN.test(name)) {
                 // Never echoes the entry: a malformed entry may be a value.
-                findings.push("sharedWorld.plane.envNames carries an entry that is not an env var NAME shape (values must never appear in evidence)");
+                findings.push("sharedWorld.plane.envNames has an entry that is not an environment variable name; evidence may hold names only, never values");
             }
         }
     }
     return findings;
 }
 /**
- * Tolerant shape guard for the shared-world evidence block (#164). Validates required fields +
+ * Tolerant shape guard for the shared-world evidence block. Validates required fields +
  * types and tolerates extra keys (additive): the strict value-shape/timeline checks are
  * sharedWorldEvidenceFindings' job (an injected value-shaped checkpoint field must pass the shape
  * guard so verify can catch it fail-closed, not silently bounce off isRunBundle).
@@ -110,7 +110,7 @@ export function isSharedWorldEvidence(value) {
         value.attributionLimits.every((limit) => typeof limit === "string")))
         return false;
     // Tolerant: validate the type of each present field only (the coherence + topologyMode dispatch
-    // are the job of sharedWorldEvidenceFindings — an injected value-shaped field must pass this
+    // are the job of sharedWorldEvidenceFindings; an injected value-shaped field must pass this
     // guard so verify catches it fail-closed). A bundle must carry at least one of the two shapes.
     if (value.sequence !== undefined &&
         !(Array.isArray(value.sequence) && value.sequence.every((id) => typeof id === "string")))

package/dist/run/stats.d.ts

@@ -1,12 +1,13 @@
 import { type CostTotals, type CostRow } from "./costs.js";
-declare const STATS_SCHEMA = "humanish.stats.v1";
+declare const STATS_SCHEMA = "humanish.stats.v2";
 interface StatsParticipants {
     total: number;
     reachedGoal: number;
     reportedFriction: number;
 }
-interface StatsLabRow {
-    lab: string;
+interface StatsStudyRow {
+    /** The study's `id`. */
+    study: string;
     runs: number;
     live: number;
     dryRun: number;
@@ -40,7 +41,8 @@ export interface StatsResult {
     ok: true;
     cwd: string;
     since?: string;
-    lab?: string;
+    /** The study the stats are limited to, when one was given. */
+    study?: string;
     totals: {
         runs: number;
         live: number;
@@ -53,11 +55,11 @@ export interface StatsResult {
         verdicts: Record<string, number>;
         costs: CostTotals;
     };
-    labs: StatsLabRow[];
+    studies: StatsStudyRow[];
     days: StatsDayRow[];
     /** Same selected runs; individual accounting gaps are inspectable without reading private evidence. */
     costsByRun: CostRow[];
-    /** Directories that could not be read, by name — surfaced, never silently dropped. */
+    /** Directories that could not be read, by name: surfaced, never silently dropped. */
     unreadable: string[];
     note: string;
 }
@@ -65,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 {
@@ -78,5 +80,9 @@ export interface StatsFailure {
     };
 }
 export declare function computeStats(cwdInput: string, options?: StatsOptions): Promise<StatsResult | StatsFailure>;
-export declare function formatStatsHuman(result: StatsResult | StatsFailure): string;
+/** Human output; a failure is an error the CLI prints on stderr (HumanOutput in src/cli/io.ts). */
+export declare function formatStatsHuman(result: StatsResult): string;
+export declare function formatStatsHuman(result: StatsResult | StatsFailure): string | {
+    error: StatsFailure["error"];
+};
 export {};

package/dist/run/stats.js

@@ -5,12 +5,10 @@ import path from "node:path";
 import { readRunIndex } from "./run-index.js";
 import { addCostTotals, emptyCostTotals, readCostTotals, } from "./costs.js";
 import { round6 } from "./pricing.js";
-const STATS_SCHEMA = "humanish.stats.v1";
-const STATS_NOTE = "Every dollar figure is a retained rate-table estimate, never a provider charge. " +
-    "Known spend includes participant/desktop estimates and all distinct recorded analysis attempts; reuse is counted once. " +
-    "Unknown amounts are excluded, not $0. Missing historical attempts cannot be reconstructed. " +
-    "Analysis is attributed to its run's start date, including later reruns. " +
-    "JSON estimatedSpendUsd and medianCostUsd retain their participant/desktop-only meaning; costs includes analysis.";
+import { plural } from "./text.js";
+const STATS_SCHEMA = "humanish.stats.v2";
+// docs/contracts/study-costs.md holds the accounting rules this sentence summarizes.
+const STATS_NOTE = "Dollar figures are estimates from humanish's rate table, never provider charges, and a cost humanish does not know is left out of every total.";
 function median(values) {
     if (values.length === 0)
         return undefined;
@@ -28,15 +26,26 @@ function addParticipants(into, entry) {
     into.reachedGoal += entry.participants.reachedGoal;
     into.reportedFriction += entry.participants.reportedFriction ?? 0;
 }
+/**
+ * A run's participant and desktop estimate: its recorded figure, or $0 for a dry run that records
+ * none, since a dry run makes no model request and creates no desktop. Undefined when the cost is
+ * unknown, including a dry run that records an unknown (null) figure.
+ */
+function runEstimateUsd(entry) {
+    const usd = entry.estimatedCostUsd;
+    if (typeof usd === "number" && Number.isFinite(usd) && usd >= 0)
+        return usd;
+    return usd === undefined && entry.mode === "dry-run" ? 0 : undefined;
+}
 function entryTime(entry) {
     return entry.startedAt ?? entry.completedAt ?? entry.updatedAt;
 }
-function addToLabRow(labs, entry, priced, costs) {
-    const labId = entry.lab?.id ?? "(no lab)";
-    let row = labs.get(labId);
+function addToStudyRow(studies, entry, runUsd, costs) {
+    const studyId = entry.study?.id ?? "(no study)";
+    let row = studies.get(studyId);
     if (row === undefined) {
         row = {
-            lab: labId,
+            study: studyId,
             runs: 0,
             live: 0,
             dryRun: 0,
@@ -50,7 +59,7 @@ function addToLabRow(labs, entry, priced, costs) {
             costs: emptyCostTotals(),
             runCosts: [],
         };
-        labs.set(labId, row);
+        studies.set(studyId, row);
     }
     row.runs += 1;
     if (entry.mode === "live")
@@ -64,14 +73,14 @@ function addToLabRow(labs, entry, priced, costs) {
     }
     if (entry.mode === "live" && entry.durationMs !== undefined)
         row.durations.push(entry.durationMs);
-    if (priced)
-        row.runCosts.push(entry.estimatedCostUsd);
-    else
+    if (runUsd === undefined)
         row.unpricedRuns += 1;
+    else
+        row.runCosts.push(runUsd);
     addParticipants(row.participants, entry);
     addCostTotals(row.costs, costs);
 }
-function addToDayRow(days, entry, priced, costs) {
+function addToDayRow(days, entry, runUsd, costs) {
     const at = entryTime(entry);
     const day = at === undefined ? "(undated)" : at.slice(0, 10);
     let dayRow = days.get(day);
@@ -89,10 +98,10 @@ function addToDayRow(days, entry, priced, costs) {
     dayRow.runs += 1;
     if (entry.mode === "live")
         dayRow.live += 1;
-    if (priced)
-        dayRow.estimatedSpendUsd += entry.estimatedCostUsd;
-    else
+    if (runUsd === undefined)
         dayRow.unpricedRuns += 1;
+    else
+        dayRow.estimatedSpendUsd += runUsd;
     addCostTotals(dayRow.costs, costs);
 }
 export async function computeStats(cwdInput, options = {}) {
@@ -114,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,
@@ -127,7 +136,7 @@ export async function computeStats(cwdInput, options = {}) {
         })),
     ];
     const selected = entries.filter((entry) => {
-        if (options.lab !== undefined && entry.lab?.id !== options.lab)
+        if (options.study !== undefined && entry.study?.id !== options.study)
             return false;
         if (sinceMs !== undefined) {
             const at = entryTime(entry);
@@ -150,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) {
@@ -164,20 +173,18 @@ export async function computeStats(cwdInput, options = {}) {
             totals.dryRun += 1;
         if (entry.liveness === "running")
             totals.running += 1;
-        const priced = typeof entry.estimatedCostUsd === "number" &&
-            Number.isFinite(entry.estimatedCostUsd) &&
-            entry.estimatedCostUsd >= 0;
-        if (priced)
-            totals.estimatedSpendUsd += entry.estimatedCostUsd;
-        else
+        const runUsd = runEstimateUsd(entry);
+        if (runUsd === undefined)
             totals.unpricedRuns += 1;
+        else
+            totals.estimatedSpendUsd += runUsd;
         addParticipants(totals.participants, entry);
         if (entry.verdict !== undefined)
             totals.verdicts[entry.verdict] = (totals.verdicts[entry.verdict] ?? 0) + 1;
-        addToLabRow(labs, entry, priced, accounting.costs);
-        addToDayRow(days, entry, priced, accounting.costs);
+        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) }),
@@ -186,15 +193,15 @@ export async function computeStats(cwdInput, options = {}) {
         ...(runCosts.length === 0 ? {} : { medianCostUsd: round6(median(runCosts)) }),
         costSamples: runCosts.length,
     }))
-        .sort((a, b) => b.runs - a.runs || a.lab.localeCompare(b.lab));
+        .sort((a, b) => b.runs - a.runs || a.study.localeCompare(b.study));
     return {
         schema: STATS_SCHEMA,
         ok: true,
         cwd,
         ...(options.since === undefined ? {} : { since: options.since }),
-        ...(options.lab === undefined ? {} : { lab: options.lab }),
+        ...(options.study === undefined ? {} : { study: options.study }),
         totals: { ...totals, estimatedSpendUsd: round6(totals.estimatedSpendUsd) },
-        labs: labRows,
+        studies: studyRows,
         days: [...days.values()]
             .map((row) => ({ ...row, estimatedSpendUsd: round6(row.estimatedSpendUsd) }))
             .sort((a, b) => a.day.localeCompare(b.day)),
@@ -212,47 +219,98 @@ function knownMoney(value) {
 function minutes(ms) {
     return `${(ms / 60_000).toFixed(1)}m`;
 }
+/**
+ * Whether every selected run is a dry run whose accounting is a complete $0: no recorded figure,
+ * no incomplete estimate and no analysis attempt. Only then does the one-line report hold.
+ */
+function onlyFreeDryRuns(t) {
+    return (t.runs > 0 &&
+        t.runs === t.dryRun &&
+        t.costs.estimatedTotalUsd === 0 &&
+        t.costs.incompleteRunEstimates === 0 &&
+        t.costs.analysisAttempts === 0);
+}
+/** The run counts, with dry runs on their own line. */
+function runCountLines(t) {
+    if (t.runs === 0)
+        return ["no runs yet; start one with humanish run first-run"];
+    if (onlyFreeDryRuns(t))
+        return [`${plural(t.dryRun, "dry run")} ($0); no live runs yet`];
+    const running = t.running > 0 ? ` (${t.running} still running)` : "";
+    return [`live runs: ${t.live}${running}`, ...(t.dryRun > 0 ? [`dry runs: ${t.dryRun}`] : [])];
+}
+/** Spend, analysis, participants and verdicts across the selected live runs. */
+function totalsLines(t) {
+    const c = t.costs;
+    const incomplete = c.incompleteRunEstimates > 0
+        ? `; ${plural(c.incompleteRunEstimates, "run")} with incomplete accounting`
+        : "";
+    const unpriced = c.analysisUnpricedAttempts > 0 || c.analysisUnresolvedAttempts > 0
+        ? `; ${c.analysisUnpricedAttempts} unpriced, ${c.analysisUnresolvedAttempts} unresolved`
+        : "";
+    const verdicts = Object.entries(t.verdicts).map(([verdict, count]) => `${verdict} ${count}`);
+    return [
+        `known estimated spend: ${knownMoney(c.estimatedTotalUsd)}`,
+        `participants and desktops: ${knownMoney(c.runEstimatedUsd)}${incomplete}`,
+        c.analysisAttempts === 0
+            ? "analysis: none recorded"
+            : `analysis: ${knownMoney(c.analysisEstimatedUsd)} over ${plural(c.analysisAttempts, "recorded attempt")}${unpriced}`,
+        ...(c.analysisHistoryUncertainRuns > 0
+            ? [
+                `analysis history: ${plural(c.analysisHistoryUncertainRuns, "run")} missing or uncertain; --json lists each run`,
+            ]
+            : []),
+        ...(t.participants.total > 0
+            ? [
+                `participants: ${t.participants.reachedGoal} of ${t.participants.total} reached the goal, ${t.participants.reportedFriction} reported friction`,
+            ]
+            : []),
+        ...(verdicts.length > 0 ? [`verdicts: ${verdicts.join(", ")}`] : []),
+    ];
+}
+function dayLine(row) {
+    return `- ${row.day}: ${plural(row.runs, "run")}, ${row.live} live, known study spend ${knownMoney(row.costs.estimatedTotalUsd)}${unpricedTail(row.unpricedRuns, row.costs.analysisUnpricedAttempts)}`;
+}
+/** "; 2 unpriced runs, 1 unpriced analysis", or nothing when both are zero. */
+function unpricedTail(runs, analyses) {
+    if (runs === 0 && analyses === 0)
+        return "";
+    return `; ${plural(runs, "unpriced run")}, ${plural(analyses, "unpriced analysis", "unpriced analyses")}`;
+}
 export function formatStatsHuman(result) {
     if (!result.ok)
-        return `${result.error.code}: ${result.error.message}\n`;
+        return { error: result.error };
     const t = result.totals;
     const scope = [
-        result.lab === undefined ? undefined : `lab ${result.lab}`,
+        result.study === undefined ? undefined : `study ${result.study}`,
         result.since === undefined ? undefined : `since ${result.since}`,
     ].filter((part) => part !== undefined);
     const lines = [
         `humanish stats${scope.length === 0 ? "" : ` (${scope.join(", ")})`}`,
-        `runs: ${t.runs} (${t.live} live, ${t.dryRun} dry-run${t.running > 0 ? `, ${t.running} running` : ""})`,
-        `known estimated spend: ${knownMoney(t.costs.estimatedTotalUsd)}`,
-        `participants + desktops: ${knownMoney(t.costs.runEstimatedUsd)}; ${t.costs.incompleteRunEstimates} run(s) with incomplete accounting`,
-        `analysis: ${knownMoney(t.costs.analysisEstimatedUsd)} over ${t.costs.analysisAttempts} recorded attempt(s); ${t.costs.analysisUnpricedAttempts} unpriced, ${t.costs.analysisUnresolvedAttempts} unresolved`,
-        `analysis history: ${t.costs.analysisHistoryUncertainRuns} run(s) missing or uncertain; use --json for per-run accounting`,
-        `participants: ${t.participants.reachedGoal}/${t.participants.total} recorded goal completions, ${t.participants.reportedFriction} reported friction`,
-        `verdicts: ${Object.entries(t.verdicts)
-            .map(([verdict, count]) => `${verdict} ${count}`)
-            .join(", ") || "none recorded"}`,
+        ...runCountLines(t),
     ];
-    if (result.labs.length > 0) {
-        lines.push("", "per lab:");
-        for (const row of result.labs) {
-            const rate = row.passRate === undefined ? "no verdicts" : `${row.passed}/${row.judged} pass`;
-            const duration = row.medianDurationMs === undefined
-                ? "no timed live runs"
-                : `median ${minutes(row.medianDurationMs)} over ${row.durationSamples}`;
-            const cost = row.medianCostUsd === undefined
-                ? "no priced participant/desktop runs"
-                : `participant/desktop median ${money(row.medianCostUsd)} over ${row.costSamples}`;
-            lines.push(`- ${row.lab}: ${row.runs} run(s), ${row.live} live; ${rate}; ${duration}; known study spend ${knownMoney(row.costs.estimatedTotalUsd)}; ${cost}; ${row.unpricedRuns} unpriced runs, ${row.costs.analysisUnpricedAttempts} unpriced analyses`);
-        }
-    }
-    if (result.days.length > 0) {
-        lines.push("", "by day:");
-        for (const row of result.days) {
-            lines.push(`- ${row.day}: ${row.runs} run(s), ${row.live} live, known study spend ${knownMoney(row.costs.estimatedTotalUsd)}, ${row.unpricedRuns} unpriced runs, ${row.costs.analysisUnpricedAttempts} unpriced analyses`);
-        }
+    // Free dry runs alone have no spend, outcome or duration to report. Anything else, an unreadable
+    // directory or a dry run that records a cost included, gets the full report.
+    const reportable = t.runs > 0 && !onlyFreeDryRuns(t);
+    if (reportable) {
+        lines.push(...totalsLines(t));
+        if (result.studies.length > 0)
+            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"
+                    : `median ${minutes(row.medianDurationMs)} over ${row.durationSamples}`;
+                const cost = row.medianCostUsd === undefined
+                    ? "no priced participant/desktop runs"
+                    : `participant/desktop median ${money(row.medianCostUsd)} over ${row.costSamples}`;
+                return `- ${row.study}: ${plural(row.runs, "run")}, ${row.live} live; ${rate}; ${duration}; known study spend ${knownMoney(row.costs.estimatedTotalUsd)}; ${cost}${unpricedTail(row.unpricedRuns, row.costs.analysisUnpricedAttempts)}`;
+            }));
+        if (result.days.length > 0)
+            lines.push("", "by day:", ...result.days.map(dayLine));
     }
     if (result.unreadable.length > 0)
         lines.push("", `unreadable run directories: ${result.unreadable.join(", ")}`);
-    lines.push("", result.note);
+    if (reportable)
+        lines.push("", result.note);
     return `${lines.join("\n")}\n`;
 }