humanish 0.121.0 → 0.123.0

package/dist/observer/run-routes.js

@@ -1,6 +1,7 @@
 // HTTP handlers for one run's Observer: the page, its data with live status and runtime stream
 // URLs, its analysis, and its media with byte ranges. serveObserver (render.ts) and the library
 // server (serve.ts) both route requests through them.
+import { lstat } from "node:fs/promises";
 import path from "node:path";
 import { isAnalysisRecordPath, projectShareCheckedAnalysis } from "../analysis/sharing.js";
 import { loadAnalysis } from "../analysis/load.js";
@@ -9,6 +10,8 @@ import { listRuns } from "../run/stored-runs.js";
 import { readAnalysisAccounting } from "../run/costs.js";
 import { bindExistingRunArtifactPaths, isPathInside, isSafeRunIdSegment, } from "../run/paths.js";
 import { isRunOutcome } from "../run/bundle-shape.js";
+import { displayedTraces, loadStreamTraces } from "../run/stream-trace.js";
+import { isNodeError, isRecord } from "../run/type-guards.js";
 import { MAX_NOTE_FILE_BYTES, readRunNotes, RUN_NOTES_DIR, } from "../run/note-files.js";
 import { analysisCostOf, runCost, runCostLabel } from "../run/run-cost.js";
 import { RUN_STATUS_FILE, RUN_STATUS_STALE_MS, isRunStatusRecord, } from "../run/status.js";
@@ -99,9 +102,9 @@ export async function serveRunPath(runRoot, relativePath, response, runtimeStrea
         return;
     }
     if (cleanedRelativePath === "observer/index.html") {
-        const observerData = await readObserverData(runRoot, runtimeStreamUrls);
-        if (!observerData) {
-            writeResponse(response, 404, "Observer data not found", "text/plain; charset=utf-8");
+        const observerData = await observerDataOrReason(runRoot, runtimeStreamUrls);
+        if ("unavailable" in observerData) {
+            writeResponse(response, 404, `Observer data not found: ${observerData.unavailable}`, "text/plain; charset=utf-8");
             return;
         }
         const analysis = await readObserverAnalysis(runRoot);
@@ -114,9 +117,9 @@ export async function serveRunPath(runRoot, relativePath, response, runtimeStrea
         return;
     }
     if (cleanedRelativePath === "observer/observer-data.json") {
-        const observerData = await readObserverData(runRoot, runtimeStreamUrls);
-        if (!observerData) {
-            writeResponse(response, 404, "Observer data not found", "text/plain; charset=utf-8");
+        const observerData = await observerDataOrReason(runRoot, runtimeStreamUrls);
+        if ("unavailable" in observerData) {
+            writeResponse(response, 404, `Observer data not found: ${observerData.unavailable}`, "text/plain; charset=utf-8");
             return;
         }
         writeResponse(response, 200, JSON.stringify(observerData, null, 2), "application/json; charset=utf-8");
@@ -153,29 +156,69 @@ export async function serveRunPath(runRoot, relativePath, response, runtimeStrea
         writeResponse(response, 404, "Not found", "text/plain; charset=utf-8");
     }
 }
+/** The run's trace files, read through its pinned folder. */
+function pinnedTraceReader(runRoot) {
+    return async (relativePath, maxBytes) => {
+        const bytes = await readContainedFile(runRoot, path.join(runRoot.physicalPath, relativePath), {
+            maxBytes,
+        }).catch(() => null);
+        return bytes === null ? { refused: `${relativePath} could not be read` } : { bytes };
+    };
+}
 async function readObserverData(runRoot, runtimeStreamUrls = []) {
+    const read = await observerDataOrReason(runRoot, runtimeStreamUrls);
+    return "unavailable" in read ? null : read;
+}
+/**
+ * The run's Observer data, or why there is none. run.json is the source: each trace is loaded
+ * through the loader, and a participant whose trace it refuses shows as unavailable, with no
+ * fallback. The saved observer-data.json is read only while the run has no run.json at all, or in
+ * safe serving, where only its admitted bytes can be read. Otherwise a run.json that is there and
+ * cannot be read, parsed or used as a bundle (which a browser poll can meet mid-write) gives the
+ * reason, a 404 the poller retries, never the saved projection.
+ */
+async function observerDataOrReason(runRoot, runtimeStreamUrls) {
     const record = await readLocalRunStatus(runRoot);
-    // Best-effort load from either source. Both reads swallow all errors on
-    // purpose: this runs on every browser poll of a live run, where run.json may
-    // be absent, still being written (a partial-JSON parse error), or superseded
-    // by observer-data.json. A transient failure just falls through to the next
-    // source, or to null -> a 404 the poller retries; it must not surface a 500.
+    const runJson = path.join(runRoot.physicalPath, "run.json");
+    const bundleBytes = await readContainedFile(runRoot, runJson).catch(() => null);
+    const absent = bundleBytes === null &&
+        (await lstat(runJson).then(() => false, (error) => isNodeError(error) && error.code === "ENOENT"));
+    // A root admitted for safe serving checks every read against the identity and digest admitted
+    // with the run's share_ready verification, so a run.json changed since then is refused, and the
+    // saved projection it may serve is the one admitted with the verified run.
+    if (absent || (bundleBytes === null && runRoot.admitsContent !== undefined))
+        return savedObserverData(runRoot, record, runtimeStreamUrls);
+    if (bundleBytes === null)
+        return { unavailable: "run.json is there but could not be read: it is a link or changed." };
+    let stored;
+    try {
+        const parsed = JSON.parse(bundleBytes.toString("utf8"));
+        if (!isRecord(parsed) || !Array.isArray(parsed.streams))
+            throw new Error("not a run bundle");
+        stored = parsed;
+    }
+    catch {
+        return { unavailable: "run.json is not a run bundle; it may be mid-write, so try again." };
+    }
     try {
-        const bundleBytes = await readContainedFile(runRoot, path.join(runRoot.physicalPath, "run.json"));
-        if (!bundleBytes)
-            throw new Error("run.json unavailable");
-        const bundle = JSON.parse(bundleBytes.toString("utf8"));
+        const bundle = displayedTraces(await loadStreamTraces(pinnedTraceReader(runRoot), stored));
         return withRuntimeStreamUrls(withLocalRunStatus(record, buildObserverData(bundle, undefined, record), bundle.outcome), runtimeStreamUrls);
     }
-    catch { }
+    catch {
+        return { unavailable: "run.json could not be shown as a run." };
+    }
+}
+/** The saved observer-data.json of a run that has written no run.json yet. */
+async function savedObserverData(runRoot, record, runtimeStreamUrls) {
     try {
         const observerBytes = await readContainedFile(runRoot, path.join(runRoot.physicalPath, "observer", "observer-data.json"));
         if (!observerBytes)
             throw new Error("observer-data.json unavailable");
         return withRuntimeStreamUrls(withLocalRunStatus(record, withObserverEndings(JSON.parse(observerBytes.toString("utf8")))), runtimeStreamUrls);
     }
-    catch { }
-    return null;
+    catch {
+        return { unavailable: "The run has written no run.json or Observer data yet." };
+    }
 }
 /** The run directory's own status record, when it is well formed and names that directory. */
 async function readLocalRunStatus(runRoot) {

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

@@ -35,7 +35,6 @@ 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,6 @@ 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,

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;

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

@@ -181,9 +181,8 @@ function fanoutFeedbackCandidates(args) {
 /**
  * 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 function buildCuaFanoutBundle(args) {
@@ -215,15 +214,6 @@ export function buildCuaFanoutBundle(args) {
         streams.push(records.stream);
         events.push(...records.events);
     });
-    if (args.failFastReason) {
-        events.push({
-            id: nextEventId("fanout-fail-fast"),
-            at: args.run.createdAt,
-            level: "warn",
-            type: "cua-lab.fanout.fail-fast",
-            message: `Fan-out fail-fast: ${args.failFastReason}. In-flight participants finished; queued participants were skipped (blocked); completed evidence is retained.`,
-        });
-    }
     const review = fanoutReview(args, streams, judgment);
     const anyRaw = (outcomes ?? []).some((outcome) => outcome.session?.trace.redaction.screenshots === "raw");
     const ranLive = (outcomes ?? []).some((outcome) => outcome.session !== undefined || outcome.sessionError !== undefined);

package/dist/routes/computer-use/live-phase.d.ts

@@ -47,7 +47,6 @@ export declare function runStudyParticipants(setup: CuaRunSetup, participants: C
         runId: string;
     };
     outcomes?: never;
-    failFastReason?: never;
     receiving?: never;
     receivingWarnings?: never;
     externalCommsWarnings?: never;
@@ -55,7 +54,6 @@ export declare function runStudyParticipants(setup: CuaRunSetup, participants: C
     result?: never;
     ok: true;
     outcomes: ParticipantRunOutcome[] | undefined;
-    failFastReason: string | undefined;
     receiving: CommsReceivingRun | undefined;
     receivingWarnings: string[];
     externalCommsWarnings: string[];

package/dist/routes/computer-use/live-phase.js

@@ -94,17 +94,16 @@ export async function runStudyParticipants(setup, participants) {
     }
     // Run the participants (dry-run runs none). In-process is always one.
     let outcomes;
-    let failFastReason;
     try {
         if (!dryRun)
-            ({ outcomes, failFastReason } = await runAllCuaParticipants(participantRuns, {
+            outcomes = await runAllCuaParticipants(participantRuns, {
                 ...deps,
                 // A session that throws returns no trace; the run still records that it started.
                 runSession: (options) => {
                     run.participantStarted();
                     return deps.runSession(options);
                 },
-            }, participantPlan, inProcess));
+            }, participantPlan, inProcess);
     }
     finally {
         try {
@@ -130,7 +129,6 @@ export async function runStudyParticipants(setup, participants) {
     return {
         ok: true,
         outcomes,
-        failFastReason,
         receiving,
         receivingWarnings,
         externalCommsWarnings,

package/dist/routes/computer-use/participant-execution.d.ts

@@ -12,28 +12,22 @@ export declare function makeParticipantWriteScreenshot(artifactRoot: PreparedOut
 export declare function runCuaParticipant(spec: DesktopParticipantRun, deps: CuaParticipantDeps): Promise<ParticipantRunOutcome>;
 /**
  * Run N>1 E2B participants on the study's schedule (runOnSchedule: each at its start offset, at
- * most `concurrency` at once), behind the pipeline gate when the subject is set up in each sandbox,
- * and session fail-fast on harness errors only (queued participants become `blocked` with a pinned
- * reason + a fail-fast event; mission verdicts never trip it). A participant that stops before its
- * session has failed on its own and trips no fail-fast. A closed gate or a fail-fast ends every
- * wait for a later start at once. Each participant tears down its own sandbox by id; nothing here
- * ever enumerates.
+ * most `concurrency` at once), behind the pipeline gate when the subject is set up in each sandbox.
+ * A harness error ends only its own participant: one desktop's stall or one provider failure does
+ * not predict the next participant's, so the schedule goes on. Only a closed gate ends every wait
+ * for a later start at once, and the participants it skips are `blocked` with its reason. Each
+ * participant tears down its own sandbox by id; nothing here ever enumerates.
  *
  * Exported for the total-runner tests: the injectable runner lets a test make one participant
  * throw (the exact class the guard exists for) without a live sandbox. Production always uses
  * the default.
  */
-export declare function runCuaParticipants(runs: DesktopParticipantRun[], deps: Omit<CuaParticipantDeps, "signalReady">, concurrency: number, runParticipant?: typeof runCuaParticipant): Promise<{
-    outcomes: ParticipantRunOutcome[];
-    failFastReason?: string;
-}>;
+export declare function runCuaParticipants(runs: DesktopParticipantRun[], deps: Omit<CuaParticipantDeps, "signalReady">, concurrency: number, runParticipant?: typeof runCuaParticipant): Promise<ParticipantRunOutcome[]>;
 /** Project one participant outcome (or a dry-run contract spec) into the public CuaParticipantResult. */
 export declare function toParticipantResult(spec: DesktopParticipantRun, outcome: ParticipantRunOutcome | undefined, subject: RunSubjectProvenance, dryRun: boolean): CuaParticipantResult;
 /**
  * Run every participant of a live run. The in-process route drives its single participant in this
- * process; one hosted participant runs alone; a fan-out runs at the plan's concurrency and may stop early.
+ * process; one hosted participant runs alone; a fan-out runs at the plan's concurrency, and stops
+ * early only when the pipeline gate closes.
  */
-export declare function runAllCuaParticipants(runs: readonly DesktopParticipantRun[], deps: Omit<CuaParticipantDeps, "signalReady">, participantPlan: CuaParticipantPlan, inProcess: boolean): Promise<{
-    outcomes: ParticipantRunOutcome[];
-    failFastReason: string | undefined;
-}>;
+export declare function runAllCuaParticipants(runs: readonly DesktopParticipantRun[], deps: Omit<CuaParticipantDeps, "signalReady">, participantPlan: CuaParticipantPlan, inProcess: boolean): Promise<ParticipantRunOutcome[]>;

package/dist/routes/computer-use/participant-execution.js

@@ -1,3 +1,4 @@
+import { scheduledParticipantDeps } from "./participant-runs.js";
 import { judgeParticipantRecords } from "../../run/judge.js";
 import { createE2BParticipantDesktop } from "./e2b-desktop/desktop.js";
 import { createInProcessDesktop } from "./in-process-desktop.js";
@@ -31,7 +32,7 @@ export function makeParticipantWriteScreenshot(artifactRoot, spec, screenshots)
         return rel;
     };
 }
-/** A blocked participant outcome (pipeline gate / fail-fast skipped it before it ran). */
+/** A blocked participant outcome: the pipeline gate or the study budget skipped it. */
 function skippedOutcome(spec, reason, arrival) {
     return {
         spec,
@@ -110,8 +111,8 @@ export async function runCuaParticipant(spec, deps) {
     if (session)
         await recordParticipantTrace(spec, deps, session, warnings);
     const { noEngagement, selfReportedBlocker, reportedFriction } = judgeParticipantSession(session, deps, warnings);
-    // A provider-cleanup or provider-policy failure still trips fail-fast and counts in the
-    // participant summary's harness errors.
+    // A provider-cleanup or provider-policy failure counts in the participant summary's harness
+    // errors.
     const harnessError = sessionError !== undefined ||
         providerCleanupError !== undefined ||
         providerPolicyError !== undefined ||
@@ -191,33 +192,26 @@ function pipelineGate(open, onClose) {
 }
 /**
  * Run N>1 E2B participants on the study's schedule (runOnSchedule: each at its start offset, at
- * most `concurrency` at once), behind the pipeline gate when the subject is set up in each sandbox,
- * and session fail-fast on harness errors only (queued participants become `blocked` with a pinned
- * reason + a fail-fast event; mission verdicts never trip it). A participant that stops before its
- * session has failed on its own and trips no fail-fast. A closed gate or a fail-fast ends every
- * wait for a later start at once. Each participant tears down its own sandbox by id; nothing here
- * ever enumerates.
+ * most `concurrency` at once), behind the pipeline gate when the subject is set up in each sandbox.
+ * A harness error ends only its own participant: one desktop's stall or one provider failure does
+ * not predict the next participant's, so the schedule goes on. Only a closed gate ends every wait
+ * for a later start at once, and the participants it skips are `blocked` with its reason. Each
+ * participant tears down its own sandbox by id; nothing here ever enumerates.
  *
  * Exported for the total-runner tests: the injectable runner lets a test make one participant
  * throw (the exact class the guard exists for) without a live sandbox. Production always uses
  * the default.
  */
 export async function runCuaParticipants(runs, deps, concurrency, runParticipant = runCuaParticipant) {
-    const failFast = { tripped: false, reason: "" };
     const stopping = new AbortController();
     // An app-url subject is only opened, so one participant's start says nothing about another's.
     const gate = pipelineGate(deps.subject.kind === "app-url", () => stopping.abort());
-    const outcomes = await runOnSchedule(runs, {
+    return runOnSchedule(runs, {
         startAfterMs: (spec) => spec.planned.startAfterMs,
         slots: concurrency,
         now: deps.now,
         signal: stopping.signal,
     }, async (spec, _index, { scheduledAt }) => {
-        if (failFast.tripped) {
-            return skippedOutcome(spec, `skipped: ${failFast.reason}`, { scheduledAt });
-        }
-        // A participant trips fail-fast only after the gate opened, or as it closes the gate, so no
-        // participant is still waiting at the gate when fail-fast skips the rest.
         const id = spec.planned.id;
         if ((await gate.enter(id)) === "closed") {
             return skippedOutcome(spec, `skipped: participant ${gate.holder()} failed to provision its world (pipeline gate)`, { scheduledAt });
@@ -233,6 +227,7 @@ export async function runCuaParticipants(runs, deps, concurrency, runParticipant
         try {
             outcome = await runParticipant(spec, {
                 ...deps,
+                ...scheduledParticipantDeps(spec.planned, deps, scheduledAt),
                 signalReady: () => {
                     ready = true;
                     gate.ready();
@@ -258,23 +253,17 @@ export async function runCuaParticipants(runs, deps, concurrency, runParticipant
                 endedAt: deps.now(),
             };
         }
-        // A participant that stopped before its session failed on its own and trips no fail-fast.
-        // Without a desktop it says nothing about the subject, so the next participant starts first.
-        // A runner that threw is a harness defect: it closes the gate and trips fail-fast.
+        // A participant that stopped before its session without a desktop says nothing about the
+        // subject, so the next participant starts first. A runner that threw is a harness defect: it
+        // closes the gate.
         if (!ready)
             gate.failed(id, { handOver: !threw && outcome.sandboxId === undefined });
-        if (outcome.harnessError && (ready || threw) && !failFast.tripped) {
-            failFast.tripped = true;
-            failFast.reason = `a prior participant (${outcome.spec.planned.id}) ended in a harness error (fail-fast)`;
-            stopping.abort();
-        }
         // A participant the study budget skipped never requested its desktop.
         return {
             ...outcome,
             arrival: outcome.skippedReason === undefined ? arrival : { scheduledAt },
         };
     });
-    return { outcomes, ...(failFast.tripped ? { failFastReason: failFast.reason } : {}) };
 }
 /** Project one participant outcome (or a dry-run contract spec) into the public CuaParticipantResult. */
 export function toParticipantResult(spec, outcome, subject, dryRun) {
@@ -369,19 +358,21 @@ export function toParticipantResult(spec, outcome, subject, dryRun) {
 }
 /**
  * Run every participant of a live run. The in-process route drives its single participant in this
- * process; one hosted participant runs alone; a fan-out runs at the plan's concurrency and may stop early.
+ * process; one hosted participant runs alone; a fan-out runs at the plan's concurrency, and stops
+ * early only when the pipeline gate closes.
  */
 export async function runAllCuaParticipants(runs, deps, participantPlan, inProcess) {
+    // A participant that runs alone starts with the run.
+    const alone = { ...deps, ...scheduledParticipantDeps(runs[0].planned, deps, deps.now()) };
     if (inProcess) {
         // The caller's executor stands in for a desktop, and the shared runner drives the participant.
         const outcome = await runCuaParticipant(runs[0], {
-            ...deps,
+            ...alone,
             createDesktop: () => createInProcessDesktop(deps),
         });
-        return { outcomes: [outcome], failFastReason: undefined };
+        return [outcome];
     }
     if (runs.length === 1)
-        return { outcomes: [await runCuaParticipant(runs[0], deps)], failFastReason: undefined };
-    const ran = await runCuaParticipants([...runs], deps, participantPlan.concurrency);
-    return { outcomes: ran.outcomes, failFastReason: ran.failFastReason };
+        return [await runCuaParticipant(runs[0], alone)];
+    return runCuaParticipants([...runs], deps, participantPlan.concurrency);
 }

package/dist/routes/computer-use/participant-model.js

@@ -99,6 +99,7 @@ export function participantSessionOptions(spec, deps, ready, provider, writeScre
             : spec.instructions,
         persona: spec.persona,
         timeoutMs: deps.timeoutMs,
+        ...participantClock(spec.planned.limits.timeZone, deps),
         // The brain is either a keyed API client or a CLI the operator is already signed in to.
         // Everything below this line (loop, executor, trace, affordances) is identical either
         // way, which is what makes a local-agent run comparable to an API one.
@@ -305,3 +306,19 @@ export function makeCuaRunBudget(maxTotalUsd) {
         },
     };
 }
+/**
+ * The participant's clock: its time zone, and its scheduled end on the run's clock. A participant
+ * with an end runs its session on the run's clock, so the end and the schedule read one clock.
+ */
+function participantClock(timeZone, deps) {
+    const { scheduledEnd } = deps;
+    if (timeZone === undefined && scheduledEnd === undefined)
+        return {};
+    return {
+        clock: {
+            ...(timeZone === undefined ? {} : { timeZone }),
+            ...(scheduledEnd === undefined ? {} : { end: scheduledEnd }),
+        },
+        ...(scheduledEnd === undefined ? {} : { now: deps.now }),
+    };
+}

package/dist/routes/computer-use/participant-runs.d.ts

@@ -3,7 +3,8 @@ import { type StudyConfig } from "../../study/types.js";
 import { type ResolvedPersona } from "../../study/persona.js";
 import { type RunRerunLineage } from "../../run/bundle.js";
 import type { PreparedSelectedOutputDirectory } from "../../run/contained-output.js";
-import { type CuaActorStudyErrorCode, type CuaParticipantPlan, type CuaParticipantPlanEntry, type DesktopParticipantRun, type ParticipantRunsAndPlan } from "./types.js";
+import { type CuaActorStudyErrorCode, type CuaParticipantDeps, type CuaParticipantPlan, type CuaParticipantPlanEntry, type DesktopParticipantRun, type ParticipantRunsAndPlan } from "./types.js";
+import { type ParticipantWindow } from "../../study/arrivals.js";
 /**
  * The session budget of a study that declares no execution.timeoutMs. On a provisioned route it is
  * what the `ceilingMs` sandbox ceiling leaves after provisioning, seeding and the teardown buffer.
@@ -16,6 +17,15 @@ export declare function defaultSessionTimeoutMs(config: StudyConfig, ceilingMs:
  *  git clone for an upload+extract, but the shared install/build/state/start/probe pipeline
  *  costs the same wall-clock room either way. */
 export declare function resolveParticipantSandboxMs(config: StudyConfig, ceilingMs: number): number;
+/**
+ * The deps one participant runs with once its start comes: its own session budget and sandbox
+ * deadline, and with a declared end, that end on the run's clock (`scheduledAt` is when it was
+ * due, from runOnSchedule).
+ */
+export declare function scheduledParticipantDeps(participant: ParticipantWindow, deps: {
+    readonly timeoutMs: number;
+    readonly sandboxMs: number;
+}, scheduledAt: number): Pick<CuaParticipantDeps, "timeoutMs" | "sandboxMs" | "scheduledEnd">;
 /**
  * The in-flight participant bound a study declares. Defaults to the participant count: every
  * declared participant runs at once, because a throttle nobody asked for silently turns "N actors

package/dist/routes/computer-use/participant-runs.js

@@ -18,7 +18,7 @@ import { composeParticipantInstructions, DEFAULT_MISSION } from "./participant-p
 import { resolveCuaRerunSelection } from "./rerun-selection.js";
 import { plural } from "../../run/text.js";
 import { formatDuration } from "../../run/projection.js";
-import { describeArrivals, planArrivals } from "../../study/arrivals.js";
+import { describeArrivals, participantSessionMs, planArrivals, scheduledEndAt, } from "../../study/arrivals.js";
 /**
  * The session budget of a study that declares no execution.timeoutMs. On a provisioned route it is
  * what the `ceilingMs` sandbox ceiling leaves after provisioning, seeding and the teardown buffer.
@@ -45,6 +45,30 @@ export function resolveParticipantSandboxMs(config, ceilingMs) {
         timeoutMs +
             sandboxHeadroomMs(provisionedRoute ? { seed: config.subject.state?.seed ?? [] } : undefined));
 }
+/**
+ * A participant's own session budget and sandbox deadline: the study's, or with a declared end its
+ * window plus room for the closing report (participantSessionMs), with the same setup and
+ * teardown headroom the study's sandbox has over its session.
+ */
+function participantWindow(participant, study) {
+    const timeoutMs = participantSessionMs(participant, study.sessionBudgetMs);
+    return { timeoutMs, sandboxMs: study.sandboxMs - study.sessionBudgetMs + timeoutMs };
+}
+/**
+ * The deps one participant runs with once its start comes: its own session budget and sandbox
+ * deadline, and with a declared end, that end on the run's clock (`scheduledAt` is when it was
+ * due, from runOnSchedule).
+ */
+export function scheduledParticipantDeps(participant, deps, scheduledAt) {
+    const end = scheduledEndAt(participant, scheduledAt);
+    return {
+        ...participantWindow(participant, {
+            sessionBudgetMs: deps.timeoutMs,
+            sandboxMs: deps.sandboxMs,
+        }),
+        ...(end === undefined ? {} : { scheduledEnd: end }),
+    };
+}
 /**
  * The in-flight participant bound a study declares. Defaults to the participant count: every
  * declared participant runs at once, because a throttle nobody asked for silently turns "N actors
@@ -114,10 +138,11 @@ export function participantRunsAndPlan(plan, opts = {}) {
     });
     const resolved = envLoweredConcurrency(plan.concurrency, participantCount, env);
     const concurrency = resolved.bound;
-    const { sessionBudgetMs, sandboxMs } = plan;
+    const { sessionBudgetMs } = plan;
     const schedule = resolved.envLoweredFrom === undefined
         ? plan.arrivals
-        : planArrivals(participants.map((participant) => participant.startAfterMs), { slots: concurrency, sessionMs: sessionBudgetMs });
+        : planArrivals(participants.map((participant) => participant.startAfterMs), { slots: concurrency, sessionMs: sessionBudgetMs }, participants.map((participant) => participantSessionMs(participant, sessionBudgetMs)));
+    const sandboxesMs = participants.reduce((sum, participant) => sum + participantWindow(participant, plan).sandboxMs, 0);
     const participantPlan = {
         strategy: CUA_FANOUT_STRATEGY,
         laneCount: participantCount,
@@ -127,7 +152,7 @@ export function participantRunsAndPlan(plan, opts = {}) {
             : { envLoweredConcurrencyFrom: resolved.envLoweredFrom }),
         waves: Math.ceil(participantCount / concurrency),
         perLaneSessionBudgetMs: sessionBudgetMs,
-        worstCaseSandboxMinutes: Math.round((participantCount * sandboxMs) / 60_000),
+        worstCaseSandboxMinutes: Math.round(sandboxesMs / 60_000),
         ...(schedule.declared ? { schedule } : {}),
         dryRun: plan.dryRun,
         lanes: runs.map((spec) => ({
@@ -158,6 +183,7 @@ export function participantRunsAndPlan(plan, opts = {}) {
             ...(spec.planned.startAfterMs === undefined
                 ? {}
                 : { startAfterMs: spec.planned.startAfterMs }),
+            ...(spec.planned.endAfterMs === undefined ? {} : { endAfterMs: spec.planned.endAfterMs }),
         })),
     };
     return { runs, participantPlan };
@@ -182,6 +208,7 @@ export function formatParticipantPlanEntry(entry) {
         entry.caseGroup ? `case=${entry.caseGroup}` : undefined,
         entry.reasoningEffort ? `effort=${entry.reasoningEffort}` : undefined,
         entry.startAfterMs === undefined ? undefined : `start=+${formatDuration(entry.startAfterMs)}`,
+        entry.endAfterMs === undefined ? undefined : `end=+${formatDuration(entry.endAfterMs)}`,
     ].filter((part) => part !== undefined);
     return `${entry.id}: persona=${entry.persona}${taxonomy.length > 0 ? ` ${taxonomy.join(" ")}` : ""} device=${entry.device} ${entry.resolution[0]}x${entry.resolution[1]} prompt#${entry.instructionDigest}${entry.targetDigest ? ` target#${entry.targetDigest}` : ""}`;
 }

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

@@ -9,7 +9,7 @@ import { studyUrlCredentialReason } from "../../study/url-credentials.js";
 import { subjectStateInvalidReason } from "../../study/parse/subject-state.js";
 import { brainOf, callerBrainOf, planCaps, desktopRequirements, planBase, provisionedSubject, } from "../../study/plan-base.js";
 import { computerUseParticipants, declaredTargets } from "../../study/plan-participants.js";
-import { planStarts } from "../../study/arrivals.js";
+import { planStarts, windowDeadlineRefusal } from "../../study/arrivals.js";
 import { computerUseParticipantCount, participantCountReason } from "../../study/routing.js";
 import { cloneTargetValidationReason, computerUseValidationReason, desktopMediaValidationReason, outputTokenLimitValidationReason, receivingEmailValidationReason, taskProtocolValidationReason, waitLimitValidationReason, } from "../../study/validation.js";
 import { desktopCliProductReason } from "../../study/composition-rules.js";
@@ -209,6 +209,13 @@ function startsOf(config, runner, limit, ceilingMs) {
     if (!atOnce.ok)
         return atOnce;
     const sessionMs = config.execution?.timeoutMs ?? defaultSessionTimeoutMs(config, ceilingMs);
+    // A participant with a declared end gets a sandbox sized from its own window.
+    if (runner.desktop === "e2b-desktop") {
+        const headroomMs = resolveParticipantSandboxMs(config, ceilingMs) - sessionMs;
+        const window = windowDeadlineRefusal(runner.participants, { sessionMs, headroomMs }, ceilingMs);
+        if (window !== undefined)
+            return { ok: false, message: window };
+    }
     const slots = { slots: atOnce.count, sessionMs };
     return {
         ok: true,

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

@@ -201,7 +201,7 @@ export async function finishCuaRun(setup, finish, ran) {
     const appUrl = plannedAppUrl(plan.runner.subject);
     const { runId } = run;
     const participantCount = participantRuns.length;
-    const { outcomes, failFastReason, receiving, receivingWarnings, externalCommsWarnings } = ran;
+    const { outcomes, receiving, receivingWarnings, externalCommsWarnings } = ran;
     // Per-participant subject projections.
     const subjects = projectParticipantSubjects({ ...subjectArgs, outcomes, dryRun });
     const aggregate = aggregateCuaSubject({ subjects, outcomes, participantCount, dryRun });
@@ -222,7 +222,6 @@ export async function finishCuaRun(setup, finish, ran) {
         outcomes,
         subjects,
         aggregateSubject,
-        ...(failFastReason === undefined ? {} : { failFastReason }),
         ...(hostSuspension === undefined ? {} : { hostSuspension }),
     });
     const adapterWarnings = [];