humanish 0.121.0 → 0.123.0

package/CHANGELOG.md

@@ -8,6 +8,37 @@ The Unreleased section holds the full notes for the next version until it is tag
 
 ## Unreleased
 
+## 0.123.0: Run bundle v2 writes each trace once, bundle size estimate (2026-10-12)
+
+humanish 0.123.0 writes each participant's trace once, outside run.json, so long studies stay
+within the bundle's size limits, and estimates a study's bundle before it runs. Run bundles are now
+`humanish.run-bundle.v2`: a participant's trace items live only in its trace file
+(`actor.json`, `actors/<stream>.json` or `actor-<surface>.json`), and run.json indexes each one by
+path, size and sha256. On a synthetic 8-participant, 1,000-turn run, run.json fell from 17 MB to
+74 KB. Every reader loads traces through one loader that checks the index and refuses a missing,
+altered or shared trace; a refused trace shows as evidence unavailable, and an unfinished run
+grades `local_only`. Bundles from earlier versions still load unchanged; npm 0.122.0 and earlier
+refuse a v2 bundle by name. `study check` and `run` estimate the bundle's size and file count and
+warn before any sandbox is created when it may pass the analysis or verify limit, and the
+public-safety scan's file limit grows with the number of participants.
+
+[Release notes](https://github.com/danielgwilson/humanish/releases/tag/v0.123.0)
+
+## 0.122.0: Participants end on the clock, a harness error ends only its participant (2026-10-12)
+
+humanish 0.122.0 lets a participant end at a scheduled time and keeps one participant's harness
+error from stopping the rest of a study. `participants[].endAfterMs`, on the same clock as
+`startAfterMs`, ends a participant's session at that time with stop cause `scheduled_end`,
+counted as reaching the goal; from `endAfterMs - windDownMs` (10 minutes by default) each turn
+tells the participant the end time and the minutes left, its turns that only wait no longer count
+toward the idle limits before then, and its sandbox is sized from its own window. `actor.clock {
+timeZone }` adds the local time to each turn, and `participants[].idleWaitMs` sets one
+participant's wait length, so staff on a long shift can check the screen less often than patients.
+A participant's harness error now ends only that participant: the study-wide fail-fast is removed,
+and every later participant starts on its schedule.
+
+[Release notes](https://github.com/danielgwilson/humanish/releases/tag/v0.122.0)
+
 ## 0.121.0: One failed desktop fails alone, host sleep named as the cause (2026-10-10)
 
 humanish 0.121.0 keeps one participant's failed desktop from costing a whole hosted study, and

package/CONTEXT.md

@@ -12,7 +12,7 @@ bundle and output fields keep older spellings; the second table maps them.
 | Term                | Meaning                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Where it lives in the code                                                                                                                                                                                                                                                                                                                                                                                  |
 | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | study               | What a user designs and runs: one YAML file that declares the subject, the actor, the participants and the caps. The file lives at `humanish/studies/<id>.yaml` with schema `humanish.study.v3`, read by `humanish study` and `--study`. humanish refuses a 0.107 `humanish.lab.v2` file, and `humanish migrate` converts it (second table).                                                                                                                                                                                          | `src/study/`; `StudyConfig` in `src/study/types.ts`, parsed by `parseStudy` in `src/study/config.ts`                                                                                                                                                                                                                                                                                                        |
-| run                 | One execution of a study, on disk: `.humanish/runs/<runId>/`, with `run.json` (`humanish.run-bundle.v1`) as the source of truth.                                                                                                                                                                                                                                                                                                                                                                                                      | `src/run/`; `RunBundle` in `src/run/bundle.ts`                                                                                                                                                                                                                                                                                                                                                              |
+| run                 | One execution of a study, on disk: `.humanish/runs/<runId>/`, with `run.json` (`humanish.run-bundle.v2`) as the source of truth and each participant's trace in its own file.                                                                                                                                                                                                                                                                                                                                                         | `src/run/`; `RunBundle` in `src/run/bundle.ts`                                                                                                                                                                                                                                                                                                                                                              |
 | dry run             | A run with no live participant, from `--dry-run` or `mode: dry-run`. humanish writes a synthetic run bundle, review and Observer with no browser, model, keys or provider spend, and tests no product behavior. The `preview` route only dry-runs; "preview" names that route and nothing else.                                                                                                                                                                                                                                       | `runDryRun` in `src/run/dry-run.ts`; `resolveStudyDryRun` in `src/study/plan.ts`                                                                                                                                                                                                                                                                                                                            |
 | participant         | One simulated person, or agent, taking part in a study. The planner builds each one's record (id, persona id, assignment, labels and the route's own fields). Shared-world participants resolve the plan's records; computer-use participants rebuild the same records from the study config with `computerUseParticipants` (`src/study/plan-participants.ts`) and resolve those. `ResolvedParticipant` adds the bundle ids, persona and prompt. `run.json` records each one as a `simulations[]` entry with one or more `streams[]`. | `ResolvedParticipant` in `src/run/participant.ts`; the planned records in `src/study/plan-participants.ts`. Computer-use and shared-world participants run a `DesktopParticipantRun` (`src/routes/computer-use/types.ts`). The terminal session (`src/routes/terminal/session.ts`), scripted surfaces (`src/routes/scripted/plan.ts`) and fixture simulations (`src/run/dry-run.ts`) still build their own. |
 | persona             | Who a participant is: traits, background, device. `humanish/personas/<id>.yaml`.                                                                                                                                                                                                                                                                                                                                                                                                                                                      | `src/study/persona.ts`, `src/study/persona-resolve.ts`                                                                                                                                                                                                                                                                                                                                                      |

package/README.md

@@ -1,12 +1,23 @@
 # humanish
 
-Synthetic user research for apps, CLIs, and agent-facing product flows. AI participants with a persona and a task use your app on real desktops, and each run leaves evidence you can verify: what they did, where they got stuck, and what it cost.
+[![npm version](https://img.shields.io/npm/v/humanish)](https://www.npmjs.com/package/humanish) [![npm downloads per month](https://img.shields.io/npm/dm/humanish)](https://www.npmjs.com/package/humanish) [![CI status on main](https://img.shields.io/github/actions/workflow/status/danielgwilson/humanish/ci.yml?branch=main&label=CI)](https://github.com/danielgwilson/humanish/actions/workflows/ci.yml?query=branch%3Amain) [![License: MIT](https://img.shields.io/npm/l/humanish)](LICENSE) [![Node.js version](https://img.shields.io/node/v/humanish)](https://nodejs.org/)
 
-[![The Observer grid of a saved eight-participant study: eight desktops in one multiplayer lobby, each tile a participant's live screen](https://humanish.dev/runs/lobby-0927/poster.jpg)](https://humanish.dev/demo)
+Synthetic user research for apps, CLIs, and agent-facing product flows. AI participants with a persona and a task use your app on real desktops, and each run leaves evidence you can verify: what they did, where they got stuck, and what it cost.
 
-**[Watch a saved run](https://humanish.dev/demo).** Eight synthetic participants joined one
-lobby of a multiplayer game on its live deployment, each on its own hosted desktop. The page
-replays the real Observer; nothing runs from it.
+<a href="https://humanish.dev/demo">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://humanish.dev/runs/lobby-0927/observer-grid-dark.webp">
+    <img alt="The humanish Observer replaying a saved study five minutes into its 13-minute recording: a grid of eight participants' desktops in a multiplayer movie-guessing game, seven in the same round and one held at the join page, under tabs for 8 participants and 7 findings" src="https://humanish.dev/runs/lobby-0927/observer-grid-light.webp">
+  </picture>
+</a>
+
+**[Watch the replay](https://humanish.dev/demo).** The image is the Observer partway through a
+saved study. Eight synthetic participants joined one lobby of a multiplayer movie-guessing game
+on its live deployment, each on its own hosted desktop, and each tile shows one participant's
+screen at the same moment of the recording. Six reached the final standings. Two were blocked,
+among them Player six, who arrived after the game started and is still on the join page. The
+Findings tab holds the seven findings the analysis wrote. The demo page replays this run in the
+Observer, and nothing runs from it.
 
 ## Learn how a study works
 
@@ -19,6 +30,14 @@ disposable browser VM on your machine. On the computer-use route a model drives
 participant: every turn it reads a screenshot and answers with mouse and keyboard actions, until
 the participant finishes, gets stuck or reaches a limit.
 
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://humanish.dev/runs/lobby-0927/observer-player-dark.webp">
+  <img alt="The Observer with one participant open: its desktop during a round of a movie-guessing game, replay controls and a filmstrip of captures below, and on the right its trace, with the participant's reasoning and each TAB and ENTER keypress" src="https://humanish.dev/runs/lobby-0927/observer-player-light.webp">
+</picture>
+
+Player four from the run above, a keyboard-only participant: its screen, and beside it each
+keypress and the reasoning it wrote before acting.
+
 The run writes its evidence to gitignored `.humanish/runs/<run id>/`: screenshots, every
 action, each participant's report and the estimated cost. The Observer replays it,
 `humanish review` prints the findings of the analysis that follows a live run, and
@@ -26,6 +45,14 @@ action, each participant's report and the estimated cost. The Observer replays i
 [How a study works](https://humanish.dev/docs/concepts) walks through one annotated study file,
 and the [study file reference](https://humanish.dev/docs/study-files) lists every field.
 
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://humanish.dev/runs/lobby-0927/observer-findings-dark.webp">
+  <img alt="The Observer's Findings tab: the first of seven findings, that three participants found keyboard guessing hard to track and one stopped mid-game, with the analysis's summary, what to check next, a cited capture and the timeline of evidence moments behind it" src="https://humanish.dev/runs/lobby-0927/observer-findings-light.webp">
+</picture>
+
+The first of the seven findings the analysis wrote for the same run, with the evidence moments
+it cites.
+
 ## Try it without keys
 
 In a project directory, with Node.js 22.19 or newer:
@@ -308,7 +335,7 @@ and the library exports.
 - Breaking changes ship together in one minor release. Its release notes carry a migration
   table: each old form, its new form, and the change to make.
 - The study file and the run bundle carry versioned schemas, `humanish.study.v3` and
-  `humanish.run-bundle.v1`. A breaking change to either one bumps its version.
+  `humanish.run-bundle.v2`. A breaking change to either one bumps its version.
 
 Pin the exact version in `package.json` and read [CHANGELOG.md](CHANGELOG.md) before upgrading.
 

package/dist/actors/computer-use/actor.d.ts

@@ -1,5 +1,6 @@
 import type { ActorPersonaRef, ActorTokenUsage, ActorTraceItem } from "../contract.js";
 import { type CuaExecutor, type CuaLiveMetadata, type CuaLoopResult, type CuaProvider, type CuaSafetyCheck } from "./loop.js";
+import type { ParticipantClock } from "./loop/types.js";
 import { type E2BDesktopExecutorOptions, type E2BDesktopLike } from "../../substrates/e2b/desktop-executor.js";
 import { type OpenAiResponsesProviderOptions } from "./openai-provider.js";
 import { type RedactionHooks } from "../../evidence/redaction.js";
@@ -42,6 +43,8 @@ export interface CuaActorSessionOptions {
     maxWaitMs?: number;
     /** How long a wait with no duration lasts in an idle turn. See LoopRunOptions.idleWaitMs. */
     idleWaitMs?: number;
+    /** The participant's time zone and scheduled end, forwarded to the loop. See CuaLoopOptions.clock. */
+    clock?: ParticipantClock;
     /**
      * Redact persisted screenshots (blur+downscale). Default `false`: full fidelity for local use.
      * Set true for unowned subjects or share-as-is bundles. The provider always sees raw frames.

package/dist/actors/computer-use/actor.js

@@ -43,6 +43,7 @@ export async function runCuaActorSession(options) {
         ...(options.writeScreenshot === undefined ? {} : { writeScreenshot: options.writeScreenshot }),
         ...(options.stopWhen === undefined ? {} : { stopWhen: options.stopWhen }),
         ...(options.dwell === undefined ? {} : { dwell: options.dwell }),
+        ...(options.clock === undefined ? {} : { clock: options.clock }),
         ...(options.tasks === undefined ? {} : { tasks: options.tasks }),
         ...(options.maxUsd === undefined ? {} : { maxUsd: options.maxUsd }),
         ...(options.estimateTurnCostUsd === undefined

package/dist/actors/computer-use/loop/backstop.d.ts

@@ -34,9 +34,14 @@ export interface BackstopStep {
     /** The gave_up reason when a streak tripped. */
     readonly tripReason: string | undefined;
 }
-/** Fold one acted turn and the observation after it into the backstop. */
+/**
+ * Fold one acted turn and the observation after it into the backstop. `waitingIsTheTask` says the
+ * participant has a scheduled end still to come: waiting for it is its job, so an idle turn counts
+ * toward neither streak and earns no nudge. A turn that acts is folded as usual.
+ */
 export declare function advanceBackstop(previous: Backstop, turn: {
     actions: readonly CuaAction[];
     observation: CuaObservation;
     heardNewSpeech: boolean;
+    waitingIsTheTask?: boolean;
 }, limits: BackstopLimits): BackstopStep;

package/dist/actors/computer-use/loop/backstop.js

@@ -122,9 +122,21 @@ export function startBackstop(observation) {
         idleProgressForgivenessUsed: 0,
     };
 }
-/** Fold one acted turn and the observation after it into the backstop. */
+/**
+ * Fold one acted turn and the observation after it into the backstop. `waitingIsTheTask` says the
+ * participant has a scheduled end still to come: waiting for it is its job, so an idle turn counts
+ * toward neither streak and earns no nudge. A turn that acts is folded as usual.
+ */
 export function advanceBackstop(previous, turn, limits) {
     const idle = isIdleTurn(turn.actions);
+    if (idle && turn.waitingIsTheTask === true)
+        return {
+            backstop: { ...previous, progressKey: progressKeyOf(turn.observation), consecutiveIdle: 0 },
+            idle,
+            progressed: true,
+            hints: [],
+            tripReason: undefined,
+        };
     const progressKey = progressKeyOf(turn.observation);
     const frameChanged = progressKey !== previous.progressKey;
     // Corroboration. A stale frame alone is not evidence of a stuck agent. The frame hash is

package/dist/actors/computer-use/loop/clock.d.ts

@@ -0,0 +1,20 @@
+import type { Stop } from "./ending.js";
+import type { LoopSession } from "./session.js";
+import type { CuaObservation, ParticipantClock } from "./types.js";
+/**
+ * The time text for the request the loop is about to send: the local time when the participant
+ * has a time zone, and the end time and the minutes left from the start of its wind-down, or
+ * after it tried to end its session before its end (`askedToEnd`). Undefined when there is
+ * nothing to say.
+ */
+export declare function clockHint(clock: ParticipantClock | undefined, now: () => number, askedToEnd?: boolean): string | undefined;
+/**
+ * Whether the participant has a scheduled end still to come. Its own end before then does not end
+ * the session: the end is what the study declared for it.
+ */
+export declare function beforeScheduledEnd(session: LoopSession): boolean;
+/**
+ * The stop at the participant's scheduled end, or undefined before it. The session passes as a
+ * planned end and the participant is asked for its closing report on the last observation.
+ */
+export declare function scheduledEndStop(session: LoopSession, observation: CuaObservation): Stop | undefined;

package/dist/actors/computer-use/loop/clock.js

@@ -0,0 +1,64 @@
+import { plural } from "../../../run/text.js";
+// What the participant knows about the time. A hosted desktop shows a maximized browser with no
+// OS clock, so a participant told "your shift ends at 11:00" cannot relate it to now unless each
+// turn says so. The text rides the request's context hint, which every provider sends with the
+// turn (OpenAI as a user message, Codex and the local agents as the harness note).
+/**
+ * The time text for the request the loop is about to send: the local time when the participant
+ * has a time zone, and the end time and the minutes left from the start of its wind-down, or
+ * after it tried to end its session before its end (`askedToEnd`). Undefined when there is
+ * nothing to say.
+ */
+export function clockHint(clock, now, askedToEnd = false) {
+    if (clock === undefined)
+        return undefined;
+    const nowMs = now();
+    const parts = [];
+    if (clock.timeZone !== undefined)
+        parts.push(`The local time is ${hourMinute(nowMs, clock.timeZone)} (${clock.timeZone}).`);
+    const { end } = clock;
+    if (end !== undefined && (askedToEnd || nowMs >= end.atMs - end.windDownMs)) {
+        const minutesLeft = Math.max(1, Math.ceil((end.atMs - nowMs) / 60_000));
+        parts.push(`${askedToEnd ? "Your session is not over. " : ""}Your session ends at ${endTime(clock, end.atMs)}, in ${plural(minutesLeft, "minute")}. Keep working until then. The session ends by itself at that time, and you will then be asked for your closing account.`);
+    }
+    return parts.length === 0 ? undefined : parts.join(" ");
+}
+/**
+ * Whether the participant has a scheduled end still to come. Its own end before then does not end
+ * the session: the end is what the study declared for it.
+ */
+export function beforeScheduledEnd(session) {
+    const end = session.settings.clock?.end;
+    return end !== undefined && session.now() < end.atMs;
+}
+/**
+ * The stop at the participant's scheduled end, or undefined before it. The session passes as a
+ * planned end and the participant is asked for its closing report on the last observation.
+ */
+export function scheduledEndStop(session, observation) {
+    const end = session.settings.clock?.end;
+    if (end === undefined || session.now() < end.atMs)
+        return undefined;
+    return {
+        completionReason: "goal_satisfied",
+        reason: `the participant's scheduled end at ${endTime(session.settings.clock, end.atMs)} was reached`,
+        stopCause: "scheduled_end",
+        debriefTrigger: { kind: "scheduled_end", observation },
+    };
+}
+// The end to the nearest minute: a run starts at no particular second, and "ends at 00:09" read
+// at 00:09:06 looks past.
+function endTime(clock, atMs) {
+    const minute = Math.round(atMs / 60_000) * 60_000;
+    return clock.timeZone === undefined
+        ? `${hourMinute(minute, "UTC")} UTC`
+        : hourMinute(minute, clock.timeZone);
+}
+function hourMinute(ms, timeZone) {
+    return new Intl.DateTimeFormat("en-GB", {
+        timeZone,
+        hour: "2-digit",
+        minute: "2-digit",
+        hourCycle: "h23",
+    }).format(ms);
+}

package/dist/actors/computer-use/loop/ending.d.ts

@@ -8,7 +8,7 @@ import type { CuaObservation, CuaProvider, CuaTurn } from "./types.js";
  * the participant's own ending when only its impressions are missing.
  */
 export interface DebriefTrigger {
-    readonly kind: "stop_when" | "dwell" | "participant_end";
+    readonly kind: "stop_when" | "dwell" | "scheduled_end" | "participant_end";
     /** The final observation, already captured; the debrief request sends it without observing. */
     readonly observation: CuaObservation;
 }

package/dist/actors/computer-use/loop/session.d.ts

@@ -12,7 +12,7 @@ export type ScreenshotRef = NonNullable<ActorTraceItem["screenshotRef"]>;
  * wrapped callbacks are fields on LoopSession instead. Callers destructure hooks to call them.
  */
 export type LoopSettings = {
-    readonly [K in "instructions" | "persona" | "redaction" | "stopWhen" | "dwell" | "tasks" | "maxUsd" | "overRunBudget" | "estimateTurnCostUsd" | "onObservedUrl" | "onMessage" | "onScreenshot" | "onTrace"]: LoopRunOptions[K];
+    readonly [K in "instructions" | "persona" | "redaction" | "stopWhen" | "dwell" | "clock" | "tasks" | "maxUsd" | "overRunBudget" | "estimateTurnCostUsd" | "onObservedUrl" | "onMessage" | "onScreenshot" | "onTrace"]: LoopRunOptions[K];
 };
 /** The participant's dispatched actions, as the backstop and failure notices describe them. */
 export interface ActionHistory {

package/dist/actors/computer-use/loop/session.js

@@ -70,13 +70,14 @@ export class LoopSession {
     scrubText;
     constructor(options) {
         // Read once, in this order: a caller mutating its options object mid-run changes nothing.
-        const { instructions, provider, executor, persona, redaction, timeoutMs, now, signal, idleSteps = DEFAULT_IDLE_STEPS, noProgressSteps = DEFAULT_NO_PROGRESS_STEPS, maxWaitMs, idleWaitMs, acknowledgeSafetyChecks = () => null, redactScreenshots = false, scrubText = (text) => text, writeScreenshot = async (name) => `screenshots/${name}`, stopWhen, dwell, sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)), tasks, maxUsd, overRunBudget, estimateTurnCostUsd, requireReportedUsageForSpendCap = false, onObservedUrl, onMessage, onScreenshot, onTrace, } = options;
+        const { instructions, provider, executor, persona, redaction, timeoutMs, now, signal, idleSteps = DEFAULT_IDLE_STEPS, noProgressSteps = DEFAULT_NO_PROGRESS_STEPS, maxWaitMs, idleWaitMs, acknowledgeSafetyChecks = () => null, redactScreenshots = false, scrubText = (text) => text, writeScreenshot = async (name) => `screenshots/${name}`, stopWhen, dwell, clock, sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)), tasks, maxUsd, overRunBudget, estimateTurnCostUsd, requireReportedUsageForSpendCap = false, onObservedUrl, onMessage, onScreenshot, onTrace, } = options;
         this.settings = {
             instructions,
             persona,
             redaction,
             stopWhen,
             dwell,
+            clock,
             tasks,
             maxUsd,
             overRunBudget,

package/dist/actors/computer-use/loop/types.d.ts

@@ -4,6 +4,14 @@ import type { RedactionHooks } from "../../../evidence/redaction.js";
 import type { DwellWindow, StopWhen } from "../../stop-conditions.js";
 import type { StudyTask } from "../../../study/tasks.js";
 import type { ReasoningEffort } from "../../reasoning-effort.js";
+/** The participant's clock: its local time zone and its scheduled end, on the loop's clock. */
+export interface ParticipantClock {
+    readonly timeZone?: string;
+    readonly end?: {
+        readonly atMs: number;
+        readonly windDownMs: number;
+    };
+}
 /**
  * One desktop action. `heldKeys` on a pointer action are held down for the whole action and
  * released after it, named as the provider sent them (for example `SHIFT` for a shift-click). An
@@ -346,6 +354,14 @@ export interface CuaLoopOptions {
     dwell?: DwellWindow;
     /** Injected pause for the dwell window's cadence; tests advance their clock through it. */
     sleep?: (ms: number) => Promise<void>;
+    /**
+     * What each turn tells the participant about the time (loop/clock.ts). With `timeZone`, a time zone
+     * name, every request carries the local time. With `end`, from `end.atMs - end.windDownMs`
+     * every request names the end time (in `timeZone`, else UTC) and the minutes left, and at
+     * `end.atMs`, read on `now`, the loop asks for the closing report and ends the session with
+     * stop cause `scheduled_end`.
+     */
+    clock?: ParticipantClock;
     /**
      * The study's declared protocol: discrete tasks whose completion is corroborated by the
      * same observations stopWhen reads, on the same cadence. The tracker never influences the loop's

package/dist/actors/computer-use/loop.d.ts

@@ -1,5 +1,5 @@
 import type { CuaLoopOptions, CuaLoopResult, LoopRunOptions } from "./loop/types.js";
-export type { CuaAction, CuaExecutor, CuaLiveMetadata, CuaLoopOptions, CuaLoopResult, CuaObservation, CuaProvider, CuaSafetyCheck, CuaSpendGate, CuaTurn, CuaTurnRequest, } from "./loop/types.js";
+export type { CuaAction, CuaExecutor, CuaLiveMetadata, CuaLoopOptions, CuaLoopResult, CuaObservation, CuaProvider, CuaSafetyCheck, CuaSpendGate, CuaTurn, CuaTurnRequest, ParticipantClock, } from "./loop/types.js";
 export { describeCuaAction } from "./loop/actions.js";
 export { stableProgressKey } from "./loop/backstop.js";
 export { IMPRESSIONS_ASK } from "./loop/impressions.js";

package/dist/actors/computer-use/loop.js

@@ -1,7 +1,8 @@
 import { closingReportSchema } from "../closing-report.js";
 import { ComputerUseProviderError } from "./provider-error.js";
 import { runActionBatch } from "./loop/actions.js";
-import { advanceBackstop, startBackstop } from "./loop/backstop.js";
+import { advanceBackstop, startBackstop, } from "./loop/backstop.js";
+import { beforeScheduledEnd, clockHint, scheduledEndStop } from "./loop/clock.js";
 import { requestDebrief } from "./loop/debrief.js";
 import * as stops from "./loop/ending.js";
 import { declaredOutcomeOf } from "./loop/ending.js";
@@ -51,6 +52,7 @@ export async function runComputerUseLoopWithTaps(options) {
         previousExecution: undefined,
         acknowledgedSafetyChecks: undefined,
         contextHint: undefined,
+        askedToEnd: false,
     };
     let stop;
     try {
@@ -84,7 +86,7 @@ async function runTurns(session, conversation) {
     // A request whose reply was cut off by the output limit, to be sent once more.
     let resend;
     for (;;) {
-        const halt = haltBeforeTurn(session);
+        const halt = haltBeforeTurn(session, observation);
         if (halt !== undefined)
             return halt;
         turnNumber += 1;
@@ -116,6 +118,13 @@ async function runTurns(session, conversation) {
         const blocked = reviewSafetyChecks(session, conversation, turn);
         if (blocked !== undefined)
             return blocked;
+        if ((turn.done || turn.actions.length === 0) && beforeScheduledEnd(session)) {
+            const held = keepWorking(session, conversation, backstop, observation);
+            if ("stop" in held)
+                return held.stop;
+            backstop = held.backstop;
+            continue;
+        }
         if (turn.done || turn.actions.length === 0) {
             // The declared outcome is kept even if redacting the participant's summary fails.
             session.declaredOutcome = declaredOutcomeOf(turn);
@@ -139,7 +148,12 @@ async function runTurns(session, conversation) {
         if ("stop" in checkpoint)
             return checkpoint.stop;
         observation = checkpoint.observation;
-        const step = advanceBackstop(backstop, { actions: turn.actions, observation, heardNewSpeech: observer.heardNewSpeech }, { idleSteps: session.idleSteps, noProgressSteps: session.noProgressSteps });
+        const step = advanceBackstop(backstop, {
+            actions: turn.actions,
+            observation,
+            heardNewSpeech: observer.heardNewSpeech,
+            waitingIsTheTask: beforeScheduledEnd(session),
+        }, { idleSteps: session.idleSteps, noProgressSteps: session.noProgressSteps });
         backstop = step.backstop;
         const stalled = applyBackstop(session, conversation, step, [checkpoint.hint, batch.hint]);
         if (stalled !== undefined)
@@ -149,6 +163,20 @@ async function runTurns(session, conversation) {
             return unknownSpend;
     }
 }
+/**
+ * A participant with a scheduled end that ended its own session before the end keeps going: the
+ * next request tells it the time left. The turn took no action, so it counts toward the idle
+ * backstop, which ends a participant that only keeps trying to stop.
+ */
+function keepWorking(session, conversation, backstop, observation) {
+    session.trace.record("notice", () => notice("warn", "participant ended before its scheduled end", "The participant ended its session before its scheduled end, so the session continues and the participant is told the time left."));
+    conversation.askedToEnd = true;
+    // The turn executed nothing, so the next request acknowledges nothing.
+    conversation.previousExecution = undefined;
+    const step = advanceBackstop(backstop, { actions: [], observation, heardNewSpeech: false }, { idleSteps: session.idleSteps, noProgressSteps: session.noProgressSteps });
+    const stalled = applyBackstop(session, conversation, step, []);
+    return stalled === undefined ? { backstop: step.backstop } : { stop: stalled };
+}
 /**
  * Count the turn's idle and no-progress flags, stage every hint for the next request, and stop
  * when a streak tripped. The
@@ -173,15 +201,22 @@ function refuseAccountBilledCaps(options) {
         });
     }
 }
-function haltBeforeTurn(session) {
+function haltBeforeTurn(session, observation) {
     if (session.signal?.aborted)
         return stops.harnessAborted;
-    if (session.remaining() < 0)
-        return stops.timeLimit(session);
-    return undefined;
+    return (scheduledEndStop(session, observation) ??
+        (session.remaining() < 0 ? stops.timeLimit(session) : undefined));
 }
-/** Build the next request; the context hint and safety acknowledgements ride it once. */
+/**
+ * Build the next request; the context hint and safety acknowledgements ride it once. The
+ * participant's clock text rides every request, after any other hint.
+ */
 function nextRequest(session, conversation, observation) {
+    const clock = clockHint(session.settings.clock, session.now, conversation.askedToEnd);
+    conversation.askedToEnd = false;
+    if (clock !== undefined)
+        conversation.contextHint =
+            conversation.contextHint === undefined ? clock : `${conversation.contextHint} ${clock}`;
     const request = {
         instructions: session.settings.instructions,
         observation,

package/dist/actors/computer-use/wait.d.ts

@@ -50,12 +50,13 @@ export interface PlannedWait {
 export declare function defaultMaxWaitMs(speechEnabled: boolean): number;
 /**
  * Why these wait fields cannot run, or null. `prefix` names their owner in the message: `actor.`
- * in a study file, empty for loop options.
+ * in a study file, empty for loop options. `maxPrefix` names the owner of maxWaitMs when it is
+ * another, as for a participant's own idleWaitMs under actor.maxWaitMs.
  */
 export declare function waitFieldsReason(fields: {
     readonly maxWaitMs?: unknown;
     readonly idleWaitMs?: unknown;
-}, prefix: string): string | null;
+}, prefix: string, maxPrefix?: string): string | null;
 /**
  * The wait lengths a session applies: the study's values, or their defaults. The idle wait never
  * outlasts the longest wait, which on a desktop with speech defaults to 30 s. Throws a RangeError

package/dist/actors/computer-use/wait.js

@@ -55,16 +55,17 @@ const FIELDS = [
 ];
 /**
  * Why these wait fields cannot run, or null. `prefix` names their owner in the message: `actor.`
- * in a study file, empty for loop options.
+ * in a study file, empty for loop options. `maxPrefix` names the owner of maxWaitMs when it is
+ * another, as for a participant's own idleWaitMs under actor.maxWaitMs.
  */
-export function waitFieldsReason(fields, prefix) {
+export function waitFieldsReason(fields, prefix, maxPrefix = prefix) {
     for (const [name, meaning] of FIELDS) {
         if (fields[name] !== undefined && !isWaitMs(fields[name]))
-            return `${prefix}${name}, ${meaning}, must be a whole number of milliseconds from ${CUA_WAIT_LIMITS.leastMs} to ${CUA_WAIT_LIMITS.mostMs}.`;
+            return `${name === "maxWaitMs" ? maxPrefix : prefix}${name}, ${meaning}, must be a whole number of milliseconds from ${CUA_WAIT_LIMITS.leastMs} to ${CUA_WAIT_LIMITS.mostMs}.`;
     }
     const { maxWaitMs, idleWaitMs } = fields;
     if (typeof maxWaitMs === "number" && typeof idleWaitMs === "number" && idleWaitMs > maxWaitMs)
-        return `${prefix}idleWaitMs (${idleWaitMs}) is longer than ${prefix}maxWaitMs (${maxWaitMs}), the longest one wait action lasts. Lower ${prefix}idleWaitMs or raise ${prefix}maxWaitMs.`;
+        return `${prefix}idleWaitMs (${idleWaitMs}) is longer than ${maxPrefix}maxWaitMs (${maxWaitMs}), the longest one wait action lasts. Lower ${prefix}idleWaitMs or raise ${maxPrefix}maxWaitMs.`;
     return null;
 }
 /**

package/dist/actors/contract.d.ts

@@ -37,7 +37,7 @@ export type ParticipantDeclaredOutcome = "reached" | "not_reached" | "blocked";
 export declare const PARTICIPANT_OUTCOME_STATUSES: readonly ActorStatus[];
 /** Optional precise interruption cause; completionReason and status retain their original meaning.
  *  One list, so the analysis schema and the diagnostics projection cannot drift from the trace. */
-export declare const ACTOR_STOP_CAUSES: readonly ["provider_output_limit", "provider_token_limit", "time_limit", "spend_limit", "study_spend_limit", "adapter_limit", "provider_incomplete", "provider_status", "provider_refused_prompt", "harness_aborted", "usage_unreported"];
+export declare const ACTOR_STOP_CAUSES: readonly ["provider_output_limit", "provider_token_limit", "time_limit", "spend_limit", "study_spend_limit", "adapter_limit", "provider_incomplete", "provider_status", "provider_refused_prompt", "harness_aborted", "usage_unreported", "scheduled_end"];
 export type ActorStopCause = (typeof ACTOR_STOP_CAUSES)[number];
 export type ActorCompletionReason = "goal_satisfied" | "turn_completed" | "gave_up" | "blocked_approval" | "timed_out" | "budget_reached" | "actor_error" | "step_failed" | "harness_error";
 type ActorRunKind = "code" | "computer-use" | "scripted-browser" | "terminal";
@@ -346,11 +346,11 @@ export interface ActorTrace {
     declaredOutcome?: ParticipantDeclaredOutcome;
     /**
      * The read-only closing request: a closing report after a harness-owned stop (`stop_when`,
-     * `dwell`), or impressions only after the participant ended the session itself
+     * `dwell`, `scheduled_end`), or impressions only after the participant ended the session itself
      * (`participant_end`, never with `report`). Does not change task outcomes or permit actions.
      */
     debrief?: {
-        trigger: "stop_when" | "dwell" | "participant_end";
+        trigger: "stop_when" | "dwell" | "scheduled_end" | "participant_end";
         status: "completed" | "skipped" | "failed";
         reason: string;
         /** Absent if no request was made; false means token accounting is incomplete. */

package/dist/actors/contract.js

@@ -53,6 +53,9 @@ export const ACTOR_STOP_CAUSES = [
     "provider_refused_prompt",
     "harness_aborted",
     "usage_unreported",
+    // The participant's scheduled end (participants[].endAfterMs) came. A planned end: the session
+    // is goal_satisfied, and the closing report follows.
+    "scheduled_end",
 ];
 /**
  * The oldest Codex CLI release a recorded account profile may name. Readers accept every stable

package/dist/actors/stop-cause.js

@@ -10,6 +10,7 @@ const labels = {
     provider_status: "unexpected provider status",
     provider_refused_prompt: "provider refused the prompt under its usage policy",
     harness_aborted: "stopped by harness",
+    scheduled_end: "scheduled end",
     unspecified_limit: "limit reached",
 };
 /** Shared wording for consumers that already hold a validated, finite stop cause. */

package/dist/analysis/automatic.js

@@ -4,6 +4,7 @@ import {} from "../run/bundle.js";
 import { refreshObserver, analyzeRun, readCompletedAnalysisSource, resolveAnalysisRun, } from "./service.js";
 import { preferLargerAnalysisOutput, ANALYSIS_PROMPT_VERSION } from "./execute.js";
 import { captureEvidence } from "./evidence.js";
+import { loadRunTraces } from "../run/stream-trace.js";
 import { hashAnalysisValue } from "./validation.js";
 import { refusedCost } from "./admission.js";
 import { claimAutomaticAnalysis, readAutomaticAnalysisPrepared, requestAutomaticAnalysisCancellationPrepared, } from "./job.js";
@@ -88,7 +89,7 @@ async function readAutomaticSource(cwd, prepared, configInput, deps, hasKey) {
     let config = configInput;
     try {
         const bytes = await readCompletedAnalysisSource(cwd, prepared);
-        const bundle = JSON.parse(bytes.toString("utf8"));
+        const bundle = await loadRunTraces(prepared, JSON.parse(bytes.toString("utf8")));
         if (bundle.streams.some((stream) => stream.actor?.stopCause === "harness_aborted"))
             return skipped("AUTOMATIC_ANALYSIS_ACTOR_CANCELLED");
         const participantEvidence = hasParticipantEvidence(bundle);