humanish 0.117.0 → 0.119.0

package/dist/study/plan-types.d.ts

@@ -5,6 +5,7 @@ import type { BrowserSurface } from "../actors/scripted-browser/types.js";
 import type { ScriptedRefusal } from "../routes/scripted/plan.js";
 import type { TerminalRefusal } from "../routes/terminal/plan.js";
 import type { RunStudyProvenance } from "../run/study-provenance.js";
+import type { ArrivalPlan } from "./arrivals.js";
 import type { ComputerUseRefusal } from "../routes/computer-use/plan.js";
 import type { SharedWorldRefusal } from "../routes/shared-world/plan.js";
 import type { ComputerUseParticipant, ExternalPublicParticipant, ProvisionedParticipant } from "./plan-participants.js";
@@ -63,7 +64,8 @@ interface PlanBase {
     /** The study's declared title, which bundles record. */
     readonly title?: string;
     readonly study?: RunStudyProvenance;
-    /** Warnings about the study's own fields, which the run records in its bundle as warn events. */
+    /** Warnings about the study's own fields and the plan made from them, which the run records in
+     *  its bundle as warn events. */
     readonly warnings?: readonly string[];
     /** A frozen copy owned by the plan. */
     readonly residual: Readonly<ResidualConfig>;
@@ -162,6 +164,8 @@ export interface ComputerUsePlan extends PlanBase {
     readonly runner: ComputerUseRunner;
     /** Declared cap clamped to [1, participants]; the route may only lower it from env. */
     readonly concurrency: number;
+    /** When the participants start and how many run at once, with every session at its budget. */
+    readonly arrivals: ArrivalPlan;
     readonly sessionBudgetMs: number;
     readonly sandboxMs: number;
     readonly caps: {
@@ -196,6 +200,11 @@ export interface SharedWorldPlan extends PlanBase {
     readonly plane: SharedWorldPlane;
     /** At least 2. */
     readonly concurrency: number;
+    /**
+     * When the participants start and how many run at once, with every session at its budget. On
+     * the provisioned plane the subject sandbox serves until `lastEndMs`.
+     */
+    readonly arrivals: ArrivalPlan;
     /** Each participant's session budget: execution.timeoutMs, else the plane's derived default. */
     readonly sessionTimeoutMs: number;
     readonly brain: Extract<Brain, {
@@ -258,9 +267,10 @@ export interface ScriptedPlan extends PlanBase {
     readonly scenarioRef: string;
     /** Empty only for a library caller's `count: 0`, which the parser refuses; that run has no sessions. */
     readonly surfaces: readonly BrowserSurface[];
-    /** The declared persona and session timeout; the route supplies its defaults. */
+    /** The declared persona; the route supplies its default. */
     readonly personaId?: string;
-    readonly sessionTimeoutMs?: number;
+    /** Each surface's journey budget: execution.timeoutMs, else 5 minutes. */
+    readonly sessionTimeoutMs: number;
 }
 export type StudyPlan = PreviewPlan | ComputerUsePlan | SharedWorldPlan | TerminalPlan | ScriptedPlan;
 interface PlannedStudy {

package/dist/study/plan.d.ts

@@ -7,9 +7,9 @@ export { routeOf, type StudyRoute } from "./routing.js";
 export declare function resolveStudyDryRun(config: StudyConfig, override: boolean | undefined, fallback: boolean | undefined): boolean | undefined;
 /**
  * The plan a study runs under, built without reading files or the network. From the environment
- * (options.env, else process.env, as the routes read it) it reads one value, the E2B sandbox
- * ceiling, which no study file can know. Each route's planner makes every refusal that route
- * makes, in the route's order and with its codes and messages; the route's exported runner calls
- * the same planner.
+ * (options.env, else process.env, as the routes read it) it reads the operator's E2B plan limits,
+ * the sandbox ceiling and the concurrent sandboxes, which no study file can know. Each route's
+ * planner makes every refusal that route makes, in the route's order and with its codes and
+ * messages; the route's exported runner calls the same planner.
  */
 export declare function planStudy(config: StudyConfig, options: InternalRunStudyOptions, deps?: StudyDeps): PlanResult;

package/dist/study/plan.js

@@ -6,7 +6,7 @@ import { callerDrivingOf, planComputerUseStudy } from "../routes/computer-use/pl
 import { injectedBrowser, planScriptedStudy } from "../routes/scripted/plan.js";
 import { planSharedWorldStudy } from "../routes/shared-world/plan.js";
 import { planTerminalStudy } from "../routes/terminal/plan.js";
-import { sandboxCeiling } from "../substrates/e2b/lifetime.js";
+import { concurrentSandboxes, sandboxCeiling, } from "../substrates/e2b/lifetime.js";
 import { localBrowserDefaults } from "../substrates/local/runtime-config.js";
 import { THIS_REPO_DRY_RUN_ONLY } from "./composition-rules.js";
 import { planBase } from "./plan-base.js";
@@ -65,21 +65,25 @@ function planPreview(config, options, input) {
 }
 /**
  * The plan a study runs under, built without reading files or the network. From the environment
- * (options.env, else process.env, as the routes read it) it reads one value, the E2B sandbox
- * ceiling, which no study file can know. Each route's planner makes every refusal that route
- * makes, in the route's order and with its codes and messages; the route's exported runner calls
- * the same planner.
+ * (options.env, else process.env, as the routes read it) it reads the operator's E2B plan limits,
+ * the sandbox ceiling and the concurrent sandboxes, which no study file can know. Each route's
+ * planner makes every refusal that route makes, in the route's order and with its codes and
+ * messages; the route's exported runner calls the same planner.
  */
 export function planStudy(config, options, deps = {}) {
     const study = localBrowserDefaults(config);
     const input = { dryRun: resolveStudyDryRun(study, options.dryRun, true) ?? true };
-    const ceiling = sandboxCeiling(options.env ?? process.env);
-    const result = planRoute(routeOf(config), study, options, input, deps, ceiling);
+    const env = options.env ?? process.env;
+    const e2b = {
+        sandboxCeiling: sandboxCeiling(env),
+        concurrentSandboxes: concurrentSandboxes(env),
+    };
+    const result = planRoute(routeOf(config), study, options, input, deps, e2b);
     if (!result.ok)
         return result;
     // The manifest the CLI resolved enters the plan here and nowhere else; the routes read
     // plan.study for the run's status record and bundle, and plan.warnings for its bundle events.
-    const warnings = recordedStudyWarnings(study);
+    const warnings = [...recordedStudyWarnings(study), ...(result.plan.warnings ?? [])];
     const plan = {
         ...result.plan,
         ...(options.study === undefined ? {} : { study: options.study }),
@@ -87,7 +91,8 @@ export function planStudy(config, options, deps = {}) {
     };
     return { ok: true, planned: { plan } };
 }
-function planRoute(route, study, options, input, deps, sandboxCeiling) {
+function planRoute(route, study, options, input, deps, e2b) {
+    const { sandboxCeiling } = e2b;
     switch (route) {
         case "preview":
             return planPreview(study, options, input);
@@ -98,13 +103,13 @@ function planRoute(route, study, options, input, deps, sandboxCeiling) {
                 driving: callerDrivingOf(options),
                 ...(options.count === undefined ? {} : { countOverride: options.count }),
                 ...(options.rerun === undefined ? {} : { rerun: options.rerun }),
-                sandboxCeiling,
+                ...e2b,
             });
         case "shared-world":
             return planSharedWorldStudy(study, {
                 ...input,
                 hasRunSession: deps.runSession !== undefined,
-                sandboxCeiling,
+                ...e2b,
             });
         case "terminal":
             return planTerminalStudy(study, {
@@ -113,6 +118,10 @@ function planRoute(route, study, options, input, deps, sandboxCeiling) {
                 sandboxCeiling,
             });
         case "scripted":
-            return planScriptedStudy(study, { ...input, injectedBrowser: injectedBrowser(deps) });
+            return planScriptedStudy(study, {
+                ...input,
+                injectedBrowser: injectedBrowser(deps),
+                sandboxCeiling,
+            });
     }
 }

package/dist/study/preflight.d.ts

@@ -3,6 +3,7 @@ import type { E2BDesktopModule } from "../substrates/e2b/sdk.js";
 import { type StudyConfig } from "./types.js";
 import { STUDY_CHECK_SCHEMA } from "./preflight-result.js";
 import { type StudyRoute } from "./plan.js";
+import type { PlanRefusal } from "./plan-types.js";
 import { type StudyResolveFailure } from "./discover.js";
 export type StudyPreflightReachabilityMode = "metadata" | "public-preview" | "sandbox-loopback" | "prepared-host";
 export interface StudyPreflightCheck {
@@ -57,7 +58,7 @@ export interface StudyPreflightResult {
     spend: StudyPreflightSpend;
     warnings: string[];
     error?: {
-        code: StudyResolveFailure["error"]["code"] | "HUMANISH_STUDY_PREFLIGHT_INVALID_OPTION" | "HUMANISH_STUDY_PREFLIGHT_UNSUPPORTED_ROUTE" | "HUMANISH_STUDY_PREFLIGHT_TARGET_POLICY" | "HUMANISH_STUDY_PREFLIGHT_ENV_MISSING" | "HUMANISH_STUDY_PREFLIGHT_E2B_REQUIRED" | "HUMANISH_STUDY_PREFLIGHT_TARGET_UNREACHABLE" | "HUMANISH_STUDY_PREFLIGHT_PROVISION_FAILED" | "HUMANISH_STUDY_PREFLIGHT_TEARDOWN_FAILED";
+        code: StudyResolveFailure["error"]["code"] | "HUMANISH_STUDY_PREFLIGHT_INVALID_OPTION" | "HUMANISH_STUDY_PREFLIGHT_UNSUPPORTED_ROUTE" | "HUMANISH_STUDY_PREFLIGHT_TARGET_POLICY" | "HUMANISH_STUDY_PREFLIGHT_ENV_MISSING" | "HUMANISH_STUDY_PREFLIGHT_E2B_REQUIRED" | "HUMANISH_STUDY_PREFLIGHT_TARGET_UNREACHABLE" | "HUMANISH_STUDY_PREFLIGHT_PROVISION_FAILED" | "HUMANISH_STUDY_PREFLIGHT_TEARDOWN_FAILED" | PlanRefusal["code"];
         message: string;
     };
 }

package/dist/study/preflight.js

@@ -4,8 +4,9 @@ import path from "node:path";
 import { isLoopbackUrl } from "./parse/subject.js";
 import {} from "./types.js";
 import { runPublicPreviewPreflight, runSandboxLoopbackPreflight } from "./preflight-probes.js";
-import { digest, finalize, STUDY_CHECK_SCHEMA } from "./preflight-result.js";
-import { routeOf } from "./plan.js";
+import { digest, fail, finalize, STUDY_CHECK_SCHEMA } from "./preflight-result.js";
+import { planStudy, routeOf } from "./plan.js";
+import { describeArrivals } from "./arrivals.js";
 import { resolveStudyManifest } from "./discover.js";
 import { participantList } from "./study-fields.js";
 import { isLocalBrowserStudy } from "../substrates/local/runtime-config.js";
@@ -42,6 +43,7 @@ export async function runStudyPreflight(options) {
         ? new Map()
         : (await resolveCommittedPersonasForCwd(cwd, studyPersonaIds(resolved.config))).personas;
     const route = routeOf(resolved.config);
+    const env = options.env ?? process.env;
     const ctx = {
         cwd,
         study: options.study,
@@ -52,7 +54,7 @@ export async function runStudyPreflight(options) {
         route,
         reachability,
         timeoutMs,
-        env: options.env ?? process.env,
+        env,
         hooks: options.hooks ?? {},
         checks: [
             { name: "study file", ok: true, message: `resolved ${resolved.origin} study file` },
@@ -65,6 +67,17 @@ export async function runStudyPreflight(options) {
             ...personaBackgroundWarnings(resolved.config.id, participants, personas),
         ],
     };
+    // The plan `humanish run <study>` makes before it creates anything: no run options, so the file's
+    // mode decides dry or live, and the same environment for the sandbox ceiling. A study the run
+    // would refuse fails here with the run's code, before any probe creates a sandbox.
+    const planned = planStudy(resolved.config, { cwd, env });
+    if (!planned.ok) {
+        const { code, message } = planned.refusal;
+        return fail(ctx, code, message, [{ name: "plan", ok: false, message }]);
+    }
+    const schedule = scheduleCheck(planned.planned.plan);
+    if (schedule !== undefined)
+        ctx.checks.push(schedule);
     const machine = machineCheck(ctx.config);
     // A local study's app and desktops run on this machine, so the hosted probes do not apply.
     if (reachability !== "metadata" && isLocalBrowserStudy(ctx.config))
@@ -109,6 +122,14 @@ export async function runStudyPreflight(options) {
             });
     }
 }
+/** The plan's schedule, for a study that declares when its participants start. */
+function scheduleCheck(plan) {
+    if (plan.route !== "computer-use" && plan.route !== "shared-world")
+        return undefined;
+    if (!plan.arrivals.declared)
+        return undefined;
+    return { name: "schedule", ok: true, message: describeArrivals(plan.arrivals) };
+}
 /** What study check leaves to doctor: this machine's setup for the study, and the command. */
 function machineCheck(config) {
     const command = cli(`doctor --study ${config.id}`);

package/dist/study/routing.d.ts

@@ -1,5 +1,6 @@
 import type { StudyConfig } from "./types.js";
-export declare const MAX_COMPUTER_USE_PARTICIPANTS = 16;
+/** Why a study of `count` participants cannot run, or undefined when it can. */
+export declare function participantCountReason(count: number): string | undefined;
 export declare function actorResolvesToComputerUse(type: string | undefined): boolean;
 export declare function registeredComputerUseActors(): string[];
 export declare function actorResolvesToScriptedBrowser(type: string | undefined): boolean;
@@ -9,11 +10,11 @@ export declare function registeredScriptedBrowserActors(): string[];
 export declare function actorResolvesToTerminal(type: string | undefined): boolean;
 export declare function registeredTerminalActors(): string[];
 /**
- * The declared fan-out participant count on the computer-use route: a `participants` list's
- * length, else a participant count, else 1. The single source of truth shared by the parser, the engine,
+ * The fan-out participant count on the computer-use route: a `participants` list's length, else
+ * the caller's count override, else a participant count, else 1. The single source of truth shared by the parser, the engine,
  * and the pre-flight plan so the participant count is computed the same way everywhere.
  */
-export declare function computerUseParticipantCount(config: StudyConfig): number;
+export declare function computerUseParticipantCount(config: StudyConfig, countOverride?: number): number;
 /**
  * A participant's id: its declared roster id, else `lane-NN` (independent participants) or `role-NN`
  * (shared-world participants) from its 0-based position. The parser's filled email recipients and

package/dist/study/routing.js

@@ -1,9 +1,17 @@
 import { actorRegistry } from "../actors/registry.js";
 import { isLoopbackUrl } from "./parse/subject.js";
 import { participantList, declaredParticipantCount } from "./study-fields.js";
-// Hard cap on computer-use participants. No setting raises it: each participant is a paid desktop,
-// and they all run at once.
-export const MAX_COMPUTER_USE_PARTICIPANTS = 16;
+// The most participants one study holds, on any route. One run keeps every participant's stream in
+// one bundle, one Observer view and one analysis, and those are sized for 100: the analysis reads a
+// bundle of at most 128 streams. How many run at once is a separate limit, the E2B plan's
+// (concurrentSandboxes in substrates/e2b/lifetime.ts), and caps.maxUsd bounds what they spend.
+const MAX_STUDY_PARTICIPANTS = 100;
+/** Why a study of `count` participants cannot run, or undefined when it can. */
+export function participantCountReason(count) {
+    return count > MAX_STUDY_PARTICIPANTS
+        ? `A study runs at most ${MAX_STUDY_PARTICIPANTS} participants, and this one has ${count}. One run keeps every participant's evidence in one bundle and one Observer view, and humanish supports runs of up to ${MAX_STUDY_PARTICIPANTS}; split the participants across studies.`
+        : undefined;
+}
 // Run kinds whose evidence is the participant's screenshots. An actor that declares it produces none
 // cannot run on them: a code-only actor would claim a GUI flow it only reached through a shell.
 const SCREENSHOT_RUN_KINDS = new Set([
@@ -46,12 +54,13 @@ export function registeredTerminalActors() {
     return registeredActorsOn("terminal");
 }
 /**
- * The declared fan-out participant count on the computer-use route: a `participants` list's
- * length, else a participant count, else 1. The single source of truth shared by the parser, the engine,
+ * The fan-out participant count on the computer-use route: a `participants` list's length, else
+ * the caller's count override, else a participant count, else 1. The single source of truth shared by the parser, the engine,
  * and the pre-flight plan so the participant count is computed the same way everywhere.
  */
-export function computerUseParticipantCount(config) {
-    return participantList(config)?.length ?? declaredParticipantCount(config) ?? 1;
+export function computerUseParticipantCount(config, countOverride) {
+    return (participantList(config)?.length ??
+        Math.max(1, countOverride ?? declaredParticipantCount(config) ?? 1));
 }
 /**
  * A participant's id: its declared roster id, else `lane-NN` (independent participants) or `role-NN`

package/dist/study/types.d.ts

@@ -319,6 +319,12 @@ export interface StudyParticipantEntry {
      * into the follower missions at a host-first barrier. Inert/warned on every other route.
      */
     host?: boolean;
+    /**
+     * Computer use and shared world: when this participant starts, in milliseconds after the run
+     * starts its participants (0 to 86,400,000). A group's `startEveryMs` sets it for each member.
+     * Absent, the participant starts with the run. src/study/arrivals.ts schedules the start.
+     */
+    startAfterMs?: number;
 }
 export interface StudyActor {
     /**
@@ -783,6 +789,14 @@ export interface StudyParticipantGroup {
     count?: number;
     instruction?: string;
 }
+/**
+ * The keys a `participants` list entry with `count` adds to an entry's. parseStudy expands the
+ * group into its members, and member k starts at `startAfterMs + (k - 1) * startEveryMs`.
+ */
+export interface StudyParticipantListGroup {
+    count?: number;
+    startEveryMs?: number;
+}
 /** The scripted surfaces: desktop, or desktop and mobile. */
 export type StudySurfaces = readonly ["desktop"] | readonly ["desktop", "mobile"];
 interface StudyParseSuccess {

package/dist/study/validation.d.ts

@@ -2,8 +2,8 @@ import type { StudyConfig } from "./types.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
- * that skipped the parser. It runs rosterStructuralValidationReason (id and device
- * validity, unique ids) first, then the route-scoped XOR, cap and policy checks.
+ * that skipped the parser. It runs rosterStructuralValidationReason (roster size, id and device
+ * validity, unique ids) first, then the route-scoped XOR, participant count and policy checks.
  */
 export declare function computerUseValidationReason(config: StudyConfig): string | null;
 /**

package/dist/study/validation.js

@@ -1,15 +1,17 @@
 import { isMaxOutputTokens } from "../actors/output-token-limit.js";
+import { MAX_RECEIVING_INBOXES } from "../comms/receiving-types.js";
 import { waitFieldsReason } from "../actors/computer-use/wait.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 { actorResolvesToComputerUse, computerUseParticipantCount, participantCountReason, registeredComputerUseActors, resolveEntryUrl, isComputerUseComposition, isScriptedBrowserComposition, isSharedWorldComposition, isTerminalProductComposition, } from "./routing.js";
 import { participantList } from "./study-fields.js";
+import { isStartAfterMs, rosterStartsReason, startAfterMessage } from "./arrivals.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
- * that skipped the parser. It runs rosterStructuralValidationReason (id and device
- * validity, unique ids) first, then the route-scoped XOR, cap and policy checks.
+ * that skipped the parser. It runs rosterStructuralValidationReason (roster size, id and device
+ * validity, unique ids) first, then the route-scoped XOR, participant count and policy checks.
  */
 export function computerUseValidationReason(config) {
     const roster = participantList(config);
@@ -42,9 +44,9 @@ export function computerUseValidationReason(config) {
         }
     }
     const participantCount = computerUseParticipantCount(config);
-    if (participantCount > MAX_COMPUTER_USE_PARTICIPANTS) {
-        return `A computer-use study runs at most ${MAX_COMPUTER_USE_PARTICIPANTS} participants, and this one declares ${participantCount}. Each participant is a paid desktop and they all run at once, so no setting raises the cap; split the roster across studies.`;
-    }
+    const countReason = participantCountReason(participantCount);
+    if (countReason)
+        return countReason;
     // 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
@@ -60,8 +62,8 @@ export function computerUseValidationReason(config) {
     return null;
 }
 /**
- * Engine-level path-token validation for configs supplied directly through the
- * public TypeScript/JavaScript API instead of parseStudy.
+ * Engine-level roster validation (its size and its ids' path tokens) for configs supplied directly
+ * through the public TypeScript/JavaScript API instead of parseStudy.
  */
 function rosterStructuralValidationReason(config) {
     const roster = participantList(config);
@@ -70,10 +72,16 @@ function rosterStructuralValidationReason(config) {
         if (!Array.isArray(roster) || roster.length === 0) {
             return "participants must be a non-empty array when set.";
         }
+        const countReason = participantCountReason(roster.length);
+        if (countReason)
+            return countReason;
         for (const [index, entry] of roster.entries()) {
             if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
                 return `participants[${index}] must be an object.`;
             }
+            if (entry.startAfterMs !== undefined && !isStartAfterMs(entry.startAfterMs)) {
+                return startAfterMessage(`participants[${index}].startAfterMs`);
+            }
             const id = entry.id;
             if (id === undefined) {
                 continue;
@@ -88,6 +96,7 @@ function rosterStructuralValidationReason(config) {
             }
             seenIds.add(id);
         }
+        return rosterStartsReason(roster) ?? null;
     }
     return null;
 }
@@ -195,6 +204,10 @@ 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.";
     }
+    const participants = computerUseParticipantCount(config);
+    if (participants > MAX_RECEIVING_INBOXES) {
+        return `Real email receiving leases one inbox per participant, at most ${MAX_RECEIVING_INBOXES} per run, and this study has ${participants} participants. Run at most ${MAX_RECEIVING_INBOXES} participants with a real inbox, or split them across studies.`;
+    }
     if (config.actor?.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.";
     }
@@ -245,14 +258,14 @@ export function waitLimitValidationReason(config) {
 }
 /**
  * Shared-world participants share one live app, so at least two must be live at once. The
- * sequential shared-world route (`execution.concurrency: 1`) was removed in 0.106.0; the parser
- * fills an omitted concurrency with the participant count. Both callers check it after their
- * two-participant roster floor, so a one-participant roster gets the roster refusal, never this
- * one.
+ * sequential shared-world route (`execution.concurrency: 1`) was removed in 0.106.0. An omitted
+ * concurrency runs every participant, up to the E2B plan's limit, which the planner checks. Both
+ * callers check it after their two-participant roster floor, so a one-participant roster gets the
+ * roster refusal, never this one.
  */
 function sharedWorldConcurrencyReason(config) {
-    // Direct library callers skip the parser, so an omitted value defaults here exactly as the
-    // route does: to the participant count. A missing roster reads as 0 and is refused.
+    // An omitted value runs every participant, so it is checked as the participant count. A missing
+    // roster reads as 0 and is refused.
     const participants = participantList(config)?.length ?? 0;
     const concurrency = config.execution?.concurrency ?? participants;
     if (concurrency >= 2)

package/dist/study/warnings.js

@@ -302,11 +302,19 @@ export function forwardDeclaredWarnings(config) {
         ];
     // A declared cap below the participant count is legal but loud: the roster promises N live actors
     // and the cap delivers waves of M. Say so up front (inspect + dry-run + run): a green run in
-    // waves is otherwise indistinguishable from the all-live run the author meant.
+    // waves is otherwise indistinguishable from the all-live run the author meant. A roster that
+    // declares when its participants start never promised them all at once; the plan's schedule
+    // says who waits for a slot.
     {
-        const participantCount = participantList(config)?.length ?? declaredParticipantCount(config) ?? 1;
+        const roster = participantList(config);
+        const participantCount = roster?.length ?? declaredParticipantCount(config) ?? 1;
         const cap = config.execution?.concurrency;
-        if (routes.cua && cap !== undefined && participantCount > 1 && cap < participantCount) {
+        const scheduled = roster?.some((entry) => entry.startAfterMs !== undefined) === true;
+        if (routes.cua &&
+            !scheduled &&
+            cap !== undefined &&
+            participantCount > 1 &&
+            cap < participantCount) {
             warnings.push(`execution.concurrency ${cap} caps a ${participantCount}-participant roster: participants run in waves of ${cap}, never all live at once. Remove execution.concurrency (the default runs all ${participantCount} participants simultaneously) or set it to ${participantCount}; declare a lower cap only to bound simultaneous paid desktops.`);
         }
     }

package/dist/substrates/e2b/lifetime.d.ts

@@ -24,9 +24,80 @@ export declare function describeSandboxCeiling(ceiling: SandboxCeiling): string;
  * setting value that would admit it, when an E2B plan allows that long.
  */
 export declare function ceilingAdvice(deadlineMs: number): string;
-/** Server-side reclamation buffer past a participant's own wall-clock stop. */
-export declare const SANDBOX_TIMEOUT_BUFFER_MS: number;
-/** Room a provisioned subject adds to the sandbox deadline for clone, install, build, start and probe. */
-export declare const SUBJECT_PROVISION_BUDGET_MS: number;
+/**
+ * How many sandboxes humanish runs at once, and whether it is the default or the setting; or why
+ * the setting cannot be read.
+ */
+export type ConcurrentSandboxes = {
+    readonly ok: true;
+    readonly count: number;
+    readonly source: "default" | "setting";
+} | {
+    readonly ok: false;
+    readonly message: string;
+};
+/**
+ * The concurrent sandbox limit: HUMANISH_E2B_MAX_CONCURRENT_SANDBOXES when set, else 20. E2B
+ * refuses a create past the plan's limit, and neither its API nor its SDK says which plan a key is
+ * on, so the operator states it, as for the sandbox ceiling. A study that would run more desktops
+ * at once is refused or run in waves at plan time, before a create fails mid-run.
+ */
+export declare function concurrentSandboxes(env: Readonly<Record<string, string | undefined>>): ConcurrentSandboxes;
+/** The limit in use and where it came from, or why the setting cannot be read (doctor's row). */
+export declare function describeConcurrentSandboxes(limit: ConcurrentSandboxes): string;
+/**
+ * How many participants a hosted study runs at once: its `concurrency` (the declared
+ * execution.concurrency clamped to the roster, else every participant), lowered to what the plan
+ * runs. `declared` says whether the study set it. `alongside` counts the sandboxes the study keeps
+ * for the whole run besides its participants' desktops, such as a shared world's app, and
+ * `minimum` is the fewest at once the route can run. A declared value that does not fit is a
+ * refusal naming the setting value that admits it. `lowered` is the warning a plan records when
+ * the limit holds an undeclared default to waves.
+ */
+export declare function participantsAtOnce(study: {
+    readonly concurrency: number;
+    readonly declared: boolean;
+    readonly participants: number;
+    readonly alongside?: number;
+    readonly minimum?: number;
+}, limit: ConcurrentSandboxes): {
+    readonly ok: true;
+    readonly count: number;
+    readonly lowered?: string;
+} | {
+    readonly ok: false;
+    readonly message: string;
+};
+/**
+ * What a sandbox's server-side timeout adds to the session it hosts: the teardown buffer, and on a
+ * sandbox that serves the subject, the provisioning budget and each seed step's budget. A planner
+ * adds it to the session to get the deadline it checks against the ceiling, and the route adds it
+ * to set the timeout it asks E2B for.
+ */
+export declare function sandboxHeadroomMs(servedSubject?: {
+    readonly seed: readonly {
+        readonly timeoutMs?: number | undefined;
+    }[];
+}): number;
+/** A sandbox a plan will ask E2B for, as its deadline refusal describes it. */
+export interface PlannedSandbox {
+    /** How the refusal names the sandbox, as in "the subject sandbox". */
+    readonly name: string;
+    /** The session it hosts, and whether the study set it in execution.timeoutMs. */
+    readonly sessionMs: number;
+    readonly sessionDeclared: boolean;
+    /** The subject it serves, whose provisioning and seed steps add to its deadline. */
+    readonly servedSubject?: {
+        readonly seed: readonly {
+            readonly timeoutMs?: number | undefined;
+        }[];
+    } | undefined;
+}
+/**
+ * Why the sandbox's deadline, its session plus sandboxHeadroomMs, passes the `ceilingMs` ceiling,
+ * or undefined when it fits. The message shows the arithmetic, the longest execution.timeoutMs the
+ * ceiling leaves, and the setting value that would admit the study.
+ */
+export declare function sandboxDeadlineRefusal(sandbox: PlannedSandbox, ceilingMs: number): string | undefined;
 /** The timeout of one E2B API request: HUMANISH_E2B_REQUEST_TIMEOUT_MS when set, else 60 s. */
 export declare function e2bRequestTimeoutMs(env: Record<string, string | undefined>): number;