humanish 0.125.0 → 0.126.0

package/dist/study/parse/actors.js

@@ -9,6 +9,8 @@ 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_.-]*$/;
@@ -78,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") {
@@ -118,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
@@ -129,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);
@@ -205,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);
@@ -228,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).
@@ -241,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 };
@@ -412,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/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(", ")}.`;
+}

package/dist/study/plan.js

@@ -86,12 +86,11 @@ export function planStudy(config, options, deps = {}) {
     const bundle = plannedBundle(result.plan);
     // The manifest the CLI resolved enters the plan here and nowhere else; the routes read
     // plan.study for the run's status record and bundle, and plan.warnings for its bundle events.
-    const closing = closingReportWarning(result.plan);
     const warnings = [
         ...recordedStudyWarnings(study),
         ...(result.plan.warnings ?? []),
         ...(bundle.warning === undefined ? [] : [bundle.warning]),
-        ...(closing === undefined ? [] : [closing]),
+        ...closingReportWarnings(result.plan),
     ];
     const plan = {
         ...result.plan,
@@ -115,21 +114,33 @@ function plannedBundle(plan) {
     return warning === undefined ? { estimate } : { estimate, warning };
 }
 /**
- * The warning for participants with a scheduled end on Claude as a local-agent participant model.
- * Its session has no read-only closing request, so each such participant ends with the scheduled
- * end as its reason and no account of its session.
+ * The warnings for participants with a scheduled end or a session cap on Claude as a local-agent
+ * participant model. Its session has no read-only closing request, so each such participant ends
+ * at its end or cap with that as its reason and no account of its session.
  */
-function closingReportWarning(plan) {
+function closingReportWarnings(plan) {
     if (plan.route !== "computer-use")
-        return undefined;
+        return [];
     const { brain } = plan.runner;
     if (brain.kind !== "local-agent" || brain.agent !== "claude")
-        return undefined;
-    const scheduled = plan.runner.participants.filter((participant) => participant.endAfterMs !== undefined).length;
-    if (scheduled === 0)
-        return undefined;
-    const subject = scheduled === 1 ? "it ends" : "each ends";
-    return `${plural(scheduled, "participant")} ${scheduled === 1 ? "has" : "have"} a scheduled end (participants[].endAfterMs), and Claude as a local-agent participant model cannot be asked for a closing report, so ${subject} with the scheduled end as its reason and no closing account. A computer-use model (actor.type: openai-computer-use) or Codex (actor.localAgent: codex) writes one.`;
+        return [];
+    const { participants } = plan.runner;
+    const scheduled = participants.filter((participant) => participant.endAfterMs !== undefined);
+    const capped = participants.filter((participant) => participant.maxSessionMs !== undefined);
+    const claude = "Claude as a local-agent participant model cannot be asked for a closing report";
+    const writers = "A computer-use model (actor.type: openai-computer-use) or Codex (actor.localAgent: codex) writes one.";
+    return [
+        ...(scheduled.length === 0
+            ? []
+            : [
+                `${plural(scheduled.length, "participant")} ${scheduled.length === 1 ? "has" : "have"} a scheduled end (participants[].endAfterMs), and ${claude}, so ${scheduled.length === 1 ? "it ends" : "each ends"} with the scheduled end as its reason and no closing account. ${writers}`,
+            ]),
+        ...(capped.length === 0
+            ? []
+            : [
+                `${plural(capped.length, "participant")} ${capped.length === 1 ? "has" : "have"} a session cap (participants[].maxSessionMs), and ${claude}, so ${capped.length === 1 ? "if it reaches its cap it ends" : "each that reaches its cap ends"} with the cap as its reason and no closing account. ${writers}`,
+            ]),
+    ];
 }
 function planRoute(route, study, options, input, deps, e2b) {
     const { sandboxCeiling } = e2b;

package/dist/study/preflight.js

@@ -8,6 +8,7 @@ import { digest, fail, finalize, STUDY_CHECK_SCHEMA } from "./preflight-result.j
 import { planStudy, routeOf } from "./plan.js";
 import { describeArrivals, describeWindows } from "./arrivals.js";
 import { describeBundle } from "./bundle-estimate.js";
+import { describeTimeZones } from "./plan-participants.js";
 import { resolveStudyManifest } from "./discover.js";
 import { participantList } from "./study-fields.js";
 import { isLocalBrowserStudy } from "../substrates/local/runtime-config.js";
@@ -82,6 +83,9 @@ export async function runStudyPreflight(options) {
     const windows = windowsCheck(planned.planned.plan);
     if (windows !== undefined)
         ctx.checks.push(windows);
+    const timeZones = describeTimeZones(participants);
+    if (timeZones !== undefined)
+        ctx.checks.push({ name: "time zones", ok: true, message: timeZones });
     const bundle = planned.planned.bundle;
     if (bundle !== undefined)
         ctx.checks.push({ name: "bundle size", ok: true, message: describeBundle(bundle) });

package/dist/study/types.d.ts

@@ -257,6 +257,13 @@ export interface StudySubject {
      */
     localTree?: StudySubjectLocalTree;
 }
+/** One file a participant's desktop receives (`participants[].files`). */
+export interface StudyParticipantFile {
+    /** Path of the file, relative to the folder that holds the study file. */
+    from: string;
+    /** Where it lands, relative to the desktop user's home folder. */
+    as: string;
+}
 /**
  * One participant in a differentiated fan-out on the computer-use E2B route (`per-lane-worlds`).
  * Each entry becomes an independent E2B desktop sandbox with its own persona/device/starting-steer. All
@@ -304,6 +311,11 @@ export interface StudyParticipantEntry {
      * shared-world, scripted-browser, and terminal routes.
      */
     target?: string;
+    /**
+     * Hosted computer use only: files copied onto this participant's desktop before it starts, so a
+     * browser upload dialog can find them. src/study/desktop-files.ts holds the rules.
+     */
+    files?: StudyParticipantFile[];
     /**
      * Shared-world only: this participant's loopback entry route, resolved against
      * `subject.serve.url`. It must be same-origin (loopback) with it, and the participant opens
@@ -334,8 +346,16 @@ export interface StudyParticipantEntry {
      */
     endAfterMs?: number;
     /**
-     * With endAfterMs: how long before the end each turn tells the participant the end time and the
-     * minutes left. Default 600000 (10 minutes).
+     * Computer use: the longest this participant's session lasts, in milliseconds from the start of
+     * its session (1 to 86,400,000). It may end its session before then and counts as passed when it
+     * does so normally; at the cap it is asked for its closing report and the session ends as passed,
+     * with stop cause `session_cap`. Its session lasts the cap plus 5 minutes in place of
+     * execution.timeoutMs, and its sandbox is sized from that. Not with endAfterMs.
+     */
+    maxSessionMs?: number;
+    /**
+     * With endAfterMs or maxSessionMs: how long before the end each turn tells the participant the
+     * end time and the minutes left. Default 600000 (10 minutes).
      */
     windDownMs?: number;
     /**
@@ -343,6 +363,14 @@ export interface StudyParticipantEntry {
      * no duration lasts while it only waits. Same range, and no longer than actor.maxWaitMs.
      */
     idleWaitMs?: number;
+    /**
+     * Computer use and shared world: this participant's clock, in place of actor.clock. Its
+     * `timeZone` is the zone each turn gives the time in and, on a hosted desktop, the zone its
+     * browser runs in.
+     */
+    clock?: {
+        timeZone: string;
+    };
 }
 export interface StudyActor {
     /**
@@ -388,9 +416,10 @@ export interface StudyActor {
      */
     idleWaitMs?: number;
     /**
-     * Computer use: the participant's clock. `timeZone`, a time zone name such as "Europe/London", adds
-     * the local time to each turn, for missions that refer to appointment times, and gives a
-     * scheduled end (participants[].endAfterMs) in that zone. A hosted desktop shows no clock.
+     * Computer use: the participants' clock, unless a participant declares its own. `timeZone`, a
+     * time zone name such as "Europe/London", adds the local time to each turn, for missions that
+     * refer to clock times, gives a scheduled end or session cap in that zone, and sets the zone
+     * of a hosted desktop's browser and of the clock in its panel, which shows UTC without one.
      */
     clock?: {
         timeZone: string;

package/dist/study/validation.js

@@ -114,6 +114,9 @@ export function sharedWorldValidationReason(config) {
     const ending = participantList(config)?.findIndex((entry) => entry?.endAfterMs !== undefined);
     if (ending !== undefined && ending >= 0)
         return `participants[${ending}].endAfterMs ends a participant at a set time on route: computer-use only. A shared-world participant runs for execution.timeoutMs; remove endAfterMs and windDownMs.`;
+    const capped = participantList(config)?.findIndex((entry) => entry?.maxSessionMs !== undefined);
+    if (capped !== undefined && capped >= 0)
+        return `participants[${capped}].maxSessionMs caps a participant's session on route: computer-use only. A shared-world participant runs for execution.timeoutMs; remove maxSessionMs and windDownMs.`;
     return config.subject.source === "app-url"
         ? externalPublicSharedWorldValidationReason(config)
         : concurrentSharedWorldValidationReason(config);

package/dist/study/warnings.d.ts

@@ -1,6 +1,6 @@
 import type { ResolvedPersona } from "./persona.js";
 import type { StudyConfig } from "./types.js";
-import { type Participant } from "./plan-participants.js";
+import { type DesktopParticipant, type Participant } from "./plan-participants.js";
 /**
  * The fields a config sets that its route does not read, each as `field` or `field (reason)`.
  * parseStudy refuses a study for any of them.
@@ -30,4 +30,4 @@ export declare function personaBackgroundWarnings(studyId: string, participants:
  * and `study show`, which run no plan. Only computer-use and shared-world studies have them; a run's
  * `--count` is not applied.
  */
-export declare function plannedParticipants(config: StudyConfig): readonly Participant[];
+export declare function plannedParticipants(config: StudyConfig): readonly DesktopParticipant[];

package/dist/study/warnings.js

@@ -1,5 +1,6 @@
 import { cli } from "../cli/invocation.js";
 import { isComputerUseComposition, isScriptedBrowserComposition, isSharedWorldComposition, isTerminalProductComposition, } from "./routing.js";
+import { DESKTOP_FILES_ROUTE_REASON } from "./desktop-files.js";
 import { computerUseParticipants, declaredParticipantIds, sharedWorldParticipants, } from "./plan-participants.js";
 import { addressedRecipients } from "./parse/comms.js";
 import { participantList, participantInstruction, declaredParticipantCount, } from "./study-fields.js";
@@ -27,6 +28,12 @@ const ACTOR_ROWS = [
         applies: (config, routes) => Boolean(participantList(config)?.some((entry) => entry.host === true)) &&
             !routes.externalPublic,
     },
+    {
+        field: "participants[].files",
+        reason: DESKTOP_FILES_ROUTE_REASON,
+        applies: (config, routes) => Boolean(participantList(config)?.some((entry) => entry.files !== undefined)) &&
+            !(routes.hostedCuaBrowser && !routes.shared),
+    },
     {
         field: "actor.mission",
         reason: "the scripted-browser actor runs no model",

package/dist/subject/local-tree-archive.d.ts

@@ -71,6 +71,13 @@ export declare function enumerateLocalTree(root: string, options?: {
  * produces zero entries; or total packed bytes exceed maxArchiveBytes.
  */
 export declare function createLocalTreeArchive(root: string, options?: CreateLocalTreeArchiveOptions): LocalTreeArchive;
+/**
+ * Whether a relative path an author wrote names a file the always-on denylist keeps on this
+ * machine: a secret-shaped name, or one under .git, node_modules or .humanish. It compares without
+ * case, since on a case-insensitive filesystem `.ENV` opens `.env`. participants[].files refuses
+ * the same paths.
+ */
+export declare function isLocalTreeDenylisted(relPath: string): boolean;
 /**
  * Normalize an author-supplied exclude entry to the relPath shape enumeration
  * produces (no leading "./", no trailing "/"). Absolute paths and glob syntax

package/dist/subject/local-tree-archive.js

@@ -283,6 +283,18 @@ function matchesBasenamePattern(basename, pattern) {
 function isDenylistedBasename(basename) {
     return LOCAL_TREE_DENYLIST_BASENAME_PATTERNS.some((pattern) => matchesBasenamePattern(basename, pattern));
 }
+/**
+ * Whether a relative path an author wrote names a file the always-on denylist keeps on this
+ * machine: a secret-shaped name, or one under .git, node_modules or .humanish. It compares without
+ * case, since on a case-insensitive filesystem `.ENV` opens `.env`. participants[].files refuses
+ * the same paths.
+ */
+export function isLocalTreeDenylisted(relPath) {
+    const segments = relPath.toLowerCase().split("/");
+    const basename = segments.at(-1) ?? "";
+    return (segments.some((segment) => LOCAL_TREE_DENYLIST_PATH_SEGMENTS.some((denied) => denied.toLowerCase() === segment)) ||
+        LOCAL_TREE_DENYLIST_BASENAME_PATTERNS.some((pattern) => matchesBasenamePattern(basename, pattern.toLowerCase())));
+}
 function isDenylistedSegment(relPath) {
     const segments = relPath.split("/");
     return segments.some((segment) => LOCAL_TREE_DENYLIST_PATH_SEGMENTS.includes(segment));

package/dist/substrates/e2b/desktop-browser.d.ts

@@ -76,6 +76,9 @@ extraChromiumFlags?: readonly string[], environment?: Readonly<Record<string, st
  * `x-terminal-emulator` is tried first so a template that swaps
  * the emulator still works; a desktop with neither is a template problem and fails closed rather
  * than handing a participant an empty screen and calling it a study.
+ *
+ * A `timeZone` is TZ on the terminal, so its shells, the product under test and any browser started
+ * from it run in that zone.
  */
-export declare function openDesktopTerminal(desktop: E2BDesktopSandbox, requestTimeoutMs: number, workdir: string | undefined): Promise<void>;
+export declare function openDesktopTerminal(desktop: E2BDesktopSandbox, requestTimeoutMs: number, workdir: string | undefined, timeZone?: string): Promise<void>;
 export declare function startDesktopStream(desktop: E2BDesktopSandbox, browserWindowId: string | undefined): Promise<void>;

package/dist/substrates/e2b/desktop-browser.js

@@ -367,9 +367,13 @@ function desktopBrowserFamily(value) {
  * `x-terminal-emulator` is tried first so a template that swaps
  * the emulator still works; a desktop with neither is a template problem and fails closed rather
  * than handing a participant an empty screen and calling it a study.
+ *
+ * A `timeZone` is TZ on the terminal, so its shells, the product under test and any browser started
+ * from it run in that zone.
  */
-export async function openDesktopTerminal(desktop, requestTimeoutMs, workdir) {
+export async function openDesktopTerminal(desktop, requestTimeoutMs, workdir, timeZone) {
     const dir = workdir ?? "/home/user";
+    const zone = timeZone === undefined ? "" : `TZ=${shellQuote(timeZone)} `;
     const result = await runDetachedStep(e2bShell(desktop), {
         name: "desktop-cli-terminal",
         command: [
@@ -379,7 +383,7 @@ export async function openDesktopTerminal(desktop, requestTimeoutMs, workdir) {
             // a study that measures our own mojibake against an unconfigured template would be measuring
             // the template. The product-side fix (an ASCII fallback when the locale is not UTF-8) is in
             // src/routes/terminal/encoding.ts, and it is the one that matters for real users.
-            `    (cd ${shellQuote(dir)} 2>/dev/null || cd /home/user; DISPLAY=:0 LANG=C.UTF-8 LC_ALL=C.UTF-8 HUMANISH_STUDY_PARTICIPANT=1 nohup "$candidate" >/dev/null 2>&1 &)`,
+            `    (cd ${shellQuote(dir)} 2>/dev/null || cd /home/user; DISPLAY=:0 LANG=C.UTF-8 LC_ALL=C.UTF-8 ${zone}HUMANISH_STUDY_PARTICIPANT=1 nohup "$candidate" >/dev/null 2>&1 &)`,
             "    sleep 3",
             '    echo "humanish: opened $candidate"',
             "    exit 0",

package/dist/substrates/e2b/desktop-clock.d.ts

@@ -0,0 +1,10 @@
+import type { E2BDesktopSandbox } from "./sdk.js";
+/**
+ * Set every clock in the desktop's XFCE panel to `timeZone`, a tz database name, by writing the
+ * clock plugin's `timezone` property through xfconf-query. The property lives in the session's
+ * settings daemon, reached over the session bus whose address xfce4-session holds, and the panel
+ * redraws its clock when the property changes (live: 02:12 UTC became 11:12 for Asia/Tokyo with no
+ * restart). A desktop without xfconf-query or without a clock plugin is left as it is. Throws with
+ * xfconf-query's error output when a clock is found and cannot be set.
+ */
+export declare function setPanelClockZone(desktop: E2BDesktopSandbox, timeZone: string, requestTimeoutMs: number): Promise<void>;

package/dist/substrates/e2b/desktop-clock.js

@@ -0,0 +1,29 @@
+// The clock in the hosted desktop's panel. The stock template's XFCE panel sits above every window,
+// so a participant sees its clock in each screenshot, and it shows the desktop's zone, UTC, unless
+// its clock plugin names another.
+import { shellQuote } from "../shell.js";
+import { e2bShell } from "./shell.js";
+/**
+ * Set every clock in the desktop's XFCE panel to `timeZone`, a tz database name, by writing the
+ * clock plugin's `timezone` property through xfconf-query. The property lives in the session's
+ * settings daemon, reached over the session bus whose address xfce4-session holds, and the panel
+ * redraws its clock when the property changes (live: 02:12 UTC became 11:12 for Asia/Tokyo with no
+ * restart). A desktop without xfconf-query or without a clock plugin is left as it is. Throws with
+ * xfconf-query's error output when a clock is found and cannot be set.
+ */
+export async function setPanelClockZone(desktop, timeZone, requestTimeoutMs) {
+    const result = await e2bShell(desktop).run([
+        `zone=${shellQuote(timeZone)}`,
+        "command -v xfconf-query >/dev/null 2>&1 || exit 0",
+        'session_pid="$(pgrep -x xfce4-session | head -n 1)"',
+        'if [ -n "$session_pid" ]; then',
+        `  bus="$(tr '\\0' '\\n' < "/proc/$session_pid/environ" | sed -n 's/^DBUS_SESSION_BUS_ADDRESS=//p')"`,
+        '  if [ -n "$bus" ]; then export DBUS_SESSION_BUS_ADDRESS="$bus"; fi',
+        "fi",
+        `for plugin in $(xfconf-query -c xfce4-panel -p /plugins -l -v | awk '$2 == "clock" { print $1 }'); do`,
+        '  xfconf-query -c xfce4-panel -p "$plugin/timezone" -n -t string -s "$zone" || exit 1',
+        "done",
+    ].join("\n"), { requestTimeoutMs, timeoutMs: 15_000 });
+    if (result.exitCode !== 0)
+        throw new Error(result.stderr.trim() || `xfconf-query exited ${result.exitCode}`);
+}

package/dist/substrates/e2b/sdk.d.ts

@@ -154,6 +154,12 @@ export interface E2BDesktopSandbox {
             requestTimeoutMs?: number;
             useOctetStream?: boolean;
         }): Promise<unknown>;
+        /** A file's size as the sandbox sees it. A relative path is under the sandbox user's home. */
+        getInfo?(path: string, options?: {
+            requestTimeoutMs?: number;
+        }): Promise<{
+            size: number;
+        }>;
     };
     launch(application: string, uri?: string): Promise<void>;
     /** Open a file or URL with the desktop's default application (present on @e2b/desktop >= 1.x). */

package/dist/verify/pages.d.ts

@@ -0,0 +1,7 @@
+import type { RunBundle } from "../run/bundle.js";
+/**
+ * One finding per recorded page that holds more than an origin and a path, in each finished
+ * trace's items and summary and each running participant's items. A finding names where the page
+ * is, never what it says.
+ */
+export declare function pageFindings(bundle: RunBundle): string[];