humanish 0.117.0 → 0.118.0

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

package/dist/routes/scripted/plan.js

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

package/dist/routes/scripted/setup.js

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

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

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

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

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

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

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

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

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

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/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;