humanish 0.121.0 → 0.123.0

package/dist/run/stream-trace.js

@@ -0,0 +1,260 @@
+// Where a participant's trace lives. A v1 run.json holds every stream's trace items and screenshot
+// entries inline. From v2 the run writer moves them into one file per stream and leaves an index
+// in run.json, so run.json stays a summary whatever the length of the sessions. Every reader that
+// needs the items loads them here, which accepts both versions and checks a file against its index.
+import { createHash } from "node:crypto";
+import { RUN_BUNDLE_SCHEMA } from "./bundle.js";
+import { readContainedRegularFile, refusalText, RUN_ARTIFACT_MAX_BYTES, } from "./contained-output.js";
+import { isRunStreamArtifact, isStreamTraceIndex, isStreamTracePath } from "./stream-shape.js";
+import { isRecord } from "./type-guards.js";
+/** A trace that does not match its index, or cannot be read. The message names the stream. */
+export class StreamTraceRefusedError extends Error {
+    streamId;
+    constructor(streamId, detail) {
+        super(`Participant ${streamId}'s trace was not read: ${detail}. A trace file must stay as the run wrote it; restore the run folder from a copy.`);
+        this.streamId = streamId;
+        this.name = "StreamTraceRefusedError";
+    }
+}
+const sha256 = (bytes) => createHash("sha256").update(bytes).digest("hex");
+const isScreenshot = (artifact) => artifact.kind === "screenshot";
+/**
+ * The file a trace path names on any file system. Trace file names are ASCII (isStreamTracePath),
+ * so lower case folds them as a case-insensitive file system does: actors/Case.json and
+ * actors/case.json are one file there.
+ */
+const traceFileKey = (tracePath) => tracePath.toLowerCase();
+/** Names of the form actors/<n>.json, which the splitter gives by position and never reuses. */
+const POSITION_TRACE_FILE = /^actors\/\d+\.json$/;
+/**
+ * The stream's actor trace artifact (actor.json, actors/<stream>.json, actor-<surface>.json) when
+ * no earlier stream claimed it (compared by traceFileKey), else actors/<position>.json. The
+ * position names are a namespace of their own: an artifact named that way is not reused, so two
+ * streams never get one file. Another trace artifact (the scripted route's traces/<surface>.json
+ * holds its native step trace) keeps its own file.
+ */
+function tracePath(stream, index, claimed) {
+    const own = stream.artifacts.find((artifact) => artifact.kind === "trace" &&
+        isStreamTracePath(artifact.path) &&
+        !POSITION_TRACE_FILE.test(artifact.path))?.path;
+    return own !== undefined && !claimed.has(traceFileKey(own)) ? own : `actors/${index + 1}.json`;
+}
+/**
+ * The run.json the run writes, and the trace files it writes first. Each stream with a finished
+ * actor keeps that actor without `items`, its artifacts other than screenshots, and an index of its
+ * trace file; the file is the actor trace with the stream's screenshot entries as `artifacts`. A
+ * stream already split (its actor read back from a v2 run.json without its items) keeps its index,
+ * since its file is on disk.
+ */
+export function splitStreamTraces(bundle) {
+    const files = [];
+    const claimed = new Set();
+    for (const stream of bundle.streams)
+        if (stream.trace)
+            claimed.add(traceFileKey(stream.trace.path));
+    const streams = bundle.streams.map((stream, index) => {
+        const actor = stream.actor;
+        if (actor === undefined || !Array.isArray(actor.items))
+            return stream;
+        const { trace: _previous, ...rest } = stream;
+        const filePath = tracePath(rest, index, claimed);
+        // Only a stream already split that moved position can hold this stream's position name.
+        if (claimed.has(traceFileKey(filePath)))
+            throw new Error(`Two participants' traces would both be written to ${filePath}.`);
+        claimed.add(traceFileKey(filePath));
+        const screenshots = stream.artifacts.filter(isScreenshot);
+        const bytes = Buffer.from(`${JSON.stringify({ ...actor, artifacts: screenshots }, null, 2)}\n`);
+        files.push({ path: filePath, bytes });
+        const { items, ...summary } = actor;
+        return {
+            ...rest,
+            // run.json's actor is the summary: every field of the trace except its items.
+            actor: summary,
+            artifacts: stream.artifacts.filter((artifact) => !isScreenshot(artifact)),
+            trace: {
+                path: filePath,
+                bytes: bytes.length,
+                sha256: sha256(bytes),
+                items: items.length,
+                screenshots: screenshots.length,
+            },
+        };
+    });
+    return { bundle: { ...bundle, schema: RUN_BUNDLE_SCHEMA, streams }, files };
+}
+function containedReader(runPaths) {
+    return async (relativePath, maxBytes) => {
+        const read = await readContainedRegularFile(runPaths, relativePath, maxBytes);
+        if (read.status === "missing")
+            return { refused: `${relativePath} is missing` };
+        if (read.status === "refused")
+            return { refused: refusalText(relativePath, read) };
+        return { bytes: read.bytes };
+    };
+}
+/**
+ * The stream from the bytes of its trace file: its actor with the file's items, and its artifacts
+ * followed by the file's screenshot entries, without the index.
+ */
+function joinTrace(stream, bytes) {
+    const index = stream.trace;
+    const refuse = (detail) => {
+        throw new StreamTraceRefusedError(stream.id, detail);
+    };
+    if (bytes.length !== index.bytes)
+        refuse(`${index.path} holds ${bytes.length} bytes and run.json records ${index.bytes} bytes`);
+    if (sha256(bytes) !== index.sha256)
+        refuse(`${index.path} does not match the sha256 run.json records for it`);
+    let value;
+    try {
+        value = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+    }
+    catch {
+        refuse(`${index.path} is not JSON`);
+    }
+    if (!isRecord(value) || !Array.isArray(value.items) || !Array.isArray(value.artifacts))
+        return refuse(`${index.path} has no items or artifacts list`);
+    const artifacts = value.artifacts;
+    if (!artifacts.every((artifact) => isRunStreamArtifact(artifact) && isScreenshot(artifact)))
+        refuse(`${index.path} lists an artifact that is not a screenshot entry`);
+    if (value.items.length !== index.items || artifacts.length !== index.screenshots)
+        refuse(`${index.path} holds ${value.items.length} items and ${artifacts.length} screenshots and run.json records ${index.items} and ${index.screenshots}`);
+    const { trace: _index, ...rest } = stream;
+    return {
+        ...rest,
+        actor: { ...stream.actor, items: value.items },
+        artifacts: [...stream.artifacts, ...artifacts],
+    };
+}
+/** Refuses an index the shape check would refuse, naming a file that is not a trace file name. */
+function assertIndex(stream) {
+    const index = stream.trace;
+    if (isRecord(index) && typeof index.path === "string" && !isStreamTracePath(index.path))
+        throw new StreamTraceRefusedError(stream.id, `run.json indexes ${index.path}, which is not a trace file name (actor.json, actors/<stream>.json or actor-<surface>.json)`);
+    if (!isStreamTraceIndex(index) || stream.actor === undefined)
+        throw new StreamTraceRefusedError(stream.id, "run.json records a malformed trace index");
+    if (stream.actor.items !== undefined)
+        throw new StreamTraceRefusedError(stream.id, "run.json holds items beside its trace index");
+}
+/** The stream with its trace joined, and the bytes it was joined from when it has an index. */
+async function readStreamTrace(read, stream, maxBytes) {
+    if (stream.trace === undefined)
+        return { stream };
+    assertIndex(stream);
+    const file = await read(stream.trace.path, maxBytes);
+    if ("refused" in file)
+        throw new StreamTraceRefusedError(stream.id, file.refused);
+    return { stream: joinTrace(stream, file.bytes), bytes: file.bytes };
+}
+/**
+ * The stream as a v1 run.json held it: its actor with every item and every artifact entry. A
+ * stream without an index is returned as it is (a v1 stream, or one with no actor). An indexed
+ * stream's file must have a trace file name (isStreamTracePath); it is read under `maxBytes` and
+ * checked against the index's byte count, sha256, item count and screenshot count, and any
+ * difference throws StreamTraceRefusedError. The rules that need the whole bundle (an unindexed v2
+ * actor, two participants indexing one file) are loadStreamTraces'.
+ */
+export async function loadStreamTrace(runPaths, stream, maxBytes = RUN_ARTIFACT_MAX_BYTES) {
+    return (await readStreamTrace(containedReader(runPaths), stream, maxBytes)).stream;
+}
+/**
+ * Why a stream of this bundle cannot be read, before any file is. A trace file belongs to one
+ * participant, so every stream indexing a path another stream indexes, compared as a
+ * case-insensitive file system compares them, is refused. In v2 the writer
+ * indexes every actor on every write, mid-run flushes included, so a v2 actor without an index lost
+ * its trace file, and inline items never come from the writer. A run still writing carries its
+ * participants' items so far as `liveActor` (humanish.live-actor.v1), which no index binds; a
+ * run.json whose outcome says the run finished never does, since the final write replaces it.
+ */
+function bundleRefusal(bundle, stream, owners) {
+    const shared = isRecord(stream.trace)
+        ? owners.get(traceFileKey(String(stream.trace.path)))
+        : undefined;
+    if (shared !== undefined && shared.length > 1)
+        return `run.json indexes ${String(stream.trace.path)} for participants ${shared.join(", ")} (paths that differ only in case name one file on some file systems), and a trace file belongs to one participant`;
+    if (bundle.schema !== RUN_BUNDLE_SCHEMA)
+        return undefined;
+    if (stream.actor !== undefined && stream.trace === undefined)
+        return "run.json holds its actor and names no trace file";
+    if (stream.liveActor !== undefined && bundle.outcome?.state === "finished")
+        return "run.json records a finished run and still holds in-progress items";
+    return undefined;
+}
+/**
+ * Every stream of the bundle loaded through loadStreamTrace, one file at a time, and the refusal
+ * of each stream that could not be (see bundleRefusal for the rules that need the whole bundle).
+ * Each refused stream is kept as run.json holds it; a reader that shows the run passes the result
+ * to displayedTraces. `source` is the run's prepared paths, or a TraceFileReader. `onTrace`
+ * receives each trace file's path and the bytes the stream was joined from, after they matched
+ * the index, so a caller scans exactly what it reads.
+ */
+export async function loadStreamTraces(source, bundle, options = {}) {
+    const read = typeof source === "function" ? source : containedReader(source);
+    const owners = new Map();
+    for (const stream of bundle.streams)
+        if (isRecord(stream.trace)) {
+            const key = traceFileKey(String(stream.trace.path));
+            owners.set(key, [...(owners.get(key) ?? []), stream.id]);
+        }
+    const streams = [];
+    const refused = [];
+    for (const stream of bundle.streams) {
+        try {
+            const reason = bundleRefusal(bundle, stream, owners);
+            if (reason !== undefined)
+                throw new StreamTraceRefusedError(stream.id, reason);
+            const loaded = await readStreamTrace(read, stream, options.maxBytes ?? RUN_ARTIFACT_MAX_BYTES);
+            if (loaded.bytes !== undefined)
+                options.onTrace?.(stream.trace.path, loaded.bytes);
+            streams.push(loaded.stream);
+        }
+        catch (error) {
+            if (!(error instanceof StreamTraceRefusedError))
+                throw error;
+            refused.push(error);
+            streams.push(stream);
+        }
+    }
+    return { bundle: { ...bundle, streams }, refused };
+}
+/**
+ * A loaded bundle as a reader that shows a run presents it. A refused stream keeps run.json's
+ * summary, shows none of the items run.json or a file supplied for it (its actor's items, its
+ * in-progress items, its screenshot entries), and carries `traceUnavailable` with the reason; a
+ * warn event on its timeline says the same.
+ */
+export function displayedTraces(loaded) {
+    const reasons = new Map(loaded.refused.map((error) => [error.streamId, error.message]));
+    if (reasons.size === 0)
+        return loaded.bundle;
+    const streams = loaded.bundle.streams.map((stream) => {
+        const reason = reasons.get(stream.id);
+        if (reason === undefined)
+            return stream;
+        const { liveActor: _live, trace: _index, actor, ...rest } = stream;
+        return {
+            ...rest,
+            ...(actor === undefined ? {} : { actor: { ...actor, items: [] } }),
+            artifacts: stream.artifacts.filter((artifact) => !isScreenshot(artifact)),
+            traceUnavailable: reason,
+        };
+    });
+    const events = loaded.bundle.streams
+        .filter((stream) => reasons.has(stream.id))
+        .map((stream) => ({
+        id: `event-trace-unavailable-${stream.id}`,
+        at: stream.updatedAt,
+        level: "warn",
+        type: "trace.unavailable",
+        message: reasons.get(stream.id),
+        streamId: stream.id,
+    }));
+    return { ...loaded.bundle, streams, events: [...loaded.bundle.events, ...events] };
+}
+/** The bundle with every stream loaded; the first refusal throws. */
+export async function loadRunTraces(source, bundle, maxBytes) {
+    const loaded = await loadStreamTraces(source, bundle, maxBytes === undefined ? {} : { maxBytes });
+    if (loaded.refused[0])
+        throw loaded.refused[0];
+    return loaded.bundle;
+}

package/dist/run/streams.d.ts

@@ -142,6 +142,18 @@ export interface RunDesktopGeometry {
     /** Public-safe geometry measurement/fill warnings retained with the stream evidence. */
     warnings?: string[];
 }
+/**
+ * A stream's trace file in a v2 run.json: the actor trace with its items and the stream's
+ * screenshot entries as `artifacts`. `bytes` and `sha256` bind the file to run.json; `items` and
+ * `screenshots` are what it holds, so a reader can list them without opening it.
+ */
+export interface StreamTraceIndex {
+    path: string;
+    bytes: number;
+    sha256: string;
+    items: number;
+    screenshots: number;
+}
 /** The original participant-facing assignment, before runtime access/coordination details. */
 export interface RunParticipantAssignment {
     mission: string;
@@ -189,6 +201,12 @@ export interface RunStream {
      *  and never persisted into bundles; declared here because the served observer-data carries it
      *  and the client is typed against this contract. */
     liveEnded?: boolean;
+    /**
+     * Set by a reader that shows the run (displayedTraces in src/run/stream-trace.ts) when the loader
+     * refused this participant's trace: the reason. Runtime-only and never persisted; the stream then
+     * carries none of the refused items.
+     */
+    traceUnavailable?: string;
     /**
      * Browser CSS layout viewport. Deterministic browser adapters may declare and render this
      * exactly; hosted-desktop CUA producers set it only from a runtime measurement. Historical
@@ -234,6 +252,8 @@ export interface RunStream {
         turnId?: string;
     };
     actor?: ActorTrace;
+    /** Present in a v2 run.json on each stream with an actor: where its items and screenshots are. */
+    trace?: StreamTraceIndex;
     /**
      * Mid-run partial actor evidence: the redacted trace items recorded so far,
      * flushed while a live participant is still running so the attached Observer's timeline can

package/dist/study/arrivals.d.ts

@@ -6,6 +6,54 @@ import type { RunParticipantArrival } from "../run/bundle.js";
 export declare const LATEST_START_AFTER_MS: number;
 /** Whether `value` is a start offset humanish runs: whole milliseconds from 0 to 24 hours. */
 export declare function isStartAfterMs(value: unknown): value is number;
+/** How long before its end a participant is told the time left, unless it declares `windDownMs`. */
+export declare const DEFAULT_WIND_DOWN_MS: number;
+/** A participant's declared window: when it starts and when it ends, on the run's clock. */
+export interface ParticipantWindow {
+    readonly id?: string;
+    readonly startAfterMs?: number;
+    readonly endAfterMs?: number;
+    readonly windDownMs?: number;
+}
+/**
+ * Why a participant's declared end cannot run, or undefined: an end that is not a whole number of
+ * milliseconds up to 24 hours, one at or before its start, or a wind-down that is not a whole
+ * number of milliseconds or has no end. `path` names the entry, as in "participants[1]".
+ */
+export declare function windowReason(entry: {
+    readonly id?: string;
+    readonly startAfterMs?: number;
+    readonly endAfterMs?: unknown;
+    readonly windDownMs?: unknown;
+}, path: string): string | undefined;
+/**
+ * A participant's session budget: with a declared end, its window plus SCHEDULED_END_ROOM_MS in
+ * place of the study's `sessionMs` (execution.timeoutMs or its default); else `sessionMs`.
+ */
+export declare function participantSessionMs(participant: ParticipantWindow, sessionMs: number): number;
+/**
+ * When a participant that was due at `scheduledAt` (runOnSchedule's ScheduledStart) ends, on the
+ * same clock, or undefined when it declares no end. A participant that waited for a slot still ends
+ * at its declared time.
+ */
+export declare function scheduledEndAt(participant: ParticipantWindow, scheduledAt: number): {
+    readonly atMs: number;
+    readonly windDownMs: number;
+} | undefined;
+/**
+ * Why the sandbox of the first participant whose window passes `ceilingMs` cannot live that long,
+ * or undefined. Its deadline is its session (participantSessionMs) plus `headroomMs`, what the
+ * route adds to a session for setup and teardown (sandboxHeadroomMs).
+ */
+export declare function windowDeadlineRefusal(participants: readonly ParticipantWindow[], sandbox: {
+    readonly sessionMs: number;
+    readonly headroomMs: number;
+}, ceilingMs: number): string | undefined;
+/**
+ * Each participant's window for `study check`, when any participant declares an end: when it starts
+ * and ends and when it is first told the time left, or when it starts and its session budget.
+ */
+export declare function describeWindows(participants: readonly ParticipantWindow[], sessionMs: number): string | undefined;
 /** The refusal of a start offset that is not one, naming its `field`. */
 export declare function startAfterMessage(field: string): string;
 /**
@@ -49,9 +97,10 @@ export interface StartQueue {
  * The schedule a roster's declared offsets give under the queue (`undefined` is 0: the participant
  * starts with the run). Participants start in schedule order, by offset and then roster position,
  * each at its time or when a slot frees, whichever is later; this is the rule runOnSchedule
- * follows.
+ * follows. `sessionsMs` gives a participant with a declared end its own session budget
+ * (participantSessionMs); the others hold their slot for `queue.sessionMs`.
  */
-export declare function planArrivals(offsets: readonly (number | undefined)[], queue: StartQueue): ArrivalPlan;
+export declare function planArrivals(offsets: readonly (number | undefined)[], queue: StartQueue, sessionsMs?: readonly number[]): ArrivalPlan;
 /**
  * The plan's schedule, after a "schedule:" label: the first and last start, and how many run at
  * once at the most.
@@ -64,9 +113,7 @@ export declare function describeArrivals(arrivals: ArrivalPlan): string;
  * sandbox with servedScheduleRefusal. `lowered` is the warning that the E2B plan's limit runs the
  * roster in waves.
  */
-export declare function planStarts(participants: readonly {
-    readonly startAfterMs?: number;
-}[], queue: StartQueue, lowered: string | undefined): {
+export declare function planStarts(participants: readonly ParticipantWindow[], queue: StartQueue, lowered: string | undefined): {
     arrivals: ArrivalPlan;
     warnings: string[];
 };

package/dist/study/arrivals.js

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

package/dist/study/bundle-estimate.d.ts

@@ -0,0 +1,48 @@
+import type { DwellWindow } from "../actors/stop-conditions.js";
+/** One participant as the plan has it: when it starts and ends, and its dwell window. */
+export interface EstimatedParticipant {
+    readonly startAfterMs?: number;
+    readonly endAfterMs?: number;
+    readonly limits: {
+        readonly dwell?: DwellWindow;
+    };
+}
+/** A run's estimated bundle, and the scan's limit for its participants. */
+export interface BundleEstimate {
+    /** run.json, which analysis reads whole. */
+    readonly runFileBytes: number;
+    /** The largest file: observer/observer-data.json, or the Observer page for a small run. */
+    readonly largestFileBytes: number;
+    /** Every file, screenshots included. */
+    readonly totalBytes: number;
+    /** Files and folders in the run folder, as the public-safety scan counts them. */
+    readonly entries: number;
+    /** The most entries the scan reads in a run of these participants (runEntryLimit). */
+    readonly entryLimit: number;
+    /** What the estimate assumed, for its messages. */
+    readonly basis: {
+        readonly participants: number;
+        /** Participants with a declared end, counted for their whole window, and the longest window. */
+        readonly scheduled: number;
+        readonly longestWindowMs: number;
+        /** Participants without one, and how long each is counted at most. */
+        readonly open: number;
+        readonly openMs: number;
+        readonly dwell: boolean;
+    };
+}
+/**
+ * The bundle a live run of `participants` leaves, each in its session of `sessionMs` unless it
+ * declares an end. A participant with an end works its whole window; one without is counted for
+ * the measured open session above, or its budget when that is shorter. Each takes a model turn at
+ * the measured pace, and a dwell window adds a frame every `everyMs` for its length, cut to the
+ * session, and the frame after it.
+ */
+export declare function estimateBundle(participants: readonly EstimatedParticipant[], sessionMs: number): BundleEstimate;
+/**
+ * The warning for a run whose estimate passes a limit, or undefined: each limit it passes, what the
+ * estimate counted, how high it runs, and what to change.
+ */
+export declare function bundleLimitReason(estimate: BundleEstimate): string | undefined;
+/** The estimate beside the limits, for `study check`. */
+export declare function describeBundle(estimate: BundleEstimate): string;