humanish 0.117.0 → 0.118.0

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,9 +36,8 @@ 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, waitLimitValidationReason, } from "./validation.js";
 import { forwardDeclaredWarnings, inertFieldLabels, inertFieldPaths } from "./warnings.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);
@@ -231,20 +231,6 @@ function checkStudyConfig(config) {
     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
-    // 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 };
-        }
-    }
     // 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/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

@@ -99,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.js

@@ -1,7 +1,7 @@
 // Who takes part in a study: one record per participant, built from the declared roster or a count.
 // Computer-use and shared-world participants share the desktop fields; each kind adds its own.
 import { resolveParticipantDevice } from "./device-presets.js";
-import { isSharedWorldComposition, participantIdAt } from "./routing.js";
+import { computerUseParticipantCount, isSharedWorldComposition, participantIdAt, } from "./routing.js";
 import { participantList, declaredParticipantCount, participantInstruction, } from "./study-fields.js";
 function desktopParticipant(config, entry, index, kind, focus) {
     const actor = config.actor;
@@ -45,10 +45,7 @@ function desktopParticipant(config, entry, index, kind, focus) {
 export function computerUseParticipants(config, countOverride) {
     const actor = config.actor;
     const roster = participantList(config);
-    const count = roster
-        ? roster.length
-        : Math.max(1, countOverride ?? declaredParticipantCount(config) ?? 1);
-    return Array.from({ length: count }, (_, index) => {
+    return Array.from({ length: computerUseParticipantCount(config, countOverride) }, (_, index) => {
         const entry = roster?.[index];
         const focus = roster ? entry?.instruction : participantInstruction(config);
         return {

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

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

package/dist/study/plan.d.ts

@@ -7,9 +7,9 @@ export { routeOf, type StudyRoute } from "./routing.js";
 export declare function resolveStudyDryRun(config: StudyConfig, override: boolean | undefined, fallback: boolean | undefined): boolean | undefined;
 /**
  * The plan a study runs under, built without reading files or the network. From the environment
- * (options.env, else process.env, as the routes read it) it reads one value, the E2B sandbox
- * ceiling, which no study file can know. Each route's planner makes every refusal that route
- * makes, in the route's order and with its codes and messages; the route's exported runner calls
- * the same planner.
+ * (options.env, else process.env, as the routes read it) it reads the operator's E2B plan limits,
+ * the sandbox ceiling and the concurrent sandboxes, which no study file can know. Each route's
+ * planner makes every refusal that route makes, in the route's order and with its codes and
+ * messages; the route's exported runner calls the same planner.
  */
 export declare function planStudy(config: StudyConfig, options: InternalRunStudyOptions, deps?: StudyDeps): PlanResult;

package/dist/study/plan.js

@@ -6,7 +6,7 @@ import { callerDrivingOf, planComputerUseStudy } from "../routes/computer-use/pl
 import { injectedBrowser, planScriptedStudy } from "../routes/scripted/plan.js";
 import { planSharedWorldStudy } from "../routes/shared-world/plan.js";
 import { planTerminalStudy } from "../routes/terminal/plan.js";
-import { sandboxCeiling } from "../substrates/e2b/lifetime.js";
+import { concurrentSandboxes, sandboxCeiling, } from "../substrates/e2b/lifetime.js";
 import { localBrowserDefaults } from "../substrates/local/runtime-config.js";
 import { THIS_REPO_DRY_RUN_ONLY } from "./composition-rules.js";
 import { planBase } from "./plan-base.js";
@@ -65,21 +65,25 @@ function planPreview(config, options, input) {
 }
 /**
  * The plan a study runs under, built without reading files or the network. From the environment
- * (options.env, else process.env, as the routes read it) it reads one value, the E2B sandbox
- * ceiling, which no study file can know. Each route's planner makes every refusal that route
- * makes, in the route's order and with its codes and messages; the route's exported runner calls
- * the same planner.
+ * (options.env, else process.env, as the routes read it) it reads the operator's E2B plan limits,
+ * the sandbox ceiling and the concurrent sandboxes, which no study file can know. Each route's
+ * planner makes every refusal that route makes, in the route's order and with its codes and
+ * messages; the route's exported runner calls the same planner.
  */
 export function planStudy(config, options, deps = {}) {
     const study = localBrowserDefaults(config);
     const input = { dryRun: resolveStudyDryRun(study, options.dryRun, true) ?? true };
-    const ceiling = sandboxCeiling(options.env ?? process.env);
-    const result = planRoute(routeOf(config), study, options, input, deps, ceiling);
+    const env = options.env ?? process.env;
+    const e2b = {
+        sandboxCeiling: sandboxCeiling(env),
+        concurrentSandboxes: concurrentSandboxes(env),
+    };
+    const result = planRoute(routeOf(config), study, options, input, deps, e2b);
     if (!result.ok)
         return result;
     // The manifest the CLI resolved enters the plan here and nowhere else; the routes read
     // plan.study for the run's status record and bundle, and plan.warnings for its bundle events.
-    const warnings = recordedStudyWarnings(study);
+    const warnings = [...recordedStudyWarnings(study), ...(result.plan.warnings ?? [])];
     const plan = {
         ...result.plan,
         ...(options.study === undefined ? {} : { study: options.study }),
@@ -87,7 +91,8 @@ export function planStudy(config, options, deps = {}) {
     };
     return { ok: true, planned: { plan } };
 }
-function planRoute(route, study, options, input, deps, sandboxCeiling) {
+function planRoute(route, study, options, input, deps, e2b) {
+    const { sandboxCeiling } = e2b;
     switch (route) {
         case "preview":
             return planPreview(study, options, input);
@@ -98,13 +103,13 @@ function planRoute(route, study, options, input, deps, sandboxCeiling) {
                 driving: callerDrivingOf(options),
                 ...(options.count === undefined ? {} : { countOverride: options.count }),
                 ...(options.rerun === undefined ? {} : { rerun: options.rerun }),
-                sandboxCeiling,
+                ...e2b,
             });
         case "shared-world":
             return planSharedWorldStudy(study, {
                 ...input,
                 hasRunSession: deps.runSession !== undefined,
-                sandboxCeiling,
+                ...e2b,
             });
         case "terminal":
             return planTerminalStudy(study, {
@@ -113,6 +118,10 @@ function planRoute(route, study, options, input, deps, sandboxCeiling) {
                 sandboxCeiling,
             });
         case "scripted":
-            return planScriptedStudy(study, { ...input, injectedBrowser: injectedBrowser(deps) });
+            return planScriptedStudy(study, {
+                ...input,
+                injectedBrowser: injectedBrowser(deps),
+                sandboxCeiling,
+            });
     }
 }

package/dist/study/preflight-result.js

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

package/dist/study/preflight.d.ts

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

package/dist/study/preflight.js

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

package/dist/study/routing.d.ts

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

package/dist/study/routing.js

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

package/dist/study/summary.d.ts

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

package/dist/study/summary.js

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

package/dist/study/validation.d.ts

@@ -2,8 +2,8 @@ import type { StudyConfig } from "./types.js";
 /**
  * Cross-validate the computer-use fan-out declaration (`per-lane-worlds`). Returns the failure
  * message, or null when valid. The parser enforces it, and runStudyWith checks it again for a config
- * that skipped the parser. It runs rosterStructuralValidationReason (id and device
- * validity, unique ids) first, then the route-scoped XOR, cap and policy checks.
+ * that skipped the parser. It runs rosterStructuralValidationReason (roster size, id and device
+ * validity, unique ids) first, then the route-scoped XOR, participant count and policy checks.
  */
 export declare function computerUseValidationReason(config: StudyConfig): string | null;
 /**