humanish 0.106.1 → 0.108.0

package/dist/lab/types.d.ts

@@ -3,32 +3,34 @@ import type { LabTask } from "./tasks.js";
 import type { DwellWindow, StopWhen } from "../actors/stop-conditions.js";
 import { type ReasoningEffort } from "../actors/reasoning-effort.js";
 export declare const LAB_CONFIG_SCHEMA = "humanish.lab.v2";
+/** The study format: it declares its route, one actor, its participants and one caps block. */
+export declare const STUDY_SCHEMA = "humanish.study.v3";
 export declare const ID_PATTERN: RegExp;
 /**
  * Where the run acts: the host repo, a fresh clone, a running app a browser actor drives
- * (`app-url`), an already-running LOCAL dev server driven IN-PROCESS via a custom
- * CuaExecutor with NO clone and NO E2B desktop (`local-app`), or the operator's own local
+ * (`app-url`), an already-running local dev server driven in-process via a custom
+ * CuaExecutor with no clone and no E2B desktop (`local-app`), or the operator's own local
  * working tree packed and provisioned in-sandbox in place of a clone (`local-tree`).
- * `local-app` routes to the cua backend and is library-assisted: a caller supplies
+ * `local-app` routes to the computer-use route and is library-assisted: a caller supplies
  * `RunLabOptions.inProcess` + `createProvider` (no built-in driver exists yet), and the engine
- * fails closed (HUMANISH_CUA_LAB_LOCAL_APP_NO_EXECUTOR) when run without them: a structured
+ * fails closed (HUMANISH_COMPUTER_USE_LOCAL_APP_NO_EXECUTOR) when run without them: a structured
  * error, never a desktop attempt. See docs/architecture/state-driven-executor.md.
  */
 type LabSubjectSource = "this-repo" | "clone" | "app-url" | "local-app" | "terminal-product" | "desktop-cli" | "local-tree";
 /**
- * How a subject's WORLD relates across actor lanes. `per-lane-worlds` (the default; absent ==
- * this) is the only fan-out topology the computer-use route ships — N lanes, N independent
- * worlds, isolation + per-lane attribution. `shared-world` (#164) is the DECLARED override: ONE
- * mutable service plane that N role SEATS use at the same time, so their actions interact through
- * shared state. Consumed ONLY on the shared-world routes (a provisioned clone plane, or an
+ * How a subject's world relates across participants. `per-lane-worlds` (the default; absent ==
+ * this) is the only fan-out topology the computer-use route ships: N participants, N independent
+ * worlds, isolation + per-participant attribution. `shared-world` is the declared override: one
+ * mutable service plane that N participants use at the same time, so their actions interact through
+ * shared state. Consumed only on the shared-world routes (a provisioned clone plane, or an
  * external-public app-url plane) with a computer-use actor; inert/warned everywhere else
- * (invariant 6).
+ * (claims match mechanism).
  */
 type LabSubjectTopology = "per-lane-worlds" | "shared-world";
 export interface LabSubjectClone {
     /** git clone depth; 1 (shallow) by default. Consumed on the computer-use clone route. */
     depth?: number;
-    /** how many independent clone lanes to fan out (one sandbox/desktop each). */
+    /** how many participants to fan out, each with its own clone (one sandbox/desktop each). */
     fanout?: number;
     /** keep the disposable clone for debugging instead of discarding. */
     keep?: boolean;
@@ -51,11 +53,11 @@ export interface LabSubjectServe {
     install?: string;
     /** Optional bounded build step. */
     build?: string;
-    /** Required long-lived start command — launched detached; the sandbox lifecycle owns it. */
+    /** Required long-lived start command, launched detached; the sandbox lifecycle owns it. */
     start: string;
     /** Loopback entry URL: the readiness-probe target and the URL the actor drives. The lab
-     *  serves the clone INSIDE the sandbox, so this is always loopback (not subject to
-     *  allowPublicTargets — that governs app-url subjects, i.e. external deployments). */
+     *  serves the clone inside the sandbox, so this is always loopback (not subject to
+     *  allowPublicTargets, which governs app-url subjects, i.e. external deployments). */
     url: string;
     /** Budget for the served app to answer the readiness probe. Default 180000. */
     readyTimeoutMs?: number;
@@ -69,43 +71,43 @@ export type LabStateStepWhen = "before-build" | "before-start" | "after-ready";
 interface LabSubjectStateStep {
     /**
      * [a-z0-9-] step label (must start alphanumeric), <=40 chars, unique across steps; becomes
-     * the detached-step name `subject-state-<name>` (interpolates into in-sandbox file paths —
-     * the shape is load-bearing, validated at parse AND re-enforced in the engine).
+     * the detached-step name `subject-state-<name>` (interpolates into in-sandbox file paths, so
+     * the shape is validated at parse and re-enforced in the engine).
      */
     name: string;
     /**
-     * Author-trusted shell command (same trust class as serve.install/build/start — the
+     * Author-trusted shell command (same trust class as serve.install/build/start: the
      * "serve commands are author-trusted" corollary). Runs detached in the subject directory
      * with an atomic status file, kill-on-timeout, and a capped log tail. Persisted in
-     * evidence as a sha256-16 DIGEST only, never as text.
+     * evidence as a sha256-16 digest only, never as text.
      */
     command: string;
     /**
-     * Phase: before-build (after install — for builds that read the DB, e.g. SSG),
-     * before-start (after build, before the server launches — migrations, SQL/file fixtures,
-     * an in-sandbox `service postgresql start`), after-ready (after the readiness probe —
-     * fixtures loaded through the RUNNING app's API). Default: before-start.
+     * Phase: before-build (after install, for builds that read the DB, e.g. SSG),
+     * before-start (after build, before the server launches: migrations, SQL/file fixtures,
+     * an in-sandbox `service postgresql start`), after-ready (after the readiness probe:
+     * fixtures loaded through the running app's API). Default: before-start.
      */
     when?: LabStateStepWhen;
     /** Wall-clock budget per step. Default 300000. */
     timeoutMs?: number;
 }
 /**
- * A shared-world state CHECKPOINT: an author-trusted, READ-ONLY, AGGREGATE/DIGEST probe command
+ * A shared-world state checkpoint: an author-trusted, read-only, aggregate/digest probe command
  * (counts, max-timestamps, hashes) run at baseline and after each role's turn. Reuses the
- * seed-step validation shape (name [a-z0-9-] ≤40, unique; command required). Persisted DIGEST-ONLY
- * (only sha256-16(scrub+redact(stdout)) ever lands — never the raw value), same lockdown as the
- * seed surface. Consumed ONLY on the shared-world route (#164); inert/warned elsewhere.
+ * seed-step validation shape (name [a-z0-9-] ≤40, unique; command required). Persisted digest-only
+ * (only sha256-16(scrub+redact(stdout)) ever lands, never the raw value), same lockdown as the
+ * seed surface. Consumed only on the shared-world route; inert/warned elsewhere.
  */
 export interface LabSubjectStateCheckpoint {
     /**
      * [a-z0-9-] probe label (must start alphanumeric), <=40 chars, unique across checkpoints;
-     * names the detached step (`checkpoint-<snapshot>-<name>`) — load-bearing shape, validated at
-     * parse AND re-enforced in the engine.
+     * names the detached step (`checkpoint-<snapshot>-<name>`), a shape validated at
+     * parse and re-enforced in the engine.
      */
     name: string;
     /**
-     * Author-trusted READ-ONLY shell command (same trust class as serve/seed — the "serve commands
+     * Author-trusted read-only shell command (same trust class as serve/seed: the "serve commands
      * are author-trusted" corollary). Its stdout is scrubbed + pattern-redacted, then digested
      * (sha256-16); the raw value never persists.
      */
@@ -113,43 +115,43 @@ export interface LabSubjectStateCheckpoint {
     /**
      * Optional extra literal values to scrub from this probe's stdout before digesting (author-known
      * values that may appear in the probe output, beyond the harness-provisioned env values which are
-     * always scrubbed). Names/values are NEVER persisted — only the digest is.
+     * always scrubbed). Names and values are never persisted; only the digest is.
      */
     redact?: string[];
 }
-/** The subject's STATE story (clone subjects): seeded in-sandbox, or declared external. */
+/** The subject's state story (clone subjects): seeded in-sandbox, or declared external. */
 export interface LabSubjectState {
     /** Ordered seed/migration/fixture steps. Order within a phase is declaration order. */
     seed?: LabSubjectStateStep[];
     /**
-     * Env var NAMES whose values point at state the lab does NOT control (e.g. a shared dev
+     * Env var names whose values point at state the lab does not control (e.g. a shared dev
      * DB). Must be a subset of subject.env (so the declaration is mechanically backed by a
      * provisioned name, not a vibe). Flips state provenance to "unpinned".
      */
     external?: string[];
     /**
-     * Shared-world state checkpoints (#164): read-only digest probes run at baseline + after each
-     * role's turn to produce the harness-clocked interaction timeline. Consumed ONLY on the
-     * shared-world route; inert/warned elsewhere (invariant 6). Shape-validated everywhere.
+     * Shared-world state checkpoints: read-only digest probes run at baseline + after each
+     * role's turn to produce the harness-clocked interaction timeline. Consumed only on the
+     * shared-world route; inert/warned elsewhere. Shape-validated everywhere.
      */
     checkpoint?: LabSubjectStateCheckpoint[];
 }
 /**
- * `terminal-product`: the product-under-study a terminal agent must discover and use from PUBLIC
- * SURFACES ONLY (the terminal-product route's subject). The subject is NOT provisioned/cloned —
- * the agent drives the declared public surfaces, so provenance is UNPINNED (invariant 5). The
- * concrete product name + surfaces are operator data; committed fixtures use a NEUTRAL mock name.
+ * `terminal-product`: the product-under-study a terminal agent must discover and use from public
+ * surfaces only (the terminal-product route's subject). The subject is not provisioned or cloned:
+ * the agent drives the declared public surfaces, so provenance is declared unpinned. The
+ * concrete product name + surfaces are operator data; committed fixtures use a neutral mock name.
  */
 export interface LabSubjectProduct {
     /** Public-safe product label (shape-validated like a lab id; interpolates into evidence). */
     name: string;
     /**
-     * How the product gets onto the machine, run UNKEYED before the participant starts, in the
-     * lane's working directory. Consumed on BOTH product routes: `desktop-cli` (a person at a
+     * How the product gets onto the machine, run with no keys before the participant starts, in the
+     * participant's working directory. Consumed on both product routes: `desktop-cli` (a person at a
      * desktop) and `terminal-product` (an agent in a shell).
      *
      * Absent means the participant installs it themselves from the public surfaces, which is a
-     * different study — one about the install, not about the tool. Present means the study starts
+     * different study, one about the install. Present means the study starts
      * where you want it to start: asking a participant what studies a project contains, in an empty
      * directory, measures the lab rather than the product.
      * Both routes prepare Node/npm when install is absent; product installation remains the
@@ -157,29 +159,29 @@ export interface LabSubjectProduct {
      */
     install?: string;
     /**
-     * `desktop-cli` ONLY: the directory the participant's terminal opens in. Absent means the home
-     * directory. (The terminal-product lane has its own fixed study workdir.)
+     * `desktop-cli` only: the directory the participant's terminal opens in. Absent means the home
+     * directory. (The terminal-product route has its own fixed study workdir.)
      *
      * This exists because the first live study failed on it: the participant was asked what studies
      * the project contained, landed in an empty home directory, correctly reported that there was no
      * project, and stopped. The finding was about the lab, not the product. A study of a
-     * project-scoped tool has to put the participant IN a project, the same way an app study opens
+     * project-scoped tool has to put the participant inside a project, the same way an app study opens
      * the app rather than a blank tab.
      */
     workdir?: string;
     /**
-     * The product's PUBLIC surfaces — the only world the agent sees. Each must be an http(s) URL
+     * The product's public surfaces, the only world the agent sees. Each must be an http(s) URL
      * (e.g. a docs page, an llms.txt, a skill manifest). Validated at parse; recorded in evidence.
      */
     publicSurfaces: string[];
     /**
-     * `terminal-product` ONLY: a local file uploaded into the sandbox before `install` runs, and
+     * `terminal-product` only: a local file uploaded into the sandbox before `install` runs, and
      * exposed to it as `$HUMANISH_PRODUCT_UPLOAD`. A project-relative path; `..` and absolute paths
      * are refused, because this reads a file off the operator's disk and puts it on a machine an
      * autonomous agent is about to drive.
      *
-     * It exists so a study can test a build that is NOT PUBLISHED YET. Installing `@latest` measures
-     * the last release, which is exactly the wrong artifact for a pre-release gate — the point is to
+     * It exists so a study can test a build that is not published yet. Installing `@latest` measures
+     * the last release, which is exactly the wrong artifact for a pre-release gate. The point is to
      * meet the candidate before anyone else does. Any adopter shipping a CLI wants the same thing.
      */
     upload?: string;
@@ -187,33 +189,33 @@ export interface LabSubjectProduct {
 export interface LabSubject {
     source: LabSubjectSource;
     /**
-     * WORLD topology across actor lanes. Absent == `per-lane-worlds` (the isolation default; every
-     * existing lab is byte-stable). `shared-world` is the declared override (#164): one mutable
-     * service plane, N role seats at once. Consumed ONLY on the shared-world routes (a provisioned
-     * clone or an external-public app-url plane, a computer-use actor, and a roster of ≥2 lanes);
-     * inert/warned elsewhere.
+     * World topology across participants. Absent == `per-lane-worlds` (the isolation default; every
+     * existing study is byte-stable). `shared-world` is the declared override: one mutable service
+     * plane, N participants at once, each in its role. Consumed only on the shared-world routes (a
+     * provisioned clone or an external-public app-url plane, a computer-use actor, and a roster of ≥2
+     * participants); inert/warned elsewhere.
      */
     topology?: LabSubjectTopology;
     /**
-     * CONCURRENT shared-world route ONLY (#164 phase 2): the author's REQUIRED attestation that the
-     * subject behind the internet-reachable `getHost` URL is SYNTHETIC seeded data. The concurrent
+     * Concurrent shared-world route only: the author's required attestation that the
+     * subject behind the internet-reachable `getHost` URL is synthetic seeded data. The concurrent
      * route exposes the subject on a tokenless public URL for the run's duration, so real/external
      * data must never sit behind it. This is author-trust + a provenance gate (verify also requires
-     * `subject.state.provenance == "seeded"`), NOT a no-real-data guarantee. Required when
+     * `subject.state.provenance == "seeded"`). It does not guarantee the data is synthetic. Required when
      * `topology: shared-world` + `execution.concurrency > 1`; inert/warned elsewhere.
      */
     exposure?: "synthetic";
     /**
-     * EXTERNAL-PUBLIC shared-world route ONLY (#164 phase 2): the author's REQUIRED ownership
-     * attestation when a real PUBLIC deployment (`source: app-url` + `topology: shared-world` +
+     * External-public shared-world route only: the author's required ownership
+     * attestation when a real public deployment (`source: app-url` + `topology: shared-world` +
      * `concurrency > 1` + `policies.allowPublicTargets: true`) is used directly as the shared plane.
      * The harness neither provisions nor exposes this target (no getHost, no clone, no seed), so it
-     * cannot attest the data is synthetic; instead the operator MUST attest they own/operate it.
-     * `owner` is a public-safe operator/repo label; `authorized` must be true. This is author-trust —
-     * the harness cannot verify ownership — surfaced honestly in the evidence class. Required on the
-     * external-public branch. On a non-`app-url` subject it is REJECTED (parse error); on any OTHER
-     * `app-url` config that does not route to external-public shared-world it is IGNORED-WITH-A-WARNING
-     * (forwardDeclaredWarnings), never silently consumed — it is meaningless without that plane.
+     * cannot attest the data is synthetic; instead the operator must attest they own/operate it.
+     * `owner` is a public-safe operator/repo label; `authorized` must be true. This is author-trust:
+     * the harness cannot verify ownership, and the evidence class says so. Required on the
+     * external-public branch. On a non-`app-url` subject it is rejected (parse error); on any other
+     * `app-url` config that does not route to external-public shared-world it is ignored with a warning
+     * (forwardDeclaredWarnings), never silently consumed, because it is meaningless without that plane.
      */
     publicTarget?: {
         owner: string;
@@ -224,44 +226,44 @@ export interface LabSubject {
     clone?: LabSubjectClone;
     /**
      * `app-url`: a loopback http(s) URL the computer-use actor drives (127.0.0.1/localhost
-     * only — driving arbitrary public sites is not allowed). The URL must be reachable from
-     * INSIDE the desktop sandbox; library callers provision it via the prepareDesktop hook.
-     * For a config-only path use `clone` + `serve` — the lab serves the app itself.
+     * only; driving arbitrary public sites is not allowed). The URL must be reachable from
+     * inside the desktop sandbox; library callers provision it via the prepareDesktop hook.
+     * For a config-only path use `clone` + `serve`: the lab serves the app itself.
      *
-     * `local-app`: the loopback http(s) URL of an already-running LOCAL dev server the caller's
-     * custom CuaExecutor drives in-process (no sandbox, no public-target option — always
-     * loopback). Passed to `buildExecutor` so the bridge knows where the app lives.
+     * `local-app`: the loopback http(s) URL of an already-running local dev server the caller's
+     * custom CuaExecutor drives in-process (no sandbox, no public-target option, always
+     * loopback). Passed to `inProcess.executor` so the bridge knows where the app lives.
      */
     appUrl?: string;
     /** `clone` (computer-use route): how the cloned app is served in-sandbox. */
     serve?: LabSubjectServe;
     /**
-     * Env var NAMES the subject app needs, provisioned into the sandbox from the caller's
+     * Env var names the subject app needs, provisioned into the sandbox from the caller's
      * environment (--env-file). Names are recorded in evidence; values never are. Consumed
      * on the computer-use clone route.
      */
     env?: string[];
     /**
-     * LITERAL, NON-SECRET env values committed alongside the lab — the configuration every real app
+     * Literal, non-secret env values committed alongside the lab: the configuration every real app
      * needs before it will boot: a public base URL, a transport selector, a feature flag. None of that
      * is secret, and routing it through `subject.env` would force an adopter to carry a private env
      * file just to reproduce a public study, which is the opposite of a reproducible lab.
      *
-     * These values ARE recorded in evidence, because they are part of how the subject was configured,
+     * These values are recorded in evidence, because they are part of how the subject was configured,
      * so a value that looks like a secret or a local path is refused at parse rather than committed to
      * a public repo. Anything genuinely secret belongs in `subject.env`.
      */
     envValues?: Record<string, string>;
     /**
-     * `clone` (computer-use route): the subject's state story — seed/migration/fixture steps
+     * `clone` (computer-use route): the subject's state story, as seed/migration/fixture steps
      * executed in-sandbox around the serve sequence, and/or declared external state. Recorded
-     * in the run bundle as structured provenance (invariant 5): seeded with command digests,
-     * UNPINNED for external state, declared-not-run for dry-run/failed provisioning.
+     * in the run bundle as structured provenance: seeded with command digests,
+     * unpinned for external state, declared-not-run for dry-run/failed provisioning.
      */
     state?: LabSubjectState;
     /**
      * `terminal-product` (terminal route): the product the terminal agent discovers + uses from
-     * PUBLIC surfaces only. Consumed on the terminal route; rejected on every other source.
+     * public surfaces only. Consumed on the terminal route; rejected on every other source.
      */
     product?: LabSubjectProduct;
     /**
@@ -276,98 +278,98 @@ export interface LabSubject {
 export interface LabParticipantFocus {
     id?: string;
     label?: string;
-    /** Per-lane steer appended to the actor's mission. Consumed on the app-url route. */
+    /** Per-participant steer appended to the actor's mission. Consumed on the app-url route. */
     instruction?: string;
 }
 /**
- * One differentiated fan-out lane on the computer-use E2B route (per-lane worlds). Each lane
- * becomes an independent E2B desktop sandbox with its own persona/device/starting-steer. All
+ * One participant in a differentiated fan-out on the computer-use E2B route (`per-lane-worlds`).
+ * Each entry becomes an independent E2B desktop sandbox with its own persona/device/starting-steer. All
  * fields optional: an omitted persona/device/instruction inherits the actor-level default. `id`
- * defaults to `lane-01`..`lane-NN` and must be a public-safe token (it names per-lane evidence
- * paths). Consumed ONLY on the computer-use E2B route (inert/warned elsewhere).
+ * defaults to `lane-01`..`lane-NN` and must be a public-safe token (it names per-participant evidence
+ * paths). Consumed only on the computer-use E2B route (inert/warned elsewhere).
  */
 export interface LabParticipantEntry {
-    /** Public-safe lane label (interpolates into per-lane evidence paths). Default lane-NN. */
+    /** Public-safe participant id (interpolates into its evidence paths). Default `lane-NN`. */
     id?: string;
     /**
      * App-defined actor type label for grouping simulated users ("operator", "viewer",
-     * "maintainer", etc.). This is NOT the execution actor dispatch key (`actors[0].type`);
+     * "maintainer", etc.). It is separate from the execution actor dispatch key (`actors[0].type`);
      * it is adapter-owned taxonomy for roster/readback.
      */
     actorType?: string;
-    /** App-defined surface label for grouping lanes that start from different product areas. */
+    /** App-defined surface label for grouping participants that start from different product areas. */
     surface?: string;
-    /** App-defined correlation id tying lanes to one shared case/account/work item. */
+    /** App-defined correlation id tying participants to one shared case/account/work item. */
     caseGroup?: string;
-    /** Persona id/label threaded into this lane's actor prompt. Default: actors[0].persona. */
+    /** Persona id/label threaded into this participant's actor prompt. Default: actors[0].persona. */
     persona?: string;
-    /** Named hosted-screen preset for this lane. XOR raw execution.desktop.resolution. */
+    /** Named hosted-screen preset for this participant. XOR raw execution.desktop.resolution. */
     device?: string;
-    /** Per-lane steer appended to this lane's mission (the roster's per-lane focus). */
+    /** Steer appended to this participant's mission (the roster's per-participant focus). */
     instruction?: string;
     /**
-     * Deterministic lane completion guard. When set, this lane stops as soon as the runtime
+     * Deterministic participant completion guard. When set, this participant stops as soon as the runtime
      * observation matches any declared rule; actor-level stopWhen is used as the default.
      */
     stopWhen?: StopWhen;
-    /** A declared observation window for THIS lane (#510); actor-level dwell is the default. */
+    /** A declared observation window for this participant; actor-level dwell is the default. */
     dwell?: DwellWindow;
     /**
-     * How hard the model is asked to think in THIS lane; actor-level reasoningEffort is the default.
+     * How hard the model is asked to think for this participant; actor-level reasoningEffort is the default.
      *
      * The single-run control: same persona, same mission, two efforts, one set of conditions.
      */
     reasoningEffort?: ReasoningEffort;
     /**
-     * App-url computer-use ONLY: absolute browser URL this lane opens instead of `subject.appUrl`.
+     * App-url computer-use only: absolute browser URL this participant opens instead of `subject.appUrl`.
      * This is the generic setup-produced-target handoff for crawler/swarm labs: product adapters may
-     * start any topology they need, then hand humanish explicit lane targets. Public/non-loopback
+     * start any topology they need, then hand humanish explicit participant targets. Public/non-loopback
      * targets still require `policies.allowPublicTargets: true`. Inert/rejected on clone, local-app,
      * shared-world, scripted-browser, and terminal routes.
      */
     target?: string;
     /**
-     * Shared-world ONLY (#164): this role's per-seat loopback entry route, resolved against
-     * `subject.serve.url` and REQUIRED to be same-origin (loopback) with it — the seat opens
-     * `serve.url + entry`. Validated at parse AND re-enforced in the engine. Inert/warned on every
-     * non-shared-world route (the per-lane-worlds fan-out roster has no per-lane entry).
+     * Shared-world only: this participant's loopback entry route, resolved against
+     * `subject.serve.url`. It must be same-origin (loopback) with it, and the participant opens
+     * `serve.url + entry`. Validated at parse and re-enforced in the engine. Inert/warned on every
+     * non-shared-world route (the per-lane-worlds fan-out roster has no per-participant entry).
      */
     entry?: string;
     /**
-     * EXTERNAL-PUBLIC shared-world ONLY (#164 phase 2): marks this lane the DESIGNATED HOST seat — it
-     * creates the shared session (e.g. a multiplayer lobby) that the follower seats then join. Exactly
-     * ONE lane in the roster may carry `host: true` (validated in externalPublicSharedWorldValidationReason).
-     * The orchestrator watches the host seat's observed URL for the shared-session code and threads it
+     * External-public shared-world only: marks this participant as the host. It
+     * creates the shared session (e.g. a multiplayer lobby) that the followers then join. Exactly
+     * one participant in the roster may carry `host: true` (validated in externalPublicSharedWorldValidationReason).
+     * The orchestrator watches the host's observed URL for the shared-session code and threads it
      * into the follower missions at a host-first barrier. Inert/warned on every other route.
      */
     host?: boolean;
 }
 /**
- * Compact authoring sugar for repeated lane groups. The parser expands each group into concrete
+ * Compact authoring sugar for repeated participant groups. The parser expands each group into concrete
  * `lanes[]` with deterministic ids (`<group.id>-01`, `<group.id>-02`, ...). The runtime never
  * consumes this shape directly; it always sees ordinary `LabActorLane` entries.
  */
 export interface LabActorRosterGroup extends Omit<LabParticipantEntry, "id"> {
-    /** Public-safe group id; prefixes generated lane ids. */
+    /** Public-safe group id; prefixes generated participant ids. */
     id: string;
-    /** Number of lanes to generate for this group. */
+    /** Number of participants to generate for this group. */
     count: number;
 }
 export interface LabActor {
     /**
      * The actor label. On computer-use (including shared-world), scripted-browser, and
-     * terminal-product routes this is a REAL dispatch key resolved against the closed first-party
+     * terminal-product routes this is a real dispatch key resolved against the closed first-party
      * actor registry. On the synthetic route it remains a free-form descriptive label (e.g.
      * synthetic-persona). The terminal route owns its live lifecycle after using
      * the descriptor for dispatch and capability enforcement.
      */
     type: string;
-    /** Lane count — route-specific (see HONEST SCOPE header): synthetic simCount; scripted
+    /** Participant count, route-specific (see the scope header in config.ts): synthetic simCount; scripted
      *  surface roster {1 = desktop, 2 = desktop + mobile, default 1}; computer-use E2B route the
-     *  HOMOGENEOUS fan-out lane count (cap 16). XOR `lanes`. */
+     *  homogeneous fan-out participant count (cap 16). XOR `lanes`. */
     count?: number;
-    /** Computer-use E2B route: a DIFFERENTIATED fan-out roster (per-lane worlds). XOR `count`,
-     *  `roster`, and `laneFocus`. Cap 16 lanes. Consumed only on the cua E2B route
+    /** Computer-use E2B route: a differentiated fan-out roster (`per-lane-worlds`). XOR `count`,
+     *  `roster`, and `laneFocus`. Cap 16 participants. Consumed only on the cua E2B route
      *  (inert/warned elsewhere). */
     lanes?: LabParticipantEntry[];
     /** Persona id/label threaded into the actor prompt. Consumed on the app-url route. */
@@ -375,16 +377,17 @@ export interface LabActor {
     /** Consumed on the app-url route (laneFocus.instruction appended to the mission). XOR `lanes`. */
     laneFocus?: LabParticipantFocus;
     /** Free-form mission threaded into the actor prompt. Consumed on the app-url route. A mission on
-     *  its own is a complete, valid lab — `tasks` is additive, never required. */
+     *  its own is a complete, valid lab; `tasks` is additive, never required. */
     mission?: string;
     /**
      * The researcher's protocol: discrete tasks, each with what the participant is asked to do and
      * (optionally) how the researcher measures it. Additive to `mission`, which stays the brief.
      *
      * The two halves belong to different people. `goal` reaches the participant's prompt; `success`
-     * never does — a moderator does not read the success criterion aloud, because telling someone how
+     * never does. A moderator does not read the success criterion aloud, because telling someone how
      * they will be judged changes what they do. See src/lab/tasks.ts.
-     * Supported only on the first actor of per-lane CUA routes; other routes fail preflight.
+     * Supported only on the first actor of per-participant computer-use routes; other routes fail
+     * preflight.
      */
     tasks?: LabTask[];
     /** Provider model override. Consumed on the app-url route. */
@@ -392,35 +395,35 @@ export interface LabActor {
     /** First-party OpenAI CUA only: per-response output limit including reasoning, not a dollar cap. */
     maxOutputTokens?: number;
     /**
-     * `local-agent` ONLY: which locally signed-in coding agent is the brain. Absent = codex.
+     * `local-agent` only: which locally signed-in coding agent is the brain. Absent = codex.
      *
      * A separate field from `model` on purpose. The first cut of this route overloaded `model` to
-     * mean BOTH which CLI and which model, which left no way to say "Claude Code, running Opus" —
+     * mean both which CLI and which model, which left no way to say "Claude Code, running Opus":
      * two different choices wearing one name.
      */
     localAgent?: "codex" | "claude";
     /**
-     * How hard the model is asked to think, per turn. Lane-level `reasoningEffort` overrides this.
+     * How hard the model is asked to think, per turn. A `lanes[]` entry's `reasoningEffort` overrides this.
      *
-     * Absent means the PROVIDER's default, and absence is recorded as absence: a run that did not
+     * Absent means the provider's default, and absence is recorded as absence: a run that did not
      * declare an effort does not claim one. Support is model-dependent (see src/actors/reasoning-effort.ts),
      * so a level a model does not accept fails on the first turn rather than being downgraded.
      *
-     * This is a recruiting decision, not a tuning knob: it changes who the participant IS, the same
-     * way a persona prompt does. Two lanes running the same persona and mission at different efforts
-     * is therefore a CONTRAST between two participants, not a control for an instrument — a lane that
+     * This is a recruiting decision: it changes who the participant is, the same
+     * way a persona prompt does. Two participants running the same persona and mission at different efforts
+     * is therefore a contrast between two participants. It does not control for an instrument: a participant that
      * abandons at one level and completes at another has reported on both of them. The obligation it
      * creates is to declare and record, never to hold it constant. See
      * docs/principles/actor-fidelity.md.
      */
     reasoningEffort?: ReasoningEffort;
     /**
-     * Deterministic completion guard used as the default for CUA lanes. Lane-level stopWhen
+     * Deterministic completion guard used as the default for CUA participants. A `lanes[]` entry's stopWhen
      * overrides this value.
      */
     stopWhen?: StopWhen;
     /**
-     * A declared observation window (#510), the default for every lane; lane-level dwell overrides
+     * A declared observation window, the default for every participant; a `lanes[]` entry's dwell overrides
      * it. `when` is a stopWhen-shaped condition (absent: the window opens after the first
      * observation); `ms` is the hold, `everyMs` the frame cadence (default 10 s), `then` whether
      * the participant continues afterwards (default) or the session ends. The harness takes no
@@ -429,9 +432,9 @@ export interface LabActor {
     dwell?: DwellWindow;
 }
 type LabExecutionTarget = "local" | "e2b-desktop" | "e2b-terminal";
-/** Terminal transport: the captured non-interactive exec stream (stdin disabled). NOT an
- *  interactive duplex PTY — labeling captured exec output "pty" would be a claim/mechanism
- *  mismatch (invariant 6 + the goal packet's PTY ruling), so this lane uses "exec-stream". */
+/** Terminal transport: the captured non-interactive exec stream (stdin disabled). It is not an
+ *  interactive duplex PTY; labeling captured exec output "pty" would be a claim/mechanism
+ *  mismatch, so this route uses "exec-stream". */
 type LabTerminalTransport = "exec-stream";
 /** Whether operator stdin reaches the in-sandbox agent. Disabled by default (the run is
  *  autonomous + comparable to an unassisted baseline). "planned" records intent but sends no
@@ -457,13 +460,13 @@ export interface LabExecutionDesktop {
      * Named device preset (mobile / small-mobile / narrow-mobile / tablet / desktop / wide) the
      * run renders at. Consumed on the computer-use route; default `desktop` (1440x950). On that
      * route only width/height physically render (the X screen is sized to the preset, so
-     * width-based responsive CSS fires) — touch/DPR/UA are sim-parity prompt signals, not rendered.
+     * width-based responsive CSS fires). Touch/DPR/UA are sim-parity prompt signals and do not render.
      */
     device?: string;
-    /** Raw hosted screen resolution [width, height] — an escape hatch that overrides `device`. */
+    /** Raw hosted screen resolution [width, height]: an escape hatch that overrides `device`. */
     resolution?: [number, number];
     /**
-     * Browser family to launch for hosted desktop actor lanes. Absent/default preserves the
+     * Browser family to launch for hosted desktop participants. Absent/default preserves the
      * historical desktop opener behavior. A concrete value means "launch this browser or fail"
      * instead of silently accepting the template's default URL opener.
      */
@@ -471,10 +474,10 @@ export interface LabExecutionDesktop {
     /** Sandbox server-side timeout. Consumed on the app-url route. */
     sandboxTimeoutMs?: number;
     /**
-     * Custom E2B desktop TEMPLATE (image) the run launches on — a non-empty template NAME or ID —
+     * Custom E2B desktop template (image) the run launches on, given as a non-empty template name or ID,
      * instead of the stock `desktop` template. Lets a subject that needs runtimes the stock image
      * lacks (e.g. node/bun/a local Postgres baked into an adopter-maintained image) run as-is. Any
-     * string is a valid template name/id (there is no allowlist). Consumed ONLY on the
+     * string is a valid template name/id (there is no allowlist). Consumed only on the
      * `execution.target: e2b-desktop` computer-use routes (the cua/shared-world/concurrent backends
      * that call `Sandbox.create`) and the clone scripted-browser route; inert/warned on every route
      * that creates no desktop. Threaded to
@@ -485,19 +488,19 @@ export interface LabExecutionDesktop {
     /** Use the Codex app-server client mode for headed desktop actor surfaces. Consumed (meta). */
     codexAppServer?: boolean;
     /**
-     * Mobile fidelity beyond viewport size (#221). With `mobileEmulation: true`, every hosted
-     * Chromium computer-use lane ON A MOBILE PRESET (mobile / small-mobile / narrow-mobile) gets
+     * Mobile fidelity beyond viewport size. With `mobileEmulation: true`, every hosted
+     * Chromium computer-use participant on a mobile preset (mobile / small-mobile / narrow-mobile) gets
      * CDP device emulation applied to its launch page before the participant arrives; desktop,
-     * tablet and wide lanes in the same run are untouched and carry no fidelity block. Applied: the lane's device preset width/height as the CSS viewport, the preset's
+     * tablet and wide participants in the same run are untouched and carry no fidelity block. Applied: the participant's device preset width/height as the CSS viewport, the preset's
      * device pixel ratio (or `deviceScaleFactor`), touch events (`touch`, default true) and a mobile
      * user agent (`userAgent`, default an iPhone Safari string). The bundle records what the page
      * then reported about itself under `desktopGeometry.fidelity`; a browser that cannot be
-     * emulated (Firefox) fails the lane closed instead of shipping a desktop run labelled mobile.
+     * emulated (Firefox) fails the participant closed instead of shipping a desktop run labelled mobile.
      * A held CDP session also applies the overrides to later page targets. Their first observed
      * viewport and touch read-back is recorded separately; missing or different values warn.
      */
     fidelity?: LabDesktopFidelity;
-    /** Synthetic media devices behind the browser's own permission prompt (#509). */
+    /** Synthetic media devices behind the browser's own permission prompt. */
     media?: LabDesktopMedia;
     /** Optional retained screen video. Capture is independent of participant media input. */
     recording?: {
@@ -505,7 +508,7 @@ export interface LabExecutionDesktop {
     };
 }
 /**
- * A participant with a camera (#509): a property of the ENVIRONMENT, like the screen preset and
+ * A participant with a camera: a property of the environment, like the screen preset and
  * the browser, never support for any conferencing product. `camera.source: synthetic` generates
  * a test pattern in the sandbox with the image's own ffmpeg; a `.y4m` path on the host is
  * uploaded instead on hosted desktops. `microphone.source: speech` enables the participant's
@@ -532,25 +535,26 @@ export interface LabExecution {
     target?: LabExecutionTarget;
     /** Actor session wall-clock budget. Consumed on the app-url route. */
     timeoutMs?: number;
-    /** FORWARD-DECLARED. */
+    /** Forward-declared: no route reads it yet, so a set value warns. */
     completionTimeoutMs?: number;
     /**
-     * Bounds in-flight fan-out lanes on the computer-use route. Shared-world needs at least 2 and
+     * Bounds in-flight fan-out participants on the computer-use route. Shared-world needs at least 2 and
      * defaults to the participant count. Inert (warned) elsewhere.
      */
     concurrency?: number;
     desktop?: LabExecutionDesktop;
     /**
-     * Blast-radius budget for the computer-use lane. CONSUMED on the CUA route: `caps.maxUsd`, when
-     * set, is a FAIL-CLOSED abort — the session stops the moment its running ESTIMATED spend crosses
-     * it (the runaway-retry guard), and a cap on a model src/run/pricing.ts cannot price is REFUSED at
-     * preflight rather than run uncapped. It is a PER-LANE cap: enforced inside each lane's loop, so
-     * an N-lane fan-out can spend up to N × maxUsd before any lane aborts (the run warns with the
-     * true ~N × cap ceiling). `caps.maxTotalUsd` is the shared STUDY budget (#299): one ledger
-     * across every lane, the knob a researcher actually reasons with. Absent = UNCAPPED (the
-     * historical CUA behavior); maxUsd: 0 still permits a request before reported usage trips it. Inert
-     * (warned) on non-CUA routes. Reuses the same LabScenarioCaps shape as the terminal lane's
-     * `scenario.caps` (not a fork).
+     * Blast-radius budget for each computer-use participant. Consumed on the computer-use route:
+     * `caps.maxUsd`, when set, is a fail-closed abort: the session stops the moment its running
+     * estimated spend crosses it (the runaway-retry guard), and a cap on a model src/run/pricing.ts
+     * cannot price is refused at preflight rather than run uncapped. It is a per-participant cap:
+     * enforced inside each participant's loop, so an N-participant fan-out can spend up to N × maxUsd
+     * before any participant aborts (the run warns with the true ~N × cap ceiling).
+     * `caps.maxTotalUsd` is the shared study budget: one ledger across every participant, the knob a
+     * researcher actually reasons with. Absent = uncapped (the historical CUA behavior); maxUsd: 0
+     * still permits a request before reported usage trips it. Inert (warned) on non-computer-use
+     * routes. Reuses the same LabScenarioCaps shape as the terminal route's `scenario.caps` (not a
+     * fork).
      */
     caps?: LabScenarioCaps;
     /** `terminal-product` route: the terminal transport + stdin posture. Consumed on that route. */
@@ -565,14 +569,14 @@ export interface LabExecution {
     /**
      * `terminal-product` route: outbound routing allowlist passed to E2B with a deny-all fallback.
      * Domain filtering is a routing control, not strict destination isolation on shared hosting.
-     * It does not constrain spending through an allowed runtime provider (#538), including when
+     * It does not constrain spending through an allowed runtime provider, including when
      * openai-egress keeps the raw runtime key outside the sandbox.
      *
      * Absent means unrestricted, which is the historical behavior and stays the default, because a
      * wrong host list fails studies in ways that look like product bugs. Opt in per lab.
      *
      * Domain filtering covers HTTP on :80 (Host header) and TLS on :443 (SNI); anything else needs
-     * an IP or CIDR. `*.example.com` matches subdomains at any depth and NOT the apex, which needs
+     * an IP or CIDR. `*.example.com` matches subdomains at any depth and not the apex, which needs
      * its own entry.
      */
     egressAllow?: string[];
@@ -584,20 +588,20 @@ type LabScenarioMode = "dry-run" | "live";
  * All values are non-negative numbers (0 is the no-spend default). Live runs require maxUsd and a
  * positive maxMinutes; maxUsd/maxJobs are checked after the session against known ledger signals
  * and maxMinutes is enforced as the command wall clock. Codex tokens are unpriced, so a live run
- * refuses a positive maxUsd unless a costProbe measures spend (HUMANISH_TERMINAL_LAB_UNPRICED_CAP).
+ * refuses a positive maxUsd unless a costProbe measures spend (HUMANISH_TERMINAL_UNPRICED_CAP).
  */
 export interface LabScenarioCaps {
     /** Max USD the run may spend (provider + product). 0 = no-spend. */
     maxUsd?: number;
     /**
-     * STUDY-LEVEL model-spend budget (#299), the number a researcher actually reasons with: "this
-     * study is N participants, roughly $X" — decided once, up front, where recruiting decisions are
-     * made. The computer-use route reads it from `execution.caps.maxTotalUsd` only: every lane's
-     * running ESTIMATED model spend feeds one shared ledger, and the moment the run total crosses
-     * this, each lane stops at its next turn with an honest `budget_reached` (status `incomplete` —
+     * study-level model-spend budget, the number a researcher actually reasons with: "this
+     * study is N participants, roughly $X", decided once, up front, where recruiting decisions are
+     * made. The computer-use route reads it from `execution.caps.maxTotalUsd` only: every participant's
+     * running estimated model spend feeds one shared ledger, and the moment the run total crosses
+     * this, each participant stops at its next turn with `budget_reached` (status `incomplete`:
      * the participant ran out of budget; never `gave_up`, because a study-level stop is not the
-     * participant's doing). Estimated MODEL spend only — desktop-minutes ride the cost summary but
-     * not this ledger. Independent of the per-lane `maxUsd` backstop; either, both, or neither may
+     * participant's doing). Estimated model spend only; desktop-minutes ride the cost summary but
+     * not this ledger. Independent of the per-participant `maxUsd` backstop; either, both, or neither may
      * be set. A positive `scenario.caps.maxTotalUsd` on a computer-use lab is a parse error; on the
      * terminal route it is inert (warned), since the single agent's maxUsd already caps the run.
      */
@@ -608,12 +612,12 @@ export interface LabScenarioCaps {
     maxMinutes?: number;
 }
 export interface LabScenario {
-    /** Reference a committed scenario by id (humanish/scenarios/<ref>.yaml) or path. CONSUMED
-     *  (and REQUIRED) on the scripted-browser route; FORWARD-DECLARED elsewhere. */
+    /** Reference a committed scenario by id (humanish/scenarios/<ref>.yaml) or path. Consumed
+     *  (and required) on the scripted-browser route; forward-declared elsewhere. */
     ref?: string;
-    /** Or inline the scenario body. FORWARD-DECLARED (PR #2). */
+    /** Or inline the scenario body. Forward-declared: no route reads it yet, so a set value warns. */
     inline?: Record<string, unknown>;
-    /** dry-run = contract evidence (no provider spend); live = real run. Consumed. */
+    /** dry-run = a synthetic bundle with no provider spend; live = real run. Consumed. */
     mode?: LabScenarioMode;
     /** Spend/job/time caps. Consumed (recorded in the bundle) on the terminal-product route;
      *  inert (warned) elsewhere. */
@@ -622,14 +626,14 @@ export interface LabScenario {
 export interface LabPolicies {
     /**
      * Redact target repo labels in durable artifacts. Consumed on the computer-use,
-     * scripted-browser and shared-world clone routes (provenance), where it DEFAULTS to true when
+     * scripted-browser and shared-world clone routes (provenance), where it defaults to true when
      * the clone authenticates via GITHUB_TOKEN (a token-bearing clone is treated as private until
      * declared otherwise).
      */
     redactRepos?: boolean;
     /**
-     * Blur+downscale persisted screenshots on the computer-use route. Default FALSE — the common
-     * case is watching a sim of your OWN app locally (gitignored .humanish), where full fidelity is
+     * Blur+downscale persisted screenshots on the computer-use route. Default `false`; the common
+     * case is watching a sim of your own app locally (gitignored .humanish), where full fidelity is
      * the deliverable. Set true for unowned subjects or bundles meant to be shared as-is. The
      * provider always sees raw frames; this only governs what is persisted. Raw bundles stay
      * local (gitignored, commit-scan-guarded); a redact-on-export step for them is planned.
@@ -637,12 +641,12 @@ export interface LabPolicies {
     redactScreenshots?: boolean;
     /**
      * Allow an app-url subject to point at a non-loopback (public/preview/staging) URL the lab
-     * owner declares. Default FALSE (loopback-only). The invariant is "the actor drives a target
-     * the owner declared" — setting this IS that declaration (e.g. a Vercel preview of your app).
+     * owner declares. Default `false` (loopback-only). The invariant is "the actor drives a target
+     * the owner declared"; setting this is that declaration (e.g. a Vercel preview of your app).
      */
     allowPublicTargets?: boolean;
     /**
-     * How the browser's camera/microphone permission is answered (#509). `prompt` (default): the
+     * How the browser's camera/microphone permission is answered. `prompt` (default): the
      * participant meets Chrome's real dialog and answers it, which is where a real person hesitates
      * or refuses. `granted`: the dialog is bypassed (`--use-fake-ui-for-media-stream`, which Chrome
      * marks with an "unsupported command-line flag" banner), for studies about what happens after
@@ -661,17 +665,17 @@ export interface LabPolicies {
 export interface LabReview {
     /** Analysis defaults on for eligible live recordings; false disables the separate request. */
     analysis?: LabAnalysis | false;
-    /** FORWARD-DECLARED (PR #2). */
+    /** Forward-declared: no route reads it yet, so a set value warns. */
     scoring?: string;
-    /** FORWARD-DECLARED (PR #2). */
+    /** Forward-declared: no route reads it yet, so a set value warns. */
     milestones?: string;
-    /** FORWARD-DECLARED (PR #2). */
+    /** Forward-declared: no route reads it yet, so a set value warns. */
     vocabulary?: string;
     /**
-     * #316 code escape hatch: a repo-relative path to an adopter scorer module (.mjs recommended) that
-     * exports any of `{score, deriveFeedback, deriveArtifacts}`. CONSUMED on the scorer-capable routes
+     * Code escape hatch: a repo-relative path to an adopter scorer module (.mjs recommended) that
+     * exports any of `{score, deriveFeedback, deriveArtifacts}`. Consumed on the scorer-capable routes
      * (terminal / computer-use / shared-world); loaded fail-closed (typed error, pre-spend). The entry
-     * is executable code — review a PR that adds one as code, not config.
+     * is executable code: review a PR that adds one as code.
      */
     scorer?: {
         ref: string;
@@ -680,7 +684,7 @@ export interface LabReview {
 export interface LabDefaults {
     open?: boolean;
 }
-/** Off-app comms (email/SMS the persona lives in) the harness provides for the run (#297). */
+/** Off-app comms (email/SMS the persona lives in) the harness provides for the run. */
 export interface LabComms {
     email?: LabCommsEmail;
 }
@@ -716,15 +720,15 @@ interface LabCommsCaptureEmail {
     connection?: never;
     allowedOrigins?: never;
     /** Which implementation backs the inbox (a backend discriminator, distinct from `scenario.mode`):
-     *  `fake` (default) is an in-harness in-memory inbox in the Fowler test-double sense — an in-sandbox
+     *  `fake` (default) is an in-harness in-memory inbox in the Fowler test-double sense: an in-sandbox
      *  catch captures the app's sends. Provider-backed receiving uses the separate
      *  LabCommsReceivingEmail configuration selected by a saved connection. */
     kind: "fake";
     /**
-     * The subject-env var the harness sets to the in-sandbox catch's base URL — ADOPTER-NAMED (an app
+     * The subject-env var the harness sets to the in-sandbox catch's base URL. The adopter names it (an app
      * calling Resend's API directly reads `RESEND_API_URL`; an app using the SDK reads `RESEND_BASE_URL`).
-     * The value is computed by the harness (a loopback URL), so it is NOT declared in `subject.env`.
-     * REQUIRED on the provisioned routes; absent (and meaningless) when `external` is declared,
+     * The value is computed by the harness (a loopback URL), so it is not declared in `subject.env`.
+     * Required on the provisioned routes; absent (and meaningless) when `external` is declared,
      * because there the adopter runs the catch and points their own app at it.
      */
     injectEnv?: string;
@@ -736,7 +740,7 @@ interface LabCommsCaptureEmail {
      * into the same captured-send shape the HTTP path produces, so the inbox surface, the drain, and
      * the evidence artifact are identical either way.
      *
-     * `hostEnv` and `portEnv` are ADOPTER-NAMED, exactly like `injectEnv`: the harness sets them to
+     * `hostEnv` and `portEnv` are adopter-named, exactly like `injectEnv`: the harness sets them to
      * its own loopback and the chosen port. Declare the pair your app actually reads.
      */
     smtp?: LabCommsSmtp;
@@ -746,19 +750,20 @@ interface LabCommsCaptureEmail {
      *  prepended to the inbox link-origin rewrite so the persona's clicked link resolves to a reachable
      *  host. Omit when the app emits loopback links (the default derivation covers those). */
     linkOrigin?: string;
-    /** Each lane's inbox address: the actor is TOLD to sign up with it (the injected inbox
+    /** Each participant's inbox address: the actor is told to sign up with it (the injected inbox
      *  instruction carries it) and the teardown drain matches captured mail against it. Omit the
-     *  whole list and the parser fills one deterministic address per lane (`<laneId>@example.test`)
-     *  so every seat can do email out of the box (#351). When declared: a `lane` naming a lane that
-     *  does not exist is a hard parse error (a mismatch silently disables the funnel for that seat),
-     *  zero covered lanes is a hard error, and partial coverage warns with the uncovered lanes. An
-     *  entry without `address` is legal but inert for the funnel — it is NOT matched by the drain
-     *  and its lane gets no inbox instruction; captured mail to an undeclared address is warned,
+     *  whole list and the parser fills one deterministic address per participant (`<laneId>@example.test`)
+     *  so every participant can do email out of the box. When declared: a `lane` naming a participant
+     * that  does not exist is a hard parse error (a mismatch silently disables the funnel for that
+     * participant),  zero covered participants is a hard error, and partial coverage warns with the
+     * uncovered ones. An  entry without `address` is legal but inert for the funnel: the drain does
+     * not match it,  and its participant gets no inbox instruction; captured mail to an undeclared
+     * address is warned,
      *  never silently dropped. */
     recipients?: LabCommsRecipient[];
     /**
-     * ADOPTER-HOSTED ingress (#328). Declaring this says: the operator runs the catch and the inbox
-     * themselves, so humanish neither provisions the subject nor injects `injectEnv` — it points the
+     * adopter-hosted ingress. Declaring this says: the operator runs the catch and the inbox
+     * themselves, so humanish neither provisions the subject nor injects `injectEnv`. It points the
      * persona at the declared inbox, drains the declared catch over HTTP at teardown, and writes the
      * same digest-only evidence. This is what makes comms work on the app-url / operator-provisioned
      * plane, where humanish holds no sandbox handle to host a catch in and the block was previously
@@ -771,25 +776,26 @@ export interface LabCommsExternal {
     catchBaseUrl: string;
     /** Where the persona opens its inbox. Defaults to catchBaseUrl (one server serves both). */
     inboxBaseUrl?: string;
-    /** Env var NAME holding the bearer token for the drain read. The NAME is recorded as evidence;
+    /** Env var name holding the bearer token for the drain read. The name is recorded as evidence;
      *  the value is read at runtime and never persisted (the credential-boundary discipline). */
     authTokenEnv?: string;
 }
 export interface LabCommsRecipient {
     lane: string;
-    /** The literal address the app sends to — what the evidence drain matches. Omit to reserve the lane
+    /** The literal address the app sends to, which the evidence drain matches. Omit to reserve the participant
      *  for the persona surface's default address (not drain-matched). */
     address?: string;
 }
 export interface LabConfig {
-    schema: typeof LAB_CONFIG_SCHEMA;
+    /** The format the file was written in. Both parse into this one shape. */
+    schema: typeof LAB_CONFIG_SCHEMA | typeof STUDY_SCHEMA;
     id: string;
     title?: string;
     description?: string;
     subject: LabSubject;
     actors: LabActor[];
     execution?: LabExecution;
-    /** FORWARD-DECLARED (PR #2). */
+    /** Forward-declared: no route reads it yet, so a set value warns. */
     personas?: Record<string, unknown>[];
     scenario?: LabScenario;
     policies?: LabPolicies;
@@ -805,7 +811,7 @@ interface LabConfigParseSuccess {
 export interface LabConfigParseFailure {
     ok: false;
     error: {
-        code: "HUMANISH_LAB_INVALID";
+        code: "HUMANISH_STUDY_INVALID";
         message: string;
     };
 }