humanish 0.118.0 → 0.119.0

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/doctor.js

@@ -6,7 +6,7 @@ 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 { studyAnalysisBudget } from "./automatic-analysis-plan.js";
+import { automaticAnalysisBudget } from "../analysis/automatic-config.js";
 import { externalCatchHealthy } from "../comms/sandbox-catch.js";
 import { receivingRequiredKey } from "../comms/setup.js";
 import { classifyCodexInstallation, codexInstallAdvice, codexVersionRecovery, } from "../actors/codex/codex-admission.js";
@@ -191,11 +191,7 @@ export async function studySetupChecks(args) {
     if (route === "scripted")
         checks.push(await scriptedBrowserCheck());
     checks.push(...subjectEnvChecks(requiredSubjectEnv(requirements), args));
-    const analysis = studyAnalysisBudget(config.review?.analysis, route, plan.route === "computer-use"
-        ? plan.runner.participants.length
-        : plan.route === "shared-world"
-            ? plan.plane.participants.length
-            : 1);
+    const analysis = automaticAnalysisBudget(config.review?.analysis, route);
     if (analysis)
         checks.push(await analysisCheck(analysis, args, checkAccount));
     checks.push(checkScope(analysis));
@@ -352,15 +348,6 @@ function subjectEnvChecks(names, args) {
 }
 /** The post-run analysis: the Codex account, or the OpenAI key and the analysis cost limit. */
 async function analysisCheck(analysis, args, checkAccount) {
-    if (analysis.skip !== undefined) {
-        const explicit = analysis.trigger === "explicit";
-        return {
-            name: "post-run analysis",
-            ok: !explicit,
-            ...(explicit ? {} : { status: "note" }),
-            message: `Will not run: this study has ${analysis.participants ?? "more"} participants, more than automatic analysis reads. The participants still run.${explicit ? " review.analysis asks for it, so the run will exit 2; set review.analysis: false or run fewer participants." : ""}`,
-        };
-    }
     if (analysis.provider === "codex") {
         const readiness = await checkAccount();
         const recovery = readiness.errorCode === "codex_unsupported_platform"

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,7 +25,7 @@ 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, the participant bound) runs in parseStudy

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,7 +97,7 @@ 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, the participant bound) runs in parseStudy
@@ -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.js

@@ -7,6 +7,7 @@ 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",
@@ -143,6 +144,8 @@ function entriesOf(raw) {
     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;
@@ -157,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;
@@ -25,6 +25,4 @@ export declare function planBase(config: StudyConfig, input: {
         readonly config?: PlannedAnalysis["config"] | undefined;
         readonly preferLargerOutput?: boolean | undefined;
     };
-    /** How many participants the run has, which decides whether its analysis can run. */
-    readonly participants?: number;
 }): Base;

package/dist/study/plan-base.js

@@ -1,7 +1,6 @@
 // What every route planner shares: the plan fields common to all routes, the frozen residual config,
 // and the requirement and subject helpers.
 import { DEFAULT_OPENAI_CU_MODEL } from "../actors/computer-use/openai-provider.js";
-import { analysisSkipFor } from "./automatic-analysis-plan.js";
 // A YAML alias can make a parsed record contain itself (an inline persona that names its own
 // anchor), and structuredClone keeps the cycle, so each object is frozen once.
 function deepFreeze(value, frozen = new WeakSet()) {
@@ -109,7 +108,6 @@ export function pricedModel(brain) {
 /** The fields every plan shares, from a config whose analysis already resolved. */
 export function planBase(config, input) {
     const analysis = input.analysis?.config;
-    const skip = analysisSkipFor(input.participants ?? 1);
     return {
         studyId: config.id,
         ...(config.title === undefined ? {} : { title: config.title }),
@@ -122,7 +120,6 @@ export function planBase(config, input) {
                     config: analysis,
                     trigger: config.review?.analysis === undefined ? "default" : "explicit",
                     preferLargerOutput: input.analysis?.preferLargerOutput === true,
-                    ...(skip === undefined ? {} : { skip }),
                 },
             }),
         requirements: [],

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

@@ -36,6 +36,7 @@ function desktopParticipant(config, entry, index, kind, focus) {
             ...(maxWaitMs === undefined ? {} : { maxWaitMs }),
             ...(idleWaitMs === undefined ? {} : { idleWaitMs }),
         },
+        ...(entry?.startAfterMs === undefined ? {} : { startAfterMs: entry.startAfterMs }),
     };
 }
 /**

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";
@@ -57,9 +58,6 @@ export interface PlannedAnalysis {
     /** "default" when the study declared no review.analysis. */
     readonly trigger: "default" | "explicit";
     readonly preferLargerOutput: boolean;
-    /** Set when the study has more participants than one analysis reads: a live run records the
-     *  analysis as skipped for this reason and never starts it. */
-    readonly skip?: "AUTOMATIC_ANALYSIS_PARTICIPANT_LIMIT";
 }
 interface PlanBase {
     readonly studyId: string;
@@ -166,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: {
@@ -200,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, {

package/dist/study/preflight-result.js

@@ -1,13 +1,13 @@
 // The preflight result a run returns, built from its context. preflight.ts and the probes in
 // preflight-probes.ts both finish through these, so they live below both.
-import { studyAnalysisBudget } from "./automatic-analysis-plan.js";
+import { automaticAnalysisBudget } from "../analysis/automatic-config.js";
 import { digestText } from "../evidence/redaction.js";
 import { computerUseParticipantCount } from "./routing.js";
 /** The schema of `study check` results: whether a study is ready to run on this machine. */
 export const STUDY_CHECK_SCHEMA = "humanish.study-check.v1";
 export function finalize(ctx, args) {
     const checks = [...ctx.checks, ...(args?.check ? [args.check] : []), ...(args?.checks ?? [])];
-    const analysis = studyAnalysisBudget(ctx.config.review?.analysis, ctx.route, computerUseParticipantCount(ctx.config));
+    const analysis = automaticAnalysisBudget(ctx.config.review?.analysis, ctx.route, computerUseParticipantCount(ctx.config));
     return {
         schema: STUDY_CHECK_SCHEMA,
         ...(analysis ? { analysis } : {}),

package/dist/study/preflight.js

@@ -6,6 +6,7 @@ import {} from "./types.js";
 import { runPublicPreviewPreflight, runSandboxLoopbackPreflight } from "./preflight-probes.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";
@@ -74,6 +75,9 @@ export async function runStudyPreflight(options) {
         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))
@@ -118,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/summary.d.ts

@@ -1,5 +1,5 @@
 import { type LocalRuntimeStatus } from "../substrates/local/runtime.js";
-import { type StudyAnalysisBudget } from "./automatic-analysis-plan.js";
+import { type AutomaticAnalysisBudget } from "../analysis/automatic-config.js";
 import { type KeyResolutionDeps } from "../keys/key-resolution.js";
 export declare const STUDY_SUMMARY_SCHEMA = "humanish.study-summary.v1";
 export interface StudyCaps {
@@ -15,8 +15,8 @@ export interface StudySummary {
         message: string;
     };
     communications?: string;
-    analysis?: StudyAnalysisBudget & {
-        /** The budget line `run` and `study check` print, from formatStudyAnalysisBudget. */
+    analysis?: AutomaticAnalysisBudget & {
+        /** The budget line `run` and `study check` print, from formatAutomaticAnalysisBudget. */
         line: string;
     };
     schema: typeof STUDY_SUMMARY_SCHEMA;

package/dist/study/summary.js

@@ -11,7 +11,7 @@ import { localRuntimeStatus } from "../substrates/local/runtime.js";
 import { planStudy, resolveStudyDryRun, routeOf } from "./plan.js";
 import { localCodexParticipantCheck } from "./doctor.js";
 import { requiredKeys, requiredSubjectEnv } from "./requirements.js";
-import { formatStudyAnalysisBudget, studyAnalysisBudget, } from "./automatic-analysis-plan.js";
+import { automaticAnalysisBudget, formatAutomaticAnalysisBudget, } from "../analysis/automatic-config.js";
 import { DEFAULT_OPENAI_CU_MODEL, DEFAULT_OPENAI_CU_REASONING_EFFORT, } from "../actors/computer-use/openai-provider.js";
 import { inspectStudyManifest } from "./discover.js";
 import { computerUseParticipantCount, isComputerUseComposition } from "./routing.js";
@@ -123,7 +123,7 @@ export async function readStudySummary(cwd, study, options = {}) {
             missingKeys = missing;
     }
     // Computed once: a test-then-use pair reads as though the two calls could differ.
-    const analysis = studyAnalysisBudget(inspected.config.review?.analysis, route, computerUseParticipantCount(inspected.config));
+    const analysis = automaticAnalysisBudget(inspected.config.review?.analysis, route, computerUseParticipantCount(inspected.config));
     const subject = subjectOf(config);
     const participants = participantsOf(inspected.config);
     const caps = summaryCapsOf(inspected.config);
@@ -140,7 +140,9 @@ export async function readStudySummary(cwd, study, options = {}) {
         ? await localCodexParticipantCheck({ env: options.env ?? process.env })
         : undefined;
     return {
-        ...(analysis ? { analysis: { ...analysis, line: formatStudyAnalysisBudget(analysis) } } : {}),
+        ...(analysis
+            ? { analysis: { ...analysis, line: formatAutomaticAnalysisBudget(analysis) } }
+            : {}),
         ...(runtime
             ? { runtime: { ok: runtime.ok, installed: runtime.installed, message: runtime.message } }
             : {}),

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.js

@@ -6,6 +6,7 @@ import { isHttpUrl, isLoopbackUrl } from "./parse/subject.js";
 import { declaredTargets } from "./plan-participants.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
@@ -78,6 +79,9 @@ function rosterStructuralValidationReason(config) {
             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;
@@ -92,6 +96,7 @@ function rosterStructuralValidationReason(config) {
             }
             seenIds.add(id);
         }
+        return rosterStartsReason(roster) ?? null;
     }
     return null;
 }