humanish 0.121.0 → 0.122.0

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

@@ -1,3 +1,4 @@
+import { scheduledParticipantDeps } from "./participant-runs.js";
 import { judgeParticipantRecords } from "../../run/judge.js";
 import { createE2BParticipantDesktop } from "./e2b-desktop/desktop.js";
 import { createInProcessDesktop } from "./in-process-desktop.js";
@@ -31,7 +32,7 @@ export function makeParticipantWriteScreenshot(artifactRoot, spec, screenshots)
         return rel;
     };
 }
-/** A blocked participant outcome (pipeline gate / fail-fast skipped it before it ran). */
+/** A blocked participant outcome: the pipeline gate or the study budget skipped it. */
 function skippedOutcome(spec, reason, arrival) {
     return {
         spec,
@@ -110,8 +111,8 @@ export async function runCuaParticipant(spec, deps) {
     if (session)
         await recordParticipantTrace(spec, deps, session, warnings);
     const { noEngagement, selfReportedBlocker, reportedFriction } = judgeParticipantSession(session, deps, warnings);
-    // A provider-cleanup or provider-policy failure still trips fail-fast and counts in the
-    // participant summary's harness errors.
+    // A provider-cleanup or provider-policy failure counts in the participant summary's harness
+    // errors.
     const harnessError = sessionError !== undefined ||
         providerCleanupError !== undefined ||
         providerPolicyError !== undefined ||
@@ -191,33 +192,26 @@ function pipelineGate(open, onClose) {
 }
 /**
  * Run N>1 E2B participants on the study's schedule (runOnSchedule: each at its start offset, at
- * most `concurrency` at once), behind the pipeline gate when the subject is set up in each sandbox,
- * 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 participant that stops before its
- * session has failed on its own and trips no fail-fast. A closed gate 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.
+ * most `concurrency` at once), behind the pipeline gate when the subject is set up in each sandbox.
+ * A harness error ends only its own participant: one desktop's stall or one provider failure does
+ * not predict the next participant's, so the schedule goes on. Only a closed gate ends every wait
+ * for a later start at once, and the participants it skips are `blocked` with its reason. 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
  * the default.
  */
 export async function runCuaParticipants(runs, deps, concurrency, runParticipant = runCuaParticipant) {
-    const failFast = { tripped: false, reason: "" };
     const stopping = new AbortController();
     // An app-url subject is only opened, so one participant's start says nothing about another's.
     const gate = pipelineGate(deps.subject.kind === "app-url", () => stopping.abort());
-    const outcomes = await runOnSchedule(runs, {
+    return runOnSchedule(runs, {
         startAfterMs: (spec) => spec.planned.startAfterMs,
         slots: concurrency,
         now: deps.now,
         signal: stopping.signal,
     }, async (spec, _index, { scheduledAt }) => {
-        if (failFast.tripped) {
-            return skippedOutcome(spec, `skipped: ${failFast.reason}`, { scheduledAt });
-        }
-        // A participant trips fail-fast only after the gate opened, or as it closes the gate, so no
-        // participant is still waiting at the gate when fail-fast skips the rest.
         const id = spec.planned.id;
         if ((await gate.enter(id)) === "closed") {
             return skippedOutcome(spec, `skipped: participant ${gate.holder()} failed to provision its world (pipeline gate)`, { scheduledAt });
@@ -233,6 +227,7 @@ export async function runCuaParticipants(runs, deps, concurrency, runParticipant
         try {
             outcome = await runParticipant(spec, {
                 ...deps,
+                ...scheduledParticipantDeps(spec.planned, deps, scheduledAt),
                 signalReady: () => {
                     ready = true;
                     gate.ready();
@@ -258,23 +253,17 @@ export async function runCuaParticipants(runs, deps, concurrency, runParticipant
                 endedAt: deps.now(),
             };
         }
-        // A participant that stopped before its session failed on its own and trips no fail-fast.
-        // Without a desktop it says nothing about the subject, so the next participant starts first.
-        // A runner that threw is a harness defect: it closes the gate and trips fail-fast.
+        // A participant that stopped before its session without a desktop says nothing about the
+        // subject, so the next participant starts first. A runner that threw is a harness defect: it
+        // closes the gate.
         if (!ready)
             gate.failed(id, { handOver: !threw && outcome.sandboxId === undefined });
-        if (outcome.harnessError && (ready || threw) && !failFast.tripped) {
-            failFast.tripped = true;
-            failFast.reason = `a prior participant (${outcome.spec.planned.id}) ended in a harness error (fail-fast)`;
-            stopping.abort();
-        }
         // 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 } : {}) };
 }
 /** Project one participant outcome (or a dry-run contract spec) into the public CuaParticipantResult. */
 export function toParticipantResult(spec, outcome, subject, dryRun) {
@@ -369,19 +358,21 @@ export function toParticipantResult(spec, outcome, subject, dryRun) {
 }
 /**
  * Run every participant of a live run. The in-process route drives its single participant in this
- * process; one hosted participant runs alone; a fan-out runs at the plan's concurrency and may stop early.
+ * process; one hosted participant runs alone; a fan-out runs at the plan's concurrency, and stops
+ * early only when the pipeline gate closes.
  */
 export async function runAllCuaParticipants(runs, deps, participantPlan, inProcess) {
+    // A participant that runs alone starts with the run.
+    const alone = { ...deps, ...scheduledParticipantDeps(runs[0].planned, deps, deps.now()) };
     if (inProcess) {
         // The caller's executor stands in for a desktop, and the shared runner drives the participant.
         const outcome = await runCuaParticipant(runs[0], {
-            ...deps,
+            ...alone,
             createDesktop: () => createInProcessDesktop(deps),
         });
-        return { outcomes: [outcome], failFastReason: undefined };
+        return [outcome];
     }
     if (runs.length === 1)
-        return { outcomes: [await runCuaParticipant(runs[0], deps)], failFastReason: undefined };
-    const ran = await runCuaParticipants([...runs], deps, participantPlan.concurrency);
-    return { outcomes: ran.outcomes, failFastReason: ran.failFastReason };
+        return [await runCuaParticipant(runs[0], alone)];
+    return runCuaParticipants([...runs], deps, participantPlan.concurrency);
 }

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

@@ -99,6 +99,7 @@ export function participantSessionOptions(spec, deps, ready, provider, writeScre
             : spec.instructions,
         persona: spec.persona,
         timeoutMs: deps.timeoutMs,
+        ...participantClock(spec.planned.limits.timeZone, deps),
         // The brain is either a keyed API client or a CLI the operator is already signed in to.
         // Everything below this line (loop, executor, trace, affordances) is identical either
         // way, which is what makes a local-agent run comparable to an API one.
@@ -305,3 +306,19 @@ export function makeCuaRunBudget(maxTotalUsd) {
         },
     };
 }
+/**
+ * The participant's clock: its time zone, and its scheduled end on the run's clock. A participant
+ * with an end runs its session on the run's clock, so the end and the schedule read one clock.
+ */
+function participantClock(timeZone, deps) {
+    const { scheduledEnd } = deps;
+    if (timeZone === undefined && scheduledEnd === undefined)
+        return {};
+    return {
+        clock: {
+            ...(timeZone === undefined ? {} : { timeZone }),
+            ...(scheduledEnd === undefined ? {} : { end: scheduledEnd }),
+        },
+        ...(scheduledEnd === undefined ? {} : { now: deps.now }),
+    };
+}

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

@@ -3,7 +3,8 @@ import { type StudyConfig } from "../../study/types.js";
 import { type ResolvedPersona } from "../../study/persona.js";
 import { type RunRerunLineage } from "../../run/bundle.js";
 import type { PreparedSelectedOutputDirectory } from "../../run/contained-output.js";
-import { type CuaActorStudyErrorCode, type CuaParticipantPlan, type CuaParticipantPlanEntry, type DesktopParticipantRun, type ParticipantRunsAndPlan } from "./types.js";
+import { type CuaActorStudyErrorCode, type CuaParticipantDeps, type CuaParticipantPlan, type CuaParticipantPlanEntry, type DesktopParticipantRun, type ParticipantRunsAndPlan } from "./types.js";
+import { type ParticipantWindow } 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.
@@ -16,6 +17,15 @@ export declare function defaultSessionTimeoutMs(config: StudyConfig, ceilingMs:
  *  git clone for an upload+extract, but the shared install/build/state/start/probe pipeline
  *  costs the same wall-clock room either way. */
 export declare function resolveParticipantSandboxMs(config: StudyConfig, ceilingMs: number): number;
+/**
+ * The deps one participant runs with once its start comes: its own session budget and sandbox
+ * deadline, and with a declared end, that end on the run's clock (`scheduledAt` is when it was
+ * due, from runOnSchedule).
+ */
+export declare function scheduledParticipantDeps(participant: ParticipantWindow, deps: {
+    readonly timeoutMs: number;
+    readonly sandboxMs: number;
+}, scheduledAt: number): Pick<CuaParticipantDeps, "timeoutMs" | "sandboxMs" | "scheduledEnd">;
 /**
  * The in-flight participant bound a study declares. Defaults to the participant count: every
  * declared participant runs at once, because a throttle nobody asked for silently turns "N actors

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

@@ -18,7 +18,7 @@ import { composeParticipantInstructions, DEFAULT_MISSION } from "./participant-p
 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";
+import { describeArrivals, participantSessionMs, planArrivals, scheduledEndAt, } 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.
@@ -45,6 +45,30 @@ export function resolveParticipantSandboxMs(config, ceilingMs) {
         timeoutMs +
             sandboxHeadroomMs(provisionedRoute ? { seed: config.subject.state?.seed ?? [] } : undefined));
 }
+/**
+ * A participant's own session budget and sandbox deadline: the study's, or with a declared end its
+ * window plus room for the closing report (participantSessionMs), with the same setup and
+ * teardown headroom the study's sandbox has over its session.
+ */
+function participantWindow(participant, study) {
+    const timeoutMs = participantSessionMs(participant, study.sessionBudgetMs);
+    return { timeoutMs, sandboxMs: study.sandboxMs - study.sessionBudgetMs + timeoutMs };
+}
+/**
+ * The deps one participant runs with once its start comes: its own session budget and sandbox
+ * deadline, and with a declared end, that end on the run's clock (`scheduledAt` is when it was
+ * due, from runOnSchedule).
+ */
+export function scheduledParticipantDeps(participant, deps, scheduledAt) {
+    const end = scheduledEndAt(participant, scheduledAt);
+    return {
+        ...participantWindow(participant, {
+            sessionBudgetMs: deps.timeoutMs,
+            sandboxMs: deps.sandboxMs,
+        }),
+        ...(end === undefined ? {} : { scheduledEnd: end }),
+    };
+}
 /**
  * The in-flight participant bound a study declares. Defaults to the participant count: every
  * declared participant runs at once, because a throttle nobody asked for silently turns "N actors
@@ -114,10 +138,11 @@ export function participantRunsAndPlan(plan, opts = {}) {
     });
     const resolved = envLoweredConcurrency(plan.concurrency, participantCount, env);
     const concurrency = resolved.bound;
-    const { sessionBudgetMs, sandboxMs } = plan;
+    const { sessionBudgetMs } = plan;
     const schedule = resolved.envLoweredFrom === undefined
         ? plan.arrivals
-        : planArrivals(participants.map((participant) => participant.startAfterMs), { slots: concurrency, sessionMs: sessionBudgetMs });
+        : planArrivals(participants.map((participant) => participant.startAfterMs), { slots: concurrency, sessionMs: sessionBudgetMs }, participants.map((participant) => participantSessionMs(participant, sessionBudgetMs)));
+    const sandboxesMs = participants.reduce((sum, participant) => sum + participantWindow(participant, plan).sandboxMs, 0);
     const participantPlan = {
         strategy: CUA_FANOUT_STRATEGY,
         laneCount: participantCount,
@@ -127,7 +152,7 @@ export function participantRunsAndPlan(plan, opts = {}) {
             : { envLoweredConcurrencyFrom: resolved.envLoweredFrom }),
         waves: Math.ceil(participantCount / concurrency),
         perLaneSessionBudgetMs: sessionBudgetMs,
-        worstCaseSandboxMinutes: Math.round((participantCount * sandboxMs) / 60_000),
+        worstCaseSandboxMinutes: Math.round(sandboxesMs / 60_000),
         ...(schedule.declared ? { schedule } : {}),
         dryRun: plan.dryRun,
         lanes: runs.map((spec) => ({
@@ -158,6 +183,7 @@ export function participantRunsAndPlan(plan, opts = {}) {
             ...(spec.planned.startAfterMs === undefined
                 ? {}
                 : { startAfterMs: spec.planned.startAfterMs }),
+            ...(spec.planned.endAfterMs === undefined ? {} : { endAfterMs: spec.planned.endAfterMs }),
         })),
     };
     return { runs, participantPlan };
@@ -182,6 +208,7 @@ export function formatParticipantPlanEntry(entry) {
         entry.caseGroup ? `case=${entry.caseGroup}` : undefined,
         entry.reasoningEffort ? `effort=${entry.reasoningEffort}` : undefined,
         entry.startAfterMs === undefined ? undefined : `start=+${formatDuration(entry.startAfterMs)}`,
+        entry.endAfterMs === undefined ? undefined : `end=+${formatDuration(entry.endAfterMs)}`,
     ].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,7 +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 { planStarts, windowDeadlineRefusal } 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";
@@ -209,6 +209,13 @@ function startsOf(config, runner, limit, ceilingMs) {
     if (!atOnce.ok)
         return atOnce;
     const sessionMs = config.execution?.timeoutMs ?? defaultSessionTimeoutMs(config, ceilingMs);
+    // A participant with a declared end gets a sandbox sized from its own window.
+    if (runner.desktop === "e2b-desktop") {
+        const headroomMs = resolveParticipantSandboxMs(config, ceilingMs) - sessionMs;
+        const window = windowDeadlineRefusal(runner.participants, { sessionMs, headroomMs }, ceilingMs);
+        if (window !== undefined)
+            return { ok: false, message: window };
+    }
     const slots = { slots: atOnce.count, sessionMs };
     return {
         ok: true,

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

@@ -201,7 +201,7 @@ export async function finishCuaRun(setup, finish, ran) {
     const appUrl = plannedAppUrl(plan.runner.subject);
     const { runId } = run;
     const participantCount = participantRuns.length;
-    const { outcomes, failFastReason, receiving, receivingWarnings, externalCommsWarnings } = ran;
+    const { outcomes, receiving, receivingWarnings, externalCommsWarnings } = ran;
     // Per-participant subject projections.
     const subjects = projectParticipantSubjects({ ...subjectArgs, outcomes, dryRun });
     const aggregate = aggregateCuaSubject({ subjects, outcomes, participantCount, dryRun });
@@ -222,7 +222,6 @@ export async function finishCuaRun(setup, finish, ran) {
         outcomes,
         subjects,
         aggregateSubject,
-        ...(failFastReason === undefined ? {} : { failFastReason }),
         ...(hostSuspension === undefined ? {} : { hostSuspension }),
     });
     const adapterWarnings = [];

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

@@ -112,6 +112,8 @@ export interface CuaParticipantPlanEntry {
     targetDigest?: string;
     /** The participant's declared start, in ms after the run starts its participants. */
     startAfterMs?: number;
+    /** The participant's declared end, on the same clock. */
+    endAfterMs?: 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). */
@@ -138,7 +140,8 @@ export interface CuaParticipantPlan {
     lanes: CuaParticipantPlanEntry[];
 }
 /** One participant's outcome in the result projection. Always present in `result.lanes` (length
- *  1 at N=1). A `blocked` participant is one the pipeline-gate / fail-fast skipped before it ran. */
+ *  1 at N=1). A `blocked` participant is one the pipeline gate or the study budget skipped before
+ *  it ran. */
 export interface CuaParticipantResult {
     id: string;
     actorType?: string;
@@ -149,7 +152,7 @@ export interface CuaParticipantResult {
     device: string;
     /** Requested E2B/X screen resolution. See the run stream's desktopGeometry for measurements. */
     resolution: [number, number];
-    /** Terminal participant status; "blocked" = skipped (gate/fail-fast); "contract_proof_only" = dry-run. */
+    /** Terminal participant status; "blocked" = skipped (gate or study budget); "contract_proof_only" = dry-run. */
     status: ActorStatus | "blocked" | "contract_proof_only";
     ok: boolean;
     session?: {
@@ -183,7 +186,7 @@ export interface CuaParticipantSummary {
     total: number;
     /** Participants whose own verdict is ok (terminal, engaged, no harness error). */
     passed: number;
-    /** Participants skipped by the pipeline gate / fail-fast. */
+    /** Participants skipped by the pipeline gate or the study budget. */
     skipped: number;
     /** Participants that ended in a harness error. */
     harnessErrors: number;
@@ -363,6 +366,16 @@ export interface ParticipantModelDeps {
     env: Record<string, string | undefined>;
     openaiApiKey: string;
     timeoutMs: number;
+    /**
+     * The participant's scheduled end on `now`'s clock, when it declares participants[].endAfterMs
+     * (scheduledParticipantDeps). Its session ends there with stop cause `scheduled_end`.
+     */
+    scheduledEnd?: {
+        readonly atMs: number;
+        readonly windDownMs: number;
+    };
+    /** The run's clock. A participant with a scheduled end runs its session on it. */
+    now: () => number;
     participantCount: number;
     artifactRoot: PreparedOutputRoot;
     redactScreenshots: boolean;
@@ -441,7 +454,7 @@ export interface ParticipantRunOutcome {
      *  folded into bundle.events at build time. Empty on the in-process route (no provisioning). */
     phaseRecords: SubjectPhaseEvent[];
     warnings: string[];
-    /** Set when the participant was skipped by the pipeline gate / fail-fast (a pinned reason). */
+    /** Set when the pipeline gate or the study budget skipped the participant (a pinned reason). */
     skippedReason?: string;
     /** When a fan-out participant was due and when its desktop was requested. */
     arrival?: ParticipantArrival;
@@ -481,7 +494,6 @@ export interface CuaFanoutBundleArgs {
     source: RunBundle["source"];
     participantPlan: CuaParticipantPlan;
     rerun?: RunRerunLineage;
-    failFastReason?: string;
     /** The run's host suspensions and the participant failures they likely caused. */
     hostSuspension?: HostSuspensionReading;
     publicRepo?: string;

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

@@ -383,8 +383,8 @@ async function publishInProgress(plane, ctx, live, setup) {
     startParticipantFlush(ctx, live, inProgressBundle);
 }
 // Launch N actor sandboxes independently on the study's schedule (runCuaParticipant +
-// runOnSchedule; runCuaParticipants would add a pipeline gate and fail-fast). Each actor's window is
-// measured on the one orchestrator clock.
+// runOnSchedule; runCuaParticipants would add a pipeline gate). Each actor's window is measured on
+// the one orchestrator clock.
 function runParticipants(plane, ctx, live, setup) {
     const { now } = ctx;
     const participants = ctx.plan.plane.participants;

package/dist/run/host-suspension.d.ts

@@ -50,7 +50,7 @@ export interface HostSuspensionReading {
  * without a suspension. A frozen loop's failures surface at the wake (macOS fires every overdue
  * timer at once) or up to a turn timeout later (Linux timers do not count suspended time), so the
  * rule reads who was in flight across the suspension. A skip follows another participant's
- * harness error (the pipeline gate, fail-fast), so skips count only when the run had harness
- * errors and every one was in flight across a suspension.
+ * harness error (the pipeline gate), so skips count only when the run had harness errors and
+ * every one was in flight across a suspension.
  */
 export declare function readHostSuspensions(suspensions: readonly HostSuspension[], participants: readonly SuspendedParticipant[], runStartMs: number): HostSuspensionReading | undefined;

package/dist/run/host-suspension.js

@@ -79,8 +79,8 @@ function inFlight(participant, suspension) {
  * without a suspension. A frozen loop's failures surface at the wake (macOS fires every overdue
  * timer at once) or up to a turn timeout later (Linux timers do not count suspended time), so the
  * rule reads who was in flight across the suspension. A skip follows another participant's
- * harness error (the pipeline gate, fail-fast), so skips count only when the run had harness
- * errors and every one was in flight across a suspension.
+ * harness error (the pipeline gate), so skips count only when the run had harness errors and
+ * every one was in flight across a suspension.
  */
 export function readHostSuspensions(suspensions, participants, runStartMs) {
     if (suspensions.length === 0)

package/dist/run/judge.d.ts

@@ -34,7 +34,7 @@ export interface ParticipantFacts {
     completionReason?: ActorCompletionReason;
     /** The harness failed before the session reached a terminal status. */
     sessionError?: string;
-    /** The pipeline gate or fail-fast skipped the participant. */
+    /** The pipeline gate or the study budget skipped the participant. */
     skipped: boolean;
     /** hollowCompletion held for its session. */
     noEngagement: boolean;

package/dist/study/arrivals.d.ts

@@ -6,6 +6,54 @@ import type { RunParticipantArrival } from "../run/bundle.js";
 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;
+/** How long before its end a participant is told the time left, unless it declares `windDownMs`. */
+export declare const DEFAULT_WIND_DOWN_MS: number;
+/** A participant's declared window: when it starts and when it ends, on the run's clock. */
+export interface ParticipantWindow {
+    readonly id?: string;
+    readonly startAfterMs?: number;
+    readonly endAfterMs?: number;
+    readonly windDownMs?: number;
+}
+/**
+ * Why a participant's declared end cannot run, or undefined: an end that is not a whole number of
+ * milliseconds up to 24 hours, one at or before its start, or a wind-down that is not a whole
+ * number of milliseconds or has no end. `path` names the entry, as in "participants[1]".
+ */
+export declare function windowReason(entry: {
+    readonly id?: string;
+    readonly startAfterMs?: number;
+    readonly endAfterMs?: unknown;
+    readonly windDownMs?: unknown;
+}, path: string): string | undefined;
+/**
+ * A participant's session budget: with a declared end, its window plus SCHEDULED_END_ROOM_MS in
+ * place of the study's `sessionMs` (execution.timeoutMs or its default); else `sessionMs`.
+ */
+export declare function participantSessionMs(participant: ParticipantWindow, sessionMs: number): number;
+/**
+ * When a participant that was due at `scheduledAt` (runOnSchedule's ScheduledStart) ends, on the
+ * same clock, or undefined when it declares no end. A participant that waited for a slot still ends
+ * at its declared time.
+ */
+export declare function scheduledEndAt(participant: ParticipantWindow, scheduledAt: number): {
+    readonly atMs: number;
+    readonly windDownMs: number;
+} | undefined;
+/**
+ * Why the sandbox of the first participant whose window passes `ceilingMs` cannot live that long,
+ * or undefined. Its deadline is its session (participantSessionMs) plus `headroomMs`, what the
+ * route adds to a session for setup and teardown (sandboxHeadroomMs).
+ */
+export declare function windowDeadlineRefusal(participants: readonly ParticipantWindow[], sandbox: {
+    readonly sessionMs: number;
+    readonly headroomMs: number;
+}, ceilingMs: number): string | undefined;
+/**
+ * Each participant's window for `study check`, when any participant declares an end: when it starts
+ * and ends and when it is first told the time left, or when it starts and its session budget.
+ */
+export declare function describeWindows(participants: readonly ParticipantWindow[], sessionMs: number): string | undefined;
 /** The refusal of a start offset that is not one, naming its `field`. */
 export declare function startAfterMessage(field: string): string;
 /**
@@ -49,9 +97,10 @@ export interface StartQueue {
  * 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.
+ * follows. `sessionsMs` gives a participant with a declared end its own session budget
+ * (participantSessionMs); the others hold their slot for `queue.sessionMs`.
  */
-export declare function planArrivals(offsets: readonly (number | undefined)[], queue: StartQueue): ArrivalPlan;
+export declare function planArrivals(offsets: readonly (number | undefined)[], queue: StartQueue, sessionsMs?: readonly number[]): ArrivalPlan;
 /**
  * The plan's schedule, after a "schedule:" label: the first and last start, and how many run at
  * once at the most.
@@ -64,9 +113,7 @@ export declare function describeArrivals(arrivals: ArrivalPlan): string;
  * 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): {
+export declare function planStarts(participants: readonly ParticipantWindow[], queue: StartQueue, lowered: string | undefined): {
     arrivals: ArrivalPlan;
     warnings: string[];
 };