humanish 0.125.0 → 0.126.0

package/dist/study/arrivals.d.ts

@@ -8,41 +8,58 @@ export declare const LATEST_START_AFTER_MS: number;
 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. */
+/**
+ * A participant's declared window: when it starts, and when it ends on the run's clock
+ * (`endAfterMs`) or at the latest after its own session started (`maxSessionMs`).
+ */
 export interface ParticipantWindow {
     readonly id?: string;
     readonly startAfterMs?: number;
     readonly endAfterMs?: number;
+    readonly maxSessionMs?: 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]".
+ * milliseconds up to 24 hours, one at or before its start, a cap that is not a whole number of
+ * milliseconds from 1 to 24 hours, a cap beside an end, or a wind-down that is not a whole number
+ * of milliseconds or has neither. `path` names the entry, as in "participants[1]".
  */
 export declare function windowReason(entry: {
     readonly id?: string;
     readonly startAfterMs?: number;
     readonly endAfterMs?: unknown;
+    readonly maxSessionMs?: 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`.
+ * A participant's session budget: with a declared end, its window plus SCHEDULED_END_ROOM_MS, and
+ * with a cap, the cap plus the same room, 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.
+ * When a participant's session ends: at a time on the run's clock, or at the latest a time after
+ * its own session starts, which the route reads when the session starts.
  */
-export declare function scheduledEndAt(participant: ParticipantWindow, scheduledAt: number): {
+export type ParticipantEnd = {
+    readonly kind: "scheduled_end";
     readonly atMs: number;
     readonly windDownMs: number;
-} | undefined;
+} | {
+    readonly kind: "session_cap";
+    readonly afterMs: number;
+    readonly windDownMs: number;
+};
+/**
+ * How a participant that was due at `scheduledAt` (runOnSchedule's ScheduledStart) ends, or
+ * undefined when it declares neither an end nor a cap. A participant that waited for a slot still
+ * ends at its declared time, and still gets its whole cap.
+ */
+export declare function participantEnd(participant: ParticipantWindow, scheduledAt: number): ParticipantEnd | 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
+ * Why the sandbox of the first participant whose window or cap 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: {
@@ -50,8 +67,9 @@ export declare function windowDeadlineRefusal(participants: readonly Participant
     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.
+ * Each participant's window for `study check`, when any participant declares an end or a cap: when
+ * it starts and ends and when it is first told the time left, when it starts and its cap and how
+ * far into its session 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`. */

package/dist/study/arrivals.js

@@ -32,13 +32,18 @@ export const DEFAULT_WIND_DOWN_MS = 10 * 60_000;
 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]".
+ * milliseconds up to 24 hours, one at or before its start, a cap that is not a whole number of
+ * milliseconds from 1 to 24 hours, a cap beside an end, or a wind-down that is not a whole number
+ * of milliseconds or has neither. `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.`;
+    const { endAfterMs, maxSessionMs, windDownMs } = entry;
+    if (maxSessionMs !== undefined && endAfterMs !== undefined)
+        return `${path} sets both endAfterMs and maxSessionMs. endAfterMs holds the participant until a set time, and maxSessionMs lets it end its session sooner, up to a cap, so a participant takes one of them. Keep endAfterMs for one that stays until a set time, or maxSessionMs for one that may leave when it is done.`;
+    if (maxSessionMs !== undefined && !(isStartAfterMs(maxSessionMs) && maxSessionMs > 0))
+        return `${path}.maxSessionMs must be a whole number of milliseconds from 1 to ${LATEST_START_AFTER_MS} (24 hours): the longest the participant's session lasts, counted from its start.`;
+    if (windDownMs !== undefined && endAfterMs === undefined && maxSessionMs === undefined)
+        return `${path}.windDownMs is how long before its endAfterMs or maxSessionMs a participant is told the time left, so it needs one of them. Add an 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)
@@ -53,54 +58,75 @@ export function windowReason(entry, path) {
     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`.
+ * A participant's session budget: with a declared end, its window plus SCHEDULED_END_ROOM_MS, and
+ * with a cap, the cap plus the same room, in place of the study's `sessionMs` (execution.timeoutMs
+ * or its default); else `sessionMs`.
  */
 export function participantSessionMs(participant, sessionMs) {
+    const windowMs = declaredWindowMs(participant);
+    return windowMs === undefined ? sessionMs : windowMs + SCHEDULED_END_ROOM_MS;
+}
+/** How long a participant with a declared end or cap may work, or undefined without either. */
+function declaredWindowMs(participant) {
+    if (participant.maxSessionMs !== undefined)
+        return participant.maxSessionMs;
     if (participant.endAfterMs === undefined)
-        return sessionMs;
-    return participant.endAfterMs - (participant.startAfterMs ?? 0) + SCHEDULED_END_ROOM_MS;
+        return undefined;
+    return participant.endAfterMs - (participant.startAfterMs ?? 0);
 }
 /**
- * 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.
+ * How a participant that was due at `scheduledAt` (runOnSchedule's ScheduledStart) ends, or
+ * undefined when it declares neither an end nor a cap. A participant that waited for a slot still
+ * ends at its declared time, and still gets its whole cap.
  */
-export function scheduledEndAt(participant, scheduledAt) {
+export function participantEnd(participant, scheduledAt) {
+    const windDownMs = participant.windDownMs ?? DEFAULT_WIND_DOWN_MS;
+    if (participant.maxSessionMs !== undefined)
+        return { kind: "session_cap", afterMs: participant.maxSessionMs, windDownMs };
     if (participant.endAfterMs === undefined)
         return undefined;
     return {
+        kind: "scheduled_end",
         atMs: scheduledAt - (participant.startAfterMs ?? 0) + participant.endAfterMs,
-        windDownMs: participant.windDownMs ?? DEFAULT_WIND_DOWN_MS,
+        windDownMs,
     };
 }
 /**
- * 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
+ * Why the sandbox of the first participant whose window or cap 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)
+        if (declaredWindowMs(participant) === 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)}`;
+        const works = participant.maxSessionMs === undefined
+            ? `works from +${formatDuration(participant.startAfterMs ?? 0)} to +${formatDuration(participant.endAfterMs ?? 0)}`
+            : `may work for up to ${formatDuration(participant.maxSessionMs)}`;
+        const window = participant.maxSessionMs === undefined ? "window" : "cap";
+        return `${name} ${works}, 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.
+ * Each participant's window for `study check`, when any participant declares an end or a cap: when
+ * it starts and ends and when it is first told the time left, when it starts and its cap and how
+ * far into its session 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))
+    if (!participants.some((participant) => declaredWindowMs(participant) !== undefined))
         return undefined;
     const windows = participants.map((participant) => {
         const start = `${participant.id ?? "participant"} from +${formatDuration(participant.startAfterMs ?? 0)}`;
+        if (participant.maxSessionMs !== undefined) {
+            const told = Math.max(0, participant.maxSessionMs - (participant.windDownMs ?? DEFAULT_WIND_DOWN_MS));
+            return `${start} until it ends itself or for up to ${formatDuration(participant.maxSessionMs)}, told the time left from ${formatDuration(told)} into its session`;
+        }
         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));

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

@@ -1,8 +1,9 @@
 import type { DwellWindow } from "../actors/stop-conditions.js";
-/** One participant as the plan has it: when it starts and ends, and its dwell window. */
+/** One participant as the plan has it: when it starts and ends, its cap, and its dwell window. */
 export interface EstimatedParticipant {
     readonly startAfterMs?: number;
     readonly endAfterMs?: number;
+    readonly maxSessionMs?: number;
     readonly limits: {
         readonly dwell?: DwellWindow;
     };
@@ -33,10 +34,10 @@ export interface BundleEstimate {
 }
 /**
  * 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.
+ * declares an end or a cap. A participant with an end works its whole window; one without ends
+ * itself, so it is counted for the measured open session above, or its budget (its cap, else
+ * `sessionMs`) 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;
 /**

package/dist/study/bundle-estimate.js

@@ -48,26 +48,31 @@ const RATES = Object.freeze({
 const MIB = 1024 * 1024;
 /**
  * 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.
+ * declares an end or a cap. A participant with an end works its whole window; one without ends
+ * itself, so it is counted for the measured open session above, or its budget (its cap, else
+ * `sessionMs`) 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 function estimateBundle(participants, sessionMs) {
     let turns = 0;
     let frames = 0;
     let longestWindowMs = 0;
-    const openMs = Math.min(sessionMs, RATES.openSessionMs);
+    // The longest any participant without an end is counted, for the messages.
+    let openMs = Math.min(sessionMs, RATES.openSessionMs);
     for (const participant of participants) {
         const windowMs = participant.endAfterMs === undefined
             ? undefined
             : participant.endAfterMs - (participant.startAfterMs ?? 0);
+        const budgetMs = windowMs ?? participant.maxSessionMs ?? sessionMs;
+        const countedMs = windowMs ?? Math.min(budgetMs, RATES.openSessionMs);
         if (windowMs !== undefined)
             longestWindowMs = Math.max(longestWindowMs, windowMs);
-        turns += Math.ceil((windowMs ?? openMs) / (RATES.secondsPerTurn * 1000));
+        else
+            openMs = Math.max(openMs, countedMs);
+        turns += Math.ceil(countedMs / (RATES.secondsPerTurn * 1000));
         const dwell = participant.limits.dwell;
         if (dwell !== undefined)
-            frames += Math.floor(Math.min(dwell.ms, windowMs ?? sessionMs) / dwell.everyMs) + 1;
+            frames += Math.floor(Math.min(dwell.ms, budgetMs) / dwell.everyMs) + 1;
     }
     const count = participants.length;
     const runFileBytes = RATES.runBytes +

package/dist/study/desktop-files.d.ts

@@ -0,0 +1,37 @@
+import type { StudyParseFailure, StudyParticipantFile } from "./types.js";
+/**
+ * Where `participants[].files` act: the hosted desktop of an independent computer-use participant.
+ * The parser's unread-field check and the route planners give this reason.
+ */
+export declare const DESKTOP_FILES_ROUTE_REASON = "files are copied onto a hosted computer-use desktop; needs route: computer-use with execution.target: e2b-desktop";
+/** A participant's `files` list: each entry's `from` and `as`. */
+export declare function parseParticipantFiles(raw: unknown, field: string): {
+    ok: true;
+    value: StudyParticipantFile[] | undefined;
+} | StudyParseFailure;
+/** One file read on this machine for a participant's desktop. */
+export interface DesktopFile {
+    /** Where it lands, relative to the desktop user's home folder. */
+    readonly as: string;
+    /** The file's bytes, shared by every participant that receives it and uploaded as they are. */
+    readonly data: ArrayBuffer;
+    readonly size: number;
+    /** The sha256 of `data`, 64 hex characters. */
+    readonly sha256: string;
+}
+type DesktopFilesRead = {
+    readonly ok: true;
+    readonly files: ReadonlyMap<string, readonly DesktopFile[]>;
+} | {
+    readonly ok: false;
+    readonly message: string;
+};
+/**
+ * Read every participant's declared files from `folder`, the folder that holds the study file, and
+ * return them by participant id. Runs before any sandbox exists, so a refusal costs nothing.
+ */
+export declare function readDesktopFiles(folder: string, participants: readonly {
+    readonly id: string;
+    readonly files?: readonly StudyParticipantFile[];
+}[]): Promise<DesktopFilesRead>;
+export {};

package/dist/study/desktop-files.js

@@ -0,0 +1,174 @@
+// Files a participant's hosted desktop receives before it starts (`participants[].files`), so a
+// browser upload dialog can find them. The parser checks the declared paths; readDesktopFiles reads
+// the files from the study's folder on this machine before any sandbox exists.
+import { createHash } from "node:crypto";
+import { stat } from "node:fs/promises";
+import path from "node:path";
+import { scanEncodedText } from "../evidence/encoded-text.js";
+import { prepareSelectedOutputDirectory, readContainedRegularFile, } from "../run/contained-output.js";
+import { isRecord } from "../run/type-guards.js";
+import { isLocalTreeDenylisted } from "../subject/local-tree-archive.js";
+import { SUBJECT_DIR } from "../subject/steps.js";
+import { invalid, str } from "./parse/values.js";
+/**
+ * Where `participants[].files` act: the hosted desktop of an independent computer-use participant.
+ * The parser's unread-field check and the route planners give this reason.
+ */
+export const DESKTOP_FILES_ROUTE_REASON = "files are copied onto a hosted computer-use desktop; needs route: computer-use with execution.target: e2b-desktop";
+/** The most files one participant's desktop receives. */
+const MAX_FILES = 20;
+/** A participant's `files` list: each entry's `from` and `as`. */
+export function parseParticipantFiles(raw, field) {
+    if (raw === undefined)
+        return { ok: true, value: undefined };
+    const listReason = `\`${field}\` must be a list of 1 to ${MAX_FILES} { from, as } entries, one per file the participant's desktop receives.`;
+    if (!Array.isArray(raw) || raw.length === 0 || raw.length > MAX_FILES)
+        return invalid(listReason);
+    const files = [];
+    for (const [index, entry] of raw.entries()) {
+        const at = `${field}[${index}]`;
+        const from = isRecord(entry) ? str(entry.from) : undefined;
+        const as = isRecord(entry) ? str(entry.as) : undefined;
+        if (from === undefined || as === undefined)
+            return invalid(listReason);
+        if (!isPlainRelativePath(from))
+            return invalid(`\`${at}.from\` must be a path inside the folder that holds the study file, written relative to it, such as fixtures/insurance-card.png, with / between folders and no empty, . or .. part.`);
+        if (isLocalTreeDenylisted(from))
+            return invalid(`\`${at}.from\` names a file humanish keeps on this machine: a .env file, a key, a credential file, or one under .git, node_modules or .humanish. The local-tree archive leaves the same files out. Copy a synthetic file instead.`);
+        if (!isPlainRelativePath(as) || as.startsWith("~"))
+            return invalid(`\`${at}.as\` must be a path relative to the desktop user's home folder, such as Downloads/insurance-card.png, with / between folders, no empty, . or .. part, and no leading ~.`);
+        if (isHumanishDesktopPath(as))
+            return invalid(`\`${at}.as\` is a path humanish uses on the desktop: ${SUBJECT_FOLDER}/ holds the cloned or unpacked app, and names that start with .humanish are humanish's own files. Pick another path, such as Downloads/insurance-card.png.`);
+        // The run records `as`, and redacting it would record a different path. Encoded text the
+        // public-safety scan cannot read would leave run.json unscanned.
+        const scanned = scanEncodedText(as);
+        if (scanned.sensitive || scanned.opaque)
+            return invalid(`\`${at}.as\` looks like a secret, a local path or encoded text, and the run records it. Name the file plainly, such as Downloads/insurance-card.png.`);
+        const clash = files.find((earlier) => earlier.as === as || as.startsWith(`${earlier.as}/`) || earlier.as.startsWith(`${as}/`));
+        if (clash !== undefined)
+            return invalid(clash.as === as
+                ? `\`${at}.as\` names ${as}, which another file in this list already uses. Give each file its own path.`
+                : `\`${at}.as\` names ${as}, and another file in this list uses ${clash.as}, so one would have to be both a file and a folder. Give each file its own path.`);
+        files.push({ from, as });
+    }
+    return { ok: true, value: files };
+}
+/** The subject's folder under the sandbox user's home, where a clone or local tree is put. */
+const SUBJECT_FOLDER = path.posix.relative("/home/user", SUBJECT_DIR);
+/**
+ * Whether `as` lands where humanish puts its own files: the subject's folder, which provisioning
+ * replaces, or a name starting with .humanish, such as the local-tree archive.
+ */
+function isHumanishDesktopPath(as) {
+    const first = as.split("/")[0] ?? "";
+    return first === SUBJECT_FOLDER || first.startsWith(".humanish");
+}
+/**
+ * A relative path of plain names joined by `/`. A backslash is refused because the desktop is
+ * Linux, where it is part of a name, and on Windows it would be a separator.
+ */
+function isPlainRelativePath(value) {
+    if (value.includes("\0") || value.includes("\\") || value.startsWith("/"))
+        return false;
+    return value.split("/").every((part) => part !== "" && part !== "." && part !== "..");
+}
+const MIB = 1024 * 1024;
+/** The most bytes humanish copies for one file. */
+const FILE_MAX_BYTES = 10 * MIB;
+/** The most bytes one participant's desktop receives, a file counted each time it is placed. */
+const PARTICIPANT_MAX_BYTES = 25 * MIB;
+/** The most bytes of distinct files a study names: humanish holds them in memory for the run. */
+const STUDY_MAX_BYTES = 100 * MIB;
+/**
+ * Read every participant's declared files from `folder`, the folder that holds the study file, and
+ * return them by participant id. Runs before any sandbox exists, so a refusal costs nothing.
+ */
+export async function readDesktopFiles(folder, participants) {
+    // A library caller's config skips the parser, so its rules run again here.
+    for (const participant of participants) {
+        const checked = parseParticipantFiles(participant.files, `Participant ${participant.id}'s files`);
+        if (!checked.ok)
+            return { ok: false, message: checked.error.message };
+    }
+    const files = new Map();
+    if (!participants.some((participant) => participant.files !== undefined))
+        return { ok: true, files };
+    const root = await bindFolder(folder);
+    if (root === undefined)
+        return {
+            ok: false,
+            message: "The folder that holds the study file could not be read as a folder, so its participants' files cannot be copied. Run the study from its file, with the folder in place.",
+        };
+    // One read per distinct `from`: a group of participants shares one file's bytes.
+    const sources = new Map();
+    let studyBytes = 0;
+    for (const participant of participants) {
+        const placed = [];
+        let participantBytes = 0;
+        for (const [index, file] of (participant.files ?? []).entries()) {
+            let source = sources.get(file.from);
+            if (source === undefined) {
+                // A file past what the study has left is refused unread, so memory stays under the total.
+                const left = STUDY_MAX_BYTES - studyBytes;
+                const read = await readContainedRegularFile(root, file.from, Math.min(FILE_MAX_BYTES, left));
+                if (read.status === "refused" && read.reason === "too-large" && left < FILE_MAX_BYTES)
+                    return {
+                        ok: false,
+                        message: `The files this study's participants receive total more than ${STUDY_MAX_BYTES / MIB} MiB, the most humanish holds in memory for one run. Use smaller files, or give more participants the same file.`,
+                    };
+                if (read.status !== "read")
+                    return {
+                        ok: false,
+                        message: `Participant ${participant.id}'s files[${index}].from, ${file.from}, ${unreadReason(read)}. Paths in from are relative to the folder that holds the study file.`,
+                    };
+                const sha256 = createHash("sha256").update(read.bytes).digest("hex");
+                source = { data: new Uint8Array(read.bytes).buffer, size: read.bytes.length, sha256 };
+                sources.set(file.from, source);
+                studyBytes += source.size;
+            }
+            participantBytes += source.size;
+            if (participantBytes > PARTICIPANT_MAX_BYTES)
+                return {
+                    ok: false,
+                    message: `Participant ${participant.id}'s files total more than ${PARTICIPANT_MAX_BYTES / MIB} MiB, the most humanish copies onto one desktop. Use smaller or fewer files.`,
+                };
+            placed.push({ as: file.as, ...source });
+        }
+        if (placed.length > 0)
+            files.set(participant.id, placed);
+    }
+    return { ok: true, files };
+}
+/**
+ * The study's folder as a contained-read root, or undefined when it is not an existing folder.
+ * prepareSelectedOutputDirectory would create a missing one.
+ */
+async function bindFolder(folder) {
+    try {
+        if (!(await stat(folder)).isDirectory())
+            return undefined;
+        return await prepareSelectedOutputDirectory(folder, folder);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Why a `from` could not be read, as a clause after its path. */
+function unreadReason(read) {
+    if (read.status === "missing")
+        return "does not exist in the folder that holds the study file";
+    switch (read.reason) {
+        case "too-large":
+            return `is larger than ${FILE_MAX_BYTES / MIB} MiB, the most humanish copies for one file`;
+        case "directory":
+            return "is a folder; name a file";
+        case "not-regular":
+            return "is a symbolic link, a hard link or another kind of file humanish does not copy; put a plain copy of the file in the folder";
+        case "unsafe-path":
+            return "leaves the folder that holds the study file or passes through a symbolic link; put a plain copy of the file in the folder";
+        case "changed":
+            return "changed while humanish read it; run the study again";
+        case "unreadable":
+            return "could not be read; check its permissions";
+    }
+}

package/dist/study/keys.d.ts

@@ -16,12 +16,20 @@ export declare const PARTICIPANT_ENTRY: {
     device: true;
     instruction: true;
     target: true;
+    files: {
+        from: true;
+        as: true;
+    };
     entry: true;
     host: true;
     startAfterMs: true;
     endAfterMs: true;
+    maxSessionMs: true;
     windDownMs: true;
     idleWaitMs: true;
+    clock: {
+        timeZone: true;
+    };
     reasoningEffort: true;
     stopWhen: {
         any: {

package/dist/study/keys.js

@@ -37,12 +37,15 @@ export const PARTICIPANT_ENTRY = {
     device: true,
     instruction: true,
     target: true,
+    files: { from: true, as: true },
     entry: true,
     host: true,
     startAfterMs: true,
     endAfterMs: true,
+    maxSessionMs: true,
     windDownMs: true,
     idleWaitMs: true,
+    clock: { timeZone: true },
     reasoningEffort: true,
     stopWhen: STOP_WHEN,
     dwell: DWELL,

package/dist/study/migrate/v2.js

@@ -80,6 +80,16 @@ export function movedV2KeyReason(raw) {
     }
     return undefined;
 }
+// Participant keys that arrived after v2, so a v2 participant cannot carry them.
+const AFTER_V2_PARTICIPANT_KEYS = [
+    "startAfterMs",
+    "endAfterMs",
+    "windDownMs",
+    "idleWaitMs",
+    "files",
+    "maxSessionMs",
+    "clock",
+];
 // The keys of a humanish.lab.v2 file, in the order its parser listed them: the v3 sections with
 // `subject.topology`, the actor list with its participant keys, `execution.caps`, `personas` and
 // the `scenario` object.
@@ -92,11 +102,10 @@ const V2_KEYS = {
     actors: {
         type: true,
         count: true,
-        // The participant's window and idle wait arrived after v2, so a v2 participant cannot carry them.
-        lanes: without(PARTICIPANT_ENTRY, "startAfterMs", "endAfterMs", "windDownMs", "idleWaitMs"),
+        lanes: without(PARTICIPANT_ENTRY, ...AFTER_V2_PARTICIPANT_KEYS),
         // Roster groups are participants with a count; the parser expanded them into `lanes[]`.
         roster: {
-            ...without(PARTICIPANT_ENTRY, "startAfterMs", "endAfterMs", "windDownMs", "idleWaitMs"),
+            ...without(PARTICIPANT_ENTRY, ...AFTER_V2_PARTICIPANT_KEYS),
             count: true,
         },
         // maxWaitMs, idleWaitMs and clock arrived after v2, so a v2 file cannot carry them.

package/dist/study/parse/actors.d.ts

@@ -25,7 +25,7 @@ export interface ParticipantPaths {
  * Parse a participant list into a fan-out roster (computer-use E2B route): `participants` in a
  * study, `actors[0].lanes` in the v2 file migrate reads, each named in messages by `paths`.
  * Structural only: each entry is `{ id?, actorType?, surface?, caseGroup?, persona?, device?,
- * instruction?, target?, entry?, host?, startAfterMs?, endAfterMs?, windDownMs?, idleWaitMs?, reasoningEffort?, stopWhen?, dwell? }`.
+ * instruction?, target?, entry?, host?, startAfterMs?, endAfterMs?, windDownMs?, idleWaitMs?, maxSessionMs?, clock?, reasoningEffort?, stopWhen?, dwell?, files? }`.
  * Participant ids (when declared) must be public-safe path tokens and unique; grouping metadata
  * must be public-safe tokens; a device must be a known preset name. The
  * route-scoped cross-validation (device XOR raw resolution, targets, the participant bound) runs in parseStudy