humanish 0.116.0 → 0.118.0

package/dist/study/plan-participants.js

@@ -1,7 +1,7 @@
 // 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 { resolveParticipantDevice } from "./device-presets.js";
-import { isSharedWorldComposition, participantIdAt } from "./routing.js";
+import { computerUseParticipantCount, isSharedWorldComposition, participantIdAt, } from "./routing.js";
 import { participantList, declaredParticipantCount, participantInstruction, } from "./study-fields.js";
 function desktopParticipant(config, entry, index, kind, focus) {
     const actor = config.actor;
@@ -12,6 +12,8 @@ function desktopParticipant(config, entry, index, kind, focus) {
     const dwell = entry?.dwell ?? actor?.dwell;
     const reasoningEffort = entry?.reasoningEffort ?? actor?.reasoningEffort;
     const maxOutputTokens = actor?.maxOutputTokens;
+    const maxWaitMs = actor?.maxWaitMs;
+    const idleWaitMs = actor?.idleWaitMs;
     return {
         id: participantIdAt(index, entry?.id, kind),
         index,
@@ -31,6 +33,8 @@ function desktopParticipant(config, entry, index, kind, focus) {
             ...(dwell === undefined ? {} : { dwell }),
             ...(reasoningEffort === undefined ? {} : { reasoningEffort }),
             ...(maxOutputTokens === undefined ? {} : { maxOutputTokens }),
+            ...(maxWaitMs === undefined ? {} : { maxWaitMs }),
+            ...(idleWaitMs === undefined ? {} : { idleWaitMs }),
         },
     };
 }
@@ -41,10 +45,7 @@ function desktopParticipant(config, entry, index, kind, focus) {
 export function computerUseParticipants(config, countOverride) {
     const actor = config.actor;
     const roster = participantList(config);
-    const count = roster
-        ? roster.length
-        : Math.max(1, countOverride ?? declaredParticipantCount(config) ?? 1);
-    return Array.from({ length: count }, (_, index) => {
+    return Array.from({ length: computerUseParticipantCount(config, countOverride) }, (_, index) => {
         const entry = roster?.[index];
         const focus = roster ? entry?.instruction : participantInstruction(config);
         return {

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

@@ -57,13 +57,17 @@ export interface PlannedAnalysis {
     /** "default" when the study declared no review.analysis. */
     readonly trigger: "default" | "explicit";
     readonly preferLargerOutput: boolean;
+    /** Set when the study has more participants than one analysis reads: a live run records the
+     *  analysis as skipped for this reason and never starts it. */
+    readonly skip?: "AUTOMATIC_ANALYSIS_PARTICIPANT_LIMIT";
 }
 interface PlanBase {
     readonly studyId: string;
     /** The study's declared title, which bundles record. */
     readonly title?: string;
     readonly study?: RunStudyProvenance;
-    /** Warnings about the study's own fields, which the run records in its bundle as warn events. */
+    /** Warnings about the study's own fields and the plan made from them, which the run records in
+     *  its bundle as warn events. */
     readonly warnings?: readonly string[];
     /** A frozen copy owned by the plan. */
     readonly residual: Readonly<ResidualConfig>;
@@ -258,9 +262,10 @@ export interface ScriptedPlan extends PlanBase {
     readonly scenarioRef: string;
     /** Empty only for a library caller's `count: 0`, which the parser refuses; that run has no sessions. */
     readonly surfaces: readonly BrowserSurface[];
-    /** The declared persona and session timeout; the route supplies its defaults. */
+    /** The declared persona; the route supplies its default. */
     readonly personaId?: string;
-    readonly sessionTimeoutMs?: number;
+    /** Each surface's journey budget: execution.timeoutMs, else 5 minutes. */
+    readonly sessionTimeoutMs: number;
 }
 export type StudyPlan = PreviewPlan | ComputerUsePlan | SharedWorldPlan | TerminalPlan | ScriptedPlan;
 interface PlannedStudy {

package/dist/study/plan.d.ts

@@ -7,9 +7,9 @@ export { routeOf, type StudyRoute } from "./routing.js";
 export declare function resolveStudyDryRun(config: StudyConfig, override: boolean | undefined, fallback: boolean | undefined): boolean | undefined;
 /**
  * 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 one value, the E2B sandbox
- * ceiling, 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.
+ * (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
+ * 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.
  */
 export declare function planStudy(config: StudyConfig, options: InternalRunStudyOptions, deps?: StudyDeps): PlanResult;

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 { sandboxCeiling } from "../substrates/e2b/lifetime.js";
+import { 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 { planBase } from "./plan-base.js";
@@ -65,21 +65,25 @@ 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 one value, the E2B sandbox
- * ceiling, 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.
+ * (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
+ * 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.
  */
 export function planStudy(config, options, deps = {}) {
     const study = localBrowserDefaults(config);
     const input = { dryRun: resolveStudyDryRun(study, options.dryRun, true) ?? true };
-    const ceiling = sandboxCeiling(options.env ?? process.env);
-    const result = planRoute(routeOf(config), study, options, input, deps, ceiling);
+    const env = options.env ?? process.env;
+    const e2b = {
+        sandboxCeiling: sandboxCeiling(env),
+        concurrentSandboxes: concurrentSandboxes(env),
+    };
+    const result = planRoute(routeOf(config), study, options, input, deps, e2b);
     if (!result.ok)
         return result;
     // The manifest the CLI resolved enters the plan here and nowhere else; the routes read
     // plan.study for the run's status record and bundle, and plan.warnings for its bundle events.
-    const warnings = recordedStudyWarnings(study);
+    const warnings = [...recordedStudyWarnings(study), ...(result.plan.warnings ?? [])];
     const plan = {
         ...result.plan,
         ...(options.study === undefined ? {} : { study: options.study }),
@@ -87,7 +91,8 @@ export function planStudy(config, options, deps = {}) {
     };
     return { ok: true, planned: { plan } };
 }
-function planRoute(route, study, options, input, deps, sandboxCeiling) {
+function planRoute(route, study, options, input, deps, e2b) {
+    const { sandboxCeiling } = e2b;
     switch (route) {
         case "preview":
             return planPreview(study, options, input);
@@ -98,13 +103,13 @@ function planRoute(route, study, options, input, deps, sandboxCeiling) {
                 driving: callerDrivingOf(options),
                 ...(options.count === undefined ? {} : { countOverride: options.count }),
                 ...(options.rerun === undefined ? {} : { rerun: options.rerun }),
-                sandboxCeiling,
+                ...e2b,
             });
         case "shared-world":
             return planSharedWorldStudy(study, {
                 ...input,
                 hasRunSession: deps.runSession !== undefined,
-                sandboxCeiling,
+                ...e2b,
             });
         case "terminal":
             return planTerminalStudy(study, {
@@ -113,6 +118,10 @@ function planRoute(route, study, options, input, deps, sandboxCeiling) {
                 sandboxCeiling,
             });
         case "scripted":
-            return planScriptedStudy(study, { ...input, injectedBrowser: injectedBrowser(deps) });
+            return planScriptedStudy(study, {
+                ...input,
+                injectedBrowser: injectedBrowser(deps),
+                sandboxCeiling,
+            });
     }
 }

package/dist/study/preflight-result.js

@@ -1,13 +1,13 @@
 // The preflight result a run returns, built from its context. preflight.ts and the probes in
 // preflight-probes.ts both finish through these, so they live below both.
-import { automaticAnalysisBudget } from "../analysis/automatic-config.js";
+import { studyAnalysisBudget } from "./automatic-analysis-plan.js";
 import { digestText } from "../evidence/redaction.js";
 import { computerUseParticipantCount } from "./routing.js";
 /** The schema of `study check` results: whether a study is ready to run on this machine. */
 export const STUDY_CHECK_SCHEMA = "humanish.study-check.v1";
 export function finalize(ctx, args) {
     const checks = [...ctx.checks, ...(args?.check ? [args.check] : []), ...(args?.checks ?? [])];
-    const analysis = automaticAnalysisBudget(ctx.config.review?.analysis, ctx.route, computerUseParticipantCount(ctx.config));
+    const analysis = studyAnalysisBudget(ctx.config.review?.analysis, ctx.route, computerUseParticipantCount(ctx.config));
     return {
         schema: STUDY_CHECK_SCHEMA,
         ...(analysis ? { analysis } : {}),

package/dist/study/preflight.d.ts

@@ -3,6 +3,7 @@ import type { E2BDesktopModule } from "../substrates/e2b/sdk.js";
 import { type StudyConfig } from "./types.js";
 import { STUDY_CHECK_SCHEMA } from "./preflight-result.js";
 import { type StudyRoute } from "./plan.js";
+import type { PlanRefusal } from "./plan-types.js";
 import { type StudyResolveFailure } from "./discover.js";
 export type StudyPreflightReachabilityMode = "metadata" | "public-preview" | "sandbox-loopback" | "prepared-host";
 export interface StudyPreflightCheck {
@@ -57,7 +58,7 @@ export interface StudyPreflightResult {
     spend: StudyPreflightSpend;
     warnings: string[];
     error?: {
-        code: StudyResolveFailure["error"]["code"] | "HUMANISH_STUDY_PREFLIGHT_INVALID_OPTION" | "HUMANISH_STUDY_PREFLIGHT_UNSUPPORTED_ROUTE" | "HUMANISH_STUDY_PREFLIGHT_TARGET_POLICY" | "HUMANISH_STUDY_PREFLIGHT_ENV_MISSING" | "HUMANISH_STUDY_PREFLIGHT_E2B_REQUIRED" | "HUMANISH_STUDY_PREFLIGHT_TARGET_UNREACHABLE" | "HUMANISH_STUDY_PREFLIGHT_PROVISION_FAILED" | "HUMANISH_STUDY_PREFLIGHT_TEARDOWN_FAILED";
+        code: StudyResolveFailure["error"]["code"] | "HUMANISH_STUDY_PREFLIGHT_INVALID_OPTION" | "HUMANISH_STUDY_PREFLIGHT_UNSUPPORTED_ROUTE" | "HUMANISH_STUDY_PREFLIGHT_TARGET_POLICY" | "HUMANISH_STUDY_PREFLIGHT_ENV_MISSING" | "HUMANISH_STUDY_PREFLIGHT_E2B_REQUIRED" | "HUMANISH_STUDY_PREFLIGHT_TARGET_UNREACHABLE" | "HUMANISH_STUDY_PREFLIGHT_PROVISION_FAILED" | "HUMANISH_STUDY_PREFLIGHT_TEARDOWN_FAILED" | PlanRefusal["code"];
         message: string;
     };
 }

package/dist/study/preflight.js

@@ -4,8 +4,8 @@ import path from "node:path";
 import { isLoopbackUrl } from "./parse/subject.js";
 import {} from "./types.js";
 import { runPublicPreviewPreflight, runSandboxLoopbackPreflight } from "./preflight-probes.js";
-import { digest, finalize, STUDY_CHECK_SCHEMA } from "./preflight-result.js";
-import { routeOf } from "./plan.js";
+import { digest, fail, finalize, STUDY_CHECK_SCHEMA } from "./preflight-result.js";
+import { planStudy, routeOf } from "./plan.js";
 import { resolveStudyManifest } from "./discover.js";
 import { participantList } from "./study-fields.js";
 import { isLocalBrowserStudy } from "../substrates/local/runtime-config.js";
@@ -42,6 +42,7 @@ export async function runStudyPreflight(options) {
         ? new Map()
         : (await resolveCommittedPersonasForCwd(cwd, studyPersonaIds(resolved.config))).personas;
     const route = routeOf(resolved.config);
+    const env = options.env ?? process.env;
     const ctx = {
         cwd,
         study: options.study,
@@ -52,7 +53,7 @@ export async function runStudyPreflight(options) {
         route,
         reachability,
         timeoutMs,
-        env: options.env ?? process.env,
+        env,
         hooks: options.hooks ?? {},
         checks: [
             { name: "study file", ok: true, message: `resolved ${resolved.origin} study file` },
@@ -65,6 +66,14 @@ export async function runStudyPreflight(options) {
             ...personaBackgroundWarnings(resolved.config.id, participants, personas),
         ],
     };
+    // The plan `humanish run <study>` makes before it creates anything: no run options, so the file's
+    // mode decides dry or live, and the same environment for the sandbox ceiling. A study the run
+    // would refuse fails here with the run's code, before any probe creates a sandbox.
+    const planned = planStudy(resolved.config, { cwd, env });
+    if (!planned.ok) {
+        const { code, message } = planned.refusal;
+        return fail(ctx, code, message, [{ name: "plan", ok: false, message }]);
+    }
     const machine = machineCheck(ctx.config);
     // A local study's app and desktops run on this machine, so the hosted probes do not apply.
     if (reachability !== "metadata" && isLocalBrowserStudy(ctx.config))

package/dist/study/routing.d.ts

@@ -1,5 +1,6 @@
 import type { StudyConfig } from "./types.js";
-export declare const MAX_COMPUTER_USE_PARTICIPANTS = 16;
+/** Why a study of `count` participants cannot run, or undefined when it can. */
+export declare function participantCountReason(count: number): string | undefined;
 export declare function actorResolvesToComputerUse(type: string | undefined): boolean;
 export declare function registeredComputerUseActors(): string[];
 export declare function actorResolvesToScriptedBrowser(type: string | undefined): boolean;
@@ -9,11 +10,11 @@ export declare function registeredScriptedBrowserActors(): string[];
 export declare function actorResolvesToTerminal(type: string | undefined): boolean;
 export declare function registeredTerminalActors(): string[];
 /**
- * The declared fan-out participant count on the computer-use route: a `participants` list's
- * length, else a participant count, else 1. The single source of truth shared by the parser, the engine,
+ * The fan-out participant count on the computer-use route: a `participants` list's length, else
+ * the caller's count override, else a participant count, else 1. The single source of truth shared by the parser, the engine,
  * and the pre-flight plan so the participant count is computed the same way everywhere.
  */
-export declare function computerUseParticipantCount(config: StudyConfig): number;
+export declare function computerUseParticipantCount(config: StudyConfig, countOverride?: number): number;
 /**
  * A participant's id: its declared roster id, else `lane-NN` (independent participants) or `role-NN`
  * (shared-world participants) from its 0-based position. The parser's filled email recipients and

package/dist/study/routing.js

@@ -1,9 +1,17 @@
 import { actorRegistry } from "../actors/registry.js";
 import { isLoopbackUrl } from "./parse/subject.js";
 import { participantList, declaredParticipantCount } from "./study-fields.js";
-// Hard cap on computer-use participants. No setting raises it: each participant is a paid desktop,
-// and they all run at once.
-export const MAX_COMPUTER_USE_PARTICIPANTS = 16;
+// The most participants one study holds, on any route. One run keeps every participant's stream in
+// one bundle, one Observer view and one analysis, and those are sized for 100: the analysis reads a
+// bundle of at most 128 streams. How many run at once is a separate limit, the E2B plan's
+// (concurrentSandboxes in substrates/e2b/lifetime.ts), and caps.maxUsd bounds what they spend.
+const MAX_STUDY_PARTICIPANTS = 100;
+/** Why a study of `count` participants cannot run, or undefined when it can. */
+export function participantCountReason(count) {
+    return count > MAX_STUDY_PARTICIPANTS
+        ? `A study runs at most ${MAX_STUDY_PARTICIPANTS} participants, and this one has ${count}. One run keeps every participant's evidence in one bundle and one Observer view, and humanish supports runs of up to ${MAX_STUDY_PARTICIPANTS}; split the participants across studies.`
+        : undefined;
+}
 // Run kinds whose evidence is the participant's screenshots. An actor that declares it produces none
 // cannot run on them: a code-only actor would claim a GUI flow it only reached through a shell.
 const SCREENSHOT_RUN_KINDS = new Set([
@@ -46,12 +54,13 @@ export function registeredTerminalActors() {
     return registeredActorsOn("terminal");
 }
 /**
- * The declared fan-out participant count on the computer-use route: a `participants` list's
- * length, else a participant count, else 1. The single source of truth shared by the parser, the engine,
+ * The fan-out participant count on the computer-use route: a `participants` list's length, else
+ * the caller's count override, else a participant count, else 1. The single source of truth shared by the parser, the engine,
  * and the pre-flight plan so the participant count is computed the same way everywhere.
  */
-export function computerUseParticipantCount(config) {
-    return participantList(config)?.length ?? declaredParticipantCount(config) ?? 1;
+export function computerUseParticipantCount(config, countOverride) {
+    return (participantList(config)?.length ??
+        Math.max(1, countOverride ?? declaredParticipantCount(config) ?? 1));
 }
 /**
  * A participant's id: its declared roster id, else `lane-NN` (independent participants) or `role-NN`

package/dist/study/summary.d.ts

@@ -1,5 +1,5 @@
 import { type LocalRuntimeStatus } from "../substrates/local/runtime.js";
-import { type AutomaticAnalysisBudget } from "../analysis/automatic-config.js";
+import { type StudyAnalysisBudget } from "./automatic-analysis-plan.js";
 import { type KeyResolutionDeps } from "../keys/key-resolution.js";
 export declare const STUDY_SUMMARY_SCHEMA = "humanish.study-summary.v1";
 export interface StudyCaps {
@@ -15,8 +15,8 @@ export interface StudySummary {
         message: string;
     };
     communications?: string;
-    analysis?: AutomaticAnalysisBudget & {
-        /** The budget line `run` and `study check` print, from formatAutomaticAnalysisBudget. */
+    analysis?: StudyAnalysisBudget & {
+        /** The budget line `run` and `study check` print, from formatStudyAnalysisBudget. */
         line: string;
     };
     schema: typeof STUDY_SUMMARY_SCHEMA;

package/dist/study/summary.js

@@ -11,7 +11,7 @@ import { localRuntimeStatus } from "../substrates/local/runtime.js";
 import { planStudy, resolveStudyDryRun, routeOf } from "./plan.js";
 import { localCodexParticipantCheck } from "./doctor.js";
 import { requiredKeys, requiredSubjectEnv } from "./requirements.js";
-import { automaticAnalysisBudget, formatAutomaticAnalysisBudget, } from "../analysis/automatic-config.js";
+import { formatStudyAnalysisBudget, studyAnalysisBudget, } from "./automatic-analysis-plan.js";
 import { DEFAULT_OPENAI_CU_MODEL, DEFAULT_OPENAI_CU_REASONING_EFFORT, } from "../actors/computer-use/openai-provider.js";
 import { inspectStudyManifest } from "./discover.js";
 import { computerUseParticipantCount, isComputerUseComposition } from "./routing.js";
@@ -123,7 +123,7 @@ export async function readStudySummary(cwd, study, options = {}) {
             missingKeys = missing;
     }
     // Computed once: a test-then-use pair reads as though the two calls could differ.
-    const analysis = automaticAnalysisBudget(inspected.config.review?.analysis, route, computerUseParticipantCount(inspected.config));
+    const analysis = studyAnalysisBudget(inspected.config.review?.analysis, route, computerUseParticipantCount(inspected.config));
     const subject = subjectOf(config);
     const participants = participantsOf(inspected.config);
     const caps = summaryCapsOf(inspected.config);
@@ -140,9 +140,7 @@ export async function readStudySummary(cwd, study, options = {}) {
         ? await localCodexParticipantCheck({ env: options.env ?? process.env })
         : undefined;
     return {
-        ...(analysis
-            ? { analysis: { ...analysis, line: formatAutomaticAnalysisBudget(analysis) } }
-            : {}),
+        ...(analysis ? { analysis: { ...analysis, line: formatStudyAnalysisBudget(analysis) } } : {}),
         ...(runtime
             ? { runtime: { ok: runtime.ok, installed: runtime.installed, message: runtime.message } }
             : {}),

package/dist/study/types.d.ts

@@ -349,6 +349,20 @@ export interface StudyActor {
     model?: string;
     /** First-party OpenAI CUA only: per-response output limit including reasoning, not a dollar cap. */
     maxOutputTokens?: number;
+    /**
+     * Computer-use and shared-world: the longest one `wait` action lasts, in whole milliseconds from
+     * 1000 to 600000. Default 120000, or 30000 on a desktop with speech. A longer wait is shortened
+     * to it, the trace records a `wait shortened` notice, and the participant is told on its next
+     * turn.
+     */
+    maxWaitMs?: number;
+    /**
+     * Computer-use and shared-world: how long a `wait` that names no duration lasts when the
+     * participant's turn only waits or takes screenshots, in whole milliseconds from 1000 to 600000
+     * and no longer than maxWaitMs. Default 5000. After an action in the same turn such a wait lasts
+     * 500 ms. OpenAI's computer-use `wait` never names a duration.
+     */
+    idleWaitMs?: number;
     /**
      * `local-agent` only: which locally signed-in coding agent is the brain. Absent = codex.
      *

package/dist/study/validation.d.ts

@@ -2,8 +2,8 @@ import type { StudyConfig } from "./types.js";
 /**
  * Cross-validate the computer-use fan-out declaration (`per-lane-worlds`). Returns the failure
  * message, or null when valid. The parser enforces it, and runStudyWith checks it again for a config
- * that skipped the parser. It runs rosterStructuralValidationReason (id and device
- * validity, unique ids) first, then the route-scoped XOR, cap and policy checks.
+ * that skipped the parser. It runs rosterStructuralValidationReason (roster size, id and device
+ * validity, unique ids) first, then the route-scoped XOR, participant count and policy checks.
  */
 export declare function computerUseValidationReason(config: StudyConfig): string | null;
 /**
@@ -36,6 +36,11 @@ export declare function taskProtocolValidationReason(config: StudyConfig, suppor
 export declare function cloneTargetValidationReason(config: StudyConfig): string | null;
 /** Refuse a claimed output bound when the route cannot pass it to the first-party provider. */
 export declare function outputTokenLimitValidationReason(config: StudyConfig): string | null;
+/**
+ * Refuse a wait field out of range, or an idle wait longer than the longest wait. On a route whose
+ * participants take no wait actions the fields are inert (warnings.ts).
+ */
+export declare function waitLimitValidationReason(config: StudyConfig): string | null;
 /**
  * Cross-validate a concurrent shared-world declaration. Returns the failure message,
  * or null when valid. Includes the base shared-world checks plus the concurrent extras: a synthetic

package/dist/study/validation.js

@@ -1,14 +1,16 @@
 import { isMaxOutputTokens } from "../actors/output-token-limit.js";
+import { MAX_RECEIVING_INBOXES } from "../comms/receiving-types.js";
+import { waitFieldsReason } from "../actors/computer-use/wait.js";
 import { PARTICIPANT_ID_MAX_CHARS, PARTICIPANT_ID_PATTERN } from "./parse/actors.js";
 import { isHttpUrl, isLoopbackUrl } from "./parse/subject.js";
 import { declaredTargets } from "./plan-participants.js";
-import { actorResolvesToComputerUse, computerUseParticipantCount, MAX_COMPUTER_USE_PARTICIPANTS, registeredComputerUseActors, resolveEntryUrl, isComputerUseComposition, isScriptedBrowserComposition, isSharedWorldComposition, isTerminalProductComposition, } from "./routing.js";
+import { actorResolvesToComputerUse, computerUseParticipantCount, participantCountReason, registeredComputerUseActors, resolveEntryUrl, isComputerUseComposition, isScriptedBrowserComposition, isSharedWorldComposition, isTerminalProductComposition, } from "./routing.js";
 import { participantList } from "./study-fields.js";
 /**
  * Cross-validate the computer-use fan-out declaration (`per-lane-worlds`). Returns the failure
  * message, or null when valid. The parser enforces it, and runStudyWith checks it again for a config
- * that skipped the parser. It runs rosterStructuralValidationReason (id and device
- * validity, unique ids) first, then the route-scoped XOR, cap and policy checks.
+ * that skipped the parser. It runs rosterStructuralValidationReason (roster size, id and device
+ * validity, unique ids) first, then the route-scoped XOR, participant count and policy checks.
  */
 export function computerUseValidationReason(config) {
     const roster = participantList(config);
@@ -41,9 +43,9 @@ export function computerUseValidationReason(config) {
         }
     }
     const participantCount = computerUseParticipantCount(config);
-    if (participantCount > MAX_COMPUTER_USE_PARTICIPANTS) {
-        return `A computer-use study runs at most ${MAX_COMPUTER_USE_PARTICIPANTS} participants, and this one declares ${participantCount}. Each participant is a paid desktop and they all run at once, so no setting raises the cap; split the roster across studies.`;
-    }
+    const countReason = participantCountReason(participantCount);
+    if (countReason)
+        return countReason;
     // Public targets fan out into N independent worlds driving the same public app, which is an
     // ambiguous shared-world-ish shape, not a per-participant target swarm. Permit N>1 public runs only
     // when every roster entry declares its own target, making the adapter-owned topology explicit. But when
@@ -59,8 +61,8 @@ export function computerUseValidationReason(config) {
     return null;
 }
 /**
- * Engine-level path-token validation for configs supplied directly through the
- * public TypeScript/JavaScript API instead of parseStudy.
+ * Engine-level roster validation (its size and its ids' path tokens) for configs supplied directly
+ * through the public TypeScript/JavaScript API instead of parseStudy.
  */
 function rosterStructuralValidationReason(config) {
     const roster = participantList(config);
@@ -69,6 +71,9 @@ function rosterStructuralValidationReason(config) {
         if (!Array.isArray(roster) || roster.length === 0) {
             return "participants must be a non-empty array when set.";
         }
+        const countReason = participantCountReason(roster.length);
+        if (countReason)
+            return countReason;
         for (const [index, entry] of roster.entries()) {
             if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
                 return `participants[${index}] must be an object.`;
@@ -194,6 +199,10 @@ export function receivingEmailValidationReason(config) {
         !["app-url", "clone", "local-tree"].includes(config.subject.source)) {
         return "Real email receiving requires a hosted computer-use browser study with an app-url, clone, or local-tree subject. Scripted, terminal, desktop-cli and local-app routes are unsupported.";
     }
+    const participants = computerUseParticipantCount(config);
+    if (participants > MAX_RECEIVING_INBOXES) {
+        return `Real email receiving leases one inbox per participant, at most ${MAX_RECEIVING_INBOXES} per run, and this study has ${participants} participants. Run at most ${MAX_RECEIVING_INBOXES} participants with a real inbox, or split them across studies.`;
+    }
     if (config.actor?.type === "local-agent") {
         return "Real email receiving is unavailable for local-agent: its host process does not isolate the inbox management credential. Use a hosted first-party computer-use actor.";
     }
@@ -235,16 +244,23 @@ export function outputTokenLimitValidationReason(config) {
     }
     return null;
 }
+/**
+ * Refuse a wait field out of range, or an idle wait longer than the longest wait. On a route whose
+ * participants take no wait actions the fields are inert (warnings.ts).
+ */
+export function waitLimitValidationReason(config) {
+    return config.actor === undefined ? null : waitFieldsReason(config.actor, "actor.");
+}
 /**
  * Shared-world participants share one live app, so at least two must be live at once. The
- * sequential shared-world route (`execution.concurrency: 1`) was removed in 0.106.0; the parser
- * fills an omitted concurrency with the participant count. Both callers check it after their
- * two-participant roster floor, so a one-participant roster gets the roster refusal, never this
- * one.
+ * sequential shared-world route (`execution.concurrency: 1`) was removed in 0.106.0. An omitted
+ * concurrency runs every participant, up to the E2B plan's limit, which the planner checks. Both
+ * callers check it after their two-participant roster floor, so a one-participant roster gets the
+ * roster refusal, never this one.
  */
 function sharedWorldConcurrencyReason(config) {
-    // Direct library callers skip the parser, so an omitted value defaults here exactly as the
-    // route does: to the participant count. A missing roster reads as 0 and is refused.
+    // An omitted value runs every participant, so it is checked as the participant count. A missing
+    // roster reads as 0 and is refused.
     const participants = participantList(config)?.length ?? 0;
     const concurrency = config.execution?.concurrency ?? participants;
     if (concurrency >= 2)

package/dist/study/warnings.js

@@ -50,6 +50,18 @@ const ACTOR_ROWS = [
         field: "actor.model",
         applies: (config, routes) => otherRoute(routes) && Boolean(config.actor?.model),
     },
+    // Only a computer-use loop dispatches wait actions; terminal, scripted and preview participants
+    // take none.
+    {
+        field: "actor.maxWaitMs",
+        reason: "the longest wait action of a computer-use participant; needs route: computer-use or shared-world",
+        applies: (config, routes) => config.actor?.maxWaitMs !== undefined && !routes.cua && !routes.shared,
+    },
+    {
+        field: "actor.idleWaitMs",
+        reason: "how long a computer-use participant's wait with no duration lasts; needs route: computer-use or shared-world",
+        applies: (config, routes) => config.actor?.idleWaitMs !== undefined && !routes.cua && !routes.shared,
+    },
 ];
 const TERMINAL_ONLY = "needs subject.source: terminal-product + a registered terminal actor";
 const RESERVED = "reserved; no route reads it yet";

package/dist/subject/serve.d.ts

@@ -37,3 +37,6 @@ export declare function runSubjectServePipeline(shell: Shell, args: {
      *  an in-sandbox git refresh, because the archive excludes .git). */
     onPhaseComplete?: () => Promise<void>;
 } & DetachedTimers): Promise<void>;
+/** A serve.build that exited non-zero or ran out of time; the message carries its redacted log tail. */
+export declare class SubjectBuildError extends Error {
+}

package/dist/subject/serve.js

@@ -196,6 +196,9 @@ async function installSubject(step, command) {
         throw new Error(`${headline}: ${failureTail(step.scrub(install.logTail))}`);
     }
 }
+/** A serve.build that exited non-zero or ran out of time; the message carries its redacted log tail. */
+export class SubjectBuildError extends Error {
+}
 /** serve.build, once. */
 async function buildSubject(step, command) {
     const { now } = step;
@@ -211,7 +214,7 @@ async function buildSubject(step, command) {
     });
     emitPhaseCompleted(step.onPhase, now, buildStartedAt, "build", build.ok, build.ok ? "subject build complete" : "subject build failed");
     if (!build.ok) {
-        throw new Error(`subject build ${build.timedOut ? "timed out" : `failed (exit ${build.exitCode})`}: ${failureTail(step.scrub(build.logTail))}`);
+        throw new SubjectBuildError(`subject build ${build.timedOut ? "timed out" : `failed (exit ${build.exitCode})`}: ${failureTail(step.scrub(build.logTail))}`);
     }
 }
 /** serve.start as a detached process that keeps running. */

package/dist/substrates/detached.js

@@ -3,7 +3,9 @@
 //
 // - Scripts are written via `writeFile`, never heredocs, which eliminates the
 //   sentinel-collision bug class (a command line that equals the heredoc terminator) by
-//   construction.
+//   construction. The author's command is a script file of its own, so bash parses it apart
+//   from the wrapper: a syntax error in it is that script's exit 2, logged, and the wrapper
+//   still writes the status.
 // - Bounded steps (install/build) run detached with an atomically-written status file
 //   (write tmp + mv), polled by short foreground commands; a timeout kills the process
 //   group and surfaces a capped log tail for the caller to redact and persist.
@@ -34,10 +36,11 @@ function assertName(name) {
 function stepDir(name) {
     return `${WORK_ROOT}/${name}`;
 }
-// The wrapper script: runs the command from its own session (Shell.start makes the script the
-// process-group leader, so `kill -- -PID` reclaims the whole tree), logs everything, and
-// writes the exit code atomically so a poller can never read a half-written status.
-function wrapperScript(name, command, cwd) {
+// The wrapper script: runs the command script from its own session (Shell.start makes the
+// wrapper the process-group leader, so `kill -- -PID` reclaims the whole tree), logs everything,
+// and writes the exit code atomically so a poller can never read a half-written status. It holds
+// no author text, so it always parses and always reaches the status write.
+function wrapperScript(name, cwd) {
     const dir = stepDir(name);
     return [
         "#!/bin/bash",
@@ -46,7 +49,7 @@ function wrapperScript(name, command, cwd) {
         cwd === undefined
             ? ": # no cwd override"
             : `cd ${shellQuote(cwd)} || { echo 127 > ${shellQuote(`${dir}/status.tmp`)}; mv ${shellQuote(`${dir}/status.tmp`)} ${shellQuote(`${dir}/status`)}; exit 127; }`,
-        `( ${command} ) > ${shellQuote(`${dir}/log.txt`)} 2>&1`,
+        `bash ${shellQuote(`${dir}/command.sh`)} > ${shellQuote(`${dir}/log.txt`)} 2>&1`,
         "code=$?",
         `echo $code > ${shellQuote(`${dir}/status.tmp`)}`,
         `mv ${shellQuote(`${dir}/status.tmp`)} ${shellQuote(`${dir}/status`)}`,
@@ -59,7 +62,11 @@ async function writeAndLaunch(shell, name, command, cwd, requestTimeoutMs) {
     const dir = stepDir(name);
     const scriptPath = `${dir}/run.sh`;
     await runOrThrow(shell, `mkdir -p ${shellQuote(dir)}`, { requestTimeoutMs });
-    await shell.writeFile(scriptPath, wrapperScript(name, command, cwd));
+    // The study parser trims each command, so a YAML `|` block arrives without its final newline.
+    // bash closes a heredoc whose delimiter is a script's last line either way; the newline makes
+    // the file plain text.
+    await shell.writeFile(`${dir}/command.sh`, `${command}\n`);
+    await shell.writeFile(scriptPath, wrapperScript(name, cwd));
     throwOnExit(await shell.start(`bash ${shellQuote(scriptPath)}`, { requestTimeoutMs }));
 }
 /** Read the capped log tail for a step (raw; caller redacts). */

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

@@ -54,8 +54,6 @@ export interface E2BDesktopLike {
     wait(ms: number): Promise<void> | void;
 }
 export interface E2BDesktopExecutorOptions {
-    /** Fallback wait when a wait action carries no ms. Default 500. */
-    defaultWaitMs?: number;
     /**
      * Pixels of CuaAction scroll dy per one SDK scroll tick. The executor maps
      * abs(dy) / scrollAmountPerTick to the SDK's integer `amount` (floored at 1 for