humanish 0.120.1 → 0.122.0

package/CHANGELOG.md

@@ -8,6 +8,36 @@ The Unreleased section holds the full notes for the next version until it is tag
 
 ## Unreleased
 
+## 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
+names a host that slept mid-run as the likely cause of the failures after it. A computer-use study
+on an `app-url` subject no longer holds its participants behind the first one's desktop, and a
+participant that fails before its session no longer stops the participants queued behind it; a
+study whose subject is built in each sandbox still lets one participant set it up first, and the
+next one takes over when the first never got a desktop. When the machine running a study sleeps,
+the run records the suspension as a `host.suspended` event, and the run outcome, `humanish run`,
+the review and the `--json` result say the failures of participants running through it are
+likely its effect, while each participant's record keeps its own error. The review's participant
+line lists interruption causes in a fixed order.
+
+[Release notes](https://github.com/danielgwilson/humanish/releases/tag/v0.121.0)
+
 ## 0.120.1: Analysis requests under Bun run past 5 minutes (2026-10-09)
 
 humanish 0.120.1 lets an analysis request from a Bun process run longer than 5 minutes. Under Bun,

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/cli/commands/study-format.js

@@ -1,10 +1,12 @@
 import { participantCaption } from "../../run/participant-caption.js";
 import { formatCuaDiagnostics, formatCuaStopCause } from "../../routes/computer-use/diagnostics.js";
 import { subjectName } from "../../run/subject-name.js";
+import { cli } from "../invocation.js";
 /**
  * A run's first lines: the command that ran, whether it was a dry run, how it ended, and its route.
  * `runOk` is the run's own ok, which automaticAnalysisEnvelope keeps when an analysis that did not
- * complete turns `ok` false. That run finished, and the line says so.
+ * complete turns `ok` false. That run finished, and the line says so. A host suspension follows,
+ * since it may explain every failure listed after it.
  */
 function runHeader(result, route) {
     const kind = result.dryRun === true ? "dry run" : result.dryRun === false ? "live run" : "run";
@@ -13,7 +15,24 @@ function runHeader(result, route) {
         : result.runOk === true
             ? "finished; the analysis did not complete"
             : "failed";
-    return [`humanish run ${result.studyId}: ${kind} ${ending}`, `route: ${route}`];
+    return [
+        `humanish run ${result.studyId}: ${kind} ${ending}`,
+        `route: ${route}`,
+        ...(result.hostSuspension === undefined ? [] : [result.hostSuspension.summary]),
+    ];
+}
+/**
+ * What to run after a host suspension failed participants: the rerun of those that did not pass,
+ * or the study again for a run with one participant.
+ */
+function suspensionNextStep(result, participants) {
+    if ((result.hostSuspension?.participantIds.length ?? 0) === 0)
+        return [];
+    return participants > 1
+        ? [
+            `Rerun the participants that did not pass: ${cli(`run ${result.studyId} --rerun-failed-from ${result.runId}`)}`,
+        ]
+        : [`Run it again: ${cli(`run ${result.studyId}`)}`];
 }
 /**
  * A run's human output: its lines on stdout and, when it failed with an error, that error on
@@ -167,8 +186,10 @@ export function formatScriptedStudyHuman(result, subject) {
 }
 /** `subject` is the study's declared subject, which names it when the result has no URL. */
 export function formatCuaStudyHuman(result, subject) {
+    const participants = result.lanes ?? [];
     return withError(result.error, [
         ...runHeader(result, "computer-use"),
+        ...suspensionNextStep(result, participants.length),
         `run: ${result.runId}`,
         `actor: ${result.actor}`,
         `subject: ${subjectLine(result.appUrl, subject)}`,
@@ -181,8 +202,8 @@ export function formatCuaStudyHuman(result, subject) {
             ? [`rerun: ${result.rerun.selectedLaneIds.join(", ")} from ${result.rerun.sourceRunId}`]
             : []),
         ...(result.diagnostics ? [`diagnostic: ${formatCuaDiagnostics(result.diagnostics)}`] : []),
-        ...participantLines(result.lanes ?? []),
-        ...(result.session && (result.lanes?.length ?? 0) <= 1
+        ...participantLines(participants),
+        ...(result.session && participants.length <= 1
             ? [
                 `session: ${participantStatus(result.session.status)} (${result.session.completionReason})${result.session.stopCause ? ` · ${formatCuaStopCause(result.session.stopCause)}` : ""} · ${result.session.reason}`,
                 `screenshots: ${result.session.screenshots}`,

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

@@ -2,6 +2,7 @@ import type { CuaActorDescriptor } from "../../actors/registry.js";
 import type { ComputerUsePlan } from "../../study/plan-types.js";
 import type { BundleRun, RunBundle, RunRerunLineage, RunSubjectProvenance } from "../../run/bundle.js";
 import { type Judgment } from "../../run/judge.js";
+import type { HostSuspensionReading } from "../../run/host-suspension.js";
 import type { CuaParticipantPlan, DesktopParticipantRun, ParticipantRunOutcome } from "./types.js";
 /** What every bundle of one run shares, in progress or final. */
 export interface CuaRunBundleBase {
@@ -34,7 +35,8 @@ interface CuaRunBundleState {
     outcomes: ParticipantRunOutcome[] | undefined;
     subjects: RunSubjectProvenance[];
     aggregateSubject: RunSubjectProvenance;
-    failFastReason?: string;
+    /** The final bundle's reading of the run's host suspensions. */
+    hostSuspension?: HostSuspensionReading;
     inProgress?: true;
 }
 /**

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

@@ -60,7 +60,7 @@ export function buildCuaRunBundle(base, state) {
         source: base.source,
         participantPlan: base.participantPlan,
         ...(base.rerun === undefined ? {} : { rerun: base.rerun }),
-        ...(state.failFastReason === undefined ? {} : { failFastReason: state.failFastReason }),
+        ...(state.hostSuspension === undefined ? {} : { hostSuspension: state.hostSuspension }),
         ...(base.publicRepo === undefined ? {} : { publicRepo: base.publicRepo }),
         ...inProgress,
     });
@@ -117,6 +117,7 @@ function singleParticipantArgs(base, state) {
             }),
         source: base.source,
         ...(state.inProgress === undefined ? {} : { inProgress: state.inProgress }),
+        ...(state.hostSuspension === undefined ? {} : { hostSuspension: state.hostSuspension }),
         subject: state.aggregateSubject,
         ...(desktopTemplate === undefined ? {} : { desktopTemplate }),
         ...(outcome?.desktopBrowser === undefined ? {} : { desktopBrowser: outcome.desktopBrowser }),

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

@@ -3,7 +3,7 @@ import { type ActorCompletionReason, type ActorStatus, type ActorStopCause } fro
 declare const CUA_DIAGNOSTIC_CATEGORIES: readonly ["preview", "participant_outcome", "session_interrupted", "execution_error", "evidence_invalid", "mixed", "unknown"];
 export type CuaDiagnosticCategory = (typeof CUA_DIAGNOSTIC_CATEGORIES)[number];
 /** Closed at both projection and telemetry boundaries. No provider messages are classified. */
-declare const CUA_DIAGNOSTIC_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", "unspecified_limit", "mixed", "unknown"];
+declare const CUA_DIAGNOSTIC_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", "unspecified_limit", "mixed", "unknown"];
 export type CuaDiagnosticStopCause = (typeof CUA_DIAGNOSTIC_STOP_CAUSES)[number];
 export interface CuaDiagnostics {
     category: CuaDiagnosticCategory;

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

@@ -30,6 +30,10 @@ export function cuaParticipantDiagnostics(input) {
     const session = input.session;
     if (!session)
         return { category: "unknown" };
+    // A scheduled end is the participant's planned ending, so a run whose other participants ended
+    // themselves reads as one kind of ending.
+    if (session.stopCause === "scheduled_end")
+        return { category: "participant_outcome" };
     if (session.stopCause !== undefined) {
         return {
             category: "session_interrupted",

package/dist/routes/computer-use/fanout-bundle.d.ts

@@ -3,9 +3,8 @@ import type { CuaFanoutBundleArgs } from "./types.js";
 /**
  * Project N>1 fan-out participants into a humanish.run-bundle.v1 (the evidence schema is unchanged; this
  * is a new producer for the multi-stream shape). One sim + one stream per participant; per-participant
- * provenance/session events; a recorded `cua-lab.fanout.plan` event (and a `cua-lab.fanout.fail-fast`
- * event when a harness error skipped queued participants). N-ary verify/Observer already handle multiple
- * streams. A single-participant run without a rerun never reaches here: buildCuaRunBundle
+ * provenance/session events; a recorded `cua-lab.fanout.plan` event. N-ary verify/Observer already
+ * handle multiple streams. A single-participant run without a rerun never reaches here: buildCuaRunBundle
  * (bundle.ts) sends it to buildSingleParticipantBundle (single-bundle.ts).
  */
 export declare function buildCuaFanoutBundle(args: CuaFanoutBundleArgs): RunBundle;