humanish 0.116.0 → 0.117.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/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/plan.js

@@ -10,7 +10,7 @@ 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 { 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";
@@ -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 &&

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/shared-world/plan.js

@@ -10,7 +10,7 @@ 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";
@@ -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));

package/dist/routes/terminal/live-sandbox.d.ts

@@ -45,7 +45,7 @@ export declare class LiveTerminalSandbox {
     private readonly wallClockMs;
     private readonly sandboxTimeoutMs;
     private sandbox;
-    private module;
+    private account;
     private allocation;
     private startupCleanup;
     private startupCleanupDetail;

package/dist/routes/terminal/live-sandbox.js

@@ -11,6 +11,7 @@ import { extractLocalActorVerdict, normalizeLocalActorTranscript, } from "../../
 import { NODE_BOOTSTRAP_COMMAND, NODE_BOOTSTRAP_TIMEOUT_MS } from "../../subject/node-bootstrap.js";
 import { observeDesktopResources, } from "../../substrates/e2b/desktop-resources.js";
 import { acquireE2BShellSandbox } from "../../substrates/e2b/sandbox.js";
+import { e2bAccount } from "../../substrates/e2b/connection.js";
 import { E2BDesktopStartupError, loadE2BDesktopModule, } from "../../substrates/e2b/sdk.js";
 import { shellQuote } from "../../substrates/shell.js";
 import { buildOpenAiEgressNetwork } from "./runtime-auth.js";
@@ -36,7 +37,7 @@ export class LiveTerminalSandbox {
     wallClockMs;
     sandboxTimeoutMs;
     sandbox;
-    module;
+    account;
     allocation;
     startupCleanup;
     startupCleanupDetail;
@@ -60,7 +61,6 @@ export class LiveTerminalSandbox {
         // Declared egress allowlist, or undefined for the historical unrestricted default.
         const egressAllow = plan.egressAllow;
         const sandboxModule = await (deps.desktopModule ?? loadE2BDesktopModule)();
-        this.module = sandboxModule;
         await validatePreparedRunArtifactPaths(runPaths);
         // No sandbox-global env in either mode. In openai-egress, only this host-side SDK request
         // carries the real runtime key; participant commands receive an inert placeholder. The proxy
@@ -71,16 +71,19 @@ export class LiveTerminalSandbox {
         const network = runtimeEnv.mode === "openai-egress"
             ? buildOpenAiEgressNetwork(runtimeEnv.keyValue, routing)
             : routing;
+        const options = {
+            apiKey: e2bApiKey,
+            requestTimeoutMs,
+            timeoutMs: sandboxTimeoutMs,
+            metadata,
+            ...(network === undefined ? {} : { network }),
+            lifecycle: { onTimeout: "kill" },
+        };
+        // Teardown's check by id reaches the account the create used, whatever process.env names.
+        this.account = e2bAccount(sandboxModule, options);
         const acquired = await acquireE2BShellSandbox({
             module: sandboxModule,
-            options: {
-                apiKey: e2bApiKey,
-                requestTimeoutMs,
-                timeoutMs: sandboxTimeoutMs,
-                metadata,
-                ...(network === undefined ? {} : { network }),
-                lifecycle: { onTimeout: "kill" },
-            },
+            options,
             retry: {
                 // A failed first attempt may have allocated a sandbox whose id never reached this run;
                 // its own kill-on-timeout reclaims it.
@@ -418,7 +421,7 @@ export class LiveTerminalSandbox {
         // --- Proven cleanup, by exact id, never Sandbox.list. ---
         this.cleanup = await teardownSandbox({
             allocation: this.allocation,
-            sandboxModule: this.module,
+            account: this.account,
             ...(this.startupCleanup === undefined ? {} : { startupCleanup: this.startupCleanup }),
             startupCleanupDetail: this.startupCleanupDetail,
             requestTimeoutMs,

package/dist/routes/terminal/sandbox.d.ts

@@ -1,5 +1,6 @@
 import type { OwnedDesktopAllocation } from "../../substrates/desktop-session.js";
-import { E2BDesktopStartupError, type E2BDesktopModule } from "../../substrates/e2b/sdk.js";
+import type { E2BAccount } from "../../substrates/e2b/connection.js";
+import { E2BDesktopStartupError } from "../../substrates/e2b/sdk.js";
 import type { TerminalLedgers } from "./types.js";
 /**
  * Tear the sandbox down and prove it by exact id, never by Sandbox.list (humanish must never
@@ -14,8 +15,8 @@ import type { TerminalLedgers } from "./types.js";
 export declare function teardownSandbox(args: {
     /** The allocation from acquisition; its release kills the exact id it captured. */
     allocation: OwnedDesktopAllocation | undefined;
-    /** For the Sandbox.getInfo(id) re-check only. */
-    sandboxModule: E2BDesktopModule | undefined;
+    /** The account the create used, for the Sandbox.getInfo(id) re-check only. */
+    account: E2BAccount | undefined;
     startupCleanup?: E2BDesktopStartupError["cleanup"];
     /** Why the startup guard's cleanup is unconfirmed, when it knows. */
     startupCleanupDetail?: string | undefined;

package/dist/routes/terminal/sandbox.js

@@ -1,5 +1,5 @@
 import { toErrorMessage } from "../../evidence/redaction.js";
-import { E2BDesktopStartupError, isSandboxNotFoundError, } from "../../substrates/e2b/sdk.js";
+import { E2BDesktopStartupError, isSandboxNotFoundError } from "../../substrates/e2b/sdk.js";
 import { releaseUnavailableDetail } from "../../substrates/e2b/sandbox.js";
 /**
  * Tear the sandbox down and prove it by exact id, never by Sandbox.list (humanish must never
@@ -12,8 +12,8 @@ import { releaseUnavailableDetail } from "../../substrates/e2b/sandbox.js";
  * fails closed on an unproven teardown.
  */
 export async function teardownSandbox(args) {
-    const { allocation, sandboxModule, startupCleanup, startupCleanupDetail, requestTimeoutMs, sanitize, recordLifecycle, warnings, } = args;
-    if (allocation === undefined || !sandboxModule) {
+    const { allocation, account, startupCleanup, startupCleanupDetail, requestTimeoutMs, sanitize, recordLifecycle, warnings, } = args;
+    if (allocation === undefined || account === undefined) {
         // create() can reject after its constructor acquired a handle. The default loader retains
         // that authority and reclaims it before rejecting; the route itself never receives its ID.
         if (startupCleanup === "killed" || startupCleanup === "already_gone") {
@@ -58,7 +58,7 @@ export async function teardownSandbox(args) {
     const killNote = released.reason === "terminated"
         ? "kill(id) returned true (found and killed)"
         : "kill(id) found the exact sandbox already gone (404)";
-    if (typeof sandboxModule.Sandbox.getInfo !== "function") {
+    if (account.getInfo === undefined) {
         recordLifecycle("terminal-lab.cleanup.killed", `Sandbox ${sandboxId} reclaimed: ${killNote}; the installed SDK has no getInfo(id) to re-verify, so kill(id)'s own result is the proof.`);
         return {
             killed: true,
@@ -67,7 +67,7 @@ export async function teardownSandbox(args) {
         };
     }
     try {
-        const info = await sandboxModule.Sandbox.getInfo(sandboxId, { requestTimeoutMs });
+        const info = await account.getInfo(sandboxId, { requestTimeoutMs });
         const state = info.state ?? "unknown";
         recordLifecycle("terminal-lab.cleanup.unconfirmed", `Sandbox ${sandboxId} ${killNote}, but getInfo(id) still reports state=${state} (not confirmed reclaimed by id).`);
         return {

package/dist/study/config.js

@@ -40,7 +40,7 @@ import { isComputerUseComposition, isSharedWorldComposition, routeOf } from "./r
 import { declaredParticipantIds } from "./plan-participants.js";
 import { declaredParticipantCount, participantList } from "./study-fields.js";
 import { ID_PATTERN, STUDY_SCHEMA, } from "./types.js";
-import { automaticAnalysisRouteReason, desktopMediaValidationReason, outputTokenLimitValidationReason, receivingEmailValidationReason, smtpValidationReason, taskProtocolValidationReason, } from "./validation.js";
+import { automaticAnalysisRouteReason, desktopMediaValidationReason, outputTokenLimitValidationReason, receivingEmailValidationReason, smtpValidationReason, taskProtocolValidationReason, waitLimitValidationReason, } from "./validation.js";
 import { forwardDeclaredWarnings, inertFieldLabels, inertFieldPaths } from "./warnings.js";
 import { plural } from "../run/text.js";
 /**
@@ -228,6 +228,9 @@ function checkStudyConfig(config) {
     const outputLimitReason = outputTokenLimitValidationReason(config);
     if (outputLimitReason)
         return invalid(outputLimitReason);
+    const waitLimitReason = waitLimitValidationReason(config);
+    if (waitLimitReason)
+        return invalid(waitLimitReason);
     // All-parallel default: a multi-participant study that does not declare execution.concurrency
     // runs every participant at once; the declared field is a cap the author chose, never a mode.
     // Independent computer-use participants resolve that default from the final participant count

package/dist/study/keys.d.ts

@@ -107,6 +107,8 @@ export declare const ACTOR: {
     mission: true;
     model: true;
     maxOutputTokens: true;
+    maxWaitMs: true;
+    idleWaitMs: true;
     localAgent: true;
     reasoningEffort: true;
     stopWhen: {

package/dist/study/keys.js

@@ -94,6 +94,8 @@ export const ACTOR = {
     mission: true,
     model: true,
     maxOutputTokens: true,
+    maxWaitMs: true,
+    idleWaitMs: true,
     localAgent: true,
     reasoningEffort: true,
     stopWhen: STOP_WHEN,

package/dist/study/migrate/v2.js

@@ -95,7 +95,8 @@ const V2_KEYS = {
         lanes: PARTICIPANT_ENTRY,
         // Roster groups are participants with a count; the parser expanded them into `lanes[]`.
         roster: { ...PARTICIPANT_ENTRY, count: true },
-        ...without(ACTOR, "type"),
+        // maxWaitMs and idleWaitMs arrived after v2, so a v2 file cannot carry them.
+        ...without(ACTOR, "type", "maxWaitMs", "idleWaitMs"),
         laneFocus: { id: true, label: true, instruction: true },
     },
     execution: withAfter(EXECUTION, "egressAllow", { caps: CAPS }),

package/dist/study/parse/actors.js

@@ -1,6 +1,7 @@
 import { DEVICE_PRESET_NAMES, isDevicePresetName } from "../device-presets.js";
 import { isReasoningEffort, reasoningEffortNames } from "../../actors/reasoning-effort.js";
 import { isMaxOutputTokens } from "../../actors/output-token-limit.js";
+import { waitFieldsReason } from "../../actors/computer-use/wait.js";
 import { isHttpUrl } from "./subject.js";
 import { entryCredentialReason, urlCredentialReason } from "./url-credentials.js";
 import { registeredComputerUseActors, registeredScriptedBrowserActors, registeredTerminalActors, } from "../routing.js";
@@ -54,6 +55,13 @@ export function parseActorFields(entry, path) {
             return invalid(`${path}.maxOutputTokens must be a positive safe integer.`);
         actor.maxOutputTokens = entry.maxOutputTokens;
     }
+    const waitReason = waitFieldsReason(entry, `${path}.`);
+    if (waitReason)
+        return invalid(waitReason);
+    if (typeof entry.maxWaitMs === "number")
+        actor.maxWaitMs = entry.maxWaitMs;
+    if (typeof entry.idleWaitMs === "number")
+        actor.idleWaitMs = entry.idleWaitMs;
     const localAgent = str(entry.localAgent);
     if (entry.localAgent !== undefined) {
         if (localAgent !== "codex" && localAgent !== "claude") {

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

@@ -36,6 +36,10 @@ interface DesktopParticipant extends Participant {
         readonly dwell?: DwellWindow;
         readonly reasoningEffort?: ReasoningEffort;
         readonly maxOutputTokens?: number;
+        /** actor.maxWaitMs: the longest one wait action lasts. */
+        readonly maxWaitMs?: number;
+        /** actor.idleWaitMs: how long a wait with no duration lasts while the participant only waits. */
+        readonly idleWaitMs?: number;
     };
 }
 /** Only independent computer-use participants consume a task protocol and their own target. */

package/dist/study/plan-participants.js

@@ -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 }),
         },
     };
 }

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

@@ -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,4 +1,5 @@
 import { isMaxOutputTokens } from "../actors/output-token-limit.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";
@@ -235,6 +236,13 @@ 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

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

package/dist/substrates/e2b/desktop-executor.js

@@ -2,8 +2,8 @@ import { shellQuote } from "../shell.js";
 import { perceptualSignature } from "../../evidence/frame-signature.js";
 import { commandFailureInfo } from "../command-failure.js";
 import { ComputerUseExecutorError } from "../../actors/computer-use/executor-error.js";
+import { CUA_WAIT_LIMITS } from "../../actors/computer-use/wait.js";
 import { xdotoolChord, xdotoolHeldModifiers } from "../../guest/desktop-keys.js";
-const DEFAULT_WAIT_MS = 500;
 const DEFAULT_SCROLL_AMOUNT_PER_TICK = 100;
 const TYPE_COMMAND_TIMEOUT_MS = 15_000;
 const KEY_COMMAND_TIMEOUT_MS = 15_000;
@@ -145,7 +145,6 @@ async function typeText(desktop, text) {
  * screenshot or action is ever logged.
  */
 export function createE2BDesktopExecutor(desktop, options = {}) {
-    const defaultWaitMs = options.defaultWaitMs ?? DEFAULT_WAIT_MS;
     const scrollAmountPerTick = options.scrollAmountPerTick ?? DEFAULT_SCROLL_AMOUNT_PER_TICK;
     return {
         async observe() {
@@ -258,7 +257,8 @@ export function createE2BDesktopExecutor(desktop, options = {}) {
                 return;
             }
             case "wait":
-                await desktop.wait(action.ms ?? defaultWaitMs);
+                // The loop sends every wait with its length; planWait owns the lengths.
+                await desktop.wait(action.ms ?? CUA_WAIT_LIMITS.settleMs);
                 return;
             case "screenshot":
                 // No-op: the loop calls observe() separately to capture each frame, so