humanish 0.106.1 → 0.107.0

package/dist/run/projection.d.ts

@@ -40,11 +40,11 @@ export interface LabExpectation {
     costUnknown: number;
 }
 /**
- * Derive what to expect from a lab's own history. Only FINISHED runs count: an interrupted run's
+ * Derive what to expect from a lab's own history. Only finished runs count: an interrupted run's
  * duration is the length of an accident, not of a study, and including it would quietly bias the
  * estimate the operator uses to decide whether to press Start.
  *
- * MODE MATTERS, and mixing modes is a lie rather than an imprecision. A dry run spends nothing and
+ * The mode matters: mixing modes produces a false figure. A dry run spends nothing and
  * takes no time, so a median over nine dry runs and one live one reports that a live run is free —
  * next to a control that spends money. Pass the mode the figure is about; omit it only for a
  * summary that is not attached to an action.
@@ -59,7 +59,7 @@ export declare function expectationLine(expectation: LabExpectation): string;
 /**
  * The one line a lab may say about itself, wherever it is shown.
  *
- * Prefers LIVE figures: cost and duration are what someone reads before spending, and a median
+ * Prefers live figures: cost and duration are what someone reads before spending, and a median
  * diluted by dry runs reports a live study as cheaper and faster than it has ever been. With no
  * live history it reports the count and claims nothing about time or money — which is why this is
  * shared rather than reimplemented per surface, since the two disagreeing is the whole failure.
@@ -104,15 +104,15 @@ export declare function livenessLabel(entry: Pick<RunIndexEntry, "liveness" | "v
 /** A lab as the labs list shows it: what is declared, joined to what actually happened. */
 export interface LabRow {
     /**
-     * Stable identity for THIS ROW. A manifest's path when it has one, else the lab id — because two
+     * Stable identity for this row. A manifest's path when it has one, else the lab id, because two
      * manifests can declare the same id, and keying rows by id makes them collapse into a pair of
      * indistinguishable duplicates.
      */
     key: string;
-    /** The declared id. Run history attributes to this, so it is NOT unique across manifests. */
+    /** The declared id. Run history attributes to this, so it is not unique across manifests. */
     labId: string;
     /**
-     * The handle an operator would actually type. Lab resolution is by FILENAME, so the manifest
+     * The handle an operator would actually type. Lab resolution is by filename, so the manifest
      * `\`.humanish/labs/persona-contrast-live.yaml\`` is reached as `persona-contrast-live` even when
      * the id inside it says something else.
      */
@@ -120,25 +120,25 @@ export interface LabRow {
     /** The manifest's own title, when it has one. */
     title?: string;
     /**
-     * The shortest label that is UNIQUE among the rows it is listed with: the title when no other
+     * The shortest label that is unique among the rows it is listed with: the title when no other
      * lab shares it, else the filename, else the full path. A list is only navigable if every row can
      * be told from every other one, and a title is not guaranteed to be distinct — two manifests in
-     * this repo carry the same title AND the same declared id, differing only by filename.
+     * this repo carry the same title and the same declared id, differing only by filename.
      */
     label: string;
-    /** The manifest's own words, for the list to say what this study IS. */
+    /** The manifest's own words, for the list to say what this study is. */
     description?: string;
     /** Repo-relative manifest path, absent for a lab known only from run history. */
     path?: string;
     origin?: "committed" | "ignored" | "explicit";
     /**
-     * False for a lab that has runs but NO manifest here — renamed, deleted, or run from a path that
+     * False for a lab that has runs but no manifest here: renamed, deleted, or run from a path that
      * is gone. Its runs are still evidence and must stay reachable, so it is listed and marked rather
      * than dropped.
      */
     declared: boolean;
     /**
-     * How many OTHER manifests declare this same lab id. Above zero, the run history below is shared
+     * How many other manifests declare this same lab id. Above zero, the run history below is shared
      * between them and cannot be attributed to one file — worth saying, because it is a
      * misconfiguration the operator almost certainly does not know about.
      */
@@ -169,13 +169,13 @@ export interface DeclaredLab {
  * deleted — that evidence still exists on disk, so dropping those rows would make real runs
  * unreachable from the surface that is supposed to list them.
  *
- * ONE ROW PER MANIFEST, not per id. The two are not the same thing: a manifest is addressed by its
+ * One row per manifest, not per id. The two are not the same thing: a manifest is addressed by its
  * filename while its runs attribute to the id declared inside it, so several files can legitimately
  * share an id. Collapsing them hides a real file; keying by id duplicates a row with no way to tell
  * the copies apart. Both happen in practice — this repo has exactly that pair.
  *
  * Order puts a lab someone is working in first, then labs by how recently they ran, then declared
- * labs that have never run (alphabetically BY WHAT IS DISPLAYED, so the order on screen is the
+ * labs that have never run (alphabetically by the displayed label, so the order on screen is the
  * order a reader can predict), then labs known only from history.
  */
 export declare function labRows(declared: readonly DeclaredLab[], entries: readonly RunIndexEntry[]): {

package/dist/run/projection.js

@@ -3,7 +3,7 @@
 // the parts most likely to be wrong are testable without a terminal.
 //
 // The honesty rules these encode, because they are the ones a UI is most tempted to break:
-//   - a statistic ALWAYS carries its denominator, and says when it has none;
+//   - a statistic always carries its denominator, and says when it has none;
 //   - an unknown cost is `null` (declared absent), never 0;
 //   - truncation is reported, never silent;
 //   - a participant's reported thinking is quoted, never paraphrased or summarized.
@@ -58,11 +58,11 @@ function recencyOf(entry) {
     return 0;
 }
 /**
- * Derive what to expect from a lab's own history. Only FINISHED runs count: an interrupted run's
+ * Derive what to expect from a lab's own history. Only finished runs count: an interrupted run's
  * duration is the length of an accident, not of a study, and including it would quietly bias the
  * estimate the operator uses to decide whether to press Start.
  *
- * MODE MATTERS, and mixing modes is a lie rather than an imprecision. A dry run spends nothing and
+ * The mode matters: mixing modes produces a false figure. A dry run spends nothing and
  * takes no time, so a median over nine dry runs and one live one reports that a live run is free —
  * next to a control that spends money. Pass the mode the figure is about; omit it only for a
  * summary that is not attached to an action.
@@ -78,7 +78,7 @@ export function expectationFor(entries, mode) {
         .map((entry) => entry.estimatedCostUsd)
         .filter((value) => typeof value === "number" && Number.isFinite(value))
         .sort((a, b) => a - b);
-    // A cost is unknown whether it was DECLARED absent (`null`) or never recorded at all
+    // A cost is unknown whether it was declared absent (`null`) or never recorded at all
     // (`undefined` — every fail-closed exit finalized with no outcome). Counting only the first
     // reports "~$1.20 median · 3 runs" for a sample where two runs were never priced, which claims a
     // denominator the figure does not have.
@@ -134,7 +134,7 @@ export function expectationLine(expectation) {
 /**
  * The one line a lab may say about itself, wherever it is shown.
  *
- * Prefers LIVE figures: cost and duration are what someone reads before spending, and a median
+ * Prefers live figures: cost and duration are what someone reads before spending, and a median
  * diluted by dry runs reports a live study as cheaper and faster than it has ever been. With no
  * live history it reports the count and claims nothing about time or money — which is why this is
  * shared rather than reimplemented per surface, since the two disagreeing is the whole failure.
@@ -253,13 +253,13 @@ function labNameFromPath(manifestPath) {
  * deleted — that evidence still exists on disk, so dropping those rows would make real runs
  * unreachable from the surface that is supposed to list them.
  *
- * ONE ROW PER MANIFEST, not per id. The two are not the same thing: a manifest is addressed by its
+ * One row per manifest, not per id. The two are not the same thing: a manifest is addressed by its
  * filename while its runs attribute to the id declared inside it, so several files can legitimately
  * share an id. Collapsing them hides a real file; keying by id duplicates a row with no way to tell
  * the copies apart. Both happen in practice — this repo has exactly that pair.
  *
  * Order puts a lab someone is working in first, then labs by how recently they ran, then declared
- * labs that have never run (alphabetically BY WHAT IS DISPLAYED, so the order on screen is the
+ * labs that have never run (alphabetically by the displayed label, so the order on screen is the
  * order a reader can predict), then labs known only from history.
  */
 export function labRows(declared, entries) {
@@ -310,7 +310,7 @@ export function labRows(declared, entries) {
             .filter((lab) => !declaredIds.has(lab.labId))
             .map((lab) => build(lab.labId, undefined, false)),
     ];
-    // Resolve each row's label BEFORE sorting, so the list is ordered by what a reader actually sees.
+    // Resolve each row's label before sorting, so the list is ordered by what a reader actually sees.
     assignLabels(rows);
     const label = (row) => row.label;
     rows.sort((left, right) => {

package/dist/run/reclaim.d.ts

@@ -1,4 +1,5 @@
 import { type E2BDesktopModule } from "../substrates/e2b/sdk.js";
+import { type PreparedRunArtifactPaths } from "./paths.js";
 declare const RECLAIM_RESULT_SCHEMA = "humanish.reclaim-result.v1";
 export declare const RECLAIM_RECEIPT_ARTIFACT = "reclaim-receipt.json";
 interface ReclaimOutcome {
@@ -31,6 +32,11 @@ export interface ReclaimHooks {
     requestTimeoutMs?: number;
 }
 export declare function reclaimRunSandboxes(cwd: string, runInput: string, hooks?: ReclaimHooks): Promise<ReclaimResult>;
+/**
+ * Reclaim the run whose directory the caller already holds. Nothing is resolved, so an id that is
+ * also an alias (a run named `latest`) cannot reach another run's receipts.
+ */
+export declare function reclaimPinnedRunSandboxes(cwd: string, runPaths: PreparedRunArtifactPaths, hooks?: ReclaimHooks): Promise<ReclaimResult>;
 /**
  * Kill the sandboxes left by interrupted `humanish lab preflight` probes. A probe journals under
  * .humanish/preflight/<probe-id>/ and removes the journal after a confirmed kill, so what is left

package/dist/run/reclaim.js

@@ -1,4 +1,4 @@
-// `humanish reclaim`: kill an interrupted run's sandboxes by the EXACT ids the run journaled at
+// `humanish reclaim`: kill an interrupted run's sandboxes by the exact ids the run journaled at
 // create time (sandbox-receipts.ndjson), and report what happened to each. It reads one file inside
 // the managed run dir, kills by id, and never lists the account: an account-wide operation once
 // destroyed unrelated infrastructure. Without it, orphaned sandboxes run until the server-side
@@ -13,7 +13,17 @@ import { redactText, toErrorMessage } from "../evidence/redaction.js";
 import { runIdOf } from "./paths.js";
 const RECLAIM_RESULT_SCHEMA = "humanish.reclaim-result.v1";
 export const RECLAIM_RECEIPT_ARTIFACT = "reclaim-receipt.json";
-export async function reclaimRunSandboxes(cwd, runInput, hooks = {}) {
+export function reclaimRunSandboxes(cwd, runInput, hooks = {}) {
+    return reclaimRun(cwd, runInput, () => resolveRunPath(cwd, runInput), hooks);
+}
+/**
+ * Reclaim the run whose directory the caller already holds. Nothing is resolved, so an id that is
+ * also an alias (a run named `latest`) cannot reach another run's receipts.
+ */
+export function reclaimPinnedRunSandboxes(cwd, runPaths, hooks = {}) {
+    return reclaimRun(cwd, runIdOf(runPaths), () => Promise.resolve(runPaths), hooks);
+}
+async function reclaimRun(cwd, runInput, locate, hooks) {
     const warnings = [];
     const base = {
         schema: RECLAIM_RESULT_SCHEMA,
@@ -25,7 +35,7 @@ export async function reclaimRunSandboxes(cwd, runInput, hooks = {}) {
     };
     if (e2bDebugMode())
         return { ...base, ok: false, error: E2B_DEBUG_REFUSAL };
-    const runPaths = await resolveRunPath(cwd, runInput);
+    const runPaths = await locate();
     if (!runPaths) {
         return {
             ...base,

package/dist/run/results.d.ts

@@ -30,7 +30,7 @@ export interface RunResult {
     observer?: ObserverResult;
     warnings: string[];
     error?: {
-        code: "HUMANISH_LAB_ANALYSIS_INVALID" | "HUMANISH_LAB_ANALYSIS_UNSUPPORTED" | "HUMANISH_LAB_TASKS_UNSUPPORTED" | "HUMANISH_LAB_OPTION_CONFLICT" | "HUMANISH_LAB_OPTION_UNSUPPORTED" | "HUMANISH_LAB_COMMS_UNSUPPORTED" | "HUMANISH_LIVE_RUN_UNIMPLEMENTED" | "HUMANISH_INVALID_CWD" | "HUMANISH_RUN_ID_IN_USE" | "HUMANISH_INVALID_SIM_COUNT" | "HUMANISH_INVALID_PORT" | "HUMANISH_UNSUPPORTED_RERUN_FLAGS" | "HUMANISH_WATCH_OPTION_CONFLICT" | "HUMANISH_WATCH_SAFE_NOT_APPLICABLE" | "HUMANISH_APP_URL_REMOVED" | "HUMANISH_LAB_SCORER_BAD_REF" | "HUMANISH_LAB_SCORER_NOT_FOUND" | "HUMANISH_LAB_SCORER_LOAD_FAILED" | "HUMANISH_LAB_SCORER_NO_HOOKS" | "HUMANISH_LAB_SCORER_UNSUPPORTED_BACKEND";
+        code: "HUMANISH_LAB_ANALYSIS_INVALID" | "HUMANISH_LAB_ANALYSIS_UNSUPPORTED" | "HUMANISH_LAB_TASKS_UNSUPPORTED" | "HUMANISH_LAB_OPTION_UNSUPPORTED" | "HUMANISH_LAB_COMMS_UNSUPPORTED" | "HUMANISH_LIVE_RUN_UNIMPLEMENTED" | "HUMANISH_INVALID_CWD" | "HUMANISH_RUN_ID_IN_USE" | "HUMANISH_INVALID_SIM_COUNT" | "HUMANISH_INVALID_PORT" | "HUMANISH_UNSUPPORTED_RERUN_FLAGS" | "HUMANISH_WATCH_OPTION_CONFLICT" | "HUMANISH_WATCH_SAFE_NOT_APPLICABLE" | "HUMANISH_APP_URL_REMOVED" | "HUMANISH_LAB_SCORER_BAD_REF" | "HUMANISH_LAB_SCORER_NOT_FOUND" | "HUMANISH_LAB_SCORER_LOAD_FAILED" | "HUMANISH_LAB_SCORER_NO_HOOKS" | "HUMANISH_LAB_SCORER_UNSUPPORTED_BACKEND";
         message: string;
     };
 }

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

@@ -7,7 +7,7 @@ export interface RunIndexEntry {
     liveness: RunLiveness;
     mode?: "dry-run" | "live";
     /**
-     * The pid that owns a run, when it recorded one. This is how a surface identifies the run IT just
+     * The pid that owns a run, when it recorded one. This is how a surface identifies the run it just
      * started without minting an id or guessing at a new directory: it spawned a process, and exactly
      * one run's record carries that pid.
      */

package/dist/run/run-index.js

@@ -1,4 +1,4 @@
-// The run index (#455 PR 2): list and classify every run in a project WITHOUT parsing bundles.
+// The run index (#455 PR 2): list and classify every run in a project without parsing bundles.
 //
 // 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
@@ -6,10 +6,10 @@
 // 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:
+// Honesty 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 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.
 //   - One unreadable run directory degrades that run, never the listing.
@@ -97,7 +97,7 @@ function usableStatusRecord(raw, runId) {
     return isRunStatusRecord(raw) && raw.runId === runId;
 }
 /**
- * The bundle-only reading, for a run with no usable status record. A bundle on disk USUALLY means
+ * 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
  * 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
@@ -169,15 +169,15 @@ export async function readRunIndex(cwdInput, options = {}) {
         if (statusKey !== null) {
             const cached = cache?.get(runId, statusKey);
             if (cached !== undefined) {
-                // Liveness is time-dependent, so it is recomputed even on a cache hit — a record that has
-                // not changed can still have gone stale since the last read.
-                runs.push(cached.derivedFrom === "status" && cached.updatedAt !== undefined
+                // A running record's liveness is time-dependent, so it is recomputed even on a cache hit:
+                // an unchanged record can still have gone stale. An ended record (finished or
+                // interrupted, both with completedAt) keeps the liveness it was cached with.
+                runs.push(cached.derivedFrom === "status" &&
+                    cached.updatedAt !== undefined &&
+                    cached.completedAt === undefined
                     ? {
                         ...cached,
-                        liveness: classifyRunStatus({
-                            state: cached.completedAt === undefined ? "running" : "finished",
-                            updatedAt: cached.updatedAt,
-                        }, nowMs),
+                        liveness: classifyRunStatus({ state: "running", updatedAt: cached.updatedAt }, nowMs),
                     }
                     : cached);
                 continue;

package/dist/run/run.d.ts

@@ -13,7 +13,7 @@ interface StartRunOptions {
     lab?: RunLabProvenance | undefined;
     /** review.md for the published bundle. */
     renderReview: (bundle: RunBundle) => string;
-    /** Used by `FinishedRun.renderObserver`; `render` is the routes' `renderObserverFn` seam. */
+    /** Used by `FinishedRun.renderObserver`; `render` is the `LabDeps.renderObserver` seam. */
     observer?: {
         open: boolean;
         render?: typeof renderObserver | undefined;
@@ -25,7 +25,9 @@ interface Run {
     readonly runId: string;
     readonly createdAt: string;
     readonly mode: "dry-run" | "live";
-    /** Routes write their evidence files through these and hand them to lanes. */
+    /** The manifest the run came from (#455); bundleHead copies it into the bundle. */
+    readonly lab?: RunLabProvenance;
+    /** Routes write their evidence files through these and hand them to participants. */
     readonly paths: PreparedRunArtifactPaths;
     /**
      * Publish an in-progress bundle: run.json, review.json, review.md, events.ndjson and

package/dist/run/run.js

@@ -7,6 +7,7 @@ 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";
 /** An entry point called in a state that does not admit it. */
@@ -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,7 +4,7 @@ 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;
@@ -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 {

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 (#164): 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 (#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
      * 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 — invariant 1) before digesting. verify proves every
+     * 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.
      */
     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
+     * External-public plane class only (#164 phase 2): sha256-16 of the observed origin the seats
+     * 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.
      */
     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.
+     * 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 (#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, because under concurrency the evidence cannot say which actor caused a state change.
  */
 export interface SharedWorldParticipantWindow {
     roleId: string;
@@ -63,13 +63,13 @@ 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).
+    /** 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). */
     routeHostDigest: string;
     /** The shared plane's commit this actor observed (omitted when unresolved). */
@@ -77,15 +77,15 @@ export interface SharedWorldParticipantWindow {
     /** 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;
@@ -117,7 +117,7 @@ export interface SharedWorldCheckpoint {
     /** 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). */
+     *  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
@@ -150,45 +150,45 @@ 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"`, #164 phase 2): `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
+ * 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
+     * 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
+     * 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
+     * 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
+     * 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 role seats. */
     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
+     * `/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.
+     * 6-char lobby code and full URLs are runtime-only and never land). Absent when seats did not converge.
      */
     lobbyConvergenceDigest?: string;
     /** The role ids that actually took a turn, in declared order. */

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 (#164). 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).
  */