humanish 0.116.0 → 0.118.0

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

@@ -5,6 +5,7 @@ import { validatePreparedRunArtifactPaths } from "../../../run/paths.js";
 import { provisionCloneSubject } from "../../../subject/clone.js";
 import { provisionDesktopCli } from "../../../subject/desktop-cli.js";
 import { provisionLocalTreeSubject } from "../../../subject/local-tree.js";
+import { SubjectBuildError } from "../../../subject/serve.js";
 import { inspectDesktopScreenGeometry } from "../../../substrates/e2b/desktop-geometry.js";
 import { observeDesktopResources } from "../../../substrates/e2b/desktop-resources.js";
 import { acquireE2BDesktopSandbox, e2bDesktopTemplate } from "../../../substrates/e2b/sandbox.js";
@@ -166,37 +167,45 @@ export async function provisionParticipantSubject(ctx, state, desktop) {
             onPhase: ctx.onSubjectPhase,
         });
     }
-    if (subject.kind === "clone") {
-        state.subjectCommit = await provisionCloneSubject(shell, {
-            repo: subject.repo,
-            depth: residual.subject.clone?.depth ?? 1,
-            serve: subject.serve,
-            ...(subject.state === undefined ? {} : { state: subject.state }),
-            hasGithubToken: subject.env.includes("GITHUB_TOKEN"),
-            requestTimeoutMs: deps.requestTimeoutMs,
-            scrub: deps.scrubKnownValues,
-            onCommit: (commit) => {
-                state.subjectCommit = commit;
-            },
-            onStateStep: (record) => {
-                state.stateStepRecords.push(record);
-            },
-            onPhase: ctx.onSubjectPhase,
-            ...deps.detachedTimers,
-        });
+    try {
+        if (subject.kind === "clone") {
+            state.subjectCommit = await provisionCloneSubject(shell, {
+                repo: subject.repo,
+                depth: residual.subject.clone?.depth ?? 1,
+                serve: subject.serve,
+                ...(subject.state === undefined ? {} : { state: subject.state }),
+                hasGithubToken: subject.env.includes("GITHUB_TOKEN"),
+                requestTimeoutMs: deps.requestTimeoutMs,
+                scrub: deps.scrubKnownValues,
+                onCommit: (commit) => {
+                    state.subjectCommit = commit;
+                },
+                onStateStep: (record) => {
+                    state.stateStepRecords.push(record);
+                },
+                onPhase: ctx.onSubjectPhase,
+                ...deps.detachedTimers,
+            });
+        }
+        else if (subject.kind === "local-tree" && deps.localTreeArchiveBuffer) {
+            await provisionLocalTreeSubject(shell, {
+                archiveBuffer: deps.localTreeArchiveBuffer,
+                serve: subject.serve,
+                ...(subject.state === undefined ? {} : { state: subject.state }),
+                requestTimeoutMs: deps.requestTimeoutMs,
+                scrub: deps.scrubKnownValues,
+                onStateStep: (record) => {
+                    state.stateStepRecords.push(record);
+                },
+                onPhase: ctx.onSubjectPhase,
+                ...deps.detachedTimers,
+            });
+        }
     }
-    else if (subject.kind === "local-tree" && deps.localTreeArchiveBuffer) {
-        await provisionLocalTreeSubject(shell, {
-            archiveBuffer: deps.localTreeArchiveBuffer,
-            serve: subject.serve,
-            ...(subject.state === undefined ? {} : { state: subject.state }),
-            requestTimeoutMs: deps.requestTimeoutMs,
-            scrub: deps.scrubKnownValues,
-            onStateStep: (record) => {
-                state.stateStepRecords.push(record);
-            },
-            onPhase: ctx.onSubjectPhase,
-            ...deps.detachedTimers,
-        });
+    catch (error) {
+        // A failed serve.build gets its own code, so the run names the step the author has to fix.
+        if (error instanceof SubjectBuildError)
+            state.failureCode = "HUMANISH_COMPUTER_USE_SUBJECT_BUILD_FAILED";
+        throw error;
     }
 }

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

@@ -5,6 +5,7 @@ import { redactText } from "../../evidence/redaction.js";
 import { REVIEW_SCHEMA, bundleArtifacts, bundleHead, } from "../../run/bundle.js";
 import { aggregateTaskFunnels, formatParticipantOutcomes, formatRunTaskFunnel, gapsListClause, withCuaReviewProvenance, } from "../../run/outcomes.js";
 import { providerResourcesForOutcome, publicSafeAppUrlLabel } from "./bundle-parts.js";
+import { subjectName } from "../../run/subject-name.js";
 import { participantFeedbackCandidates } from "./participant-feedback.js";
 import { participantFactsOf } from "./participant-facts.js";
 import { judgeParticipantRecords } from "../../run/judge.js";
@@ -44,7 +45,7 @@ function fanoutSummary(args, facts) {
         return `${people} ${count === 1 ? "is" : "are"} each using their own copy of the app. The run is still going, so nothing here is final.`;
     }
     if (args.dryRun) {
-        return `${rerun}Dry run: ${people} would each use their own copy of ${publicSafeAppUrlLabel(args.appUrl)}. No desktops were launched and $0 was spent.`;
+        return `${rerun}Dry run: ${people} would each use their own copy of ${subjectName(publicSafeAppUrlLabel(args.appUrl), args.aggregateSubject)}. No desktops were launched and $0 was spent.`;
     }
     const tasks = facts.tasks === undefined ? "" : ` Tasks: ${facts.tasks}.`;
     return `${rerun}${people} took part, each in their own copy of the app: ${facts.outcomes}${gapsListClause(count - facts.passed, count)}.${tasks}`;

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

@@ -4,6 +4,7 @@ import { participantAssignment } from "../../study/participant-assignment.js";
 import { participantEvent, participantRecord, participantStream, } from "../../run/participant-records.js";
 import { participantCaption } from "../../run/participant-caption.js";
 import { participantSummary } from "../../run/outcomes.js";
+import { subjectName } from "../../run/subject-name.js";
 import { declaredScreenForRender } from "../../substrates/e2b/desktop-geometry.js";
 import { describeSubjectState, phaseEventIdSuffix, publicSafeAppUrlLabel } from "./bundle-parts.js";
 import { participantSubjectEnv } from "./types.js";
@@ -60,7 +61,7 @@ function fanoutParticipantRecord(args, spec, index, view) {
         mode: "browser-sim",
         progress: args.inProgress === true && outcome === undefined ? 20 : 100,
         currentStep: reason,
-        summary: participantSummary(name, { name: "the app", target: publicTargetUrl }, {
+        summary: participantSummary(name, { name: "the app", target: subjectName(publicTargetUrl, view.subject) }, {
             trace: session?.trace,
             skippedReason: outcome?.skippedReason,
             sessionError: outcome?.sessionError,

package/dist/routes/computer-use/local-vm.js

@@ -139,10 +139,11 @@ function createLocalParticipantDesktop(context, run, warnings, artifactRoot) {
     };
 }
 /** The Codex account participant, whose unconfirmed cleanup blocks the study's analysis. */
-function accountProvider(state) {
+function accountProvider(state, maxWaitMs) {
     return async ({ executor }) => {
         const participant = createRestrictedCodexParticipant({
             speechEnabled: executor.speechEnabled === true,
+            ...(maxWaitMs === undefined ? {} : { maxWaitMs }),
         });
         state.participants.push(participant);
         const provider = Object.assign(participant.provider, {
@@ -183,7 +184,9 @@ export function prepareLocalVmRun(options) {
     };
     const { config: _config, assets: _assets, signal: _signal, ...runOptions } = options;
     return {
-        options: account ? { ...runOptions, createProvider: accountProvider(state) } : runOptions,
+        options: account
+            ? { ...runOptions, createProvider: accountProvider(state, config.actor?.maxWaitMs) }
+            : runOptions,
         localVm: {
             desktop: (run, warnings, artifactRoot) => createLocalParticipantDesktop(context, run, warnings, artifactRoot),
             capacity: () => localRuntimeCapacity(),

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

@@ -44,6 +44,9 @@ export async function startParticipantModel(spec, deps, executor) {
                 : { reasoningEffort: spec.planned.limits.reasoningEffort }),
             ...(brain.declaredModel === undefined ? {} : { model: brain.declaredModel }),
             ...(executor.speechEnabled === true ? { speechEnabled: true } : {}),
+            ...(spec.planned.limits.maxWaitMs === undefined
+                ? {}
+                : { maxWaitMs: spec.planned.limits.maxWaitMs }),
             session: { env },
         });
         return { provider: codexParticipant.provider, codexParticipant };
@@ -130,6 +133,12 @@ export function participantSessionOptions(spec, deps, ready, provider, writeScre
             ? {}
             : { stopWhen: spec.planned.limits.stopWhen }),
         ...(spec.planned.limits.dwell === undefined ? {} : { dwell: spec.planned.limits.dwell }),
+        ...(spec.planned.limits.maxWaitMs === undefined
+            ? {}
+            : { maxWaitMs: spec.planned.limits.maxWaitMs }),
+        ...(spec.planned.limits.idleWaitMs === undefined
+            ? {}
+            : { idleWaitMs: spec.planned.limits.idleWaitMs }),
         ...(spec.planned.tasks === undefined ? {} : { tasks: spec.planned.tasks }),
         // The study budget: this participant notes its own running estimate on the shared
         // ledger and stops when the run total crosses the cap, independent of the per-participant

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

@@ -3,7 +3,6 @@
 // paths, and the public plan printed before any sandbox or provider call. loadCuaParticipants
 // compiles the committed personas first and narrows a rerun to its selected participants.
 import { isLocalBrowserStudy, LOCAL_BROWSER_LIFETIME_MS, } from "../../substrates/local/runtime-config.js";
-import { DEFAULT_STATE_STEP_TIMEOUT_MS } from "../../subject/state.js";
 import { resolveParticipant } from "../../run/participant.js";
 import {} from "../../study/types.js";
 import { scrubPersonaBrief } from "../../study/persona.js";
@@ -12,7 +11,7 @@ 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 { SANDBOX_TIMEOUT_BUFFER_MS, SUBJECT_PROVISION_BUDGET_MS, } from "../../substrates/e2b/lifetime.js";
+import { sandboxHeadroomMs } from "../../substrates/e2b/lifetime.js";
 import { readPositiveInt } from "../../study/parse/values.js";
 import { digestUrl } from "./bundle-parts.js";
 import { composeParticipantInstructions, DEFAULT_MISSION } from "./participant-prompt.js";
@@ -26,8 +25,7 @@ export function defaultSessionTimeoutMs(config, ceilingMs) {
     const provisionedRoute = config.subject.source === "clone" || config.subject.source === "local-tree";
     if (!provisionedRoute)
         return DEFAULT_APP_URL_SESSION_TIMEOUT_MS;
-    const stateBudgetMs = (config.subject.state?.seed ?? []).reduce((sum, step) => sum + (step.timeoutMs ?? DEFAULT_STATE_STEP_TIMEOUT_MS), 0);
-    const room = ceilingMs - SUBJECT_PROVISION_BUDGET_MS - stateBudgetMs - SANDBOX_TIMEOUT_BUFFER_MS;
+    const room = ceilingMs - sandboxHeadroomMs({ seed: config.subject.state?.seed ?? [] });
     return Math.max(MIN_DERIVED_SESSION_TIMEOUT_MS, Math.min(DEFAULT_APP_URL_SESSION_TIMEOUT_MS, room));
 }
 /** Per-participant sandbox deadline (each one owns its own desktop). Mirrors the
@@ -41,13 +39,9 @@ export function resolveParticipantSandboxMs(config, ceilingMs) {
         return LOCAL_BROWSER_LIFETIME_MS;
     const timeoutMs = config.execution?.timeoutMs ?? defaultSessionTimeoutMs(config, ceilingMs);
     const provisionedRoute = config.subject.source === "clone" || config.subject.source === "local-tree";
-    const stateBudgetMs = provisionedRoute
-        ? (config.subject.state?.seed ?? []).reduce((sum, step) => sum + (step.timeoutMs ?? DEFAULT_STATE_STEP_TIMEOUT_MS), 0)
-        : 0;
     return (config.execution?.desktop?.sandboxTimeoutMs ??
         timeoutMs +
-            (provisionedRoute ? SUBJECT_PROVISION_BUDGET_MS + stateBudgetMs : 0) +
-            SANDBOX_TIMEOUT_BUFFER_MS);
+            sandboxHeadroomMs(provisionedRoute ? { seed: config.subject.state?.seed ?? [] } : undefined));
 }
 /**
  * The in-flight participant bound a study declares. Defaults to the participant count: every

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

@@ -1,7 +1,7 @@
 import { type CuaActorDescriptor } from "../../actors/registry.js";
 import type { ComputerUsePlan, ComputerUseRunner, RoutePlanResult, RouteRefusal } from "../../study/plan-types.js";
 import type { StudyConfig, StudySubjectState } from "../../study/types.js";
-import { type SandboxCeiling } from "../../substrates/e2b/lifetime.js";
+import { type ConcurrentSandboxes, type SandboxCeiling } from "../../substrates/e2b/lifetime.js";
 import { type ComputerUseRunInput, type CuaActorStudyErrorCode } from "./types.js";
 /** The error a computer-use study returns before a run starts. */
 export interface ComputerUseRefusal extends RouteRefusal<"computer-use", CuaActorStudyErrorCode> {
@@ -48,4 +48,6 @@ export declare function planComputerUseStudy(config: StudyConfig, input: {
     readonly rerun?: ComputerUseRunInput["rerun"];
     /** The longest sandbox lifetime the operator's E2B plan allows (sandboxCeiling). */
     readonly sandboxCeiling: SandboxCeiling;
+    /** How many sandboxes the operator's E2B plan runs at once (concurrentSandboxes). */
+    readonly concurrentSandboxes: ConcurrentSandboxes;
 }): ComputerUsePlanResult;

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

@@ -9,12 +9,12 @@ 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 { MAX_COMPUTER_USE_PARTICIPANTS } from "../../study/routing.js";
-import { cloneTargetValidationReason, computerUseValidationReason, desktopMediaValidationReason, outputTokenLimitValidationReason, receivingEmailValidationReason, taskProtocolValidationReason, } from "../../study/validation.js";
+import { computerUseParticipantCount, participantCountReason } from "../../study/routing.js";
+import { cloneTargetValidationReason, computerUseValidationReason, desktopMediaValidationReason, outputTokenLimitValidationReason, receivingEmailValidationReason, taskProtocolValidationReason, waitLimitValidationReason, } from "../../study/validation.js";
 import { desktopCliProductReason } from "../../study/composition-rules.js";
 import { isLocalBrowserStudy } from "../../substrates/local/runtime-config.js";
 import { boundedConcurrency, defaultSessionTimeoutMs, resolveParticipantSandboxMs, } from "./participant-runs.js";
-import { ceilingAdvice } from "../../substrates/e2b/lifetime.js";
+import { ceilingAdvice, participantsAtOnce, } from "../../substrates/e2b/lifetime.js";
 import {} from "./types.js";
 /** The registered descriptor for a planned actor id; planComputerUseStudy checked the registry. */
 export function cuaDescriptorOf(actor) {
@@ -83,7 +83,9 @@ function cuaStudyRejection(config, hasRunSession, driving, subjectRoute, ceiling
 }
 /** A declaration this route cannot honor, for any subject or with the caller's own driver. */
 function unsupportedDeclarationReason(config, hasRunSession, driving, { inProcessRoute }) {
-    const reason = desktopMediaValidationReason(config) || outputTokenLimitValidationReason(config);
+    const reason = desktopMediaValidationReason(config) ||
+        outputTokenLimitValidationReason(config) ||
+        waitLimitValidationReason(config);
     if (reason)
         return invalid(reason);
     if (config.actor?.maxOutputTokens !== undefined &&
@@ -190,6 +192,19 @@ function rosterShapeReason(config, ceilingMs) {
     const headroomMs = derivedSandboxMs - sessionMs;
     return invalid(`execution.timeoutMs ${Math.round(sessionMs / 60_000)}m derives a ${Math.round(derivedSandboxMs / 60_000)}m sandbox deadline, and a sandbox may not live longer than ${ceilingMs / 60_000}m. The deadline is the session budget plus ${Math.round(headroomMs / 60_000)}m of provisioning and teardown headroom${provisionedRoute ? " (this route clones, installs, builds and serves the subject before the actor starts)" : ""}. Lower execution.timeoutMs to at most ${Math.round((ceilingMs - headroomMs) / 60_000)}m, or set execution.desktop.sandboxTimeoutMs explicitly.${ceilingAdvice(derivedSandboxMs)}`);
 }
+/**
+ * How many of the runner's participants run at once. 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.
+ */
+function concurrencyOf(config, runner, limit) {
+    const declared = config.execution?.concurrency;
+    const n = runner.participants.length;
+    const concurrency = boundedConcurrency(declared, n);
+    return runner.desktop === "e2b-desktop"
+        ? participantsAtOnce({ concurrency, declared: declared !== undefined, participants: n }, limit)
+        : { ok: true, count: concurrency };
+}
 /** The plan's rerun: the source run and, when given, the participants to rerun. */
 function rerunPlan({ sourceRunId, participantIds, }) {
     return { sourceRunId, ...(participantIds === undefined ? {} : { participantIds }) };
@@ -244,9 +259,11 @@ export function planComputerUseStudy(config, input) {
     const productReason = desktopCliProductReason(config);
     if (productReason)
         return refuse("in-scope", "HUMANISH_COMPUTER_USE_SUBJECT_INVALID", productReason, actor);
+    // Counted before any participant is built, so a large --count is refused without building it.
+    const countReason = participantCountReason(computerUseParticipantCount(config, input.countOverride));
+    if (countReason)
+        return refuse("after-personas", "HUMANISH_COMPUTER_USE_FANOUT_INVALID", countReason, actor);
     const participants = computerUseParticipants(config, input.countOverride);
-    if (participants.length > MAX_COMPUTER_USE_PARTICIPANTS)
-        return refuse("after-personas", "HUMANISH_COMPUTER_USE_FANOUT_INVALID", `Computer-use fan-out is capped at ${MAX_COMPUTER_USE_PARTICIPANTS} participants (resolved ${participants.length}); N concurrent paid desktops is real spend.`, actor);
     const [first, ...rest] = participants;
     if (driving.inProcess && rest.length > 0)
         return refuse("after-personas", "HUMANISH_COMPUTER_USE_FANOUT_INVALID", "Fan-out to more than one participant is not supported on the in-process route (RunStudyOptions.inProcess): fan-out provisions one independent E2B desktop per participant, which the in-process route deliberately skips. Run a single in-process participant, or fan out on the E2B route.", actor);
@@ -276,21 +293,24 @@ 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 declared = config.execution?.concurrency;
-    const n = participants.length;
+    const atOnce = concurrencyOf(config, runner, input.concurrentSandboxes);
+    if (!atOnce.ok)
+        return refuse("after-personas", "HUMANISH_COMPUTER_USE_FANOUT_INVALID", atOnce.message, actor);
     const provisioned = source === "clone" || source === "local-tree";
     const base = planBase(config, {
         dryRun: input.dryRun,
         analysis,
+        participants: participants.length,
     });
     return {
         ok: true,
         plan: {
             ...base,
+            ...(atOnce.lowered === undefined ? {} : { warnings: [atOnce.lowered] }),
             route: "computer-use",
             actor,
             runner,
-            concurrency: boundedConcurrency(declared, n),
+            concurrency: atOnce.count,
             sessionBudgetMs: config.execution?.timeoutMs ?? defaultSessionTimeoutMs(config, ceiling.ms),
             sandboxMs: resolveParticipantSandboxMs(config, ceiling.ms),
             caps: planCaps(config),

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

@@ -10,6 +10,7 @@ import { participantFeedbackCandidates } from "./participant-feedback.js";
 import { judgeParticipantRecords } from "../../run/judge.js";
 import { buildRunCostSummary } from "../../run/cost-summary.js";
 import { participantEvent, participantIds, participantRecord, participantStream, } from "../../run/participant-records.js";
+import { subjectName } from "../../run/subject-name.js";
 import { plural } from "../../run/text.js";
 /** The one participant's record and stream ids: sim-001 and stream-001. */
 const SINGLE = participantIds(0);
@@ -79,6 +80,8 @@ function participantView(args, publicAppUrl) {
         : (args.captureRedaction ?? "raw");
     return {
         publicAppUrl,
+        /** How the participant's sentence and the summary name the subject. */
+        subjectName: subjectName(publicAppUrl, args.subject),
         participant,
         tally: judgment.tally,
         status,
@@ -90,7 +93,7 @@ function participantView(args, publicAppUrl) {
     };
 }
 function singleSimulation(args, view) {
-    const { publicAppUrl, status, reason } = view;
+    const { status, reason } = view;
     const name = participantCaption({
         id: args.participantId ?? "lane-01",
         personaId: args.persona.id,
@@ -103,7 +106,7 @@ function singleSimulation(args, view) {
         mode: "browser-sim",
         progress: args.inProgress === true ? 20 : 100,
         currentStep: reason,
-        summary: participantSummary(name, { name: "the app", place: browserPlace(args), target: publicAppUrl }, {
+        summary: participantSummary(name, { name: "the app", place: browserPlace(args), target: view.subjectName }, {
             trace: args.session?.trace,
             sessionError: args.sessionError,
             inProgress: args.inProgress === true,
@@ -285,11 +288,11 @@ function singleSummary(args, view, facts) {
         return "1 participant is using the app. The run is still going, so nothing here is final.";
     }
     if (args.dryRun) {
-        return `Dry run: 1 participant would use ${view.publicAppUrl}. Nothing was launched and $0 was spent.`;
+        return `Dry run: 1 participant would use ${view.subjectName}. Nothing was launched and $0 was spent.`;
     }
     if (args.session === undefined) {
         return args.sessionError === undefined
-            ? `1 participant was planned against ${view.publicAppUrl}, but no session ran.`
+            ? `1 participant was planned against ${view.subjectName}, but no session ran.`
             : `1 participant was planned, but the run failed before their session finished: ${view.reason}`;
     }
     const ending = actorEnding(args.session.trace);

package/dist/routes/computer-use/subject-projection.js

@@ -103,6 +103,8 @@ function participantSubjectProjection(args) {
     if (args.subject.kind === "desktop-cli") {
         return { source: "desktop-cli", product: args.subject.product.name, state: args.subjectState };
     }
+    if (args.subject.kind === "local-app")
+        return { source: "local-app", state: args.subjectState };
     return { source: "app-url", state: args.subjectState };
 }
 /**

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

@@ -185,7 +185,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_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_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. */

package/dist/routes/scripted/plan.d.ts

@@ -1,8 +1,9 @@
 import type { StudyDeps } from "../../study/study-deps.js";
 import type { RoutePlanResult, RouteRefusal, ScriptedPlan } from "../../study/plan-types.js";
 import type { StudyConfig } from "../../study/types.js";
+import { type SandboxCeiling } from "../../substrates/e2b/lifetime.js";
 /** The error a scripted study returns before a run starts. */
-export interface ScriptedRefusal extends RouteRefusal<"scripted", "HUMANISH_STUDY_ANALYSIS_INVALID" | "HUMANISH_STUDY_TASKS_UNSUPPORTED" | "HUMANISH_SCRIPTED_ACTOR_UNSUPPORTED" | "HUMANISH_SCRIPTED_SCENARIO_INVALID" | "HUMANISH_SCRIPTED_SUBJECT_UNSAFE"> {
+export interface ScriptedRefusal extends RouteRefusal<"scripted", "HUMANISH_STUDY_ANALYSIS_INVALID" | "HUMANISH_STUDY_TASKS_UNSUPPORTED" | "HUMANISH_SCRIPTED_ACTOR_UNSUPPORTED" | "HUMANISH_SCRIPTED_SCENARIO_INVALID" | "HUMANISH_SCRIPTED_SUBJECT_UNSAFE" | "HUMANISH_SCRIPTED_SUBJECT_INVALID"> {
     /**
      * Set on the receiving, analysis and tasks refusals. The route returns those before it opens its
      * run scope, so their result has its own field order and no automatic-analysis record.
@@ -25,4 +26,6 @@ export declare function planScriptedStudy(config: StudyConfig, input: {
     readonly dryRun: boolean;
     /** A test's injected browser means a live run needs no host browser. */
     readonly injectedBrowser?: boolean;
+    /** The longest sandbox lifetime the operator's E2B plan allows (sandboxCeiling). */
+    readonly sandboxCeiling: SandboxCeiling;
 }): ScriptedPlanResult;

package/dist/routes/scripted/plan.js

@@ -7,9 +7,13 @@ import { browserSurfaces } from "../../actors/scripted-browser/types.js";
 import { resolveAutomaticAnalysis } from "../../analysis/automatic-config.js";
 import { isNonEmpty, planBase, provisionedSubject } from "../../study/plan-base.js";
 import { cloneTargetValidationReason, desktopMediaValidationReason, taskProtocolValidationReason, } from "../../study/validation.js";
+import { sandboxDeadlineRefusal } from "../../substrates/e2b/lifetime.js";
 // Default surface roster is 1 (desktop only): the defaults-table single-participant row governs;
 // `count: 2` is the declared override that adds the mobile surface.
 const DEFAULT_SURFACE_COUNT = 1;
+// Journey wall-clock budget per surface: 5 minutes. A scripted surface has zero model cost and
+// sandbox-seconds are pennies; a short default only truncated slow-loading subjects.
+const DEFAULT_SESSION_TIMEOUT_MS = 300_000;
 /** The app URL a run's evidence names: a provisioned subject's getHost URL is never persisted. */
 export function evidenceAppUrlOf(subject) {
     return subject.kind === "clone" ? "[provisioned-subject]" : subject.appUrl;
@@ -66,6 +70,26 @@ export function planScriptedStudy(config, input) {
     const scenarioRef = config.scenario;
     if (!scenarioRef?.trim())
         return refuse("HUMANISH_SCRIPTED_SCENARIO_INVALID", "A scripted-browser study needs `scenario`: the actor runs the browser steps in that scenario file.", { actor, appUrl: evidenceAppUrlOf(subject) });
+    const timeoutMs = config.execution?.timeoutMs;
+    const sessionTimeoutMs = timeoutMs ?? DEFAULT_SESSION_TIMEOUT_MS;
+    // A clone is served from an E2B sandbox that must outlive the journey; a loopback app runs on
+    // this machine and needs no sandbox.
+    if (subject.kind === "clone") {
+        const ceiling = input.sandboxCeiling;
+        const reason = ceiling.ok
+            ? sandboxDeadlineRefusal({
+                name: "the subject sandbox",
+                sessionMs: sessionTimeoutMs,
+                sessionDeclared: timeoutMs !== undefined,
+                servedSubject: { seed: subject.state?.seed ?? [] },
+            }, ceiling.ms)
+            : ceiling.message;
+        if (reason)
+            return refuse("HUMANISH_SCRIPTED_SUBJECT_INVALID", reason, {
+                actor,
+                appUrl: evidenceAppUrlOf(subject),
+            });
+    }
     const requirements = [];
     if (!input.dryRun && subject.kind === "clone") {
         requirements.push({ kind: "key", name: "E2B_API_KEY" });
@@ -76,7 +100,6 @@ export function planScriptedStudy(config, input) {
     if (!input.dryRun && input.injectedBrowser !== true)
         requirements.push({ kind: "host-browser" });
     const persona = config.actor?.persona;
-    const timeoutMs = config.execution?.timeoutMs;
     return {
         ok: true,
         plan: {
@@ -90,7 +113,7 @@ export function planScriptedStudy(config, input) {
             scenarioRef,
             surfaces: browserSurfaces.slice(0, config.surfaces?.length ?? DEFAULT_SURFACE_COUNT),
             ...(persona === undefined ? {} : { personaId: persona }),
-            ...(timeoutMs === undefined ? {} : { sessionTimeoutMs: timeoutMs }),
+            sessionTimeoutMs,
             requirements,
         },
     };

package/dist/routes/scripted/setup.js

@@ -12,9 +12,6 @@ import { evidenceAppUrlOf } from "./plan.js";
 import { resolveScriptedScenario } from "./scenario.js";
 import {} from "./types.js";
 import { refusedResult } from "../../run/study-result.js";
-// Journey wall-clock budget per surface: 5 minutes. A scripted surface has zero model cost and
-// sandbox-seconds are pennies; a short default only truncated slow-loading subjects.
-const DEFAULT_SESSION_TIMEOUT_MS = 300_000;
 /**
  * Checks what the plan cannot: the scenario file, the E2B key and subject env of a live clone,
  * and a browser to launch. Returns the refusal, or what the run needs.
@@ -83,7 +80,7 @@ export async function prepareScriptedRun(plan, input) {
     if (refusal)
         return { ok: false, result: failed(refusal.code, refusal.message) };
     const surfaces = plan.surfaces;
-    const timeoutMs = plan.sessionTimeoutMs ?? DEFAULT_SESSION_TIMEOUT_MS;
+    const timeoutMs = plan.sessionTimeoutMs;
     const persona = {
         id: plan.personaId ?? "scripted-journey",
         traitsApplied: [],

package/dist/routes/scripted/types.d.ts

@@ -58,7 +58,7 @@ export interface ScriptedBrowserStudyResult extends AutomaticAnalysisResult, Stu
     observer?: ObserverResult;
     warnings: string[];
     error?: {
-        code: StudyResultErrorCode | "HUMANISH_SCRIPTED_FAILED" | "HUMANISH_SCRIPTED_ACTOR_UNSUPPORTED" | "HUMANISH_SCRIPTED_SCENARIO_INVALID" | "HUMANISH_SCRIPTED_SUBJECT_UNSAFE" | "HUMANISH_SCRIPTED_BROWSER_MISSING" | "HUMANISH_SCRIPTED_KEYS_MISSING" | "HUMANISH_SCRIPTED_SUBJECT_ENV_MISSING" | "HUMANISH_SCRIPTED_GETHOST_UNAVAILABLE";
+        code: StudyResultErrorCode | "HUMANISH_SCRIPTED_FAILED" | "HUMANISH_SCRIPTED_ACTOR_UNSUPPORTED" | "HUMANISH_SCRIPTED_SCENARIO_INVALID" | "HUMANISH_SCRIPTED_SUBJECT_UNSAFE" | "HUMANISH_SCRIPTED_SUBJECT_INVALID" | "HUMANISH_SCRIPTED_BROWSER_MISSING" | "HUMANISH_SCRIPTED_KEYS_MISSING" | "HUMANISH_SCRIPTED_SUBJECT_ENV_MISSING" | "HUMANISH_SCRIPTED_GETHOST_UNAVAILABLE";
         message: string;
     };
 }

package/dist/routes/shared-world/participant-specs.js

@@ -11,7 +11,7 @@ import { desktopParticipantDeps, } from "../computer-use/participant-deps.js";
 import { resolveCommittedPersonasForCwd } from "../../study/persona-resolve.js";
 import { participantAssignment } from "../../study/participant-assignment.js";
 import { redactText } from "../../evidence/redaction.js";
-import { SANDBOX_TIMEOUT_BUFFER_MS } from "../../substrates/e2b/lifetime.js";
+import { sandboxHeadroomMs } from "../../substrates/e2b/lifetime.js";
 // prose-check: model prompt (the participant model reads this, not a person)
 const DEFAULT_MISSION = "You are one of MANY users hitting a shared web application at the same time. The browser is already open at the app. Accomplish your role's task, then stop.";
 /** Resolve an actor's participant URL against the harness-minted getHost base (entry is a
@@ -134,7 +134,7 @@ export function participantRunDeps(ctx, live, scrubKnownValues) {
         openaiApiKey: ctx.openaiApiKey,
         e2bApiKey: ctx.e2bApiKey,
         timeoutMs: ctx.timeoutMs,
-        sandboxMs: ctx.timeoutMs + SANDBOX_TIMEOUT_BUFFER_MS,
+        sandboxMs: ctx.timeoutMs + sandboxHeadroomMs(),
         participantCount: plan.plane.participants.length,
         artifactRoot: ctx.runPaths,
         studyCwd: ctx.cwd,

package/dist/routes/shared-world/plan.d.ts

@@ -1,7 +1,7 @@
 import { type CuaActorDescriptor } from "../../actors/registry.js";
 import type { RoutePlanResult, RouteRefusal, SharedWorldPlan } from "../../study/plan-types.js";
 import type { StudyConfig, StudySubjectState } from "../../study/types.js";
-import { type SandboxCeiling } from "../../substrates/e2b/lifetime.js";
+import { type ConcurrentSandboxes, type SandboxCeiling } from "../../substrates/e2b/lifetime.js";
 import type { ConcurrentSharedWorldStudyErrorCode } from "./types.js";
 /** The error a shared-world study returns before a run starts. */
 export interface SharedWorldRefusal extends RouteRefusal<"shared-world", ConcurrentSharedWorldStudyErrorCode> {
@@ -21,6 +21,8 @@ export declare function planSharedWorldStudy(config: StudyConfig, input: {
     readonly hasRunSession?: boolean;
     /** The longest sandbox lifetime the operator's E2B plan allows (sandboxCeiling). */
     readonly sandboxCeiling: SandboxCeiling;
+    /** How many sandboxes the operator's E2B plan runs at once (concurrentSandboxes). */
+    readonly concurrentSandboxes: ConcurrentSandboxes;
 }): SharedWorldPlanResult;
 /** The provisioned plane's declared subject state. The external-public plane declares none. */
 export declare function planeStateOf(plan: SharedWorldPlan): StudySubjectState | undefined;

package/dist/routes/shared-world/plan.js

@@ -10,10 +10,10 @@ import { brainOf, planCaps, desktopRequirements, isNonEmpty, planBase, } from ".
 import { sharedWorldParticipants } from "../../study/plan-participants.js";
 import { PUBLIC_TARGET_OWNER_PATTERN } from "../../study/parse/subject.js";
 import { REPO_SLUG_PATTERN } from "../../study/parse/values.js";
-import { concurrentSharedWorldValidationReason, desktopMediaValidationReason, externalPublicSharedWorldValidationReason, outputTokenLimitValidationReason, receivingEmailValidationReason, taskProtocolValidationReason, } from "../../study/validation.js";
+import { concurrentSharedWorldValidationReason, desktopMediaValidationReason, externalPublicSharedWorldValidationReason, outputTokenLimitValidationReason, receivingEmailValidationReason, taskProtocolValidationReason, waitLimitValidationReason, } from "../../study/validation.js";
 import { unpricedCapCheck } from "../../study/requirements.js";
-import { DEFAULT_STATE_STEP_TIMEOUT_MS } from "../../subject/state.js";
-import { SANDBOX_TIMEOUT_BUFFER_MS, SUBJECT_PROVISION_BUDGET_MS, } from "../../substrates/e2b/lifetime.js";
+import { participantsAtOnce, sandboxDeadlineRefusal, sandboxHeadroomMs, } from "../../substrates/e2b/lifetime.js";
+import { boundedConcurrency } from "../computer-use/participant-runs.js";
 /** The registered descriptor for a planned actor; planSharedWorldStudy checked the registry. */
 export function sharedWorldDescriptorOf(actorType) {
     const descriptor = actorRegistry[actorType];
@@ -55,6 +55,7 @@ export function planSharedWorldStudy(config, input) {
     // A library caller's config skips the parser, which refuses these first.
     studyUrlCredentialReason(config) ??
         outputTokenLimitValidationReason(config) ??
+        waitLimitValidationReason(config) ??
         (externalPublic
             ? externalPublicSharedWorldValidationReason(config)
             : concurrentSharedWorldValidationReason(config));
@@ -95,22 +96,54 @@ export function planSharedWorldStudy(config, input) {
     const plane = planeOf(config);
     if (plane === undefined)
         throw new Error("shared-world validation admitted a plane it cannot plan");
+    // Every participant's desktop and, on the provisioned plane, the app's own sandbox share the E2B
+    // plan's concurrent sandboxes. A shared world needs two participants live together.
+    const declared = config.execution?.concurrency;
+    const n = plane.participants.length;
+    const atOnce = participantsAtOnce({
+        concurrency: boundedConcurrency(declared, n),
+        declared: declared !== undefined,
+        participants: n,
+        alongside: plane.kind === "provisioned" ? 1 : 0,
+        minimum: 2,
+    }, input.concurrentSandboxes);
+    if (!atOnce.ok)
+        return refuse(invalid, atOnce.message, actor);
+    const sessionTimeoutMs = config.execution?.timeoutMs ?? defaultSessionTimeoutMs(plane, ceiling.ms);
+    // The run's longest deadline: on the provisioned plane the subject sandbox, which serves the app
+    // until every participant ends; on the external-public plane each participant's own sandbox.
+    const deadlineReason = sandboxDeadlineRefusal(plane.kind === "provisioned"
+        ? {
+            name: "the subject sandbox, which serves the app until every participant ends",
+            sessionMs: sessionTimeoutMs,
+            sessionDeclared: config.execution?.timeoutMs !== undefined,
+            servedSubject: { seed: plane.subject.state.seed ?? [] },
+        }
+        : {
+            name: "each participant's sandbox",
+            sessionMs: sessionTimeoutMs,
+            sessionDeclared: config.execution?.timeoutMs !== undefined,
+        }, ceiling.ms);
+    if (deadlineReason)
+        return refuse(invalid, deadlineReason, actor);
     const brain = brainOf(config, false);
     if (brain.kind === "caller")
         throw new Error("a shared-world participant has no caller brain");
     const base = planBase(config, {
         dryRun: input.dryRun,
         analysis,
+        participants: n,
     });
     return {
         ok: true,
         plan: {
             ...base,
+            ...(atOnce.lowered === undefined ? {} : { warnings: [atOnce.lowered] }),
             route: "shared-world",
             actor,
             plane,
-            concurrency: config.execution?.concurrency ?? plane.participants.length,
-            sessionTimeoutMs: config.execution?.timeoutMs ?? defaultSessionTimeoutMs(plane, ceiling.ms),
+            concurrency: atOnce.count,
+            sessionTimeoutMs,
             brain,
             caps: planCaps(config),
             requirements: base.dryRun
@@ -144,8 +177,7 @@ const DEFAULT_APP_URL_SESSION_MS = 30 * 60_000;
 function defaultSessionTimeoutMs(plane, ceilingMs) {
     if (plane.kind !== "provisioned")
         return DEFAULT_APP_URL_SESSION_MS;
-    const stateBudgetMs = (plane.subject.state.seed ?? []).reduce((sum, step) => sum + (step.timeoutMs ?? DEFAULT_STATE_STEP_TIMEOUT_MS), 0);
-    const room = ceilingMs - SUBJECT_PROVISION_BUDGET_MS - stateBudgetMs - SANDBOX_TIMEOUT_BUFFER_MS;
+    const room = ceilingMs - sandboxHeadroomMs({ seed: plane.subject.state.seed ?? [] });
     return Math.max(MIN_DERIVED_SESSION_MS, Math.min(MAX_DERIVED_SESSION_MS, room));
 }
 /** The provisioned plane's declared subject state. The external-public plane declares none. */