humanish 0.120.1 → 0.122.0

package/dist/run/status.d.ts

@@ -2,6 +2,7 @@ import type { RunBundle } from "./bundle.js";
 import { type RunStudyProvenance } from "./study-provenance.js";
 import { type PreparedOutputRoot } from "./contained-output.js";
 import type { ExecutionOutcome } from "./judge.js";
+import { type HostClock, type HostSuspension } from "./host-suspension.js";
 export declare const RUN_STATUS_SCHEMA = "humanish.run-status.v1";
 /** The file, relative to the run directory. */
 export declare const RUN_STATUS_FILE = "status.json";
@@ -87,17 +88,22 @@ export interface RunStatusHandle {
     interrupt(signal: RunInterruptSignal): Promise<boolean>;
     /** True from the moment `interrupt` accepts a signal, before its write lands. */
     readonly interrupted: boolean;
+    /** The host suspensions the cadence saw until now, or until it stopped. */
+    suspensions(): readonly HostSuspension[];
 }
 export interface BeginRunStatusOptions {
     runId: string;
     mode: "dry-run" | "live";
     study?: RunStudyProvenance | undefined;
     sandboxes?: "none" | undefined;
+    /** The clock its timestamps and cadence read. Defaults to systemHostClock. */
+    clock?: HostClock | undefined;
 }
 /**
  * Start a run's status record and keep it fresh. Fire-and-forget by design: a status write that
- * fails must never fail the run it describes, so every write swallows its error. The interval is
- * `unref`'d, so this file can never be the reason a process stays alive.
+ * fails must never fail the run it describes, so every write swallows its error. The cadence is
+ * the run's heartbeat, which also records each host suspension, and its timer never keeps the
+ * process alive.
  */
 export declare function beginRunStatus(runPaths: PreparedOutputRoot, options: BeginRunStatusOptions): RunStatusHandle;
 /** The three ways a run reads from disk. `interrupted` is a record its stopped process wrote, or a

package/dist/run/status.js

@@ -12,6 +12,7 @@
 // operator may share the run directory, so a share-safety gate must have nothing to strip here.
 import { isProvenanceField, studyFields } from "./study-provenance.js";
 import { writeContainedOutputFile } from "./contained-output.js";
+import { startHeartbeat, systemHostClock, } from "./host-suspension.js";
 export const RUN_STATUS_SCHEMA = "humanish.run-status.v1";
 /** The file, relative to the run directory. */
 export const RUN_STATUS_FILE = "status.json";
@@ -52,11 +53,13 @@ export function runStatusOutcome(bundle) {
 }
 /**
  * Start a run's status record and keep it fresh. Fire-and-forget by design: a status write that
- * fails must never fail the run it describes, so every write swallows its error. The interval is
- * `unref`'d, so this file can never be the reason a process stays alive.
+ * fails must never fail the run it describes, so every write swallows its error. The cadence is
+ * the run's heartbeat, which also records each host suspension, and its timer never keeps the
+ * process alive.
  */
 export function beginRunStatus(runPaths, options) {
-    const iso = () => new Date().toISOString();
+    const clock = options.clock ?? systemHostClock;
+    const iso = () => new Date(clock.now()).toISOString();
     const startedAt = iso();
     const base = {
         schema: RUN_STATUS_SCHEMA,
@@ -84,19 +87,18 @@ export function beginRunStatus(runPaths, options) {
         return writing;
     };
     const started = write(base);
-    const timer = setInterval(() => {
+    const heartbeat = startHeartbeat(clock, RUN_STATUS_TOUCH_MS, () => {
         if (finished)
             return;
         void write({ ...base, updatedAt: iso() });
-    }, RUN_STATUS_TOUCH_MS);
-    timer.unref?.();
+    });
     const handle = {
         started,
         async finish(outcome) {
             if (finished)
                 return;
             finished = true;
-            clearInterval(timer);
+            heartbeat.stop();
             const completedAt = iso();
             finishedRecord = {
                 ...base,
@@ -122,7 +124,7 @@ export function beginRunStatus(runPaths, options) {
             }
             finished = true;
             interrupted = true;
-            clearInterval(timer);
+            heartbeat.stop();
             const completedAt = iso();
             await write({ ...base, state: "interrupted", updatedAt: completedAt, completedAt, signal });
             return true;
@@ -130,6 +132,7 @@ export function beginRunStatus(runPaths, options) {
         get interrupted() {
             return interrupted;
         },
+        suspensions: () => heartbeat.suspensions(),
     };
     return handle;
 }

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[];
 };

package/dist/study/arrivals.js

@@ -1,6 +1,8 @@
-// When each participant of a computer-use or shared-world run starts. A study may give each
-// participant an offset from the moment the run starts its participants
-// (`participants[].startAfterMs`). The plan simulates the start queue to report the schedule and
+// When each participant of a computer-use or shared-world run starts, and on computer use when it
+// ends. A study may give each participant an offset from the moment the run starts its participants
+// (`participants[].startAfterMs`) and, on computer use, an end on the same clock
+// (`participants[].endAfterMs`), with a wind-down before it in which each turn tells the
+// participant the time left (`windDownMs`). The plan simulates the start queue to report the schedule and
 // when the last session ends at the latest; the routes start their participants through
 // runOnSchedule, which waits for each one's time and then for a free slot. A participant's desktop
 // is created when it starts, so a late start holds no sandbox before then.
@@ -20,6 +22,92 @@ export function isStartAfterMs(value) {
         value >= 0 &&
         value <= LATEST_START_AFTER_MS);
 }
+/** How long before its end a participant is told the time left, unless it declares `windDownMs`. */
+export const DEFAULT_WIND_DOWN_MS = 10 * 60_000;
+/**
+ * Room a scheduled participant's session keeps past its end for the turn in flight and the closing
+ * report. The loop ends the session at the end; this keeps the session's own time limit, and the
+ * sandbox sized from it, from cutting the closing report short.
+ */
+const SCHEDULED_END_ROOM_MS = 5 * 60_000;
+/**
+ * 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 function windowReason(entry, path) {
+    const { endAfterMs, windDownMs } = entry;
+    if (windDownMs !== undefined && endAfterMs === undefined)
+        return `${path}.windDownMs is how long before its endAfterMs a participant is told the time left, so it needs ${path}.endAfterMs. Add the end, or remove windDownMs.`;
+    if (windDownMs !== undefined && !isStartAfterMs(windDownMs))
+        return `${path}.windDownMs must be a whole number of milliseconds from 0 to ${LATEST_START_AFTER_MS} (24 hours): how long before its end the participant is told the time left.`;
+    if (endAfterMs === undefined)
+        return undefined;
+    if (!isStartAfterMs(endAfterMs))
+        return `${path}.endAfterMs must be a whole number of milliseconds up to ${LATEST_START_AFTER_MS} (24 hours): when the participant's session ends, after the run starts its participants.`;
+    const startAfterMs = entry.startAfterMs ?? 0;
+    if (endAfterMs <= startAfterMs) {
+        const who = entry.id === undefined ? "" : ` ("${entry.id}")`;
+        return `${path}.endAfterMs${who} is ${endAfterMs} ms and its startAfterMs is ${startAfterMs} ms, so it would end before it starts. Set endAfterMs after startAfterMs.`;
+    }
+    return 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 function participantSessionMs(participant, sessionMs) {
+    if (participant.endAfterMs === undefined)
+        return sessionMs;
+    return participant.endAfterMs - (participant.startAfterMs ?? 0) + SCHEDULED_END_ROOM_MS;
+}
+/**
+ * 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 function scheduledEndAt(participant, scheduledAt) {
+    if (participant.endAfterMs === undefined)
+        return undefined;
+    return {
+        atMs: scheduledAt - (participant.startAfterMs ?? 0) + participant.endAfterMs,
+        windDownMs: participant.windDownMs ?? DEFAULT_WIND_DOWN_MS,
+    };
+}
+/**
+ * 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 function windowDeadlineRefusal(participants, sandbox, ceilingMs) {
+    const inMinutes = (ms) => Math.round(ms / 60_000);
+    for (const participant of participants) {
+        if (participant.endAfterMs === undefined)
+            continue;
+        const deadlineMs = participantSessionMs(participant, sandbox.sessionMs) + sandbox.headroomMs;
+        if (deadlineMs <= ceilingMs)
+            continue;
+        const name = participant.id === undefined ? "A participant" : `Participant "${participant.id}"`;
+        return `${name} works from +${formatDuration(participant.startAfterMs ?? 0)} to +${formatDuration(participant.endAfterMs)}, so its sandbox needs a ${inMinutes(deadlineMs)}m deadline: the window, ${inMinutes(SCHEDULED_END_ROOM_MS)}m for its closing report and ${inMinutes(sandbox.headroomMs)}m to set up and tear down. A sandbox may not live longer than ${ceilingMs / 60_000}m. Shorten its window.${ceilingAdvice(deadlineMs)}`;
+    }
+    return 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 function describeWindows(participants, sessionMs) {
+    if (!participants.some((participant) => participant.endAfterMs !== undefined))
+        return undefined;
+    const windows = participants.map((participant) => {
+        const start = `${participant.id ?? "participant"} from +${formatDuration(participant.startAfterMs ?? 0)}`;
+        if (participant.endAfterMs === undefined)
+            return `${start} for up to ${formatDuration(sessionMs)}`;
+        const told = Math.max(participant.startAfterMs ?? 0, participant.endAfterMs - (participant.windDownMs ?? DEFAULT_WIND_DOWN_MS));
+        return `${start} to +${formatDuration(participant.endAfterMs)}, told the time left from +${formatDuration(told)}`;
+    });
+    return `${windows.join("; ")}.`;
+}
 /** The refusal of a start offset that is not one, naming its `field`. */
 export function startAfterMessage(field) {
     return `${field} must be a whole number of milliseconds from 0 to ${LATEST_START_AFTER_MS} (24 hours): how long after the run starts its participants this one starts.`;
@@ -41,11 +129,13 @@ export function rosterStartsReason(roster) {
  * 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 function planArrivals(offsets, queue) {
+export function planArrivals(offsets, queue, sessionsMs = []) {
     const due = offsets.map((offset) => offset ?? 0);
-    const starts = queueStarts(due, queue);
+    const session = (index) => sessionsMs[index] ?? queue.sessionMs;
+    const starts = queueStarts(due, queue, session);
     let waiting = 0;
     let longestWaitMs = 0;
     for (const [index, start] of starts.entries()) {
@@ -58,10 +148,10 @@ export function planArrivals(offsets, queue) {
         declared: offsets.some((offset) => offset !== undefined),
         firstStartMs: Math.min(...due),
         lastStartMs: Math.max(...due),
-        peak: mostAtOnce(starts, queue.sessionMs),
+        peak: mostAtOnce(starts, session),
         waiting,
         longestWaitMs,
-        lastEndMs: Math.max(...starts) + queue.sessionMs,
+        lastEndMs: Math.max(...starts.map((start, index) => start + session(index))),
         sessionMs: queue.sessionMs,
     };
 }
@@ -83,7 +173,7 @@ export function describeArrivals(arrivals) {
  * roster in waves.
  */
 export function planStarts(participants, queue, lowered) {
-    const arrivals = planArrivals(participants.map((participant) => participant.startAfterMs), queue);
+    const arrivals = planArrivals(participants.map((participant) => participant.startAfterMs), queue, participants.map((participant) => participantSessionMs(participant, queue.sessionMs)));
     return { arrivals, warnings: startQueueWarnings(arrivals, queue, lowered) };
 }
 // A roster that starts together keeps `lowered`. A declared schedule spreads its participants
@@ -126,8 +216,8 @@ export function servedScheduleRefusal(arrivals, sandbox, ceilingMs) {
 function scheduleOrder(due) {
     return due.map((_, index) => index).sort((a, b) => due[a] - due[b] || a - b);
 }
-/** Each participant's start in roster order, when every session holds its slot for `sessionMs`. */
-function queueStarts(due, queue) {
+/** Each participant's start in roster order, when each session holds its slot for `session(index)`. */
+function queueStarts(due, queue, session) {
     const starts = [...due];
     const queued = scheduleOrder(due).filter((index) => index !== queue.ownSlot);
     const pooled = queue.ownSlot === undefined ? queue.slots : queue.slots - 1;
@@ -137,16 +227,16 @@ function queueStarts(due, queue) {
         const slot = free.indexOf(Math.min(...free));
         const start = Math.max(due[index], free[slot]);
         starts[index] = start;
-        free[slot] = start + queue.sessionMs;
+        free[slot] = start + session(index);
     }
     return starts;
 }
-function mostAtOnce(starts, sessionMs) {
+function mostAtOnce(starts, session) {
     // An end sorts before a start at the same instant: that slot is free again.
     const changes = starts
-        .flatMap((start) => [
+        .flatMap((start, index) => [
         { at: start, by: 1 },
-        { at: start + sessionMs, by: -1 },
+        { at: start + session(index), by: -1 },
     ])
         .sort((a, b) => a.at - b.at || a.by - b.by);
     let live = 0;

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

@@ -6,7 +6,7 @@ import {} from "./types.js";
 import { runPublicPreviewPreflight, runSandboxLoopbackPreflight } from "./preflight-probes.js";
 import { digest, fail, finalize, STUDY_CHECK_SCHEMA } from "./preflight-result.js";
 import { planStudy, routeOf } from "./plan.js";
-import { describeArrivals } from "./arrivals.js";
+import { describeArrivals, describeWindows } from "./arrivals.js";
 import { resolveStudyManifest } from "./discover.js";
 import { participantList } from "./study-fields.js";
 import { isLocalBrowserStudy } from "../substrates/local/runtime-config.js";
@@ -78,6 +78,9 @@ 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 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 +133,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/study-deps.d.ts

@@ -4,6 +4,7 @@ import type { CuaActorSessionOptions } from "../actors/computer-use/actor.js";
 import type { AutomaticAnalysisDeps, runAutomaticAnalysis } from "../analysis/automatic.js";
 import type { CuaLoopResult } from "../actors/computer-use/loop.js";
 import type { renderObserver } from "../observer/render.js";
+import type { HostClock } from "../run/host-suspension.js";
 import type { TerminalCostProbe } from "../routes/terminal/types.js";
 import type { DetachedTimers } from "../substrates/detached.js";
 import type { E2BDesktopModule } from "../substrates/e2b/sdk.js";
@@ -17,6 +18,11 @@ export interface StudyDeps {
     readonly renderObserver?: typeof renderObserver;
     /** The clock, in epoch milliseconds. Defaults to Date.now. */
     readonly now?: () => number;
+    /**
+     * Every recorded route: the run's wall clock and heartbeat timer, which time the run and notice
+     * a host suspension. Defaults to systemHostClock.
+     */
+    readonly hostClock?: HostClock;
     /** Clock and sleep for detached provisioning steps. */
     readonly detachedTimers?: DetachedTimers;
     /**

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