humanish 0.121.0 → 0.122.0

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/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

package/docs/contracts/run-bundle.md

@@ -183,7 +183,7 @@ whose message names its start, end, length and offset into the run (`src/run/hos
 
 On a computer-use run, a participant that failed in the harness or at its session time limit, and
 was in flight across a suspension, likely failed because of it. So did a participant skipped after
-such a failure (the pipeline gate, fail-fast). When any did, the outcome's first failure has
+such a failure (the pipeline gate). When any did, the outcome's first failure has
 `kind: run` and one sentence, such as "The host was suspended for 6m 5s at +1m; the 34
 participant failures after it are likely its effect.", ahead of each participant's own failure.
 `review.summary` starts with the same sentence, the attributed participants share one gap line,
@@ -197,7 +197,7 @@ An actor trace may include `stopCause` alongside its unchanged `status`,
 `completionReason` and verbatim `reason`. Computer-use sessions distinguish
 `provider_output_limit`, `provider_token_limit`, `time_limit`, `spend_limit`,
 `study_spend_limit`, `adapter_limit`, `provider_incomplete`, `provider_status`,
-`provider_refused_prompt`, `harness_aborted`, and `usage_unreported`. Absence means the route or
+`provider_refused_prompt`, `harness_aborted`, `usage_unreported`, and `scheduled_end`. Absence means the route or
 recording did not retain this precise field; it does not mean the participant
 finished.
 

package/docs/contracts/schemas.md

@@ -227,6 +227,25 @@ The rest of this section names keys by their v3 spelling:
   and the most participants at once with every session at its full budget, and the provisioned
   shared world's subject sandbox serves until the last session can end, which the plan checks
   against the sandbox ceiling. A rerun starts its selected participants together;
+- `participants[].endAfterMs` and `windDownMs` (computer-use only): when the participant's
+  session ends, in whole milliseconds on the `startAfterMs` clock and after its start, and how
+  long before that each turn tells it the end time and the minutes left (default 600,000).
+  Refused: an end at or before the start, a `windDownMs` without `endAfterMs`, an end on
+  `shared-world`, and a window whose sandbox deadline passes the sandbox ceiling. The
+  participant's session budget is its window plus 5 minutes (`participantSessionMs` in
+  `src/study/arrivals.ts`) in place of `execution.timeoutMs`, and its sandbox deadline adds the
+  route's headroom to that. At the end the loop requests the closing report (`debrief.trigger:
+  scheduled_end`) and the session ends `goal_satisfied` with `stopCause: scheduled_end`. Before
+  the end, a turn that requests no action does not end the session: the trace records a
+  `participant ended before its scheduled end` notice, the next request says the time left, and
+  the turn counts toward the idle backstop. Before the end, a turn that only waits or takes
+  screenshots counts toward neither backstop streak (`advanceBackstop`'s `waitingIsTheTask`). The
+  plan entry carries `endAfterMs`, and `study check` prints a `windows` row;
+- `participants[].idleWaitMs` (computer-use and shared-world, also on `count:` groups): this
+  participant's `actor.idleWaitMs`, in the same range and refused above an explicit
+  `actor.maxWaitMs` (`waitLimitValidationReason`). Its trace records it in `waitSettings`;
+- `actor.clock.timeZone` (computer-use): a tz database time zone name, such as `Europe/London`. Each turn's context hint carries
+  the local time in it, and a scheduled end is given in it (UTC without it);
 - `execution.concurrency` (computer-use E2B routes, including shared-world): a
   cap on participants in flight at once. When omitted, every participant runs
   simultaneously: both routes resolve it when they plan, from the final participant count
@@ -460,9 +479,9 @@ length 1 at N=1; per-participant status/session/sandbox/subject), and `laneSumma
 mirror the first participant and `subject.commit` is unanimity-gated across participants
 (omitted with a divergence warning when participants resolve different commits). At N=1
 the run bundle is byte-stable with the pre-fan-out output; only the result
-projection changed. A fan-out run records a `cua-lab.fanout.plan` bundle event
-(and a `cua-lab.fanout.fail-fast` event when a harness error in a participant's session skips
-queued participants);
+projection changed. A fan-out run records a `cua-lab.fanout.plan` bundle event, and
+each participant's outcome event (`cua-lab.session.<completionReason>`, `cua-lab.session.error`
+or `cua-lab.session.blocked`) carries its reason;
 `ok = observer.ok ∧ every participant ok ∧ no failed adapter or declared-scorer verdict`,
 where a dry-run participant is ok as synthetic and a live participant must pass
 `participantPassed` (`src/run/judge.ts`): not skipped, status `passed`, no harness
@@ -1014,7 +1033,8 @@ Core-owned fields:
   applied, in milliseconds, defaults included. `maxWaitMs` is the longest one
   wait action lasts (`actor.maxWaitMs`); a longer wait is shortened to it.
   `idleWaitMs` is how long a wait that names no duration lasts in a turn that
-  only waits or takes screenshots (`actor.idleWaitMs`), and `settleWaitMs` how
+  only waits or takes screenshots (`participants[].idleWaitMs`, else
+  `actor.idleWaitMs`), and `settleWaitMs` how
   long such a wait lasts after an action in the same turn. Each `ui_action` for
   a wait is titled with the length it lasted. Absent on other routes and on
   earlier bundles

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "humanish",
-  "version": "0.121.0",
+  "version": "0.122.0",
   "description": "Synthetic user research for apps, CLIs, and agent-facing product flows.",
   "keywords": [
     "cli",