humanish 0.110.3 → 0.111.0

package/dist/run/run.js

@@ -32,11 +32,13 @@ export class FinishedRun {
     runId;
     /** The paths created by startRun and validated at the start of `finish`. */
     paths;
-    constructor(key, runId, paths, observer, outcome, recordFailure, interrupted) {
+    #participantsRan;
+    constructor(key, runId, paths, observer, outcome, recordFailure, interrupted, participantsRan) {
         if (key !== issueKey)
             throw new Error("Only Run.finish issues a FinishedRun.");
         this.runId = runId;
         this.paths = paths;
+        this.#participantsRan = participantsRan;
         this.#observer = observer;
         this.#outcome = outcome;
         this.#recordFailure = recordFailure;
@@ -49,6 +51,10 @@ export class FinishedRun {
     get interrupted() {
         return this.#interrupted();
     }
+    /** The route reported a participant's session started (Run.participantStarted). */
+    get participantsRan() {
+        return this.#participantsRan();
+    }
     static isIssued(value) {
         return typeof value === "object" && value !== null && #observer in value;
     }
@@ -106,7 +112,7 @@ function observerTarget(options) {
         };
 }
 function runPublisher(args) {
-    const { options, runId, paths, runStatus, now, admit } = args;
+    const { options, runId, paths, runStatus, now, admit, participantsRan } = args;
     const observer = observerTarget(options);
     let pointerWritten = false;
     // The bundle of the last write asked for, and the outcome every later write carries once a
@@ -176,7 +182,7 @@ function runPublisher(args) {
             await writeBundleFiles(bundle, finishedOutcome(current), (publicBundle) => runStatus.restate(runStatusOutcome(publicBundle))).catch(() => undefined);
             return current;
         }));
-        return new FinishedRun(issueKey, runId, paths, observer, current, recordFailure, () => runStatus.interrupted);
+        return new FinishedRun(issueKey, runId, paths, observer, current, recordFailure, () => runStatus.interrupted, participantsRan);
     };
     const interrupt = async (signal) => {
         interrupted = { state: "interrupted", ok: false, signal, at: new Date(now()).toISOString() };
@@ -231,7 +237,8 @@ export async function runScope(fn) {
             const created = await createRunArtifactPaths(options.cwd, runId);
             if (!created.ok)
                 return created;
-            // beginRunStatus reads only the mode and the study provenance from the run's options.
+            // beginRunStatus reads only the mode, the study provenance and the sandboxes field from
+            // the run's options.
             const runStatus = beginRunStatus(created.paths, { ...options, runId });
             status = runStatus;
             let interruptBundle;
@@ -260,7 +267,16 @@ export async function runScope(fn) {
     const openRun = (options, runId, paths, runStatus) => {
         const now = options.now ?? Date.now;
         const createdAt = new Date(now()).toISOString();
-        const publisher = runPublisher({ options, runId, paths, runStatus, now, admit });
+        let participantsRan = false;
+        const publisher = runPublisher({
+            options,
+            runId,
+            paths,
+            runStatus,
+            now,
+            admit,
+            participantsRan: () => participantsRan,
+        });
         let finishCalled = false;
         const checkIdentity = (bundle) => bundle.runId !== runId || bundle.mode !== options.mode
             ? "The bundle names another run or mode than this run."
@@ -271,6 +287,9 @@ export async function runScope(fn) {
             mode: options.mode,
             ...(options.study === undefined ? {} : { study: options.study }),
             paths,
+            participantStarted() {
+                participantsRan = true;
+            },
             writeSnapshot(bundle) {
                 if (closed)
                     return refuse("The run scope has closed.");

package/dist/run/status.d.ts

@@ -53,6 +53,11 @@ export interface RunStatusRecord {
      * Read either through studyProvenanceOf.
      */
     lab?: RunStudyProvenance;
+    /**
+     * `none` when the route recorded at start that this run creates no sandbox, as a scripted run
+     * against an app-url subject does. Absent when the run may create one. Reclaim reads it.
+     */
+    sandboxes?: "none";
     /** The pid that owns the run, for local liveness checks. */
     pid: number;
     startedAt: string;
@@ -87,6 +92,7 @@ export interface BeginRunStatusOptions {
     runId: string;
     mode: "dry-run" | "live";
     study?: RunStudyProvenance | undefined;
+    sandboxes?: "none" | undefined;
 }
 /**
  * Start a run's status record and keep it fresh. Fire-and-forget by design: a status write that

package/dist/run/status.js

@@ -64,6 +64,7 @@ export function beginRunStatus(runPaths, options) {
         state: "running",
         mode: options.mode,
         ...studyFields(options.study),
+        ...(options.sandboxes === undefined ? {} : { sandboxes: options.sandboxes }),
         pid: process.pid,
         startedAt,
         updatedAt: startedAt,

package/dist/run/stored-runs.js

@@ -5,7 +5,7 @@ import { bindExistingRunArtifactPaths, RUNS_RELATIVE_ROOT, isSafeRunIdSegment, r
 import { assertPreparedSelectedOutputDirectory, bindExistingManagedHumanishOutputDirectory, } from "./contained-output.js";
 import { RUN_BUNDLE_FILE } from "./bundle.js";
 import { isReviewSummary, isRunOutcome } from "./bundle-shape.js";
-import { bundleDisplayFacts, runDisplay } from "./display.js";
+import { bundleDisplayFacts, displayedReview, runDisplay, } from "./display.js";
 import { RUN_STATUS_FILE } from "./status.js";
 import { readLatest, readRunJsonIfExists, resolveRunPath } from "./locate.js";
 import { withCuaReviewProvenance } from "./outcomes.js";
@@ -101,22 +101,33 @@ export async function listRuns(cwdInput) {
  * that is not an object naming a run gets none.
  */
 async function listedRunDisplay(runPaths, bundle) {
-    if (!isRecord(bundle) || typeof bundle.runId !== "string")
+    const displayed = displayedBundle(bundle);
+    if (displayed === undefined)
         return {};
-    const outcome = isRunOutcome(bundle.outcome) ? bundle.outcome : undefined;
-    const status = outcome === undefined ? await readRunJsonIfExists(runPaths, RUN_STATUS_FILE) : undefined;
-    const facts = bundleDisplayFacts({
+    const status = displayed.outcome === undefined
+        ? await readRunJsonIfExists(runPaths, RUN_STATUS_FILE)
+        : undefined;
+    return { display: runDisplay(bundleDisplayFacts(displayed, status)) };
+}
+/** The fields runDisplay reads from an unchecked run.json; none when it does not name a run. */
+function displayedBundle(bundle) {
+    if (!isRecord(bundle) || typeof bundle.runId !== "string")
+        return undefined;
+    return {
         runId: bundle.runId,
         ...(typeof bundle.mode === "string" ? { mode: bundle.mode } : {}),
         ...(isRecord(bundle.review) && typeof bundle.review.verdict === "string"
             ? { review: { verdict: bundle.review.verdict } }
             : {}),
         ...(Array.isArray(bundle.simulations)
-            ? { simulations: bundle.simulations.filter(isRecord) }
+            ? {
+                simulations: bundle.simulations
+                    .filter(isRecord)
+                    .map((record) => (typeof record.status === "string" ? { status: record.status } : {})),
+            }
             : {}),
-        ...(outcome === undefined ? {} : { outcome }),
-    }, status);
-    return { display: runDisplay(facts) };
+        ...(isRunOutcome(bundle.outcome) ? { outcome: bundle.outcome } : {}),
+    };
 }
 function runsUnavailableResult(cwd, error) {
     return {
@@ -159,10 +170,14 @@ export async function readReview(cwdInput, runInput) {
     const projected = isRecord(bundle) && Array.isArray(bundle.streams)
         ? withCuaReviewProvenance(review, bundle.streams.filter(isRecord))
         : review;
+    const displayed = displayedBundle(bundle);
+    const { display } = runPaths ? await listedRunDisplay(runPaths, bundle) : {};
     return {
-        ...projected,
+        ...(displayed === undefined || display === undefined
+            ? projected
+            : displayedReview(projected, displayed, display)),
         path: path.relative(cwd, path.join(runPaths.absoluteRunRoot, "review.json")),
         runId: path.basename(runPaths.absoluteRunRoot),
-        ...(runPaths ? await listedRunDisplay(runPaths, bundle) : {}),
+        ...(display === undefined ? {} : { display }),
     };
 }

package/dist/run-study.d.ts

@@ -3,7 +3,7 @@ import { type LateScorer } from "./study/route-inputs.js";
 import { type StudyRoute } from "./study/plan.js";
 import type { StudyDeps } from "./study/study-deps.js";
 import type { RunStudyDriving, RunStudyHomes } from "./study/run-study-homes.js";
-import { type StudyConfig } from "./study/types.js";
+import type { StudyConfig } from "./study/types.js";
 import type { ObserverResult } from "./observer/render.js";
 import { type CuaActorStudyResult } from "./routes/computer-use/types.js";
 import { type PreviewStudyResult } from "./routes/preview.js";
@@ -20,8 +20,10 @@ import type { RunStudyProvenance } from "./run/study-provenance.js";
 export declare function runStudyWith(config: StudyConfig, options: InternalRunStudyOptions, deps?: StudyDeps): Promise<StudyOutcome>;
 /**
  * The package's study runner (`src/index.ts`): runStudyWith with the public options only. A
- * JavaScript caller that passes a field RunStudyOptions no longer has, or a humanish.lab.v2 config,
- * is refused in the route's own result envelope before anything runs.
+ * config that skipped parseStudy is checked first (libraryConfigRefusal): a humanish.lab.v2 config
+ * or one with a humanish 0.110 field, no `actor`, or a `route` the config does not take. That, or a
+ * field RunStudyOptions no longer has, is refused in the route's own result envelope before
+ * anything runs.
  */
 export declare function runStudy(config: StudyConfig, options: RunStudyOptions): Promise<StudyOutcome>;
 /** A study planned once: the route's refusal, or the run of its plan. */

package/dist/run-study.js

@@ -7,8 +7,7 @@
 import { computerUseInput, scriptedInput, sharedWorldInput, terminalInput, } from "./study/route-inputs.js";
 import { planStudy, resolveStudyDryRun, routeOf } from "./study/plan.js";
 import { normalizeRunStudyOptions, optionRefusalOutcome, removedOptionRefusal, } from "./study/run-study-options.js";
-import { V2_SCHEMA } from "./study/types.js";
-import { V2_UNSUPPORTED_MESSAGE } from "./study/config.js";
+import { libraryConfigRefusal } from "./study/config.js";
 import { admitComputerUsePlan, computerUseStudyRefusal } from "./routes/computer-use/route.js";
 import {} from "./routes/computer-use/types.js";
 import { admitPreviewPlan, previewStudyRefusal, } from "./routes/preview.js";
@@ -32,17 +31,14 @@ export async function runStudyWith(config, options, deps = {}) {
 }
 /**
  * The package's study runner (`src/index.ts`): runStudyWith with the public options only. A
- * JavaScript caller that passes a field RunStudyOptions no longer has, or a humanish.lab.v2 config,
- * is refused in the route's own result envelope before anything runs.
+ * config that skipped parseStudy is checked first (libraryConfigRefusal): a humanish.lab.v2 config
+ * or one with a humanish 0.110 field, no `actor`, or a `route` the config does not take. That, or a
+ * field RunStudyOptions no longer has, is refused in the route's own result envelope before
+ * anything runs.
  */
 export async function runStudy(config, options) {
-    const refusal = config.schema === V2_SCHEMA
-        ? {
-            ok: false,
-            code: "HUMANISH_STUDY_V2_UNSUPPORTED",
-            message: V2_UNSUPPORTED_MESSAGE,
-        }
-        : removedOptionRefusal(options);
+    const rejected = libraryConfigRefusal(config);
+    const refusal = rejected === undefined ? removedOptionRefusal(options) : { ok: false, ...rejected };
     if (refusal === undefined)
         return runStudyWith(config, options);
     const study = localBrowserDefaults(config);

package/dist/study/adapter-scorer-loader.d.ts

@@ -50,7 +50,7 @@ export type AdapterScorerLoadResult = {
     };
 };
 /**
- * Resolve + load a config-declared scorer module. Resolution clones scenario.ref exactly
+ * Resolve + load a config-declared scorer module. Resolution clones the scripted `scenario` resolution exactly
  * (prepareSelectedOutputDirectory → cwd-clamp → readContainedRegularFile), then `import()`s the
  * entry file in a broad try/catch. The digest is over the readContainedRegularFile entry bytes.
  */

package/dist/study/adapter-scorer-loader.js

@@ -54,7 +54,7 @@ const SCORER_CAPABLE_ROUTES = new Set([
  *  package.json `type`. `.ts` is rejected: the compiled `dist/` CLI ships no TypeScript loader. */
 const SCORER_EXTENSIONS = new Set([".mjs", ".js", ".cjs"]);
 /**
- * Resolve + load a config-declared scorer module. Resolution clones scenario.ref exactly
+ * Resolve + load a config-declared scorer module. Resolution clones the scripted `scenario` resolution exactly
  * (prepareSelectedOutputDirectory → cwd-clamp → readContainedRegularFile), then `import()`s the
  * entry file in a broad try/catch. The digest is over the readContainedRegularFile entry bytes.
  */
@@ -84,10 +84,10 @@ export async function loadAdapterScorer(args) {
     if (!SCORER_EXTENSIONS.has(ext)) {
         return fail("HUMANISH_STUDY_SCORER_BAD_REF", `review.scorer.ref "${trimmed}" must be a path relative to the project ending in .mjs (recommended), .js or .cjs.`);
     }
-    // Root token: realpath(cwd) → prepareSelectedOutputDirectory(dirname, cwd). Mirrors scenario.ref.
+    // Root token: realpath(cwd) → prepareSelectedOutputDirectory(dirname, cwd). Mirrors the scripted `scenario`.
     const physicalCwd = await realpath(path.resolve(args.cwd));
     const root = await prepareSelectedOutputDirectory(path.dirname(physicalCwd), physicalCwd);
-    // Clamp verbatim from the scripted scenario.ref branch: resolve → relative → reject escape/absolute.
+    // Clamp verbatim from the scripted `scenario` branch: resolve → relative → reject escape/absolute.
     const absolutePath = path.resolve(root.physicalPath, trimmed);
     const relative = path.relative(root.physicalPath, absolutePath);
     if (!relative || relative.startsWith("..") || path.isAbsolute(relative)) {

package/dist/study/composition-rules.js

@@ -4,13 +4,22 @@
 // a library caller's config itself, under its route's error codes. The planners call the shared
 // checks in study/validation.ts and desktopCliProductReason below. The other subject rules here have
 // planner counterparts whose conditions and wording differ (clone serve and repo, local-tree
-// target, in-process fan-out, loopback targets, scripted scenario.ref).
+// target, in-process fan-out, loopback targets, scripted `scenario`).
 import { isLoopbackUrl } from "./parse/subject.js";
 import { REPO_SLUG_PATTERN } from "./parse/values.js";
 import { declaredTargets } from "./plan-participants.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";
+import { actorOf, participantList, declaredParticipantCount, surfaceCount, modeOf, scenarioRefOf, declaresSharedWorld, } from "./study-fields.js";
+/**
+ * The count a scripted or terminal composition reads: its surfaces, or a participant count.
+ * parse/front.ts refuses `participants` on route: scripted and route: terminal, and `surfaces` off
+ * route: scripted, but a study can declare a route its composition does not take, and these rules
+ * run before parseStudy compares the two. migrate's view of a v2 file reaches them the same way.
+ */
+function participantOrSurfaceCount(config) {
+    return declaredParticipantCount(config) ?? surfaceCount(config);
+}
 /** The first composition rule a config breaks, in the parser's order, or null. */
 export function compositionReason(config) {
     return (thisRepoValidationReason(config) ??
@@ -25,7 +34,7 @@ export function compositionReason(config) {
         (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 participants.
-        (config.subject.topology === "shared-world" ? sharedWorldValidationReason(config) : null) ??
+        (declaresSharedWorld(config) ? sharedWorldValidationReason(config) : null) ??
         desktopCliValidationReason(config) ??
         terminalValidationReason(config) ??
         cloneActorValidationReason(config));
@@ -39,7 +48,7 @@ function thisRepoValidationReason(config) {
         if (config.execution?.target) {
             return "`execution.target` applies only to clone/app-url/local-app subjects; this-repo studies run locally.";
         }
-        if (config.scenario?.mode === "live") {
+        if (modeOf(config) === "live") {
             return THIS_REPO_DRY_RUN_ONLY;
         }
     }
@@ -54,18 +63,18 @@ function thisRepoValidationReason(config) {
 // planComputerUseStudy refuses it with HUMANISH_COMPUTER_USE_LOCAL_APP_NO_EXECUTOR.
 function localAppValidationReason(config) {
     if (config.subject.source === "local-app") {
-        const type = config.actors[0]?.type ?? "";
+        const type = actorOf(config)?.type ?? "";
         if (config.execution?.target !== undefined && config.execution.target !== "local") {
             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}".`;
+            return `actor.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 (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).";
+            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. Remove `participants`, or set `participants: 1`. For fan-out, use an app-url or clone subject on execution.target: e2b-desktop.";
         }
-        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 (participantList(config) !== undefined) {
+            return "`participants` (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` 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.";
@@ -78,18 +87,18 @@ function localAppValidationReason(config) {
 // 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 ?? "";
+        const type = actorOf(config)?.type ?? "";
         if (actorResolvesToScriptedBrowser(type)) {
             // 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 "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 "A scripted-browser study needs `scenario.ref`: the actor runs the browser steps in that scenario file.";
+            if (!scenarioRefOf(config)) {
+                return "A scripted-browser study needs `scenario`: the actor runs the browser steps in that scenario file.";
             }
-            if ((config.actors[0]?.count ?? 1) > 2) {
-                return "A scripted-browser study takes `actors[0].count` 1 (desktop) or 2 (desktop and mobile). Higher counts are not supported yet.";
+            if ((participantOrSurfaceCount(config) ?? 1) > 2) {
+                return "A scripted-browser study takes `surfaces` 1 (desktop) or 2 (desktop and mobile). Higher counts are not supported yet.";
             }
             if (config.policies?.redactScreenshots === true) {
                 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.";
@@ -106,17 +115,16 @@ function appUrlValidationReason(config) {
                 return "app-url computer-use subjects require `execution.target: local` or `e2b-desktop`.";
             }
             if (!actorResolvesToComputerUse(type)) {
-                return `actors[0].type must be a registered computer-use actor for app-url × e2b-desktop studies (one of: ${registeredComputerUseActors().join(", ")}); for local scripted execution use a registered scripted-browser actor (${registeredScriptedBrowserActors().join(", ")}). Got "${type}".`;
+                return `actor.type must be a registered computer-use actor for app-url × e2b-desktop studies (one of: ${registeredComputerUseActors().join(", ")}); for local scripted execution use a registered scripted-browser actor (${registeredScriptedBrowserActors().join(", ")}). Got "${type}".`;
             }
             // 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).
+            // cross-validation below enforces the 16 cap, 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 or localhost). To drive a deployed or preview URL you own, set `policies.allowPublicTargets: true`.";
+                return "`subject.appUrl` and `participants[].target` must be loopback URLs (127.0.0.1 or localhost). To drive a deployed or preview URL you own, set `policies.allowPublicTargets: true`.";
             }
         }
     }
@@ -125,7 +133,7 @@ function appUrlValidationReason(config) {
 // Scripted-browser actors on any other subject: only a provisioned clone on e2b-desktop.
 function scriptedBrowserValidationReason(config) {
     if (config.subject.source !== "app-url" &&
-        actorResolvesToScriptedBrowser(config.actors[0]?.type)) {
+        actorResolvesToScriptedBrowser(actorOf(config)?.type)) {
         if (config.subject.source !== "clone") {
             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).";
         }
@@ -142,20 +150,22 @@ function scriptedBrowserValidationReason(config) {
         if (!REPO_SLUG_PATTERN.test(repo)) {
             return `subject.repos[0] must be an owner/repo slug (got "${repo}").`;
         }
-        if (config.subject.topology !== undefined) {
+        // migrate converts a v2 file's `subject.topology: shared-world` to `route: shared-world`, and
+        // refuses it here with the v2 parser's message.
+        if (declaresSharedWorld(config)) {
             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 "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 "A scripted-browser study needs `scenario.ref`: the actor runs the browser steps in that scenario file.";
+        if (!scenarioRefOf(config)) {
+            return "A scripted-browser study needs `scenario`: the actor runs the browser steps in that scenario file.";
         }
-        if ((config.actors[0]?.count ?? 1) > 2) {
-            return "A scripted-browser study takes `actors[0].count` 1 (desktop) or 2 (desktop and mobile). Higher counts are not supported yet.";
+        if ((participantOrSurfaceCount(config) ?? 1) > 2) {
+            return "A scripted-browser study takes `surfaces` 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` to choose the desktop and mobile surfaces.";
+        if (participantList(config) !== undefined) {
+            return "`participants` is not supported on the scripted-browser route yet. Use `surfaces` to choose the desktop and mobile surfaces.";
         }
         if (config.policies?.redactScreenshots === true) {
             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.";
@@ -183,7 +193,7 @@ function scriptedBrowserValidationReason(config) {
 function cloneComputerUseValidationReason(config) {
     if (config.subject.source === "clone" &&
         config.execution?.target === "e2b-desktop" &&
-        actorResolvesToComputerUse(config.actors[0]?.type)) {
+        actorResolvesToComputerUse(actorOf(config)?.type)) {
         if (!config.subject.serve) {
             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.";
         }
@@ -195,8 +205,8 @@ function cloneComputerUseValidationReason(config) {
             return `subject.repos[0] must be an owner/repo slug (got "${repo}").`;
         }
         // 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.
+        // E2B desktop (`per-lane-worlds`). The shared cua cross-validation below enforces the 16 cap;
+        // the single-repo rule above is unchanged.
     }
     return null;
 }
@@ -210,8 +220,8 @@ function localTreeValidationReason(config) {
         if (config.execution?.target !== "e2b-desktop") {
             return "local-tree subjects require `execution.target: e2b-desktop`: the packed working tree is provisioned and served inside a hosted desktop sandbox; there is no local route for a local-tree subject.";
         }
-        if (!actorResolvesToComputerUse(config.actors[0]?.type)) {
-            return `actors[0].type must be a registered computer-use actor for local-tree subjects (one of: ${registeredComputerUseActors().join(", ")}); the actor drives the hosted desktop that serves the packed working tree. Got "${config.actors[0]?.type ?? ""}".`;
+        if (!actorResolvesToComputerUse(actorOf(config)?.type)) {
+            return `actor.type must be a registered computer-use actor for local-tree subjects (one of: ${registeredComputerUseActors().join(", ")}); the actor drives the hosted desktop that serves the packed working tree. Got "${actorOf(config)?.type ?? ""}".`;
         }
     }
     return null;
@@ -238,7 +248,7 @@ function desktopCliValidationReason(config) {
         if (config.execution?.target !== undefined && config.execution.target !== "e2b-desktop") {
             return "A desktop-cli subject runs on a hosted desktop. Set `execution.target: e2b-desktop` or omit it.";
         }
-        if (!actorResolvesToComputerUse(config.actors[0]?.type ?? "")) {
+        if (!actorResolvesToComputerUse(actorOf(config)?.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.";
         }
         const install = config.subject.product.install;
@@ -255,15 +265,15 @@ function desktopCliValidationReason(config) {
 // fan-out lands.
 function terminalValidationReason(config) {
     if (config.subject.source === "terminal-product") {
-        const type = config.actors[0]?.type ?? "";
+        const type = actorOf(config)?.type ?? "";
         if (config.execution?.target !== undefined && config.execution.target !== "e2b-terminal") {
             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}".`;
+            return `actor.type must be a registered terminal actor for terminal-product subjects (one of: ${registeredTerminalActors().join(", ")}). Got "${type}".`;
         }
-        if ((config.actors[0]?.count ?? 1) > 1) {
-            return "Terminal fan-out to more than one participant is not supported yet; set actors[0].count to 1.";
+        if ((participantOrSurfaceCount(config) ?? 1) > 1) {
+            return "Terminal fan-out to more than one participant is not supported yet; set participants to 1.";
         }
     }
     else if (config.execution?.target === "e2b-terminal") {
@@ -271,7 +281,7 @@ function terminalValidationReason(config) {
         // 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)) {
+    else if (actorResolvesToTerminal(actorOf(config)?.type)) {
         // A registered terminal actor on a non-terminal-product subject: rejected, never ignored (the
         // terminal agent only studies a declared terminal-product from public surfaces).
         return "terminal actors require `subject.source: terminal-product` (a CLI/product the agent studies from public surfaces); other subjects are not supported on this route.";
@@ -283,7 +293,7 @@ function terminalValidationReason(config) {
 // Terminal actors were already refused above with their own message.
 function cloneActorValidationReason(config) {
     if (config.subject.source === "clone") {
-        const type = config.actors[0]?.type ?? "";
+        const type = actorOf(config)?.type ?? "";
         if (!actorResolvesToComputerUse(type) && !actorResolvesToScriptedBrowser(type)) {
             return `clone subjects need a registered computer-use actor (one of: ${registeredComputerUseActors().join(", ")}) or scripted-browser actor (one of: ${registeredScriptedBrowserActors().join(", ")}); humanish clones and serves the app for that participant to drive. Got "${type}".`;
         }

package/dist/study/config.d.ts

@@ -1,15 +1,38 @@
-import { type StudyParseResult } from "./types.js";
-/** The message for a humanish.lab.v2 document, which the package and the CLI no longer run. */
-export declare const V2_UNSUPPORTED_MESSAGE = "This is a humanish.lab.v2 study, which humanish no longer reads. Convert its file with humanish migrate <path>.";
+import { type StudyConfig, type StudyParseFailure, type StudyParseResult } from "./types.js";
 /**
  * The package's study parser (src/index.ts) and the one discovery uses: a humanish.study.v3
  * document. It refuses a humanish.lab.v2 one with HUMANISH_STUDY_V2_UNSUPPORTED.
  */
 export declare function parseStudy(raw: unknown): StudyParseResult;
+interface StudyV3Options {
+    /**
+     * `report`, for `humanish migrate`: list the fields the route does not read in `inert`, in place
+     * of refusing the study for them. 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: StudyConfig;
+    warnings: string[];
+    inert?: string[];
+} | StudyParseFailure;
 /**
- * Validate a parsed YAML object, humanish.study.v3 or humanish.lab.v2, into a StudyConfig. Pure:
- * the caller owns file IO. Structural validation only. Fields the engine does not yet consume are
- * accepted but reported in `warnings` so `study show` never silently swallows a setting that does
- * nothing. migrate's conversion (convert.ts) calls it directly, since it reads v2 files.
+ * Validate a humanish.study.v3 document into a StudyConfig. Pure: the caller owns file IO. Fields the
+ * route does not read refuse the study; migrate's report mode lists them in `inert` instead.
  */
-export declare function parseStudyDocument(raw: unknown): StudyParseResult;
+export declare function parseStudyV3(raw: Record<string, unknown>, options?: StudyV3Options): StudyV3ParseResult;
+/** Why runStudy refuses a config before anything runs. */
+interface ConfigRefusal {
+    readonly code: "HUMANISH_STUDY_V2_UNSUPPORTED" | "HUMANISH_STUDY_INVALID";
+    readonly message: string;
+}
+/**
+ * Why runStudy refuses a config a library caller passes, or undefined: a humanish.lab.v2 config,
+ * one that still sets a StudyConfig field of humanish 0.110, one with no `actor` object, and one
+ * whose `route` is not the route its subject and actor take, with parseStudy's message. A planner
+ * reads only the v3 fields, so a budget left in `execution.caps` would otherwise run uncapped.
+ */
+export declare function libraryConfigRefusal(config: StudyConfig): ConfigRefusal | undefined;
+export {};