humanish 0.118.0 → 0.120.0

package/dist/routes/computer-use/fanout-bundle.js

@@ -13,6 +13,7 @@ import { buildRunCostSummary, desktopSpanToMinutes } from "../../run/cost-summar
 import { formatParticipantPlanEntry } from "./participant-runs.js";
 import { fanoutParticipantRecords } from "./fanout-records.js";
 import { plural } from "../../run/text.js";
+import { describeArrivals } from "../../study/arrivals.js";
 /** The run's first two events: its creation and the fan-out plan. */
 function fanoutPlanEvents(args) {
     const { specs, plan } = args;
@@ -29,7 +30,7 @@ function fanoutPlanEvents(args) {
         at: args.run.createdAt,
         level: "info",
         type: "cua-lab.fanout.plan",
-        message: `Fan-out plan: ${plural(args.participantPlan.laneCount, "participant")} (${args.participantPlan.strategy}), concurrency ${args.participantPlan.concurrency}, ${plural(args.participantPlan.waves, "wave")}; session budget ${Math.round(args.participantPlan.perLaneSessionBudgetMs / 1000)}s per participant; worst-case ~${args.participantPlan.worstCaseSandboxMinutes} sandbox-minutes${args.dryRun ? " (dry-run: $0)" : ""}. Participants: ${args.participantPlan.lanes.map(formatParticipantPlanEntry).join(", ")}.`,
+        message: `Fan-out plan: ${plural(args.participantPlan.laneCount, "participant")} (${args.participantPlan.strategy}), concurrency ${args.participantPlan.concurrency}, ${plural(args.participantPlan.waves, "wave")}; session budget ${Math.round(args.participantPlan.perLaneSessionBudgetMs / 1000)}s per participant; worst-case ~${args.participantPlan.worstCaseSandboxMinutes} sandbox-minutes${args.dryRun ? " (dry-run: $0)" : ""}.${args.participantPlan.schedule === undefined ? "" : ` Schedule: ${describeArrivals(args.participantPlan.schedule)}`} Participants: ${args.participantPlan.lanes.map(formatParticipantPlanEntry).join(", ")}.`,
     });
     return events;
 }

package/dist/routes/computer-use/fanout-records.js

@@ -1,6 +1,7 @@
 // Each participant's records in a computer-use fan-out bundle: its simulation, its stream, its
 // subject provenance event and the events of its outcome (session, geometry warnings, phase trail).
 import { participantAssignment } from "../../study/participant-assignment.js";
+import { arrivalRecord } from "../../study/arrivals.js";
 import { participantEvent, participantRecord, participantStream, } from "../../run/participant-records.js";
 import { participantCaption } from "../../run/participant-caption.js";
 import { participantSummary } from "../../run/outcomes.js";
@@ -69,6 +70,9 @@ function fanoutParticipantRecord(args, spec, index, view) {
         }),
         startedAt: args.run.createdAt,
         updatedAt: args.run.createdAt,
+        ...(args.participantPlan.schedule === undefined
+            ? {}
+            : { arrival: arrivalRecord(spec.planned.startAfterMs, outcome?.arrival) }),
     });
 }
 function fanoutParticipantStream(args, spec, view) {

package/dist/routes/computer-use/participant-execution.d.ts

@@ -11,10 +11,12 @@ export declare function makeParticipantWriteScreenshot(artifactRoot: PreparedOut
  * evidence and cleanup; this runner owns the model, trace and participant outcome. */
 export declare function runCuaParticipant(spec: DesktopParticipantRun, deps: CuaParticipantDeps): Promise<ParticipantRunOutcome>;
 /**
- * Run N>1 E2B participants with bounded concurrency, a pipeline gate (the first provisions
- * before the rest start), and session fail-fast on harness errors only (queued participants
- * become `blocked` with a pinned reason + a fail-fast event; mission verdicts never trip it).
- * Each participant tears down its own sandbox by id; nothing here ever enumerates.
+ * Run N>1 E2B participants on the study's schedule (runOnSchedule: each at its start offset, at
+ * most `concurrency` at once), behind a pipeline gate (the first to start provisions before the
+ * rest start) and session fail-fast on harness errors only (queued participants become `blocked`
+ * with a pinned reason + a fail-fast event; mission verdicts never trip it). A gate failure or a
+ * fail-fast ends every wait for a later start at once. Each participant tears down its own sandbox
+ * by id; nothing here ever enumerates.
  *
  * Exported for the total-runner tests: the injectable runner lets a test make one participant
  * throw (the exact class the guard exists for) without a live sandbox. Production always uses

package/dist/routes/computer-use/participant-execution.js

@@ -3,7 +3,7 @@ import { createE2BParticipantDesktop } from "./e2b-desktop/desktop.js";
 import { createInProcessDesktop } from "./in-process-desktop.js";
 import path from "node:path";
 import { cuaParticipantDiagnostics } from "./diagnostics.js";
-import { mapWithConcurrency } from "../../run/concurrency.js";
+import { runOnSchedule } from "../../study/arrivals.js";
 import { assertScreenshotEvidence, stripPngMetadataChunks } from "../../evidence/image.js";
 import { redactText, toErrorMessage } from "../../evidence/redaction.js";
 import { assertSafeOutputPathSegment, writeContainedOutputFile, } from "../../run/contained-output.js";
@@ -32,9 +32,10 @@ export function makeParticipantWriteScreenshot(artifactRoot, spec, screenshots)
     };
 }
 /** A blocked participant outcome (pipeline gate / fail-fast skipped it before it ran). */
-function skippedOutcome(spec, reason) {
+function skippedOutcome(spec, reason, arrival) {
     return {
         spec,
+        ...(arrival === undefined ? {} : { arrival }),
         killed: false,
         streamUrlPresent: false,
         screenshots: [],
@@ -51,6 +52,13 @@ function skippedOutcome(spec, reason) {
 /** Run one participant against a prepared desktop. The adapter owns provisioning, final
  * evidence and cleanup; this runner owns the model, trace and participant outcome. */
 export async function runCuaParticipant(spec, deps) {
+    // A participant whose start comes after the study budget is spent would pay for a desktop and a
+    // model turn only to stop at its first one, so it is skipped before its desktop exists.
+    const crossed = deps.runBudget?.crossed();
+    if (crossed !== undefined) {
+        deps.signalProvisioned?.(false);
+        return skippedOutcome(spec, `skipped: study budget reached before this participant started: ${crossed}; no desktop was created`);
+    }
     let model = {};
     const warnings = [];
     const screenshots = [];
@@ -142,10 +150,12 @@ export async function runCuaParticipant(spec, deps) {
     };
 }
 /**
- * Run N>1 E2B participants with bounded concurrency, a pipeline gate (the first provisions
- * before the rest start), and session fail-fast on harness errors only (queued participants
- * become `blocked` with a pinned reason + a fail-fast event; mission verdicts never trip it).
- * Each participant tears down its own sandbox by id; nothing here ever enumerates.
+ * Run N>1 E2B participants on the study's schedule (runOnSchedule: each at its start offset, at
+ * most `concurrency` at once), behind a pipeline gate (the first to start provisions before the
+ * rest start) and session fail-fast on harness errors only (queued participants become `blocked`
+ * with a pinned reason + a fail-fast event; mission verdicts never trip it). A gate failure or a
+ * fail-fast ends every wait for a later start at once. Each participant tears down its own sandbox
+ * by id; nothing here ever enumerates.
  *
  * Exported for the total-runner tests: the injectable runner lets a test make one participant
  * throw (the exact class the guard exists for) without a live sandbox. Production always uses
@@ -153,28 +163,41 @@ export async function runCuaParticipant(spec, deps) {
  */
 export async function runCuaParticipants(runs, deps, concurrency, runParticipant = runCuaParticipant) {
     const failFast = { tripped: false, reason: "" };
+    const stopping = new AbortController();
+    let gateHolder = runs[0]?.planned.id ?? "lane-01";
     let resolveGate;
     let rejectGate;
     const gate = new Promise((resolve, reject) => {
         resolveGate = resolve;
-        rejectGate = () => reject(new Error("gate"));
+        rejectGate = () => {
+            reject(new Error("gate"));
+            stopping.abort();
+        };
     });
     // The gate is rejected on the first participant's provisioning failure; swallow the unhandled
     // rejection if no later participant ever awaits it (concurrency could let the first finish
     // alone).
     gate.catch(() => undefined);
-    const outcomes = await mapWithConcurrency(runs, concurrency, async (spec, index) => {
-        if (index > 0) {
+    const outcomes = await runOnSchedule(runs, {
+        startAfterMs: (spec) => spec.planned.startAfterMs,
+        slots: concurrency,
+        now: deps.now,
+        signal: stopping.signal,
+    }, async (spec, _index, { order, scheduledAt }) => {
+        if (order === 0)
+            gateHolder = spec.planned.id;
+        if (order > 0) {
             try {
                 await gate;
             }
             catch {
-                return skippedOutcome(spec, `skipped: participant ${runs[0]?.planned.id ?? "lane-01"} failed to provision its world (pipeline gate)`);
+                return skippedOutcome(spec, `skipped: participant ${gateHolder} failed to provision its world (pipeline gate)`, { scheduledAt });
             }
         }
         if (failFast.tripped) {
-            return skippedOutcome(spec, `skipped: ${failFast.reason}`);
+            return skippedOutcome(spec, `skipped: ${failFast.reason}`, { scheduledAt });
         }
+        const arrival = { scheduledAt, startedAt: deps.now() };
         // The participant runner is total: every exit path returns a recorded outcome. Without this
         // guard, one participant's late throw (e.g. its trace write hitting ENOSPC after its own sandbox was
         // already torn down) rejected the whole map while sibling workers kept launching sandboxes
@@ -183,7 +206,7 @@ export async function runCuaParticipants(runs, deps, concurrency, runParticipant
         try {
             outcome = await runParticipant(spec, {
                 ...deps,
-                ...(index === 0
+                ...(order === 0
                     ? {
                         signalProvisioned: (ok) => {
                             if (ok) {
@@ -200,7 +223,7 @@ export async function runCuaParticipants(runs, deps, concurrency, runParticipant
         catch (error) {
             // The first participant may have thrown before signaling the provisioning gate; release the followers as
             // blocked rather than leaving them awaiting a gate that will never settle.
-            if (index === 0)
+            if (order === 0)
                 rejectGate?.();
             const detail = redactText(toErrorMessage(error));
             outcome = {
@@ -221,8 +244,13 @@ export async function runCuaParticipants(runs, deps, concurrency, runParticipant
         if (outcome.harnessError && !failFast.tripped) {
             failFast.tripped = true;
             failFast.reason = `a prior participant (${outcome.spec.planned.id}) ended in a harness error (fail-fast)`;
+            stopping.abort();
         }
-        return outcome;
+        // A participant the study budget skipped never requested its desktop.
+        return {
+            ...outcome,
+            arrival: outcome.skippedReason === undefined ? arrival : { scheduledAt },
+        };
     });
     return { outcomes, ...(failFast.tripped ? { failFastReason: failFast.reason } : {}) };
 }

package/dist/routes/computer-use/participant-model.js

@@ -148,10 +148,11 @@ export function participantSessionOptions(spec, deps, ready, provider, writeScre
             : {
                 overRunBudget: (usage) => {
                     const estimate = estimateActorCostForExecution(usage, provider?.version ?? capModelId, provider?.executionProfile).estimatedCostUsd;
-                    const totalUsd = deps.runBudget.note(spec.planned.id, estimate);
-                    return totalUsd > deps.runBudget.maxTotalUsd
-                        ? `study budget reached: the run's estimated model spend $${round6(totalUsd)} crossed caps.maxTotalUsd=$${deps.runBudget.maxTotalUsd}; this lane stops here and sibling lanes stop at their next turn`
-                        : null;
+                    deps.runBudget.note(spec.planned.id, estimate);
+                    const crossed = deps.runBudget.crossed();
+                    return crossed === undefined
+                        ? null
+                        : `study budget reached: ${crossed}; this lane stops here and sibling lanes stop at their next turn`;
                 },
             }),
         ...(deps.onObservedUrl === undefined ? {} : { onObservedUrl: deps.onObservedUrl }),
@@ -283,15 +284,24 @@ export function participantCapWarning(caps, participantCount, capped = "each par
 }
 export function makeCuaRunBudget(maxTotalUsd) {
     const participantEstimates = new Map();
+    const total = () => {
+        let sum = 0;
+        for (const value of participantEstimates.values())
+            sum += value;
+        return sum;
+    };
     return {
         maxTotalUsd,
         note(participantId, estimateUsd) {
             if (estimateUsd !== null)
                 participantEstimates.set(participantId, estimateUsd);
-            let total = 0;
-            for (const value of participantEstimates.values())
-                total += value;
-            return total;
+            return total();
+        },
+        crossed() {
+            const totalUsd = total();
+            return totalUsd > maxTotalUsd
+                ? `the run's estimated model spend $${round6(totalUsd)} crossed caps.maxTotalUsd=$${maxTotalUsd}`
+                : undefined;
         },
     };
 }

package/dist/routes/computer-use/participant-runs.js

@@ -17,6 +17,8 @@ import { digestUrl } from "./bundle-parts.js";
 import { composeParticipantInstructions, DEFAULT_MISSION } from "./participant-prompt.js";
 import { resolveCuaRerunSelection } from "./rerun-selection.js";
 import { plural } from "../../run/text.js";
+import { formatDuration } from "../../run/projection.js";
+import { describeArrivals, planArrivals } from "../../study/arrivals.js";
 /**
  * The session budget of a study that declares no execution.timeoutMs. On a provisioned route it is
  * what the `ceilingMs` sandbox ceiling leaves after provisioning, seeding and the teardown buffer.
@@ -113,6 +115,9 @@ export function participantRunsAndPlan(plan, opts = {}) {
     const resolved = envLoweredConcurrency(plan.concurrency, participantCount, env);
     const concurrency = resolved.bound;
     const { sessionBudgetMs, sandboxMs } = plan;
+    const schedule = resolved.envLoweredFrom === undefined
+        ? plan.arrivals
+        : planArrivals(participants.map((participant) => participant.startAfterMs), { slots: concurrency, sessionMs: sessionBudgetMs });
     const participantPlan = {
         strategy: CUA_FANOUT_STRATEGY,
         laneCount: participantCount,
@@ -123,6 +128,7 @@ export function participantRunsAndPlan(plan, opts = {}) {
         waves: Math.ceil(participantCount / concurrency),
         perLaneSessionBudgetMs: sessionBudgetMs,
         worstCaseSandboxMinutes: Math.round((participantCount * sandboxMs) / 60_000),
+        ...(schedule.declared ? { schedule } : {}),
         dryRun: plan.dryRun,
         lanes: runs.map((spec) => ({
             id: spec.planned.id,
@@ -149,6 +155,9 @@ export function participantRunsAndPlan(plan, opts = {}) {
             ...(spec.planned.targetUrl === undefined
                 ? {}
                 : { targetDigest: digestUrl(spec.planned.targetUrl) }),
+            ...(spec.planned.startAfterMs === undefined
+                ? {}
+                : { startAfterMs: spec.planned.startAfterMs }),
         })),
     };
     return { runs, participantPlan };
@@ -159,6 +168,8 @@ export function emitPreflightPlan(participantPlan, studyId) {
     const lines = [];
     lines.push(`humanish computer-use fan-out plan (${studyId}): ${plural(participantPlan.laneCount, "participant")}, strategy ${participantPlan.strategy}, concurrency ${participantPlan.concurrency}${participantPlan.envLoweredConcurrencyFrom === undefined ? "" : ` (lowered from ${participantPlan.envLoweredConcurrencyFrom} by ${CUA_MAX_CONCURRENCY_ENV})`}, ${plural(participantPlan.waves, "wave")}.`);
     lines.push(`  session budget ${Math.round(participantPlan.perLaneSessionBudgetMs / 1000)}s per participant; worst-case ~${participantPlan.worstCaseSandboxMinutes} sandbox-minutes total${participantPlan.dryRun ? " (dry-run: $0)" : ""}.`);
+    if (participantPlan.schedule)
+        lines.push(`  schedule: ${describeArrivals(participantPlan.schedule)}`);
     for (const entry of participantPlan.lanes) {
         lines.push(`  - ${formatParticipantPlanEntry(entry)}`);
     }
@@ -170,6 +181,7 @@ export function formatParticipantPlanEntry(entry) {
         entry.surface ? `surface=${entry.surface}` : undefined,
         entry.caseGroup ? `case=${entry.caseGroup}` : undefined,
         entry.reasoningEffort ? `effort=${entry.reasoningEffort}` : undefined,
+        entry.startAfterMs === undefined ? undefined : `start=+${formatDuration(entry.startAfterMs)}`,
     ].filter((part) => part !== undefined);
     return `${entry.id}: persona=${entry.persona}${taxonomy.length > 0 ? ` ${taxonomy.join(" ")}` : ""} device=${entry.device} ${entry.resolution[0]}x${entry.resolution[1]} prompt#${entry.instructionDigest}${entry.targetDigest ? ` target#${entry.targetDigest}` : ""}`;
 }

package/dist/routes/computer-use/plan.js

@@ -9,6 +9,7 @@ import { studyUrlCredentialReason } from "../../study/url-credentials.js";
 import { subjectStateInvalidReason } from "../../study/parse/subject-state.js";
 import { brainOf, callerBrainOf, planCaps, desktopRequirements, planBase, provisionedSubject, } from "../../study/plan-base.js";
 import { computerUseParticipants, declaredTargets } from "../../study/plan-participants.js";
+import { planStarts } from "../../study/arrivals.js";
 import { computerUseParticipantCount, participantCountReason } from "../../study/routing.js";
 import { cloneTargetValidationReason, computerUseValidationReason, desktopMediaValidationReason, outputTokenLimitValidationReason, receivingEmailValidationReason, taskProtocolValidationReason, waitLimitValidationReason, } from "../../study/validation.js";
 import { desktopCliProductReason } from "../../study/composition-rules.js";
@@ -193,17 +194,27 @@ function rosterShapeReason(config, ceilingMs) {
     return invalid(`execution.timeoutMs ${Math.round(sessionMs / 60_000)}m derives a ${Math.round(derivedSandboxMs / 60_000)}m sandbox deadline, and a sandbox may not live longer than ${ceilingMs / 60_000}m. The deadline is the session budget plus ${Math.round(headroomMs / 60_000)}m of provisioning and teardown headroom${provisionedRoute ? " (this route clones, installs, builds and serves the subject before the actor starts)" : ""}. Lower execution.timeoutMs to at most ${Math.round((ceilingMs - headroomMs) / 60_000)}m, or set execution.desktop.sandboxTimeoutMs explicitly.${ceilingAdvice(derivedSandboxMs)}`);
 }
 /**
- * How many of the runner's participants run at once. Hosted desktops share the E2B plan's
- * concurrent sandboxes; the local VM has its own capacity rules and the in-process route runs one
+ * How many of the runner's participants run at once, and when each one starts, with the session
+ * budget the `ceilingMs` sandbox ceiling leaves. Hosted desktops share the E2B plan's concurrent
+ * sandboxes; the local VM has its own capacity rules and the in-process route runs one
  * participant.
  */
-function concurrencyOf(config, runner, limit) {
+function startsOf(config, runner, limit, ceilingMs) {
     const declared = config.execution?.concurrency;
     const n = runner.participants.length;
     const concurrency = boundedConcurrency(declared, n);
-    return runner.desktop === "e2b-desktop"
+    const atOnce = runner.desktop === "e2b-desktop"
         ? participantsAtOnce({ concurrency, declared: declared !== undefined, participants: n }, limit)
         : { ok: true, count: concurrency };
+    if (!atOnce.ok)
+        return atOnce;
+    const sessionMs = config.execution?.timeoutMs ?? defaultSessionTimeoutMs(config, ceilingMs);
+    const slots = { slots: atOnce.count, sessionMs };
+    return {
+        ok: true,
+        count: atOnce.count,
+        ...planStarts(runner.participants, slots, atOnce.lowered),
+    };
 }
 /** The plan's rerun: the source run and, when given, the participants to rerun. */
 function rerunPlan({ sourceRunId, participantIds, }) {
@@ -293,25 +304,22 @@ export function planComputerUseStudy(config, input) {
         : isLocalBrowserStudy(config)
             ? { desktop: "local-vm", brain, participants: [first, ...rest], subject: appUrlSubject }
             : { desktop: "e2b-desktop", brain, participants: [first, ...rest], subject: hosted };
-    const atOnce = concurrencyOf(config, runner, input.concurrentSandboxes);
-    if (!atOnce.ok)
-        return refuse("after-personas", "HUMANISH_COMPUTER_USE_FANOUT_INVALID", atOnce.message, actor);
+    const starts = startsOf(config, runner, input.concurrentSandboxes, ceiling.ms);
+    if (!starts.ok)
+        return refuse("after-personas", "HUMANISH_COMPUTER_USE_FANOUT_INVALID", starts.message, actor);
     const provisioned = source === "clone" || source === "local-tree";
-    const base = planBase(config, {
-        dryRun: input.dryRun,
-        analysis,
-        participants: participants.length,
-    });
+    const base = planBase(config, { dryRun: input.dryRun, analysis });
     return {
         ok: true,
         plan: {
             ...base,
-            ...(atOnce.lowered === undefined ? {} : { warnings: [atOnce.lowered] }),
+            ...(starts.warnings.length === 0 ? {} : { warnings: starts.warnings }),
             route: "computer-use",
             actor,
             runner,
-            concurrency: atOnce.count,
-            sessionBudgetMs: config.execution?.timeoutMs ?? defaultSessionTimeoutMs(config, ceiling.ms),
+            concurrency: starts.count,
+            arrivals: starts.arrivals,
+            sessionBudgetMs: starts.arrivals.sessionMs,
             sandboxMs: resolveParticipantSandboxMs(config, ceiling.ms),
             caps: planCaps(config),
             ...(input.rerun === undefined ? {} : { rerun: rerunPlan(input.rerun) }),

package/dist/routes/computer-use/rerun-selection.js

@@ -57,12 +57,17 @@ export async function resolveCuaRerunSelection(args) {
             message: `${plural(missingCurrent.length, "selected participant id")} ${missingCurrent.length === 1 ? "is" : "are"} not present in the current study file ${args.studyId}: ${missingCurrent.join(", ")}`,
         };
     }
-    const selectedSpecs = selectedIds.map((id) => specsById.get(id));
+    // A rerun runs the selected participants again now, all together: the study's start offsets
+    // placed them in the first run's day, and that day is over.
+    const selectedSpecs = selectedIds.map((id) => startingWithTheRun(specsById.get(id)));
     const selectedPlanIds = new Set(selectedIds);
-    const selectedPlanEntries = args.participantPlan.lanes.filter((entry) => selectedPlanIds.has(entry.id));
+    const selectedPlanEntries = args.participantPlan.lanes
+        .filter((entry) => selectedPlanIds.has(entry.id))
+        .map(({ startAfterMs: _offset, ...entry }) => entry);
     const concurrency = Math.max(1, Math.min(args.participantPlan.concurrency, selectedSpecs.length));
+    const { schedule: _schedule, ...unscheduled } = args.participantPlan;
     const participantPlan = {
-        ...args.participantPlan,
+        ...unscheduled,
         laneCount: selectedSpecs.length,
         concurrency,
         waves: Math.ceil(selectedSpecs.length / concurrency),
@@ -81,6 +86,12 @@ export async function resolveCuaRerunSelection(args) {
         },
     };
 }
+function startingWithTheRun(spec) {
+    if (spec.planned.startAfterMs === undefined)
+        return spec;
+    const { startAfterMs: _offset, ...planned } = spec.planned;
+    return { ...spec, planned };
+}
 function uniqueIds(values) {
     const seen = new Set();
     const result = [];

package/dist/routes/computer-use/types.d.ts

@@ -12,6 +12,7 @@ import { type CuaDiagnostics } from "./diagnostics.js";
 import type { ActorCompletionReason, ActorStatus, ActorStopCause, ActorTokenUsage, ActorTraceItem } from "../../actors/contract.js";
 import { type CuaActorDescriptor } from "../../actors/registry.js";
 import type { StudyDeps } from "../../study/study-deps.js";
+import type { ArrivalPlan, ParticipantArrival } from "../../study/arrivals.js";
 import type { StudyEvent, ParticipantRef } from "../../study/run-study-events.js";
 import type { InProcessDriver, ProviderFactory, RunStudyHomes } from "../../study/run-study-homes.js";
 import { type BrowserScorer } from "../../study/adapter-extension.js";
@@ -108,6 +109,8 @@ export interface CuaParticipantPlanEntry {
     maxOutputTokens?: number;
     /** Present only when a participant overrides subject.appUrl; digest avoids leaking preview hosts in plan logs. */
     targetDigest?: string;
+    /** The participant's declared start, in ms after the run starts its participants. */
+    startAfterMs?: number;
 }
 /** The pre-flight spend and participant plan (pure; printed to stderr + recorded as a bundle event before
  *  any sandbox or provider call; identical in dry-run, marked $0). */
@@ -126,6 +129,9 @@ export interface CuaParticipantPlan {
     perLaneSessionBudgetMs: number;
     /** Worst-case total sandbox-minutes across all participants (each one's full sandbox deadline). */
     worstCaseSandboxMinutes: number;
+    /** The schedule, when the study declares `participants[].startAfterMs`; a rerun starts its
+     *  participants together and has none. */
+    schedule?: ArrivalPlan;
     /** True for a dry-run plan (no spend); the same table appears live. */
     dryRun: boolean;
     lanes: CuaParticipantPlanEntry[];
@@ -261,7 +267,8 @@ export interface ParticipantRunsAndPlan {
 /**
  * The study's shared spend ledger: one counter across every participant. Each one notes its
  * own latest running model-spend estimate (monotone per participant: an estimate can only grow)
- * and reads back the run total; the loop stops the participant the moment the total crosses the study budget.
+ * and reads back the run total; the loop stops the participant the moment the total crosses the study budget,
+ * and a participant whose start comes after that is skipped before its desktop is created.
  * Estimated model spend only: desktop-minutes ride the cost summary, not this ledger.
  */
 export interface CuaRunBudget {
@@ -269,6 +276,9 @@ export interface CuaRunBudget {
     /** Record this participant's latest running estimate (null = unpriceable, ignored) and return
      *  the run's current total across all participants. */
     note(participantId: string, estimateUsd: number | null): number;
+    /** The run total against caps.maxTotalUsd once the total has crossed it, in words; undefined
+     *  while it has not. */
+    crossed(): string | undefined;
 }
 /**
  * The subject as a participant's desktop meets it. A computer-use participant gets the plan's
@@ -427,6 +437,8 @@ export interface ParticipantRunOutcome {
     warnings: string[];
     /** Set when the participant was skipped by the pipeline gate / fail-fast (a pinned reason). */
     skippedReason?: string;
+    /** When a fan-out participant was due and when its desktop was requested. */
+    arrival?: ParticipantArrival;
     noEngagement: boolean;
     selfReportedBlocker: boolean;
     /** The inclusive friction read: blocker-shaped narration incl. self-resolved arcs.

package/dist/routes/shared-world/bundle-records.js

@@ -7,6 +7,7 @@ import { declaredScreenForRender } from "../../substrates/e2b/desktop-geometry.j
 import { publicSafeRouteLabel } from "./provenance.js";
 import { participantCaption } from "../../run/participant-caption.js";
 import { participantSummary } from "../../run/outcomes.js";
+import { arrivalRecord } from "../../study/arrivals.js";
 function participantView(ctx, spec, index) {
     const { args, external } = ctx;
     const name = participantCaption({ id: spec.planned.id, personaId: spec.persona.id });
@@ -69,8 +70,21 @@ function sharedWorldSimulation(ctx, spec, index, view) {
         summary: participantSummary(name, { name: "the shared app" }, { trace: session?.trace, sessionError: outcome?.sessionError, inProgress }),
         startedAt: args.run.createdAt,
         updatedAt: args.run.createdAt,
+        ...(args.plan.arrivals.declared
+            ? {
+                arrival: arrivalRecord(spec.planned.startAfterMs, actorArrival(args.actorResults[index])),
+            }
+            : {}),
     });
 }
+// A follower the handoff stopped before it opened the app never started its desktop.
+function actorArrival(result) {
+    if (result === undefined)
+        return undefined;
+    return result.outcome.skippedReason === undefined
+        ? { scheduledAt: result.scheduledAt, startedAt: result.startedAt }
+        : { scheduledAt: result.scheduledAt };
+}
 function sharedWorldStream(ctx, spec, index, view) {
     const { args } = ctx;
     const { name, session, screenshots, lastScreenshot, desktopGeometry, screenshotMode } = view;

package/dist/routes/shared-world/bundle.js

@@ -18,6 +18,7 @@ import { sharedWorldParticipantRecords } from "./bundle-records.js";
 import { CONCURRENT_ATTRIBUTION_LIMITS, EXTERNAL_PUBLIC_ATTRIBUTION_LIMITS, } from "./types.js";
 import { gapsListClause } from "../../run/outcomes.js";
 import { plural } from "../../run/text.js";
+import { describeArrivals } from "../../study/arrivals.js";
 /** Max windows live at the same instant (sweep over start/end points). The simultaneity
  *  count: the participant count says how many existed; this says how many ever ran at once. */
 export function maxSimultaneousWindows(windows) {
@@ -107,7 +108,7 @@ function planeEvents(args, external) {
         at: createdAt,
         level: "info",
         type: "concurrent-shared-world.run.created",
-        message: `Created a concurrent shared-world run for ${plan.studyId} (actor ${descriptor.id}, ${plural(actorSpecs.length, "persona")} on one shared app, at most ${plan.concurrency} at once).`,
+        message: `Created a concurrent shared-world run for ${plan.studyId} (actor ${descriptor.id}, ${plural(actorSpecs.length, "persona")} on one shared app, at most ${plan.concurrency} at once).${plan.arrivals.declared ? ` Schedule: ${describeArrivals(plan.arrivals)}` : ""}`,
     });
     // Human-readable plane label, byte-stable for the clone route. local-tree has no repo slug: it
     // labels the packed archive instead (archiveSha256 + dirty/clean when the packed root was a git

package/dist/routes/shared-world/external-public.js

@@ -6,7 +6,7 @@
 // deadline.
 import { liveObserverResult } from "../../observer/live.js";
 import { redactText, toErrorMessage } from "../../evidence/redaction.js";
-import { mapWithConcurrency } from "../../run/concurrency.js";
+import { runOnSchedule } from "../../study/arrivals.js";
 import { buildConcurrentSharedWorldBundle, judgeSharedWorldRun } from "./bundle.js";
 import { drainExternalComms } from "./comms.js";
 import { LobbyHandoff, runFollower, runHost } from "./handoff.js";
@@ -95,10 +95,22 @@ export async function runExternalPublicPlane(ctx, live, inbox) {
         .filter(({ index }) => index !== hostIndex);
     const orderedResults = new Array(actorSpecs.length);
     try {
+        // The host starts with the run (parse refuses a later start for it); the followers start on
+        // the study's schedule.
         const hostPromise = hostIndex >= 0 && actorSpecs[hostIndex] !== undefined
-            ? runHost(handoff, deps, actorSpecs[hostIndex], hostIndex)
+            ? runHost(handoff, deps, actorSpecs[hostIndex], hostIndex).then((result) => ({
+                ...result,
+                scheduledAt: result.startedAt,
+            }))
             : undefined;
-        const followerResultsPromise = mapWithConcurrency(followerEntries, Math.max(1, concurrency - 1), ({ spec, index }) => runFollower(handoff, deps, spec, index));
+        const followerResultsPromise = runOnSchedule(followerEntries, {
+            startAfterMs: ({ spec }) => spec.planned.startAfterMs,
+            slots: Math.max(1, concurrency - 1),
+            now: ctx.now,
+        }, async ({ spec, index }, _position, { scheduledAt }) => ({
+            ...(await runFollower(handoff, deps, spec, index)),
+            scheduledAt,
+        }));
         const [hostResult, followerResults] = await Promise.all([hostPromise, followerResultsPromise]);
         if (hostResult !== undefined && hostIndex >= 0) {
             orderedResults[hostIndex] = hostResult;

package/dist/routes/shared-world/handoff.d.ts

@@ -59,5 +59,5 @@ export declare class LobbyHandoff {
         lobbyConvergenceDigest: string | undefined;
     };
 }
-export declare function runHost(handoff: LobbyHandoff, deps: HandoffParticipantDeps, spec: DesktopParticipantRun, participantIndex: number): Promise<ActorRunResult>;
-export declare function runFollower(handoff: LobbyHandoff, deps: HandoffParticipantDeps, spec: DesktopParticipantRun, participantIndex: number): Promise<ActorRunResult>;
+export declare function runHost(handoff: LobbyHandoff, deps: HandoffParticipantDeps, spec: DesktopParticipantRun, participantIndex: number): Promise<Omit<ActorRunResult, "scheduledAt">>;
+export declare function runFollower(handoff: LobbyHandoff, deps: HandoffParticipantDeps, spec: DesktopParticipantRun, participantIndex: number): Promise<Omit<ActorRunResult, "scheduledAt">>;

package/dist/routes/shared-world/plan.d.ts

@@ -24,5 +24,12 @@ export declare function planSharedWorldStudy(config: StudyConfig, input: {
     /** How many sandboxes the operator's E2B plan runs at once (concurrentSandboxes). */
     readonly concurrentSandboxes: ConcurrentSandboxes;
 }): SharedWorldPlanResult;
+/**
+ * The schedule lines a shared-world run prints before it creates anything, when the study declares
+ * `participants[].startAfterMs`: the schedule, and the worst case in sandbox-minutes, which counts
+ * every participant's sandbox (its session plus the teardown buffer) and on the provisioned plane
+ * the app's sandbox until the last participant ends.
+ */
+export declare function sharedWorldScheduleLines(plan: SharedWorldPlan): string;
 /** The provisioned plane's declared subject state. The external-public plane declares none. */
 export declare function planeStateOf(plan: SharedWorldPlan): StudySubjectState | undefined;