humanish 0.117.0 → 0.119.0

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

@@ -7,6 +7,7 @@ import { declaredScreenForRender } from "../../substrates/e2b/desktop-geometry.j
 import { publicSafeRouteLabel } from "./provenance.js";
 import { participantCaption } from "../../run/participant-caption.js";
 import { participantSummary } from "../../run/outcomes.js";
+import { arrivalRecord } from "../../study/arrivals.js";
 function participantView(ctx, spec, index) {
     const { args, external } = ctx;
     const name = participantCaption({ id: spec.planned.id, personaId: spec.persona.id });
@@ -69,8 +70,21 @@ function sharedWorldSimulation(ctx, spec, index, view) {
         summary: participantSummary(name, { name: "the shared app" }, { trace: session?.trace, sessionError: outcome?.sessionError, inProgress }),
         startedAt: args.run.createdAt,
         updatedAt: args.run.createdAt,
+        ...(args.plan.arrivals.declared
+            ? {
+                arrival: arrivalRecord(spec.planned.startAfterMs, actorArrival(args.actorResults[index])),
+            }
+            : {}),
     });
 }
+// A follower the handoff stopped before it opened the app never started its desktop.
+function actorArrival(result) {
+    if (result === undefined)
+        return undefined;
+    return result.outcome.skippedReason === undefined
+        ? { scheduledAt: result.scheduledAt, startedAt: result.startedAt }
+        : { scheduledAt: result.scheduledAt };
+}
 function sharedWorldStream(ctx, spec, index, view) {
     const { args } = ctx;
     const { name, session, screenshots, lastScreenshot, desktopGeometry, screenshotMode } = view;

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

@@ -18,6 +18,7 @@ import { sharedWorldParticipantRecords } from "./bundle-records.js";
 import { CONCURRENT_ATTRIBUTION_LIMITS, EXTERNAL_PUBLIC_ATTRIBUTION_LIMITS, } from "./types.js";
 import { gapsListClause } from "../../run/outcomes.js";
 import { plural } from "../../run/text.js";
+import { describeArrivals } from "../../study/arrivals.js";
 /** Max windows live at the same instant (sweep over start/end points). The simultaneity
  *  count: the participant count says how many existed; this says how many ever ran at once. */
 export function maxSimultaneousWindows(windows) {
@@ -107,7 +108,7 @@ function planeEvents(args, external) {
         at: createdAt,
         level: "info",
         type: "concurrent-shared-world.run.created",
-        message: `Created a concurrent shared-world run for ${plan.studyId} (actor ${descriptor.id}, ${plural(actorSpecs.length, "persona")} on one shared app, at most ${plan.concurrency} at once).`,
+        message: `Created a concurrent shared-world run for ${plan.studyId} (actor ${descriptor.id}, ${plural(actorSpecs.length, "persona")} on one shared app, at most ${plan.concurrency} at once).${plan.arrivals.declared ? ` Schedule: ${describeArrivals(plan.arrivals)}` : ""}`,
     });
     // Human-readable plane label, byte-stable for the clone route. local-tree has no repo slug: it
     // labels the packed archive instead (archiveSha256 + dirty/clean when the packed root was a git

package/dist/routes/shared-world/external-public.js

@@ -6,7 +6,7 @@
 // deadline.
 import { liveObserverResult } from "../../observer/live.js";
 import { redactText, toErrorMessage } from "../../evidence/redaction.js";
-import { mapWithConcurrency } from "../../run/concurrency.js";
+import { runOnSchedule } from "../../study/arrivals.js";
 import { buildConcurrentSharedWorldBundle, judgeSharedWorldRun } from "./bundle.js";
 import { drainExternalComms } from "./comms.js";
 import { LobbyHandoff, runFollower, runHost } from "./handoff.js";
@@ -95,10 +95,22 @@ export async function runExternalPublicPlane(ctx, live, inbox) {
         .filter(({ index }) => index !== hostIndex);
     const orderedResults = new Array(actorSpecs.length);
     try {
+        // The host starts with the run (parse refuses a later start for it); the followers start on
+        // the study's schedule.
         const hostPromise = hostIndex >= 0 && actorSpecs[hostIndex] !== undefined
-            ? runHost(handoff, deps, actorSpecs[hostIndex], hostIndex)
+            ? runHost(handoff, deps, actorSpecs[hostIndex], hostIndex).then((result) => ({
+                ...result,
+                scheduledAt: result.startedAt,
+            }))
             : undefined;
-        const followerResultsPromise = mapWithConcurrency(followerEntries, Math.max(1, concurrency - 1), ({ spec, index }) => runFollower(handoff, deps, spec, index));
+        const followerResultsPromise = runOnSchedule(followerEntries, {
+            startAfterMs: ({ spec }) => spec.planned.startAfterMs,
+            slots: Math.max(1, concurrency - 1),
+            now: ctx.now,
+        }, async ({ spec, index }, _position, { scheduledAt }) => ({
+            ...(await runFollower(handoff, deps, spec, index)),
+            scheduledAt,
+        }));
         const [hostResult, followerResults] = await Promise.all([hostPromise, followerResultsPromise]);
         if (hostResult !== undefined && hostIndex >= 0) {
             orderedResults[hostIndex] = hostResult;

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

@@ -59,5 +59,5 @@ export declare class LobbyHandoff {
         lobbyConvergenceDigest: string | undefined;
     };
 }
-export declare function runHost(handoff: LobbyHandoff, deps: HandoffParticipantDeps, spec: DesktopParticipantRun, participantIndex: number): Promise<ActorRunResult>;
-export declare function runFollower(handoff: LobbyHandoff, deps: HandoffParticipantDeps, spec: DesktopParticipantRun, participantIndex: number): Promise<ActorRunResult>;
+export declare function runHost(handoff: LobbyHandoff, deps: HandoffParticipantDeps, spec: DesktopParticipantRun, participantIndex: number): Promise<Omit<ActorRunResult, "scheduledAt">>;
+export declare function runFollower(handoff: LobbyHandoff, deps: HandoffParticipantDeps, spec: DesktopParticipantRun, participantIndex: number): Promise<Omit<ActorRunResult, "scheduledAt">>;

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,15 @@ 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 schedule lines a shared-world run prints before it creates anything, when the study declares
+ * `participants[].startAfterMs`: the schedule, and the worst case in sandbox-minutes, which counts
+ * every participant's sandbox (its session plus the teardown buffer) and on the provisioned plane
+ * the app's sandbox until the last participant ends.
+ */
+export declare function sharedWorldScheduleLines(plan: SharedWorldPlan): string;
 /** 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,9 @@ 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";
+import { describeArrivals, planStarts, servedScheduleRefusal, } from "../../study/arrivals.js";
 /** The registered descriptor for a planned actor; planSharedWorldStudy checked the registry. */
 export function sharedWorldDescriptorOf(actorType) {
     const descriptor = actorRegistry[actorType];
@@ -96,22 +97,32 @@ export function planSharedWorldStudy(config, input) {
     const plane = planeOf(config);
     if (plane === undefined)
         throw new Error("shared-world validation admitted a plane it cannot plan");
+    const sessionTimeoutMs = config.execution?.timeoutMs ?? defaultSessionTimeoutMs(plane, ceiling.ms);
+    const starts = startsOf(plane, config.execution?.concurrency, input.concurrentSandboxes, sessionTimeoutMs);
+    if (!starts.ok)
+        return refuse(invalid, starts.message, actor);
+    const { arrivals, warnings } = starts;
+    const deadlineReason = deadlineReasonOf(plane, arrivals, {
+        sessionDeclared: config.execution?.timeoutMs !== undefined,
+        ceilingMs: 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,
-    });
+    const base = planBase(config, { dryRun: input.dryRun, analysis });
     return {
         ok: true,
         plan: {
             ...base,
+            ...(warnings.length === 0 ? {} : { warnings }),
             route: "shared-world",
             actor,
             plane,
-            concurrency: config.execution?.concurrency ?? plane.participants.length,
-            sessionTimeoutMs: config.execution?.timeoutMs ?? defaultSessionTimeoutMs(plane, ceiling.ms),
+            concurrency: starts.count,
+            arrivals,
+            sessionTimeoutMs,
             brain,
             caps: planCaps(config),
             requirements: base.dryRun
@@ -132,6 +143,72 @@ export function planSharedWorldStudy(config, input) {
         },
     };
 }
+/**
+ * How many participants run at once, and when each one starts. Every participant's desktop and, on
+ * the provisioned plane, the app's own sandbox share the E2B plan's concurrent sandboxes, and a
+ * shared world needs two participants live together. On the external-public plane the host runs
+ * on a slot of its own and the others queue for the rest (external-public.ts).
+ */
+function startsOf(plane, declared, limit, sessionMs) {
+    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,
+    }, limit);
+    if (!atOnce.ok)
+        return atOnce;
+    const hostIndex = plane.participants.findIndex((participant) => participant.host === true);
+    const queue = {
+        slots: atOnce.count,
+        sessionMs,
+        ...(plane.kind === "external-public" && hostIndex >= 0 ? { ownSlot: hostIndex } : {}),
+    };
+    return {
+        ok: true,
+        count: atOnce.count,
+        ...planStarts(plane.participants, queue, atOnce.lowered),
+    };
+}
+/**
+ * Why the run's longest-lived sandbox cannot live as long as the plan needs. On the provisioned
+ * plane that is the subject sandbox, which serves the app for one session and then until the last
+ * participant ends; on the external-public plane, each participant's own sandbox, created at its
+ * start.
+ */
+function deadlineReasonOf(plane, arrivals, options) {
+    const { sessionDeclared, ceilingMs } = options;
+    const sessionMs = arrivals.sessionMs;
+    if (plane.kind !== "provisioned")
+        return sandboxDeadlineRefusal({ name: "each participant's sandbox", sessionMs, sessionDeclared }, ceilingMs);
+    const seed = plane.subject.state.seed ?? [];
+    return (sandboxDeadlineRefusal({
+        name: "the subject sandbox, which serves the app until every participant ends",
+        sessionMs,
+        sessionDeclared,
+        servedSubject: { seed },
+    }, ceilingMs) ?? servedScheduleRefusal(arrivals, { sessionMs, seed }, ceilingMs));
+}
+/**
+ * The schedule lines a shared-world run prints before it creates anything, when the study declares
+ * `participants[].startAfterMs`: the schedule, and the worst case in sandbox-minutes, which counts
+ * every participant's sandbox (its session plus the teardown buffer) and on the provisioned plane
+ * the app's sandbox until the last participant ends.
+ */
+export function sharedWorldScheduleLines(plan) {
+    const participants = plan.plane.participants.length;
+    const participantMs = participants * (plan.sessionTimeoutMs + sandboxHeadroomMs());
+    const subjectMs = plan.plane.kind === "provisioned"
+        ? plan.arrivals.lastEndMs + sandboxHeadroomMs({ seed: plan.plane.subject.state.seed ?? [] })
+        : 0;
+    return [
+        `humanish shared-world plan (${plan.studyId}): ${participants} participants, at most ${plan.concurrency} at once; worst-case ~${Math.round((participantMs + subjectMs) / 60_000)} sandbox-minutes total${plan.dryRun ? " (dry-run: $0)" : ""}.`,
+        `  schedule: ${describeArrivals(plan.arrivals)}`,
+        "",
+    ].join("\n");
+}
 // The default per-participant session budget is derived from the plane. On a provisioned plane the
 // binding constraint is the subject sandbox (it must outlive every participant: timeoutMs +
 // provisioning + seeding + teardown buffer, under the sandbox ceiling), so the derivation hands each
@@ -145,8 +222,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/provisioned.js

@@ -6,7 +6,7 @@ import { buildOriginMap } from "../../comms/capture-surface.js";
 import { deployCommsCatch, refreshInboxSurface, writeInboxSurface, } from "../../comms/sandbox-catch.js";
 import { redactText, toErrorMessage } from "../../evidence/redaction.js";
 import { liveObserverResult } from "../../observer/live.js";
-import { mapWithConcurrency } from "../../run/concurrency.js";
+import { runOnSchedule } from "../../study/arrivals.js";
 import { provisionCloneSubject } from "../../subject/clone.js";
 import { provisionLocalTreeSubject } from "../../subject/local-tree.js";
 import { defaultSharedWorldPhaseSink } from "../../subject/steps.js";
@@ -96,7 +96,7 @@ class SubjectPlane {
         this.setup.stateSnapshots.push({ timestamp, digest: snapshot.digest });
     }
     async acquire() {
-        const { plan, deps, env, requestTimeoutMs, timeoutMs } = this.ctx;
+        const { plan, deps, env, requestTimeoutMs } = this.ctx;
         const { subjectEnvNames, commsEnv } = this.setup;
         const subjectModule = await (deps.desktopModule ?? loadE2BDesktopModule)();
         // The one subject sandbox: headless service host (no GUI participant). The subject env is
@@ -107,7 +107,9 @@ class SubjectPlane {
             module: subjectModule,
             apiKey: this.ctx.e2bApiKey,
             requestTimeoutMs,
-            sessionTimeoutMs: timeoutMs,
+            // The app serves until the last participant ends, which a late start or a wait for a free
+            // slot puts past one session.
+            sessionTimeoutMs: plan.arrivals.lastEndMs,
             seed: planeStateOf(plan)?.seed ?? [],
             metadata: {
                 ...CONCURRENT_SHARED_WORLD_PROVIDER_METADATA,
@@ -380,15 +382,20 @@ async function publishInProgress(plane, ctx, live, setup) {
     }
     startParticipantFlush(ctx, live, inProgressBundle);
 }
-// Launch N actor sandboxes concurrently and independently (runCuaParticipant + mapWithConcurrency;
-// runCuaParticipants would add a pipeline gate and fail-fast). Each actor's window is measured on the
-// one orchestrator clock.
+// Launch N actor sandboxes independently on the study's schedule (runCuaParticipant +
+// runOnSchedule; runCuaParticipants would add a pipeline gate and fail-fast). Each actor's window is
+// measured on the one orchestrator clock.
 function runParticipants(plane, ctx, live, setup) {
     const { now } = ctx;
     const participants = ctx.plan.plane.participants;
     const { commsEmail } = setup;
     const baseActorDeps = participantRunDeps(ctx, live, ctx.scrubKnownValues);
-    return mapWithConcurrency(ctx.actorSpecs, Math.max(1, ctx.concurrency), async (spec, i) => {
+    const schedule = {
+        startAfterMs: (spec) => spec.planned.startAfterMs,
+        slots: Math.max(1, ctx.concurrency),
+        now,
+    };
+    return runOnSchedule(ctx.actorSpecs, schedule, async (spec, i, { scheduledAt }) => {
         const route = resolveActorEntryUrl(plane.getHostUrl, participants[i]?.entry);
         // Tell this persona its (getHost-reachable) inbox URL, but only when comms is live and this participant
         // has a declared recipient it can actually receive mail into (else it would stall on an empty
@@ -400,7 +407,7 @@ function runParticipants(plane, ctx, live, setup) {
         const startedAt = now();
         const outcome = await runCuaParticipant(actorSpec, { ...baseActorDeps, appUrl: route });
         const endedAt = now();
-        return { spec, outcome, startedAt, endedAt, route };
+        return { spec, outcome, scheduledAt, startedAt, endedAt, route };
     });
 }
 export async function runProvisionedPlane(ctx, live, setup) {

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

@@ -23,7 +23,7 @@
 // per-delta→actor field, so causation under concurrency is structurally inexpressible.
 //
 // Capability and proof: the deterministic $0 gate proves the plumbing + the claims-match-mechanism
-// contract: the real mapWithConcurrency produces genuinely overlapping laneWindows (a rendezvous
+// contract: the real start queue (runOnSchedule) produces genuinely overlapping laneWindows (a rendezvous
 // latch in the fake session forces two participant fns in-flight while the real orchestrator clock
 // measures the windows). Every generated bundle describes only its own observations; no one run
 // establishes scale, repeatability, or adopter-harness replacement.
@@ -38,7 +38,7 @@ import {} from "../../run/run.js";
 import { RunSecrets } from "../../run/secrets.js";
 import { admitRoute, completeRefusalAnalysis, } from "../../run/route-shell.js";
 import { runExternalPublicPlane } from "./external-public.js";
-import { sharedWorldDescriptorOf } from "./plan.js";
+import { sharedWorldDescriptorOf, sharedWorldScheduleLines, } from "./plan.js";
 import { runProvisionedPlane } from "./provisioned.js";
 import { concurrentStudyFailure, finishConcurrentRun } from "./result.js";
 import { prepareConcurrentRun } from "./setup.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,
@@ -143,6 +143,9 @@ async function runPlanInScope(plan, input, config, scope) {
     const deps = input.deps ?? {};
     const env = input.env ?? process.env;
     const fail = sharedWorldFailure(plan, input);
+    // Before any sandbox or provider call, as computer use prints its participant plan.
+    if (plan.arrivals.declared)
+        process.stderr.write(sharedWorldScheduleLines(plan));
     const descriptor = sharedWorldDescriptorOf(plan.actor);
     const planeClass = plan.plane.kind === "external-public" ? "external-public" : "provisioned-getHost";
     // The provisioned plane's subject; the external-public plane has none.

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

@@ -138,6 +138,8 @@ export interface ConcurrentSharedWorldStudyResult extends AutomaticAnalysisResul
 export interface ActorRunResult {
     spec: DesktopParticipantRun;
     outcome: ParticipantRunOutcome;
+    /** When the schedule had it start, in epoch ms; the host of an external public app starts with the run. */
+    scheduledAt: number;
     startedAt: number;
     endedAt: number;
     route: string;

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;
@@ -312,7 +313,16 @@ function isRunSimulation(value) {
         Array.isArray(value.streamIds) &&
         value.streamIds.every((streamId) => typeof streamId === "string") &&
         typeof value.startedAt === "string" &&
-        typeof value.updatedAt === "string");
+        typeof value.updatedAt === "string" &&
+        (value.arrival === undefined || isRunParticipantArrival(value.arrival)));
+}
+function isRunParticipantArrival(value) {
+    return (isRecord(value) &&
+        typeof value.startAfterMs === "number" &&
+        Number.isSafeInteger(value.startAfterMs) &&
+        value.startAfterMs >= 0 &&
+        (value.scheduledAt === undefined || typeof value.scheduledAt === "string") &&
+        (value.startedAt === undefined || typeof value.startedAt === "string"));
 }
 function isRunAdapterArtifact(value) {
     return (isRecord(value) &&

package/dist/run/bundle.d.ts

@@ -123,6 +123,21 @@ export interface RunSimulation {
     streamIds: string[];
     startedAt: string;
     updatedAt: string;
+    /**
+     * When a computer-use or shared-world participant was due and when it started, in a study that
+     * declares `participants[].startAfterMs`. `startAfterMs` is its offset (0 when its entry declares
+     * none), `scheduledAt` the moment the run started its participants plus that offset, and
+     * `startedAt` when its desktop was requested: later than `scheduledAt` when it waited for a free
+     * slot. A dry run records only the offset, and a participant that never started has no
+     * `startedAt`. The record's own `startedAt` above is the run's creation time.
+     */
+    arrival?: RunParticipantArrival;
+}
+/** A participant record's `arrival`. */
+export interface RunParticipantArrival {
+    startAfterMs: number;
+    scheduledAt?: string;
+    startedAt?: string;
 }
 export interface RunEvent {
     id: string;
@@ -158,7 +173,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 +202,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/participant-records.js

@@ -29,6 +29,7 @@ export function participantRecord(ids, place, fields) {
         streamIds: [ids.streamId],
         startedAt: fields.startedAt,
         updatedAt: fields.updatedAt,
+        ...(fields.arrival === undefined ? {} : { arrival: fields.arrival }),
     };
 }
 /**

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

@@ -117,13 +117,15 @@ function observerTarget(options) {
 function runPublisher(args) {
     const { options, runId, createdAt, paths, runStatus, now, admit, participantsRan } = args;
     const observer = observerTarget(options);
-    // The study's warnings join whatever events the route wrote, once, in every write.
+    // The study's warnings join whatever events the route wrote, once, in every write. A warning can
+    // quote the study file, which may name a sandbox URL a participant needs, so each goes through
+    // the redaction a run failure gets.
     const studyWarnings = (options.warnings ?? []).map((message, index) => ({
         id: `event-study-warning-${String(index + 1).padStart(3, "0")}`,
         at: createdAt,
         level: "warn",
         type: "study.warning",
-        message,
+        message: redactText(message),
     }));
     const withStudyWarnings = (events) => [
         ...events.filter((event) => !studyWarnings.some((warning) => warning.id === event.id)),

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})`;
+}