humanish 0.115.0 → 0.117.0

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/plan-types.d.ts

@@ -196,8 +196,8 @@ export interface SharedWorldPlan extends PlanBase {
     readonly plane: SharedWorldPlane;
     /** At least 2. */
     readonly concurrency: number;
-    /** The declared participant session timeout; the route supplies its default. */
-    readonly sessionTimeoutMs?: number;
+    /** Each participant's session budget: execution.timeoutMs, else the plane's derived default. */
+    readonly sessionTimeoutMs: number;
     readonly brain: Extract<Brain, {
         kind: "openai" | "local-agent";
     }>;

package/dist/study/plan.d.ts

@@ -6,8 +6,10 @@ export { routeOf, type StudyRoute } from "./routing.js";
 /** Resolve dry-run: explicit override wins, else the scenario mode, else the given fallback. */
 export declare function resolveStudyDryRun(config: StudyConfig, override: boolean | undefined, fallback: boolean | undefined): boolean | undefined;
 /**
- * The plan a study runs under, built without reading files, env or the network. 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.
+ * 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.
  */
 export declare function planStudy(config: StudyConfig, options: InternalRunStudyOptions, deps?: StudyDeps): PlanResult;

package/dist/study/plan.js

@@ -6,13 +6,14 @@ 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 { localBrowserDefaults } from "../substrates/local/runtime-config.js";
 import { THIS_REPO_DRY_RUN_ONLY } from "./composition-rules.js";
 import { planBase } from "./plan-base.js";
 import { routeOf } from "./routing.js";
 import { automaticAnalysisRouteReason, taskProtocolValidationReason } from "./validation.js";
 import { declaredParticipantCount } from "./study-fields.js";
-import { egressAllowIgnoredWarning, scriptedMissionWarnings } from "./warnings.js";
+import { recordedStudyWarnings } from "./warnings.js";
 export { routeOf } from "./routing.js";
 /** Resolve dry-run: explicit override wins, else the scenario mode, else the given fallback. */
 export function resolveStudyDryRun(config, override, fallback) {
@@ -63,20 +64,22 @@ function planPreview(config, options, input) {
     };
 }
 /**
- * The plan a study runs under, built without reading files, env or the network. 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.
+ * 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.
  */
 export function planStudy(config, options, deps = {}) {
     const study = localBrowserDefaults(config);
     const input = { dryRun: resolveStudyDryRun(study, options.dryRun, true) ?? true };
-    const result = planRoute(routeOf(config), study, options, input, deps);
+    const ceiling = sandboxCeiling(options.env ?? process.env);
+    const result = planRoute(routeOf(config), study, options, input, deps, ceiling);
     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 warning = egressAllowIgnoredWarning(study);
-    const warnings = [...(warning === undefined ? [] : [warning]), ...scriptedMissionWarnings(study)];
+    const warnings = recordedStudyWarnings(study);
     const plan = {
         ...result.plan,
         ...(options.study === undefined ? {} : { study: options.study }),
@@ -84,7 +87,7 @@ export function planStudy(config, options, deps = {}) {
     };
     return { ok: true, planned: { plan } };
 }
-function planRoute(route, study, options, input, deps) {
+function planRoute(route, study, options, input, deps, sandboxCeiling) {
     switch (route) {
         case "preview":
             return planPreview(study, options, input);
@@ -95,14 +98,20 @@ function planRoute(route, study, options, input, deps) {
                 driving: callerDrivingOf(options),
                 ...(options.count === undefined ? {} : { countOverride: options.count }),
                 ...(options.rerun === undefined ? {} : { rerun: options.rerun }),
+                sandboxCeiling,
             });
         case "shared-world":
             return planSharedWorldStudy(study, {
                 ...input,
                 hasRunSession: deps.runSession !== undefined,
+                sandboxCeiling,
             });
         case "terminal":
-            return planTerminalStudy(study, { ...input, hasCostProbe: deps.costProbe !== undefined });
+            return planTerminalStudy(study, {
+                ...input,
+                hasCostProbe: deps.costProbe !== undefined,
+                sandboxCeiling,
+            });
         case "scripted":
             return planScriptedStudy(study, { ...input, injectedBrowser: injectedBrowser(deps) });
     }

package/dist/study/preflight-probes.js

@@ -4,7 +4,7 @@
 // the study and dispatches here.
 import { cloneProvisioningBudgetMs, provisionCloneSubject } from "../subject/clone.js";
 import { CUA_ACTOR_STUDY_PROVIDER_METADATA } from "../routes/computer-use/e2b-desktop/prepare.js";
-import { MAX_SANDBOX_MS } from "../substrates/e2b/lifetime.js";
+import { sandboxCeiling } from "../substrates/e2b/lifetime.js";
 import { abandonPreflightJournal, discardPreflightJournal, openPreflightJournal, } from "../run/preflight-receipts.js";
 import { probeUrl } from "../substrates/detached.js";
 import { loadE2BDesktopModule } from "../substrates/e2b/sdk.js";
@@ -147,8 +147,16 @@ async function withPreflightSandbox(ctx, args, callback) {
     let allocation;
     let failureMessage;
     // The lease is sized to the probe's work, never longer than a declared sandbox timeout (the run
-    // gets no more than that either) or E2B's maximum.
-    const timeoutMs = Math.min(args.leaseMs, ctx.config.execution?.desktop?.sandboxTimeoutMs ?? MAX_SANDBOX_MS);
+    // gets no more than that either) or the sandbox ceiling.
+    const ceiling = sandboxCeiling(ctx.env);
+    if (!ceiling.ok)
+        return {
+            ok: false,
+            result: fail(ctx, "HUMANISH_STUDY_PREFLIGHT_PROVISION_FAILED", ceiling.message, [
+                { name: "sandbox preflight", ok: false, message: ceiling.message },
+            ]),
+        };
+    const timeoutMs = Math.min(args.leaseMs, ctx.config.execution?.desktop?.sandboxTimeoutMs ?? ceiling.ms);
     // The receipt goes to a journal under .humanish/preflight, so `humanish reclaim --preflight`
     // can kill the probe if this process dies before the finally block does.
     let journal;

package/dist/study/preflight.js

@@ -1,4 +1,4 @@
-import { personaBackgroundWarnings } from "./warnings.js";
+import { personaBackgroundWarnings, plannedParticipants } from "./warnings.js";
 import { resolveCommittedPersonasForCwd, studyPersonaIds } from "./persona-resolve.js";
 import path from "node:path";
 import { isLoopbackUrl } from "./parse/subject.js";
@@ -37,9 +37,10 @@ export async function runStudyPreflight(options) {
             error: resolved.error,
         };
     }
-    const personas = resolved.config.route === "computer-use" || resolved.config.route === "shared-world"
-        ? (await resolveCommittedPersonasForCwd(cwd, studyPersonaIds(resolved.config))).personas
-        : new Map();
+    const participants = plannedParticipants(resolved.config);
+    const personas = participants.length === 0
+        ? new Map()
+        : (await resolveCommittedPersonasForCwd(cwd, studyPersonaIds(resolved.config))).personas;
     const route = routeOf(resolved.config);
     const ctx = {
         cwd,
@@ -59,7 +60,10 @@ export async function runStudyPreflight(options) {
         ],
         targets: collectTargets(resolved.config),
         sandbox: { created: false },
-        warnings: [...resolved.warnings, ...personaBackgroundWarnings(resolved.config, personas)],
+        warnings: [
+            ...resolved.warnings,
+            ...personaBackgroundWarnings(resolved.config.id, participants, personas),
+        ],
     };
     const machine = machineCheck(ctx.config);
     // A local study's app and desktops run on this machine, so the hosted probes do not apply.

package/dist/study/summary.d.ts

@@ -38,9 +38,15 @@ export interface StudySummary {
      * default. A study variable you cannot see is one nobody chose.
      */
     reasoningEffort?: string;
-    caps: StudyCaps;
+    /** Absent on routes whose dollar caps the summary does not show; `{}` when none is declared. */
+    caps?: StudyCaps;
     /**
-     * Whether the configured route's required keys resolve. Dry runs require none. This checks key
+     * What `humanish run <study>` runs this file as: its `mode`, a dry run when it sets none. The TUI
+     * cannot start a live run of a dry-run file, because no `run` flag overrides the file to live.
+     */
+    mode: "live" | "dry-run";
+    /**
+     * Whether the keys a live run of this study needs resolve, whatever its mode. This checks key
      * presence, not local CLI authentication or provider validity. Undefined when not checked.
      */
     keysReady?: boolean;

package/dist/study/summary.js

@@ -7,10 +7,9 @@ import { localRuntimeStatus } from "../substrates/local/runtime.js";
 // what a stakeholder reads on the screen where they decide whether to press Start.
 //
 // Resolved analysis defaults are shown independently of declared participant caps. A cap that is not
-// declared is not "unlimited" and not "$0"; it is a line the screen does not draw.
-import { resolveStudyDryRun } from "./plan.js";
-import { routeOf } from "./plan.js";
-import { localCodexParticipantCheck, planCliRun } from "./doctor.js";
+// declared is not "unlimited" and not "$0": the screen says that no cap is set.
+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 { DEFAULT_OPENAI_CU_MODEL, DEFAULT_OPENAI_CU_REASONING_EFFORT, } from "../actors/computer-use/openai-provider.js";
@@ -70,7 +69,7 @@ function participantsOf(config) {
 /** The computer-use caps. Other routes draw none. */
 function summaryCapsOf(config) {
     if (!isComputerUseComposition(config))
-        return {};
+        return undefined;
     const caps = config.caps;
     return {
         ...(typeof caps?.maxUsd === "number" ? { laneUsd: caps.maxUsd } : {}),
@@ -89,18 +88,17 @@ export async function readStudySummary(cwd, study, options = {}) {
     const route = routeOf(inspected.config);
     let keysReady;
     let missingKeys;
-    const dryRun = resolveStudyDryRun(inspected.config, undefined, true) === true;
-    // A live key check reads the plan's requirements. A study the planner refuses has none to check,
-    // so the summary reports the refusal in place of its keys.
-    const planned = options.checkKeys === true && !dryRun ? await planCliRun(inspected.config, cwd) : undefined;
+    const mode = resolveStudyDryRun(inspected.config, undefined, true) === true ? "dry-run" : "live";
+    // The keys are the live plan's, whatever the file's mode: the screen offers a live run of every
+    // study, and a dry run needs no keys to report. A study the planner refuses live has none to
+    // check, so the summary reports the refusal in place of its keys.
+    const planned = options.checkKeys === true ? planStudy(inspected.config, { cwd, dryRun: false }) : undefined;
     const planRefusal = planned?.ok === false ? planned.refusal.message : undefined;
-    if (options.checkKeys === true && planned?.ok !== false) {
-        const requirements = planned?.planned.plan.requirements ?? [];
+    if (planned?.ok === true) {
+        const requirements = planned.planned.plan.requirements;
         const subjectKeys = requiredSubjectEnv(requirements);
         const email = inspected.config.comms?.email;
-        const receivingKey = !dryRun && email?.kind === "real"
-            ? await receivingRequiredKey(cwd, email.connection)
-            : undefined;
+        const receivingKey = email?.kind === "real" ? await receivingRequiredKey(cwd, email.connection) : undefined;
         const candidates = [
             "OPENAI_API_KEY",
             "CODEX_API_KEY",
@@ -108,13 +106,11 @@ export async function readStudySummary(cwd, study, options = {}) {
             ...subjectKeys,
             ...(receivingKey ? [receivingKey] : []),
         ];
-        const probes = dryRun
-            ? []
-            : await probeKeySources(candidates, {
-                cwd,
-                env: options.env ?? process.env,
-                ...(options.keyDeps === undefined ? {} : { deps: options.keyDeps }),
-            }).catch(() => []);
+        const probes = await probeKeySources(candidates, {
+            cwd,
+            env: options.env ?? process.env,
+            ...(options.keyDeps === undefined ? {} : { deps: options.keyDeps }),
+        }).catch(() => []);
         const present = new Set(probes.filter((probe) => probe.source !== null).map((probe) => probe.name));
         const required = requiredKeys(requirements, (name) => present.has(name));
         const missing = [
@@ -130,6 +126,7 @@ export async function readStudySummary(cwd, study, options = {}) {
     const analysis = automaticAnalysisBudget(inspected.config.review?.analysis, route, computerUseParticipantCount(inspected.config));
     const subject = subjectOf(config);
     const participants = participantsOf(inspected.config);
+    const caps = summaryCapsOf(inspected.config);
     const runtime = options.checkKeys === true && isLocalBrowserStudy(inspected.config)
         ? await localRuntimeStatus({
             ...(options.env ? { env: options.env } : {}),
@@ -170,7 +167,8 @@ export async function readStudySummary(cwd, study, options = {}) {
         ...(participants === undefined ? {} : { participants }),
         model: inspected.config.actor?.model ?? DEFAULT_OPENAI_CU_MODEL,
         reasoningEffort: reasoningEffortOf(inspected.config),
-        caps: summaryCapsOf(inspected.config),
+        ...(caps === undefined ? {} : { caps }),
+        mode,
         ...(keysReady === undefined ? {} : { keysReady }),
         ...(missingKeys === undefined ? {} : { missingKeys }),
         ...(planRefusal === undefined ? {} : { planRefusal }),

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.d.ts

@@ -1,5 +1,6 @@
 import type { ResolvedPersona } from "./persona.js";
 import type { StudyConfig } from "./types.js";
+import { type Participant } from "./plan-participants.js";
 /**
  * The fields a config sets that its route does not read, each as `field` or `field (reason)`.
  * parseStudy refuses a study for any of them.
@@ -10,17 +11,23 @@ export declare function inertFieldLabels(config: StudyConfig): string[];
  * `participants[].entry` or `execution.timeoutMs`. `humanish migrate` drops each one.
  */
 export declare function inertFieldPaths(config: StudyConfig): string[];
+export declare function forwardDeclaredWarnings(config: StudyConfig): string[];
 /**
- * The warning for `execution.egressAllow` on a route that ignores it, or undefined. Only the
- * terminal route creates its sandbox with the list as an outbound allowlist; on any other route the
- * study author would trust a list that blocks nothing. `humanish study check` and every run print
- * it, and the run records it in its bundle.
- * Removed in the first minor release on or after 2026-11-04: deprecated on 2026-10-05. That release refuses the field off the terminal
- * route.
+ * The warnings about a study's own fields that a run records in its bundle as `study.warning`
+ * events: `execution.egressAllow` off the terminal route, and participant text that reads like a
+ * script. parseStudy reports them too, after its other warnings, so `study check` and every run
+ * print them.
  */
-export declare function egressAllowIgnoredWarning(config: StudyConfig): string | undefined;
-export declare function forwardDeclaredWarnings(config: StudyConfig): string[];
-/** Authored participant text is checked before runtime instructions or researcher criteria join it. */
-export declare function scriptedMissionWarnings(config: StudyConfig): string[];
-/** Backgrounds give participants a reason to act beyond the assigned task. */
-export declare function personaBackgroundWarnings(config: StudyConfig, personas: ReadonlyMap<string, ResolvedPersona>): string[];
+export declare function recordedStudyWarnings(config: StudyConfig): string[];
+/**
+ * A warning for each participant whose persona has no background, which gives a participant a
+ * reason to act beyond the assigned task. `participants` are the records the planner builds: a
+ * computer-use or shared-world plan's participants, or `plannedParticipants` before a plan exists.
+ */
+export declare function personaBackgroundWarnings(studyId: string, participants: readonly Pick<Participant, "id" | "personaId">[], personas: ReadonlyMap<string, ResolvedPersona>): string[];
+/**
+ * The participant records planStudy builds for a study's declared participants, for `study check`
+ * and `study show`, which run no plan. Only computer-use and shared-world studies have them; a run's
+ * `--count` is not applied.
+ */
+export declare function plannedParticipants(config: StudyConfig): readonly Participant[];

package/dist/study/warnings.js

@@ -1,6 +1,6 @@
 import { cli } from "../cli/invocation.js";
 import { isComputerUseComposition, isScriptedBrowserComposition, isSharedWorldComposition, isTerminalProductComposition, } from "./routing.js";
-import { declaredParticipantIds } from "./plan-participants.js";
+import { computerUseParticipants, declaredParticipantIds, sharedWorldParticipants, } from "./plan-participants.js";
 import { addressedRecipients } from "./parse/comms.js";
 import { participantList, participantInstruction, declaredParticipantCount, } from "./study-fields.js";
 // The computer-use and terminal routes consume mission/persona/model (they compose the agent prompt
@@ -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";
@@ -269,12 +281,11 @@ export function inertFieldPaths(config) {
 /**
  * The warning for `execution.egressAllow` on a route that ignores it, or undefined. Only the
  * terminal route creates its sandbox with the list as an outbound allowlist; on any other route the
- * study author would trust a list that blocks nothing. `humanish study check` and every run print
- * it, and the run records it in its bundle.
+ * study author would trust a list that blocks nothing.
  * Removed in the first minor release on or after 2026-11-04: deprecated on 2026-10-05. That release refuses the field off the terminal
  * route.
  */
-export function egressAllowIgnoredWarning(config) {
+function egressAllowIgnoredWarning(config) {
     if (config.execution?.egressAllow === undefined || config.route === "terminal")
         return undefined;
     return `\`execution.egressAllow\` is ignored on route: ${config.route}. Only route: terminal creates its sandbox with that outbound allowlist, and this route's browser desktops can reach any site. Remove the field: the first minor release on or after 2026-11-04 refuses it on every route except terminal.`;
@@ -289,9 +300,6 @@ export function forwardDeclaredWarnings(config) {
         : [
             `These fields are set, but no route reads them yet, so they have no effect: ${inert.join(", ")}.`,
         ];
-    const egressIgnored = egressAllowIgnoredWarning(config);
-    if (egressIgnored !== undefined)
-        warnings.push(egressIgnored);
     // A declared cap below the participant count is legal but loud: the roster promises N live actors
     // and the cap delivers waves of M. Say so up front (inspect + dry-run + run): a green run in
     // waves is otherwise indistinguishable from the all-live run the author meant.
@@ -312,7 +320,20 @@ export function forwardDeclaredWarnings(config) {
             warnings.push(`comms.email covers ${covered.size} of ${participantIds.length} participants. These get no inbox and are never told one exists: ${uncovered.join(", ")}. Add a recipient with an address for each one whose flow needs email.`);
         }
     }
-    return [...warnings, ...scriptedMissionWarnings(config)];
+    return [...warnings, ...recordedStudyWarnings(config)];
+}
+/**
+ * The warnings about a study's own fields that a run records in its bundle as `study.warning`
+ * events: `execution.egressAllow` off the terminal route, and participant text that reads like a
+ * script. parseStudy reports them too, after its other warnings, so `study check` and every run
+ * print them.
+ */
+export function recordedStudyWarnings(config) {
+    const egressIgnored = egressAllowIgnoredWarning(config);
+    return [
+        ...(egressIgnored === undefined ? [] : [egressIgnored]),
+        ...scriptedMissionWarnings(config),
+    ];
 }
 const UI_ACTION = /\b(?:click|tap|press|type\b[^.!?\n]*?\binto|select\b[^.!?\n]*?\bfrom)\b/gi;
 function normalizedUrl(value) {
@@ -343,7 +364,7 @@ function actionChain(text) {
             /\bthen\b/i.test(text.slice((actions[0]?.index ?? 0) + (actions[0]?.[0].length ?? 0)))));
 }
 /** Authored participant text is checked before runtime instructions or researcher criteria join it. */
-export function scriptedMissionWarnings(config) {
+function scriptedMissionWarnings(config) {
     if (config.route !== "computer-use" && config.route !== "shared-world")
         return [];
     const fields = [
@@ -374,20 +395,32 @@ export function scriptedMissionWarnings(config) {
         ];
     });
 }
-/** Backgrounds give participants a reason to act beyond the assigned task. */
-export function personaBackgroundWarnings(config, personas) {
-    if (config.route !== "computer-use" && config.route !== "shared-world")
-        return [];
-    const roster = participantList(config);
-    return declaredParticipantIds(config).flatMap((id, index) => {
-        const personaId = roster?.[index]?.persona ?? config.actor?.persona;
+/**
+ * A warning for each participant whose persona has no background, which gives a participant a
+ * reason to act beyond the assigned task. `participants` are the records the planner builds: a
+ * computer-use or shared-world plan's participants, or `plannedParticipants` before a plan exists.
+ */
+export function personaBackgroundWarnings(studyId, participants, personas) {
+    return participants.flatMap(({ id, personaId }) => {
         if (personaId && personas.get(personaId)?.background)
             return [];
         const reason = personaId
             ? `persona ${personaId} has no readable background`
             : "no persona is assigned";
         return [
-            `Participant ${id} has no persona background because ${reason}. Add a short, fictional background describing their experience and situation. Run ${cli(`study show ${config.id} --json`)} to see what the participant receives.`,
+            `Participant ${id} has no persona background because ${reason}. Add a short, fictional background describing their experience and situation. Run ${cli(`study show ${studyId} --json`)} to see what the participant receives.`,
         ];
     });
 }
+/**
+ * The participant records planStudy builds for a study's declared participants, for `study check`
+ * and `study show`, which run no plan. Only computer-use and shared-world studies have them; a run's
+ * `--count` is not applied.
+ */
+export function plannedParticipants(config) {
+    if (config.route === "computer-use")
+        return computerUseParticipants(config);
+    if (config.route === "shared-world")
+        return sharedWorldParticipants(config).participants;
+    return [];
+}

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/connection.d.ts

@@ -0,0 +1,12 @@
+import type { E2BConnection, E2BDesktopModule } from "./sdk.js";
+/** The connection an env names: E2B_API_KEY and E2B_DOMAIN, trimmed, each only when set. */
+export declare function e2bConnection(env: Readonly<Record<string, string | undefined>>): E2BConnection;
+/** The calls humanish makes on sandboxes that already exist. */
+export type E2BAccount = Pick<E2BDesktopModule["Sandbox"], "kill" | "getInfo" | "list">;
+/**
+ * The kill, getInfo and list of `module`, each carrying `connection`'s key and domain over the
+ * call's own options. `connection` may be a create's options, so the release of a sandbox reaches
+ * the account that created it. Each method is bound now: a hook that later replaces one on the
+ * shared module does not change this account. A method the installed SDK lacks stays absent.
+ */
+export declare function e2bAccount(module: E2BDesktopModule, connection: E2BConnection): E2BAccount;