humanish 0.106.1 → 0.108.0

package/dist/run/run.js

@@ -7,8 +7,9 @@ import { renderObserver } from "../observer/render.js";
 import { RUN_BUNDLE_FILE, PUBLIC_TARGET_CWD } from "./bundle.js";
 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";
@@ -66,6 +67,7 @@ export async function runScope(fn) {
     let closed = false;
     let started = false;
     let status;
+    let unregister;
     let finished;
     const admitted = new Set();
     const admit = (operation) => {
@@ -86,11 +88,11 @@ export async function runScope(fn) {
             const created = await createRunArtifactPaths(options.cwd, runId);
             if (!created.ok)
                 return created;
-            status = beginRunStatus(created.paths, {
-                runId,
-                mode: options.mode,
-                ...(options.lab === undefined ? {} : { lab: options.lab }),
-            });
+            // beginRunStatus reads only the mode and the lab provenance from the run's options.
+            status = beginRunStatus(created.paths, { ...options, runId });
+            // Registered before the first write lands: a signal while it is still settling reaches
+            // the handle, whose interrupt queues behind that write.
+            unregister = registerActiveRun({ cwd: options.cwd, runId, paths: created.paths, status });
             await status.started;
             return { ok: true, run: openRun(options, runId, created.paths, status) };
         })());
@@ -154,6 +156,7 @@ export async function runScope(fn) {
             runId,
             createdAt,
             mode: options.mode,
+            ...(options.lab === undefined ? {} : { lab: options.lab }),
             paths,
             writeSnapshot(bundle) {
                 if (closed)
@@ -193,6 +196,7 @@ export async function runScope(fn) {
         finally {
             if (finished === undefined)
                 await status?.finish();
+            unregister?.();
         }
     }
     return { result: outcome.result, finished };

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

@@ -4,12 +4,12 @@ export declare const SANDBOX_RECEIPTS_ARTIFACT = "sandbox-receipts.ndjson";
 export type SandboxProviderId = "e2b";
 export interface SandboxReceipt {
     at: string;
-    /** The lane/role/subject label the sandbox belongs to (public-safe token). */
+    /** The participant or subject label the sandbox belongs to (public-safe token). */
     laneId: string;
     /** 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;
 }
 /**
@@ -21,10 +21,10 @@ export interface ParsedSandboxReceipt extends Omit<SandboxReceipt, "provider"> {
     provider: string;
 }
 /**
- * Append one receipt. Best-effort BY DESIGN: the receipt exists to protect the run, so a failed
- * receipt write must never fail the lane — the only cost of a miss is that `reclaim` cannot see
+ * 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
  * 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 lanes' receipts intact.
+ * artifact write uses; append (not atomic-replace) keeps racing participants' receipts intact.
  */
 export declare function appendSandboxReceipt(root: PreparedOutputRoot, receipt: SandboxReceipt): Promise<void>;
 /** Parse a receipts file leniently: a torn final line (crash mid-append) drops, valid lines keep. */

package/dist/run/sandbox-receipts.js

@@ -1,14 +1,14 @@
 // Every created sandbox id is journaled to the run dir the moment create returns, before any work
-// happens in it. The lane loop lives in the caller's local process, so a sleeping laptop, crash or
+// happens in it. The participant loop lives in the caller's local process, so a sleeping laptop, crash or
 // kill loses every in-memory id; this append-only file keeps them for `humanish reclaim`.
 import { appendFile } from "node:fs/promises";
 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 lane — the only cost of a miss is that `reclaim` cannot see
+ * 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
  * 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 lanes' receipts intact.
+ * artifact write uses; append (not atomic-replace) keeps racing participants' receipts intact.
  */
 export async function appendSandboxReceipt(root, receipt) {
     try {
@@ -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,58 +1,58 @@
 import type { ParticipantIds } from "./participant-records.js";
 export declare const SHARED_WORLD_SCHEMA = "humanish.shared-world.v1";
-/** The ONE shared service-plane provenance for a shared-world run (#164): single commit + a
- *  seed-recipe digest + the provisioned env NAMES (values never). */
+/** 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). */
     commit?: string;
-    /** sha256-16 over the ordered seed-step command digests — the seeded-state RECIPE identity
+    /** sha256-16 over the ordered seed-step command digests: the seeded-state recipe identity
      *  (not the runtime state). Pins "same seed recipe" across bundles. */
     seedDigest: string;
-    /** Declared env NAMES provisioned for the shared plane (values never surface). */
+    /** 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 — invariant 2). A DIGEST, not 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 — 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;
     /**
-     * CONCURRENT route only: the author's REQUIRED attestation that the subject behind the
-     * internet-reachable getHost URL is synthetic seeded data (FIX-3). This is author-trust + a
-     * provenance gate, NOT a no-real-data guarantee. Verify fails closed if absent on the concurrent route.
+     * Concurrent route only: the author's required attestation that the subject behind the
+     * internet-reachable getHost URL is synthetic seeded data. This is author-trust + a
+     * provenance gate; it does not guarantee the data is synthetic. Verify fails closed if absent on the concurrent route.
      *
-     * FORBIDDEN on the external-public plane class: claiming synthetic on a real public site the
-     * harness neither provisioned nor exposed would be a lie (verify asserts it ABSENT there).
+     * Forbidden on the external-public plane class: claiming synthetic on a real public site the
+     * harness neither provisioned nor exposed would be false (verify asserts it is absent there).
      */
     exposure?: "synthetic";
     /**
-     * EXTERNAL-PUBLIC plane class only (#164 phase 2): sha256-16 of the OBSERVED origin the seats
-     * CONVERGED on (the honest analog of hostDigest, but WEAKER and disclosed — the harness only
-     * OBSERVES that each seat reached this origin; it never MINTED it). It is derived from what the
-     * seats actually reached, NOT from the declared appUrl: verify proves every laneWindow.routeHostDigest
-     * (that seat's CDP-observed final URL origin) equals it — 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.
+     * 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 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),
-     * 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
-     * + the declared appUrl, NOT on digest equality. A digest, not the raw origin. Absent on getHost.
+     * 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
+     * + the declared appUrl; digest equality plays no part. Only the digest is stored. Absent on getHost.
      */
     declaredOriginDigest?: string;
 }
 /**
- * CONCURRENT shape (#164 phase 2): 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 (causation under concurrency is structurally inexpressible — FIX-7).
+ * 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.
  */
 export interface SharedWorldParticipantWindow {
     roleId: string;
@@ -63,29 +63,29 @@ export interface SharedWorldParticipantWindow {
     simId: string;
     /** Resolves to a real RunStream (the actor's trace) in this bundle. */
     streamId: string;
-    /** ms on the ONE harness clock — the wrapped [start,end] the orchestrator MEASURED (FIX-1). */
+    /** ms on the one harness clock: the wrapped [start,end] the orchestrator measured. */
     startedAt: number;
     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 — i.e. the actor drove EXACTLY the harness-minted host (invariant 2; FIX-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;
     /** The shared plane's seed-recipe digest this actor observed. */
     seedDigest: string;
 }
-/** CONCURRENT shape: one cadence checkpoint of the shared world under load. DIGEST-ONLY — the
- *  allowed-keys tripwire (SHARED_WORLD_STATESERIES_KEYS) permits ONLY {timestamp, digest}. */
+/** Concurrent shape: one cadence checkpoint of the shared world under load. Digest-only: the
+ *  allowed-keys tripwire (SHARED_WORLD_STATESERIES_KEYS) permits only {timestamp, digest}. */
 export interface SharedWorldStateSnapshot {
-    /** ms on the ONE harness clock. */
+    /** ms on the one harness clock. */
     timestamp: number;
     /** sha256-16 of the (scrubbed, redacted) combined probe output at this snapshot. */
     digest: string;
 }
-/** CONCURRENT shape: one persona's OUTCOME against the contended world (the "M of N" headline). */
+/** Concurrent shape: one persona's outcome against the contended world (the "M of N" headline). */
 export interface SharedWorldOutcome {
     roleId: string;
     actorType?: 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
-     *  state changed across the intervening turn (delta attributed to the TURN, not an action). */
+    /** 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<{
@@ -150,45 +150,46 @@ interface SharedWorldSkippedTail {
     estimatedTotalUsd?: number;
 }
 /**
- * The shared-world evidence block (`humanish.shared-world.v1`). TWO variants discriminated by
- * `topologyMode` (FIX-8 — renamed off `RunBundle.mode` to avoid the dry-run|live collision):
+ * The shared-world evidence block (`humanish.shared-world.v1`). Two variants discriminated by
+ * `topologyMode`, which is named so it does not collide with `RunBundle.mode` (dry-run|live):
  *
- * - SEQUENTIAL (`topologyMode: "sequential"`): `sequence` + an alternating `timeline`
+ * - 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` +
- *   `outcomes`; limits `concurrent` etc. NO `timeline`.
+ * - 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.
- * The mandatory `attributionLimits` are verify-enforced (FAIL CLOSED on a missing required or a
+ * 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).
  */
 export interface SharedWorldEvidence {
     schema: typeof SHARED_WORLD_SCHEMA;
     topology: "shared-world";
-    /** The substrate discriminator (FIX-8). Branched on first by sharedWorldEvidenceFindings. */
+    /** 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
-     * harness MINTED the host; synthetic-seeded attestation + authoritative in-sandbox checkpoint
+     * 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; operator-attested, not harness-controlled; NO authoritative
-     * 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
+     * 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).
+     * 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 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

@@ -6,7 +6,7 @@ export declare const MANDATORY_ATTRIBUTION_LIMITS: readonly ["sequential-only",
 export declare const SHARED_WORLD_CHECKPOINT_KEYS: Set<string>;
 export declare const SHARED_WORLD_STATESERIES_KEYS: Set<string>;
 /**
- * Single-plane provenance: every item shares ONE (commit, seedDigest), and that pair matches
+ * Single-plane provenance: every item shares one (commit, seedDigest), and that pair matches
  * sharedWorld.plane. Only the first item that diverges from the plane is reported. The shape guard
  * has already typed both fields as strings (commit may be absent).
  */
@@ -18,8 +18,8 @@ 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 +
- * types but TOLERATES extra keys (additive): the strict value-shape/timeline checks are
+ * 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,24 +4,24 @@ 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
-// must hold NAMES only — a value sneaking into the list trips this check (a free secret tripwire).
+// Env var name shape (mirrors ENV_NAME_PATTERN in src/lab/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
-// a checkpoint delta is attributed to the TURN it followed, not a specific action (correlation).
+// Sequential: the three disclosures a sequential shared-world bundle must pin (verify fails closed
+// 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"]);
-// CONCURRENT stateSeries record is DIGEST-ONLY too (FIX-7): permit ONLY a numeric timestamp + the
+// 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.
 export const SHARED_WORLD_STATESERIES_KEYS = new Set(["timestamp", "digest"]);
 /**
- * Single-plane provenance: every item shares ONE (commit, seedDigest), and that pair matches
+ * Single-plane provenance: every item shares one (commit, seedDigest), and that pair matches
  * sharedWorld.plane. Only the first item that diverges from the plane is reported. The shape guard
  * has already typed both fields as strings (commit may be absent).
  */
@@ -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;
@@ -62,16 +62,16 @@ export function sharedWorldCommonFindings(bundle, sw) {
     if (isRecord(plane) && Array.isArray(plane.envNames)) {
         for (const name of plane.envNames) {
             if (typeof name !== "string" || !SUBJECT_ENV_NAME_PATTERN.test(name)) {
-                // Does NOT echo 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)");
+                // Never echoes the entry: a malformed entry may be a value.
+                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 +
- * types but TOLERATES extra keys (additive): the strict value-shape/timeline checks are
+ * 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).
  */
@@ -109,8 +109,8 @@ export function isSharedWorldEvidence(value) {
     if (!(Array.isArray(value.attributionLimits) &&
         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
+    // 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
     // 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")))
@@ -148,7 +148,7 @@ function isSharedWorldTimelineEntry(value) {
     }
     return false;
 }
-// Tolerant shape guards for the CONCURRENT series (extra keys tolerated — the digest-only /
+// Tolerant shape guards for the concurrent series (extra keys tolerated; the digest-only /
 // allowed-keys tripwires are the strict job of sharedWorldEvidenceFindings).
 function isSharedWorldLaneWindow(value) {
     return (isRecord(value) &&

package/dist/run/stats.d.ts

@@ -1,12 +1,13 @@
-import { type StudyCosts, type StudyCostRow } from "./costs.js";
-declare const STATS_SCHEMA = "humanish.stats.v1";
+import { type CostTotals, type CostRow } from "./costs.js";
+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;
@@ -24,7 +25,7 @@ interface StatsLabRow {
     /** Runs with no estimate: a subscription brain, an interrupted run, an old bundle. Never zero. */
     unpricedRuns: number;
     participants: StatsParticipants;
-    costs: StudyCosts;
+    costs: CostTotals;
 }
 interface StatsDayRow {
     day: string;
@@ -33,14 +34,15 @@ interface StatsDayRow {
     /** Participant and desktop subtotal; `costs` also includes retained analysis. */
     estimatedSpendUsd: number;
     unpricedRuns: number;
-    costs: StudyCosts;
+    costs: CostTotals;
 }
 export interface StatsResult {
     schema: typeof STATS_SCHEMA;
     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;
@@ -51,13 +53,13 @@ export interface StatsResult {
         unpricedRuns: number;
         participants: StatsParticipants;
         verdicts: Record<string, number>;
-        costs: StudyCosts;
+        costs: CostTotals;
     };
-    labs: StatsLabRow[];
+    studies: StatsLabRow[];
     days: StatsDayRow[];
     /** Same selected runs; individual accounting gaps are inspectable without reading private evidence. */
-    costsByRun: StudyCostRow[];
-    /** Directories that could not be read, by name — surfaced, never silently dropped. */
+    costsByRun: CostRow[];
+    /** 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 {};