humanish 0.125.0 → 0.127.0

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

@@ -10,15 +10,14 @@ import { redactText } from "../../evidence/redaction.js";
 import {} from "../../run/bundle.js";
 import { participantAssignment } from "../../study/participant-assignment.js";
 import { resolveCommittedPersonas } from "../../study/persona-resolve.js";
-import { CUA_FANOUT_STRATEGY, CUA_MAX_CONCURRENCY_ENV, DEFAULT_APP_URL_SESSION_TIMEOUT_MS, MIN_DERIVED_SESSION_TIMEOUT_MS, } from "./types.js";
-import { sandboxHeadroomMs } from "../../substrates/e2b/lifetime.js";
-import { readPositiveInt } from "../../study/parse/values.js";
+import { CUA_FANOUT_STRATEGY, DEFAULT_APP_URL_SESSION_TIMEOUT_MS, MIN_DERIVED_SESSION_TIMEOUT_MS, } from "./types.js";
+import { CUA_MAX_CONCURRENCY_ENV, sandboxHeadroomMs } from "../../substrates/e2b/lifetime.js";
 import { digestUrl } from "./bundle-parts.js";
 import { composeParticipantInstructions, DEFAULT_MISSION } from "./participant-prompt.js";
 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, participantSession, } 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.
@@ -45,28 +44,21 @@ export function resolveParticipantSandboxMs(config, ceilingMs) {
         timeoutMs +
             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.
- */
-function participantWindow(participant, study) {
-    const timeoutMs = participantSessionMs(participant, study.sessionBudgetMs);
-    return { timeoutMs, sandboxMs: study.sandboxMs - study.sessionBudgetMs + timeoutMs };
-}
 /**
  * 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
- * due, from runOnSchedule).
+ * deadline (participantSession), 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 own = participantSession(participant.schedule, {
+        sessionMs: deps.timeoutMs,
+        sandboxMs: deps.sandboxMs,
+    });
+    const end = participantEnd(participant.schedule, scheduledAt);
     return {
-        ...participantWindow(participant, {
-            sessionBudgetMs: deps.timeoutMs,
-            sandboxMs: deps.sandboxMs,
-        }),
-        ...(end === undefined ? {} : { scheduledEnd: end }),
+        timeoutMs: own.sessionMs,
+        sandboxMs: own.sandboxMs,
+        ...(end === undefined ? {} : { end }),
     };
 }
 /**
@@ -74,33 +66,17 @@ export function scheduledParticipantDeps(participant, deps, scheduledAt) {
  * declared participant runs at once, because a throttle nobody asked for silently turns "N actors
  * live" into waves; total session count and spend are the same either way, only wall-clock
  * and simultaneity differ. A declared execution.concurrency is a cap, clamped to [1, participants].
- * The planner records it; the route may only lower it from the environment.
+ * participantsAtOnce then lowers it to what the E2B plan and HUMANISH_CUA_MAX_CONCURRENCY allow.
  */
 export function boundedConcurrency(declared, participantCount) {
     return Math.max(1, declared === undefined ? participantCount : Math.min(Math.max(1, declared), participantCount));
 }
-/**
- * The planned bound, lowered by the env override. The override may only lower it (never raise
- * concurrent paid desktops), and a lowering is reported via envLoweredFrom so the
- * plan never silently disagrees with the manifest.
- */
-function envLoweredConcurrency(planned, participantCount, env) {
-    const envLower = readPositiveInt(env[CUA_MAX_CONCURRENCY_ENV], 0);
-    if (envLower > 0 && envLower < planned) {
-        return {
-            bound: Math.max(1, Math.min(planned, envLower, participantCount)),
-            envLoweredFrom: planned,
-        };
-    }
-    return { bound: planned };
-}
 /**
  * Build the participant runs and the public plan from a computer-use plan (pure). The same plan
- * appears in dry-run and live, marked $0 for a dry run. `env` may lower the planned concurrency;
- * `personas` are the compiled committed personas the prompts carry.
+ * appears in dry-run and live, marked $0 for a dry run. `personas` are the compiled committed
+ * personas the prompts carry.
  */
 export function participantRunsAndPlan(plan, opts = {}) {
-    const env = opts.env ?? {};
     // Who each participant is (id, persona, focus, device, limits) comes from the plan; this adds
     // what the route derives from it: the prompt, bundle ids and artifact paths.
     const { participants } = plan.runner;
@@ -136,58 +112,54 @@ export function participantRunsAndPlan(plan, opts = {}) {
             traceArtifactPath: participantCount === 1 ? "actor.json" : `actors/${run.streamId}.json`,
         };
     });
-    const resolved = envLoweredConcurrency(plan.concurrency, participantCount, env);
-    const concurrency = resolved.bound;
-    const { sessionBudgetMs } = plan;
-    const schedule = resolved.envLoweredFrom === undefined
-        ? plan.arrivals
-        : planArrivals(participants.map((participant) => participant.startAfterMs), { slots: concurrency, sessionMs: sessionBudgetMs }, participants.map((participant) => participantSessionMs(participant, sessionBudgetMs)));
-    const sandboxesMs = participants.reduce((sum, participant) => sum + participantWindow(participant, plan).sandboxMs, 0);
+    const { concurrency, sessionBudgetMs, arrivals: schedule, envLoweredConcurrencyFrom } = plan;
+    const study = { sessionMs: sessionBudgetMs, sandboxMs: plan.sandboxMs };
+    const sandboxesMs = participants.reduce((sum, participant) => sum + participantSession(participant.schedule, study).sandboxMs, 0);
     const participantPlan = {
         strategy: CUA_FANOUT_STRATEGY,
         laneCount: participantCount,
         concurrency,
-        ...(resolved.envLoweredFrom === undefined
-            ? {}
-            : { envLoweredConcurrencyFrom: resolved.envLoweredFrom }),
+        ...(envLoweredConcurrencyFrom === undefined ? {} : { envLoweredConcurrencyFrom }),
         waves: Math.ceil(participantCount / concurrency),
         perLaneSessionBudgetMs: sessionBudgetMs,
         worstCaseSandboxMinutes: Math.round(sandboxesMs / 60_000),
         ...(schedule.declared ? { schedule } : {}),
         dryRun: plan.dryRun,
-        lanes: runs.map((spec) => ({
-            id: spec.planned.id,
-            ...(spec.planned.labels.actorType === undefined
-                ? {}
-                : { actorType: spec.planned.labels.actorType }),
-            ...(spec.planned.labels.surface === undefined
-                ? {}
-                : { surface: spec.planned.labels.surface }),
-            ...(spec.planned.labels.caseGroup === undefined
-                ? {}
-                : { caseGroup: spec.planned.labels.caseGroup }),
-            index: spec.planned.index + 1,
-            persona: spec.persona.id,
-            device: spec.planned.device.name,
-            resolution: spec.planned.device.resolution,
-            instructionDigest: spec.persona.promptDigest,
-            ...(spec.planned.limits.reasoningEffort === undefined
-                ? {}
-                : { reasoningEffort: spec.planned.limits.reasoningEffort }),
-            ...(spec.planned.limits.maxOutputTokens === undefined
-                ? {}
-                : { maxOutputTokens: spec.planned.limits.maxOutputTokens }),
-            ...(spec.planned.targetUrl === undefined
-                ? {}
-                : { targetDigest: digestUrl(spec.planned.targetUrl) }),
-            ...(spec.planned.startAfterMs === undefined
-                ? {}
-                : { startAfterMs: spec.planned.startAfterMs }),
-            ...(spec.planned.endAfterMs === undefined ? {} : { endAfterMs: spec.planned.endAfterMs }),
-        })),
+        lanes: runs.map((spec) => planEntry(spec)),
     };
     return { runs, participantPlan };
 }
+/** One participant's row in the plan: ids, labels, device, digests and its declared times. */
+function planEntry(spec) {
+    const { startAfterMs, end } = spec.planned.schedule;
+    return {
+        id: spec.planned.id,
+        ...(spec.planned.labels.actorType === undefined
+            ? {}
+            : { actorType: spec.planned.labels.actorType }),
+        ...(spec.planned.labels.surface === undefined ? {} : { surface: spec.planned.labels.surface }),
+        ...(spec.planned.labels.caseGroup === undefined
+            ? {}
+            : { caseGroup: spec.planned.labels.caseGroup }),
+        index: spec.planned.index + 1,
+        persona: spec.persona.id,
+        device: spec.planned.device.name,
+        resolution: spec.planned.device.resolution,
+        instructionDigest: spec.persona.promptDigest,
+        ...(spec.planned.limits.reasoningEffort === undefined
+            ? {}
+            : { reasoningEffort: spec.planned.limits.reasoningEffort }),
+        ...(spec.planned.limits.maxOutputTokens === undefined
+            ? {}
+            : { maxOutputTokens: spec.planned.limits.maxOutputTokens }),
+        ...(spec.planned.targetUrl === undefined
+            ? {}
+            : { targetDigest: digestUrl(spec.planned.targetUrl) }),
+        ...(startAfterMs === undefined ? {} : { startAfterMs }),
+        ...(end?.kind === "scheduled_end" ? { endAfterMs: end.endAfterMs } : {}),
+        ...(end?.kind === "session_cap" ? { maxSessionMs: end.windowMs } : {}),
+    };
+}
 /** Print the participant plan to stderr before any sandbox/provider call (public-safe: ids, devices,
  *  digests, and budgets only; no prompt text, no secrets). */
 export function emitPreflightPlan(participantPlan, studyId) {
@@ -209,6 +181,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}` : ""}`;
 }
@@ -236,10 +209,7 @@ export async function loadCuaParticipants(args) {
     // Compile any committed personas before planning, so the plan builder stays pure and each participant's
     // prompt carries real behavioral directives rather than a bare `Persona: <id>.` label.
     const personas = await compileParticipantPersonas(args.projectRoot, participants.map((participant) => participant.personaId));
-    const { runs: participantRuns, participantPlan } = participantRunsAndPlan(plan, {
-        env: args.env,
-        personas,
-    });
+    const { runs: participantRuns, participantPlan } = participantRunsAndPlan(plan, { personas });
     const rerun = plan.rerun;
     if (!rerun)
         return { ok: true, participantRuns, participantPlan };

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

@@ -50,4 +50,6 @@ export declare function planComputerUseStudy(config: StudyConfig, input: {
     readonly sandboxCeiling: SandboxCeiling;
     /** How many sandboxes the operator's E2B plan runs at once (concurrentSandboxes). */
     readonly concurrentSandboxes: ConcurrentSandboxes;
+    /** HUMANISH_CUA_MAX_CONCURRENCY (concurrencyCap), which may only lower the participants at once. */
+    readonly concurrencyCap?: number | undefined;
 }): ComputerUsePlanResult;

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";
@@ -197,36 +198,82 @@ function rosterShapeReason(config, ceilingMs) {
  * How many of the runner's participants run at once, and when each one starts, with the session
  * budget the `ceilingMs` sandbox ceiling leaves. Hosted desktops share the E2B plan's concurrent
  * sandboxes; the local VM has its own capacity rules and the in-process route runs one
- * participant.
+ * participant. HUMANISH_CUA_MAX_CONCURRENCY (`concurrencyCap`) lowers the count on every desktop.
+ * `starts` holds the plan's fields for them.
  */
-function startsOf(config, runner, limit, ceilingMs) {
+function startsOf(config, runner, limits, ceilingMs) {
     const declared = config.execution?.concurrency;
     const n = runner.participants.length;
-    const concurrency = boundedConcurrency(declared, n);
-    const atOnce = runner.desktop === "e2b-desktop"
-        ? participantsAtOnce({ concurrency, declared: declared !== undefined, participants: n }, limit)
-        : { ok: true, count: concurrency };
+    const hosted = runner.desktop === "e2b-desktop";
+    const atOnce = participantsAtOnce({
+        concurrency: boundedConcurrency(declared, n),
+        declared: declared !== undefined,
+        participants: n,
+    }, {
+        ...(hosted ? { sandboxes: limits.concurrentSandboxes } : {}),
+        cap: limits.concurrencyCap,
+    });
     if (!atOnce.ok)
         return atOnce;
     const sessionMs = config.execution?.timeoutMs ?? defaultSessionTimeoutMs(config, ceilingMs);
     // A participant with a declared end gets a sandbox sized from its own window.
-    if (runner.desktop === "e2b-desktop") {
-        const headroomMs = resolveParticipantSandboxMs(config, ceilingMs) - sessionMs;
-        const window = windowDeadlineRefusal(runner.participants, { sessionMs, headroomMs }, ceilingMs);
+    if (hosted) {
+        const sandboxMs = resolveParticipantSandboxMs(config, ceilingMs);
+        const window = windowDeadlineRefusal(runner.participants, { sessionMs, sandboxMs }, ceilingMs);
         if (window !== undefined)
             return { ok: false, message: window };
     }
-    const slots = { slots: atOnce.count, sessionMs };
+    const { arrivals, warnings } = planStarts(runner.participants, { slots: atOnce.count, sessionMs }, atOnce.lowered);
+    const lowered = atOnce.loweredFrom;
     return {
         ok: true,
-        count: atOnce.count,
-        ...planStarts(runner.participants, slots, atOnce.lowered),
+        starts: {
+            concurrency: atOnce.count,
+            ...(lowered === undefined ? {} : { envLoweredConcurrencyFrom: lowered }),
+            arrivals,
+            sessionBudgetMs: sessionMs,
+        },
+        warnings,
     };
 }
 /** The plan's rerun: the source run and, when given, the participants to rerun. */
 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,7 +358,10 @@ 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 starts = startsOf(config, runner, input.concurrentSandboxes, ceiling.ms);
+    const unsupported = runnerRefusal(runner.desktop, participants);
+    if (unsupported)
+        return refuse("in-scope", unsupported.code, unsupported.message, actor);
+    const starts = startsOf(config, runner, input, ceiling.ms);
     if (!starts.ok)
         return refuse("after-personas", "HUMANISH_COMPUTER_USE_FANOUT_INVALID", starts.message, actor);
     const provisioned = source === "clone" || source === "local-tree";
@@ -324,9 +374,7 @@ export function planComputerUseStudy(config, input) {
             route: "computer-use",
             actor,
             runner,
-            concurrency: starts.count,
-            arrivals: starts.arrivals,
-            sessionBudgetMs: starts.arrivals.sessionMs,
+            ...starts.starts,
             sandboxMs: resolveParticipantSandboxMs(config, ceiling.ms),
             caps: planCaps(config),
             ...(input.rerun === undefined ? {} : { rerun: rerunPlan(input.rerun) }),

package/dist/routes/computer-use/rerun-selection.js

@@ -7,6 +7,7 @@ import {} from "../../run/streams.js";
 import { plural } from "../../run/text.js";
 import { access } from "node:fs/promises";
 import { cli } from "../../cli/invocation.js";
+import { startingWithTheRun } from "../../study/arrivals.js";
 export async function resolveCuaRerunSelection(args) {
     const { studyId, sourceRunId } = args;
     // Every refusal ends with the command that runs the whole study, which is what a user who
@@ -59,7 +60,7 @@ export async function resolveCuaRerunSelection(args) {
     }
     // A rerun runs the selected participants again now, all together: the study's start offsets
     // placed them in the first run's day, and that day is over.
-    const selectedSpecs = selectedIds.map((id) => startingWithTheRun(specsById.get(id)));
+    const selectedSpecs = selectedIds.map((id) => startingNow(specsById.get(id)));
     const selectedPlanIds = new Set(selectedIds);
     const selectedPlanEntries = args.participantPlan.lanes
         .filter((entry) => selectedPlanIds.has(entry.id))
@@ -86,11 +87,13 @@ export async function resolveCuaRerunSelection(args) {
         },
     };
 }
-function startingWithTheRun(spec) {
-    if (spec.planned.startAfterMs === undefined)
+function startingNow(spec) {
+    if (spec.planned.schedule.startAfterMs === undefined)
         return spec;
-    const { startAfterMs: _offset, ...planned } = spec.planned;
-    return { ...spec, planned };
+    return {
+        ...spec,
+        planned: { ...spec.planned, schedule: startingWithTheRun(spec.planned.schedule) },
+    };
 }
 function uniqueIds(values) {
     const seen = new Set();

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) {
@@ -107,7 +108,7 @@ export async function admitCuaRun(plan, input, config) {
         ? comms?.email?.external
         : undefined;
     const externalCommsEmail = externalCommsConfig ? comms?.email : undefined;
-    const participants = await loadCuaParticipants({ plan, cwd, projectRoot, env });
+    const participants = await loadCuaParticipants({ plan, cwd, projectRoot });
     if (!participants.ok) {
         return refuse(participants.code, participants.message, descriptor.id);
     }
@@ -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

@@ -5,6 +5,7 @@ import {} from "../../run/streams.js";
 import { aggregateTaskFunnels, formatParticipantOutcomes, formatRunTaskFunnel, participantSummary, withCuaReviewProvenance, } from "../../run/outcomes.js";
 import { participantCaption } from "../../run/participant-caption.js";
 import { actorEnding } from "../../actors/stop-cause.js";
+import { cuaGoalSource, ranUntilClockEnd } from "../../actors/goal-source.js";
 import { describeSubjectState, phaseEventIdSuffix, publicSafeAppUrlLabel, subjectProvenanceMessage, } from "./bundle-parts.js";
 import { participantFeedbackCandidates } from "./participant-feedback.js";
 import { judgeParticipantRecords } from "../../run/judge.js";
@@ -46,6 +47,7 @@ function runCost(args) {
 }
 /** The participant's status, reason, last frame, geometry and screenshot mode, shared by its records. */
 function participantView(args, publicAppUrl) {
+    const ranUntil = args.session === undefined ? undefined : ranUntilClockEnd(args.session.trace);
     const judgment = judgeParticipantRecords([
         {
             ...(args.session === undefined
@@ -55,6 +57,7 @@ function participantView(args, publicAppUrl) {
                     completionReason: args.session.completionReason,
                     reason: args.session.reason,
                 }),
+            ...(ranUntil === undefined ? {} : { ranUntil }),
             ...(args.sessionError === undefined ? {} : { sessionError: args.sessionError }),
             inProgress: args.inProgress === true,
             skipped: false,
@@ -151,6 +154,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,
@@ -296,8 +301,13 @@ function singleSummary(args, view, facts) {
             : `1 participant was planned, but the run failed before their session finished: ${view.reason}`;
     }
     const ending = actorEnding(args.session.trace);
+    const goalSource = cuaGoalSource(args.session.trace);
     const outcomes = formatParticipantOutcomes(view.tally, [
-        { status: args.session.status, ...(ending === undefined ? {} : { label: ending.label }) },
+        {
+            status: args.session.status,
+            ...(ending === undefined ? {} : { label: ending.label }),
+            ...(goalSource === undefined ? {} : { goalSource }),
+        },
     ]);
     return [
         `1 participant took part: ${outcomes}.`,

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

@@ -13,7 +13,7 @@ import { type CuaDiagnostics } from "./diagnostics.js";
 import type { ActorCompletionReason, ActorStatus, ActorStopCause, ActorTokenUsage, ActorTraceItem } from "../../actors/contract.js";
 import { type CuaActorDescriptor } from "../../actors/registry.js";
 import type { StudyDeps } from "../../study/study-deps.js";
-import type { ArrivalPlan, ParticipantArrival } from "../../study/arrivals.js";
+import type { ArrivalPlan, ParticipantArrival, ParticipantEnd } from "../../study/arrivals.js";
 import type { StudyEvent, ParticipantRef } from "../../study/run-study-events.js";
 import type { InProcessDriver, ProviderFactory, RunStudyHomes } from "../../study/run-study-homes.js";
 import { type BrowserScorer } from "../../study/adapter-extension.js";
@@ -23,15 +23,15 @@ import { type DesktopResourceObservation } from "../../substrates/e2b/desktop-re
 import { type DetachedTimers } from "../../substrates/detached.js";
 import type { Brain, ComputerUsePlan, ComputerUseRunner, ResidualConfig } from "../../study/plan-types.js";
 import { type StudyCommsEmail } from "../../study/types.js";
+import type { DesktopFile } from "../../study/desktop-files.js";
 import { type ObserverResult } from "../../observer/render.js";
 import { type BundleRun, type RunBundle, type RunRerunLineage, type RunScorerProvenance, type RunSubjectProvenance, type RunSubjectStateStepRecord } from "../../run/bundle.js";
-import { type RunDesktopGeometry } from "../../run/streams.js";
+import { type RunDesktopFile, type RunDesktopGeometry } from "../../run/streams.js";
 import { type PreparedOutputRoot } from "../../run/contained-output.js";
 import type { ComputerUseParticipant, SharedWorldParticipant } from "../../study/plan-participants.js";
 import type { ResolvedParticipant } from "../../run/participant.js";
 import { type StudyResultErrorCode, type StudyResultIdentity } from "../../run/study-result.js";
 export declare const CUA_FANOUT_STRATEGY: "per-lane-worlds";
-export declare const CUA_MAX_CONCURRENCY_ENV = "HUMANISH_CUA_MAX_CONCURRENCY";
 export declare const DEFAULT_APP_URL_SESSION_TIMEOUT_MS: number;
 export declare const MIN_DERIVED_SESSION_TIMEOUT_MS: number;
 /**
@@ -114,6 +114,8 @@ export interface CuaParticipantPlanEntry {
     startAfterMs?: number;
     /** The participant's declared end, on the same clock. */
     endAfterMs?: number;
+    /** The participant's session cap, from the start of its session. */
+    maxSessionMs?: number;
 }
 /** The pre-flight spend and participant plan (pure; printed to stderr + recorded as a bundle event before
  *  any sandbox or provider call; identical in dry-run, marked $0). */
@@ -123,8 +125,8 @@ export interface CuaParticipantPlan {
     /** Effective in-flight bound (defaults to laneCount, all participants live; a declared
      *  execution.concurrency is a cap; the env override may only lower it). */
     concurrency: number;
-    /** Present when the env override lowered the bound below the config's value, recorded so the
-     *  plan never silently disagrees with the manifest. */
+    /** Present when HUMANISH_CUA_MAX_CONCURRENCY lowered the bound (the plan's
+     *  envLoweredConcurrencyFrom), recorded so the plan never silently disagrees with the manifest. */
     envLoweredConcurrencyFrom?: number;
     /** ceil(laneCount / concurrency). */
     waves: number;
@@ -195,7 +197,7 @@ export interface CuaParticipantSummary {
     concurrency: number;
     waves: number;
 }
-export type CuaActorStudyErrorCode = StudyResultErrorCode | "HUMANISH_COMPUTER_USE_FAILED" | "HUMANISH_COMPUTER_USE_KEYS_MISSING" | "HUMANISH_COMPUTER_USE_AGENT_MISSING" | "HUMANISH_COMPUTER_USE_AGENT_SIGNIN_REQUIRED" | "HUMANISH_COMPUTER_USE_SUBJECT_ENV_MISSING" | "HUMANISH_COMPUTER_USE_ACTOR_UNSUPPORTED" | "HUMANISH_COMPUTER_USE_SUBJECT_INVALID" | "HUMANISH_COMPUTER_USE_SUBJECT_UNSAFE" | "HUMANISH_COMPUTER_USE_EXECUTOR_NO_PROVIDER" | "HUMANISH_COMPUTER_USE_LOCAL_APP_NO_EXECUTOR" | "HUMANISH_COMPUTER_USE_LOCAL_DESKTOP_MISSING" | "HUMANISH_COMPUTER_USE_LOCAL_CAPACITY_EXCEEDED" | "HUMANISH_COMPUTER_USE_DESKTOP_OUT_OF_MEMORY" | "HUMANISH_COMPUTER_USE_FANOUT_INVALID" | "HUMANISH_COMPUTER_USE_RERUN_INVALID" | "HUMANISH_COMPUTER_USE_DEVICE_GEOMETRY" | "HUMANISH_COMPUTER_USE_SUBJECT_BUILD_FAILED" | "HUMANISH_COMPUTER_USE_UNPRICED_CAP" | "HUMANISH_COMPUTER_USE_COMMS_CATCH_UNREACHABLE" | "HUMANISH_COMPUTER_USE_COMMS_TOKEN_INVALID" | "HUMANISH_WATCH_ALLOW_REQUIRES_OAUTH" | "HUMANISH_WATCH_OAUTH_REQUIRES_TUNNEL" | "HUMANISH_WATCH_OPTION_CONFLICT" | "HUMANISH_WATCH_TUNNEL_REQUIRES_EXPOSE" | "HUMANISH_WATCH_EXPOSE_REQUIRES_EDGE_AUTH" | "HUMANISH_WATCH_EXPOSE_REQUIRES_LIVE_FOLLOW" | "HUMANISH_WATCH_SAFE_NOT_APPLICABLE" | "HUMANISH_SERVE_TUNNEL_NOT_FOUND" | "HUMANISH_SERVE_TUNNEL_START_FAILED";
+export type CuaActorStudyErrorCode = StudyResultErrorCode | "HUMANISH_COMPUTER_USE_FAILED" | "HUMANISH_COMPUTER_USE_KEYS_MISSING" | "HUMANISH_COMPUTER_USE_AGENT_MISSING" | "HUMANISH_COMPUTER_USE_AGENT_SIGNIN_REQUIRED" | "HUMANISH_COMPUTER_USE_SUBJECT_ENV_MISSING" | "HUMANISH_COMPUTER_USE_ACTOR_UNSUPPORTED" | "HUMANISH_COMPUTER_USE_SUBJECT_INVALID" | "HUMANISH_COMPUTER_USE_SUBJECT_UNSAFE" | "HUMANISH_COMPUTER_USE_EXECUTOR_NO_PROVIDER" | "HUMANISH_COMPUTER_USE_LOCAL_APP_NO_EXECUTOR" | "HUMANISH_COMPUTER_USE_LOCAL_DESKTOP_MISSING" | "HUMANISH_COMPUTER_USE_LOCAL_CAPACITY_EXCEEDED" | "HUMANISH_COMPUTER_USE_DESKTOP_OUT_OF_MEMORY" | "HUMANISH_COMPUTER_USE_DESKTOP_FILES_INVALID" | "HUMANISH_COMPUTER_USE_TIME_ZONE_UNSUPPORTED" | "HUMANISH_COMPUTER_USE_FANOUT_INVALID" | "HUMANISH_COMPUTER_USE_RERUN_INVALID" | "HUMANISH_COMPUTER_USE_DEVICE_GEOMETRY" | "HUMANISH_COMPUTER_USE_SUBJECT_BUILD_FAILED" | "HUMANISH_COMPUTER_USE_UNPRICED_CAP" | "HUMANISH_COMPUTER_USE_COMMS_CATCH_UNREACHABLE" | "HUMANISH_COMPUTER_USE_COMMS_TOKEN_INVALID" | "HUMANISH_WATCH_ALLOW_REQUIRES_OAUTH" | "HUMANISH_WATCH_OAUTH_REQUIRES_TUNNEL" | "HUMANISH_WATCH_OPTION_CONFLICT" | "HUMANISH_WATCH_TUNNEL_REQUIRES_EXPOSE" | "HUMANISH_WATCH_EXPOSE_REQUIRES_EDGE_AUTH" | "HUMANISH_WATCH_EXPOSE_REQUIRES_LIVE_FOLLOW" | "HUMANISH_WATCH_SAFE_NOT_APPLICABLE" | "HUMANISH_SERVE_TUNNEL_NOT_FOUND" | "HUMANISH_SERVE_TUNNEL_START_FAILED";
 export interface CuaActorStudyResult extends AutomaticAnalysisResult, StudyResultIdentity<"computer-use"> {
     /** True when the Observer verified the bundle, all live participants passed credibility checks
      * (or this is a dry-run), and no declared adapter/scorer verdict failed. */
@@ -316,6 +318,9 @@ export interface E2BDesktopDeps {
     /** Local-tree route only: the once-per-run packed archive bytes, shared byte-identically
      *  across every fan-out participant's upload step. Absent on dry-run and every other route. */
     localTreeArchiveBuffer?: ArrayBuffer;
+    /** Computer use on a hosted desktop: each participant's files (participants[].files) by id,
+     *  read on this machine before any sandbox. A participant without an entry receives none. */
+    desktopFiles?: ReadonlyMap<string, readonly DesktopFile[]>;
     env: Record<string, string | undefined>;
     e2bApiKey: string;
     requestTimeoutMs: number;
@@ -367,14 +372,12 @@ export interface ParticipantModelDeps {
     openaiApiKey: string;
     timeoutMs: number;
     /**
-     * The participant's scheduled end on `now`'s clock, when it declares participants[].endAfterMs
-     * (scheduledParticipantDeps). Its session ends there with stop cause `scheduled_end`.
+     * How the participant's session ends, when it declares participants[].endAfterMs or maxSessionMs
+     * (scheduledParticipantDeps): at its scheduled end on `now`'s clock, with stop cause
+     * `scheduled_end`, or at its cap after the session starts, with stop cause `session_cap`.
      */
-    scheduledEnd?: {
-        readonly atMs: number;
-        readonly windDownMs: number;
-    };
-    /** The run's clock. A participant with a scheduled end runs its session on it. */
+    end?: ParticipantEnd;
+    /** The run's clock. A participant with an end or a cap runs its session on it. */
     now: () => number;
     participantCount: number;
     artifactRoot: PreparedOutputRoot;
@@ -449,6 +452,8 @@ export interface ParticipantRunOutcome {
     /** Requested + measured desktop/browser geometry. Viewport is absent when measurement failed. */
     desktopGeometry?: RunDesktopGeometry;
     recording?: RunDesktopRecording;
+    /** participants[].files confirmed on the participant's desktop. */
+    desktopFiles?: RunDesktopFile[];
     stateStepRecords: RunSubjectStateStepRecord[];
     /** Completed subject-phase records (clone/upload/extract/install/build/ready/state groups),
      *  folded into bundle.events at build time. Empty on the in-process route (no provisioning). */

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

@@ -15,9 +15,6 @@ import {} from "../../run/study-result.js";
 // The fan-out topology of this route: N participants = N independent E2B desktop sandboxes,
 // each its own world (clone/serve + subject.state per participant). Shared-world has its own route.
 export const CUA_FANOUT_STRATEGY = "per-lane-worlds";
-// Env override that may only lower the effective concurrency (never raise concurrent paid
-// desktops). Read names-only into a local; the value never persists.
-export const CUA_MAX_CONCURRENCY_ENV = "HUMANISH_CUA_MAX_CONCURRENCY";
 // The default session budget, sized so a study can finish (docs/principles/three-roles.md: a
 // session ends because the participant is done, not because a timer fired; the time-box is a
 // session-level cap a researcher sets generously; spend protection is the dollar caps' job).