humanish 0.124.0 → 0.126.0

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

package/dist/study/parse/actors.js

@@ -7,7 +7,10 @@ import { entryCredentialReason, urlCredentialReason } from "./url-credentials.js
 import { registeredComputerUseActors, registeredScriptedBrowserActors, registeredTerminalActors, } from "../routing.js";
 import { invalid, str } from "./values.js";
 import { isRecord } from "../../run/type-guards.js";
+import { scanEncodedText } from "../../evidence/encoded-text.js";
 import { isStartAfterMs, startAfterMessage, windowReason } from "../arrivals.js";
+import { parseParticipantFiles } from "../desktop-files.js";
+import { parseClock } from "./clock.js";
 // A participant id interpolates into its evidence paths (screenshots/<id>/, actors/<id>.json), so
 // it must be a public-safe path token, same shape as a study id.
 export const PARTICIPANT_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9_.-]*$/;
@@ -36,15 +39,29 @@ export function parseActorType(entry, path) {
     }
     return { ok: true, value: type };
 }
+/**
+ * A persona id. It names the persona file `humanish/personas/<id>.yaml`, and the run records it, so
+ * text verify would flag, as written or encoded, is refused here: redacting it would name a
+ * different file.
+ */
+function parsePersonaId(raw, path) {
+    const persona = str(raw);
+    if (persona !== undefined && scanEncodedText(persona).sensitive) {
+        return invalid(`\`${path}\` looks like a secret or a local path, and the run records it. A persona id names the persona file humanish/personas/<id>.yaml: use a plain file name such as skeptical-shopper, and put the persona's details in that file.`);
+    }
+    return { ok: true, value: persona };
+}
 /**
  * Every actor key other than `type`. The parser reads them after the participant entries, so a file
  * with errors in both reports the entry first.
  */
 export function parseActorFields(entry, path) {
     const actor = {};
-    const persona = str(entry.persona);
-    if (persona)
-        actor.persona = persona;
+    const persona = parsePersonaId(entry.persona, `${path}.persona`);
+    if (!persona.ok)
+        return persona;
+    if (persona.value !== undefined)
+        actor.persona = persona.value;
     const mission = str(entry.mission);
     if (mission)
         actor.mission = mission;
@@ -63,12 +80,11 @@ export function parseActorFields(entry, path) {
         actor.maxWaitMs = entry.maxWaitMs;
     if (typeof entry.idleWaitMs === "number")
         actor.idleWaitMs = entry.idleWaitMs;
-    if (entry.clock !== undefined) {
-        const timeZone = isRecord(entry.clock) ? entry.clock.timeZone : undefined;
-        if (typeof timeZone !== "string" || !isTimeZone(timeZone))
-            return invalid(`${path}.clock must be { timeZone }, with timeZone a time zone name such as "Europe/London": the participant's local time, which each turn tells it.`);
-        actor.clock = { timeZone };
-    }
+    const clock = parseClock(entry.clock, `${path}.clock`);
+    if (!clock.ok)
+        return clock;
+    if (clock.value !== undefined)
+        actor.clock = clock.value;
     const localAgent = str(entry.localAgent);
     if (entry.localAgent !== undefined) {
         if (localAgent !== "codex" && localAgent !== "claude") {
@@ -103,7 +119,7 @@ export function parseActorFields(entry, path) {
  * 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
@@ -114,13 +130,13 @@ export function parseParticipantEntries(raw, paths) {
         return { ok: true, value: undefined };
     }
     if (!Array.isArray(raw) || raw.length === 0) {
-        return invalid(`${paths.list} must be a non-empty array of participant objects ({ id?, actorType?, surface?, caseGroup?, persona?, device?, instruction?, target?, entry?, host?, startAfterMs?, endAfterMs?, windDownMs?, idleWaitMs?, reasoningEffort?, stopWhen?, dwell? }) when set.`);
+        return invalid(`${paths.list} must be a non-empty array of participant objects ({ id?, actorType?, surface?, caseGroup?, persona?, device?, instruction?, target?, entry?, host?, startAfterMs?, endAfterMs?, windDownMs?, idleWaitMs?, maxSessionMs?, clock?, reasoningEffort?, stopWhen?, dwell?, files? }) when set.`);
     }
     const entries = [];
     const seenIds = new Set();
     for (const [entryIndex, entry] of raw.entries()) {
         if (!isRecord(entry)) {
-            return invalid(`${paths.entry(entryIndex)} must be an object ({ id?, actorType?, surface?, caseGroup?, persona?, device?, instruction?, target?, entry?, host?, startAfterMs?, endAfterMs?, windDownMs?, idleWaitMs?, reasoningEffort?, stopWhen?, dwell? }).`);
+            return invalid(`${paths.entry(entryIndex)} must be an object ({ id?, actorType?, surface?, caseGroup?, persona?, device?, instruction?, target?, entry?, host?, startAfterMs?, endAfterMs?, windDownMs?, idleWaitMs?, maxSessionMs?, clock?, reasoningEffort?, stopWhen?, dwell?, files? }).`);
         }
         const parsedEntry = {};
         const id = str(entry.id);
@@ -141,9 +157,11 @@ export function parseParticipantEntries(raw, paths) {
             }
             parsedEntry.device = device;
         }
-        const persona = str(entry.persona);
-        if (persona !== undefined)
-            parsedEntry.persona = persona;
+        const persona = parsePersonaId(entry.persona, `${paths.entry(entryIndex)}.persona`);
+        if (!persona.ok)
+            return persona;
+        if (persona.value !== undefined)
+            parsedEntry.persona = persona.value;
         const actorType = parseEntryMetadata(entry.actorType, `${paths.entry(entryIndex)}.actorType`);
         if (!actorType.ok)
             return actorType;
@@ -188,6 +206,11 @@ export function parseParticipantEntries(raw, paths) {
                 return invalid(credential);
             parsedEntry.target = target;
         }
+        const files = parseParticipantFiles(entry.files, `${paths.entry(entryIndex)}.files`);
+        if (!files.ok)
+            return files;
+        if (files.value !== undefined)
+            parsedEntry.files = files.value;
         // `entry` is shape-captured here; the same-origin-with-serve.url check needs serve context, so
         // it runs in sharedWorldValidationReason (where the route + serve.url are known).
         const entryPath = str(entry.entry);
@@ -211,11 +234,18 @@ export function parseParticipantEntries(raw, paths) {
                 return invalid(startAfterMessage(`${paths.entry(entryIndex)}.startAfterMs`));
             parsedEntry.startAfterMs = entry.startAfterMs;
         }
-        const window = windowReason({ ...parsedEntry, endAfterMs: entry.endAfterMs, windDownMs: entry.windDownMs }, paths.entry(entryIndex));
+        const window = windowReason({
+            ...parsedEntry,
+            endAfterMs: entry.endAfterMs,
+            maxSessionMs: entry.maxSessionMs,
+            windDownMs: entry.windDownMs,
+        }, paths.entry(entryIndex));
         if (window !== undefined)
             return invalid(window);
         if (typeof entry.endAfterMs === "number")
             parsedEntry.endAfterMs = entry.endAfterMs;
+        if (typeof entry.maxSessionMs === "number")
+            parsedEntry.maxSessionMs = entry.maxSessionMs;
         if (typeof entry.windDownMs === "number")
             parsedEntry.windDownMs = entry.windDownMs;
         // Checked against actor.maxWaitMs once the actor is read (waitLimitValidationReason).
@@ -224,6 +254,11 @@ export function parseParticipantEntries(raw, paths) {
             return invalid(idleWait);
         if (typeof entry.idleWaitMs === "number")
             parsedEntry.idleWaitMs = entry.idleWaitMs;
+        const clock = parseClock(entry.clock, `${paths.entry(entryIndex)}.clock`);
+        if (!clock.ok)
+            return clock;
+        if (clock.value !== undefined)
+            parsedEntry.clock = clock.value;
         entries.push(parsedEntry);
     }
     return { ok: true, value: entries };
@@ -395,13 +430,3 @@ function parseEntryMetadata(raw, field) {
     }
     return { ok: true, value };
 }
-/** Whether Intl knows `name` as a time zone. */
-function isTimeZone(name) {
-    try {
-        new Intl.DateTimeFormat("en-GB", { timeZone: name });
-        return true;
-    }
-    catch {
-        return false;
-    }
-}

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

@@ -0,0 +1,18 @@
+import type { StudyParseFailure } from "../types.js";
+/**
+ * A participant's clock, `actor.clock` or `participants[].clock`: `{ timeZone }`. Each turn gives the
+ * participant the time in the zone, and a hosted desktop launches its browser with TZ set to it.
+ * Chrome reads TZ through ICU, which takes only a tz database name spelled with its capitals: on
+ * TZ=+05:00 it runs in UTC, and on TZ=europe/london it reports Etc/Unknown, though Intl here
+ * accepts both. So the zone must be a name Intl knows that is not a UTC offset and is spelled with
+ * capitals. Intl gives no case-sensitive check: it spells europe/belfast as Europe/London, and its
+ * supportedValuesOf omits aliases such as Europe/Belfast. So the rule is the one every tz database name
+ * keeps: each part between slashes starts with a capital, and a case variant of Intl's spelling is
+ * refused. A miscased letter after the first in a part of an alias (Europe/BELFAST) still passes.
+ */
+export declare function parseClock(raw: unknown, path: string): {
+    ok: true;
+    value: {
+        timeZone: string;
+    } | undefined;
+} | StudyParseFailure;

package/dist/study/parse/clock.js

@@ -0,0 +1,36 @@
+import { isRecord } from "../../run/type-guards.js";
+import { invalid } from "./values.js";
+/**
+ * A participant's clock, `actor.clock` or `participants[].clock`: `{ timeZone }`. Each turn gives the
+ * participant the time in the zone, and a hosted desktop launches its browser with TZ set to it.
+ * Chrome reads TZ through ICU, which takes only a tz database name spelled with its capitals: on
+ * TZ=+05:00 it runs in UTC, and on TZ=europe/london it reports Etc/Unknown, though Intl here
+ * accepts both. So the zone must be a name Intl knows that is not a UTC offset and is spelled with
+ * capitals. Intl gives no case-sensitive check: it spells europe/belfast as Europe/London, and its
+ * supportedValuesOf omits aliases such as Europe/Belfast. So the rule is the one every tz database name
+ * keeps: each part between slashes starts with a capital, and a case variant of Intl's spelling is
+ * refused. A miscased letter after the first in a part of an alias (Europe/BELFAST) still passes.
+ */
+export function parseClock(raw, path) {
+    if (raw === undefined)
+        return { ok: true, value: undefined };
+    const timeZone = isRecord(raw) ? raw.timeZone : undefined;
+    const resolved = typeof timeZone === "string" ? intlSpelling(timeZone) : undefined;
+    if (typeof timeZone !== "string" || resolved === undefined)
+        return invalid(`${path} must be { timeZone }, with timeZone a time zone name such as "Europe/London": the participant's local time, which each turn tells it and its hosted browser runs in.`);
+    if (/^[+-]/.test(resolved))
+        return invalid(`${path}.timeZone "${timeZone}" is a UTC offset, and a browser's time zone takes only a time zone name. Write the name of a place in that zone, such as "Asia/Karachi" for +05:00.`);
+    if (/(^|\/)[^A-Z]/.test(timeZone) ||
+        (resolved !== timeZone && resolved.toLowerCase() === timeZone.toLowerCase()))
+        return invalid(`${path}.timeZone "${timeZone}" must be written with the capitals of a time zone name, such as "${resolved}" for this zone: the browser reads a time zone name only with its capitals.`);
+    return { ok: true, value: { timeZone } };
+}
+/** How Intl spells the time zone `name`, or undefined when Intl does not know it. */
+function intlSpelling(name) {
+    try {
+        return new Intl.DateTimeFormat("en-GB", { timeZone: name }).resolvedOptions().timeZone;
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/study/parse/execution.js

@@ -3,6 +3,7 @@ import { DEVICE_PRESET_NAMES, isDevicePresetName } from "../device-presets.js";
 import { isExactRuntimeVersion } from "../../routes/terminal/runtime.js";
 import { invalid, nonNegNumber, posInt, str } from "./values.js";
 import { isRecord } from "../../run/type-guards.js";
+import { scanEncodedText } from "../../evidence/encoded-text.js";
 export function parseExecution(raw) {
     if (raw === undefined) {
         return { ok: true, value: undefined };
@@ -154,11 +155,16 @@ function parseDesktop(raw) {
     // A custom E2B desktop template name or ID. Trimmed non-empty when present; deliberately not
     // allowlisted (any string is a valid template name/id; over-restricting would reject real
     // adopter images). An explicitly-set but blank/whitespace value is a mistake, not a template.
+    // The run records the template it launched on, so text verify would flag, as written or
+    // encoded, is refused: redacting it in the record would name an image other than the one that ran.
     if (raw.template !== undefined) {
         const template = str(raw.template);
         if (template === undefined) {
             return invalid("`execution.desktop.template` must be a non-empty E2B desktop template name or ID when it is set. Any name is accepted.");
         }
+        if (scanEncodedText(template).sensitive) {
+            return invalid("`execution.desktop.template` looks like a secret or a local path, and the run records the template it launched on. Set it to the E2B template's name or ID only.");
+        }
         desktop.template = template;
     }
     if (typeof raw.codexAppServer === "boolean")

package/dist/study/plan-base.js

@@ -1,6 +1,7 @@
 // What every route planner shares: the plan fields common to all routes, the frozen residual config,
 // and the requirement and subject helpers.
 import { DEFAULT_OPENAI_CU_MODEL } from "../actors/computer-use/openai-provider.js";
+import { redactText } from "../evidence/redaction.js";
 // A YAML alias can make a parsed record contain itself (an inline persona that names its own
 // anchor), and structuredClone keeps the cycle, so each object is frozen once.
 function deepFreeze(value, frozen = new WeakSet()) {
@@ -110,7 +111,9 @@ export function planBase(config, input) {
     const analysis = input.analysis?.config;
     return {
         studyId: config.id,
-        ...(config.title === undefined ? {} : { title: config.title }),
+        // Every bundle writer takes the title from here, and review.md, run.json and the Observer show
+        // it, so a key or sandbox URL in it would make verify grade the run blocked.
+        ...(config.title === undefined ? {} : { title: redactText(config.title) }),
         residual: residualOf(config),
         dryRun: input.dryRun,
         ...(analysis === undefined

package/dist/study/plan-participants.d.ts

@@ -2,7 +2,7 @@ import type { DwellWindow, StopWhen } from "../actors/stop-conditions.js";
 import type { ReasoningEffort } from "../actors/reasoning-effort.js";
 import { type DevicePreset } from "./device-presets.js";
 import type { StudyTask } from "./tasks.js";
-import type { StudyConfig } from "./types.js";
+import type { StudyConfig, StudyParticipantFile } from "./types.js";
 /** Who one participant is. Every route with participants carries this record. */
 export interface Participant {
     /** Declared roster id, else `lane-NN` (independent participants) or `role-NN` (shared-world participants). */
@@ -24,7 +24,7 @@ export interface Participant {
     };
 }
 /** A participant at a desktop: computer use and shared world. */
-interface DesktopParticipant extends Participant {
+export interface DesktopParticipant extends Participant {
     readonly device: {
         readonly name: string;
         readonly preset: DevicePreset;
@@ -43,14 +43,22 @@ interface DesktopParticipant extends Participant {
          * while the participant only waits.
          */
         readonly idleWaitMs?: number;
-        /** actor.clock.timeZone: the participant's local time zone, which each turn tells it the time in. */
+        /**
+         * The participant's clock.timeZone, else actor.clock.timeZone: each turn tells it the time in
+         * this zone, and a hosted desktop runs its browser in it.
+         */
         readonly timeZone?: string;
     };
     /** When it starts, in ms after the run starts its participants; absent, with the run. */
     readonly startAfterMs?: number;
     /** Computer use: when it ends, on the same clock; absent, it runs for the study's session budget. */
     readonly endAfterMs?: number;
-    /** With endAfterMs: how long before the end each turn tells it the time left (default applied). */
+    /** Computer use: the longest its session lasts, from its start; it may end the session sooner. */
+    readonly maxSessionMs?: number;
+    /**
+     * With endAfterMs or maxSessionMs: how long before the end each turn tells it the time left
+     * (default applied).
+     */
     readonly windDownMs?: number;
 }
 /** Only independent computer-use participants consume a task protocol and their own target. */
@@ -58,6 +66,8 @@ export interface ComputerUseParticipant extends DesktopParticipant {
     readonly tasks?: readonly StudyTask[];
     /** app-url fan-out only: this participant's own entry URL; absent means the subject URL. */
     readonly targetUrl?: string;
+    /** Hosted desktop only: the files copied onto it before the participant starts. */
+    readonly files?: readonly StudyParticipantFile[];
 }
 /** A participant on a provisioned plane: an optional same-origin path under `serve.url`. */
 export interface ProvisionedParticipant extends DesktopParticipant {
@@ -93,4 +103,8 @@ export declare function sharedWorldParticipants(config: StudyConfig): SharedWorl
 export declare function declaredParticipantIds(config: StudyConfig): string[];
 /** The entry URLs roster entries declare in place of the subject URL (computer use, app-url). */
 export declare function declaredTargets(config: StudyConfig): string[];
-export {};
+/**
+ * Each participant's time zone, as `study check` and `study show` print it, in roster order with
+ * `none` for a participant without one. Undefined when no participant has a zone.
+ */
+export declare function describeTimeZones(participants: readonly DesktopParticipant[]): string | undefined;

package/dist/study/plan-participants.js

@@ -15,7 +15,7 @@ function desktopParticipant(config, entry, index, kind, focus) {
     const maxOutputTokens = actor?.maxOutputTokens;
     const maxWaitMs = actor?.maxWaitMs;
     const idleWaitMs = entry?.idleWaitMs ?? actor?.idleWaitMs;
-    const timeZone = actor?.clock?.timeZone;
+    const timeZone = entry?.clock?.timeZone ?? actor?.clock?.timeZone;
     return {
         id: participantIdAt(index, entry?.id, kind),
         index,
@@ -46,6 +46,12 @@ function desktopParticipant(config, entry, index, kind, focus) {
                 endAfterMs: entry.endAfterMs,
                 windDownMs: entry.windDownMs ?? DEFAULT_WIND_DOWN_MS,
             }),
+        ...(entry?.maxSessionMs === undefined
+            ? {}
+            : {
+                maxSessionMs: entry.maxSessionMs,
+                windDownMs: entry.windDownMs ?? DEFAULT_WIND_DOWN_MS,
+            }),
     };
 }
 /**
@@ -62,6 +68,7 @@ export function computerUseParticipants(config, countOverride) {
             ...desktopParticipant(config, entry, index, "lane", focus),
             ...(actor?.tasks === undefined ? {} : { tasks: actor.tasks }),
             ...(entry?.target === undefined ? {} : { targetUrl: entry.target }),
+            ...(entry?.files === undefined ? {} : { files: entry.files }),
         };
     });
 }
@@ -102,3 +109,12 @@ export function declaredTargets(config) {
         .map((entry) => entry.target)
         .filter((target) => target !== undefined);
 }
+/**
+ * Each participant's time zone, as `study check` and `study show` print it, in roster order with
+ * `none` for a participant without one. Undefined when no participant has a zone.
+ */
+export function describeTimeZones(participants) {
+    if (participants.every((participant) => participant.limits.timeZone === undefined))
+        return undefined;
+    return `${participants.map((participant) => `${participant.id} ${participant.limits.timeZone ?? "none"}`).join(", ")}.`;
+}