humanish 0.110.3 → 0.110.4

package/CHANGELOG.md

@@ -8,6 +8,20 @@ The Unreleased section holds the full notes for the next version until it is tag
 
 ## Unreleased
 
+## 0.110.4: Scripted runs reclaim clean, review says interrupted, Chrome under a long TMPDIR (2026-10-05)
+
+humanish 0.110.4 fixes four findings of the 0.110.3 live smoke. `humanish reclaim --check` reports
+a live scripted run against an `app-url` subject `clean`, with reason `no-sandbox`, and exits 0.
+`humanish review` on a computer-use run stopped by Ctrl-C after its desktop started says the run
+was interrupted. A run that failed before any participant started no longer prints "Participants
+finished; preparing analysis…". The scripted route launches Chrome when `TMPDIR` is too long for
+Chrome's socket path. Planner refusals for a library config built without `parseStudy` name v3
+keys, and so does `humanish migrate` when one of those checks refuses a v2 file. Inside, a v3
+parser runs beside `parseStudy`, src reads the study through accessors, and `humanish migrate`
+reads v2 files through its own front end; the library API is unchanged.
+
+[Release notes](https://github.com/danielgwilson/humanish/releases/tag/v0.110.4)
+
 ## 0.110.3: Ctrl-C at the watch prompt, review says analysis is off, E2B docs links kept (2026-10-05)
 
 humanish 0.110.3 runs the `watch` and `observe` shutdown, and prints `watch stopped` or `observe

package/dist/actors/scripted-browser/actor.js

@@ -23,17 +23,26 @@ import { assertPreparedSelectedOutputDirectory, assertSafeOutputPathSegment, pre
 import { ACTOR_TRACE_SCHEMA, SCRIPTED_BROWSER_CAPABILITIES, } from "../contract.js";
 import { buildBlockedBrowserPersonaSteps, buildBrowserTrace, captureBlockedStepScreenshot, compactBrowserError, executeBrowserPersonaStep, probeAppUrl, sanitizeBrowserEvidenceUrl, screenshotPathForBrowserStep, surfaceScreenshotPath, tracePathForBrowserSurface, } from "./steps.js";
 import { LOOPBACK_EVIDENCE_URL_POLICY, } from "./types.js";
+import { chromeLaunchEnv, chromeLaunchError } from "./launch-env.js";
 /** Production default: lazy playwright-core import + chromium.launch, exactly as the driver
- *  always did. Kept in one place so the optional peer is touched by exactly one code path. */
+ *  always did. Kept in one place so the optional peer is touched by exactly one code path. A
+ *  `TMPDIR` too long for Chrome's singleton socket is replaced for Chrome (chromeLaunchEnv). */
 async function launchPlaywrightChromium(args) {
     const { chromium } = await import("playwright-core");
-    const browser = await chromium.launch({
-        executablePath: args.browserCommand,
-        headless: true,
-        args: [...CHROMIUM_EVIDENCE_HYGIENE_FLAGS, "--disable-gpu", "--disable-dev-shm-usage"],
-        timeout: args.timeoutMs,
-    });
-    return browser;
+    const env = await chromeLaunchEnv();
+    try {
+        const browser = await chromium.launch({
+            executablePath: args.browserCommand,
+            headless: true,
+            args: [...CHROMIUM_EVIDENCE_HYGIENE_FLAGS, "--disable-gpu", "--disable-dev-shm-usage"],
+            timeout: args.timeoutMs,
+            ...(env === undefined ? {} : { env }),
+        });
+        return browser;
+    }
+    catch (error) {
+        throw chromeLaunchError(error, env);
+    }
 }
 function assertScriptedSessionPathIds(options) {
     assertSafeOutputPathSegment(options.surface.id, "Browser surface id");

package/dist/actors/scripted-browser/launch-env.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The environment to launch Chrome with: `env` with `TMPDIR` set to /tmp when its own `TMPDIR` is
+ * too long for the singleton socket and /tmp is a writable directory. Undefined when Chrome can
+ * launch with `env` as it is, or when /tmp cannot be used; chromeLaunchError then names the cause.
+ */
+export declare function chromeLaunchEnv(env?: NodeJS.ProcessEnv): Promise<NodeJS.ProcessEnv | undefined>;
+/**
+ * The launch error to report: one that names the cause and the fix when Chrome aborted because its
+ * singleton socket path was too long, and `error` itself otherwise. `env` is the environment
+ * Chrome was launched with.
+ */
+export declare function chromeLaunchError(error: unknown, env?: NodeJS.ProcessEnv): unknown;

package/dist/actors/scripted-browser/launch-env.js

@@ -0,0 +1,50 @@
+// Chrome's process singleton listens on a Unix socket at `$TMPDIR/<product>.XXXXXX/SingletonSocket`,
+// where the product is com.google.Chrome, or org.chromium.Chromium for Chromium and Chrome for
+// Testing. A Unix socket path holds at most 107 bytes on Linux and 103 on macOS, so under a longer
+// `TMPDIR`, such as a sandboxed agent's private temp directory, Chrome aborts at launch with
+// "Socket path too long", and Playwright reports only that the browser closed. The scripted
+// browser gives Chrome /tmp in that case; the browser profile stays where Playwright puts it.
+import { constants } from "node:fs";
+import { access } from "node:fs/promises";
+/** `/org.chromium.Chromium.XXXXXX/SingletonSocket`: the longest path Chrome adds to `TMPDIR`. */
+const SOCKET_SUFFIX_BYTES = 45;
+/** The longest socket path, without its NUL: `sun_path` holds 104 bytes on macOS, 108 elsewhere. */
+const SOCKET_PATH_MAX_BYTES = process.platform === "darwin" ? 103 : 107;
+/** Where Chrome makes its socket directory when `TMPDIR` is unset. */
+const DEFAULT_TMPDIR = "/tmp";
+/** The byte length of `TMPDIR` when Chrome's singleton socket path under it would be too long. */
+function overlongTmpdirBytes(env) {
+    const tmpdir = env.TMPDIR?.replace(/\/+$/, "");
+    if (tmpdir === undefined || tmpdir === "")
+        return undefined;
+    const bytes = Buffer.byteLength(tmpdir);
+    return bytes + SOCKET_SUFFIX_BYTES > SOCKET_PATH_MAX_BYTES ? bytes : undefined;
+}
+/**
+ * The environment to launch Chrome with: `env` with `TMPDIR` set to /tmp when its own `TMPDIR` is
+ * too long for the singleton socket and /tmp is a writable directory. Undefined when Chrome can
+ * launch with `env` as it is, or when /tmp cannot be used; chromeLaunchError then names the cause.
+ */
+export async function chromeLaunchEnv(env = process.env) {
+    if (process.platform === "win32" || overlongTmpdirBytes(env) === undefined)
+        return undefined;
+    try {
+        await access(DEFAULT_TMPDIR, constants.W_OK | constants.X_OK);
+    }
+    catch {
+        return undefined;
+    }
+    return { ...env, TMPDIR: DEFAULT_TMPDIR };
+}
+/**
+ * The launch error to report: one that names the cause and the fix when Chrome aborted because its
+ * singleton socket path was too long, and `error` itself otherwise. `env` is the environment
+ * Chrome was launched with.
+ */
+export function chromeLaunchError(error, env = process.env) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (!message.includes("Socket path too long"))
+        return error;
+    const bytes = overlongTmpdirBytes(env);
+    return new Error(`Chrome could not start: its singleton socket path under \`TMPDIR\`${bytes === undefined ? "" : ` (${bytes} bytes)`} is longer than the ${SOCKET_PATH_MAX_BYTES} bytes a Unix socket path allows. Set \`TMPDIR\` to a directory of at most ${SOCKET_PATH_MAX_BYTES - SOCKET_SUFFIX_BYTES} bytes, such as /tmp, and run again.`);
+}

package/dist/analysis/automatic-completion.d.ts

@@ -9,7 +9,8 @@ export interface AnalysisInput {
     readonly deps?: Pick<StudyDeps, "analysis">;
     /** Cancels the analysis only. */
     readonly analysisSignal?: AbortSignal;
-    /** Receives analysis-started and analysis-finished. */
+    /** Receives analysis-started and analysis-finished, around the analysis of a run where a
+     *  participant's session started. */
     readonly emit?: (event: StudyEvent) => void;
 }
 export interface AutomaticAnalysisResult {

package/dist/analysis/automatic-completion.js

@@ -38,8 +38,13 @@ export async function completeAutomaticAnalysis(result, finished, config, input,
     const signal = input?.analysisSignal;
     let started = false;
     try {
-        input?.emit?.({ type: "analysis-started" });
-        started = true;
+        // The CLI prints "Participants finished" on analysis-started. A run where no participant's
+        // session started (it failed before, such as at E2B login) still records its analysis
+        // outcome, but without the two events.
+        if (finished.participantsRan) {
+            input?.emit?.({ type: "analysis-started" });
+            started = true;
+        }
         try {
             await validatePreparedRunRootIdentity(prepared);
         }

package/dist/cli/commands/migrate.js

@@ -1,4 +1,4 @@
-import { migrateStudies } from "../../study/migrate.js";
+import { migrateStudies, } from "../../study/migrate/migrate.js";
 import { CWD_OPTION_DESCRIPTION, JSON_OPTION_DESCRIPTION, wantsJson, writeResult, } from "../io.js";
 function formatValue(value) {
     const text = JSON.stringify(value);

package/dist/cli/commands/runs.js

@@ -217,9 +217,12 @@ function formatReclaimHuman(result, cwd, preflight) {
     const search = result.tagSearch.status === "done"
         ? `E2B lists ${plural(result.tagSearch.found, "more sandbox", "more sandboxes")} tagged with it`
         : `E2B tag search ${result.tagSearch.status}`;
+    const head = `${check ? "Reclaim check" : "Reclaim"} ${result.runId}: ${result.state}.`;
     lines.push(result.reason === "dry-run"
-        ? `${check ? "Reclaim check" : "Reclaim"} ${result.runId}: ${result.state}. It was a dry run, which creates no sandboxes, so E2B was not contacted.`
-        : `${check ? "Reclaim check" : "Reclaim"} ${result.runId}: ${result.state}. ${plural(result.receiptCount, "sandbox receipt")}; ${search}.`);
+        ? `${head} It was a dry run, which creates no sandboxes, so E2B was not contacted.`
+        : result.reason === "no-sandbox"
+            ? `${head} Its status.json records that its route created no sandbox, so E2B was not contacted.`
+            : `${head} ${plural(result.receiptCount, "sandbox receipt")}; ${search}.`);
     for (const outcome of result.outcomes) {
         lines.push(`  sandbox ${outcome.sandboxIdDigest} (${outcome.laneId}, from ${outcome.source}): ${outcome.state}${outcome.detail ? `: ${outcome.detail}` : ""}`);
     }

package/dist/cli/commands/study-route-computer-use.js

@@ -13,6 +13,7 @@ import { writeRunFindings } from "../findings.js";
 import { formatCuaStudyHuman } from "./study-format.js";
 import { resolveRouteShouldOpen } from "./study-route-open.js";
 import { studyResultIdentity } from "../../run/study-result.js";
+import { actorOf, declaredParticipantCount } from "../../study/study-fields.js";
 /**
  * The computer-use route's CLI setup: its settings, the watch and exposure plan, the runStudyWith options
  * with the live Observer hook, and how it presents the outcome or a run error. Undefined when
@@ -54,7 +55,7 @@ function refuseCua(args, dryRun, code, message) {
         ...studyResultIdentity("computer-use", args.config.id),
         ok: false,
         cwd: args.options.cwd,
-        actor: args.config.actors[0]?.type ?? "",
+        actor: actorOf(args.config)?.type ?? "",
         appUrl: "",
         dryRun,
         runId: args.options.runId ?? "not-created",
@@ -79,7 +80,7 @@ function resolveCuaSettings(args) {
         args.io.setExitCode(2);
         return undefined;
     }
-    const count = parseStudyCount(args.options.count, args.config.actors[0]?.count ?? 1);
+    const count = parseStudyCount(args.options.count, declaredParticipantCount(args.config) ?? 1);
     if (count === null) {
         args.io.writeErr("error: --count must be a positive integer.\n");
         args.io.setExitCode(2);

package/dist/cli/commands/study-route-preview.js

@@ -2,12 +2,13 @@ import { Command } from "commander";
 import { studyResultIdentity } from "../../run/study-result.js";
 import { formatRunHuman, parseStudyCount, writeResult, } from "../io.js";
 import { planObserver, showObserver, staticObserverOpen } from "../observer-follow.js";
+import { declaredParticipantCount } from "../../study/study-fields.js";
 /**
  * The preview route's CLI setup: the participant count and Observer plan, its runStudyWith options, and how it
  * presents the outcome. Undefined when setup has already written its own result.
  */
 export function previewRouteRun(args) {
-    const participantCount = parseStudyCount(args.options.count, args.config.actors[0]?.count ?? 4);
+    const participantCount = parseStudyCount(args.options.count, declaredParticipantCount(args.config) ?? 4);
     if (participantCount === null) {
         const result = {
             ...studyResultIdentity("preview", args.config.id),

package/dist/cli/commands/study-route-shared-world.js

@@ -9,8 +9,8 @@ import { followDecision, followObserver, showObserver, staticObserverOpen, withO
 import { writeRunFindings } from "../findings.js";
 import { formatConcurrentSharedWorldStudyHuman } from "./study-format.js";
 import { resolveRouteShouldOpen, watchFinishedPlan } from "./study-route-open.js";
-import { rosterOf } from "../../study/parse/actors.js";
 import { studyResultIdentity } from "../../run/study-result.js";
+import { actorOf, participantList } from "../../study/study-fields.js";
 /**
  * The shared-world route's CLI setup: dry run, open and follow semantics, the live Observer server
  * the run attaches, and how it presents the outcome. Undefined when setup has already written its
@@ -34,10 +34,10 @@ export function sharedWorldRouteRun(args) {
             ...studyResultIdentity("shared-world", args.config.id),
             ok: false,
             cwd: args.options.cwd,
-            actor: args.config.actors[0]?.type ?? "",
+            actor: actorOf(args.config)?.type ?? "",
             topology: "shared-world",
             topologyMode: "concurrent",
-            roleCount: rosterOf(args.config.actors[0])?.length ?? 0,
+            roleCount: participantList(args.config)?.length ?? 0,
             concurrency: args.config.execution?.concurrency ?? 1,
             dryRun,
             runId: runId ?? args.options.runId ?? "not-created",

package/dist/cli/commands/study.js

@@ -4,6 +4,7 @@ import { Command, Option } from "commander";
 import { inspectStudyManifest, listStudyManifests } from "../../study/discover.js";
 import { runStudyPreflight, } from "../../study/preflight.js";
 import { applyEnvFileOption, CWD_OPTION_DESCRIPTION, DOTENV_OPTION_DESCRIPTION, dotenvPathOf, envFileAliasOption, JSON_OPTION_DESCRIPTION, parsePositiveInteger, writeResult, humanError, } from "../io.js";
+import { actorsOf } from "../../study/study-fields.js";
 export function registerStudyCommands(parent, io) {
     const study = parent
         .command("study")
@@ -114,7 +115,9 @@ function formatStudyShowHuman(result) {
         `id: ${config.id}`,
         `subject: ${config.subject.source}`,
         ...(config.execution?.target ? [`execution: ${config.execution.target}`] : []),
-        `actors: ${config.actors.map((actor) => actor.type).join(", ")}`,
+        `actors: ${actorsOf(config)
+            .map((actor) => actor.type)
+            .join(", ")}`,
         ...(config.title ? [`title: ${config.title}`] : []),
         ...(config.description ? [`description: ${config.description}`] : []),
         ...(result.path ? [`path: ${result.path}`] : []),

package/dist/routes/computer-use/live-phase.js

@@ -102,7 +102,14 @@ export async function runStudyParticipants(setup, participants) {
     let failFastReason;
     try {
         if (!dryRun)
-            ({ outcomes, failFastReason } = await runAllCuaParticipants(participantRuns, deps, participantPlan, inProcess));
+            ({ outcomes, failFastReason } = await runAllCuaParticipants(participantRuns, {
+                ...deps,
+                // A session that throws returns no trace; the run still records that it started.
+                runSession: (options) => {
+                    run.participantStarted();
+                    return deps.runSession(options);
+                },
+            }, participantPlan, inProcess));
     }
     finally {
         try {

package/dist/routes/computer-use/local-vm.js

@@ -10,6 +10,7 @@ import { createRestrictedCodexParticipant } from "../../actors/codex/restricted-
 import { withCloseReport } from "./participant-model.js";
 import { guestMediaConfigSchema } from "../../guest/media-config.js";
 import { startLocalCapturedInbox } from "../../substrates/local/captured-inbox.js";
+import { actorOf } from "../../study/study-fields.js";
 function guestMedia(config) {
     const declaredMedia = config.execution?.desktop?.media;
     return declaredMedia === undefined
@@ -164,7 +165,7 @@ export function prepareLocalVmRun(options) {
     const media = guestMedia(config);
     // A caller-supplied provider replaces the Codex account participant, so the account is
     // neither checked nor used.
-    const account = config.actors[0]?.type === "local-agent" && options.createProvider === undefined;
+    const account = actorOf(config)?.type === "local-agent" && options.createProvider === undefined;
     const state = { sessions: [], participants: [], cleanupUnconfirmed: false };
     const context = {
         config,

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

@@ -7,7 +7,7 @@ import { actorRegistry, isCuaActorDescriptor, } from "../../actors/registry.js";
 import { isHttpUrl, isLoopbackUrl } from "../../study/parse/subject.js";
 import { studyUrlCredentialReason } from "../../study/url-credentials.js";
 import { subjectStateInvalidReason } from "../../study/parse/subject-state.js";
-import { brainOf, callerBrainOf, capsOf, desktopRequirements, planBase, provisionedSubject, } from "../../study/plan-base.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 { cloneTargetValidationReason, computerUseValidationReason, desktopMediaValidationReason, outputTokenLimitValidationReason, receivingEmailValidationReason, scenarioCapsValidationReason, taskProtocolValidationReason, } from "../../study/validation.js";
@@ -16,6 +16,7 @@ import { isLocalBrowserStudy } from "../../substrates/local/runtime-config.js";
 import { boundedConcurrency, defaultSessionTimeoutMs, resolveParticipantSandboxMs, } from "./participant-runs.js";
 import { MAX_SANDBOX_MS } from "../../substrates/e2b/lifetime.js";
 import {} from "./types.js";
+import { actorOf, declaresSharedWorld } from "../../study/study-fields.js";
 /** The registered descriptor for a planned actor id; planComputerUseStudy checked the registry. */
 export function cuaDescriptorOf(actor) {
     const descriptor = actorRegistry[actor];
@@ -88,7 +89,7 @@ function unsupportedDeclarationReason(config, hasRunSession, driving, { inProces
         scenarioCapsValidationReason(config);
     if (reason)
         return invalid(reason);
-    if (config.actors[0]?.maxOutputTokens !== undefined &&
+    if (actorOf(config)?.maxOutputTokens !== undefined &&
         (hasRunSession || driving.createProvider || driving.inProcess))
         return invalid("maxOutputTokens cannot be enforced by a custom runSession/provider/executor route.");
     const receivingReason = receivingEmailValidationReason(config);
@@ -220,7 +221,7 @@ export function planComputerUseStudy(config, input) {
     if (tasksReason)
         return refuse("before-scope", "HUMANISH_STUDY_TASKS_UNSUPPORTED", tasksReason);
     // The parser checks the actor too; a library caller skips the parser.
-    const actorType = config.actors[0]?.type ?? "";
+    const actorType = actorOf(config)?.type ?? "";
     const descriptor = actorRegistry[actorType];
     if (!descriptor || !isCuaActorDescriptor(descriptor))
         return refuse("in-scope", "HUMANISH_COMPUTER_USE_ACTOR_UNSUPPORTED", `actor.type "${actorType}" is not a registered computer-use actor.`);
@@ -231,7 +232,7 @@ export function planComputerUseStudy(config, input) {
     // A shared world runs every participant against one app; this route would run them as separate
     // participants. It comes after the rules above, so a shared-world config that breaks one of them,
     // which runStudyWith sends here, still gets that rule's message.
-    if (config.subject.topology === "shared-world")
+    if (declaresSharedWorld(config))
         return refuse("in-scope", "HUMANISH_COMPUTER_USE_SUBJECT_INVALID", "route: shared-world studies run every participant against one shared app on the shared-world route; this route runs independent participants. The shared-world route takes subject.source clone or local-tree, or app-url with policies.allowPublicTargets: true, on execution.target e2b-desktop.", actor);
     // The in-process route drives subject.appUrl on this machine and creates no desktop, so it would
     // skip the subject a clone, local-tree or desktop-cli study declares.
@@ -292,7 +293,7 @@ export function planComputerUseStudy(config, input) {
             concurrency: boundedConcurrency(declared, n),
             sessionBudgetMs: config.execution?.timeoutMs ?? defaultSessionTimeoutMs(config),
             sandboxMs: resolveParticipantSandboxMs(config),
-            caps: capsOf(config),
+            caps: planCaps(config, "computer-use"),
             ...(input.rerun === undefined ? {} : { rerun: rerunPlan(input.rerun) }),
             requirements: base.dryRun || runner.desktop === "in-process"
                 ? []

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

@@ -32,6 +32,7 @@ import { runStudyParticipants } from "./live-phase.js";
 import { admitCuaRun, refuseCuaStudy, startCuaRun } from "./setup.js";
 import {} from "./types.js";
 import { studyResultIdentity } from "../../run/study-result.js";
+import { actorOf } from "../../study/study-fields.js";
 /**
  * A refused computer-use study's result, at the refusal's stage: a before-scope refusal has its own
  * envelope and no analysis record; the others come after the cwd checks, and the participant cap after
@@ -44,7 +45,7 @@ export async function computerUseStudyRefusal(options, refusal) {
             ...studyResultIdentity("computer-use", config.id),
             ok: false,
             cwd: path.resolve(options.cwd),
-            actor: config.actors[0]?.type ?? "",
+            actor: actorOf(config)?.type ?? "",
             dryRun,
             runId: options.runId ?? "not-created",
             appUrl: config.subject.appUrl ?? config.subject.serve?.url ?? "",

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

@@ -25,6 +25,7 @@ import { projectParticipantSubjects, subjectProvenanceArg } from "./subject-proj
 import { participantSubjectEnv, } from "./types.js";
 import { studyPersonaIds } from "../../study/persona-resolve.js";
 import { studyResultIdentity } from "../../run/study-result.js";
+import { actorOf } from "../../study/study-fields.js";
 /** The physical project, bound before any caller hook runs. */
 async function bindProject(cwd) {
     // Capture the physical project before reading or invoking any caller hook. A supported
@@ -47,7 +48,7 @@ export async function refuseCuaStudy(options, refusal) {
         ...studyResultIdentity("computer-use", config.id),
         ok: false,
         cwd: projectRoot.physicalPath,
-        actor: refusal.actor ?? config.actors[0]?.type ?? "",
+        actor: refusal.actor ?? actorOf(config)?.type ?? "",
         appUrl: declaredAppUrl(config),
         dryRun,
         runId: options.runId ?? "not-created",

package/dist/routes/scripted/plan.js

@@ -7,6 +7,7 @@ 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 { actorOf, surfaceCount, scenarioRefOf } from "../../study/study-fields.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;
@@ -42,7 +43,7 @@ export function planScriptedStudy(config, input) {
     const cloneTargetReason = cloneTargetValidationReason(config);
     if (cloneTargetReason)
         return refuse("HUMANISH_SCRIPTED_SUBJECT_UNSAFE", cloneTargetReason);
-    const actorType = config.actors[0]?.type ?? "";
+    const actorType = actorOf(config)?.type ?? "";
     const descriptor = actorRegistry[actorType];
     if (!descriptor || !isScriptedBrowserActorDescriptor(descriptor))
         return refuse("HUMANISH_SCRIPTED_ACTOR_UNSUPPORTED", `actor.type "${actorType}" is not a registered scripted-browser actor.`);
@@ -63,7 +64,7 @@ export function planScriptedStudy(config, input) {
         subject = { kind: "loopback", appUrl };
     }
     // The steps are the actor, so there is no built-in journey to fall back on.
-    const scenarioRef = config.scenario?.ref;
+    const scenarioRef = scenarioRefOf(config);
     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 requirements = [];
@@ -75,7 +76,7 @@ export function planScriptedStudy(config, input) {
     // The browser runs on this machine on both subjects; a clone's is pointed at its getHost URL.
     if (!input.dryRun && input.injectedBrowser !== true)
         requirements.push({ kind: "host-browser" });
-    const persona = config.actors[0]?.persona;
+    const persona = actorOf(config)?.persona;
     const timeoutMs = config.execution?.timeoutMs;
     return {
         ok: true,
@@ -88,7 +89,7 @@ export function planScriptedStudy(config, input) {
             actor,
             subject,
             scenarioRef,
-            surfaces: browserSurfaces.slice(0, config.actors[0]?.count ?? DEFAULT_SURFACE_COUNT),
+            surfaces: browserSurfaces.slice(0, surfaceCount(config) ?? DEFAULT_SURFACE_COUNT),
             ...(persona === undefined ? {} : { personaId: persona }),
             ...(timeoutMs === undefined ? {} : { sessionTimeoutMs: timeoutMs }),
             requirements,

package/dist/routes/scripted/route.js

@@ -31,6 +31,7 @@ import { ScriptedSubject } from "./subject.js";
 import { runScriptedSessions, writeSurfaceTraces } from "./surface-sessions.js";
 import {} from "./types.js";
 import { studyResultIdentity } from "../../run/study-result.js";
+import { actorOf } from "../../study/study-fields.js";
 /**
  * A refused scripted study's result, at the refusal's stage: a before-scope refusal has its own field
  * order and no analysis record; the others come after the output directory checks.
@@ -38,7 +39,7 @@ import { studyResultIdentity } from "../../run/study-result.js";
 export async function scriptedStudyRefusal(options, refusal) {
     const { config, dryRun } = options;
     const cwd = path.resolve(options.cwd);
-    const actorType = config.actors[0]?.type ?? "";
+    const actorType = actorOf(config)?.type ?? "";
     if (refusal.beforeScope)
         return {
             ...studyResultIdentity("scripted", config.id),
@@ -94,6 +95,8 @@ async function runScriptedPlanInScope(plan, input, scope) {
         mintRunId: makeScriptedRunId,
         mode: dryRun ? "dry-run" : "live",
         study: plan.study,
+        // Only a clone subject is served from a sandbox; an app-url run drives a local browser.
+        sandboxes: setup.clone ? undefined : "none",
         renderReview: renderScriptedReviewMarkdown,
         observer: { open: input.open === true, render: setup.deps.renderObserver },
     });
@@ -144,6 +147,7 @@ async function runScriptedPlanInScope(plan, input, scope) {
                 deps: setup.deps,
                 browserCommand: setup.browserCommand,
                 runPaths,
+                onSessionStart: () => run.participantStarted(),
             });
         }
         catch (error) {

package/dist/routes/scripted/surface-sessions.d.ts

@@ -8,6 +8,8 @@ export declare function runScriptedSessions(session: Required<Pick<ScriptedBrows
     deps: StudyDeps;
     browserCommand: string | undefined;
     runPaths: PreparedRunArtifactPaths;
+    /** Called as each surface's session starts, before it can throw or return. */
+    onSessionStart: () => void;
 }): Promise<ScriptedBrowserSessionResult[]>;
 /** Writes each surface's actor-<surface>.json, as the computer-use route writes actor.json. */
 export declare function writeSurfaceTraces(runPaths: PreparedRunArtifactPaths, results: readonly ScriptedBrowserSessionResult[]): Promise<void>;

package/dist/routes/scripted/surface-sessions.js

@@ -7,9 +7,10 @@ import { validateScriptedSessionResult } from "./session-result.js";
 /** One session per surface, in parallel. */
 export function runScriptedSessions(session, run) {
     const { appUrl, evidenceAppUrl, urlPolicy, journey, persona, timeoutMs, artifactRoot } = session;
-    const { surfaces, deps, browserCommand, runPaths } = run;
+    const { surfaces, deps, browserCommand, runPaths, onSessionStart } = run;
     const runSession = deps.runScriptedSession;
     return Promise.all(surfaces.map((surface) => {
+        onSessionStart();
         const sessionOptions = {
             appUrl,
             evidenceAppUrl,

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

@@ -167,7 +167,11 @@ export function participantRunDeps(ctx, live, scrubKnownValues) {
         studyCwd: ctx.cwd,
         redactScreenshots: ctx.redactScreenshots,
         scrubKnownValues,
-        runSession: ctx.runSession,
+        // A session that throws returns no trace; the run still records that it started.
+        runSession: (options) => {
+            ctx.run.participantStarted();
+            return ctx.runSession(options);
+        },
         // A local-agent brain runs each participant on the operator's signed-in agent, as on computer
         // use.
         brain: ctx.plan.brain,

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

@@ -6,12 +6,13 @@ import { DEFAULT_OPENAI_CU_MODEL } from "../../actors/computer-use/openai-provid
 import { studyUrlCredentialReason } from "../../study/url-credentials.js";
 import { actorRegistry, isCuaActorDescriptor, } from "../../actors/registry.js";
 import { resolveAutomaticAnalysis } from "../../analysis/automatic-config.js";
-import { brainOf, capsOf, desktopRequirements, isNonEmpty, planBase, } from "../../study/plan-base.js";
+import { brainOf, planCaps, desktopRequirements, isNonEmpty, planBase, } from "../../study/plan-base.js";
 import { sharedWorldParticipants } from "../../study/plan-participants.js";
 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, scenarioCapsValidationReason, taskProtocolValidationReason, } from "../../study/validation.js";
 import { MODEL_RATES, unpricedCapMessage } from "../../run/pricing.js";
+import { actorOf, capsOf } from "../../study/study-fields.js";
 /** The registered descriptor for a planned actor; planSharedWorldStudy checked the registry. */
 export function sharedWorldDescriptorOf(actorType) {
     const descriptor = actorRegistry[actorType];
@@ -38,7 +39,7 @@ export function planSharedWorldStudy(config, input) {
     const tasksReason = taskProtocolValidationReason(config, false);
     if (tasksReason)
         return refuse("HUMANISH_STUDY_TASKS_UNSUPPORTED", tasksReason);
-    const actorType = config.actors[0]?.type ?? "";
+    const actorType = actorOf(config)?.type ?? "";
     const descriptor = actorRegistry[actorType];
     if (!descriptor || !isCuaActorDescriptor(descriptor))
         return refuse("HUMANISH_SHARED_WORLD_ACTOR_UNSUPPORTED", `actor.type "${actorType}" is not a registered computer-use actor.`);
@@ -59,11 +60,11 @@ export function planSharedWorldStudy(config, input) {
             : concurrentSharedWorldValidationReason(config));
     if (invalidReason)
         return refuse(invalid, invalidReason, actor);
-    if (config.actors[0]?.maxOutputTokens !== undefined && input.hasRunSession === true)
+    if (actorOf(config)?.maxOutputTokens !== undefined && input.hasRunSession === true)
         return refuse(invalid, "maxOutputTokens cannot be enforced by a custom runSession.", actor);
-    const caps = config.execution?.caps;
+    const caps = capsOf(config, "shared-world");
     if (!input.dryRun && (caps?.maxUsd !== undefined || caps?.maxTotalUsd !== undefined)) {
-        const model = (config.actors[0]?.model ?? DEFAULT_OPENAI_CU_MODEL).trim().toLowerCase();
+        const model = (actorOf(config)?.model ?? DEFAULT_OPENAI_CU_MODEL).trim().toLowerCase();
         if (!MODEL_RATES[model])
             return refuse("HUMANISH_SHARED_WORLD_UNPRICED_CAP", unpricedCapMessage(model), actor);
     }
@@ -106,7 +107,7 @@ export function planSharedWorldStudy(config, input) {
                 ? {}
                 : { sessionTimeoutMs: config.execution.timeoutMs }),
             brain,
-            caps: capsOf(config),
+            caps: planCaps(config, "shared-world"),
             requirements: base.dryRun
                 ? []
                 : [

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

@@ -48,7 +48,7 @@ import { prepareConcurrentRun } from "./setup.js";
 import { browserRouteScorer } from "../../study/adapter-scorer-loader.js";
 import { withLateScorer } from "../../study/route-inputs.js";
 import {} from "./types.js";
-import { rosterOf } from "../../study/parse/actors.js";
+import { actorOf, participantList } from "../../study/study-fields.js";
 /** The shared-world code for each local-agent refusal, kind for kind with computer-use. */
 const LOCAL_AGENT_REFUSAL_CODES = {
     "agent-missing": "HUMANISH_SHARED_WORLD_AGENT_MISSING",
@@ -59,11 +59,11 @@ const LOCAL_AGENT_REFUSAL_CODES = {
 /** A refused shared-world study's result: the route's envelope, and a refusal's analysis record. */
 export function sharedWorldStudyRefusal(options, refusal) {
     const { config, dryRun } = options;
-    const declared = rosterOf(config.actors[0]) ?? [];
+    const declared = participantList(config) ?? [];
     const fail = concurrentStudyFailure({
         cwd: path.resolve(options.cwd),
         studyId: config.id,
-        actor: config.actors[0]?.type ?? "",
+        actor: actorOf(config)?.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.

package/dist/routes/terminal/plan.js

@@ -13,6 +13,7 @@ import { NODE_BOOTSTRAP_TIMEOUT_MS } from "../../subject/node-bootstrap.js";
 import { terminalSandboxTimeoutMs } from "./lifetime.js";
 import { isExactRuntimeVersion, TERMINAL_RUNTIME_VERSION_TIMEOUT_MS } from "./runtime.js";
 import { PRODUCT_SETUP_TIMEOUT_MS, TERMINAL_SANDBOX_TIMEOUT_BUFFER_MS, } from "./types.js";
+import { actorOf, capsOf } from "../../study/study-fields.js";
 /**
  * Plan a terminal-product study. It is called for any config handed to the terminal runner, not
  * only one routeOf sends here, so a config for another route gets this route's refusal.
@@ -40,12 +41,12 @@ export function planTerminalStudy(config, input) {
     const tasksReason = taskProtocolValidationReason(config, false);
     if (tasksReason)
         return refuse("HUMANISH_STUDY_TASKS_UNSUPPORTED", tasksReason);
-    const actorType = config.actors[0]?.type ?? "";
+    const actorType = actorOf(config)?.type ?? "";
     const descriptor = actorRegistry[actorType];
     if (!descriptor || !isTerminalActorDescriptor(descriptor))
         return refuse("HUMANISH_TERMINAL_ACTOR_UNSUPPORTED", `actor.type "${actorType}" is not a registered terminal actor.`);
     const runtimeVersion = config.execution?.runtime?.version;
-    const actor = config.actors[0];
+    const actor = actorOf(config);
     if ((config.execution?.runtime !== undefined && !isExactRuntimeVersion(runtimeVersion)) ||
         (actor?.model !== undefined &&
             (typeof actor.model !== "string" || actor.model.trim().length === 0)) ||
@@ -83,7 +84,7 @@ export function planTerminalStudy(config, input) {
         ...(egressAllow === undefined ? {} : { egressAllow }),
         ...(stdin === undefined ? {} : { stdin }),
     };
-    const caps = config.scenario?.caps;
+    const caps = capsOf(config, "terminal");
     if (input.dryRun)
         return { ok: true, plan: { ...shared, dryRun: true, ...(caps ? { caps } : {}) } };
     // The live route injects the runtime key into one command only, and only a registered actor

package/dist/routes/terminal/route.js

@@ -54,6 +54,7 @@ import { terminalRouteScorer } from "../../study/adapter-scorer-loader.js";
 import { withLateScorer } from "../../study/route-inputs.js";
 import {} from "./types.js";
 import { studyResultIdentity } from "../../run/study-result.js";
+import { actorOf } from "../../study/study-fields.js";
 /** A refused terminal study's result: the route's envelope, and the analysis record a refusal gets. */
 export function terminalStudyRefusal(options, refusal) {
     const { config, dryRun } = options;
@@ -61,7 +62,7 @@ export function terminalStudyRefusal(options, refusal) {
         ...studyResultIdentity("terminal", config.id),
         ok: false,
         cwd: path.resolve(options.cwd),
-        actor: refusal.actor ?? config.actors[0]?.type ?? "",
+        actor: refusal.actor ?? actorOf(config)?.type ?? "",
         product: config.subject.product?.name ?? "",
         dryRun,
         runId: options.runId ?? "not-created",