humanish 0.121.0 → 0.123.0

package/dist/study/bundle-estimate.js

@@ -0,0 +1,159 @@
+// How large a computer-use run's bundle grows, estimated from its plan before anything runs, and
+// whether it would pass a limit a later command holds it to: analysis reads a run.json of at most
+// EVIDENCE_LIMITS.sourceBytes, verify reads no file larger than RUN_ARTIFACT_MAX_BYTES, and the
+// public-safety scan visits at most runEntryLimit(participants) files and folders.
+import { EVIDENCE_LIMITS } from "../analysis/analysis-limits.js";
+import { RUN_ARTIFACT_MAX_BYTES } from "../run/contained-output.js";
+import { formatDuration } from "../run/projection.js";
+import { plural } from "../run/text.js";
+import { runEntryLimit } from "../verify/scan-limit.js";
+// Measured on 2026-10-12. Live: the hosted computer-use bundles kept on the maintainer's machine,
+// 219 runs since 2026-10-01 for run.json's size (a least-squares fit gave 372 bytes a run, 14,368
+// a participant and 2,423 a turn), and for the pace the 42 participant sessions of 5 minutes or
+// more among every kept run since August. Synthetic: runStudyWith on fake desktops, with the live median
+// of about 270 characters of reasoning and message a turn, from 10 to 2,000 turns and from 1 to
+// 16 participants. An adopter's 39-minute run grew run.json about 7 KB a minute for a participant
+// working the whole window; these rates give 12.6 KB, so the estimate errs high, and a limit it
+// passes is a warning.
+const RATES = Object.freeze({
+    /** run.json bytes a minute of the one long live participant measured: the adopter's run. */
+    measuredLongRunBytesPerMinute: 7_000,
+    /** run.json bytes for the run itself: its header, study and scenario. */
+    runBytes: 400,
+    /** run.json bytes for each participant before its turns: its records, events and cost lines. */
+    participantBytes: 14_400,
+    /** run.json bytes a model turn adds. Synthetic: 2,094 to 2,125 a turn over 10 to 2,000 turns. */
+    turnBytes: 2_100,
+    /** run.json bytes a dwell frame adds. Synthetic: 6,247 for 10 frames and the frame after. */
+    frameBytes: 570,
+    /** Seconds between model turns: the median of the 42 long live sessions was 10.3. */
+    secondsPerTurn: 10,
+    /**
+     * How long a participant with no declared end is counted, at most its session budget. It ends
+     * when it finishes its mission: 90 % of 974 live sessions ended within 184 s.
+     */
+    openSessionMs: 3 * 60_000,
+    /** observer-data.json bytes beyond run.json's for each participant: 0.9 to 2.6 KB live. */
+    observerDataParticipantBytes: 2_600,
+    /** observer/index.html: the page, and a share of run.json it embeds (synthetic, 10 to 2,000 turns). */
+    observerPageBytes: 1_190_000,
+    observerPageShare: 0.62,
+    /** A desktop screenshot: the median of 249 live PNG frames was 108,565 bytes. */
+    screenshotBytes: 110_000,
+    /** Run files and folders besides the participants': run.json, status, review, events, receipts, the Observer, analysis. */
+    runEntries: 20,
+    /** A participant's entries besides its turn screenshots: its trace file, its screenshot folder, its first frame. */
+    participantEntries: 3,
+});
+const MIB = 1024 * 1024;
+/**
+ * The bundle a live run of `participants` leaves, each in its session of `sessionMs` unless it
+ * declares an end. A participant with an end works its whole window; one without is counted for
+ * the measured open session above, or its budget when that is shorter. Each takes a model turn at
+ * the measured pace, and a dwell window adds a frame every `everyMs` for its length, cut to the
+ * session, and the frame after it.
+ */
+export function estimateBundle(participants, sessionMs) {
+    let turns = 0;
+    let frames = 0;
+    let longestWindowMs = 0;
+    const openMs = Math.min(sessionMs, RATES.openSessionMs);
+    for (const participant of participants) {
+        const windowMs = participant.endAfterMs === undefined
+            ? undefined
+            : participant.endAfterMs - (participant.startAfterMs ?? 0);
+        if (windowMs !== undefined)
+            longestWindowMs = Math.max(longestWindowMs, windowMs);
+        turns += Math.ceil((windowMs ?? openMs) / (RATES.secondsPerTurn * 1000));
+        const dwell = participant.limits.dwell;
+        if (dwell !== undefined)
+            frames += Math.floor(Math.min(dwell.ms, windowMs ?? sessionMs) / dwell.everyMs) + 1;
+    }
+    const count = participants.length;
+    const runFileBytes = RATES.runBytes +
+        count * RATES.participantBytes +
+        turns * RATES.turnBytes +
+        frames * RATES.frameBytes;
+    const observerDataBytes = runFileBytes + count * RATES.observerDataParticipantBytes;
+    const pageBytes = RATES.observerPageBytes + Math.round(RATES.observerPageShare * runFileBytes);
+    const screenshots = count + turns + frames;
+    const scheduled = participants.filter((participant) => participant.endAfterMs !== undefined);
+    return {
+        runFileBytes,
+        largestFileBytes: Math.max(observerDataBytes, pageBytes),
+        // Each participant's trace file holds about what its stream holds in run.json.
+        totalBytes: 2 * runFileBytes + observerDataBytes + pageBytes + screenshots * RATES.screenshotBytes,
+        entries: RATES.runEntries + count * RATES.participantEntries + turns + frames,
+        entryLimit: runEntryLimit(count),
+        basis: {
+            participants: count,
+            scheduled: scheduled.length,
+            longestWindowMs,
+            open: count - scheduled.length,
+            openMs,
+            dwell: frames > 0,
+        },
+    };
+}
+/**
+ * The warning for a run whose estimate passes a limit, or undefined: each limit it passes, what the
+ * estimate counted, how high it runs, and what to change.
+ */
+export function bundleLimitReason(estimate) {
+    const passed = [
+        ...(estimate.runFileBytes > EVIDENCE_LIMITS.sourceBytes
+            ? [
+                `This study's run.json may grow to about ${mib(estimate.runFileBytes)}, past the ${mib(EVIDENCE_LIMITS.sourceBytes)} analysis reads.`,
+            ]
+            : []),
+        ...(estimate.largestFileBytes > RUN_ARTIFACT_MAX_BYTES
+            ? [
+                `Its largest file, observer/observer-data.json, may grow to about ${mib(estimate.largestFileBytes)}, past the ${mib(RUN_ARTIFACT_MAX_BYTES)} verify reads in one file.`,
+            ]
+            : []),
+        ...(estimate.entries > estimate.entryLimit
+            ? [
+                `It may hold about ${count(estimate.entries)} files and folders, past the ${count(estimate.entryLimit)} the public-safety scan reads in a run of ${plural(estimate.basis.participants, "participant")}.`,
+            ]
+            : []),
+    ];
+    if (passed.length === 0)
+        return undefined;
+    const { scheduled, longestWindowMs, open, openMs, dwell } = estimate.basis;
+    const counted = [
+        ...(scheduled > 0
+            ? [
+                `${plural(scheduled, "participant")} working their declared windows of up to ${formatDuration(longestWindowMs)}`,
+            ]
+            : []),
+        ...(open > 0
+            ? [
+                `${scheduled > 0 ? open : plural(open, "participant")} for up to ${formatDuration(openMs)} each`,
+            ]
+            : []),
+    ];
+    const changes = [
+        ...(scheduled > 0 ? ["shorten the longest windows (participants[].endAfterMs)"] : []),
+        ...(dwell ? ["shorten the dwell window (dwell.ms) or capture less often (dwell.everyMs)"] : []),
+    ];
+    const split = "split the participants across studies";
+    const advice = changes.length === 0 ? split : `${changes.join(", ")}, or ${split}`;
+    const perMinute = (RATES.turnBytes * 60) / RATES.secondsPerTurn;
+    return [
+        ...passed,
+        `The estimate counts ${counted.join(" and ")}, at a model turn every ${formatDuration(RATES.secondsPerTurn * 1000)} that adds about ${(RATES.turnBytes / 1000).toFixed(1)} KB.`,
+        `It runs high, about ${(perMinute / RATES.measuredLongRunBytesPerMinute).toFixed(1)} times the one long live run measured, so the run goes ahead.`,
+        `To stay under the limit, ${advice}.`,
+    ].join(" ");
+}
+/** The estimate beside the limits, for `study check`. */
+export function describeBundle(estimate) {
+    return `run.json about ${mib(estimate.runFileBytes)} of the ${mib(EVIDENCE_LIMITS.sourceBytes)} analysis reads; largest file about ${mib(estimate.largestFileBytes)} of the ${mib(RUN_ARTIFACT_MAX_BYTES)} verify reads; about ${count(estimate.entries)} files and folders of the ${count(estimate.entryLimit)} the public-safety scan reads; about ${mib(estimate.totalBytes, 0)} in all. Participants with a declared end are counted for their whole window and the others for up to ${formatDuration(estimate.basis.openMs)}, at a model turn every ${formatDuration(RATES.secondsPerTurn * 1000)}.`;
+}
+function mib(bytes, digits = 1) {
+    const value = bytes / MIB;
+    return `${Number.isInteger(value) ? value : value.toFixed(digits)} MiB`;
+}
+function count(value) {
+    return value.toLocaleString("en-US");
+}

package/dist/study/doctor.js

@@ -172,6 +172,10 @@ export async function studySetupChecks(args) {
             keys: [],
             checks: [...checks, { name: "live route", ok: false, message: planned.refusal.message }],
         };
+    // A plan warning, such as a bundle estimated past a limit, is a note: the run still goes ahead.
+    for (const warning of planned.planned.plan.warnings ?? [])
+        if (!resolved.warnings.includes(warning))
+            checks.push({ name: "plan", ok: true, status: "note", message: warning });
     const requirements = planned.planned.plan.requirements;
     const keys = requiredKeys(requirements, args.keyPresent);
     // This flag controls the hosted desktop SDK check as well as its API key.

package/dist/study/keys.d.ts

@@ -19,6 +19,9 @@ export declare const PARTICIPANT_ENTRY: {
     entry: true;
     host: true;
     startAfterMs: true;
+    endAfterMs: true;
+    windDownMs: true;
+    idleWaitMs: true;
     reasoningEffort: true;
     stopWhen: {
         any: {
@@ -110,6 +113,9 @@ export declare const ACTOR: {
     maxOutputTokens: true;
     maxWaitMs: true;
     idleWaitMs: true;
+    clock: {
+        timeZone: true;
+    };
     localAgent: true;
     reasoningEffort: true;
     stopWhen: {

package/dist/study/keys.js

@@ -40,6 +40,9 @@ export const PARTICIPANT_ENTRY = {
     entry: true,
     host: true,
     startAfterMs: true,
+    endAfterMs: true,
+    windDownMs: true,
+    idleWaitMs: true,
     reasoningEffort: true,
     stopWhen: STOP_WHEN,
     dwell: DWELL,
@@ -97,6 +100,7 @@ export const ACTOR = {
     maxOutputTokens: true,
     maxWaitMs: true,
     idleWaitMs: true,
+    clock: { timeZone: true },
     localAgent: true,
     reasoningEffort: true,
     stopWhen: STOP_WHEN,

package/dist/study/migrate/v2.js

@@ -92,12 +92,15 @@ const V2_KEYS = {
     actors: {
         type: true,
         count: true,
-        // startAfterMs arrived after v2, so a v2 participant cannot carry it.
-        lanes: without(PARTICIPANT_ENTRY, "startAfterMs"),
+        // The participant's window and idle wait arrived after v2, so a v2 participant cannot carry them.
+        lanes: without(PARTICIPANT_ENTRY, "startAfterMs", "endAfterMs", "windDownMs", "idleWaitMs"),
         // Roster groups are participants with a count; the parser expanded them into `lanes[]`.
-        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"),
+        roster: {
+            ...without(PARTICIPANT_ENTRY, "startAfterMs", "endAfterMs", "windDownMs", "idleWaitMs"),
+            count: true,
+        },
+        // maxWaitMs, idleWaitMs and clock arrived after v2, so a v2 file cannot carry them.
+        ...without(ACTOR, "type", "maxWaitMs", "idleWaitMs", "clock"),
         laneFocus: { id: true, label: true, instruction: true },
     },
     execution: withAfter(EXECUTION, "egressAllow", { caps: CAPS }),

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?, startAfterMs?, reasoningEffort?, stopWhen?, dwell? }`.
+ * instruction?, target?, entry?, host?, startAfterMs?, endAfterMs?, windDownMs?, idleWaitMs?, 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,7 +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";
+import { isStartAfterMs, startAfterMessage, windowReason } 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_.-]*$/;
@@ -63,6 +63,12 @@ export function parseActorFields(entry, path) {
         actor.maxWaitMs = entry.maxWaitMs;
     if (typeof entry.idleWaitMs === "number")
         actor.idleWaitMs = entry.idleWaitMs;
+    if (entry.clock !== undefined) {
+        const timeZone = isRecord(entry.clock) ? entry.clock.timeZone : undefined;
+        if (typeof timeZone !== "string" || !isTimeZone(timeZone))
+            return invalid(`${path}.clock must be { timeZone }, with timeZone a time zone name such as "Europe/London": the participant's local time, which each turn tells it.`);
+        actor.clock = { timeZone };
+    }
     const localAgent = str(entry.localAgent);
     if (entry.localAgent !== undefined) {
         if (localAgent !== "codex" && localAgent !== "claude") {
@@ -97,7 +103,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?, startAfterMs?, reasoningEffort?, stopWhen?, dwell? }`.
+ * instruction?, target?, entry?, host?, startAfterMs?, endAfterMs?, windDownMs?, idleWaitMs?, 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
@@ -108,13 +114,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?, startAfterMs?, 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?, endAfterMs?, windDownMs?, idleWaitMs?, 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?, startAfterMs?, reasoningEffort?, stopWhen?, dwell? }).`);
+            return invalid(`${paths.entry(entryIndex)} must be an object ({ id?, actorType?, surface?, caseGroup?, persona?, device?, instruction?, target?, entry?, host?, startAfterMs?, endAfterMs?, windDownMs?, idleWaitMs?, reasoningEffort?, stopWhen?, dwell? }).`);
         }
         const parsedEntry = {};
         const id = str(entry.id);
@@ -205,6 +211,19 @@ export function parseParticipantEntries(raw, paths) {
                 return invalid(startAfterMessage(`${paths.entry(entryIndex)}.startAfterMs`));
             parsedEntry.startAfterMs = entry.startAfterMs;
         }
+        const window = windowReason({ ...parsedEntry, endAfterMs: entry.endAfterMs, windDownMs: entry.windDownMs }, paths.entry(entryIndex));
+        if (window !== undefined)
+            return invalid(window);
+        if (typeof entry.endAfterMs === "number")
+            parsedEntry.endAfterMs = entry.endAfterMs;
+        if (typeof entry.windDownMs === "number")
+            parsedEntry.windDownMs = entry.windDownMs;
+        // Checked against actor.maxWaitMs once the actor is read (waitLimitValidationReason).
+        const idleWait = waitFieldsReason({ idleWaitMs: entry.idleWaitMs }, `${paths.entry(entryIndex)}.`);
+        if (idleWait)
+            return invalid(idleWait);
+        if (typeof entry.idleWaitMs === "number")
+            parsedEntry.idleWaitMs = entry.idleWaitMs;
         entries.push(parsedEntry);
     }
     return { ok: true, value: entries };
@@ -376,3 +395,13 @@ function parseEntryMetadata(raw, field) {
     }
     return { ok: true, value };
 }
+/** Whether Intl knows `name` as a time zone. */
+function isTimeZone(name) {
+    try {
+        new Intl.DateTimeFormat("en-GB", { timeZone: name });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

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

@@ -38,11 +38,20 @@ interface DesktopParticipant extends Participant {
         readonly maxOutputTokens?: number;
         /** actor.maxWaitMs: the longest one wait action lasts. */
         readonly maxWaitMs?: number;
-        /** actor.idleWaitMs: how long a wait with no duration lasts while the participant only waits. */
+        /**
+         * The participant's idleWaitMs, else actor.idleWaitMs: how long a wait with no duration lasts
+         * while the participant only waits.
+         */
         readonly idleWaitMs?: number;
+        /** actor.clock.timeZone: the participant's local time zone, which each turn tells it the time in. */
+        readonly timeZone?: string;
     };
     /** When it starts, in ms after the run starts its participants; absent, with the run. */
     readonly startAfterMs?: number;
+    /** Computer use: when it ends, on the same clock; absent, it runs for the study's session budget. */
+    readonly endAfterMs?: number;
+    /** With endAfterMs: how long before the end each turn tells it the time left (default applied). */
+    readonly windDownMs?: number;
 }
 /** Only independent computer-use participants consume a task protocol and their own target. */
 export interface ComputerUseParticipant extends DesktopParticipant {

package/dist/study/plan-participants.js

@@ -1,5 +1,6 @@
 // Who takes part in a study: one record per participant, built from the declared roster or a count.
 // Computer-use and shared-world participants share the desktop fields; each kind adds its own.
+import { DEFAULT_WIND_DOWN_MS } from "./arrivals.js";
 import { resolveParticipantDevice } from "./device-presets.js";
 import { computerUseParticipantCount, isSharedWorldComposition, participantIdAt, } from "./routing.js";
 import { participantList, declaredParticipantCount, participantInstruction, } from "./study-fields.js";
@@ -13,7 +14,8 @@ function desktopParticipant(config, entry, index, kind, focus) {
     const reasoningEffort = entry?.reasoningEffort ?? actor?.reasoningEffort;
     const maxOutputTokens = actor?.maxOutputTokens;
     const maxWaitMs = actor?.maxWaitMs;
-    const idleWaitMs = actor?.idleWaitMs;
+    const idleWaitMs = entry?.idleWaitMs ?? actor?.idleWaitMs;
+    const timeZone = actor?.clock?.timeZone;
     return {
         id: participantIdAt(index, entry?.id, kind),
         index,
@@ -35,8 +37,15 @@ function desktopParticipant(config, entry, index, kind, focus) {
             ...(maxOutputTokens === undefined ? {} : { maxOutputTokens }),
             ...(maxWaitMs === undefined ? {} : { maxWaitMs }),
             ...(idleWaitMs === undefined ? {} : { idleWaitMs }),
+            ...(timeZone === undefined ? {} : { timeZone }),
         },
         ...(entry?.startAfterMs === undefined ? {} : { startAfterMs: entry.startAfterMs }),
+        ...(entry?.endAfterMs === undefined
+            ? {}
+            : {
+                endAfterMs: entry.endAfterMs,
+                windDownMs: entry.windDownMs ?? DEFAULT_WIND_DOWN_MS,
+            }),
     };
 }
 /**

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

@@ -6,6 +6,7 @@ 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 { BundleEstimate } from "./bundle-estimate.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";
@@ -275,6 +276,8 @@ export interface ScriptedPlan extends PlanBase {
 export type StudyPlan = PreviewPlan | ComputerUsePlan | SharedWorldPlan | TerminalPlan | ScriptedPlan;
 interface PlannedStudy {
     readonly plan: StudyPlan;
+    /** A computer-use plan's estimated bundle, which planStudy checked against the bundle limits. */
+    readonly bundle?: BundleEstimate;
 }
 /**
  * The error a route returns before a run starts: the route, its error code and a message. Each

package/dist/study/plan.js

@@ -9,6 +9,7 @@ import { planTerminalStudy } from "../routes/terminal/plan.js";
 import { concurrentSandboxes, sandboxCeiling, } from "../substrates/e2b/lifetime.js";
 import { localBrowserDefaults } from "../substrates/local/runtime-config.js";
 import { THIS_REPO_DRY_RUN_ONLY } from "./composition-rules.js";
+import { bundleLimitReason, estimateBundle } from "./bundle-estimate.js";
 import { planBase } from "./plan-base.js";
 import { routeOf } from "./routing.js";
 import { automaticAnalysisRouteReason, taskProtocolValidationReason } from "./validation.js";
@@ -81,15 +82,34 @@ export function planStudy(config, options, deps = {}) {
     const result = planRoute(routeOf(config), study, options, input, deps, e2b);
     if (!result.ok)
         return result;
+    const bundle = plannedBundle(result.plan);
     // The manifest the CLI resolved enters the plan here and nowhere else; the routes read
     // plan.study for the run's status record and bundle, and plan.warnings for its bundle events.
-    const warnings = [...recordedStudyWarnings(study), ...(result.plan.warnings ?? [])];
+    const warnings = [
+        ...recordedStudyWarnings(study),
+        ...(result.plan.warnings ?? []),
+        ...(bundle.warning === undefined ? [] : [bundle.warning]),
+    ];
     const plan = {
         ...result.plan,
         ...(options.study === undefined ? {} : { study: options.study }),
         ...(warnings.length === 0 ? {} : { warnings }),
     };
-    return { ok: true, planned: { plan } };
+    return {
+        ok: true,
+        planned: { plan, ...(bundle.estimate === undefined ? {} : { bundle: bundle.estimate }) },
+    };
+}
+/**
+ * The bundle a computer-use plan's participants leave, each session at the plan's budget, and the
+ * warning for a live plan whose estimate passes a bundle limit. A dry run records no turns.
+ */
+function plannedBundle(plan) {
+    if (plan.route !== "computer-use")
+        return {};
+    const estimate = estimateBundle(plan.runner.participants, plan.sessionBudgetMs);
+    const warning = plan.dryRun ? undefined : bundleLimitReason(estimate);
+    return warning === undefined ? { estimate } : { estimate, warning };
 }
 function planRoute(route, study, options, input, deps, e2b) {
     const { sandboxCeiling } = e2b;

package/dist/study/preflight.js

@@ -6,7 +6,8 @@ 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 { describeArrivals, describeWindows } from "./arrivals.js";
+import { describeBundle } from "./bundle-estimate.js";
 import { resolveStudyManifest } from "./discover.js";
 import { participantList } from "./study-fields.js";
 import { isLocalBrowserStudy } from "../substrates/local/runtime-config.js";
@@ -78,6 +79,16 @@ export async function runStudyPreflight(options) {
     const schedule = scheduleCheck(planned.planned.plan);
     if (schedule !== undefined)
         ctx.checks.push(schedule);
+    const windows = windowsCheck(planned.planned.plan);
+    if (windows !== undefined)
+        ctx.checks.push(windows);
+    const bundle = planned.planned.bundle;
+    if (bundle !== undefined)
+        ctx.checks.push({ name: "bundle size", ok: true, message: describeBundle(bundle) });
+    // The plan's warnings, which the run records; the study file's own are already listed.
+    for (const warning of planned.planned.plan.warnings ?? [])
+        if (!ctx.warnings.includes(warning))
+            ctx.warnings.push(warning);
     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))
@@ -130,6 +141,13 @@ function scheduleCheck(plan) {
         return undefined;
     return { name: "schedule", ok: true, message: describeArrivals(plan.arrivals) };
 }
+/** Each participant's window, for a computer-use study in which a participant declares an end. */
+function windowsCheck(plan) {
+    if (plan.route !== "computer-use")
+        return undefined;
+    const message = describeWindows(plan.runner.participants, plan.sessionBudgetMs);
+    return message === undefined ? undefined : { name: "windows", ok: true, message };
+}
 /** 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/types.d.ts

@@ -325,6 +325,24 @@ export interface StudyParticipantEntry {
      * Absent, the participant starts with the run. src/study/arrivals.ts schedules the start.
      */
     startAfterMs?: number;
+    /**
+     * Computer use: when this participant's session ends, in milliseconds after the run starts its
+     * participants, on the same clock as startAfterMs and after it. At the end the participant is
+     * asked for its closing report and the session ends as passed, with stop cause `scheduled_end`.
+     * Its session lasts the window plus 5 minutes in place of execution.timeoutMs, and its sandbox
+     * is sized from that.
+     */
+    endAfterMs?: number;
+    /**
+     * With endAfterMs: how long before the end each turn tells the participant the end time and the
+     * minutes left. Default 600000 (10 minutes).
+     */
+    windDownMs?: number;
+    /**
+     * Computer use and shared world: this participant's actor.idleWaitMs, how long a wait that names
+     * no duration lasts while it only waits. Same range, and no longer than actor.maxWaitMs.
+     */
+    idleWaitMs?: number;
 }
 export interface StudyActor {
     /**
@@ -369,6 +387,14 @@ export interface StudyActor {
      * 500 ms. OpenAI's computer-use `wait` never names a duration.
      */
     idleWaitMs?: number;
+    /**
+     * Computer use: the participant's clock. `timeZone`, a time zone name such as "Europe/London", adds
+     * the local time to each turn, for missions that refer to appointment times, and gives a
+     * scheduled end (participants[].endAfterMs) in that zone. A hosted desktop shows no clock.
+     */
+    clock?: {
+        timeZone: string;
+    };
     /**
      * `local-agent` only: which locally signed-in coding agent is the brain. Absent = codex.
      *

package/dist/study/validation.d.ts

@@ -37,8 +37,9 @@ export declare function cloneTargetValidationReason(config: StudyConfig): string
 /** Refuse a claimed output bound when the route cannot pass it to the first-party provider. */
 export declare function outputTokenLimitValidationReason(config: StudyConfig): string | null;
 /**
- * Refuse a wait field out of range, or an idle wait longer than the longest wait. On a route whose
- * participants take no wait actions the fields are inert (warnings.ts).
+ * Refuse a wait field out of range, or an idle wait longer than the longest wait: the actor's, and
+ * each participant's own idleWaitMs under actor.maxWaitMs. On a route whose participants take no
+ * wait actions the fields are inert (warnings.ts).
  */
 export declare function waitLimitValidationReason(config: StudyConfig): string | null;
 /**

package/dist/study/validation.js

@@ -6,7 +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";
+import { isStartAfterMs, rosterStartsReason, startAfterMessage, windowReason } 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
@@ -82,6 +82,9 @@ function rosterStructuralValidationReason(config) {
             if (entry.startAfterMs !== undefined && !isStartAfterMs(entry.startAfterMs)) {
                 return startAfterMessage(`participants[${index}].startAfterMs`);
             }
+            const window = windowReason(entry, `participants[${index}]`);
+            if (window !== undefined)
+                return window;
             const id = entry.id;
             if (id === undefined) {
                 continue;
@@ -107,6 +110,10 @@ function rosterStructuralValidationReason(config) {
  * runStudyWith takes a config that skipped the parser.
  */
 export function sharedWorldValidationReason(config) {
+    // The subject sandbox's deadline assumes every participant runs for execution.timeoutMs.
+    const ending = participantList(config)?.findIndex((entry) => entry?.endAfterMs !== undefined);
+    if (ending !== undefined && ending >= 0)
+        return `participants[${ending}].endAfterMs ends a participant at a set time on route: computer-use only. A shared-world participant runs for execution.timeoutMs; remove endAfterMs and windDownMs.`;
     return config.subject.source === "app-url"
         ? externalPublicSharedWorldValidationReason(config)
         : concurrentSharedWorldValidationReason(config);
@@ -250,11 +257,22 @@ export function outputTokenLimitValidationReason(config) {
     return null;
 }
 /**
- * Refuse a wait field out of range, or an idle wait longer than the longest wait. On a route whose
- * participants take no wait actions the fields are inert (warnings.ts).
+ * Refuse a wait field out of range, or an idle wait longer than the longest wait: the actor's, and
+ * each participant's own idleWaitMs under actor.maxWaitMs. On a route whose participants take no
+ * wait actions the fields are inert (warnings.ts).
  */
 export function waitLimitValidationReason(config) {
-    return config.actor === undefined ? null : waitFieldsReason(config.actor, "actor.");
+    const actorReason = config.actor === undefined ? null : waitFieldsReason(config.actor, "actor.");
+    if (actorReason !== null)
+        return actorReason;
+    for (const [index, entry] of (participantList(config) ?? []).entries()) {
+        if (entry?.idleWaitMs === undefined)
+            continue;
+        const reason = waitFieldsReason({ idleWaitMs: entry.idleWaitMs, maxWaitMs: config.actor?.maxWaitMs }, `participants[${index}].`, "actor.");
+        if (reason !== null)
+            return reason;
+    }
+    return null;
 }
 /**
  * Shared-world participants share one live app, so at least two must be live at once. The