humanish 0.125.0 → 0.127.0

package/dist/study/bundle-estimate.js

@@ -1,46 +1,85 @@
 // How large a computer-use run's bundle grows, estimated from its plan before anything runs, and
-// whether it would pass a limit a later command holds it to: analysis reads a run.json of at most
-// EVIDENCE_LIMITS.sourceBytes, verify reads no file larger than RUN_ARTIFACT_MAX_BYTES, and the
-// public-safety scan visits at most runEntryLimit(participants) files and folders.
+// whether it would pass a limit a later command holds it to: analysis reads run.json and each
+// participant's trace up to EVIDENCE_LIMITS.sourceBytes each, verify reads no file larger than
+// RUN_ARTIFACT_MAX_BYTES, and the public-safety scan visits at most runEntryLimit(participants)
+// files and folders.
+//
+// observer/index.html carries every participant's items gzipped, so with busy participants it can
+// pass verify's 32 MiB before run.json passes analysis's 16 MiB: at these rates, 17 participants
+// working 8 hours. observer-data.json carries the same per-request lists as run.json and was within
+// 7 % of its size on every live run measured, so it passes 32 MiB only after run.json passes
+// 16 MiB, and the estimate does not check it.
 import { EVIDENCE_LIMITS } from "../analysis/analysis-limits.js";
 import { RUN_ARTIFACT_MAX_BYTES } from "../run/contained-output.js";
 import { formatDuration } from "../run/projection.js";
 import { plural } from "../run/text.js";
 import { runEntryLimit } from "../verify/scan-limit.js";
-// Measured on 2026-10-12. Live: the hosted computer-use bundles kept on the maintainer's machine,
-// 219 runs since 2026-10-01 for run.json's size (a least-squares fit gave 372 bytes a run, 14,368
-// a participant and 2,423 a turn), and for the pace the 42 participant sessions of 5 minutes or
-// more among every kept run since August. Synthetic: runStudyWith on fake desktops, with the live median
-// of about 270 characters of reasoning and message a turn, from 10 to 2,000 turns and from 1 to
-// 16 participants. An adopter's 39-minute run grew run.json about 7 KB a minute for a participant
-// working the whole window; these rates give 12.6 KB, so the estimate errs high, and a limit it
-// passes is a warning.
+// Measured on 2026-10-13 on run bundle v3. Live: the 7 finished hosted computer-use runs kept from
+// the 0.125.0 smoke test and the 2026-10-12 live checks, 10 participants with 1 to 28 turns and 137
+// model requests. Dry: runs of 1, 2, 24 and 100 participants, for the Observer app and the run's
+// own files. Pace, session length and screenshots: the live computer-use runs kept on the
+// maintainer's machine. A trace's rate a turn on the public site/public/runs/lobby-0927 run
+// (8 participants, 20 to 78 turns) was 1,579 bytes plus 91 for the page, under the live fit.
 const RATES = Object.freeze({
-    /** run.json bytes a minute of the one long live participant measured: the adopter's run. */
-    measuredLongRunBytesPerMinute: 7_000,
-    /** run.json bytes for the run itself: its header, study and scenario. */
-    runBytes: 400,
-    /** run.json bytes for each participant before its turns: its records, events and cost lines. */
-    participantBytes: 14_400,
-    /** run.json bytes a model turn adds. Synthetic: 2,094 to 2,125 a turn over 10 to 2,000 turns. */
-    turnBytes: 2_100,
-    /** run.json bytes a dwell frame adds. Synthetic: 6,247 for 10 frames and the frame after. */
-    frameBytes: 570,
-    /** Seconds between model turns: the median of the 42 long live sessions was 10.3. */
+    /** run.json bytes for the run itself: its header, study, review and cost. Live fit: 4,381. */
+    runBytes: 4_400,
+    /**
+     * run.json bytes for each participant before its turns: its stream, actor summary and closing
+     * report request. Live fit: 16,239, plus one request.
+     */
+    participantBytes: 16_500,
+    /**
+     * run.json bytes a model turn adds: the request's entries in `tokenUsage.turns` and
+     * `conversation.requests`. Live: 30,623 bytes over 137 requests, 223.5 each.
+     */
+    turnRunBytes: 225,
+    /** A trace file's bytes before its turns: the actor summary. Live fit: 5,378. */
+    participantTraceBytes: 5_400,
+    /**
+     * Trace bytes a model turn adds: its items, its screenshot entry and its request's usage, plus 91
+     * for the `page` each screenshot item now carries. Live fit: 1,965 a turn. Participants with 4
+     * or more turns ranged from 1,140 to 4,532; the busiest made 311 items in 15 turns, most of them
+     * UI actions. Analysis refuses the whole run when one trace passes its limit, so each trace is
+     * counted at the busiest participant's rate.
+     */
+    turnTraceBytes: 4_700,
+    /**
+     * Trace bytes a dwell frame adds: 395 for its item and entry on the kept runs with dwell frames,
+     * plus 91 for the page.
+     */
+    frameTraceBytes: 500,
+    /**
+     * Seconds between model turns: the median of the 27 of 185 kept live participants that worked 5
+     * minutes or more was 10.4.
+     */
     secondsPerTurn: 10,
     /**
      * How long a participant with no declared end is counted, at most its session budget. It ends
-     * when it finishes its mission: 90 % of 974 live sessions ended within 184 s.
+     * when it finishes its mission: 90 % of 974 kept sessions ended within 184 s on 2026-10-12; of
+     * the 197 kept on 2026-10-13, 64 % ended within 180 s and 90 % within 325 s. Counting 325 s would
+     * add under 0.4 MiB to the run.json of 100 participants.
      */
     openSessionMs: 3 * 60_000,
-    /** observer-data.json bytes beyond run.json's for each participant: 0.9 to 2.6 KB live. */
-    observerDataParticipantBytes: 2_600,
-    /** observer/index.html: the page, and a share of run.json it embeds (synthetic, 10 to 2,000 turns). */
-    observerPageBytes: 1_190_000,
-    observerPageShare: 0.62,
-    /** A desktop screenshot: the median of 249 live PNG frames was 108,565 bytes. */
+    /** observer/index.html's app before any run data: 1,199,831 bytes on the dry runs. */
+    observerAppBytes: 1_200_000,
+    /**
+     * The page's compact copy of observer-data.json, as a share of run.json: 0.64 to 0.81 whole on
+     * the live runs, 0.49 for a participant's part, and 0.42 for the per-request entries.
+     */
+    observerPageDataShare: 0.5,
+    /**
+     * The page's gzipped base64 items, as a share of all the traces' bytes: 0.087 to 0.114 on the
+     * live runs of two participants, 0.097 for the busiest participant alone (about 475 bytes a
+     * turn), 0.142 to 0.184 on runs of one participant and 4 to 11 turns, and 0.095 on 0.124.0's
+     * synthetic 8-hour run.
+     */
+    observerPageItemsShare: 0.12,
+    /** A desktop screenshot: the median of 3,990 kept live PNG frames was 107,895 bytes. */
     screenshotBytes: 110_000,
-    /** Run files and folders besides the participants': run.json, status, review, events, receipts, the Observer, analysis. */
+    /**
+     * Run files and folders besides the participants': 10 on a dry run, and live the sandbox
+     * receipts, `actors/` and an analysis's 9.
+     */
     runEntries: 20,
     /** A participant's entries besides its turn screenshots: its trace file, its screenshot folder, its first frame. */
     participantEntries: 3,
@@ -48,48 +87,61 @@ 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 traces = 0;
+    let largestTrace = 0;
     let longestWindowMs = 0;
-    const openMs = Math.min(sessionMs, RATES.openSessionMs);
-    for (const participant of participants) {
-        const windowMs = participant.endAfterMs === undefined
-            ? undefined
-            : participant.endAfterMs - (participant.startAfterMs ?? 0);
-        if (windowMs !== undefined)
-            longestWindowMs = Math.max(longestWindowMs, windowMs);
-        turns += Math.ceil((windowMs ?? openMs) / (RATES.secondsPerTurn * 1000));
-        const dwell = participant.limits.dwell;
-        if (dwell !== undefined)
-            frames += Math.floor(Math.min(dwell.ms, windowMs ?? sessionMs) / dwell.everyMs) + 1;
+    // The longest any participant without an end is counted, for the messages.
+    let openMs = Math.min(sessionMs, RATES.openSessionMs);
+    let scheduled = 0;
+    for (const { schedule, limits } of participants) {
+        const { end } = schedule;
+        const budgetMs = end?.windowMs ?? sessionMs;
+        let countedMs;
+        if (end?.kind === "scheduled_end") {
+            scheduled += 1;
+            countedMs = end.windowMs;
+            longestWindowMs = Math.max(longestWindowMs, countedMs);
+        }
+        else {
+            countedMs = Math.min(budgetMs, RATES.openSessionMs);
+            openMs = Math.max(openMs, countedMs);
+        }
+        const own = Math.ceil(countedMs / (RATES.secondsPerTurn * 1000));
+        const dwell = limits.dwell;
+        const ownFrames = dwell === undefined ? 0 : Math.floor(Math.min(dwell.ms, budgetMs) / dwell.everyMs) + 1;
+        const trace = RATES.participantTraceBytes + own * RATES.turnTraceBytes + ownFrames * RATES.frameTraceBytes;
+        turns += own;
+        frames += ownFrames;
+        traces += trace;
+        largestTrace = Math.max(largestTrace, trace);
     }
     const count = participants.length;
-    const runFileBytes = RATES.runBytes +
-        count * RATES.participantBytes +
-        turns * RATES.turnBytes +
-        frames * RATES.frameBytes;
-    const observerDataBytes = runFileBytes + count * RATES.observerDataParticipantBytes;
-    const pageBytes = RATES.observerPageBytes + Math.round(RATES.observerPageShare * runFileBytes);
+    const runFileBytes = RATES.runBytes + count * RATES.participantBytes + turns * RATES.turnRunBytes;
     const screenshots = count + turns + frames;
-    const scheduled = participants.filter((participant) => participant.endAfterMs !== undefined);
+    const observerPageBytes = Math.round(RATES.observerAppBytes +
+        RATES.observerPageDataShare * runFileBytes +
+        RATES.observerPageItemsShare * traces);
     return {
         runFileBytes,
-        largestFileBytes: Math.max(observerDataBytes, pageBytes),
-        // Each participant's trace file holds about what its stream holds in run.json.
-        totalBytes: 2 * runFileBytes + observerDataBytes + pageBytes + screenshots * RATES.screenshotBytes,
+        largestTraceBytes: largestTrace,
+        observerPageBytes,
+        // observer-data.json is about run.json's size.
+        totalBytes: observerPageBytes + screenshots * RATES.screenshotBytes + traces + 2 * runFileBytes,
         entries: RATES.runEntries + count * RATES.participantEntries + turns + frames,
         entryLimit: runEntryLimit(count),
         basis: {
             participants: count,
-            scheduled: scheduled.length,
+            scheduled,
             longestWindowMs,
-            open: count - scheduled.length,
+            open: count - scheduled,
             openMs,
             dwell: frames > 0,
         },
@@ -97,23 +149,31 @@ export function estimateBundle(participants, sessionMs) {
 }
 /**
  * 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.
+ * estimate counted, and what to change.
  */
 export function bundleLimitReason(estimate) {
+    const runFile = estimate.runFileBytes > EVIDENCE_LIMITS.sourceBytes;
+    const page = estimate.observerPageBytes > RUN_ARTIFACT_MAX_BYTES;
+    const entries = estimate.entries > estimate.entryLimit;
     const passed = [
-        ...(estimate.runFileBytes > EVIDENCE_LIMITS.sourceBytes
+        ...(runFile
             ? [
                 `This study's run.json may grow to about ${mib(estimate.runFileBytes)}, past the ${mib(EVIDENCE_LIMITS.sourceBytes)} analysis reads.`,
             ]
             : []),
-        ...(estimate.largestFileBytes > RUN_ARTIFACT_MAX_BYTES
+        ...(estimate.largestTraceBytes > EVIDENCE_LIMITS.sourceBytes
+            ? [
+                `One participant's trace may grow to about ${mib(estimate.largestTraceBytes)}, past the ${mib(EVIDENCE_LIMITS.sourceBytes)} analysis reads of each trace.`,
+            ]
+            : []),
+        ...(page
             ? [
-                `Its largest file, observer/observer-data.json, may grow to about ${mib(estimate.largestFileBytes)}, past the ${mib(RUN_ARTIFACT_MAX_BYTES)} verify reads in one file.`,
+                `The Observer page, observer/index.html, may grow to about ${mib(estimate.observerPageBytes)}, past the ${mib(RUN_ARTIFACT_MAX_BYTES)} verify reads in one file.`,
             ]
             : []),
-        ...(estimate.entries > estimate.entryLimit
+        ...(entries
             ? [
-                `It may hold about ${count(estimate.entries)} files and folders, past the ${count(estimate.entryLimit)} the public-safety scan reads in a run of ${plural(estimate.basis.participants, "participant")}.`,
+                `The run may hold about ${count(estimate.entries)} files and folders, past the ${count(estimate.entryLimit)} the public-safety scan reads in a run of ${plural(estimate.basis.participants, "participant")}.`,
             ]
             : []),
     ];
@@ -123,7 +183,7 @@ export function bundleLimitReason(estimate) {
     const counted = [
         ...(scheduled > 0
             ? [
-                `${plural(scheduled, "participant")} working their declared windows of up to ${formatDuration(longestWindowMs)}`,
+                `${plural(scheduled, "participant")} working ${scheduled === 1 ? "a declared window" : "declared windows"} of up to ${formatDuration(longestWindowMs)}`,
             ]
             : []),
         ...(open > 0
@@ -136,23 +196,29 @@ export function bundleLimitReason(estimate) {
         ...(scheduled > 0 ? ["shorten the longest windows (participants[].endAfterMs)"] : []),
         ...(dwell ? ["shorten the dwell window (dwell.ms) or capture less often (dwell.everyMs)"] : []),
     ];
-    const split = "split the participants across studies";
-    const advice = changes.length === 0 ? split : `${changes.join(", ")}, or ${split}`;
-    const perMinute = (RATES.turnBytes * 60) / RATES.secondsPerTurn;
+    // A trace is one participant's, so splitting the study helps only the run's own files.
+    if (runFile || page || entries || changes.length === 0)
+        changes.push("split the participants across studies");
+    const advice = changes.length < 2
+        ? changes.join("")
+        : `${changes.slice(0, -1).join(", ")}, or ${changes.at(-1)}`;
     return [
         ...passed,
-        `The estimate counts ${counted.join(" and ")}, at a model turn every ${formatDuration(RATES.secondsPerTurn * 1000)} that adds about ${(RATES.turnBytes / 1000).toFixed(1)} KB.`,
-        `It runs high, about ${(perMinute / RATES.measuredLongRunBytesPerMinute).toFixed(1)} times the one long live run measured, so the run goes ahead.`,
-        `To stay under the limit, ${advice}.`,
+        `The estimate counts ${counted.join(" and ")}, at a model turn every ${formatDuration(RATES.secondsPerTurn * 1000)} that adds about ${RATES.turnRunBytes} bytes to run.json and up to ${(RATES.turnTraceBytes / 1000).toFixed(1)} KB to the participant's trace.`,
+        "The run goes ahead.",
+        `To stay under ${passed.length === 1 ? "the limit" : "the limits"}, ${advice}.`,
     ].join(" ");
 }
 /** The estimate beside the limits, for `study check`. */
 export function describeBundle(estimate) {
-    return `run.json about ${mib(estimate.runFileBytes)} of the ${mib(EVIDENCE_LIMITS.sourceBytes)} analysis reads; largest file about ${mib(estimate.largestFileBytes)} of the ${mib(RUN_ARTIFACT_MAX_BYTES)} verify reads; about ${count(estimate.entries)} files and folders of the ${count(estimate.entryLimit)} the public-safety scan reads; about ${mib(estimate.totalBytes, 0)} in all. Participants with a declared end are counted for their whole window and the others for up to ${formatDuration(estimate.basis.openMs)}, at a model turn every ${formatDuration(RATES.secondsPerTurn * 1000)}.`;
+    return `run.json about ${mib(estimate.runFileBytes)} of the ${mib(EVIDENCE_LIMITS.sourceBytes)} analysis reads; largest trace about ${mib(estimate.largestTraceBytes)} of the ${mib(EVIDENCE_LIMITS.sourceBytes)} analysis reads of each; Observer page about ${mib(estimate.observerPageBytes)} of the ${mib(RUN_ARTIFACT_MAX_BYTES)} verify reads; about ${count(estimate.entries)} files and folders of the ${count(estimate.entryLimit)} the public-safety scan reads; about ${mib(estimate.totalBytes, 0)} in all. Participants with a declared end are counted for their whole window and the others for up to ${formatDuration(estimate.basis.openMs)}, at a model turn every ${formatDuration(RATES.secondsPerTurn * 1000)}.`;
 }
+/** Bytes in MiB to `digits` places, or two under 0.1 MiB, so a short study's trace does not read 0.0. */
 function mib(bytes, digits = 1) {
     const value = bytes / MIB;
-    return `${Number.isInteger(value) ? value : value.toFixed(digits)} MiB`;
+    if (Number.isInteger(value))
+        return `${value} MiB`;
+    return `${value.toFixed(value < 0.1 ? 2 : digits)} MiB`;
 }
 function count(value) {
     return value.toLocaleString("en-US");

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/photo.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/photo.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/photo.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/photo.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