humanish 0.106.1 → 0.108.0

package/dist/lab/composition-rules.js

@@ -8,8 +8,8 @@
 import { isLoopbackUrl } from "./parse/subject.js";
 import { REPO_SLUG_PATTERN } from "./parse/values.js";
 import { declaredTargets } from "./plan-participants.js";
-import { actorResolvesToComputerUse, actorResolvesToScriptedBrowser, actorResolvesToTerminal, cuaLaneCount, registeredComputerUseActors, registeredScriptedBrowserActors, registeredTerminalActors, isComputerUseComposition, } from "./routing.js";
-import { cloneTargetValidationReason, cuaLaneValidationReason, sharedWorldValidationReason, } from "./validation.js";
+import { actorResolvesToComputerUse, actorResolvesToScriptedBrowser, actorResolvesToTerminal, computerUseParticipantCount, registeredComputerUseActors, registeredScriptedBrowserActors, registeredTerminalActors, isComputerUseComposition, } from "./routing.js";
+import { cloneTargetValidationReason, computerUseValidationReason, sharedWorldValidationReason, } from "./validation.js";
 import { rosterOf } from "./parse/actors.js";
 /** The first composition rule a config breaks, in the parser's order, or null. */
 export function compositionReason(config) {
@@ -21,10 +21,10 @@ export function compositionReason(config) {
         cloneTargetValidationReason(config) ??
         cloneComputerUseValidationReason(config) ??
         localTreeValidationReason(config) ??
-        // Independent computer-use lanes: the roster contract on every route that resolves to cua.
-        (isComputerUseComposition(config) ? cuaLaneValidationReason(config) : null) ??
+        // Independent computer-use participants: the roster contract on every route that resolves to cua.
+        (isComputerUseComposition(config) ? computerUseValidationReason(config) : null) ??
         // Whenever shared world is declared, not only when it routes, so a half-declared shared world
-        // fails with a precise reason instead of running as independent lanes.
+        // fails with a precise reason instead of running as independent participants.
         (config.subject.topology === "shared-world" ? sharedWorldValidationReason(config) : null) ??
         desktopCliValidationReason(config) ??
         terminalValidationReason(config) ??
@@ -32,7 +32,7 @@ export function compositionReason(config) {
 }
 /** Why a this-repo lab cannot run live. The parser and the preview planner both refuse with it. */
 export const THIS_REPO_DRY_RUN_ONLY = "this-repo labs are dry-run only; use a clone or app-url subject for a live run.";
-// this-repo subjects run locally and dry-run only — there is no live execution target for the
+// this-repo subjects run locally and dry-run only: there is no live execution target for the
 // host repo (clone/app-url provide that). Reject the mis-configs rather than silently mishandle.
 function thisRepoValidationReason(config) {
     if (config.subject.source === "this-repo") {
@@ -45,57 +45,57 @@ function thisRepoValidationReason(config) {
     }
     return null;
 }
-// local-app route: an already-running LOCAL dev server driven IN-PROCESS via a custom
+// local-app route: an already-running local dev server driven in-process via a custom
 // CuaExecutor (no clone, no E2B desktop). Parse-validated fail-closed: a computer-use actor
-// only, execution.target local or absent (NEVER e2b-desktop — the whole point is to skip the
+// only, execution.target local or absent (never e2b-desktop, because the route exists to skip the
 // desktop), and no public-target policy (it is always loopback; the loopback shape was already
-// enforced in parseSubject). The actual "no buildExecutor hook supplied" case is inherently an
-// engine-time decision (the parser cannot know whether a library caller will pass hooks), so
-// it fails closed in runCuaActorLab with HUMANISH_CUA_LAB_LOCAL_APP_NO_EXECUTOR.
+// enforced in parseSubject). The actual "no inProcess executor supplied" case is inherently an
+// engine-time decision (the parser cannot know whether a library caller will pass one), so
+// it fails closed in runCuaActorLab with HUMANISH_COMPUTER_USE_LOCAL_APP_NO_EXECUTOR.
 function localAppValidationReason(config) {
     if (config.subject.source === "local-app") {
         const type = config.actors[0]?.type ?? "";
         if (config.execution?.target !== undefined && config.execution.target !== "local") {
-            return "local-app subjects drive an in-process LOCAL dev server with NO E2B desktop — set `execution.target: local` or omit it (absent means local); `e2b-desktop` is rejected (use an app-url subject for the hosted-desktop route).";
+            return "A local-app subject drives a local dev server in this process, with no E2B desktop. Set `execution.target: local` or omit it. To run on a hosted desktop, use an app-url subject with `execution.target: e2b-desktop`.";
         }
         if (!actorResolvesToComputerUse(type)) {
             return `actors[0].type must be a registered computer-use actor for local-app subjects (one of: ${registeredComputerUseActors().join(", ")}); the caller's custom executor runs the computer-use loop. Got "${type}".`;
         }
-        if (cuaLaneCount(config) > 1) {
+        if (computerUseParticipantCount(config) > 1) {
             return "Fan-out to more than one participant is not supported on the in-process/local-app route: fan-out provisions one independent E2B desktop per participant, which the in-process route deliberately skips. Set actors[0].count to 1 and drop actors[0].lanes (use an app-url or clone subject on execution.target: e2b-desktop for fan-out).";
         }
         if (rosterOf(config.actors[0]) !== undefined) {
             return "`actors[0].lanes` (fan-out roster) is not supported on the in-process/local-app route: it provisions one E2B desktop per participant, which this route skips. Use an app-url or clone subject with execution.target: e2b-desktop.";
         }
         if (config.policies?.allowPublicTargets === true) {
-            return "`policies.allowPublicTargets` is not supported on the local-app route — a local-app subject is always a loopback dev server; there is no public target to allow.";
+            return "`policies.allowPublicTargets` does not apply to a local-app subject: it is always a loopback dev server, so there is no public target to allow. Remove the setting.";
         }
     }
     return null;
 }
-// app-url routes: the actor type is a REAL dispatch key (registry-resolved). The actor LANE
+// app-url routes: the actor type is a real dispatch key (registry-resolved). The actor's run kind
 // picks the substrate: a scripted-browser actor runs locally against the declared loopback
 // app; a computer-use actor drives a hosted desktop browser. Fail closed on mis-configs.
 function appUrlValidationReason(config) {
     if (config.subject.source === "app-url") {
         const type = config.actors[0]?.type ?? "";
         if (actorResolvesToScriptedBrowser(type)) {
-            // Scripted-browser route (all fail-closed: invariant 6 — a field that cannot act on
+            // Scripted-browser route (all fail-closed, so claims match mechanism: a field that cannot act on
             // this route is rejected, never silently ignored).
             if (config.execution?.target !== undefined && config.execution.target !== "local") {
-                return "scripted-browser actors run on the operator's machine — set `execution.target: local` or omit it (absent means local); in-sandbox scripted execution is a later slice.";
+                return "A scripted-browser actor on an app-url subject runs on this machine. Set `execution.target: local` or omit it. To run scripted steps on a hosted desktop, use a clone subject.";
             }
             if (!config.scenario?.ref) {
-                return "scripted-browser labs require `scenario.ref` — the committed scenario's browser steps are what this actor executes.";
+                return "A scripted-browser study needs `scenario.ref`: the actor runs the browser steps in that scenario file.";
             }
             if ((config.actors[0]?.count ?? 1) > 2) {
-                return "scripted-browser labs support actors[0].count of 1 (desktop surface) or 2 (desktop + mobile); larger fan-out is a later slice.";
+                return "A scripted-browser study takes `actors[0].count` 1 (desktop) or 2 (desktop and mobile). Higher counts are not supported yet.";
             }
             if (config.policies?.redactScreenshots === true) {
-                return "`policies.redactScreenshots: true` is not implemented on the scripted-browser route yet — screenshots persist raw in gitignored .humanish; a silently ignored redaction policy would be a safety lie, so it is rejected.";
+                return "`policies.redactScreenshots: true` is not supported on the scripted-browser route yet, so its screenshots would be stored unredacted in .humanish/. Remove the setting, or use a computer-use actor, which blurs screenshots as it takes them.";
             }
             if (config.policies?.allowPublicTargets === true) {
-                return "`policies.allowPublicTargets` is not supported on the scripted-browser route — the scripted step driver enforces loopback at every navigation; public targets on this route are a later slice.";
+                return "`policies.allowPublicTargets` is not supported on the scripted-browser route: the step driver allows only loopback URLs at every navigation. Remove the setting, or drive the public URL with a computer-use actor.";
             }
             if (!isLoopbackUrl(config.subject.appUrl ?? "")) {
                 return "`subject.appUrl` must be a loopback URL (127.0.0.1/localhost) on the scripted-browser route.";
@@ -108,15 +108,15 @@ function appUrlValidationReason(config) {
             if (!actorResolvesToComputerUse(type)) {
                 return `actors[0].type must be a registered computer-use actor for app-url × e2b-desktop labs (one of: ${registeredComputerUseActors().join(", ")}); for local scripted execution use a registered scripted-browser actor (${registeredScriptedBrowserActors().join(", ")}). Got "${type}".`;
             }
-            // Multi-lane fan-out is CONSUMED on this route (per-lane worlds; the shared cua-lane
-            // cross-validation below enforces lanes/count XOR rules, the 16 cap, and the
-            // lane-level target gates, and the allowPublicTargets+N>1 rejection for ambiguous one-target
+            // Multi-participant fan-out is consumed on this route (`per-lane-worlds`; the shared cua
+            // cross-validation below enforces `lanes`/`count` XOR rules, the 16 cap, and the
+            // per-participant target gates, and the allowPublicTargets+N>1 rejection for ambiguous one-target
             // fan-out).
             // Loopback by default; an owner may declare a public/preview target via policies.
             const targets = [config.subject.appUrl ?? "", ...declaredTargets(config)];
             const unsafeTarget = targets.find((target) => !config.policies?.allowPublicTargets && !isLoopbackUrl(target));
             if (unsafeTarget !== undefined) {
-                return "`subject.appUrl` and `actors[0].lanes[].target` must be loopback URLs (127.0.0.1/localhost) unless `policies.allowPublicTargets: true` is set — set it to drive deployed/preview URLs you own.";
+                return "`subject.appUrl` and `actors[0].lanes[].target` must be loopback URLs (127.0.0.1 or localhost). To drive a deployed or preview URL you own, set `policies.allowPublicTargets: true`.";
             }
         }
     }
@@ -130,10 +130,10 @@ function scriptedBrowserValidationReason(config) {
             return "scripted-browser actors require `subject.source: app-url` (a running app at a loopback URL) or `subject.source: clone` with `execution.target: e2b-desktop` (a provisioned synthetic subject).";
         }
         if (config.execution?.target !== "e2b-desktop") {
-            return "clone subjects with scripted-browser actors require `execution.target: e2b-desktop` — the lab provisions the clone in E2B, exposes it with getHost, then drives deterministic browser steps.";
+            return "A clone subject with a scripted-browser actor needs `execution.target: e2b-desktop`: humanish builds the clone in an E2B sandbox, opens it at a public sandbox URL and runs the scenario's browser steps against it.";
         }
         if (!config.subject.serve) {
-            return "clone subjects with scripted-browser actors require `subject.serve` (start + url) — the lab serves the app in-sandbox before the scripted browser drives it.";
+            return "A clone subject with a scripted-browser actor needs `subject.serve` (start and url): humanish starts the app in the sandbox before the browser steps run.";
         }
         if ((config.subject.repos?.length ?? 0) !== 1) {
             return "clone scripted-browser labs require exactly one repo in subject.repos.";
@@ -143,49 +143,49 @@ function scriptedBrowserValidationReason(config) {
             return `subject.repos[0] must be an owner/repo slug (got "${repo}").`;
         }
         if (config.subject.topology !== undefined) {
-            return "clone scripted-browser labs do not support `subject.topology` yet — this slice provisions one synthetic subject and one deterministic scripted actor roster, not a shared-world run.";
+            return "A clone scripted-browser study does not support `subject.topology` yet: it runs one synthetic subject for its scripted actor. Remove `subject.topology`.";
         }
         if (config.subject.clone?.fanout !== undefined || config.subject.clone?.keep === true) {
-            return "clone scripted-browser labs do not support `subject.clone.fanout` or `subject.clone.keep` yet — the provisioned subject is always a single disposable E2B sandbox.";
+            return "A clone scripted-browser study does not support `subject.clone.fanout` or `subject.clone.keep` yet: its subject is always one sandbox, removed after the run.";
         }
         if (!config.scenario?.ref) {
-            return "scripted-browser labs require `scenario.ref` — the committed scenario's browser steps are what this actor executes.";
+            return "A scripted-browser study needs `scenario.ref`: the actor runs the browser steps in that scenario file.";
         }
         if ((config.actors[0]?.count ?? 1) > 2) {
-            return "scripted-browser labs support actors[0].count of 1 (desktop surface) or 2 (desktop + mobile); larger fan-out is a later slice.";
+            return "A scripted-browser study takes `actors[0].count` 1 (desktop) or 2 (desktop and mobile). Higher counts are not supported yet.";
         }
         if (rosterOf(config.actors[0]) !== undefined) {
-            return "`actors[0].lanes` is not supported on the scripted-browser route yet — use actors[0].count for the deterministic surface roster.";
+            return "`actors[0].lanes` is not supported on the scripted-browser route yet. Use `actors[0].count` to choose the desktop and mobile surfaces.";
         }
         if (config.policies?.redactScreenshots === true) {
-            return "`policies.redactScreenshots: true` is not implemented on the scripted-browser route yet — screenshots persist raw in gitignored .humanish; a silently ignored redaction policy would be a safety lie, so it is rejected.";
+            return "`policies.redactScreenshots: true` is not supported on the scripted-browser route yet, so its screenshots would be stored unredacted in .humanish/. Remove the setting, or use a computer-use actor, which blurs screenshots as it takes them.";
         }
         if (config.policies?.allowPublicTargets === true) {
-            return "`policies.allowPublicTargets` is not supported on the clone scripted-browser route — the only external host is the harness-minted getHost URL for a provisioned synthetic subject.";
+            return "`policies.allowPublicTargets` does not apply to a clone scripted-browser study: its only public URL is the sandbox URL humanish opens for its synthetic subject. Remove the setting.";
         }
         if (config.subject.exposure !== "synthetic") {
-            return "clone scripted-browser labs require `subject.exposure: synthetic` — the subject is exposed on an internet-reachable getHost URL for the run, so the author must attest it is synthetic seeded data.";
+            return "A clone scripted-browser study needs `subject.exposure: synthetic`. The subject is reachable from the internet at a public sandbox URL during the run, so the study must declare that its data is synthetic.";
         }
         if (!config.subject.state?.seed ||
             config.subject.state.seed.length === 0 ||
             (config.subject.state.external?.length ?? 0) > 0) {
-            return "clone scripted-browser labs require `subject.state.seed` and do not allow `subject.state.external` — getHost-exposed subjects must be synthetic seeded data, not external/unpinned state.";
+            return "A clone scripted-browser study needs `subject.state.seed` and cannot use `subject.state.external`: a subject at a public sandbox URL may hold only seeded synthetic data.";
         }
         if (!config.subject.serve.start.includes("0.0.0.0")) {
-            return "clone scripted-browser labs require `subject.serve.start` to bind all interfaces (e.g. `-H 0.0.0.0` / `--host 0.0.0.0` / `HOST=0.0.0.0`) — getHost only routes to a 0.0.0.0-bound port; the readiness probe stays loopback.";
+            return "A clone scripted-browser study needs `subject.serve.start` to listen on all interfaces (for example `-H 0.0.0.0`, `--host 0.0.0.0` or `HOST=0.0.0.0`): the public sandbox URL reaches only a port bound to 0.0.0.0. The readiness probe still uses loopback.";
         }
     }
     return null;
 }
-// clone × e2b-desktop disambiguates on the actor lane: a computer-use actor means the lab
-// clones AND serves the subject in-sandbox, then drives it. Scripted-browser actors were checked
+// clone × e2b-desktop disambiguates on the actor's run kind: a computer-use actor means the study
+// clones and serves the subject in-sandbox, then drives it. Scripted-browser actors were checked
 // above.
 function cloneComputerUseValidationReason(config) {
     if (config.subject.source === "clone" &&
         config.execution?.target === "e2b-desktop" &&
         actorResolvesToComputerUse(config.actors[0]?.type)) {
         if (!config.subject.serve) {
-            return "clone subjects on the computer-use route require `subject.serve` (start + url) — the lab serves the app in-sandbox before the actor drives it.";
+            return "A clone subject on the computer-use route needs `subject.serve` (start and url): humanish starts the app in the sandbox before the participant opens it.";
         }
         if ((config.subject.repos?.length ?? 0) !== 1) {
             return "computer-use clone labs serve one repo; declare exactly one repo in subject.repos.";
@@ -194,15 +194,15 @@ function cloneComputerUseValidationReason(config) {
         if (!REPO_SLUG_PATTERN.test(repo)) {
             return `subject.repos[0] must be an owner/repo slug (got "${repo}").`;
         }
-        // Fan-out is CONSUMED here: N lanes each clone the SAME single repo into their own E2B
-        // desktop (per-lane worlds). The shared cua-lane cross-validation below enforces the
-        // lanes/count rules and the 16 cap; the single-repo rule above is unchanged.
+        // Fan-out is consumed here: N participants each clone the same single repo into their own
+        // E2B desktop (`per-lane-worlds`). The shared cua cross-validation below enforces the
+        // `lanes`/`count` rules and the 16 cap; the single-repo rule above is unchanged.
     }
     return null;
 }
 // local-tree route: packs and uploads the operator's own working tree, then serves it exactly
 // like a computer-use clone subject. The scripted-browser route has no packed-working-tree
-// mode, so e2b-desktop + a computer-use actor are the ONLY combination this source supports.
+// mode, so e2b-desktop + a computer-use actor are the only combination this source supports.
 // `subject.serve` is already required at parse time (parseSubject); the repos/clone rejection
 // also already happened there (local-tree never carries git slugs).
 function localTreeValidationReason(config) {
@@ -216,18 +216,18 @@ function localTreeValidationReason(config) {
     }
     return null;
 }
-// desktop-cli route: a computer-use participant studies a CLI/TUI the way a person does — at a
+// desktop-cli route: a computer-use participant studies a CLI/TUI the way a person does: at a
 // desktop, in a terminal window, by looking at it. The sibling of terminal-product, and the
-// distinction is the POPULATION, not the product: terminal-product sends an autonomous agent
-// through a pipe with stdin disabled, which is the honest way to study what an agent meets and
+// distinction is the population: terminal-product sends an autonomous agent
+// through a pipe with stdin disabled, which matches what an agent meets and
 // structurally cannot study an interactive surface. This route sends someone who can see it.
 //
-// Fail-closed on the pairing (invariant 6): a hosted desktop and a computer-use actor, because
+// Fail-closed on the pairing: a hosted desktop and a computer-use actor, because
 // "watch a person use a terminal" is not something the other substrates can do.
 /** A desktop-cli subject with no product to study. The computer-use planner checks this too. */
 export function desktopCliProductReason(config) {
     return config.subject.source === "desktop-cli" && config.subject.product?.name === undefined
-        ? "desktop-cli subjects need `subject.product.name` — the CLI the participant is being asked to use."
+        ? "A desktop-cli subject needs `subject.product.name`: the CLI the participant is asked to use."
         : null;
 }
 function desktopCliValidationReason(config) {
@@ -236,7 +236,7 @@ function desktopCliValidationReason(config) {
         return productReason;
     if (config.subject.source === "desktop-cli" && config.subject.product !== undefined) {
         if (config.execution?.target !== undefined && config.execution.target !== "e2b-desktop") {
-            return "desktop-cli subjects are studied at a hosted desktop — set `execution.target: e2b-desktop` or omit it.";
+            return "A desktop-cli subject runs on a hosted desktop. Set `execution.target: e2b-desktop` or omit it.";
         }
         if (!actorResolvesToComputerUse(config.actors[0]?.type ?? "")) {
             return "desktop-cli subjects need a registered computer-use actor: the participant reads the screen and types, which is what makes an interactive surface studiable at all.";
@@ -248,16 +248,16 @@ function desktopCliValidationReason(config) {
     }
     return null;
 }
-// terminal-product route: a real autonomous agent studies a CLI/product from PUBLIC surfaces
-// inside an E2B shell. Fail-closed (invariant 6 — a field that cannot act on this route is an
-// honest parse error): a registered terminal actor only, execution.target e2b-terminal or absent
-// (absent defaults to e2b-terminal — the only honest target for an in-sandbox agent), single
-// lane until fan-out lands.
+// terminal-product route: a real autonomous agent studies a CLI/product from public surfaces inside
+// an E2B shell. Fail-closed (claims match mechanism: a field that cannot act on this route is a
+// parse error): a registered terminal actor only, execution.target e2b-terminal or absent (absent
+// defaults to e2b-terminal, the only target where an in-sandbox agent runs), one participant until
+// fan-out lands.
 function terminalValidationReason(config) {
     if (config.subject.source === "terminal-product") {
         const type = config.actors[0]?.type ?? "";
         if (config.execution?.target !== undefined && config.execution.target !== "e2b-terminal") {
-            return "terminal-product subjects run the agent inside an E2B shell — set `execution.target: e2b-terminal` or omit it (absent means e2b-terminal); `local`/`e2b-desktop` are rejected.";
+            return "A terminal-product subject runs its agent in an E2B shell. Set `execution.target: e2b-terminal` or omit it; `local` and `e2b-desktop` are not supported.";
         }
         if (!actorResolvesToTerminal(type)) {
             return `actors[0].type must be a registered terminal actor for terminal-product subjects (one of: ${registeredTerminalActors().join(", ")}). Got "${type}".`;
@@ -267,8 +267,8 @@ function terminalValidationReason(config) {
         }
     }
     else if (config.execution?.target === "e2b-terminal") {
-        // e2b-terminal is the terminal-product substrate ONLY. Any other source declaring it is a
-        // mis-config — reject, never silently mishandle (mirrors app-url's e2b-desktop pairing rule).
+        // e2b-terminal is the terminal-product substrate only. Any other source declaring it is a
+        // mis-config: reject, never silently mishandle (mirrors app-url's e2b-desktop pairing rule).
         return "`execution.target: e2b-terminal` requires `subject.source: terminal-product` with a registered terminal actor.";
     }
     else if (actorResolvesToTerminal(config.actors[0]?.type)) {

package/dist/lab/config.js

@@ -1,64 +1,69 @@
-// humanish.lab.v2 — a lab is a COMPOSITION over code primitives, not a hardcoded kind.
+// humanish.lab.v2: a lab is a composition over code primitives. There is no hardcoded lab kind.
+// A humanish.study.v3 file is rewritten into this spelling first (parse/study-v3.ts), and then must
+// take the route it declares and set no field that route does not read.
 //
-// HONEST SCOPE (read before trusting field names): the engine routes by
-// subject.source × execution.target (disambiguated by the actor lane where both axes
+// Scope (read before trusting field names): the engine routes by
+// subject.source × execution.target (disambiguated by the actor's run kind where both axes
 // collide) and consumes a deliberately small set of fields:
 //   subject.source/repos/appUrl/serve/env/state/clone.{depth,fanout,keep}, actors[0].count,
 //   execution.target + execution.desktop.codexAppServer, scenario.mode,
 //   policies.redactRepos, defaults.open.
 // On the computer-use routes (app-url × e2b-desktop, and clone × e2b-desktop with a
-// computer-use actor), `actors[0].type` IS load-bearing: it must resolve to a registered
+// computer-use actor), `actors[0].type` selects the actor: it must resolve to a registered
 // computer-use actor, and that descriptor runs the session. Those routes also consume
 // actors[0].{mission,persona,laneFocus.instruction,model,reasoningEffort}, execution.timeoutMs,
 // execution.desktop.{browser,resolution,sandboxTimeoutMs}, and (clone)
 // subject.{serve,env,state,clone.depth}.
 // On the scripted-browser route (app-url × local-or-absent, or clone × e2b-desktop, with a
-// registered scripted-browser actor), `actors[0].type` is equally load-bearing, and the route
-// consumes scenario.ref (REQUIRED there — the committed scenario's browser steps ARE what the
+// registered scripted-browser actor), `actors[0].type` selects the actor too, and the route
+// consumes scenario.ref (required there, because the committed scenario's browser steps are what the
 // actor executes), actors[0].{persona,count}, and execution.timeoutMs. On the provisioned
 // clone slice it also consumes subject.{repos,serve,env,state,exposure,clone.depth} and
 // execution.desktop.template. actors[0].{mission,laneFocus,model} are inert on that route
 // because no model runs, and most execution.desktop.* fields remain forward-declared (device
-// presets belong to the cua route — scripted surfaces are the driver's own desktop/mobile
-// viewports where isMobile/DSF genuinely RENDER via playwright emulation).
-// On the other routes those fields remain FORWARD-DECLARED and NOT yet consumed —
+// presets belong to the computer-use route; scripted surfaces are the driver's own desktop/mobile
+// viewports where isMobile/DSF genuinely render via playwright emulation).
+// On the other routes those fields remain forward-declared and are not yet consumed:
 // parseLabConfig emits a warning listing any such field that is set, so `lab inspect` shows
 // the truth.
 //
-// NOTE on actors[0].count: it now carries ROUTE-SPECIFIC meanings — synthetic route: simCount;
+// NOTE on actors[0].count: it carries route-specific meanings. Preview route: simCount;
 // scripted-browser route: surface roster {1 = desktop, 2 = desktop + mobile}, default 1 (the
-// defaults-table single-lane row governs; count: 2 is the declared override); computer-use
-// E2B route: the HOMOGENEOUS fan-out lane count (N identical lanes, each its own E2B desktop),
-// capped at 16; the in-process/local-app cua route stays single lane (no E2B to fan out).
+// defaults-table single-participant row governs; count: 2 is the declared override); computer-use
+// E2B route: the homogeneous fan-out participant count (N identical participants, each its own E2B
+// desktop), capped at 16; the in-process/local-app computer-use route stays single-participant (no
+// E2B to fan out).
 //
-// NOTE on actors[0].lanes / actors[0].roster (computer-use E2B route, this slice): a
-// DIFFERENTIATED fan-out roster — each `{ id?, persona?, device?, instruction?, target? }` becomes one
-// independent E2B desktop (per-lane worlds, the default topology). `roster[]` is parser sugar for
+// NOTE on actors[0].lanes / actors[0].roster (computer-use E2B route): a
+// differentiated fan-out roster: each `{ id?, persona?, device?, instruction?, target? }` becomes one
+// independent E2B desktop (`per-lane-worlds`, the default topology). `roster[]` is parser sugar for
 // repeated groups and is normalized into `lanes[]` before the engine sees it. `lanes|roster` XOR
-// `count` (declare a differentiated roster OR a homogeneous count, never both); `lanes|roster`
-// XOR `actors[0].laneFocus` (per-lane `instruction` is the roster's steer); `lanes[].device` XOR
-// raw `execution.desktop.resolution`. `execution.concurrency` bounds in-flight lanes (default: the
-// lane count, every lane at once; env HUMANISH_CUA_MAX_CONCURRENCY may only LOWER it — invariant
-// 3). On every non-cua route normalized `lanes` are inert (warned). subject.clone.fanout is
-// REJECTED on the cua route. `lanes[].target` is app-url × computer-use ONLY: an absolute browser
-// URL this lane opens instead of `subject.appUrl`; it is the generic setup-produced-target
-// handoff, not a service topology primitive.
+// `count` (declare a differentiated roster or a homogeneous count, never both); `lanes|roster`
+// XOR `actors[0].laneFocus` (each entry's `instruction` is the roster's steer); `lanes[].device` XOR
+// raw `execution.desktop.resolution`. `execution.concurrency` bounds in-flight participants (default:
+// the participant count, all at once; env HUMANISH_CUA_MAX_CONCURRENCY may only lower it, per invariant
+// 3). On every non-computer-use route normalized `lanes` are inert (warned). subject.clone.fanout
+// is rejected on the computer-use route. `lanes[].target` is app-url × computer-use only: an
+// absolute browser URL this participant opens instead of `subject.appUrl`; it is the generic
+// setup-produced-target handoff, not a service topology primitive.
 //
-// There is deliberately NO v1 compatibility: v1 had zero real users. Breaking schema changes
-// bump the version honestly.
+// There is deliberately no v1 compatibility: v1 had zero real users. Breaking schema changes
+// bump the version.
 import { isLocalBrowserLab, localBrowserDefaults, localBrowserUnsupportedReason, } from "../substrates/local/runtime-config.js";
+import { isRecord } from "../run/type-guards.js";
 import { compositionReason } from "./composition-rules.js";
 import { findUnknownLabKey } from "./keys.js";
 import { parseActors, rosterOf } from "./parse/actors.js";
 import { parseComms, recipientParticipantId } from "./parse/comms.js";
 import { parseDefaults, parseExecution, parsePersonas, parsePolicies, parseReview, parseScenario, } from "./parse/execution.js";
+import { studySpelling, studyToV2 } from "./parse/study-v3.js";
 import { parseSubject } from "./parse/subject.js";
-import { invalid, isRecord, optionalStr, str } from "./parse/values.js";
-import { isComputerUseComposition, isSharedWorldComposition } from "./routing.js";
+import { invalid, optionalStr, str } from "./parse/values.js";
+import { isComputerUseComposition, isSharedWorldComposition, routeOf } from "./routing.js";
 import { declaredParticipantIds } from "./plan-participants.js";
-import { ID_PATTERN, LAB_CONFIG_SCHEMA, } from "./types.js";
+import { ID_PATTERN, LAB_CONFIG_SCHEMA, STUDY_SCHEMA, } from "./types.js";
 import { automaticAnalysisRouteReason, desktopMediaValidationReason, outputTokenLimitValidationReason, receivingEmailValidationReason, scenarioCapsValidationReason, taskProtocolValidationReason, } from "./validation.js";
-import { forwardDeclaredWarnings } from "./warnings.js";
+import { forwardDeclaredWarnings, inertFieldLabels } from "./warnings.js";
 /**
  * Validate a parsed YAML object into a LabConfig. Pure: the caller owns file IO. Structural
  * validation only. Fields the engine does not yet consume are accepted but reported in
@@ -68,9 +73,41 @@ export function parseLabConfig(raw) {
     if (!isRecord(raw)) {
         return invalid("Lab manifest must be a YAML object.");
     }
+    if (raw.schema === STUDY_SCHEMA)
+        return parseStudy(raw);
     if (raw.schema !== LAB_CONFIG_SCHEMA) {
-        return invalid(`Lab schema must be ${LAB_CONFIG_SCHEMA}.`);
+        return invalid(`Lab schema must be ${STUDY_SCHEMA} or ${LAB_CONFIG_SCHEMA}.`);
     }
+    return parseV2(raw);
+}
+/**
+ * A v3 study parses through the v2 parser, then must take the route it declares and set no field
+ * that route does not read. A v2 file gets those fields as a warning instead.
+ */
+function parseStudy(raw) {
+    const document = studyToV2(raw);
+    if (!document.ok)
+        return document;
+    const { route, v2, participantSource } = document.value;
+    const spell = (message) => studySpelling(message, route, participantSource);
+    const parsed = parseV2(v2);
+    if (!parsed.ok)
+        return invalid(spell(parsed.error.message));
+    const taken = routeOf(parsed.config);
+    if (taken !== route) {
+        return invalid(`This study declares route: ${route}, but its subject (source: ${parsed.config.subject.source}) and actor (type: ${parsed.config.actors[0]?.type}) take the ${taken} route. Change \`route\`, or change the subject or actor.`);
+    }
+    const inert = inertFieldLabels(parsed.config);
+    if (inert.length > 0) {
+        return invalid(spell(`route: ${route} does not read ${inert.join(", ")}. Remove ${inert.length === 1 ? "it" : "them"}.`));
+    }
+    return {
+        ok: true,
+        config: { ...parsed.config, schema: STUDY_SCHEMA },
+        warnings: parsed.warnings.map(spell),
+    };
+}
+function parseV2(raw) {
     const unknownKey = findUnknownLabKey(raw);
     if (unknownKey)
         return invalid(unknownKey);
@@ -148,11 +185,12 @@ export function parseLabConfig(raw) {
     const scenarioCapsReason = scenarioCapsValidationReason(config);
     if (scenarioCapsReason)
         return invalid(scenarioCapsReason);
-    // All-parallel default (#350): a multi-seat lab that does not declare execution.concurrency runs
-    // every seat at once; the declared field is a cap the author chose, never a mode. Independent
-    // computer-use lanes resolve that default from the final seat count when they plan, after any
-    // --count override, so the parser leaves it unset for them. A shared world's roster is fixed, so
-    // its default is filled here for the envelopes and warnings that read the parsed config.
+    // All-parallel default: a multi-participant study that does not declare execution.concurrency
+    // runs every participant at once; the declared field is a cap the author chose, never a mode.
+    // Independent computer-use participants resolve that default from the final participant count
+    // when they plan, after any --count override, so the parser leaves it unset for them. A shared
+    // world's roster is fixed, so its default is filled here for the envelopes and warnings that read
+    // the parsed config.
     {
         const participantCount = rosterOf(config.actors[0])?.length ?? config.actors[0]?.count ?? 1;
         if (participantCount > 1 &&
@@ -161,12 +199,12 @@ export function parseLabConfig(raw) {
             config.execution = { ...config.execution, concurrency: participantCount };
         }
     }
-    // Email that just works (#351): the funnel's ONLY handoff to an actor is the per-lane inbox
-    // instruction, gated on recipients[]. Guessed lane names broke a field run — recipients copied
-    // from a single-lane example matched nothing, so every actor was left inbox-blind with zero
-    // signal. Omitted recipients are therefore FILLED (one deterministic address per lane); a
-    // recipient naming an unknown lane is a hard error listing the real lane ids; declared
-    // recipients covering zero lanes are a hard error (a guaranteed-dead funnel).
+    // Email that just works: the funnel's only handoff to an actor is the per-participant
+    // inbox instruction, gated on recipients[]. Guessed participant ids broke a field run:
+    // recipients copied from a single-participant example matched nothing, so every actor was left inbox-blind with zero
+    // signal. Omitted recipients are therefore filled (one deterministic address per participant);
+    // a recipient naming an unknown participant is a hard error listing the real ids; declared
+    // recipients covering zero participants are a hard error (a guaranteed-dead funnel).
     const receivingReason = receivingEmailValidationReason(config);
     if (receivingReason)
         return invalid(receivingReason);
@@ -204,5 +242,9 @@ export function parseLabConfig(raw) {
         if (reason)
             return invalid(reason);
     }
-    return { ok: true, config: normalized, warnings: forwardDeclaredWarnings(normalized) };
+    return {
+        ok: true,
+        config: normalized,
+        warnings: forwardDeclaredWarnings(normalized),
+    };
 }

package/dist/lab/deprecated-fields.d.ts

@@ -0,0 +1,10 @@
+/** One deprecated field: what to read instead, and how to compute the old value. */
+export interface DeprecatedField {
+    readonly replacement: string;
+    readonly read: () => unknown;
+}
+/** Adds `fields` to `value` as warning getters and returns `value`. */
+export declare function withDeprecatedFields<T extends object>(value: T, owner: {
+    readonly name: string;
+    readonly code: `HUMANISH_${string}`;
+}, fields: Readonly<Record<string, DeprecatedField>>): T;

package/dist/lab/deprecated-fields.js

@@ -0,0 +1,24 @@
+// Deprecated fields on a value humanish hands to a caller. Each is a getter that warns once per
+// process when read. The getters are not enumerable, so a spread, `Object.assign`,
+// `JSON.stringify` or `structuredClone` of the value skips them and warns about no field the
+// caller never named; `"name" in value` still finds them. Core never reads them.
+const warned = new Set();
+/** Adds `fields` to `value` as warning getters and returns `value`. */
+export function withDeprecatedFields(value, owner, fields) {
+    return Object.defineProperties(value, Object.fromEntries(Object.entries(fields).map(([field, { replacement, read }]) => [
+        field,
+        {
+            enumerable: false,
+            get: () => {
+                warnOnce(`${owner.name}.${field}`, replacement, owner.code);
+                return read();
+            },
+        },
+    ])));
+}
+function warnOnce(name, replacement, code) {
+    if (warned.has(name))
+        return;
+    warned.add(name);
+    process.emitWarning(`${name} is deprecated and is removed in the next minor. Use ${replacement}.`, { type: "DeprecationWarning", code });
+}

package/dist/lab/device-presets.d.ts

@@ -4,9 +4,9 @@ export interface DevicePreset {
     width: number;
     /** Requested device height, used for the hosted physical screen. */
     height: number;
-    /** Mobile identity; enables emulation only when the hosted lane explicitly opts in. */
+    /** Mobile identity; enables emulation only when the hosted participant explicitly opts in. */
     isMobile: boolean;
-    /** Requested DPR; applied on hosted mobile lanes only with opt-in CDP emulation. */
+    /** Requested DPR; applied on hosted mobile participants only with opt-in CDP emulation. */
     deviceScaleFactor: number;
 }
 /**
@@ -55,7 +55,7 @@ export declare const DEVICE_PRESETS: {
 export type DevicePresetName = keyof typeof DEVICE_PRESETS;
 /**
  * Default device for a run that does not declare one. `desktop` (1440x950) is the median
- * first-run laptop screen — the in-house desktop default, within 10px of the 1440x960 dry-run
+ * first-run laptop screen, the in-house desktop default, within 10px of the 1440x960 dry-run
  * surface in src/run/dry-run.ts. `wide` (1920x1080), the most-common external monitor, is one
  * keystroke away (`execution.desktop.device: wide`) but is deliberately not the default,
  * because the median device a first-time user arrives on is a laptop, not a 1080p monitor.
@@ -67,22 +67,22 @@ export declare function isDevicePresetName(value: unknown): value is DevicePrese
 /** Resolve a preset name (or undefined) to its preset, falling back to the default. */
 export declare function resolveDevicePreset(name: DevicePresetName | undefined): DevicePreset;
 /**
- * The narrowest browser WINDOW Chrome/Chromium will render on the E2B desktop. Chrome refuses to
+ * The narrowest browser window Chrome/Chromium will render on the E2B desktop. Chrome refuses to
  * make its window narrower than this (~500 CSS px observed: a 414-wide X screen produced a 500-wide
- * window that OVERFLOWED it, clipping the right edge of the page off-screen). So the physically
- * RENDERED screen width is floored here: a sub-500 mobile preset (mobile 414, small-mobile 360,
- * narrow-mobile 320) gets a 500-wide screen the window fits exactly — no clip. The device PRESET keeps
+ * window that overflowed it, clipping the right edge of the page off-screen). So the physically
+ * rendered screen width is floored here: a sub-500 mobile preset (mobile 414, small-mobile 360,
+ * narrow-mobile 320) gets a 500-wide screen the window fits exactly, with no clip. The device preset keeps
  * its true identity (isMobile, nominal width) for the persona prompt + metadata; only the rendered
  * screen is floored. True sub-500 CSS-viewport rendering (page laid out at 414 regardless of window
- * width, via CDP device-metric emulation) is the separate #221 upgrade.
+ * width, via CDP device-metric emulation) is the separate mobileEmulation option.
  */
 export declare const MIN_DESKTOP_RENDER_WIDTH = 500;
-/** Floor a screen resolution's WIDTH to what Chrome can actually render (see MIN_DESKTOP_RENDER_WIDTH). */
+/** Floor a screen resolution's width to what Chrome can actually render (see MIN_DESKTOP_RENDER_WIDTH). */
 export declare function floorRenderResolution(resolution: readonly [number, number]): [number, number];
 /**
  * Resolve a participant's device + rendered resolution (most-specific wins, exactly as the
  * single-participant path always has): a raw execution.desktop.resolution escape hatch (only legal
- * when no roster entry sets a device — XOR enforced at parse) → the participant's named device → the run-wide
+ * when no roster entry sets a device; XOR enforced at parse) → the participant's named device → the run-wide
  * execution.desktop.device → the default preset. A raw resolution is an unnamed custom desktop
  * (non-mobile, DSF 1): we never claim a named preset's mobile/DPR for hand-set geometry. The rendered
  * `resolution` is floored to MIN_DESKTOP_RENDER_WIDTH so the browser window fits its X screen (no clip);