humanish 0.107.0 → 0.108.0

package/dist/lab/validation.js

@@ -2,28 +2,29 @@ import { isMaxOutputTokens } from "../actors/output-token-limit.js";
 import { PARTICIPANT_ID_MAX_CHARS, PARTICIPANT_ID_PATTERN, focusOf, rosterOf, } from "./parse/actors.js";
 import { isHttpUrl, isLoopbackUrl } from "./parse/subject.js";
 import { declaredTargets } from "./plan-participants.js";
-import { actorResolvesToComputerUse, cuaLaneCount, MAX_CUA_LANES, registeredComputerUseActors, resolveSeatUrl, isComputerUseComposition, isScriptedBrowserComposition, isSharedWorldComposition, isTerminalProductComposition, } from "./routing.js";
+import { actorResolvesToComputerUse, computerUseParticipantCount, MAX_COMPUTER_USE_PARTICIPANTS, registeredComputerUseActors, resolveEntryUrl, isComputerUseComposition, isScriptedBrowserComposition, isSharedWorldComposition, isTerminalProductComposition, } from "./routing.js";
 /**
  * Cross-validate the computer-use fan-out declaration (`per-lane-worlds`). Returns the failure
- * message, or null when valid. Enforced at parse and re-enforced in the engine (runCuaActorLab
- * is itself exported npm surface). Structural roster shape (id/device validity, id uniqueness) is
- * already checked in parseLanes; this is the route-scoped XOR/cap/policy layer.
+ * message, or null when valid. The parser enforces it, and runLab checks it again for a config
+ * that skipped the parser. It runs rosterStructuralValidationReason (id and device
+ * validity, unique ids) first, then the route-scoped XOR, cap and policy checks.
  */
-export function cuaLaneValidationReason(config) {
+export function computerUseValidationReason(config) {
     const actor = config.actors[0];
     const roster = rosterOf(actor);
     const structuralReason = rosterStructuralValidationReason(config);
     if (structuralReason) {
         return structuralReason;
     }
-    // clone.fanout is a declared behavior change: rejected on the cua route (was inert-warned).
-    // Fan-out is declared via `actors[0].count` or `actors[0].lanes`; subject.clone.fanout never applied here.
+    // clone.fanout is a declared behavior change: rejected on the computer-use route (was
+    // inert-warned). Fan-out is declared via `actors[0].count` or `actors[0].lanes`;
+    // subject.clone.fanout never applied here.
     if (config.subject.clone?.fanout !== undefined) {
         return "`subject.clone.fanout` is not used on the computer-use route: declare fan-out with actors[0].count (homogeneous) or actors[0].lanes (a roster of participants). (No current route reads clone.fanout.)";
     }
     if (roster !== undefined) {
         if (actor?.count !== undefined) {
-            return "Declare EITHER actors[0].count (a homogeneous participant count) OR actors[0].lanes (a differentiated roster), not both.";
+            return "Set either `actors[0].count` (identical participants) or `actors[0].lanes` (a roster of distinct participants), not both.";
         }
         if (focusOf(actor) !== undefined) {
             return "actors[0].laneFocus and actors[0].lanes are mutually exclusive: each roster entry's `instruction` is the fan-out steer; laneFocus is the steer for a single participant.";
@@ -35,7 +36,7 @@ export function cuaLaneValidationReason(config) {
         const targeted = roster.filter((entry) => entry.target !== undefined);
         if (targeted.length > 0) {
             if (config.subject.source !== "app-url") {
-                return "actors[0].lanes[].target is supported only on app-url computer-use labs — clone/shared-world/local-app routes provision or own their entry URL by mechanism.";
+                return "`actors[0].lanes[].target` works only on app-url computer-use studies. Clone, shared-world and local-app studies set each participant's entry URL themselves; remove `target`.";
             }
             if (roster.some((entry) => entry.entry !== undefined)) {
                 return "actors[0].lanes[].target and actors[0].lanes[].entry are mutually exclusive: target is an app-url fan-out browser URL; entry is a shared-world same-origin participant path.";
@@ -45,21 +46,21 @@ export function cuaLaneValidationReason(config) {
             }
         }
     }
-    const participantCount = cuaLaneCount(config);
-    if (participantCount > MAX_CUA_LANES) {
-        return `Computer-use fan-out is capped at ${MAX_CUA_LANES} participants (declared ${participantCount}); N concurrent paid desktops is real spend, and there is no override above the cap this slice.`;
+    const participantCount = computerUseParticipantCount(config);
+    if (participantCount > MAX_COMPUTER_USE_PARTICIPANTS) {
+        return `A computer-use study runs at most ${MAX_COMPUTER_USE_PARTICIPANTS} participants, and this one declares ${participantCount}. Each participant is a paid desktop and they all run at once, so no setting raises the cap; split the roster across studies.`;
     }
     // Public targets fan out into N independent worlds driving the same public app, which is an
     // ambiguous shared-world-ish shape, not a per-participant target swarm. Permit N>1 public runs only
     // when every roster entry declares its own target, making the adapter-owned topology explicit. But when
     // `subject.topology: shared-world` is also declared, N participants against one public target is the
-    // external-public shared-world topology (#164 phase 2), so route it there (a real public deployment
+    // external-public shared-world topology, so route it there (a real public deployment
     // as the shared plane) instead of refusing; externalPublicSharedWorldValidationReason then applies.
     if (participantCount > 1 &&
         config.policies?.allowPublicTargets === true &&
         declaredTargets(config).length === 0 &&
         config.subject.topology !== "shared-world") {
-        return "policies.allowPublicTargets cannot be combined with fan-out to more than one participant (N>1): N participants against one declared public target is the SHARED-WORLD topology (layer 7, #164), not `per-lane-worlds`. Declare `subject.topology: shared-world` to run the external-public shared-world route, fan out against a loopback/provisioned subject, or run a single public-target participant.";
+        return "`policies.allowPublicTargets` with more than one participant sends them all to one public app, which is a shared world. Set `subject.topology: shared-world` to run them together there, give each `actors[0].lanes[]` entry its own `target`, or run one participant.";
     }
     return null;
 }
@@ -96,10 +97,10 @@ function rosterStructuralValidationReason(config) {
     return null;
 }
 /**
- * Cross-validate a `topology: shared-world` declaration (#164). Returns the failure message, or
+ * Cross-validate a `topology: shared-world` declaration. Returns the failure message, or
  * null when the one shared-world route can run it: the external-public checks for an app-url
  * subject, the provisioned checks otherwise. Enforced at parse and again by the route, since
- * runConcurrentSharedWorld is exported.
+ * runLab takes a config that skipped the parser.
  */
 export function sharedWorldValidationReason(config) {
     return config.subject.source === "app-url"
@@ -119,7 +120,7 @@ function provisionedSharedWorldStructureReason(config) {
         return structuralReason;
     }
     if (config.subject.source !== "clone" && config.subject.source !== "local-tree") {
-        return "`subject.topology: shared-world` requires `subject.source: clone` or `subject.source: local-tree` - the shared world is ONE provisioned, served, seeded plane (#164).";
+        return "`subject.topology: shared-world` needs `subject.source: clone` or `local-tree`, which humanish serves as one seeded app every participant uses, or `app-url` for a public deployment you own.";
     }
     if (config.execution?.target !== "e2b-desktop") {
         return "`subject.topology: shared-world` requires `execution.target: e2b-desktop`: the role participants drive hosted desktop browsers against one in-sandbox app.";
@@ -129,17 +130,17 @@ function provisionedSharedWorldStructureReason(config) {
     }
     const serve = config.subject.serve;
     if (!serve) {
-        return "`subject.topology: shared-world` requires `subject.serve` (start + url) — the lab serves ONE shared app in-sandbox that every role drives.";
+        return "`subject.topology: shared-world` needs `subject.serve` (start and url): humanish starts one copy of the app in the sandbox, and every participant uses it.";
     }
     const roster = rosterOf(config.actors[0]);
     if (!roster || roster.length < 2) {
-        return "`subject.topology: shared-world` requires an `actors[0].lanes` roster of at least 2 roles (the roster IS the role roster: declare ≥2 participants; a single-role shared world proves no interaction).";
+        return "`subject.topology: shared-world` needs an `actors[0].lanes` roster of at least 2 participants: with one participant there is nobody to interact with.";
     }
     if (!config.subject.state?.checkpoint || config.subject.state.checkpoint.length === 0) {
-        return "`subject.topology: shared-world` requires `subject.state.checkpoint` (≥1 read-only digest probe) — the checkpoint series is how the run shows the shared state changing; without it the run cannot show that participants changed the shared app.";
+        return "`subject.topology: shared-world` needs at least one read-only `subject.state.checkpoint` probe: the checkpoints are how the run shows that participants changed the shared app.";
     }
     for (const entry of roster) {
-        if (entry.entry !== undefined && resolveSeatUrl(serve.url, entry.entry) === null) {
+        if (entry.entry !== undefined && resolveEntryUrl(serve.url, entry.entry) === null) {
             return `actors[0].lanes role "${entry.id ?? "(unnamed)"}".entry must resolve same-origin (loopback) with subject.serve.url (${serve.url}); got "${entry.entry}".`;
         }
     }
@@ -198,7 +199,7 @@ export function receivingEmailValidationReason(config) {
     }
     return undefined;
 }
-/** Refuse task declarations that the selected execution path would discard (#737).
+/** Refuse task declarations that the selected execution path would discard.
  * Direct runners pass their actual support rather than trusting the config's dispatch shape. */
 export function taskProtocolValidationReason(config, supportsTasks = isComputerUseComposition(config) && !isSharedWorldComposition(config)) {
     for (const [index, actor] of config.actors.entries()) {
@@ -263,7 +264,8 @@ export function outputTokenLimitValidationReason(config) {
  * Shared-world participants share one live app, so at least two must be live at once. The
  * sequential shared-world route (`execution.concurrency: 1`) was removed in 0.106.0; the parser
  * fills an omitted concurrency with the participant count. Both callers check it after their
- * two-participant roster floor, so a one-seat roster gets the roster refusal, never this one.
+ * two-participant roster floor, so a one-participant roster gets the roster refusal, never this
+ * one.
  */
 function sharedWorldConcurrencyReason(config) {
     // Direct library callers skip the parser, so an omitted value defaults here exactly as the
@@ -275,12 +277,12 @@ function sharedWorldConcurrencyReason(config) {
     return `shared-world labs need \`execution.concurrency\` of at least 2 (got ${concurrency}). Sequential shared-world turns (concurrency 1) were removed in 0.106.0: omit execution.concurrency to run every participant at once, or set it to 2 or more. A provisioned subject also needs \`subject.exposure: synthetic\` and a \`serve.start\` that binds 0.0.0.0.`;
 }
 /**
- * Cross-validate a concurrent shared-world declaration (#164 phase 2). Returns the failure message,
+ * Cross-validate a concurrent shared-world declaration. Returns the failure message,
  * or null when valid. Includes the base shared-world checks plus the concurrent extras: a synthetic
  * subject attestation, a 0.0.0.0 serve bind (getHost only routes to a port bound on
  * all interfaces), and no `subject.clone.keep`/`subject.localTree.keep` (either would
- * orphan actor sandboxes). Enforced at parse and re-enforced in the engine (runConcurrentSharedWorld
- * is exported npm surface).
+ * orphan actor sandboxes). Enforced at parse and re-enforced in the engine (runLab
+ * takes a config that skipped the parser).
  */
 export function concurrentSharedWorldValidationReason(config) {
     const base = provisionedSharedWorldStructureReason(config);
@@ -291,11 +293,11 @@ export function concurrentSharedWorldValidationReason(config) {
     if (sharedWorldConcurrency)
         return sharedWorldConcurrency;
     if (config.subject.exposure !== "synthetic") {
-        return "the concurrent shared-world route requires `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 (no real/external data behind a getHost URL).";
+        return "A shared-world 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 and seeded.";
     }
     const serve = config.subject.serve;
     if (!serve || !serve.start.includes("0.0.0.0")) {
-        return "the concurrent shared-world route requires `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; a loopback-only bind 502s. (The readiness probe stays loopback.)";
+        return "A shared-world 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, and a loopback-only server answers 502. The readiness probe still uses loopback.";
     }
     if (config.subject.clone?.keep === true || config.subject.localTree?.keep === true) {
         const keepField = config.subject.clone?.keep === true ? "subject.clone.keep" : "subject.localTree.keep";
@@ -304,15 +306,15 @@ export function concurrentSharedWorldValidationReason(config) {
     return null;
 }
 /**
- * Cross-validate the external-public shared-world declaration (#164 phase 2): a real public
+ * Cross-validate the external-public shared-world declaration: a real public
  * deployment used directly as the shared plane (no getHost, no clone, no subject sandbox, no seed).
  * The counterpart of concurrentSharedWorldValidationReason for a plane the harness does not own:
  * it rejects every provisioned-subject field (serve/state.seed/state.checkpoint/exposure/clone/repos
- * are inert with no sandbox, so they fail closed per invariant 6), and requires a
+ * are inert with no sandbox, so they fail closed), and requires a
  * non-loopback appUrl + allowPublicTargets + the operator-ownership attestation subject.publicTarget +
  * concurrency >= 2 + an actors[0].lanes roster of ≥2 with exactly one host participant. The getHost synthetic
  * gate is deliberately unreachable here (there is no internet-reachable harness-owned URL to attest).
- * Enforced at parse and re-enforced in the engine (runConcurrentSharedWorld is exported npm surface).
+ * Enforced at parse and re-enforced in the engine (runLab takes a config that skipped the parser).
  */
 export function externalPublicSharedWorldValidationReason(config) {
     const structuralReason = rosterStructuralValidationReason(config);
@@ -320,7 +322,7 @@ export function externalPublicSharedWorldValidationReason(config) {
         return structuralReason;
     }
     if (config.subject.source !== "app-url") {
-        return "the external-public shared-world route requires `subject.source: app-url` — a real public deployment is used directly as the shared plane (no clone, no provisioned subject).";
+        return "An external-public shared-world study needs `subject.source: app-url`: the participants share a public deployment you already run, so there is nothing to clone or serve.";
     }
     if (config.execution?.target !== "e2b-desktop") {
         return "the external-public shared-world route requires `execution.target: e2b-desktop`: the role participants drive hosted desktop browsers against the one public deployment.";
@@ -336,40 +338,40 @@ export function externalPublicSharedWorldValidationReason(config) {
     if (sharedWorldConcurrency)
         return sharedWorldConcurrency;
     if (config.policies?.allowPublicTargets !== true) {
-        return "the external-public shared-world route requires `policies.allowPublicTargets: true` — the shared plane is a real non-loopback public deployment.";
+        return "An external-public shared-world study needs `policies.allowPublicTargets: true`, because the participants drive a public deployment.";
     }
     const appUrl = config.subject.appUrl ?? "";
     if (!isHttpUrl(appUrl) || isLoopbackUrl(appUrl)) {
-        return "the external-public shared-world route requires a non-loopback http(s) `subject.appUrl` — a loopback URL is not a shared public plane (use the getHost provisioned route for a local subject).";
+        return "An external-public shared-world study needs a public http(s) `subject.appUrl`, not a loopback URL. For an app you run locally, use a clone or local-tree subject, which humanish serves itself.";
     }
-    // The operator-ownership attestation (the honest analog of exposure: synthetic — you cannot claim
+    // The operator-ownership attestation (the counterpart of exposure: synthetic; you cannot claim
     // synthetic on a real site, but you must attest you own/operate it). Author-trust; unverifiable.
     if (config.subject.publicTarget?.authorized !== true) {
-        return "the external-public shared-world route requires `subject.publicTarget: { owner, authorized: true }` — you must attest you own/operate the public deployment used as the shared plane (author-trust; the harness cannot verify ownership).";
+        return "An external-public shared-world study needs `subject.publicTarget: { owner, authorized: true }` to declare that you own or operate the public deployment. humanish cannot check ownership, so the study states it.";
     }
     // No provisioned-subject field is allowed: with no sandbox they cannot act, so they are rejected
-    // with a precise reason, never silently ignored (invariant 6). exposure: synthetic in particular
+    // with a precise reason, never silently ignored. exposure: synthetic in particular
     // would be a false claim on a real site (the harness neither provisioned nor exposed it).
     if (config.subject.exposure !== undefined) {
-        return "`subject.exposure: synthetic` is forbidden on the external-public shared-world route — you cannot attest a real public deployment is synthetic seeded data; use `subject.publicTarget` to attest ownership instead.";
+        return "`subject.exposure: synthetic` does not apply to an external-public shared-world study: a real public deployment is not seeded synthetic data. Declare ownership with `subject.publicTarget` instead.";
     }
     if (config.subject.serve !== undefined) {
-        return "`subject.serve` is forbidden on the external-public shared-world route — the harness does not serve the plane (it is an already-deployed public app); there is no in-sandbox serve to run.";
+        return "`subject.serve` does not apply to an external-public shared-world study: the app is already deployed, so humanish serves nothing. Remove `subject.serve`.";
     }
     if (config.subject.state?.seed !== undefined ||
         config.subject.state?.checkpoint !== undefined ||
         config.subject.state !== undefined) {
-        return "`subject.state` (seed/checkpoint/external) is forbidden on the external-public shared-world route — the harness neither seeds nor snapshots the plane (no in-sandbox filesystem to digest); no authoritative shared-state proof is possible on this class.";
+        return "`subject.state` (seed, checkpoint or external) does not apply to an external-public shared-world study: humanish cannot seed or read a deployment it does not run. Remove `subject.state`.";
     }
     if (config.subject.clone !== undefined || config.subject.repos !== undefined) {
-        return "`subject.clone`/`subject.repos` are forbidden on the external-public shared-world route — nothing is cloned; the public deployment IS the plane.";
+        return "`subject.clone` and `subject.repos` do not apply to an external-public shared-world study: the participants use the public deployment, so nothing is cloned. Remove them.";
     }
     if (roster.some((entry) => entry.entry !== undefined)) {
         return "`actors[0].lanes[].entry` (the loopback same-origin participant path) is forbidden on the external-public shared-world route: there is no harness-served serve.url to resolve it against; participants open the public appUrl and reach the shared session through the real UI.";
     }
     const hostEntries = roster.filter((entry) => entry.host === true);
     if (hostEntries.length !== 1) {
-        return `the external-public shared-world route requires EXACTLY ONE \`host: true\` participant (the designated host that creates the shared session; got ${hostEntries.length}). The other ≥1 participants are followers that join it.`;
+        return `An external-public shared-world study needs exactly one \`host: true\` participant, the one who creates the shared session, and this study has ${hostEntries.length}. Every other participant joins that session.`;
     }
     return null;
 }

package/dist/lab/warnings.d.ts

@@ -1,2 +1,12 @@
 import type { LabConfig } from "./types.js";
+/**
+ * The fields a config sets that its route does not read, each as `field` or `field (reason)`. A v2
+ * file gets them as one warning; a v3 study is refused for any of them.
+ */
+export declare function inertFieldLabels(config: LabConfig): string[];
+/**
+ * The same fields as `inertFieldLabels`, as paths without their reasons, such as
+ * `actors[0].lanes[].entry` or `execution.timeoutMs`. `humanish migrate` drops each one.
+ */
+export declare function inertFieldPaths(config: LabConfig): string[];
 export declare function forwardDeclaredWarnings(config: LabConfig): string[];

package/dist/lab/warnings.js

@@ -13,13 +13,13 @@ const otherRoute = (routes) => !promptRoute(routes) && !routes.scripted;
 /** Rows for each actor, reported as `actors[<index>].<field>`, in this order per actor. */
 const ACTOR_ROWS = [
     // Shared-world-only fields on the roster: a participant's `entry` is inert anywhere else
-    // (invariant 6).
+    // (claims match mechanism).
     {
         field: "lanes[].entry",
         reason: "the per-participant loopback entry is a shared-world capability; needs subject.topology: shared-world",
         applies: (actor, routes) => Boolean(rosterOf(actor)?.some((entry) => entry.entry !== undefined)) && !routes.shared,
     },
-    // The host-seat marker acts only on the external-public shared-world route; inert elsewhere.
+    // The host marker acts only on the external-public shared-world route; inert elsewhere.
     {
         field: "lanes[].host",
         reason: "the designated host-participant marker; needs the external-public shared-world route: app-url × topology shared-world × allowPublicTargets",
@@ -35,7 +35,7 @@ const ACTOR_ROWS = [
     },
     {
         field: "lanes",
-        reason: "fan-out is a computer-use route capability; terminal fan-out is a later slice",
+        reason: "only the computer-use route runs more than one participant",
         applies: (actor, routes) => routes.terminal && Boolean(rosterOf(actor)),
     },
     {
@@ -69,7 +69,7 @@ const ACTOR_ROWS = [
     { field: "lanes", applies: (actor, routes) => otherRoute(routes) && Boolean(rosterOf(actor)) },
 ];
 const TERMINAL_ONLY = "needs subject.source: terminal-product + a registered terminal actor";
-const RESERVED = "reserved for a later slice; not yet consumed";
+const RESERVED = "reserved; no route reads it yet";
 /** Rows for the rest of the config, reported after the actor rows, in this order. */
 const CONFIG_ROWS = [
     // The computer-use routes consume (clone) subject.{serve,env,state,clone.depth}, and so does the
@@ -90,8 +90,9 @@ const CONFIG_ROWS = [
         field: "subject.state",
         applies: (config, routes) => Boolean(config.subject.state) && !routes.cua && !routes.scripted,
     },
-    // topology + checkpoint act only on the shared-world route (#164); a set-but-unconsumed value
-    // (incl. an explicit per-lane-worlds, which the cua route already is by mechanism) warns inert.
+    // topology + checkpoint act only on the shared-world route; a set-but-unconsumed value
+    // (incl. an explicit per-lane-worlds, which the computer-use route already is by mechanism) warns
+    // inert.
     {
         field: "subject.topology",
         reason: "drives behavior only on the shared-world route; needs subject.topology: shared-world + clone × e2b-desktop × a computer-use actor + a roster of ≥2 participants",
@@ -113,7 +114,7 @@ const CONFIG_ROWS = [
     // getHost-exposed plane) and on scripted clones; inert elsewhere.
     {
         field: "subject.exposure",
-        reason: "the synthetic-subject attestation for a getHost-exposed plane; needs shared-world or clone × e2b-desktop × scripted-browser",
+        reason: "the statement that a subject served on a public sandbox URL holds only synthetic data; needs shared-world or clone × e2b-desktop × scripted-browser",
         applies: (config, routes) => config.subject.exposure !== undefined &&
             !routes.shared &&
             !(routes.scripted && config.subject.source === "clone"),
@@ -121,10 +122,10 @@ const CONFIG_ROWS = [
     // comms.email drives the in-sandbox email/SMS catch, which needs a subject sandbox that humanish
     // provisions (clone or local-tree) so it holds a handle to host the catch. On an app-url /
     // operator-provided subject there is no such handle, so a declared comms block would silently
-    // collect nothing — a false green. Warn at parse time (fires on inspect + dry-run too).
+    // collect nothing, a false green. Warn at parse time (fires on inspect + dry-run too).
     {
         field: "comms.email",
-        reason: "the in-sandbox email/SMS catch needs a harness-provisioned subject to host it — subject.source: clone or local-tree; on an app-url or operator-provided subject humanish holds no sandbox handle. Declare `comms.email.external` to run the catch yourself: humanish then points the persona at your inbox, drains your catch, and writes the same evidence — see #328",
+        reason: "the email catch runs in a sandbox humanish provisions, which needs `subject.source: clone` or `local-tree`, and an app-url subject has none. To use email here, run the catch yourself with `humanish comms catch` and declare `comms.email.external`: humanish then points each persona at your inbox, reads your catch and records the same evidence",
         applies: (config) => config.comms?.email?.kind === "fake" &&
             config.comms.email.external === undefined &&
             config.subject.source !== "clone" &&
@@ -139,9 +140,9 @@ const CONFIG_ROWS = [
         applies: (config) => Boolean(config.comms?.email?.external) &&
             (config.subject.source === "clone" || config.subject.source === "local-tree"),
     },
-    // clone.keep is consumed on the cua route (honored on failure: the sandbox is left up to debug
-    // a failed install/boot; otherwise always killed). clone.fanout is rejected on the cua route
-    // (a hard parse error above), so it can never reach this warning list there.
+    // clone.keep is consumed on the computer-use route (honored on failure: the sandbox is left up to
+    // debug a failed install/boot; otherwise always killed). clone.fanout is rejected on the
+    // computer-use route (a hard parse error above), so it can never reach this warning list there.
     {
         field: "execution.timeoutMs",
         applies: (config, routes) => !routes.cua &&
@@ -153,23 +154,24 @@ const CONFIG_ROWS = [
         field: "execution.completionTimeoutMs",
         applies: (config) => config.execution?.completionTimeoutMs !== undefined,
     },
-    // execution.concurrency is consumed on the cua route (it bounds in-flight fan-out participants);
-    // inert (warned) everywhere else.
+    // execution.concurrency is consumed on the computer-use route (it bounds in-flight fan-out
+    // participants); inert (warned) everywhere else.
     {
         field: "execution.concurrency",
         applies: (config, routes) => config.execution?.concurrency !== undefined && !routes.cua,
     },
-    // execution.caps is consumed on the cua route (maxUsd is the fail-closed spend abort); inert
-    // (warned) everywhere else so a misplaced budget field is never trusted to cap a route it cannot.
+    // execution.caps is consumed on the computer-use route (maxUsd is the fail-closed spend abort);
+    // inert (warned) everywhere else so a misplaced budget field is never trusted to cap a route it
+    // cannot.
     {
         field: "execution.caps",
-        reason: "the fail-closed spend abort is a computer-use route capability; needs a computer-use actor on e2b-desktop",
+        reason: "only the computer-use route enforces it, with a computer-use actor on e2b-desktop",
         applies: (config, routes) => Boolean(config.execution?.caps) && !routes.cua,
     },
     // terminal-product consumes subject.product, scenario.caps, execution.{terminal,runtimeAuth}:
     // dry-run records the contract; live execution enforces caps and command-scoped auth. On every
     // other route they are inert and must warn so a
-    // misplaced safety/budget field is never trusted to do something it cannot (invariant 6).
+    // misplaced safety/budget field is never trusted to do something it cannot.
     {
         field: "subject.product",
         reason: "needs subject.source: terminal-product or desktop-cli with the matching actor",
@@ -229,9 +231,9 @@ const CONFIG_ROWS = [
         applies: (config, routes) => !routes.cua && config.execution?.desktop?.sandboxTimeoutMs !== undefined,
     },
     // execution.desktop.template (the custom E2B desktop image) is consumed only where a desktop is
-    // actually created via Sandbox.create — the e2b-desktop computer-use routes (cua/shared-world/
-    // concurrent). It is inert on every other route (incl. the in-process local-app cua route, which
-    // creates no desktop): warn so an unconsumed template is never silently ignored (invariant 6).
+    // actually created via Sandbox.create: the e2b-desktop computer-use routes (cua/shared-world/
+    // concurrent). It is inert on every other route (incl. the in-process local-app computer-use
+    // route, which creates no desktop): warn so an unconsumed template is never silently ignored.
     {
         field: "execution.desktop.template",
         reason: "the custom E2B desktop image is consumed only on execution.target: e2b-desktop computer-use routes that create a desktop; needs a computer-use actor on e2b-desktop",
@@ -251,8 +253,8 @@ const CONFIG_ROWS = [
         applies: (config, routes) => Boolean(config.scenario?.ref) && !routes.scripted,
     },
     { field: "scenario.inline", applies: (config) => Boolean(config.scenario?.inline) },
-    // review.{scoring,milestones,vocabulary} stay forward-declared (reserved for #319) on every route.
-    // review.scorer (#316) is consumed (loaded + wired, or fail-closed at load) on every scorer-capable
+    // review.{scoring,milestones,vocabulary} stay forward-declared on every route.
+    // review.scorer is consumed (loaded + wired, or fail-closed at load) on every scorer-capable
     // route, so it does not warn there; on the scripted-browser route the actor carries no scorer seam,
     // so a declared scorer is flagged inert (the run also fails closed at load).
     {
@@ -297,9 +299,11 @@ function rowLabel(row, prefix = "") {
         ? `${prefix}${row.field}`
         : `${prefix}${row.field} (${row.reason})`;
 }
-// Report fields that are present but not yet consumed by the engine, so a user never trusts a
-// setting that silently does nothing. Keeps the schema forward-correct and honest.
-export function forwardDeclaredWarnings(config) {
+/**
+ * The fields a config sets that its route does not read, each as `field` or `field (reason)`. A v2
+ * file gets them as one warning; a v3 study is refused for any of them.
+ */
+export function inertFieldLabels(config) {
     const routes = routesOf(config);
     const inert = [];
     for (const [index, actor] of config.actors.entries()) {
@@ -310,14 +314,38 @@ export function forwardDeclaredWarnings(config) {
     for (const row of CONFIG_ROWS)
         if (row.applies(config, routes))
             inert.push(rowLabel(row));
+    return inert;
+}
+/**
+ * The same fields as `inertFieldLabels`, as paths without their reasons, such as
+ * `actors[0].lanes[].entry` or `execution.timeoutMs`. `humanish migrate` drops each one.
+ */
+export function inertFieldPaths(config) {
+    const routes = routesOf(config);
+    const paths = [];
+    for (const [index, actor] of config.actors.entries()) {
+        for (const row of ACTOR_ROWS)
+            if (row.applies(actor, routes))
+                paths.push(`actors[${index}].${row.field}`);
+    }
+    for (const row of CONFIG_ROWS)
+        if (row.applies(config, routes))
+            paths.push(row.field);
+    return paths;
+}
+// Report fields that are present but not yet consumed by the engine, so a user never trusts a
+// setting that silently does nothing.
+export function forwardDeclaredWarnings(config) {
+    const routes = routesOf(config);
+    const inert = inertFieldLabels(config);
     const warnings = inert.length === 0
         ? []
         : [
-            `Forward-declared fields are set but not yet consumed by the engine (planned for a later slice): ${inert.join(", ")}.`,
+            `These fields are set, but no route reads them yet, so they have no effect: ${inert.join(", ")}.`,
         ];
-    // A declared cap below the seat count is legal but loud: the roster promises N live actors and
-    // the cap delivers waves of M. Say so up front (inspect + dry-run + run) — a green run in waves
-    // is otherwise indistinguishable from the all-live run the author meant (#350).
+    // A declared cap below the participant count is legal but loud: the roster promises N live actors
+    // and the cap delivers waves of M. Say so up front (inspect + dry-run + run): a green run in
+    // waves is otherwise indistinguishable from the all-live run the author meant.
     {
         const participantCount = rosterOf(config.actors[0])?.length ?? config.actors[0]?.count ?? 1;
         const cap = config.execution?.concurrency;
@@ -325,14 +353,14 @@ export function forwardDeclaredWarnings(config) {
             warnings.push(`execution.concurrency ${cap} caps a ${participantCount}-participant roster: participants run in waves of ${cap}, never all live at once. Remove execution.concurrency (the default runs all ${participantCount} participants simultaneously) or set it to ${participantCount}; declare a lower cap only to bound simultaneous paid desktops.`);
         }
     }
-    // Partial email coverage is legal but loud (#351): a participant without an addressed recipient never
-    // hears an inbox exists, so an email-gated flow on that seat dead-ends by construction.
+    // Partial email coverage is legal but loud: a participant without an addressed recipient never
+    // hears an inbox exists, so an email-gated flow on that participant dead-ends by construction.
     if (routes.cua && config.comms?.email?.recipients) {
         const participantIds = declaredParticipantIds(config);
         const covered = new Set(addressedRecipients(config.comms.email).map((recipient) => recipient.participantId));
         const uncovered = participantIds.filter((id) => !covered.has(id));
         if (covered.size > 0 && uncovered.length > 0 && participantIds.length > 1) {
-            warnings.push(`comms.email covers ${covered.size} of ${participantIds.length} participants; the uncovered participant(s) get no inbox and are never told one exists: ${uncovered.join(", ")}. Add addressed recipients for them if their flows need email.`);
+            warnings.push(`comms.email covers ${covered.size} of ${participantIds.length} participants. These get no inbox and are never told one exists: ${uncovered.join(", ")}. Add a recipient with an address for each one whose flow needs email.`);
         }
     }
     return warnings;

package/dist/library-aliases.d.ts

@@ -0,0 +1,56 @@
+import { CuaAdmissionLimitError as AdmissionLimitError } from "./actors/computer-use/admission-limit.js";
+import type { CuaAction as Action, CuaExecutor as Executor, CuaLoopOptions as LoopOptions, CuaLoopResult as LoopResult, CuaObservation as Observation, CuaProvider as Provider, CuaSafetyCheck as SafetyCheck, CuaTurn as Turn, CuaTurnRequest as TurnRequest } from "./actors/computer-use/loop.js";
+import type { BrowserLabScoringContext as BrowserScoringContext } from "./lab/adapter-extension.js";
+import { parseLabConfig as parseStudy } from "./lab/config.js";
+import type { LabRoute as StudyRoute } from "./lab/routing.js";
+import type { LabEvent as StudyEvent } from "./lab/run-lab-events.js";
+import { type LabConfig as StudyConfig } from "./lab/types.js";
+import { runPackageLab as runStudy, type LabOutcome as StudyOutcome, type LabResult as StudyResult, type RunLabOptions as RunStudyOptions } from "./run-lab.js";
+/** @deprecated Use `runStudy`, the same function. 0.109 removes `runLab`. */
+export declare const runLab: typeof runStudy;
+/** @deprecated Use `parseStudy`, the same function. 0.109 removes `parseLabConfig`. */
+export declare const parseLabConfig: typeof parseStudy;
+/**
+ * The `humanish.lab.v2` schema id, which 0.109 stops parsing.
+ * @deprecated Write `STUDY_SCHEMA` (`humanish.study.v3`) files. 0.109 removes `LAB_CONFIG_SCHEMA`.
+ */
+export declare const LAB_CONFIG_SCHEMA = "humanish.lab.v2";
+/** @deprecated Use `StudyConfig`, the same type. 0.109 removes `LabConfig`. */
+export type LabConfig = StudyConfig;
+/** @deprecated Use `StudyEvent`, the same type. 0.109 removes `LabEvent`. */
+export type LabEvent = StudyEvent;
+/** @deprecated Use `StudyOutcome`, the same type. 0.109 removes `LabOutcome`. */
+export type LabOutcome = StudyOutcome;
+/** @deprecated Use `StudyResult`, the same type. 0.109 removes `LabResult`. */
+export type LabResult<R extends StudyRoute = StudyRoute> = StudyResult<R>;
+/** @deprecated Use `StudyRoute`, the same type. 0.109 removes `LabRoute`. */
+export type LabRoute = StudyRoute;
+/** @deprecated Use `RunStudyOptions`, the same type. 0.109 removes `RunLabOptions`. */
+export type RunLabOptions = RunStudyOptions;
+/** @deprecated Use `BrowserScoringContext`, the same type. 0.109 removes `BrowserLabScoringContext`. */
+export type BrowserLabScoringContext = BrowserScoringContext;
+/**
+ * @deprecated Use `ComputerUseAdmissionLimitError`, the same class, so `instanceof` matches either
+ * name. 0.109 removes `CuaAdmissionLimitError`.
+ */
+export declare const CuaAdmissionLimitError: typeof AdmissionLimitError;
+/** @deprecated Use `ComputerUseAdmissionLimitError`. 0.109 removes `CuaAdmissionLimitError`. */
+export type CuaAdmissionLimitError = AdmissionLimitError;
+/** @deprecated Use `ComputerUseAction`, the same type. 0.109 removes `CuaAction`. */
+export type CuaAction = Action;
+/** @deprecated Use `ComputerUseExecutor`, the same type. 0.109 removes `CuaExecutor`. */
+export type CuaExecutor = Executor;
+/** @deprecated Use `ComputerUseLoopOptions`, the same type. 0.109 removes `CuaLoopOptions`. */
+export type CuaLoopOptions = LoopOptions;
+/** @deprecated Use `ComputerUseLoopResult`, the same type. 0.109 removes `CuaLoopResult`. */
+export type CuaLoopResult = LoopResult;
+/** @deprecated Use `ComputerUseObservation`, the same type. 0.109 removes `CuaObservation`. */
+export type CuaObservation = Observation;
+/** @deprecated Use `ComputerUseProvider`, the same type. 0.109 removes `CuaProvider`. */
+export type CuaProvider = Provider;
+/** @deprecated Use `ComputerUseSafetyCheck`, the same type. 0.109 removes `CuaSafetyCheck`. */
+export type CuaSafetyCheck = SafetyCheck;
+/** @deprecated Use `ComputerUseTurn`, the same type. 0.109 removes `CuaTurn`. */
+export type CuaTurn = Turn;
+/** @deprecated Use `ComputerUseTurnRequest`, the same type. 0.109 removes `CuaTurnRequest`. */
+export type CuaTurnRequest = TurnRequest;

package/dist/library-aliases.js

@@ -0,0 +1,22 @@
+// The names 0.107's library exported for running a lab and driving a computer-use participant.
+// Each is the same function, constant, class or type as the name that replaces it, so an existing
+// import, call or `instanceof` check keeps working, and editors mark it deprecated.
+// Removed in 0.109.0: this module and its exports in src/index.ts.
+import { CuaAdmissionLimitError as AdmissionLimitError } from "./actors/computer-use/admission-limit.js";
+import { parseLabConfig as parseStudy } from "./lab/config.js";
+import { LAB_CONFIG_SCHEMA as V2_SCHEMA } from "./lab/types.js";
+import { runPackageLab as runStudy, } from "./run-lab.js";
+/** @deprecated Use `runStudy`, the same function. 0.109 removes `runLab`. */
+export const runLab = runStudy;
+/** @deprecated Use `parseStudy`, the same function. 0.109 removes `parseLabConfig`. */
+export const parseLabConfig = parseStudy;
+/**
+ * The `humanish.lab.v2` schema id, which 0.109 stops parsing.
+ * @deprecated Write `STUDY_SCHEMA` (`humanish.study.v3`) files. 0.109 removes `LAB_CONFIG_SCHEMA`.
+ */
+export const LAB_CONFIG_SCHEMA = V2_SCHEMA;
+/**
+ * @deprecated Use `ComputerUseAdmissionLimitError`, the same class, so `instanceof` matches either
+ * name. 0.109 removes `CuaAdmissionLimitError`.
+ */
+export const CuaAdmissionLimitError = AdmissionLimitError;

package/dist/observer/artifact.d.ts

@@ -1,7 +1,7 @@
 import type { LoadedAnalysis } from "../analysis/types.js";
 import { type ObserverData } from "./data.js";
 /**
- * Resolve — and in a repo checkout, build — the Observer artifact BEFORE any run or
+ * Resolve (and in a repo checkout, build) the Observer artifact before any run or
  * lab work starts. A missing artifact must cost seconds at startup, never a completed
  * session (a live participant spends real money before the render step would have noticed).
  * Unconditional on purpose: the artifact is the only renderer now, so the fail-before-