humanish 0.107.0 → 0.108.0

package/dist/run/run-index.js

@@ -1,21 +1,22 @@
-// The run index (#455 PR 2): list and classify every run in a project without parsing bundles.
+// The run index: list and classify every run in a project without parsing bundles.
 //
-// The existing `listRuns` walks each run tree — screenshots included — validating symlinks and
+// The existing `listRuns` walks each run tree, screenshots included, validating symlinks and
 // then parses each `run.json`: measured 197ms cold / 152ms warm at 25 runs. That is fine for a
 // command that prints once and exits, and much too hot for a surface that refreshes on a cadence
 // over SSH. This module reads the small `status.json` record each run now writes (586 bytes beside
 // a 92KB bundle) and caches per-run entries keyed on the stat of the file each was derived from.
 //
-// Honesty rules, unchanged from the record itself:
+// Rules, unchanged from the record itself:
 //   - `run.json` is the evidence-of-record. Every field here is a projection for listing and
 //     classification; nothing here is a claim about what a participant did.
 //   - A run with no status record is not assumed finished. It is classified from what is on disk:
-//     a bundle means finished, receipts without a bundle mean interrupted. That is the honest
-//     reading of a run whose process died — and, before this contract existed, of every run.
+//     a bundle means finished, receipts without a bundle mean interrupted. That is the
+//     reading of a run whose process died (and, before this contract existed, of every run).
 //   - One unreadable run directory degrades that run, never the listing.
 import { readdir, readFile, stat } from "node:fs/promises";
 import path from "node:path";
-import { RUN_STATUS_FILE, classifyRunStatus, inferLegacyLabId, isRunStatusRecord, } from "./status.js";
+import { RUN_STATUS_FILE, classifyRunStatus, isRunStatusRecord, } from "./status.js";
+import { studyProvenanceOf } from "./study-provenance.js";
 import { RUN_BUNDLE_FILE } from "./bundle.js";
 const RUN_INDEX_SCHEMA = "humanish.run-index.v1";
 /**
@@ -78,7 +79,7 @@ function entryFromStatus(record, nowMs) {
         liveness: classifyRunStatus(record, nowMs),
         mode: record.mode,
         ...(typeof record.pid === "number" ? { pid: record.pid } : {}),
-        ...(record.lab === undefined ? {} : { lab: record.lab }),
+        ...studyEntry(studyProvenanceOf(record)),
         startedAt: record.startedAt,
         updatedAt: record.updatedAt,
         ...(record.completedAt === undefined ? {} : { completedAt: record.completedAt }),
@@ -98,9 +99,9 @@ function usableStatusRecord(raw, runId) {
 }
 /**
  * The bundle-only reading, for a run with no usable status record. A bundle on disk usually means
- * the run reached its final write. But a live run now flushes an IN-PROGRESS bundle as it goes (so
+ * the run reached its final write. But a live run now flushes an in-progress bundle as it goes (so
  * anything asking what a participant is doing has something to read), and that bundle marks its
- * simulations `running`. With no status record there is no freshness to judge, and the honest
+ * simulations `running`. With no status record there is no freshness to judge, and the
  * reading of "it started, and nothing here says it finished" is interrupted, not finished.
  */
 function bundleLiveness(bundle) {
@@ -117,18 +118,16 @@ export function runLiveness(runId, status, bundle, nowMs) {
         ? { liveness: classifyRunStatus(status, nowMs), record: status }
         : { liveness: bundleLiveness(bundle) };
 }
+function studyEntry(study) {
+    return study === undefined ? {} : { study };
+}
 function entryFromBundle(runId, bundle) {
-    const legacyLabId = bundle.lab === undefined ? inferLegacyLabId(bundle) : undefined;
     return {
         runId,
         derivedFrom: "bundle",
         liveness: bundleLiveness(bundle),
         ...(bundle.mode === "dry-run" || bundle.mode === "live" ? { mode: bundle.mode } : {}),
-        ...(bundle.lab !== undefined
-            ? { lab: bundle.lab }
-            : legacyLabId === undefined
-                ? {}
-                : { lab: { id: legacyLabId } }),
+        ...studyEntry(studyProvenanceOf(bundle)),
         ...(bundle.createdAt === undefined ? {} : { startedAt: bundle.createdAt }),
         ...(bundle.review?.verdict === undefined ? {} : { verdict: bundle.review.verdict }),
         ...(bundle.review?.participants === undefined
@@ -210,7 +209,7 @@ export async function readRunIndex(cwdInput, options = {}) {
             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.
+        // run (the shape a dropped connection leaves), and saying so is more useful than hiding it.
         runs.push({ runId, derivedFrom: "directory", liveness: "interrupted" });
     }
     cache?.retain(runIds);

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

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

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

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

package/dist/run/run.d.ts

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

package/dist/run/run.js

@@ -9,7 +9,7 @@ import {} from "./results.js";
 import { createRunArtifactPaths, validatePreparedRunArtifactPaths, } from "./paths.js";
 import { registerActiveRun } from "./active-runs.js";
 import { writeContainedOutputFile, writePreparedRunLatestPointer } from "./contained-output.js";
-import { beginRunStatus, runStatusOutcome, } from "./status.js";
+import { beginRunStatus, runStatusOutcome } from "./status.js";
 /** An entry point called in a state that does not admit it. */
 class RunLifecycleError extends Error {
     name = "RunLifecycleError";

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

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

package/dist/run/sandbox-receipts.js

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

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
+     * 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
-     * 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.
+     * 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

@@ -8,14 +8,14 @@ export const COMMAND_DIGEST_PATTERN = /^[0-9a-f]{16}$/;
 // 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;
+    /** 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: StatsLabRow[];
     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;
 }
@@ -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 {};