humanish 0.125.0 → 0.126.0

package/dist/routes/computer-use/bundle.js

@@ -101,6 +101,10 @@ function singleParticipantArgs(base, state) {
                 : "e2b-desktop",
         ...(outcome?.desktopGeometry === undefined ? {} : { desktopGeometry: outcome.desktopGeometry }),
         ...(outcome?.recording === undefined ? {} : { recording: outcome.recording }),
+        ...(outcome?.desktopFiles === undefined ? {} : { desktopFiles: outcome.desktopFiles }),
+        ...(spec.planned.limits.timeZone === undefined
+            ? {}
+            : { timeZone: spec.planned.limits.timeZone }),
         isMobile: spec.planned.device.preset.isMobile,
         screenshots: outcome?.screenshots ?? [],
         captureRedaction: base.redactScreenshots ? "blurred" : "raw",

package/dist/routes/computer-use/diagnostics.d.ts

@@ -3,7 +3,7 @@ import { type ActorCompletionReason, type ActorStatus, type ActorStopCause } fro
 declare const CUA_DIAGNOSTIC_CATEGORIES: readonly ["preview", "participant_outcome", "session_interrupted", "execution_error", "evidence_invalid", "mixed", "unknown"];
 export type CuaDiagnosticCategory = (typeof CUA_DIAGNOSTIC_CATEGORIES)[number];
 /** Closed at both projection and telemetry boundaries. No provider messages are classified. */
-declare const CUA_DIAGNOSTIC_STOP_CAUSES: readonly ["provider_output_limit", "provider_token_limit", "time_limit", "spend_limit", "study_spend_limit", "adapter_limit", "provider_incomplete", "provider_status", "provider_refused_prompt", "harness_aborted", "usage_unreported", "scheduled_end", "unspecified_limit", "mixed", "unknown"];
+declare const CUA_DIAGNOSTIC_STOP_CAUSES: readonly ["provider_output_limit", "provider_token_limit", "time_limit", "spend_limit", "study_spend_limit", "adapter_limit", "provider_incomplete", "provider_status", "provider_refused_prompt", "harness_aborted", "usage_unreported", "scheduled_end", "session_cap", "unspecified_limit", "mixed", "unknown"];
 export type CuaDiagnosticStopCause = (typeof CUA_DIAGNOSTIC_STOP_CAUSES)[number];
 export interface CuaDiagnostics {
     category: CuaDiagnosticCategory;

package/dist/routes/computer-use/diagnostics.js

@@ -30,9 +30,9 @@ export function cuaParticipantDiagnostics(input) {
     const session = input.session;
     if (!session)
         return { category: "unknown" };
-    // A scheduled end is the participant's planned ending, so a run whose other participants ended
-    // themselves reads as one kind of ending.
-    if (session.stopCause === "scheduled_end")
+    // A scheduled end or a session cap is the participant's planned ending, so a run whose other
+    // participants ended themselves reads as one kind of ending.
+    if (session.stopCause === "scheduled_end" || session.stopCause === "session_cap")
         return { category: "participant_outcome" };
     if (session.stopCause !== undefined) {
         return {

package/dist/routes/computer-use/e2b-desktop/desktop.js

@@ -1,7 +1,7 @@
 import { createE2BDesktopExecutor } from "../../../substrates/e2b/desktop-executor.js";
 import { participantInbox, planParticipantComms } from "./comms.js";
 import { participantBrowserStateObserver } from "./fidelity.js";
-import { acquireParticipantDesktop, provisionParticipantSubject, verifyParticipantScreen, } from "./prepare.js";
+import { acquireParticipantDesktop, placeParticipantFiles, provisionParticipantSubject, verifyParticipantScreen, } from "./prepare.js";
 import { openParticipantSurface, startParticipantMedia, startParticipantStream } from "./start.js";
 import { desktopEvidenceOf, newParticipantState } from "./state.js";
 import { finishE2BDesktop } from "./teardown.js";
@@ -40,6 +40,7 @@ export function createE2BParticipantDesktop(spec, deps, warnings) {
         const desktop = await acquireParticipantDesktop(ctx, state);
         // The device claim is verified in the sandbox, and fails closed.
         await verifyParticipantScreen(ctx, state, desktop);
+        await placeParticipantFiles(ctx, state, desktop);
         await provisionParticipantSubject(ctx, state, desktop);
         await startParticipantMedia(ctx, state, desktop);
         await openParticipantSurface(ctx, state, desktop);

package/dist/routes/computer-use/e2b-desktop/prepare.d.ts

@@ -14,5 +14,11 @@ export declare function acquireParticipantDesktop(ctx: E2BParticipantContext, st
  * requested and verified geometry side by side.
  */
 export declare function verifyParticipantScreen(ctx: E2BParticipantContext, state: E2BParticipantState, desktop: E2BDesktopSandbox): Promise<void>;
+/**
+ * Copy the participant's files (participants[].files) into its home folder and confirm each one's
+ * size there, before the subject and the browser start. A file that does not land whole fails the
+ * participant before its first turn. The state records each confirmed file as it lands.
+ */
+export declare function placeParticipantFiles(ctx: E2BParticipantContext, state: E2BParticipantState, desktop: E2BDesktopSandbox): Promise<void>;
 /** Install a desktop CLI, or clone or unpack the subject and serve it, in the sandbox. */
 export declare function provisionParticipantSubject(ctx: E2BParticipantContext, state: E2BParticipantState, desktop: E2BDesktopSandbox): Promise<void>;

package/dist/routes/computer-use/e2b-desktop/prepare.js

@@ -8,11 +8,12 @@ import { provisionLocalTreeSubject } from "../../../subject/local-tree.js";
 import { SubjectBuildError } from "../../../subject/serve.js";
 import { inspectDesktopScreenGeometry } from "../../../substrates/e2b/desktop-geometry.js";
 import { observeDesktopResources } from "../../../substrates/e2b/desktop-resources.js";
-import { acquireE2BDesktopSandbox, e2bDesktopTemplate } from "../../../substrates/e2b/sandbox.js";
+import { acquireE2BDesktopSandbox, e2bDesktopTemplate, withOneRetryOnTransientE2BError, } from "../../../substrates/e2b/sandbox.js";
 import { loadE2BDesktopModule } from "../../../substrates/e2b/sdk.js";
 import { e2bShell } from "../../../substrates/e2b/shell.js";
 import { attachReceivingInbox, participantCommsEnv, startCommsCatch } from "./comms.js";
 import { participantSubjectEnv } from "../types.js";
+import { plural } from "../../../run/text.js";
 export const CUA_ACTOR_STUDY_PROVIDER_METADATA = {
     mode: "cua-actor-lab",
     tool: "humanish",
@@ -151,6 +152,51 @@ export async function verifyParticipantScreen(ctx, state, desktop) {
         };
     }
 }
+/**
+ * Copy the participant's files (participants[].files) into its home folder and confirm each one's
+ * size there, before the subject and the browser start. A file that does not land whole fails the
+ * participant before its first turn. The state records each confirmed file as it lands.
+ */
+export async function placeParticipantFiles(ctx, state, desktop) {
+    const { spec, deps } = ctx;
+    const files = deps.desktopFiles?.get(spec.planned.id) ?? [];
+    if (files.length === 0)
+        return;
+    const getInfo = desktop.files.getInfo?.bind(desktop.files);
+    if (getInfo === undefined)
+        throw new Error("The installed E2B SDK has no files.getInfo, so humanish cannot confirm that participants[].files landed. Update @e2b/desktop.");
+    const requestTimeoutMs = deps.requestTimeoutMs;
+    const startedAt = deps.now();
+    ctx.onSubjectPhase({
+        at: new Date(startedAt).toISOString(),
+        type: "cua-lab.desktop.files.started",
+        message: `copying ${plural(files.length, "file")} onto the desktop`,
+    });
+    const filesCompleted = (ok) => ctx.onSubjectPhase({
+        at: new Date(deps.now()).toISOString(),
+        type: "cua-lab.desktop.files.completed",
+        ok,
+        durationMs: Math.max(0, deps.now() - startedAt),
+        message: ok
+            ? `${plural(files.length, "file")} on the desktop`
+            : `copying files onto the desktop failed after ${plural(state.desktopFiles.length, "file")}`,
+    });
+    try {
+        for (const file of files) {
+            // A relative path lands under the sandbox user's home folder, and missing folders are made.
+            await withOneRetryOnTransientE2BError(() => desktop.files.write(file.as, file.data, { requestTimeoutMs, useOctetStream: true }));
+            const landed = await getInfo(file.as, { requestTimeoutMs });
+            if (landed.size !== file.size)
+                throw new Error(`participants[].files: ${file.as} measured ${landed.size} bytes on the desktop of participant ${spec.planned.id} after humanish copied ${file.size}, so the participant did not start.`);
+            state.desktopFiles.push({ as: file.as, size: file.size, sha256: file.sha256 });
+        }
+    }
+    catch (error) {
+        filesCompleted(false);
+        throw error;
+    }
+    filesCompleted(true);
+}
 /** Install a desktop CLI, or clone or unpack the subject and serve it, in the sandbox. */
 export async function provisionParticipantSubject(ctx, state, desktop) {
     const { deps } = ctx;

package/dist/routes/computer-use/e2b-desktop/start.d.ts

@@ -4,7 +4,8 @@ import type { E2BParticipantContext, E2BParticipantState } from "./state.js";
 export declare function startParticipantMedia(ctx: E2BParticipantContext, state: E2BParticipantState, desktop: E2BDesktopSandbox): Promise<void>;
 /**
  * Open what the participant sees: the browser at the target, with any declared camera and mobile
- * fidelity, or a terminal window on the desktop-cli route.
+ * fidelity, or a terminal window on the desktop-cli route. A participant with a time zone sees the
+ * desktop's panel clock in it; a clock that cannot be set is a warning, and it shows UTC.
  */
 export declare function openParticipantSurface(ctx: E2BParticipantContext, state: E2BParticipantState, desktop: E2BDesktopSandbox): Promise<void>;
 /**

package/dist/routes/computer-use/e2b-desktop/start.js

@@ -3,6 +3,7 @@
 // fills the participant's state.
 import { redactText, toErrorMessage } from "../../../evidence/redaction.js";
 import { CHROME_DEVTOOLS_PORT, DESKTOP_SETTLE_MS, openDesktopBrowserTarget, openDesktopTerminal, startDesktopStream, } from "../../../substrates/e2b/desktop-browser.js";
+import { setPanelClockZone } from "../../../substrates/e2b/desktop-clock.js";
 import { captureDesktopBrowserGeometry } from "../../../substrates/e2b/desktop-geometry.js";
 import { prepareDesktopMedia, startE2BDesktopMedia, } from "../../../substrates/e2b/desktop-media.js";
 import { startE2BDesktopRecording } from "../../../substrates/e2b/desktop-recording.js";
@@ -39,16 +40,23 @@ export async function startParticipantMedia(ctx, state, desktop) {
 }
 /**
  * Open what the participant sees: the browser at the target, with any declared camera and mobile
- * fidelity, or a terminal window on the desktop-cli route.
+ * fidelity, or a terminal window on the desktop-cli route. A participant with a time zone sees the
+ * desktop's panel clock in it; a clock that cannot be set is a warning, and it shows UTC.
  */
 export async function openParticipantSurface(ctx, state, desktop) {
     const { spec, deps, warnings, targetUrl } = ctx;
     const { residual, subject } = deps;
+    const { timeZone } = spec.planned.limits;
+    if (timeZone !== undefined) {
+        await setPanelClockZone(desktop, timeZone, deps.requestTimeoutMs).catch((error) => {
+            warnings.push(`The desktop's panel clock for participant ${spec.planned.id} could not be set to ${timeZone} and shows UTC: ${redactText(deps.scrubKnownValues(toErrorMessage(error)))}`);
+        });
+    }
     if (subject.kind === "desktop-cli") {
         // A terminal window, opened the way the browser is opened on every other route: the
         // participant arrives at a desktop with the thing they were asked to use already in front
         // of them. They can still open another from the dock; that is the point of a desktop.
-        await openDesktopTerminal(desktop, deps.requestTimeoutMs, subject.product.workdir);
+        await openDesktopTerminal(desktop, deps.requestTimeoutMs, subject.product.workdir, timeZone);
         await desktop.wait(DESKTOP_SETTLE_MS).catch(() => undefined);
         return;
     }
@@ -59,7 +67,11 @@ export async function openParticipantSurface(ctx, state, desktop) {
         ? undefined
         : await prepareDesktopMedia(desktop, requestedMedia, residual.policies?.mediaPermission ?? "prompt", deps.studyCwd, deps.requestTimeoutMs);
     const emulationFlags = mobileLaunchFlags(residual, spec);
-    const browserLaunch = await openDesktopBrowserTarget(desktop, targetUrl, deps.requestTimeoutMs, residual.execution?.desktop?.browser, [...emulationFlags, ...(mediaEvidence?.flags ?? [])], state.speech?.env ?? state.recording?.env);
+    // The participant's time zone is TZ on the launch: the browser process and every renderer it
+    // starts read it at startup, so every tab runs in the zone from the first page load. A CDP
+    // timezone override holds only on the one tab whose DevTools session sets it, from after its load.
+    const mediaEnv = state.speech?.env ?? state.recording?.env;
+    const browserLaunch = await openDesktopBrowserTarget(desktop, targetUrl, deps.requestTimeoutMs, residual.execution?.desktop?.browser, [...emulationFlags, ...(mediaEvidence?.flags ?? [])], timeZone === undefined ? mediaEnv : { ...mediaEnv, TZ: timeZone });
     state.desktopBrowser =
         mediaEvidence === undefined
             ? browserLaunch.evidence

package/dist/routes/computer-use/e2b-desktop/state.d.ts

@@ -1,6 +1,6 @@
 import type { RunDesktopRecording } from "../../../evidence/desktop-recording-types.js";
 import type { RunSubjectStateStepRecord } from "../../../run/bundle.js";
-import type { RunDesktopGeometry } from "../../../run/streams.js";
+import type { RunDesktopFile, RunDesktopGeometry } from "../../../run/streams.js";
 import type { SubjectPhaseEvent } from "../../../subject/steps.js";
 import type { OwnedDesktopAllocation } from "../../../substrates/desktop-session.js";
 import type { DesktopBrowserEvidence, DesktopBrowserFamily, DesktopBrowserLaunchIdentity } from "../../../substrates/e2b/desktop-browser.js";
@@ -45,6 +45,8 @@ export interface E2BParticipantState {
     readonly stateStepRecords: RunSubjectStateStepRecord[];
     /** Completed phases only (durationMs and ok are set on completed events); bundle.events keeps these. */
     readonly phaseRecords: SubjectPhaseEvent[];
+    /** participants[].files confirmed on the desktop, in the order they landed. */
+    readonly desktopFiles: RunDesktopFile[];
     subjectCommit: string | undefined;
     speech: Awaited<ReturnType<typeof startE2BDesktopMedia>> | undefined;
     recording: Awaited<ReturnType<typeof startE2BDesktopRecording>> | undefined;

package/dist/routes/computer-use/e2b-desktop/state.js

@@ -18,6 +18,7 @@ export function newParticipantState(spec) {
         receivingInboxUrl: undefined,
         stateStepRecords: [],
         phaseRecords: [],
+        desktopFiles: [],
         subjectCommit: undefined,
         speech: undefined,
         recording: undefined,
@@ -60,6 +61,7 @@ export function desktopEvidenceOf(state) {
         ...(state.subjectCommit === undefined ? {} : { subjectCommit: state.subjectCommit }),
         ...(state.desktopBrowser === undefined ? {} : { desktopBrowser: state.desktopBrowser }),
         ...(state.recordingEvidence === undefined ? {} : { recording: state.recordingEvidence }),
+        ...(state.desktopFiles.length === 0 ? {} : { desktopFiles: state.desktopFiles }),
         desktopGeometry: state.desktopGeometry,
         stateStepRecords: state.stateStepRecords,
         phaseRecords: state.phaseRecords,

package/dist/routes/computer-use/fanout-records.js

@@ -120,6 +120,10 @@ function fanoutParticipantStream(args, spec, view) {
                 },
             }),
         desktopGeometry,
+        ...(outcome?.desktopFiles === undefined ? {} : { desktopFiles: outcome.desktopFiles }),
+        ...(spec.planned.limits.timeZone === undefined
+            ? {}
+            : { timeZone: spec.planned.limits.timeZone }),
         ...(outcome?.recording === undefined ? {} : { recording: outcome.recording }),
         ui: {
             route: publicTargetUrl,

package/dist/routes/computer-use/participant-deps.d.ts

@@ -36,7 +36,7 @@ interface DesktopRunFacts {
 }
 /** The fields one desktop route sets and the other does not. Undefined leaves a field out. */
 type DesktopRouteOverrides = {
-    [K in "createDesktop" | "createProvider" | "inProcessExecutor" | "localTreeArchiveBuffer" | "externalComms" | "receiving" | "screenMismatchPolicy"]?: CuaParticipantDeps[K] | undefined;
+    [K in "createDesktop" | "createProvider" | "inProcessExecutor" | "localTreeArchiveBuffer" | "desktopFiles" | "externalComms" | "receiving" | "screenMismatchPolicy"]?: CuaParticipantDeps[K] | undefined;
 };
 /**
  * One run's participant deps. Call it once per run: the run budget it creates is the one ledger

package/dist/routes/computer-use/participant-desktop.d.ts

@@ -22,7 +22,7 @@ export type ParticipantDesktopEvidence = {
      * who did not pass.
      */
     desktopFailure?: string;
-} & Pick<ParticipantRunOutcome, "sandboxId" | "sandboxRelease" | "desktopDurationMs" | "desktopResources" | "streamUrlPresent" | "subjectCommit" | "desktopBrowser" | "desktopGeometry" | "stateStepRecords" | "phaseRecords" | "failureCode" | "commsArtifactPath" | "recording">;
+} & Pick<ParticipantRunOutcome, "sandboxId" | "sandboxRelease" | "desktopDurationMs" | "desktopResources" | "streamUrlPresent" | "subjectCommit" | "desktopBrowser" | "desktopGeometry" | "stateStepRecords" | "phaseRecords" | "failureCode" | "commsArtifactPath" | "recording" | "desktopFiles">;
 /**
  * The desktop one participant runs on, owned from preparation through final evidence collection.
  * Call methods sequentially: prepare, openSession, then finalize in a finally block.

package/dist/routes/computer-use/participant-model.js

@@ -307,18 +307,28 @@ export function makeCuaRunBudget(maxTotalUsd) {
     };
 }
 /**
- * The participant's clock: its time zone, and its scheduled end on the run's clock. A participant
- * with an end runs its session on the run's clock, so the end and the schedule read one clock.
+ * The participant's clock: its time zone, and its end on the run's clock. A participant with an
+ * end runs its session on the run's clock, so the end and the schedule read one clock. A cap
+ * counts from here, where the session starts, so the desktop's setup does not use it.
  */
 function participantClock(timeZone, deps) {
-    const { scheduledEnd } = deps;
-    if (timeZone === undefined && scheduledEnd === undefined)
+    const declared = deps.end;
+    if (timeZone === undefined && declared === undefined)
         return {};
+    const end = declared === undefined
+        ? undefined
+        : declared.kind === "session_cap"
+            ? {
+                atMs: deps.now() + declared.afterMs,
+                windDownMs: declared.windDownMs,
+                kind: declared.kind,
+            }
+            : { atMs: declared.atMs, windDownMs: declared.windDownMs };
     return {
         clock: {
             ...(timeZone === undefined ? {} : { timeZone }),
-            ...(scheduledEnd === undefined ? {} : { end: scheduledEnd }),
+            ...(end === undefined ? {} : { end }),
         },
-        ...(scheduledEnd === undefined ? {} : { now: deps.now }),
+        ...(end === undefined ? {} : { now: deps.now }),
     };
 }

package/dist/routes/computer-use/participant-runs.d.ts

@@ -19,13 +19,13 @@ export declare function defaultSessionTimeoutMs(config: StudyConfig, ceilingMs:
 export declare function resolveParticipantSandboxMs(config: StudyConfig, ceilingMs: number): number;
 /**
  * The deps one participant runs with once its start comes: its own session budget and sandbox
- * deadline, and with a declared end, that end on the run's clock (`scheduledAt` is when it was
+ * deadline, and with a declared end or cap, how its session ends (`scheduledAt` is when it was
  * due, from runOnSchedule).
  */
 export declare function scheduledParticipantDeps(participant: ParticipantWindow, deps: {
     readonly timeoutMs: number;
     readonly sandboxMs: number;
-}, scheduledAt: number): Pick<CuaParticipantDeps, "timeoutMs" | "sandboxMs" | "scheduledEnd">;
+}, scheduledAt: number): Pick<CuaParticipantDeps, "timeoutMs" | "sandboxMs" | "end">;
 /**
  * The in-flight participant bound a study declares. Defaults to the participant count: every
  * declared participant runs at once, because a throttle nobody asked for silently turns "N actors

package/dist/routes/computer-use/participant-runs.js

@@ -18,7 +18,7 @@ import { composeParticipantInstructions, DEFAULT_MISSION } from "./participant-p
 import { resolveCuaRerunSelection } from "./rerun-selection.js";
 import { plural } from "../../run/text.js";
 import { formatDuration } from "../../run/projection.js";
-import { describeArrivals, participantSessionMs, planArrivals, scheduledEndAt, } from "../../study/arrivals.js";
+import { describeArrivals, participantEnd, participantSessionMs, planArrivals, } from "../../study/arrivals.js";
 /**
  * The session budget of a study that declares no execution.timeoutMs. On a provisioned route it is
  * what the `ceilingMs` sandbox ceiling leaves after provisioning, seeding and the teardown buffer.
@@ -46,9 +46,9 @@ export function resolveParticipantSandboxMs(config, ceilingMs) {
             sandboxHeadroomMs(provisionedRoute ? { seed: config.subject.state?.seed ?? [] } : undefined));
 }
 /**
- * A participant's own session budget and sandbox deadline: the study's, or with a declared end its
- * window plus room for the closing report (participantSessionMs), with the same setup and
- * teardown headroom the study's sandbox has over its session.
+ * A participant's own session budget and sandbox deadline: the study's, or with a declared end or
+ * cap its window or cap plus room for the closing report (participantSessionMs), with the same
+ * setup and teardown headroom the study's sandbox has over its session.
  */
 function participantWindow(participant, study) {
     const timeoutMs = participantSessionMs(participant, study.sessionBudgetMs);
@@ -56,17 +56,17 @@ function participantWindow(participant, study) {
 }
 /**
  * The deps one participant runs with once its start comes: its own session budget and sandbox
- * deadline, and with a declared end, that end on the run's clock (`scheduledAt` is when it was
+ * deadline, and with a declared end or cap, how its session ends (`scheduledAt` is when it was
  * due, from runOnSchedule).
  */
 export function scheduledParticipantDeps(participant, deps, scheduledAt) {
-    const end = scheduledEndAt(participant, scheduledAt);
+    const end = participantEnd(participant, scheduledAt);
     return {
         ...participantWindow(participant, {
             sessionBudgetMs: deps.timeoutMs,
             sandboxMs: deps.sandboxMs,
         }),
-        ...(end === undefined ? {} : { scheduledEnd: end }),
+        ...(end === undefined ? {} : { end }),
     };
 }
 /**
@@ -184,6 +184,9 @@ export function participantRunsAndPlan(plan, opts = {}) {
                 ? {}
                 : { startAfterMs: spec.planned.startAfterMs }),
             ...(spec.planned.endAfterMs === undefined ? {} : { endAfterMs: spec.planned.endAfterMs }),
+            ...(spec.planned.maxSessionMs === undefined
+                ? {}
+                : { maxSessionMs: spec.planned.maxSessionMs }),
         })),
     };
     return { runs, participantPlan };
@@ -209,6 +212,7 @@ export function formatParticipantPlanEntry(entry) {
         entry.reasoningEffort ? `effort=${entry.reasoningEffort}` : undefined,
         entry.startAfterMs === undefined ? undefined : `start=+${formatDuration(entry.startAfterMs)}`,
         entry.endAfterMs === undefined ? undefined : `end=+${formatDuration(entry.endAfterMs)}`,
+        entry.maxSessionMs === undefined ? undefined : `cap=${formatDuration(entry.maxSessionMs)}`,
     ].filter((part) => part !== undefined);
     return `${entry.id}: persona=${entry.persona}${taxonomy.length > 0 ? ` ${taxonomy.join(" ")}` : ""} device=${entry.device} ${entry.resolution[0]}x${entry.resolution[1]} prompt#${entry.instructionDigest}${entry.targetDigest ? ` target#${entry.targetDigest}` : ""}`;
 }

package/dist/routes/computer-use/plan.js

@@ -2,13 +2,14 @@
 // in its order and with its codes, then the plan the run uses. What stays in the route reads
 // external state: committed personas, a rerun's source run, keys, the local agent, subject env
 // values, spend-cap prices and the comms catch.
+import { DESKTOP_FILES_ROUTE_REASON } from "../../study/desktop-files.js";
 import { resolveAutomaticAnalysis } from "../../analysis/automatic-config.js";
 import { actorRegistry, isCuaActorDescriptor, } from "../../actors/registry.js";
 import { isHttpUrl, isLoopbackUrl } from "../../study/parse/subject.js";
 import { studyUrlCredentialReason } from "../../study/url-credentials.js";
 import { subjectStateInvalidReason } from "../../study/parse/subject-state.js";
 import { brainOf, callerBrainOf, planCaps, desktopRequirements, planBase, provisionedSubject, } from "../../study/plan-base.js";
-import { computerUseParticipants, declaredTargets } from "../../study/plan-participants.js";
+import { computerUseParticipants, declaredTargets, } from "../../study/plan-participants.js";
 import { planStarts, windowDeadlineRefusal } from "../../study/arrivals.js";
 import { computerUseParticipantCount, participantCountReason } from "../../study/routing.js";
 import { cloneTargetValidationReason, computerUseValidationReason, desktopMediaValidationReason, outputTokenLimitValidationReason, receivingEmailValidationReason, taskProtocolValidationReason, waitLimitValidationReason, } from "../../study/validation.js";
@@ -227,6 +228,40 @@ function startsOf(config, runner, limit, ceilingMs) {
 function rerunPlan({ sourceRunId, participantIds, }) {
     return { sourceRunId, ...(participantIds === undefined ? {} : { participantIds }) };
 }
+/**
+ * Why participants[].files cannot run on this runner, or undefined. The parser refuses them off the
+ * hosted desktop; a library caller's config skips the parser, and only the hosted desktop copies
+ * files.
+ */
+function desktopFilesRunnerReason(desktop, participants) {
+    if (desktop === "e2b-desktop" || participants.every((entry) => entry.files === undefined))
+        return undefined;
+    return `participants[].files: ${DESKTOP_FILES_ROUTE_REASON}. This study runs on a ${desktop} desktop; remove the files or set execution.target: e2b-desktop.`;
+}
+/**
+ * Why a participant's time zone cannot run on this runner, or undefined. The zone also sets the
+ * zone its browser runs in, which humanish sets on a hosted desktop's browser launch only: the
+ * local runtime's guest browser and an in-process caller's browser keep their own.
+ */
+function timeZoneRunnerReason(desktop, participants) {
+    const zoned = participants.find((entry) => entry.limits.timeZone !== undefined);
+    if (desktop === "e2b-desktop" || zoned === undefined)
+        return undefined;
+    const declared = `Participant ${zoned.id} has the time zone ${zoned.limits.timeZone}, which sets the zone its browser runs in, and humanish sets a browser's zone only on a hosted desktop.`;
+    return desktop === "local-vm"
+        ? `${declared} This study runs on the local browser runtime. Remove actor.clock and participants[].clock, or set execution.target: e2b-desktop.`
+        : `${declared} This study drives your own browser through RunStudyOptions.inProcess. Remove actor.clock and participants[].clock, and set the zone in that browser yourself, or run on a hosted desktop.`;
+}
+/** What the participants declare that this runner cannot do, with its code, or undefined. */
+function runnerRefusal(desktop, participants) {
+    const files = desktopFilesRunnerReason(desktop, participants);
+    if (files)
+        return { code: "HUMANISH_COMPUTER_USE_DESKTOP_FILES_INVALID", message: files };
+    const timeZone = timeZoneRunnerReason(desktop, participants);
+    if (timeZone)
+        return { code: "HUMANISH_COMPUTER_USE_TIME_ZONE_UNSUPPORTED", message: timeZone };
+    return undefined;
+}
 /**
  * Plan a computer-use study. It is called for any config handed to the computer-use runner, not only
  * one routeOf sends here, so a config for another route gets this route's refusal.
@@ -311,6 +346,9 @@ export function planComputerUseStudy(config, input) {
         : isLocalBrowserStudy(config)
             ? { desktop: "local-vm", brain, participants: [first, ...rest], subject: appUrlSubject }
             : { desktop: "e2b-desktop", brain, participants: [first, ...rest], subject: hosted };
+    const unsupported = runnerRefusal(runner.desktop, participants);
+    if (unsupported)
+        return refuse("in-scope", unsupported.code, unsupported.message, actor);
     const starts = startsOf(config, runner, input.concurrentSandboxes, ceiling.ms);
     if (!starts.ok)
         return refuse("after-personas", "HUMANISH_COMPUTER_USE_FANOUT_INVALID", starts.message, actor);

package/dist/routes/computer-use/setup.d.ts

@@ -115,6 +115,7 @@ export declare function admitCuaRun(plan: ComputerUsePlan, input: ComputerUseRun
         publicRepo: string | undefined;
         localTreeArchive: LocalTreeArchive | undefined;
         localTreeArchiveBuffer: ArrayBuffer | undefined;
+        desktopFiles: ReadonlyMap<string, readonly import("../../study/desktop-files.js").DesktopFile[]>;
     };
 }>;
 /** Starts the run and builds what the participants and the finish read: the deps and the bundle base. */

package/dist/routes/computer-use/setup.js

@@ -24,6 +24,7 @@ import { projectParticipantSubjects } from "./subject-projection.js";
 import { participantSubjectEnv, } from "./types.js";
 import { capacityShortfall } from "../../substrates/local/capacity.js";
 import { studyPersonaIds } from "../../study/persona-resolve.js";
+import { readDesktopFiles } from "../../study/desktop-files.js";
 import { refusedResult } from "../../run/study-result.js";
 /** The physical project, bound before any caller hook runs. */
 async function bindProject(cwd) {
@@ -132,6 +133,9 @@ export async function admitCuaRun(plan, input, config) {
         ...subjectEnvNames.map((name) => env[name] ?? ""),
     ]);
     sanitizeParticipantRuns(participantRuns, secrets.scrub);
+    const desktopFiles = await readStudyDesktopFiles(input.cwd, plan, participantRuns, secrets.scrub);
+    if (!desktopFiles.ok)
+        return refuse("HUMANISH_COMPUTER_USE_DESKTOP_FILES_INVALID", desktopFiles.message, descriptor.id);
     const redactRepoLabel = plan.residual.policies?.redactRepos ?? subjectEnvNames.includes("GITHUB_TOKEN");
     const publicRepo = subject.kind === "clone" ? (redactRepoLabel ? "repo-01" : subject.repo) : undefined;
     // Key-gating is route-aware: the in-process route uses the caller's own model + executor, and
@@ -195,9 +199,32 @@ export async function admitCuaRun(plan, input, config) {
             publicRepo,
             localTreeArchive,
             localTreeArchiveBuffer,
+            desktopFiles: desktopFiles.files,
         },
     };
 }
+/**
+ * Each participant's files, read on dry runs too so a bad file is named before a live run. Paths
+ * are relative to the folder that holds the study file; a library caller's config comes from no
+ * file, so its paths are relative to the project. An `as` that holds a value `scrub` removes, such
+ * as a key from the environment, is refused: the run records `as`, and redacting it would record a
+ * different path.
+ */
+async function readStudyDesktopFiles(cwd, plan, participantRuns, scrub) {
+    const folder = plan.study?.path === undefined
+        ? path.resolve(cwd)
+        : path.dirname(path.resolve(cwd, plan.study.path));
+    const read = await readDesktopFiles(folder, participantRuns.map((run) => run.planned));
+    if (!read.ok)
+        return read;
+    const named = [...read.files].find(([, files]) => files.some((file) => scrub(file.as) !== file.as));
+    return named === undefined
+        ? read
+        : {
+            ok: false,
+            message: `Participant ${named[0]}'s files name an as path that holds a key or another value from this run's environment, which the run would record. Rename the file.`,
+        };
+}
 /**
  * Whether a local study's desktops at once fit the local runtime. Read before any desktop: a
  * desktop past the VM's memory is killed mid-session, after its participant has spent.
@@ -317,6 +344,7 @@ function cuaParticipantDeps(plan, input, admitted, run) {
         createDesktop: input.localVm?.desktop,
         ...callerDriving(input, config),
         localTreeArchiveBuffer: admitted.localTreeArchiveBuffer,
+        desktopFiles: admitted.desktopFiles.size === 0 ? undefined : admitted.desktopFiles,
         externalComms: externalCommsConfig === undefined || externalCommsEmail === undefined
             ? undefined
             : { email: externalCommsEmail, inboxUrl: externalInboxUrl(externalCommsConfig) },

package/dist/routes/computer-use/single-bundle.d.ts

@@ -4,7 +4,7 @@ import type { DesktopBrowserEvidence } from "../../substrates/e2b/desktop-browse
 import type { ActorPersonaRef } from "../../actors/contract.js";
 import type { CuaLoopResult } from "../../actors/computer-use/loop.js";
 import { type BundleRun, type RunBundle, type RunFeedbackCandidate, type RunProviderResource, type RunSubjectProvenance } from "../../run/bundle.js";
-import { type RunDesktopGeometry, type RunStream } from "../../run/streams.js";
+import { type RunDesktopFile, type RunDesktopGeometry, type RunStream } from "../../run/streams.js";
 import { type Verdict } from "../../run/judge.js";
 import { type DesktopUsage } from "../../run/cost-summary.js";
 import type { HostSuspensionReading } from "../../run/host-suspension.js";
@@ -41,6 +41,10 @@ export declare function buildSingleParticipantBundle(args: {
     /** Runtime screen/window/viewport evidence. `viewport` inside this object must be measured. */
     desktopGeometry?: RunDesktopGeometry;
     recording?: RunDesktopRecording;
+    /** participants[].files confirmed on the participant's desktop. */
+    desktopFiles?: RunDesktopFile[];
+    /** The participant's time zone, which its turns and its hosted browser used. */
+    timeZone?: string;
     /** Device-preset touch metadata echoed on the measured stream viewport (a prompt signal on
      *  this route, never a rendered claim); the measured width/height/DPR stay authoritative. */
     isMobile?: boolean;

package/dist/routes/computer-use/single-bundle.js

@@ -151,6 +151,8 @@ function singleStream(args, view) {
                 },
             }),
         ...(desktopGeometry === undefined ? {} : { desktopGeometry }),
+        ...(args.desktopFiles === undefined ? {} : { desktopFiles: args.desktopFiles }),
+        ...(args.timeZone === undefined ? {} : { timeZone: args.timeZone }),
         ...(args.recording === undefined ? {} : { recording: args.recording }),
         ui: {
             route: publicAppUrl,