humanish 0.106.1 → 0.107.0

package/dist/lab/types.d.ts

@@ -6,8 +6,8 @@ export declare const LAB_CONFIG_SCHEMA = "humanish.lab.v2";
 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
  * `RunLabOptions.inProcess` + `createProvider` (no built-in driver exists yet), and the engine
@@ -16,11 +16,11 @@ export declare const ID_PATTERN: RegExp;
  */
 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` (#164) 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).
  */
@@ -28,7 +28,7 @@ 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;
@@ -54,7 +54,7 @@ export interface LabSubjectServe {
     /** 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
+     *  serves the clone inside the sandbox, so this is always loopback (not subject to
      *  allowPublicTargets — that governs app-url subjects, i.e. external deployments). */
     url: string;
     /** Budget for the served app to answer the readiness probe. Default 180000. */
@@ -70,38 +70,38 @@ 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 shape is load-bearing, validated at parse and re-enforced in the engine).
      */
     name: string;
     /**
      * 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.
+     * 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 surface. Consumed only on the shared-world route (#164); 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.
+     * parse and re-enforced in the engine.
      */
     name: string;
     /**
@@ -113,39 +113,39 @@ 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
+     * 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.
      */
     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 unpinned (invariant 5). 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
@@ -157,28 +157,28 @@ 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
+     * 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.
      */
@@ -187,31 +187,31 @@ export interface LabSubjectProduct {
 export interface LabSubject {
     source: LabSubjectSource;
     /**
-     * WORLD topology across actor lanes. Absent == `per-lane-worlds` (the isolation default; every
+     * World topology across participants. 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);
+     * 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 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 (#164 phase 2): 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 (#164 phase 2): 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.
+     * 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
+     * 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.
      */
@@ -225,29 +225,29 @@ export interface LabSubject {
     /**
      * `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.
+     * 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
+     * `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.
+     * 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`.
      */
@@ -256,12 +256,12 @@ export interface LabSubject {
      * `clone` (computer-use route): the subject's state story — 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.
+     * 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 +276,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 (#510); 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 (#164): 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
+     * External-public shared-world only (#164 phase 2): marks this participant as the host. 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).
+     * one participant 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
      * 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. */
@@ -384,7 +384,7 @@ export interface LabActor {
      * 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
      * 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 CUA routes; other routes fail preflight.
      */
     tasks?: LabTask[];
     /** Provider model override. Consumed on the app-url route. */
@@ -392,35 +392,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 (#510), 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 +429,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
+/** 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 (invariant 6 + the goal packet's PTY ruling), so this lane uses "exec-stream". */
+ *  mismatch (invariant 6 + the goal packet's PTY ruling), 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
@@ -463,7 +463,7 @@ export interface LabExecutionDesktop {
     /** 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 +471,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
@@ -486,13 +486,13 @@ export interface LabExecutionDesktop {
     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
+     * 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.
      */
@@ -505,7 +505,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 (#509): 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
@@ -535,21 +535,21 @@ export interface LabExecution {
     /** FORWARD-DECLARED. */
     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
+     * Blast-radius budget for each computer-use participant. 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-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 (#299): 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-CUA routes. Reuses the same LabScenarioCaps shape as the terminal lane's
+     * (warned) on non-CUA routes. Reuses the same LabScenarioCaps shape as the terminal route's
      * `scenario.caps` (not a fork).
      */
     caps?: LabScenarioCaps;
@@ -572,7 +572,7 @@ export interface LabExecution {
      * 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[];
@@ -592,12 +592,12 @@ export interface LabScenarioCaps {
     /**
      * 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` —
+     * 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 an honest `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,8 +608,8 @@ 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). */
     inline?: Record<string, unknown>;
@@ -622,14 +622,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,8 +637,8 @@ 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;
     /**
@@ -669,7 +669,7 @@ export interface LabReview {
     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
+     * 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.
      */
@@ -723,8 +723,8 @@ interface LabCommsCaptureEmail {
     /**
      * The subject-env var the harness sets to the in-sandbox catch's base URL — ADOPTER-NAMED (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;
@@ -746,14 +746,14 @@ 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
+     *  whole list and the parser fills one deterministic address per participant (`<laneId>@example.test`)
+     *  so every seat can do email out of the box (#351). When declared: a `lane` naming a participant 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,
+     *  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[];
     /**
@@ -771,13 +771,13 @@ 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 — what the evidence drain matches. Omit to reserve the participant
      *  for the persona surface's default address (not drain-matched). */
     address?: string;
 }