humanish 0.116.0 → 0.118.0

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

@@ -62,8 +62,8 @@ export function sharedWorldStudyRefusal(options, refusal) {
         studyId: config.id,
         actor: config.actor?.type ?? "",
         participantCount: declared.length,
-        // The parser fills concurrency for multi-participant studies, so this fallback serves only
-        // library callers: every declared participant runs at once unless the author declared a cap.
+        // A refused study never planned its concurrency, so its result reports the declared cap, else
+        // every declared participant.
         concurrency: config.execution?.concurrency ?? Math.max(1, declared.length),
         dryRun,
         runId: options.runId,

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/run/bundle-shape.js

@@ -216,7 +216,8 @@ function isRunSubjectProvenance(value) {
     if (value.source !== "clone" &&
         value.source !== "app-url" &&
         value.source !== "local-tree" &&
-        value.source !== "desktop-cli")
+        value.source !== "desktop-cli" &&
+        value.source !== "local-app")
         return false;
     if (value.repo !== undefined && typeof value.repo !== "string")
         return false;

package/dist/run/bundle.d.ts

@@ -158,7 +158,8 @@ export interface RunSubjectStateStepRecord {
  * pre-existing bundles).
  */
 export interface RunSubjectProvenance {
-    source: "clone" | "app-url" | "local-tree" | "desktop-cli";
+    /** A run saved before `desktop-cli` or `local-app` was recorded says `app-url` for either. */
+    source: "clone" | "app-url" | "local-tree" | "desktop-cli" | "local-app";
     /** Clone-route only. Honors policies.redactRepos exactly as the provenance event does. */
     repo?: string;
     /** Desktop-cli only: the product the study declares in `subject.product.name`. */
@@ -186,8 +187,9 @@ export interface RunSubjectProvenance {
          *   an external DB is still unpinned overall).
          * declared-not-run: steps declared but not (all) executed ok: dry-run contract bundles
          *   and failed live provisioning.
-         * undeclared: no subject.state block (stateless apps, app-url and desktop-cli subjects),
-         *   the explicit "absence declared" marker that provenance requires when there is none.
+         * undeclared: no subject.state block (stateless apps, app-url, local-app and desktop-cli
+         *   subjects), the explicit "absence declared" marker that provenance requires when there
+         *   is none.
          * external-public: an operator-declared, operator-owned public deployment used
          *   directly as the shared plane; humanish neither provisioned nor seeded it (no getHost, no
          *   clone, no in-sandbox filesystem). It is not "seeded" (nothing was seeded) and not "unpinned" (this is

package/dist/run/projection.js

@@ -7,6 +7,7 @@
 //   - an unknown cost is `null` (declared absent), never 0;
 //   - truncation is reported, never silent;
 //   - a participant's reported thinking is quoted, never paraphrased or summarized.
+import { indexedRunCost } from "./run-cost.js";
 /**
  * Group runs by study, newest-first within each study and by recency between studies. Runs with no study
  * attribution are collected under `unattributed` rather than invented into a study. That is the
@@ -74,9 +75,13 @@ export function expectationFor(entries, mode) {
         .map((entry) => entry.durationMs)
         .filter((value) => typeof value === "number" && Number.isFinite(value) && value >= 0)
         .sort((a, b) => a - b);
+    // Each run's cost is the one its row and card show (src/run/run-cost.ts): participants and
+    // desktops plus its analyses. A run whose participants and desktops have no figure stays
+    // unpriced below, so an analysis alone never stands in for what a run cost.
     const costs = finished
-        .map((entry) => entry.estimatedCostUsd)
-        .filter((value) => typeof value === "number" && Number.isFinite(value))
+        .filter((entry) => typeof entry.estimatedCostUsd === "number" && Number.isFinite(entry.estimatedCostUsd))
+        .map((entry) => indexedRunCost(entry).total?.usd)
+        .filter((value) => value !== undefined)
         .sort((a, b) => a - b);
     // A cost is unknown whether it was declared absent (`null`) or never recorded at all
     // (`undefined`: every fail-closed exit finalized with no outcome). Counting only the first

package/dist/run/route-shell.js

@@ -4,6 +4,7 @@
 // either is made here once. The preview route records no run and has no shell.
 import { completeAutomaticAnalysis } from "../analysis/automatic-completion.js";
 import { resolveAutomaticAnalysis } from "../analysis/automatic-config.js";
+import { withParticipantLimitSkip } from "../study/automatic-analysis-plan.js";
 import { runScope } from "./run.js";
 import { withTransientCommsSecrets } from "./transient-comms-secrets.js";
 /**
@@ -12,11 +13,15 @@ import { withTransientCommsSecrets } from "./transient-comms-secrets.js";
  * it takes closes the run it started, and only a run that published its final bundle is analyzed.
  */
 export async function admitRoute(shell) {
-    const complete = (input, result, finished) => completeAutomaticAnalysis(result, finished, shell.analysis?.config, input, {
-        ...(shell.analysis === undefined ? {} : { trigger: shell.analysis.trigger }),
-        preferLargerOutput: shell.analysis?.preferLargerOutput === true,
-        ...(shell.analysisRefusal === undefined ? {} : { refusal: shell.analysisRefusal }),
-    });
+    const complete = (input, result, finished) => 
+    // A live run of more participants than one analysis reads records the skip and starts nothing.
+    shell.analysis?.skip !== undefined && !result.dryRun
+        ? Promise.resolve(withParticipantLimitSkip(result, shell.analysis.trigger))
+        : completeAutomaticAnalysis(result, finished, shell.analysis?.config, input, {
+            ...(shell.analysis === undefined ? {} : { trigger: shell.analysis.trigger }),
+            preferLargerOutput: shell.analysis?.preferLargerOutput === true,
+            ...(shell.analysisRefusal === undefined ? {} : { refusal: shell.analysisRefusal }),
+        });
     const admission = await shell.admit();
     if (!admission.ok)
         return {

package/dist/run/subject-name.d.ts

@@ -0,0 +1,11 @@
+/** A subject as a run records it: its source and, for a product used at a desktop, the product. */
+interface NamedSubject {
+    readonly source: string;
+    readonly product?: string | undefined;
+}
+/**
+ * The URL a participant opens names the subject. A product used at a desktop has no URL, so it is
+ * named with its source, as in `humanish (desktop-cli)`. Empty when there is neither.
+ */
+export declare function subjectName(url: string, subject: NamedSubject): string;
+export {};

package/dist/run/subject-name.js

@@ -0,0 +1,11 @@
+// The words a reader sees for a run's subject. The `subject:` line of `humanish run`, the run's
+// summary and each participant's sentence name it the same way.
+/**
+ * The URL a participant opens names the subject. A product used at a desktop has no URL, so it is
+ * named with its source, as in `humanish (desktop-cli)`. Empty when there is neither.
+ */
+export function subjectName(url, subject) {
+    if (url !== "" || subject.product === undefined)
+        return url;
+    return `${subject.product} (${subject.source})`;
+}

package/dist/study/automatic-analysis-plan.d.ts

@@ -0,0 +1,28 @@
+import { type AutomaticAnalysisResult } from "../analysis/automatic-completion.js";
+import { type AutomaticAnalysisBudget } from "../analysis/automatic-config.js";
+import type { StudyRoute } from "./routing.js";
+/** The reason a run records for an analysis its study has too many participants for. */
+export declare const PARTICIPANT_LIMIT_SKIP = "AUTOMATIC_ANALYSIS_PARTICIPANT_LIMIT";
+/** The CLI's words for that reason, after "analysis: ". */
+export declare const PARTICIPANT_LIMIT_SKIP_TEXT: string;
+/** The skip a study of `participants` gets, or undefined when its analysis runs. */
+export declare function analysisSkipFor(participants: number): typeof PARTICIPANT_LIMIT_SKIP | undefined;
+/** The analysis budget the plan line shows, and the skip when the analysis will not run. */
+export type StudyAnalysisBudget = AutomaticAnalysisBudget & {
+    readonly skip?: typeof PARTICIPANT_LIMIT_SKIP;
+};
+/**
+ * The budget of a study's automatic analysis after a live run of `participants`, or undefined
+ * when none is planned. A skipped analysis carries no expected cost, since it spends nothing.
+ */
+export declare function studyAnalysisBudget(raw: unknown, route: StudyRoute, participants: number): StudyAnalysisBudget | undefined;
+/** The line `run` and `study check` print about the analysis after a live run. */
+export declare function formatStudyAnalysisBudget(budget: StudyAnalysisBudget): string;
+/** A run's result with its analysis recorded as skipped for its participant count. */
+export declare function withParticipantLimitSkip<T>(result: T, trigger: "default" | "explicit"): T & AutomaticAnalysisResult;
+/**
+ * Whether a run's automatic analysis lets the command exit 0. A participant-count skip of the
+ * analysis a study did not ask for passes, like the default analysis's missing-key skip; a skip of
+ * an explicit request fails, like that request's missing key.
+ */
+export declare function studyAnalysisSucceeded(result: AutomaticAnalysisResult): boolean;

package/dist/study/automatic-analysis-plan.js

@@ -0,0 +1,57 @@
+// What automatic analysis does for a study of N participants. One analysis reads at most
+// EVIDENCE_LIMITS.participants of them (the analysis module owns that number). A study with more
+// runs every participant and records its analysis as skipped for that reason, where the analysis
+// would otherwise cover the first participants and drop the rest. The plan line, the run's
+// analysis record and the CLI's exit code all read the skip from here. Once the analysis covers
+// every participant a study may have, the skip never applies and this module can go.
+import { automaticAnalysisSucceeded, } from "../analysis/automatic-completion.js";
+import { automaticAnalysisBudget, formatAutomaticAnalysisBudget, } from "../analysis/automatic-config.js";
+import { EVIDENCE_LIMITS } from "../analysis/evidence.js";
+/** The reason a run records for an analysis its study has too many participants for. */
+export const PARTICIPANT_LIMIT_SKIP = "AUTOMATIC_ANALYSIS_PARTICIPANT_LIMIT";
+/** The CLI's words for that reason, after "analysis: ". */
+export const PARTICIPANT_LIMIT_SKIP_TEXT = `not run, because the study has more than ${EVIDENCE_LIMITS.participants} participants and automatic analysis reads at most ${EVIDENCE_LIMITS.participants}`;
+/** The skip a study of `participants` gets, or undefined when its analysis runs. */
+export function analysisSkipFor(participants) {
+    return participants > EVIDENCE_LIMITS.participants ? PARTICIPANT_LIMIT_SKIP : undefined;
+}
+/**
+ * The budget of a study's automatic analysis after a live run of `participants`, or undefined
+ * when none is planned. A skipped analysis carries no expected cost, since it spends nothing.
+ */
+export function studyAnalysisBudget(raw, route, participants) {
+    const skip = analysisSkipFor(participants);
+    if (skip === undefined)
+        return automaticAnalysisBudget(raw, route, participants);
+    const budget = automaticAnalysisBudget(raw, route);
+    return budget && { ...budget, participants, skip };
+}
+/** The line `run` and `study check` print about the analysis after a live run. */
+export function formatStudyAnalysisBudget(budget) {
+    if (budget.skip === undefined)
+        return formatAutomaticAnalysisBudget(budget);
+    const next = budget.trigger === "default"
+        ? "Set review.analysis: false to leave it out of this plan."
+        : "The analysis this study asks for will be recorded as skipped and the run will exit 2; set review.analysis: false or run fewer participants.";
+    return `After live runs: automatic analysis will not run. This study has ${budget.participants ?? "more"} participants, and automatic analysis reads at most ${EVIDENCE_LIMITS.participants}. ${next}`;
+}
+/** A run's result with its analysis recorded as skipped for its participant count. */
+export function withParticipantLimitSkip(result, trigger) {
+    return {
+        ...result,
+        ...(trigger === "default" ? { automaticAnalysisTrigger: trigger } : {}),
+        automaticAnalysis: { state: "skipped", reason: PARTICIPANT_LIMIT_SKIP },
+    };
+}
+/**
+ * Whether a run's automatic analysis lets the command exit 0. A participant-count skip of the
+ * analysis a study did not ask for passes, like the default analysis's missing-key skip; a skip of
+ * an explicit request fails, like that request's missing key.
+ */
+export function studyAnalysisSucceeded(result) {
+    const value = result.automaticAnalysis;
+    return (automaticAnalysisSucceeded(result) ||
+        (result.automaticAnalysisTrigger === "default" &&
+            value?.state === "skipped" &&
+            value.reason === PARTICIPANT_LIMIT_SKIP));
+}

package/dist/study/composition-rules.js

@@ -118,7 +118,7 @@ function appUrlValidationReason(config) {
                 return `actor.type must be a registered computer-use actor for app-url × e2b-desktop studies (one of: ${registeredComputerUseActors().join(", ")}); for local scripted execution use a registered scripted-browser actor (${registeredScriptedBrowserActors().join(", ")}). Got "${type}".`;
             }
             // Multi-participant fan-out is consumed on this route (`per-lane-worlds`; the shared cua
-            // cross-validation below enforces the 16 cap, the per-participant target gates, and the
+            // cross-validation below enforces the participant bound, the per-participant target gates, and the
             // allowPublicTargets+N>1 rejection for ambiguous one-target fan-out).
             // Loopback by default; an owner may declare a public/preview target via policies.
             const targets = [config.subject.appUrl ?? "", ...declaredTargets(config)];

package/dist/study/config.js

@@ -18,14 +18,14 @@
 // The terminal route consumes subject.product, `caps` and execution.{terminal,runtimeAuth}.
 //
 // NOTE on `participants`: a count (preview: the simulated count; computer use: N identical
-// participants, each its own desktop, capped at 16), `{ count, instruction }` (identical
+// participants, each its own desktop, at most 100), `{ count, instruction }` (identical
 // participants with one steer), or a list of `{ id?, persona?, device?, instruction?, target? ... }`
 // entries, each its own desktop. A list entry with a `count` is a group that expands into
 // `<id>-01` to `<id>-NN`. A shared world takes a list of at least two. `participants[].device`
 // excludes a raw `execution.desktop.resolution`, and `participants[].target` is app-url computer
 // use only: an absolute browser URL this participant opens in place of `subject.appUrl`.
-// `execution.concurrency` bounds in-flight participants (default: all at once; env
-// HUMANISH_CUA_MAX_CONCURRENCY may only lower it).
+// `execution.concurrency` bounds in-flight participants (default: all at once, up to the E2B
+// plan's concurrent sandboxes; env HUMANISH_CUA_MAX_CONCURRENCY may only lower it).
 import { isLocalBrowserStudy, localBrowserDefaults, localBrowserUnsupportedReason, } from "../substrates/local/runtime-config.js";
 import { isRecord } from "../run/type-guards.js";
 import { compositionReason } from "./composition-rules.js";
@@ -36,11 +36,10 @@ import { parseCaps, parseDefaults, parseExecution, parsePolicies, parseReview, }
 import { ACTOR_REQUIRED, readStudyFront, routeNameReason, } from "./parse/front.js";
 import { parseSubject } from "./parse/subject.js";
 import { invalid, optionalStr, str } from "./parse/values.js";
-import { isComputerUseComposition, isSharedWorldComposition, routeOf } from "./routing.js";
+import { isComputerUseComposition, routeOf } from "./routing.js";
 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";
 /**
@@ -216,7 +215,8 @@ function parseParticipants(raw, read) {
 }
 /**
  * The checks that read more than one section of a parsed config, and the defaults they fill:
- * shared-world `execution.concurrency`, `comms.email.recipients` and the local browser's defaults.
+ * `comms.email.recipients` and the local browser's defaults. An omitted `execution.concurrency`
+ * stays unset: the planner resolves it from the participants and the E2B plan's limit.
  */
 function checkStudyConfig(config) {
     const smtpReason = smtpValidationReason(config);
@@ -228,20 +228,9 @@ function checkStudyConfig(config) {
     const outputLimitReason = outputTokenLimitValidationReason(config);
     if (outputLimitReason)
         return invalid(outputLimitReason);
-    // 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
-    // when they plan, after any --count override, so the parser leaves it unset for them. A shared
-    // world's roster is fixed, so its default is filled here for the envelopes and warnings that read
-    // the parsed config.
-    {
-        const participantCount = participantList(config)?.length ?? declaredParticipantCount(config) ?? 1;
-        if (participantCount > 1 &&
-            config.execution?.concurrency === undefined &&
-            isSharedWorldComposition(config)) {
-            config.execution = { ...config.execution, concurrency: participantCount };
-        }
-    }
+    const waitLimitReason = waitLimitValidationReason(config);
+    if (waitLimitReason)
+        return invalid(waitLimitReason);
     // Email that just works: the funnel's only handoff to an actor is the per-participant
     // inbox instruction, gated on recipients[]. Guessed participant ids broke a field run:
     // recipients copied from a single-participant example matched nothing, so every actor was left inbox-blind with zero

package/dist/study/doctor.js

@@ -5,7 +5,8 @@ import { capacityShortfall, describeCapacity, } from "../substrates/local/capaci
 import { keyNamesOf, requiredKeys, requiredSubjectEnv } from "./requirements.js";
 import { localAgentReady, localAgentVersionRefusal, } from "../actors/local-agent/cli.js";
 import { protocolAdditionsWarning, protocolIncompatibilityMessage, } from "../actors/codex/protocol-compat.js";
-import { automaticAnalysisBudget } from "../analysis/automatic-config.js";
+import { admissionRule } from "../analysis/admission.js";
+import { studyAnalysisBudget } from "./automatic-analysis-plan.js";
 import { externalCatchHealthy } from "../comms/sandbox-catch.js";
 import { receivingRequiredKey } from "../comms/setup.js";
 import { classifyCodexInstallation, codexInstallAdvice, codexVersionRecovery, } from "../actors/codex/codex-admission.js";
@@ -190,7 +191,11 @@ export async function studySetupChecks(args) {
     if (route === "scripted")
         checks.push(await scriptedBrowserCheck());
     checks.push(...subjectEnvChecks(requiredSubjectEnv(requirements), args));
-    const analysis = automaticAnalysisBudget(config.review?.analysis, route);
+    const analysis = studyAnalysisBudget(config.review?.analysis, route, plan.route === "computer-use"
+        ? plan.runner.participants.length
+        : plan.route === "shared-world"
+            ? plan.plane.participants.length
+            : 1);
     if (analysis)
         checks.push(await analysisCheck(analysis, args, checkAccount));
     checks.push(checkScope(analysis));
@@ -347,6 +352,15 @@ function subjectEnvChecks(names, args) {
 }
 /** The post-run analysis: the Codex account, or the OpenAI key and the analysis cost limit. */
 async function analysisCheck(analysis, args, checkAccount) {
+    if (analysis.skip !== undefined) {
+        const explicit = analysis.trigger === "explicit";
+        return {
+            name: "post-run analysis",
+            ok: !explicit,
+            ...(explicit ? {} : { status: "note" }),
+            message: `Will not run: this study has ${analysis.participants ?? "more"} participants, more than automatic analysis reads. The participants still run.${explicit ? " review.analysis asks for it, so the run will exit 2; set review.analysis: false or run fewer participants." : ""}`,
+        };
+    }
     if (analysis.provider === "codex") {
         const readiness = await checkAccount();
         const recovery = readiness.errorCode === "codex_unsupported_platform"
@@ -368,7 +382,7 @@ async function analysisCheck(analysis, args, checkAccount) {
         ok: true,
         ...(keyed ? {} : { status: "note" }),
         message: keyed
-            ? `OPENAI_API_KEY is present for the separate automatic analysis request; model access and quota are not tested. The analysis is refused before it starts if its expected cost plus a 10% margin is over $${analysis.maxCostUsd}; this is not a billing cap. Participant readiness is independent.`
+            ? `OPENAI_API_KEY is present for the separate automatic analysis request; model access and quota are not tested. The analysis is refused before it starts if ${admissionRule(`$${analysis.maxCostUsd}`)}; this is not a billing cap. Participant readiness is independent.`
             : "Will be skipped: OPENAI_API_KEY is missing. The participant may run, but there will be no automatic findings report. Add an OpenAI API key or set review.analysis: false deliberately.",
     };
 }

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

@@ -28,7 +28,7 @@ export interface ParticipantPaths {
  * instruction?, target?, entry?, host?, reasoningEffort?, stopWhen?, dwell? }`.
  * Participant ids (when declared) must be public-safe path tokens and unique; grouping metadata
  * must be public-safe tokens; a device must be a known preset name. The
- * route-scoped cross-validation (device XOR raw resolution, targets, cap 16) runs in parseStudy
+ * route-scoped cross-validation (device XOR raw resolution, targets, the participant bound) runs in parseStudy
  * where the route is known.
  */
 export declare function parseParticipantEntries(raw: unknown, paths: ParticipantPaths): {

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") {
@@ -91,7 +99,7 @@ export function parseActorFields(entry, path) {
  * instruction?, target?, entry?, host?, reasoningEffort?, stopWhen?, dwell? }`.
  * Participant ids (when declared) must be public-safe path tokens and unique; grouping metadata
  * must be public-safe tokens; a device must be a known preset name. The
- * route-scoped cross-validation (device XOR raw resolution, targets, cap 16) runs in parseStudy
+ * route-scoped cross-validation (device XOR raw resolution, targets, the participant bound) runs in parseStudy
  * where the route is known.
  */
 export function parseParticipantEntries(raw, paths) {

package/dist/study/parse/front.d.ts

@@ -1,4 +1,4 @@
-import type { StudyRoute } from "../routing.js";
+import { type StudyRoute } from "../routing.js";
 import type { StudyParseFailure, StudySurfaces } from "../types.js";
 /** A document's `participants`, read before the participant entries parse. */
 export interface Participants {

package/dist/study/parse/front.js

@@ -4,6 +4,7 @@
 import { isRecord } from "../../run/type-guards.js";
 import { findUnknownStudyKey } from "../keys.js";
 import { movedV2KeyReason } from "../migrate/v2.js";
+import { participantCountReason } from "../routing.js";
 import { PARTICIPANT_ID_MAX_CHARS, PARTICIPANT_ID_PATTERN } from "./actors.js";
 import { invalid, posInt } from "./values.js";
 // The values `route:` takes: every route routeOf can return.
@@ -131,8 +132,13 @@ function homogeneousOf(raw) {
     return { ok: true, value: participants };
 }
 // A list entry with `count: n` is a group: n participants `<id>-01` to `<id>-NN`, even when n is 1.
-// config.ts then checks every entry and the expanded ids for collisions.
+// config.ts then checks every entry and the expanded ids for collisions. The roster's size is
+// checked before any group expands, so a large count is refused without building it.
 function entriesOf(raw) {
+    const size = raw.reduce((sum, entry) => sum + (isRecord(entry) && typeof entry.count === "number" ? (posInt(entry.count) ?? 1) : 1), 0);
+    const sizeReason = participantCountReason(size);
+    if (sizeReason)
+        return invalid(sizeReason);
     const entries = [];
     const source = [];
     for (const [index, entry] of raw.entries()) {

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

@@ -25,4 +25,6 @@ export declare function planBase(config: StudyConfig, input: {
         readonly config?: PlannedAnalysis["config"] | undefined;
         readonly preferLargerOutput?: boolean | undefined;
     };
+    /** How many participants the run has, which decides whether its analysis can run. */
+    readonly participants?: number;
 }): Base;

package/dist/study/plan-base.js

@@ -1,6 +1,7 @@
 // What every route planner shares: the plan fields common to all routes, the frozen residual config,
 // and the requirement and subject helpers.
 import { DEFAULT_OPENAI_CU_MODEL } from "../actors/computer-use/openai-provider.js";
+import { analysisSkipFor } from "./automatic-analysis-plan.js";
 // A YAML alias can make a parsed record contain itself (an inline persona that names its own
 // anchor), and structuredClone keeps the cycle, so each object is frozen once.
 function deepFreeze(value, frozen = new WeakSet()) {
@@ -108,6 +109,7 @@ export function pricedModel(brain) {
 /** The fields every plan shares, from a config whose analysis already resolved. */
 export function planBase(config, input) {
     const analysis = input.analysis?.config;
+    const skip = analysisSkipFor(input.participants ?? 1);
     return {
         studyId: config.id,
         ...(config.title === undefined ? {} : { title: config.title }),
@@ -120,6 +122,7 @@ export function planBase(config, input) {
                     config: analysis,
                     trigger: config.review?.analysis === undefined ? "default" : "explicit",
                     preferLargerOutput: input.analysis?.preferLargerOutput === true,
+                    ...(skip === undefined ? {} : { skip }),
                 },
             }),
         requirements: [],

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. */