humanish 0.110.4 → 0.111.0

package/dist/study/validation.js

@@ -1,9 +1,9 @@
 import { isMaxOutputTokens } from "../actors/output-token-limit.js";
-import { PARTICIPANT_ID_MAX_CHARS, PARTICIPANT_ID_PATTERN, focusOf } from "./parse/actors.js";
+import { PARTICIPANT_ID_MAX_CHARS, PARTICIPANT_ID_PATTERN } from "./parse/actors.js";
 import { isHttpUrl, isLoopbackUrl } from "./parse/subject.js";
 import { declaredTargets } from "./plan-participants.js";
 import { actorResolvesToComputerUse, computerUseParticipantCount, MAX_COMPUTER_USE_PARTICIPANTS, registeredComputerUseActors, resolveEntryUrl, isComputerUseComposition, isScriptedBrowserComposition, isSharedWorldComposition, isTerminalProductComposition, } from "./routing.js";
-import { actorOf, actorsOf, participantList, declaredParticipantCount, declaresSharedWorld, } from "./study-fields.js";
+import { actorOf, participantList, declaresSharedWorld } from "./study-fields.js";
 /**
  * Cross-validate the computer-use fan-out declaration (`per-lane-worlds`). Returns the failure
  * message, or null when valid. The parser enforces it, and runStudyWith checks it again for a config
@@ -11,25 +11,18 @@ import { actorOf, actorsOf, participantList, declaredParticipantCount, declaresS
  * validity, unique ids) first, then the route-scoped XOR, cap and policy checks.
  */
 export function computerUseValidationReason(config) {
-    const actor = actorOf(config);
     const roster = participantList(config);
     const structuralReason = rosterStructuralValidationReason(config);
     if (structuralReason) {
         return structuralReason;
     }
     // 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.
+    // inert-warned). Fan-out is declared with `participants`; 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 participants (homogeneous) or participants (a roster of participants). (No current route reads clone.fanout.)";
     }
     if (roster !== undefined) {
-        if (declaredParticipantCount(config) !== undefined) {
-            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.";
-        }
         if (config.execution?.desktop?.resolution !== undefined &&
             roster.some((entry) => entry.device !== undefined)) {
             return "participants[].device and a raw execution.desktop.resolution are mutually exclusive: a per-participant device preset and a single hand-set resolution cannot both govern participant geometry.";
@@ -54,7 +47,7 @@ export function computerUseValidationReason(config) {
     // 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
+    // `route: shared-world` is also declared, N participants against one public target is the
     // 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 &&
@@ -98,7 +91,7 @@ function rosterStructuralValidationReason(config) {
     return null;
 }
 /**
- * Cross-validate a `topology: shared-world` declaration. Returns the failure message, or
+ * Cross-validate a `route: 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
  * runStudyWith takes a config that skipped the parser.
@@ -110,8 +103,8 @@ export function sharedWorldValidationReason(config) {
 }
 /**
  * The structural checks every provisioned shared world shares. It requires: a clone or local-tree source + e2b-desktop
- * target + a computer-use actor + a `subject.serve` block + an `actors[0].lanes` roster of ≥2 roles (the
- * roster is the role roster; there is no separate roles[] field), and every role `entry` must resolve
+ * target + a computer-use actor + a `subject.serve` block + a `participants` list of ≥2 (the list
+ * is the role roster; there is no separate roles[] field), and every role `entry` must resolve
  * same-origin (loopback) with serve.url. Fail-closed: a half-declared shared-world is rejected,
  * never silently downgraded.
  */
@@ -181,8 +174,10 @@ export function desktopMediaValidationReason(config, supportsMedia = isComputerU
         return "execution.desktop.media requires Chrome or Chromium; Firefox cannot receive the declared synthetic capture device. Set execution.desktop.browser: chrome or chromium.";
     }
     if (media.microphone !== undefined) {
-        if (actorsOf(config).some((actor) => actor.type !== "local-agent" ||
-            (actor.localAgent !== undefined && actor.localAgent !== "codex"))) {
+        const actor = actorOf(config);
+        if (actor !== undefined &&
+            (actor.type !== "local-agent" ||
+                (actor.localAgent !== undefined && actor.localAgent !== "codex"))) {
             return "Participant speech currently requires local-agent with Codex, on a local or hosted desktop.";
         }
         if (config.execution?.target !== "local" && media.camera !== undefined) {
@@ -199,7 +194,7 @@ export function receivingEmailValidationReason(config) {
         !["app-url", "clone", "local-tree"].includes(config.subject.source)) {
         return "Real email receiving requires a hosted computer-use browser study with an app-url, clone, or local-tree subject. Scripted, terminal, desktop-cli and local-app routes are unsupported.";
     }
-    if (actorsOf(config).some((actor) => actor.type === "local-agent")) {
+    if (actorOf(config)?.type === "local-agent") {
         return "Real email receiving is unavailable for local-agent: its host process does not isolate the inbox management credential. Use a hosted first-party computer-use actor.";
     }
     return undefined;
@@ -207,15 +202,8 @@ export function receivingEmailValidationReason(config) {
 /** 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 actorsOf(config).entries()) {
-        if (actor.tasks === undefined)
-            continue;
-        if (index > 0) {
-            return `actors[${index}].tasks is unsupported: current runners consume only actors[0]. Use the first actor's computer-use participants for a task protocol.`;
-        }
-        if (!supportsTasks) {
-            return "actor.tasks is unsupported on this execution path. Task protocols require the computer-use route, with one world per participant; shared-world, terminal-product, scripted-browser and synthetic routes do not consume them. Remove tasks only if a mission-only study is intended.";
-        }
+    if (actorOf(config)?.tasks !== undefined && !supportsTasks) {
+        return "actor.tasks is unsupported on this execution path. Task protocols require the computer-use route, with one world per participant; shared-world, terminal-product, scripted-browser and synthetic routes do not consume them. Remove tasks only if a mission-only study is intended.";
     }
     return null;
 }
@@ -233,24 +221,6 @@ export function cloneTargetValidationReason(config) {
     const got = target === undefined ? "it is absent" : `got "${target}"`;
     return `clone subjects require \`execution.target: e2b-desktop\` (${got}): humanish clones and serves the repo inside a hosted desktop sandbox. \`execution.target: local\` applies to app-url and local-app subjects.`;
 }
-/**
- * Refuse a positive `scenario.caps.maxUsd` or `maxTotalUsd` on a computer-use study.
- * `scenario.caps` belongs to the terminal route; the computer-use route stops on `execution.caps`,
- * so a dollar figure here would read as a cap while the study ran uncapped. Zero spends nothing
- * either way and stays a warning. Enforced at parse and again on the computer-use routes for
- * library callers.
- */
-export function scenarioCapsValidationReason(config) {
-    if (!isComputerUseComposition(config))
-        return null;
-    for (const key of ["maxUsd", "maxTotalUsd"]) {
-        const value = config.scenario?.caps?.[key];
-        if (value === undefined || value <= 0)
-            continue;
-        return `scenario.caps.${key} (${value}) does not cap a computer-use study: this route stops on execution.caps.${key}. Move the value to execution.caps.${key}; scenario.caps applies only to terminal-product studies.`;
-    }
-    return null;
-}
 /** Refuse a claimed output bound when the route cannot pass it to the first-party provider. */
 export function outputTokenLimitValidationReason(config) {
     const actor = actorOf(config);
@@ -317,7 +287,7 @@ export function concurrentSharedWorldValidationReason(config) {
  * it rejects every provisioned-subject field (serve/state.seed/state.checkpoint/exposure/clone/repos
  * 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
+ * concurrency >= 2 + a `participants` list 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 (runStudyWith takes a config that skipped the parser).
  */

package/dist/study/warnings.d.ts

@@ -1,12 +1,12 @@
 import type { StudyConfig } 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.
+ * The fields a config sets that its route does not read, each as `field` or `field (reason)`.
+ * parseStudy refuses a study for any of them.
  */
 export declare function inertFieldLabels(config: StudyConfig): 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.
+ * `participants[].entry` or `execution.timeoutMs`. `humanish migrate` drops each one.
  */
 export declare function inertFieldPaths(config: StudyConfig): string[];
 export declare function forwardDeclaredWarnings(config: StudyConfig): string[];

package/dist/study/warnings.js

@@ -1,73 +1,54 @@
 import { isComputerUseComposition, isScriptedBrowserComposition, isSharedWorldComposition, isTerminalProductComposition, } from "./routing.js";
 import { declaredParticipantIds } from "./plan-participants.js";
 import { addressedRecipients } from "./parse/comms.js";
-import { focusOf, rosterOf } from "./parse/actors.js";
-import { actorsOf, participantList, declaredParticipantCount, scenarioRefOf, } from "./study-fields.js";
-// The computer-use and terminal routes consume mission/persona/model and laneFocus.instruction (they
-// compose the agent prompt and bundle provenance); laneFocus.id/label stay inert. On the computer-use
-// E2B route actors[0].lanes is consumed (the fan-out roster).
+import { actorOf, participantList, declaredParticipantCount, scenarioRefOf, } from "./study-fields.js";
+// The computer-use and terminal routes consume mission/persona/model (they compose the agent prompt
+// and bundle provenance).
 const promptRoute = (routes) => routes.cua || routes.terminal;
-// The scripted-browser route consumes persona and count (trace/bundle provenance; surface roster).
-// The prompt fields can never act there: the scripted actor runs no model.
+// The scripted-browser route consumes persona and surfaces (trace/bundle provenance). The prompt
+// fields can never act there: the scripted actor runs no model.
 const scriptedRoute = (routes) => !promptRoute(routes) && routes.scripted;
 const otherRoute = (routes) => !promptRoute(routes) && !routes.scripted;
-/** Rows for each actor, reported as `actors[<index>].<field>`, in this order per actor. */
+/** Rows for the actor and its participants, reported first, in this order. */
 const ACTOR_ROWS = [
     // Shared-world-only fields on the roster: a participant's `entry` is inert anywhere else
     // (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,
+        field: "participants[].entry",
+        reason: "the per-participant loopback entry is a shared-world capability; needs route: shared-world",
+        applies: (config, routes) => Boolean(participantList(config)?.some((entry) => entry.entry !== undefined)) &&
+            !routes.shared,
     },
     // The host marker acts only on the external-public shared-world route; inert elsewhere.
     {
-        field: "lanes[].host",
+        field: "participants[].host",
         reason: "the designated host-participant marker; needs the external-public shared-world route: app-url × topology shared-world × allowPublicTargets",
-        applies: (actor, routes) => Boolean(rosterOf(actor)?.some((entry) => entry.host === true)) && !routes.externalPublic,
+        applies: (config, routes) => Boolean(participantList(config)?.some((entry) => entry.host === true)) &&
+            !routes.externalPublic,
     },
     {
-        field: "laneFocus.id",
-        applies: (actor, routes) => promptRoute(routes) && Boolean(focusOf(actor)?.id),
-    },
-    {
-        field: "laneFocus.label",
-        applies: (actor, routes) => promptRoute(routes) && Boolean(focusOf(actor)?.label),
-    },
-    {
-        field: "lanes",
-        reason: "only the computer-use route runs more than one participant",
-        applies: (actor, routes) => routes.terminal && Boolean(rosterOf(actor)),
-    },
-    {
-        field: "mission",
+        field: "actor.mission",
         reason: "the scripted-browser actor runs no model",
-        applies: (actor, routes) => scriptedRoute(routes) && Boolean(actor.mission),
+        applies: (config, routes) => scriptedRoute(routes) && Boolean(actorOf(config)?.mission),
     },
     {
-        field: "laneFocus",
+        field: "actor.model",
         reason: "the scripted-browser actor runs no model",
-        applies: (actor, routes) => scriptedRoute(routes) && Boolean(focusOf(actor)),
+        applies: (config, routes) => scriptedRoute(routes) && Boolean(actorOf(config)?.model),
     },
+    // On every other route the prompt fields and persona are inert.
     {
-        field: "model",
-        reason: "the scripted-browser actor runs no model",
-        applies: (actor, routes) => scriptedRoute(routes) && Boolean(actor.model),
+        field: "actor.mission",
+        applies: (config, routes) => otherRoute(routes) && Boolean(actorOf(config)?.mission),
     },
     {
-        field: "lanes",
-        reason: "the scripted-browser route fans out via actors[0].count, not an actors[0].lanes roster",
-        applies: (actor, routes) => scriptedRoute(routes) && Boolean(rosterOf(actor)),
+        field: "actor.persona",
+        applies: (config, routes) => otherRoute(routes) && Boolean(actorOf(config)?.persona),
     },
-    // On every other route the prompt fields, persona and the `lanes[]` roster are inert.
-    { field: "mission", applies: (actor, routes) => otherRoute(routes) && Boolean(actor.mission) },
     {
-        field: "laneFocus",
-        applies: (actor, routes) => otherRoute(routes) && Boolean(focusOf(actor)),
+        field: "actor.model",
+        applies: (config, routes) => otherRoute(routes) && Boolean(actorOf(config)?.model),
     },
-    { field: "persona", applies: (actor, routes) => otherRoute(routes) && Boolean(actor.persona) },
-    { field: "model", applies: (actor, routes) => otherRoute(routes) && Boolean(actor.model) },
-    { 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; no route reads it yet";
@@ -91,17 +72,10 @@ 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; 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",
-        applies: (config, routes) => config.subject.topology !== undefined && !routes.shared,
-    },
+    // The checkpoint acts only on the shared-world route.
     {
         field: "subject.state.checkpoint",
-        reason: "the shared-world state-checkpoint probe; needs subject.topology: shared-world",
+        reason: "the shared-world state-checkpoint probe; needs route: shared-world",
         applies: (config, routes) => config.subject.state?.checkpoint !== undefined && !routes.shared,
     },
     // publicTarget (the external-public ownership attestation) acts only on the external-public
@@ -161,18 +135,10 @@ const CONFIG_ROWS = [
         field: "execution.concurrency",
         applies: (config, routes) => config.execution?.concurrency !== undefined && !routes.cua,
     },
-    // 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: "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.
+    // parse/front.ts refuses a `caps` key the declared route does not read, so no row lists `caps`.
+    // terminal-product consumes subject.product and execution.{terminal,runtimeAuth}: dry-run records
+    // the contract; live execution enforces command-scoped auth. On every other route they are inert
+    // and must warn so a misplaced safety 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",
@@ -180,18 +146,6 @@ const CONFIG_ROWS = [
             !routes.terminal &&
             config.subject.source !== "desktop-cli",
     },
-    {
-        field: "scenario.caps",
-        reason: TERMINAL_ONLY,
-        applies: (config, routes) => Boolean(config.scenario?.caps) && !routes.terminal,
-    },
-    // The study-level budget is a CUA-route capability; the terminal route is a single agent whose
-    // maxUsd already caps the whole run, so a maxTotalUsd there would be trusted and unenforced.
-    {
-        field: "scenario.caps.maxTotalUsd",
-        reason: "the study-level budget is a computer-use route capability; the terminal route's maxUsd already caps the whole run",
-        applies: (config, routes) => config.scenario?.caps?.maxTotalUsd !== undefined && routes.terminal,
-    },
     {
         field: "execution.terminal",
         reason: TERMINAL_ONLY,
@@ -247,13 +201,12 @@ const CONFIG_ROWS = [
         reason: "no current route reads it",
         applies: (config) => config.execution?.desktop?.codexAppServer !== undefined,
     },
-    // scenario.ref is consumed on the scripted-browser route (required there); forward-declared
+    // `scenario` is consumed on the scripted-browser route (required there); forward-declared
     // everywhere else.
     {
-        field: "scenario.ref",
+        field: "scenario",
         applies: (config, routes) => Boolean(scenarioRefOf(config)) && !routes.scripted,
     },
-    { field: "scenario.inline", applies: (config) => Boolean(config.scenario?.inline) },
     // 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,
@@ -278,7 +231,6 @@ const CONFIG_ROWS = [
         reason: "the scripted-browser actor has no adopter-scorer seam; declare it on a terminal / computer-use / shared-world route",
         applies: (config, routes) => Boolean(config.review?.scorer) && routes.scripted,
     },
-    { field: "personas", applies: (config) => Boolean(config.personas) },
 ];
 function routesOf(config) {
     const cua = isComputerUseComposition(config);
@@ -295,44 +247,23 @@ function routesOf(config) {
             config.execution?.target === "e2b-desktop",
     };
 }
-function rowLabel(row, prefix = "") {
-    return row.reason === undefined
-        ? `${prefix}${row.field}`
-        : `${prefix}${row.field} (${row.reason})`;
+function inertRows(config) {
+    const routes = routesOf(config);
+    return [...ACTOR_ROWS, ...CONFIG_ROWS].filter((row) => row.applies(config, routes));
 }
 /**
- * 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.
+ * The fields a config sets that its route does not read, each as `field` or `field (reason)`.
+ * parseStudy refuses a study for any of them.
  */
 export function inertFieldLabels(config) {
-    const routes = routesOf(config);
-    const inert = [];
-    for (const [index, actor] of actorsOf(config).entries()) {
-        for (const row of ACTOR_ROWS)
-            if (row.applies(actor, routes))
-                inert.push(rowLabel(row, `actors[${index}].`));
-    }
-    for (const row of CONFIG_ROWS)
-        if (row.applies(config, routes))
-            inert.push(rowLabel(row));
-    return inert;
+    return inertRows(config).map((row) => row.reason === undefined ? row.field : `${row.field} (${row.reason})`);
 }
 /**
  * The same fields as `inertFieldLabels`, as paths without their reasons, such as
- * `actors[0].lanes[].entry` or `execution.timeoutMs`. `humanish migrate` drops each one.
+ * `participants[].entry` or `execution.timeoutMs`. `humanish migrate` drops each one.
  */
 export function inertFieldPaths(config) {
-    const routes = routesOf(config);
-    const paths = [];
-    for (const [index, actor] of actorsOf(config).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;
+    return inertRows(config).map((row) => row.field);
 }
 // Report fields that are present but not yet consumed by the engine, so a user never trusts a
 // setting that silently does nothing.

package/dist/substrates/local/runtime-config.js

@@ -1,4 +1,4 @@
-import { actorOf, actorsOf, participantList } from "../../study/study-fields.js";
+import { actorOf, capsOf, participantList } from "../../study/study-fields.js";
 // The runtime image enforces a 30-minute lifetime; reserve setup/teardown room.
 export const LOCAL_BROWSER_LIFETIME_MS = 30 * 60_000;
 const MAX_SESSION_MS = 20 * 60_000;
@@ -9,15 +9,16 @@ export function isLocalBrowserStudy(config) {
 }
 /** Defaults for the explicitly selected local substrate; hosted configurations are untouched. */
 export function localBrowserDefaults(config) {
-    if (!isLocalBrowserStudy(config))
+    const actor = actorOf(config);
+    if (!isLocalBrowserStudy(config) || actor === undefined)
         return config;
     return {
         ...config,
-        actors: actorsOf(config).map((actor) => ({
+        actor: {
             ...actor,
             model: actor.model ?? "gpt-6-astra",
             reasoningEffort: actor.reasoningEffort ?? "low",
-        })),
+        },
         execution: {
             ...config.execution,
             timeoutMs: config.execution?.timeoutMs ?? MAX_SESSION_MS,
@@ -26,7 +27,7 @@ export function localBrowserDefaults(config) {
                 resolution: config.execution?.desktop?.resolution ?? [960, 720],
             },
         },
-        ...(config.review?.analysis === undefined && actorOf(config)?.type === "local-agent"
+        ...(config.review?.analysis === undefined && actor.type === "local-agent"
             ? { review: { ...config.review, analysis: { provider: "codex" } } }
             : {}),
     };
@@ -37,8 +38,7 @@ export function localBrowserUnsupportedReason(config) {
     if ((config.execution?.timeoutMs ?? MAX_SESSION_MS) > MAX_SESSION_MS) {
         return "Local browser sessions currently support at most 20 minutes, within the runtime's 30-minute lifetime.";
     }
-    if (actorsOf(config).length !== 1 ||
-        !actor ||
+    if (!actor ||
         (actor.type === "local-agent" && actor.localAgent !== undefined && actor.localAgent !== "codex")) {
         return "Local browser studies support only Codex local-agent or openai-computer-use participants.";
     }
@@ -63,10 +63,8 @@ export function localBrowserUnsupportedReason(config) {
             actor.reasoningEffort !== "low" ||
             participantList(config)?.some((entry) => entry.reasoningEffort !== undefined && entry.reasoningEffort !== "low") ||
             actor.maxOutputTokens !== undefined ||
-            config.execution?.caps?.maxUsd !== undefined ||
-            config.execution?.caps?.maxTotalUsd !== undefined ||
-            config.scenario?.caps?.maxUsd !== undefined ||
-            config.scenario?.caps?.maxTotalUsd !== undefined)) {
+            capsOf(config)?.maxUsd !== undefined ||
+            capsOf(config)?.maxTotalUsd !== undefined)) {
         return "Local Codex participants currently use gpt-6-astra at low effort. Account dollar/output-token caps are unavailable; use API participants for those controls.";
     }
     for (const target of [

package/docs/contracts/schemas.md

@@ -59,10 +59,19 @@ workflow without leaking private upstream truth into core.
 
 ## Study File
 
-Schema: `humanish.study.v3`. `src/study/parse/study-v3.ts` rewrites a v3 document into the
-normalized config in `src/study/types.ts`, which `src/study/config.ts` parses. humanish refuses a
-`humanish.lab.v2` file with `HUMANISH_STUDY_V2_UNSUPPORTED`, whose message names
-`humanish migrate <path>`; migrate converts the file to v3.
+Schema: `humanish.study.v3`. `src/study/config.ts` parses a v3 document into `StudyConfig`
+(`src/study/types.ts`), which has the file's keys; `src/study/parse/front.ts` checks the route and
+the forms of `participants`, `surfaces` and `caps` it takes. humanish refuses a `humanish.lab.v2`
+file with `HUMANISH_STUDY_V2_UNSUPPORTED`, whose message names `humanish migrate <path>`; migrate
+converts the file to v3.
+
+The parsed config is the file with defaults filled: a `participants` entry with a `count` expanded
+into its participants, `comms.email.recipients` and a shared world's `execution.concurrency`
+filled, `kind: real` added beside an email `connection`, and a local browser study's model,
+effort, timeout and resolution. `humanish study show --json` prints that config, and `parseStudy`
+reads it back to the same config. Before 0.111.0, `StudyConfig` had the `humanish.lab.v2` keys
+(`actors`, `execution.caps`, the `scenario` object, `subject.topology`); the 0.111.0 release notes
+map each one to its v3 key.
 
 A study declares its route and composes code primitives; it is not a hardcoded kind. The
 top-level keys:
@@ -1552,6 +1561,16 @@ Refusals:
   a preview or scripted study, `createProvider` off computer use, or `prepareDesktop` where no E2B
   desktop exists. The message names the option and the route. The same code refuses a field
   `RunStudyOptions` no longer has (below); that message names the field and where its job went.
+- `HUMANISH_STUDY_V2_UNSUPPORTED`: the config is `humanish.lab.v2`, or it still sets a
+  `StudyConfig` field of humanish 0.110 that 0.111.0 renamed: `actors`, a `scenario` object,
+  `execution.caps`, `subject.topology`, `personas`, or `count`, `lanes`, `roster` or `laneFocus` on
+  `actor`. The message names each one's v3 field. The
+  planners read only the v3 fields, so a budget left in `execution.caps` would otherwise run
+  uncapped.
+- `HUMANISH_STUDY_INVALID`: the config has no `actor` object, or its `route` is missing or is not
+  the route its subject and actor take. The message is the one `parseStudy` gives.
+
+`runStudy` checks the config before the options, so a config refusal comes first.
 
 `rerun.laneIds`, the older name of `rerun.participantIds`, was removed in 0.107.0. A caller that
 still passes it is refused with `HUMANISH_STUDY_OPTION_UNSUPPORTED`; use `rerun.participantIds`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "humanish",
-  "version": "0.110.4",
+  "version": "0.111.0",
   "description": "Synthetic user research for apps, CLIs, and agent-facing product flows.",
   "keywords": [
     "cli",

package/dist/study/parse/study.d.ts

@@ -1,38 +0,0 @@
-import { type StudyConfig, type StudyParseFailure, type StudyScenarioCaps, type StudyV3 } from "../types.js";
-interface StudyV3Options {
-    /**
-     * `report`, for `humanish migrate`: list the fields the route does not read in `inert`, as v2
-     * paths, in place of refusing the study for them, and give the checks' messages as they wrote
-     * them, in the v2 spelling of the file migrate converts. A shared world may then give
-     * `participants` as a count or leave it out, as a v2 file could (readStudyFront).
-     */
-    readonly inert?: "refuse" | "report";
-}
-type StudyV3ParseResult = {
-    ok: true;
-    config: StudyV3;
-    warnings: string[];
-    inert?: string[];
-} | StudyParseFailure;
-type Parsed<T> = {
-    ok: true;
-    value: T;
-} | StudyParseFailure;
-/**
- * Validate a parsed humanish.study.v3 document into a StudyV3, with the messages parseStudy gives.
- * Pure: the caller owns file IO. parseStudy refuses a humanish.lab.v2 document before this runs.
- */
-export declare function parseStudyV3(raw: unknown, options?: StudyV3Options): StudyV3ParseResult;
-/**
- * A v3 study in the v2 spelling: the actor holds its participants, `caps` moves under `execution`
- * or `scenario`, and a shared world is `subject.topology: shared-world`. The checks that read more
- * than one section run on this view until StudyConfig has the v3 shape.
- */
-export declare function toLegacy(study: StudyV3): StudyConfig;
-/**
- * A caps block's values. A value that is not a non-negative number refuses the study: a cap that
- * does nothing must not look like one that holds. readStudyFront has checked the keys against the
- * route; migrate checks a v2 file's two blocks with it.
- */
-export declare function parseCaps(raw: unknown): Parsed<StudyScenarioCaps | undefined>;
-export {};