humanish 0.110.3 → 0.110.4

package/dist/routes/terminal/session.js

@@ -111,6 +111,7 @@ export async function runLiveTerminalSession(args) {
         if ((await session.bootstrap()) &&
             (await session.verifyRuntimeVersion()) &&
             (await session.prepareProduct())) {
+            run.participantStarted();
             await session.execCodex();
         }
     }

package/dist/run/display.d.ts

@@ -57,3 +57,13 @@ export declare function bundleDisplayFacts(bundle: DisplayedBundle, status?: unk
  * execution failed never reads as a pass beside its participants' verdict.
  */
 export declare function reviewOutcome(bundle: DisplayedBundle): string;
+/**
+ * The summary and gaps a review shows beside its run's display. A run stopped while a participant
+ * was still running keeps the review its last live flush wrote, which describes that session as
+ * running. Once runDisplay reads the run as interrupted, the review says how many participants the
+ * stop cut off instead.
+ */
+export declare function displayedReview<T extends {
+    summary: string;
+    gaps: string[];
+}>(review: T, bundle: DisplayedBundle, display: RunDisplay): T;

package/dist/run/display.js

@@ -3,6 +3,7 @@
 // same facts, so a run whose own ok is false shows as a pass on none of them, and two surfaces
 // cannot disagree about one run.
 import { classifyRunStatus, isRunStatusRecord } from "./status.js";
+import { plural } from "./text.js";
 const LABELS = {
     running: "running",
     interrupted: "interrupted",
@@ -104,3 +105,24 @@ export function bundleDisplayFacts(bundle, status, nowMs = Date.now()) {
 export function reviewOutcome(bundle) {
     return runDisplayLine(runDisplay(bundleDisplayFacts(bundle)));
 }
+/**
+ * The summary and gaps a review shows beside its run's display. A run stopped while a participant
+ * was still running keeps the review its last live flush wrote, which describes that session as
+ * running. Once runDisplay reads the run as interrupted, the review says how many participants the
+ * stop cut off instead.
+ */
+export function displayedReview(review, bundle, display) {
+    const records = bundle.simulations ?? [];
+    const running = records.filter((record) => record?.status === "running").length;
+    if (display.state !== "interrupted" || running === 0)
+        return review;
+    const signal = bundle.outcome?.state === "interrupted" ? ` by ${bundle.outcome.signal}` : "";
+    const one = running === 1;
+    return {
+        ...review,
+        summary: `Interrupted${signal} while ${running} of ${plural(records.length, "participant")} ${one ? "was" : "were"} still running.`,
+        gaps: [
+            `${plural(running, "participant")} ${one ? "has" : "have"} no verdict: the run stopped before ${one ? "its session" : "their sessions"} ended.`,
+        ],
+    };
+}

package/dist/run/reclaim.d.ts

@@ -20,9 +20,10 @@ export interface ReclaimResult {
     createsInFlight: number;
     /**
      * Why there was nothing to look for: `dry-run` when run.json or status.json records the run as
-     * a dry run, which creates no sandboxes. Reclaim then contacts E2B for nothing.
+     * a dry run, which creates no sandboxes, and `no-sandbox` when status.json records that the
+     * route created none for this run. Reclaim then contacts E2B for nothing.
      */
-    reason?: "dry-run";
+    reason?: NoSandboxReason;
     warnings: string[];
     error?: {
         code: "HUMANISH_RECLAIM_RUN_NOT_FOUND" | "HUMANISH_RECLAIM_E2B_DEBUG" | "HUMANISH_RECLAIM_MODULE_UNAVAILABLE" | "HUMANISH_RECLAIM_RECEIPTS_UNREADABLE";
@@ -47,6 +48,7 @@ export declare function reclaimRunSandboxes(cwd: string, runInput: string, hooks
  * also an alias (a run named `latest`) cannot reach another run's receipts.
  */
 export declare function reclaimPinnedRunSandboxes(cwd: string, runPaths: PreparedRunArtifactPaths, hooks?: ReclaimHooks): Promise<ReclaimResult>;
+type NoSandboxReason = "dry-run" | "no-sandbox";
 /**
  * Kill the sandboxes left by interrupted `humanish study check` probes. A probe journals under
  * .humanish/preflight/<probe-id>/ and removes the journal after a confirmed kill, so what is left

package/dist/run/reclaim.js

@@ -15,6 +15,7 @@ import { readRunJsonIfExists, resolveRunPath } from "./locate.js";
 import { RUN_BUNDLE_FILE } from "./bundle.js";
 import { RUN_STATUS_FILE } from "./status.js";
 import { isRecord } from "./type-guards.js";
+import { isRunOutcome } from "./bundle-shape.js";
 import { parseSandboxOwners, parseSandboxReceipts, SANDBOX_RECEIPTS_ARTIFACT, } from "./sandbox-receipts.js";
 import { sandboxOwnerTags, } from "./sandbox-creates.js";
 import { earlierOutcomes, GONE, RECLAIM_RECEIPT_ARTIFACT, RECLAIM_RESULT_SCHEMA, receiptWriter, rootState, searchTagSets, settledWithin, targetSet, } from "./reclaim-outcomes.js";
@@ -64,8 +65,9 @@ async function reclaimRun(cwd, runInput, locate, hooks) {
     }
     const runId = runIdOf(runPaths);
     // The signal handler passes the creates it stopped and decides from what they reported.
-    if (hooks.creates === undefined && (await recordedDryRun(runPaths)))
-        return { ...base, ok: true, state: "clean", runId, reason: "dry-run" };
+    const reason = hooks.creates === undefined ? await recordedNoSandbox(runPaths) : undefined;
+    if (reason !== undefined)
+        return { ...base, ok: true, state: "clean", runId, reason };
     const reclaimed = await reclaimRoot(runPaths, runId, hooks, warnings);
     if (reclaimed.kind === "module-unavailable")
         return {
@@ -93,29 +95,70 @@ async function reclaimRun(cwd, runInput, locate, hooks) {
     };
 }
 /**
- * Whether the run records that it was a dry run: run.json and status.json, each one present, say
- * `dry-run`. A run with neither record is not taken for one. A journal with any line in it, or an
- * earlier reclaim receipt that names a sandbox, means a create ran, so that run is reclaimed as a
- * live one whatever its records say.
+ * Why the run's own records say it created no sandbox. `dry-run`: run.json and status.json, each
+ * one present, say `dry-run`. `no-sandbox`: status.json, written at start, names this run and
+ * records `sandboxes: none`, which the route sets only when it has no way to create one (a
+ * scripted run against an app-url subject), and run.json agrees (scriptedAppUrlBundle). A status
+ * record alone can be stale or copied from another run, so it never decides on its own, and an
+ * empty journal alone never makes a run clean. A journal with any line in it, or an earlier
+ * reclaim receipt that names a sandbox, means a create ran, so that run is reclaimed as a live one
+ * whatever its records say.
  */
-async function recordedDryRun(runPaths) {
-    const modes = [];
-    for (const file of [RUN_BUNDLE_FILE, RUN_STATUS_FILE]) {
-        const record = await readRunJsonIfExists(runPaths, file);
-        if (isRecord(record))
-            modes.push(record.mode);
-    }
-    if (modes.length === 0 || modes.some((mode) => mode !== "dry-run"))
-        return false;
+async function recordedNoSandbox(runPaths) {
+    const bundle = await readRunJsonIfExists(runPaths, RUN_BUNDLE_FILE);
+    const status = await readRunJsonIfExists(runPaths, RUN_STATUS_FILE);
+    const records = [bundle, status].filter(isRecord);
+    const reason = records.length > 0 && records.every((record) => record.mode === "dry-run")
+        ? "dry-run"
+        : isRecord(status) &&
+            status.runId === runIdOf(runPaths) &&
+            status.sandboxes === "none" &&
+            scriptedAppUrlBundle(bundle, runIdOf(runPaths))
+            ? "no-sandbox"
+            : undefined;
+    if (reason === undefined)
+        return undefined;
     if (!(await containedPathAbsent(runPaths, RECLAIM_RECEIPT_ARTIFACT))) {
         const earlier = await readRunJsonIfExists(runPaths, RECLAIM_RECEIPT_ARTIFACT);
         if (!isRecord(earlier) || !Array.isArray(earlier.outcomes) || earlier.outcomes.length > 0)
-            return false;
+            return undefined;
     }
     if (await containedPathAbsent(runPaths, SANDBOX_RECEIPTS_ARTIFACT))
-        return true;
+        return reason;
     const journal = await readContainedRegularFile(runPaths, SANDBOX_RECEIPTS_ARTIFACT);
-    return journal !== null && journal.toString("utf8").trim() === "";
+    return journal !== null && journal.toString("utf8").trim() === "" ? reason : undefined;
+}
+/** The execution failure kinds that leave a sandbox or a provider's resources unconfirmed. */
+const CLEANUP_KINDS = new Set(["sandbox-cleanup", "provider-cleanup"]);
+/**
+ * run.json for `runId` agrees that its run could create no sandbox: the scripted route wrote it
+ * (each lifecycle event is a `scripted-lab.` one), its subject is not a provisioned clone (a clone
+ * records `subject`), it lists no provider resource and no desktop minutes, and its outcome marks
+ * no sandbox or provider cleanup unconfirmed. A run.json that is missing, unreadable or says
+ * otherwise does not agree.
+ */
+function scriptedAppUrlBundle(bundle, runId) {
+    if (!isRecord(bundle) || bundle.runId !== runId || bundle.subject !== undefined)
+        return false;
+    const { lifecycle, providerResources, cost, outcome } = bundle;
+    const scripted = Array.isArray(lifecycle) &&
+        lifecycle.length > 0 &&
+        lifecycle.every((entry) => isRecord(entry) &&
+            typeof entry.event === "string" &&
+            entry.event.startsWith("scripted-lab."));
+    if (!scripted)
+        return false;
+    if (providerResources !== undefined &&
+        !(Array.isArray(providerResources) && providerResources.length === 0))
+        return false;
+    if (cost !== undefined && !(isRecord(cost) && cost.desktopMinutes === null))
+        return false;
+    if (!isRunOutcome(outcome))
+        return false;
+    if (outcome.state !== "finished")
+        return true;
+    const { failures, warnings = [] } = outcome.execution;
+    return ![...failures, ...warnings].some((failure) => CLEANUP_KINDS.has(failure.kind));
 }
 /**
  * Kill the sandboxes left by interrupted `humanish study check` probes. A probe journals under

package/dist/run/run.d.ts

@@ -11,6 +11,8 @@ interface StartRunOptions {
     mintRunId: () => string;
     mode: "dry-run" | "live";
     study?: RunStudyProvenance | undefined;
+    /** `none` when the route creates no sandbox for this run; status.json records it for reclaim. */
+    sandboxes?: "none" | undefined;
     /** review.md for the published bundle. */
     renderReview: (bundle: RunBundle) => string;
     /** Used by `FinishedRun.renderObserver`; `render` is the `StudyDeps.renderObserver` seam. */
@@ -52,6 +54,12 @@ interface Run {
      * can never overwrite the final bundle. Routes that throttle snapshots own their timers.
      */
     writeSnapshot(bundle: RunBundle): Promise<void>;
+    /**
+     * A participant's session started: its actor began to act on the subject. FinishedRun's
+     * participantsRan reads this, so a session that throws before it returns a trace still counts,
+     * and a run that failed before any session (a refused E2B key) does not.
+     */
+    participantStarted(): void;
     /**
      * The one final publication: run.json with `outcome` set from `outcome`, then the status
      * outcome copied from it, then review.json, review.md, events.ndjson,
@@ -92,12 +100,14 @@ export declare class FinishedRun {
     readonly runId: string;
     /** The paths created by startRun and validated at the start of `finish`. */
     readonly paths: PreparedRunArtifactPaths;
-    constructor(key: typeof issueKey, runId: string, paths: PreparedRunArtifactPaths, observer: ObserverTarget | undefined, outcome: RecordedOutcome, recordFailure: (failure: ExecutionFailure) => Promise<RecordedOutcome>, interrupted: () => boolean);
+    constructor(key: typeof issueKey, runId: string, paths: PreparedRunArtifactPaths, observer: ObserverTarget | undefined, outcome: RecordedOutcome, recordFailure: (failure: ExecutionFailure) => Promise<RecordedOutcome>, interrupted: () => boolean, participantsRan: () => boolean);
     /**
      * A signal stopped this run's process: status.json and run.json record it `interrupted`. Read
      * when asked, since the signal can arrive after the bundle was published.
      */
     get interrupted(): boolean;
+    /** The route reported a participant's session started (Run.participantStarted). */
+    get participantsRan(): boolean;
     static isIssued(value: unknown): value is FinishedRun;
     /**
      * The run's ok and execution outcome as run.json records them: what the route passed to

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/study/composition-rules.js

@@ -10,7 +10,7 @@ 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 first composition rule a config breaks, in the parser's order, or null. */
 export function compositionReason(config) {
     return (thisRepoValidationReason(config) ??
@@ -25,7 +25,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 +39,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 +54,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. Set participants to 1 and drop participants (use an app-url or clone subject on execution.target: e2b-desktop for fan-out).";
         }
-        if (rosterOf(config.actors[0]) !== undefined) {
-            return "`actors[0].lanes` (fan-out roster) is not supported on the in-process/local-app route: it provisions one E2B desktop per participant, which this route skips. Use an app-url or clone subject with execution.target: e2b-desktop.";
+        if (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 +78,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 ((surfaceCount(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,7 +106,7 @@ 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
@@ -116,7 +116,7 @@ function appUrlValidationReason(config) {
             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 +125,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).";
         }
@@ -148,14 +148,14 @@ function scriptedBrowserValidationReason(config) {
         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 ((surfaceCount(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 +183,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.";
         }
@@ -210,8 +210,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 +238,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 +255,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 ((declaredParticipantCount(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 +271,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 +283,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,4 +1,4 @@
-import { type StudyParseResult } from "./types.js";
+import { type StudyConfig, 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>.";
 /**
@@ -10,6 +10,13 @@ export declare function parseStudy(raw: unknown): StudyParseResult;
  * 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.
+ * nothing. The v2 parser's tests call it directly; migrate reads v2 files through migrate/v2.ts.
  */
 export declare function parseStudyDocument(raw: unknown): StudyParseResult;
+/**
+ * The checks that read more than one section of a parsed config, and the defaults they fill:
+ * shared-world `execution.concurrency`, `comms.email.recipients` and the local browser's defaults.
+ * parseV2 runs them once every section has parsed. parse/study.ts runs them on its v2 view of a v3
+ * study.
+ */
+export declare function checkStudyConfig(config: StudyConfig): StudyParseResult;