humanish 0.126.0 → 0.127.0

package/dist/study/bundle-estimate.js

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

package/dist/study/desktop-files.js

@@ -32,18 +32,18 @@ export function parseParticipantFiles(raw, field) {
         if (from === undefined || as === undefined)
             return invalid(listReason);
         if (!isPlainRelativePath(from))
-            return invalid(`\`${at}.from\` must be a path inside the folder that holds the study file, written relative to it, such as fixtures/insurance-card.png, with / between folders and no empty, . or .. part.`);
+            return invalid(`\`${at}.from\` must be a path inside the folder that holds the study file, written relative to it, such as fixtures/photo.png, with / between folders and no empty, . or .. part.`);
         if (isLocalTreeDenylisted(from))
             return invalid(`\`${at}.from\` names a file humanish keeps on this machine: a .env file, a key, a credential file, or one under .git, node_modules or .humanish. The local-tree archive leaves the same files out. Copy a synthetic file instead.`);
         if (!isPlainRelativePath(as) || as.startsWith("~"))
-            return invalid(`\`${at}.as\` must be a path relative to the desktop user's home folder, such as Downloads/insurance-card.png, with / between folders, no empty, . or .. part, and no leading ~.`);
+            return invalid(`\`${at}.as\` must be a path relative to the desktop user's home folder, such as Downloads/photo.png, with / between folders, no empty, . or .. part, and no leading ~.`);
         if (isHumanishDesktopPath(as))
-            return invalid(`\`${at}.as\` is a path humanish uses on the desktop: ${SUBJECT_FOLDER}/ holds the cloned or unpacked app, and names that start with .humanish are humanish's own files. Pick another path, such as Downloads/insurance-card.png.`);
+            return invalid(`\`${at}.as\` is a path humanish uses on the desktop: ${SUBJECT_FOLDER}/ holds the cloned or unpacked app, and names that start with .humanish are humanish's own files. Pick another path, such as Downloads/photo.png.`);
         // The run records `as`, and redacting it would record a different path. Encoded text the
         // public-safety scan cannot read would leave run.json unscanned.
         const scanned = scanEncodedText(as);
         if (scanned.sensitive || scanned.opaque)
-            return invalid(`\`${at}.as\` looks like a secret, a local path or encoded text, and the run records it. Name the file plainly, such as Downloads/insurance-card.png.`);
+            return invalid(`\`${at}.as\` looks like a secret, a local path or encoded text, and the run records it. Name the file plainly, such as Downloads/photo.png.`);
         const clash = files.find((earlier) => earlier.as === as || as.startsWith(`${earlier.as}/`) || earlier.as.startsWith(`${as}/`));
         if (clash !== undefined)
             return invalid(clash.as === as

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

@@ -1,3 +1,4 @@
+import { type ParticipantSchedule } from "./arrivals.js";
 import type { DwellWindow, StopWhen } from "../actors/stop-conditions.js";
 import type { ReasoningEffort } from "../actors/reasoning-effort.js";
 import { type DevicePreset } from "./device-presets.js";
@@ -49,17 +50,11 @@ export interface DesktopParticipant extends Participant {
          */
         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;
-    /** 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).
+     * When it starts and, on computer use, how its session ends: its startAfterMs, and its endAfterMs
+     * or maxSessionMs with its wind-down.
      */
-    readonly windDownMs?: number;
+    readonly schedule: ParticipantSchedule;
 }
 /** Only independent computer-use participants consume a task protocol and their own target. */
 export interface ComputerUseParticipant extends DesktopParticipant {

package/dist/study/plan-participants.js

@@ -1,6 +1,6 @@
 // Who takes part in a study: one record per participant, built from the declared roster or a count.
 // Computer-use and shared-world participants share the desktop fields; each kind adds its own.
-import { DEFAULT_WIND_DOWN_MS } from "./arrivals.js";
+import { participantSchedule } from "./arrivals.js";
 import { resolveParticipantDevice } from "./device-presets.js";
 import { computerUseParticipantCount, isSharedWorldComposition, participantIdAt, } from "./routing.js";
 import { participantList, declaredParticipantCount, participantInstruction, } from "./study-fields.js";
@@ -39,19 +39,7 @@ function desktopParticipant(config, entry, index, kind, focus) {
             ...(idleWaitMs === undefined ? {} : { idleWaitMs }),
             ...(timeZone === undefined ? {} : { timeZone }),
         },
-        ...(entry?.startAfterMs === undefined ? {} : { startAfterMs: entry.startAfterMs }),
-        ...(entry?.endAfterMs === undefined
-            ? {}
-            : {
-                endAfterMs: entry.endAfterMs,
-                windDownMs: entry.windDownMs ?? DEFAULT_WIND_DOWN_MS,
-            }),
-        ...(entry?.maxSessionMs === undefined
-            ? {}
-            : {
-                maxSessionMs: entry.maxSessionMs,
-                windDownMs: entry.windDownMs ?? DEFAULT_WIND_DOWN_MS,
-            }),
+        schedule: participantSchedule(entry ?? {}),
     };
 }
 /**

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

@@ -163,8 +163,13 @@ export interface ComputerUsePlan extends PlanBase {
     /** The registered computer-use actor id. */
     readonly actor: string;
     readonly runner: ComputerUseRunner;
-    /** Declared cap clamped to [1, participants]; the route may only lower it from env. */
+    /**
+     * How many participants run at once: the declared cap clamped to [1, participants], else all of
+     * them, lowered to what the E2B plan and HUMANISH_CUA_MAX_CONCURRENCY allow (participantsAtOnce).
+     */
     readonly concurrency: number;
+    /** The count before HUMANISH_CUA_MAX_CONCURRENCY lowered it, when it did. */
+    readonly envLoweredConcurrencyFrom?: number;
     /** When the participants start and how many run at once, with every session at its budget. */
     readonly arrivals: ArrivalPlan;
     readonly sessionBudgetMs: number;

package/dist/study/plan.d.ts

@@ -8,7 +8,8 @@ export declare function resolveStudyDryRun(config: StudyConfig, override: boolea
 /**
  * The plan a study runs under, built without reading files or the network. From the environment
  * (options.env, else process.env, as the routes read it) it reads the operator's E2B plan limits,
- * the sandbox ceiling and the concurrent sandboxes, which no study file can know. Each route's
+ * the sandbox ceiling and the concurrent sandboxes, and HUMANISH_CUA_MAX_CONCURRENCY, which no
+ * study file can know. Each route's
  * planner makes every refusal that route makes, in the route's order and with its codes and
  * messages; the route's exported runner calls the same planner.
  */

package/dist/study/plan.js

@@ -6,7 +6,7 @@ import { callerDrivingOf, planComputerUseStudy } from "../routes/computer-use/pl
 import { injectedBrowser, planScriptedStudy } from "../routes/scripted/plan.js";
 import { planSharedWorldStudy } from "../routes/shared-world/plan.js";
 import { planTerminalStudy } from "../routes/terminal/plan.js";
-import { concurrentSandboxes, sandboxCeiling, } from "../substrates/e2b/lifetime.js";
+import { concurrencyCap, concurrentSandboxes, sandboxCeiling, } from "../substrates/e2b/lifetime.js";
 import { localBrowserDefaults } from "../substrates/local/runtime-config.js";
 import { THIS_REPO_DRY_RUN_ONLY } from "./composition-rules.js";
 import { bundleLimitReason, estimateBundle } from "./bundle-estimate.js";
@@ -68,7 +68,8 @@ function planPreview(config, options, input) {
 /**
  * The plan a study runs under, built without reading files or the network. From the environment
  * (options.env, else process.env, as the routes read it) it reads the operator's E2B plan limits,
- * the sandbox ceiling and the concurrent sandboxes, which no study file can know. Each route's
+ * the sandbox ceiling and the concurrent sandboxes, and HUMANISH_CUA_MAX_CONCURRENCY, which no
+ * study file can know. Each route's
  * planner makes every refusal that route makes, in the route's order and with its codes and
  * messages; the route's exported runner calls the same planner.
  */
@@ -79,6 +80,7 @@ export function planStudy(config, options, deps = {}) {
     const e2b = {
         sandboxCeiling: sandboxCeiling(env),
         concurrentSandboxes: concurrentSandboxes(env),
+        concurrencyCap: concurrencyCap(env),
     };
     const result = planRoute(routeOf(config), study, options, input, deps, e2b);
     if (!result.ok)
@@ -125,8 +127,8 @@ function closingReportWarnings(plan) {
     if (brain.kind !== "local-agent" || brain.agent !== "claude")
         return [];
     const { participants } = plan.runner;
-    const scheduled = participants.filter((participant) => participant.endAfterMs !== undefined);
-    const capped = participants.filter((participant) => participant.maxSessionMs !== undefined);
+    const scheduled = participants.filter(({ schedule }) => schedule.end?.kind === "scheduled_end");
+    const capped = participants.filter(({ schedule }) => schedule.end?.kind === "session_cap");
     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 [

package/dist/study/types.d.ts

@@ -355,7 +355,8 @@ export interface StudyParticipantEntry {
     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).
+     * end time and the minutes left. Default: a quarter of the participant's window or cap, at most
+     * 600000 (10 minutes).
      */
     windDownMs?: number;
     /**

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

@@ -45,14 +45,24 @@ export type ConcurrentSandboxes = {
 export declare function concurrentSandboxes(env: Readonly<Record<string, string | undefined>>): ConcurrentSandboxes;
 /** The limit in use and where it came from, or why the setting cannot be read (doctor's row). */
 export declare function describeConcurrentSandboxes(limit: ConcurrentSandboxes): string;
+/** The setting that lowers how many participants a study runs at once, on any desktop. */
+export declare const CUA_MAX_CONCURRENCY_ENV = "HUMANISH_CUA_MAX_CONCURRENCY";
 /**
- * How many participants a hosted study runs at once: its `concurrency` (the declared
- * execution.concurrency clamped to the roster, else every participant), lowered to what the plan
- * runs. `declared` says whether the study set it. `alongside` counts the sandboxes the study keeps
- * for the whole run besides its participants' desktops, such as a shared world's app, and
- * `minimum` is the fewest at once the route can run. A declared value that does not fit is a
- * refusal naming the setting value that admits it. `lowered` is the warning a plan records when
- * the limit holds an undeclared default to waves.
+ * HUMANISH_CUA_MAX_CONCURRENCY when it is a whole number of 1 or more, else undefined: the
+ * operator's own bound on participants at once on this machine, which may only lower a study's.
+ * Any other value is ignored.
+ */
+export declare function concurrencyCap(env: Readonly<Record<string, string | undefined>>): number | undefined;
+/**
+ * How many participants a study runs at once: its `concurrency` (the declared
+ * execution.concurrency clamped to the roster, else every participant), lowered to `cap`
+ * (concurrencyCap) and then to what the E2B plan runs (`sandboxes`, on a hosted desktop).
+ * `declared` says whether the study set it. `alongside` counts the sandboxes the study keeps for
+ * the whole run besides its participants' desktops, such as a shared world's app, and `minimum` is
+ * the fewest at once the route can run. A declared value the E2B plan cannot run, or a cap under
+ * `minimum`, is a refusal naming the setting. `lowered` is the warning a plan records when the cap
+ * or the E2B limit lowers the count; when both do, it is the E2B limit's, since that sets the
+ * count. `loweredFrom` is the count the cap lowered, when the cap sets the count.
  */
 export declare function participantsAtOnce(study: {
     readonly concurrency: number;
@@ -60,10 +70,14 @@ export declare function participantsAtOnce(study: {
     readonly participants: number;
     readonly alongside?: number;
     readonly minimum?: number;
-}, limit: ConcurrentSandboxes): {
+}, limits: {
+    readonly sandboxes?: ConcurrentSandboxes;
+    readonly cap?: number | undefined;
+}): {
     readonly ok: true;
     readonly count: number;
     readonly lowered?: string;
+    readonly loweredFrom?: number;
 } | {
     readonly ok: false;
     readonly message: string;

package/dist/substrates/e2b/lifetime.js

@@ -1,5 +1,6 @@
 // The operator's E2B plan limits humanish plans against: how long a sandbox may live and how many
-// run at once. Also the budgets the desktop routes add to a participant's own deadline when they set
+// run at once, with the operator's own bound on participants at once (HUMANISH_CUA_MAX_CONCURRENCY).
+// Also the budgets the desktop routes add to a participant's own deadline when they set
 // a sandbox's server-side timeout. A dead host process can never orphan a sandbox past that
 // timeout, so every route derives it from these values.
 import { plural } from "../../run/text.js";
@@ -88,19 +89,62 @@ export function describeConcurrentSandboxes(limit) {
     if (!limit.ok)
         return limit.message;
     return limit.source === "setting"
-        ? `${limit.count} at once, from ${CONCURRENCY_SETTING}. A study that runs more desktops at once runs them in waves, and an execution.concurrency above it is refused before any sandbox is created.`
+        ? `${limit.count} at once, from ${CONCURRENCY_SETTING}. A study that runs more desktops at once runs them in waves, and an execution.concurrency above it is refused before any sandbox is created, unless ${CUA_MAX_CONCURRENCY_ENV} lowers it to the limit or below.`
         : `${limit.count} at once, E2B's Hobby limit. On a plan that runs more (Pro runs ${PRO_CONCURRENT_SANDBOXES}), set ${CONCURRENCY_SETTING} to that plan's limit.`;
 }
+/** The setting that lowers how many participants a study runs at once, on any desktop. */
+export const CUA_MAX_CONCURRENCY_ENV = "HUMANISH_CUA_MAX_CONCURRENCY";
 /**
- * How many participants a hosted study runs at once: its `concurrency` (the declared
- * execution.concurrency clamped to the roster, else every participant), lowered to what the plan
- * runs. `declared` says whether the study set it. `alongside` counts the sandboxes the study keeps
- * for the whole run besides its participants' desktops, such as a shared world's app, and
- * `minimum` is the fewest at once the route can run. A declared value that does not fit is a
- * refusal naming the setting value that admits it. `lowered` is the warning a plan records when
- * the limit holds an undeclared default to waves.
+ * HUMANISH_CUA_MAX_CONCURRENCY when it is a whole number of 1 or more, else undefined: the
+ * operator's own bound on participants at once on this machine, which may only lower a study's.
+ * Any other value is ignored.
  */
-export function participantsAtOnce(study, limit) {
+export function concurrencyCap(env) {
+    const cap = readPositiveInt(env[CUA_MAX_CONCURRENCY_ENV], 0);
+    return cap > 0 ? cap : undefined;
+}
+/**
+ * How many participants a study runs at once: its `concurrency` (the declared
+ * execution.concurrency clamped to the roster, else every participant), lowered to `cap`
+ * (concurrencyCap) and then to what the E2B plan runs (`sandboxes`, on a hosted desktop).
+ * `declared` says whether the study set it. `alongside` counts the sandboxes the study keeps for
+ * the whole run besides its participants' desktops, such as a shared world's app, and `minimum` is
+ * the fewest at once the route can run. A declared value the E2B plan cannot run, or a cap under
+ * `minimum`, is a refusal naming the setting. `lowered` is the warning a plan records when the cap
+ * or the E2B limit lowers the count; when both do, it is the E2B limit's, since that sets the
+ * count. `loweredFrom` is the count the cap lowered, when the cap sets the count.
+ */
+export function participantsAtOnce(study, limits) {
+    const capped = cappedAtOnce(study, limits.cap);
+    if (!capped.ok || limits.sandboxes === undefined)
+        return capped;
+    // A count the cap lowered is the operator's bound and no longer the study's declared value, so
+    // the E2B limit runs it in waves as it would an undeclared default.
+    const left = capped.loweredFrom === undefined
+        ? study
+        : { ...study, concurrency: capped.count, declared: false };
+    const planned = sandboxesAtOnce(left, limits.sandboxes);
+    return !planned.ok || planned.count < capped.count ? planned : capped;
+}
+/** participantsAtOnce under the cap alone. */
+function cappedAtOnce(study, cap) {
+    if (cap === undefined || cap >= study.concurrency)
+        return { ok: true, count: study.concurrency };
+    const minimum = study.minimum ?? 1;
+    if (cap < minimum)
+        return {
+            ok: false,
+            message: `This study runs at least ${minimum} participants at once, and ${CUA_MAX_CONCURRENCY_ENV} allows ${cap}. Set it to ${minimum} or more, or unset it.`,
+        };
+    return {
+        ok: true,
+        count: cap,
+        loweredFrom: study.concurrency,
+        lowered: `This study's ${study.participants} participants run ${cap} at a time, because ${CUA_MAX_CONCURRENCY_ENV} is ${cap}.`,
+    };
+}
+/** participantsAtOnce under the E2B plan's limit alone. */
+function sandboxesAtOnce(study, limit) {
     if (!limit.ok)
         return limit;
     const alongside = study.alongside ?? 0;

package/docs/contracts/run-bundle.md

@@ -462,7 +462,7 @@ started, in the order they landed.
 
 ```yaml
 desktopFiles:
-  - as: Downloads/insurance-card.png
+  - as: Downloads/photo.png
     size: 251
     sha256: <64 hex characters>
 ```