humanish 0.117.0 → 0.119.0

package/dist/study/arrivals.d.ts

@@ -0,0 +1,114 @@
+import type { RunParticipantArrival } from "../run/bundle.js";
+/**
+ * The latest start a study may declare: 24 hours, the longest sandbox lifetime E2B documents. It
+ * also keeps every wait under Node's timer limit of 2^31 - 1 ms, past which a timer fires at once.
+ */
+export declare const LATEST_START_AFTER_MS: number;
+/** Whether `value` is a start offset humanish runs: whole milliseconds from 0 to 24 hours. */
+export declare function isStartAfterMs(value: unknown): value is number;
+/** The refusal of a start offset that is not one, naming its `field`. */
+export declare function startAfterMessage(field: string): string;
+/**
+ * Why a roster's declared starts cannot run, or undefined. A start orders participants against
+ * each other, so it needs two or more of them, and the host of an external public app opens the
+ * session the others join, so it starts with the run.
+ */
+export declare function rosterStartsReason(roster: readonly {
+    readonly id?: string;
+    readonly startAfterMs?: number;
+    readonly host?: boolean;
+}[]): string | undefined;
+/** What the plan says about when a run's participants start, with every session at its full budget. */
+export interface ArrivalPlan {
+    /** Whether any participant declares `startAfterMs`. */
+    readonly declared: boolean;
+    /** The earliest and the latest declared start, in ms after the run starts its participants. */
+    readonly firstStartMs: number;
+    readonly lastStartMs: number;
+    /** The most participants running at once. */
+    readonly peak: number;
+    /** How many participants wait past their time for a free slot, and the longest of those waits. */
+    readonly waiting: number;
+    readonly longestWaitMs: number;
+    /** When the last session ends at the latest, in ms after the run starts its participants. */
+    readonly lastEndMs: number;
+    /** The session budget every figure above assumes each participant uses. */
+    readonly sessionMs: number;
+}
+/** How the runtime starts participants: how many run at once, and for how long at most. */
+export interface StartQueue {
+    readonly slots: number;
+    readonly sessionMs: number;
+    /**
+     * The roster index of a participant that runs on a slot of its own, outside the queue: the
+     * external-public host, which the others wait on. It counts against `slots`.
+     */
+    readonly ownSlot?: number;
+}
+/**
+ * The schedule a roster's declared offsets give under the queue (`undefined` is 0: the participant
+ * starts with the run). Participants start in schedule order, by offset and then roster position,
+ * each at its time or when a slot frees, whichever is later; this is the rule runOnSchedule
+ * follows.
+ */
+export declare function planArrivals(offsets: readonly (number | undefined)[], queue: StartQueue): ArrivalPlan;
+/**
+ * The plan's schedule, after a "schedule:" label: the first and last start, and how many run at
+ * once at the most.
+ */
+export declare function describeArrivals(arrivals: ArrivalPlan): string;
+/**
+ * A planner's arrival plan for its participants under the start queue, and the warnings the plan
+ * records about it. A participant's desktop is created when it starts, so on computer use a late
+ * start adds nothing to any sandbox's deadline; the provisioned shared world checks its app's
+ * sandbox with servedScheduleRefusal. `lowered` is the warning that the E2B plan's limit runs the
+ * roster in waves.
+ */
+export declare function planStarts(participants: readonly {
+    readonly startAfterMs?: number;
+}[], queue: StartQueue, lowered: string | undefined): {
+    arrivals: ArrivalPlan;
+    warnings: string[];
+};
+/**
+ * Why a sandbox that serves the app until the last participant ends, the provisioned shared
+ * world's subject sandbox, cannot live that long under `ceilingMs`; undefined when it can. Its
+ * deadline is the schedule's `lastEndMs` plus the time to provision and seed the subject and tear
+ * it down. The session alone is checked first (sandboxDeadlineRefusal), so this names what the
+ * schedule adds: a late start or a wait for a free slot.
+ */
+export declare function servedScheduleRefusal(arrivals: ArrivalPlan, sandbox: {
+    readonly sessionMs: number;
+    readonly seed: readonly {
+        readonly timeoutMs?: number | undefined;
+    }[];
+}, ceilingMs: number): string | undefined;
+/** When a participant was due and when it started, in epoch ms. One that never started has no `startedAt`. */
+export interface ParticipantArrival {
+    readonly scheduledAt: number;
+    readonly startedAt?: number;
+}
+/** A participant's `arrival` in run.json: its offset, and on a live run when it was due and started. */
+export declare function arrivalRecord(startAfterMs: number | undefined, arrival: ParticipantArrival | undefined): RunParticipantArrival;
+/** Where a participant sits in the run's schedule when its start comes. */
+export interface ScheduledStart {
+    /** Its place in schedule order, from 0: the first participant to start has 0. */
+    readonly order: number;
+    /** Its time in epoch ms: the moment the run started its participants plus its offset. */
+    readonly scheduledAt: number;
+}
+/**
+ * Calls `start` for each item at its time, with at most `slots` calls in flight. Items start in
+ * schedule order; one whose time comes while every slot is busy waits for the next free slot. An
+ * abort of `signal` ends every wait at once, so `start` runs for the waiting items right away and
+ * decides whether to skip them. Results come back in the items' order.
+ */
+export declare function runOnSchedule<T, R>(items: readonly T[], options: {
+    readonly startAfterMs: (item: T) => number | undefined;
+    readonly slots: number;
+    /** The run's clock in epoch ms, which must advance while a start waits. Defaults to Date.now. */
+    readonly now?: () => number;
+    /** Waits `ms` or until `signal` aborts. Defaults to node:timers/promises' setTimeout. */
+    readonly sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
+    readonly signal?: AbortSignal;
+}, start: (item: T, index: number, scheduled: ScheduledStart) => Promise<R>): Promise<R[]>;

package/dist/study/arrivals.js

@@ -0,0 +1,204 @@
+// When each participant of a computer-use or shared-world run starts. A study may give each
+// participant an offset from the moment the run starts its participants
+// (`participants[].startAfterMs`). The plan simulates the start queue to report the schedule and
+// when the last session ends at the latest; the routes start their participants through
+// runOnSchedule, which waits for each one's time and then for a free slot. A participant's desktop
+// is created when it starts, so a late start holds no sandbox before then.
+import { setTimeout as delay } from "node:timers/promises";
+import { formatDuration } from "../run/projection.js";
+import { plural } from "../run/text.js";
+import { ceilingAdvice, sandboxHeadroomMs } from "../substrates/e2b/lifetime.js";
+/**
+ * The latest start a study may declare: 24 hours, the longest sandbox lifetime E2B documents. It
+ * also keeps every wait under Node's timer limit of 2^31 - 1 ms, past which a timer fires at once.
+ */
+export const LATEST_START_AFTER_MS = 24 * 60 * 60_000;
+/** Whether `value` is a start offset humanish runs: whole milliseconds from 0 to 24 hours. */
+export function isStartAfterMs(value) {
+    return (typeof value === "number" &&
+        Number.isSafeInteger(value) &&
+        value >= 0 &&
+        value <= LATEST_START_AFTER_MS);
+}
+/** The refusal of a start offset that is not one, naming its `field`. */
+export function startAfterMessage(field) {
+    return `${field} must be a whole number of milliseconds from 0 to ${LATEST_START_AFTER_MS} (24 hours): how long after the run starts its participants this one starts.`;
+}
+/**
+ * Why a roster's declared starts cannot run, or undefined. A start orders participants against
+ * each other, so it needs two or more of them, and the host of an external public app opens the
+ * session the others join, so it starts with the run.
+ */
+export function rosterStartsReason(roster) {
+    if (roster.length === 1 && roster[0]?.startAfterMs !== undefined)
+        return "`startAfterMs` sets when a participant starts relative to the others, so it needs two or more participants, and this study has one. Remove it: a single participant starts with the run.";
+    const host = roster.find((entry) => entry.host === true && (entry.startAfterMs ?? 0) > 0);
+    if (host !== undefined)
+        return `The host participant${host.id === undefined ? "" : ` "${host.id}"`} opens the shared session the others join, so it starts with the run. Remove its \`startAfterMs\`, or set it to 0.`;
+    return undefined;
+}
+/**
+ * The schedule a roster's declared offsets give under the queue (`undefined` is 0: the participant
+ * starts with the run). Participants start in schedule order, by offset and then roster position,
+ * each at its time or when a slot frees, whichever is later; this is the rule runOnSchedule
+ * follows.
+ */
+export function planArrivals(offsets, queue) {
+    const due = offsets.map((offset) => offset ?? 0);
+    const starts = queueStarts(due, queue);
+    let waiting = 0;
+    let longestWaitMs = 0;
+    for (const [index, start] of starts.entries()) {
+        const waitMs = start - due[index];
+        if (waitMs > 0)
+            waiting += 1;
+        longestWaitMs = Math.max(longestWaitMs, waitMs);
+    }
+    return {
+        declared: offsets.some((offset) => offset !== undefined),
+        firstStartMs: Math.min(...due),
+        lastStartMs: Math.max(...due),
+        peak: mostAtOnce(starts, queue.sessionMs),
+        waiting,
+        longestWaitMs,
+        lastEndMs: Math.max(...starts) + queue.sessionMs,
+        sessionMs: queue.sessionMs,
+    };
+}
+/**
+ * The plan's schedule, after a "schedule:" label: the first and last start, and how many run at
+ * once at the most.
+ */
+export function describeArrivals(arrivals) {
+    const late = arrivals.waiting === 0
+        ? ""
+        : `; ${plural(arrivals.waiting, "participant")} then start late, waiting for a free slot, the latest by ${formatDuration(arrivals.longestWaitMs)}`;
+    return `the first participant starts at +${formatDuration(arrivals.firstStartMs)} and the last at +${formatDuration(arrivals.lastStartMs)}; at most ${arrivals.peak} run at once when every session uses its ${formatDuration(arrivals.sessionMs)} budget${late}.`;
+}
+/**
+ * A planner's arrival plan for its participants under the start queue, and the warnings the plan
+ * records about it. A participant's desktop is created when it starts, so on computer use a late
+ * start adds nothing to any sandbox's deadline; the provisioned shared world checks its app's
+ * sandbox with servedScheduleRefusal. `lowered` is the warning that the E2B plan's limit runs the
+ * roster in waves.
+ */
+export function planStarts(participants, queue, lowered) {
+    const arrivals = planArrivals(participants.map((participant) => participant.startAfterMs), queue);
+    return { arrivals, warnings: startQueueWarnings(arrivals, queue, lowered) };
+}
+// A roster that starts together keeps `lowered`. A declared schedule spreads its participants
+// itself, so it is warned only when it holds someone past their time, with `lowered` beside that
+// when the limit is the reason.
+function startQueueWarnings(arrivals, queue, lowered) {
+    if (!arrivals.declared || arrivals.waiting === 0)
+        return !arrivals.declared && lowered ? [lowered] : [];
+    const late = `${plural(arrivals.waiting, "participant")} would start after their time when every session uses its ${formatDuration(arrivals.sessionMs)} budget, the latest by ${formatDuration(arrivals.longestWaitMs)}: the run starts at most ${queue.slots} at once and holds the next one until a slot frees.`;
+    return lowered === undefined ? [late] : [late, lowered];
+}
+/**
+ * Why a sandbox that serves the app until the last participant ends, the provisioned shared
+ * world's subject sandbox, cannot live that long under `ceilingMs`; undefined when it can. Its
+ * deadline is the schedule's `lastEndMs` plus the time to provision and seed the subject and tear
+ * it down. The session alone is checked first (sandboxDeadlineRefusal), so this names what the
+ * schedule adds: a late start or a wait for a free slot.
+ */
+export function servedScheduleRefusal(arrivals, sandbox, ceilingMs) {
+    if (arrivals.lastEndMs <= sandbox.sessionMs)
+        return undefined;
+    const headroomMs = sandboxHeadroomMs({ seed: sandbox.seed });
+    const deadlineMs = arrivals.lastEndMs + headroomMs;
+    if (deadlineMs <= ceilingMs)
+        return undefined;
+    const inMinutes = (ms) => Math.round(ms / 60_000);
+    const causes = [
+        ...(arrivals.lastStartMs > arrivals.firstStartMs
+            ? [
+                `the last one is due ${formatDuration(arrivals.lastStartMs - arrivals.firstStartMs)} after the first`,
+            ]
+            : []),
+        ...(arrivals.waiting > 0
+            ? [`${plural(arrivals.waiting, "participant")} wait for a free slot`]
+            : []),
+    ];
+    return `The participants use the app for up to ${formatDuration(arrivals.lastEndMs)} when every session uses its ${formatDuration(sandbox.sessionMs)} budget, because ${causes.join(" and ")}. The subject sandbox, which serves the app until every participant ends, then needs a ${inMinutes(deadlineMs)}m deadline, with ${inMinutes(headroomMs)}m to provision and seed the subject and tear it down, and a sandbox may not live longer than ${ceilingMs / 60_000}m. Start the last participant earlier, lower execution.timeoutMs, or run more participants at once.${ceilingAdvice(deadlineMs)}`;
+}
+/** The roster indexes in the order participants start: by offset, then roster position. */
+function scheduleOrder(due) {
+    return due.map((_, index) => index).sort((a, b) => due[a] - due[b] || a - b);
+}
+/** Each participant's start in roster order, when every session holds its slot for `sessionMs`. */
+function queueStarts(due, queue) {
+    const starts = [...due];
+    const queued = scheduleOrder(due).filter((index) => index !== queue.ownSlot);
+    const pooled = queue.ownSlot === undefined ? queue.slots : queue.slots - 1;
+    // When each slot is next free; a participant takes the one that frees first.
+    const free = Array.from({ length: Math.max(1, Math.min(pooled, queued.length)) }, () => 0);
+    for (const index of queued) {
+        const slot = free.indexOf(Math.min(...free));
+        const start = Math.max(due[index], free[slot]);
+        starts[index] = start;
+        free[slot] = start + queue.sessionMs;
+    }
+    return starts;
+}
+function mostAtOnce(starts, sessionMs) {
+    // An end sorts before a start at the same instant: that slot is free again.
+    const changes = starts
+        .flatMap((start) => [
+        { at: start, by: 1 },
+        { at: start + sessionMs, by: -1 },
+    ])
+        .sort((a, b) => a.at - b.at || a.by - b.by);
+    let live = 0;
+    let most = 0;
+    for (const change of changes) {
+        live += change.by;
+        most = Math.max(most, live);
+    }
+    return most;
+}
+/** A participant's `arrival` in run.json: its offset, and on a live run when it was due and started. */
+export function arrivalRecord(startAfterMs, arrival) {
+    const iso = (ms) => new Date(ms).toISOString();
+    return {
+        startAfterMs: startAfterMs ?? 0,
+        ...(arrival === undefined ? {} : { scheduledAt: iso(arrival.scheduledAt) }),
+        ...(arrival?.startedAt === undefined ? {} : { startedAt: iso(arrival.startedAt) }),
+    };
+}
+/**
+ * Calls `start` for each item at its time, with at most `slots` calls in flight. Items start in
+ * schedule order; one whose time comes while every slot is busy waits for the next free slot. An
+ * abort of `signal` ends every wait at once, so `start` runs for the waiting items right away and
+ * decides whether to skip them. Results come back in the items' order.
+ */
+export async function runOnSchedule(items, options, start) {
+    const now = options.now ?? Date.now;
+    const sleep = options.sleep ?? sleepUntilAborted;
+    const anchor = now();
+    const due = items.map((item) => options.startAfterMs(item) ?? 0);
+    const order = scheduleOrder(due);
+    const results = new Array(items.length);
+    let next = 0;
+    const workers = Math.max(1, Math.min(options.slots, items.length));
+    await Promise.all(Array.from({ length: workers }, async () => {
+        while (next < order.length) {
+            const position = next;
+            next += 1;
+            const index = order[position];
+            const scheduledAt = anchor + due[index];
+            // A timer can fire a millisecond before the clock it was set against reads its time.
+            for (let waitMs = scheduledAt - now(); waitMs > 0; waitMs = scheduledAt - now()) {
+                if (options.signal?.aborted === true)
+                    break;
+                await sleep(waitMs, options.signal);
+            }
+            results[index] = await start(items[index], index, { order: position, scheduledAt });
+        }
+    }));
+    return results;
+}
+/** An abort ends the wait early; the caller reads the signal itself. */
+function sleepUntilAborted(ms, signal) {
+    return delay(ms, undefined, signal === undefined ? {} : { signal }).catch(() => undefined);
+}

package/dist/study/composition-rules.js

@@ -118,7 +118,7 @@ function appUrlValidationReason(config) {
                 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 the 16 cap, the per-participant target gates, and the
+            // cross-validation below enforces the participant bound, 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)];

package/dist/study/config.js

@@ -18,14 +18,14 @@
 // The terminal route consumes subject.product, `caps` and execution.{terminal,runtimeAuth}.
 //
 // NOTE on `participants`: a count (preview: the simulated count; computer use: N identical
-// participants, each its own desktop, capped at 16), `{ count, instruction }` (identical
+// participants, each its own desktop, at most 100), `{ count, instruction }` (identical
 // participants with one steer), or a list of `{ id?, persona?, device?, instruction?, target? ... }`
 // entries, each its own desktop. A list entry with a `count` is a group that expands into
 // `<id>-01` to `<id>-NN`. A shared world takes a list of at least two. `participants[].device`
 // excludes a raw `execution.desktop.resolution`, and `participants[].target` is app-url computer
 // use only: an absolute browser URL this participant opens in place of `subject.appUrl`.
-// `execution.concurrency` bounds in-flight participants (default: all at once; env
-// HUMANISH_CUA_MAX_CONCURRENCY may only lower it).
+// `execution.concurrency` bounds in-flight participants (default: all at once, up to the E2B
+// plan's concurrent sandboxes; env HUMANISH_CUA_MAX_CONCURRENCY may only lower it).
 import { isLocalBrowserStudy, localBrowserDefaults, localBrowserUnsupportedReason, } from "../substrates/local/runtime-config.js";
 import { isRecord } from "../run/type-guards.js";
 import { compositionReason } from "./composition-rules.js";
@@ -36,9 +36,8 @@ import { parseCaps, parseDefaults, parseExecution, parsePolicies, parseReview, }
 import { ACTOR_REQUIRED, readStudyFront, routeNameReason, } from "./parse/front.js";
 import { parseSubject } from "./parse/subject.js";
 import { invalid, optionalStr, str } from "./parse/values.js";
-import { isComputerUseComposition, isSharedWorldComposition, routeOf } from "./routing.js";
+import { isComputerUseComposition, routeOf } from "./routing.js";
 import { declaredParticipantIds } from "./plan-participants.js";
-import { declaredParticipantCount, participantList } from "./study-fields.js";
 import { ID_PATTERN, STUDY_SCHEMA, } from "./types.js";
 import { automaticAnalysisRouteReason, desktopMediaValidationReason, outputTokenLimitValidationReason, receivingEmailValidationReason, smtpValidationReason, taskProtocolValidationReason, waitLimitValidationReason, } from "./validation.js";
 import { forwardDeclaredWarnings, inertFieldLabels, inertFieldPaths } from "./warnings.js";
@@ -216,7 +215,8 @@ function parseParticipants(raw, read) {
 }
 /**
  * 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.
+ * `comms.email.recipients` and the local browser's defaults. An omitted `execution.concurrency`
+ * stays unset: the planner resolves it from the participants and the E2B plan's limit.
  */
 function checkStudyConfig(config) {
     const smtpReason = smtpValidationReason(config);
@@ -231,20 +231,6 @@ function checkStudyConfig(config) {
     const waitLimitReason = waitLimitValidationReason(config);
     if (waitLimitReason)
         return invalid(waitLimitReason);
-    // All-parallel default: a multi-participant study that does not declare execution.concurrency
-    // runs every participant at once; the declared field is a cap the author chose, never a mode.
-    // Independent computer-use participants resolve that default from the final participant count
-    // when they plan, after any --count override, so the parser leaves it unset for them. A shared
-    // world's roster is fixed, so its default is filled here for the envelopes and warnings that read
-    // the parsed config.
-    {
-        const participantCount = participantList(config)?.length ?? declaredParticipantCount(config) ?? 1;
-        if (participantCount > 1 &&
-            config.execution?.concurrency === undefined &&
-            isSharedWorldComposition(config)) {
-            config.execution = { ...config.execution, concurrency: participantCount };
-        }
-    }
     // Email that just works: the funnel's only handoff to an actor is the per-participant
     // inbox instruction, gated on recipients[]. Guessed participant ids broke a field run:
     // recipients copied from a single-participant example matched nothing, so every actor was left inbox-blind with zero

package/dist/study/doctor.js

@@ -5,6 +5,7 @@ import { capacityShortfall, describeCapacity, } from "../substrates/local/capaci
 import { keyNamesOf, requiredKeys, requiredSubjectEnv } from "./requirements.js";
 import { localAgentReady, localAgentVersionRefusal, } from "../actors/local-agent/cli.js";
 import { protocolAdditionsWarning, protocolIncompatibilityMessage, } from "../actors/codex/protocol-compat.js";
+import { admissionRule } from "../analysis/admission.js";
 import { automaticAnalysisBudget } from "../analysis/automatic-config.js";
 import { externalCatchHealthy } from "../comms/sandbox-catch.js";
 import { receivingRequiredKey } from "../comms/setup.js";
@@ -368,7 +369,7 @@ async function analysisCheck(analysis, args, checkAccount) {
         ok: true,
         ...(keyed ? {} : { status: "note" }),
         message: keyed
-            ? `OPENAI_API_KEY is present for the separate automatic analysis request; model access and quota are not tested. The analysis is refused before it starts if its expected cost plus a 10% margin is over $${analysis.maxCostUsd}; this is not a billing cap. Participant readiness is independent.`
+            ? `OPENAI_API_KEY is present for the separate automatic analysis request; model access and quota are not tested. The analysis is refused before it starts if ${admissionRule(`$${analysis.maxCostUsd}`)}; this is not a billing cap. Participant readiness is independent.`
             : "Will be skipped: OPENAI_API_KEY is missing. The participant may run, but there will be no automatic findings report. Add an OpenAI API key or set review.analysis: false deliberately.",
     };
 }

package/dist/study/keys.d.ts

@@ -18,6 +18,7 @@ export declare const PARTICIPANT_ENTRY: {
     target: true;
     entry: true;
     host: true;
+    startAfterMs: true;
     reasoningEffort: true;
     stopWhen: {
         any: {

package/dist/study/keys.js

@@ -39,6 +39,7 @@ export const PARTICIPANT_ENTRY = {
     target: true,
     entry: true,
     host: true,
+    startAfterMs: true,
     reasoningEffort: true,
     stopWhen: STOP_WHEN,
     dwell: DWELL,
@@ -169,6 +170,7 @@ const STUDY_KEYS = {
     participants: {
         ...PARTICIPANT_ENTRY,
         count: true,
+        startEveryMs: true,
     },
     surfaces: true,
     caps: CAPS,

package/dist/study/migrate/v2.js

@@ -92,9 +92,10 @@ const V2_KEYS = {
     actors: {
         type: true,
         count: true,
-        lanes: PARTICIPANT_ENTRY,
+        // startAfterMs arrived after v2, so a v2 participant cannot carry it.
+        lanes: without(PARTICIPANT_ENTRY, "startAfterMs"),
         // Roster groups are participants with a count; the parser expanded them into `lanes[]`.
-        roster: { ...PARTICIPANT_ENTRY, count: true },
+        roster: { ...without(PARTICIPANT_ENTRY, "startAfterMs"), count: true },
         // maxWaitMs and idleWaitMs arrived after v2, so a v2 file cannot carry them.
         ...without(ACTOR, "type", "maxWaitMs", "idleWaitMs"),
         laneFocus: { id: true, label: true, instruction: true },

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

@@ -25,10 +25,10 @@ export interface ParticipantPaths {
  * Parse a participant list into a fan-out roster (computer-use E2B route): `participants` in a
  * study, `actors[0].lanes` in the v2 file migrate reads, each named in messages by `paths`.
  * Structural only: each entry is `{ id?, actorType?, surface?, caseGroup?, persona?, device?,
- * instruction?, target?, entry?, host?, reasoningEffort?, stopWhen?, dwell? }`.
+ * instruction?, target?, entry?, host?, startAfterMs?, reasoningEffort?, stopWhen?, dwell? }`.
  * Participant ids (when declared) must be public-safe path tokens and unique; grouping metadata
  * must be public-safe tokens; a device must be a known preset name. The
- * route-scoped cross-validation (device XOR raw resolution, targets, cap 16) runs in parseStudy
+ * route-scoped cross-validation (device XOR raw resolution, targets, the participant bound) runs in parseStudy
  * where the route is known.
  */
 export declare function parseParticipantEntries(raw: unknown, paths: ParticipantPaths): {

package/dist/study/parse/actors.js

@@ -7,6 +7,7 @@ import { entryCredentialReason, urlCredentialReason } from "./url-credentials.js
 import { registeredComputerUseActors, registeredScriptedBrowserActors, registeredTerminalActors, } from "../routing.js";
 import { invalid, str } from "./values.js";
 import { isRecord } from "../../run/type-guards.js";
+import { isStartAfterMs, startAfterMessage } from "../arrivals.js";
 // A participant id interpolates into its evidence paths (screenshots/<id>/, actors/<id>.json), so
 // it must be a public-safe path token, same shape as a study id.
 export const PARTICIPANT_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9_.-]*$/;
@@ -96,10 +97,10 @@ export function parseActorFields(entry, path) {
  * Parse a participant list into a fan-out roster (computer-use E2B route): `participants` in a
  * study, `actors[0].lanes` in the v2 file migrate reads, each named in messages by `paths`.
  * Structural only: each entry is `{ id?, actorType?, surface?, caseGroup?, persona?, device?,
- * instruction?, target?, entry?, host?, reasoningEffort?, stopWhen?, dwell? }`.
+ * instruction?, target?, entry?, host?, startAfterMs?, reasoningEffort?, stopWhen?, dwell? }`.
  * Participant ids (when declared) must be public-safe path tokens and unique; grouping metadata
  * must be public-safe tokens; a device must be a known preset name. The
- * route-scoped cross-validation (device XOR raw resolution, targets, cap 16) runs in parseStudy
+ * route-scoped cross-validation (device XOR raw resolution, targets, the participant bound) runs in parseStudy
  * where the route is known.
  */
 export function parseParticipantEntries(raw, paths) {
@@ -107,13 +108,13 @@ export function parseParticipantEntries(raw, paths) {
         return { ok: true, value: undefined };
     }
     if (!Array.isArray(raw) || raw.length === 0) {
-        return invalid(`${paths.list} must be a non-empty array of participant objects ({ id?, actorType?, surface?, caseGroup?, persona?, device?, instruction?, target?, entry?, host?, reasoningEffort?, stopWhen?, dwell? }) when set.`);
+        return invalid(`${paths.list} must be a non-empty array of participant objects ({ id?, actorType?, surface?, caseGroup?, persona?, device?, instruction?, target?, entry?, host?, startAfterMs?, reasoningEffort?, stopWhen?, dwell? }) when set.`);
     }
     const entries = [];
     const seenIds = new Set();
     for (const [entryIndex, entry] of raw.entries()) {
         if (!isRecord(entry)) {
-            return invalid(`${paths.entry(entryIndex)} must be an object ({ id?, actorType?, surface?, caseGroup?, persona?, device?, instruction?, target?, entry?, host?, reasoningEffort?, stopWhen?, dwell? }).`);
+            return invalid(`${paths.entry(entryIndex)} must be an object ({ id?, actorType?, surface?, caseGroup?, persona?, device?, instruction?, target?, entry?, host?, startAfterMs?, reasoningEffort?, stopWhen?, dwell? }).`);
         }
         const parsedEntry = {};
         const id = str(entry.id);
@@ -199,6 +200,11 @@ export function parseParticipantEntries(raw, paths) {
             if (entry.host)
                 parsedEntry.host = true;
         }
+        if (entry.startAfterMs !== undefined) {
+            if (!isStartAfterMs(entry.startAfterMs))
+                return invalid(startAfterMessage(`${paths.entry(entryIndex)}.startAfterMs`));
+            parsedEntry.startAfterMs = entry.startAfterMs;
+        }
         entries.push(parsedEntry);
     }
     return { ok: true, value: entries };

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

@@ -1,4 +1,4 @@
-import type { StudyRoute } from "../routing.js";
+import { type StudyRoute } from "../routing.js";
 import type { StudyParseFailure, StudySurfaces } from "../types.js";
 /** A document's `participants`, read before the participant entries parse. */
 export interface Participants {

package/dist/study/parse/front.js

@@ -4,8 +4,10 @@
 import { isRecord } from "../../run/type-guards.js";
 import { findUnknownStudyKey } from "../keys.js";
 import { movedV2KeyReason } from "../migrate/v2.js";
+import { participantCountReason } from "../routing.js";
 import { PARTICIPANT_ID_MAX_CHARS, PARTICIPANT_ID_PATTERN } from "./actors.js";
 import { invalid, posInt } from "./values.js";
+import { isStartAfterMs, LATEST_START_AFTER_MS, startAfterMessage } from "../arrivals.js";
 // The values `route:` takes: every route routeOf can return.
 const ROUTES = [
     "preview",
@@ -131,12 +133,19 @@ function homogeneousOf(raw) {
     return { ok: true, value: participants };
 }
 // A list entry with `count: n` is a group: n participants `<id>-01` to `<id>-NN`, even when n is 1.
-// config.ts then checks every entry and the expanded ids for collisions.
+// config.ts then checks every entry and the expanded ids for collisions. The roster's size is
+// checked before any group expands, so a large count is refused without building it.
 function entriesOf(raw) {
+    const size = raw.reduce((sum, entry) => sum + (isRecord(entry) && typeof entry.count === "number" ? (posInt(entry.count) ?? 1) : 1), 0);
+    const sizeReason = participantCountReason(size);
+    if (sizeReason)
+        return invalid(sizeReason);
     const entries = [];
     const source = [];
     for (const [index, entry] of raw.entries()) {
         if (!isRecord(entry) || entry.count === undefined) {
+            if (isRecord(entry) && entry.startEveryMs !== undefined)
+                return invalid(`participants[${index}].startEveryMs spreads a group's members over time, so it needs \`count\` on the same entry.`);
             entries.push(entry);
             source.push(index);
             continue;
@@ -151,15 +160,40 @@ function entriesOf(raw) {
             id.length > PARTICIPANT_ID_MAX_CHARS - 3) {
             return invalid(`participants[${index}] has a count, so it needs an \`id\` matching ${PARTICIPANT_ID_PATTERN} of at most ${PARTICIPANT_ID_MAX_CHARS - 3} characters. Its participants are <id>-01 to <id>-${String(count).padStart(2, "0")}.`);
         }
+        const starts = memberStarts(entry, index, id, count);
+        if (!starts.ok)
+            return starts;
         const shared = { ...entry };
         delete shared.count;
+        delete shared.startEveryMs;
         for (let n = 1; n <= count; n += 1) {
-            entries.push({ ...shared, id: `${id}-${String(n).padStart(2, "0")}` });
+            const startAfterMs = starts.value(n);
+            entries.push({
+                ...shared,
+                id: `${id}-${String(n).padStart(2, "0")}`,
+                ...(startAfterMs === undefined ? {} : { startAfterMs }),
+            });
             source.push(index);
         }
     }
     return { ok: true, value: { entries, source } };
 }
+// A group's `startEveryMs` gives member n the start `startAfterMs + (n - 1) * startEveryMs`.
+// Without it every member keeps the entry's own `startAfterMs`, which the entry parser checks.
+function memberStarts(entry, index, id, count) {
+    if (entry.startEveryMs === undefined)
+        return { ok: true, value: () => entry.startAfterMs };
+    const every = typeof entry.startEveryMs === "number" ? posInt(entry.startEveryMs) : undefined;
+    if (every === undefined)
+        return invalid(`participants[${index}].startEveryMs must be a whole number of milliseconds of 1 or more: how long after one member of the group the next one starts.`);
+    const first = entry.startAfterMs ?? 0;
+    if (!isStartAfterMs(first))
+        return invalid(startAfterMessage(`participants[${index}].startAfterMs`));
+    const last = first + (count - 1) * every;
+    if (last > LATEST_START_AFTER_MS)
+        return invalid(`participants[${index}] starts its last member, ${id}-${String(count).padStart(2, "0")}, ${last} ms after the run starts its participants, and a start must be at most ${LATEST_START_AFTER_MS} ms (24 hours). Lower startEveryMs, startAfterMs or count.`);
+    return { ok: true, value: (member) => first + (member - 1) * every };
+}
 function surfacesOf(route, raw) {
     if (raw === undefined)
         return { ok: true, value: undefined };

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

@@ -1,6 +1,6 @@
 import type { Brain, ComputerUsePlan, NonEmpty, PlannedAnalysis, ProvisionedSubject, Requirement } from "./plan-types.js";
 import type { StudyConfig } from "./types.js";
-export type Base = Omit<ComputerUsePlan, "route" | "actor" | "runner" | "concurrency" | "sessionBudgetMs" | "sandboxMs" | "caps" | "rerun">;
+export type Base = Omit<ComputerUsePlan, "route" | "actor" | "runner" | "concurrency" | "arrivals" | "sessionBudgetMs" | "sandboxMs" | "caps" | "rerun">;
 export declare function isNonEmpty<T>(values: readonly T[]): values is NonEmpty<T>;
 export declare function planCaps(config: StudyConfig): ComputerUsePlan["caps"];
 export declare function provisionedSubject(config: StudyConfig): ProvisionedSubject | undefined;

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

@@ -41,6 +41,8 @@ interface DesktopParticipant extends Participant {
         /** actor.idleWaitMs: how long a wait with no duration lasts while the participant only waits. */
         readonly idleWaitMs?: number;
     };
+    /** When it starts, in ms after the run starts its participants; absent, with the run. */
+    readonly startAfterMs?: number;
 }
 /** Only independent computer-use participants consume a task protocol and their own target. */
 export interface ComputerUseParticipant extends DesktopParticipant {

package/dist/study/plan-participants.js

@@ -1,7 +1,7 @@
 // Who takes part in a study: one record per participant, built from the declared roster or a count.
 // Computer-use and shared-world participants share the desktop fields; each kind adds its own.
 import { resolveParticipantDevice } from "./device-presets.js";
-import { isSharedWorldComposition, participantIdAt } from "./routing.js";
+import { computerUseParticipantCount, isSharedWorldComposition, participantIdAt, } from "./routing.js";
 import { participantList, declaredParticipantCount, participantInstruction, } from "./study-fields.js";
 function desktopParticipant(config, entry, index, kind, focus) {
     const actor = config.actor;
@@ -36,6 +36,7 @@ function desktopParticipant(config, entry, index, kind, focus) {
             ...(maxWaitMs === undefined ? {} : { maxWaitMs }),
             ...(idleWaitMs === undefined ? {} : { idleWaitMs }),
         },
+        ...(entry?.startAfterMs === undefined ? {} : { startAfterMs: entry.startAfterMs }),
     };
 }
 /**
@@ -45,10 +46,7 @@ function desktopParticipant(config, entry, index, kind, focus) {
 export function computerUseParticipants(config, countOverride) {
     const actor = config.actor;
     const roster = participantList(config);
-    const count = roster
-        ? roster.length
-        : Math.max(1, countOverride ?? declaredParticipantCount(config) ?? 1);
-    return Array.from({ length: count }, (_, index) => {
+    return Array.from({ length: computerUseParticipantCount(config, countOverride) }, (_, index) => {
         const entry = roster?.[index];
         const focus = roster ? entry?.instruction : participantInstruction(config);
         return {