humanish 0.110.3 → 0.111.0

package/CHANGELOG.md

@@ -8,6 +8,35 @@ The Unreleased section holds the full notes for the next version until it is tag
 
 ## Unreleased
 
+## 0.111.0: StudyConfig has the keys of a v3 study file (2026-10-05)
+
+humanish 0.111.0 is the first breaking release under the compatibility policy. It breaks library
+callers that read or build a `StudyConfig`, the type `parseStudy` returns and `runStudy` takes:
+the type now has the keys of a `humanish.study.v3` file, such as `actor`, `route`,
+`participants`, `caps` and `mode`, where it had `actors[0]`, `execution.caps` and
+`scenario.mode`. The release notes carry the migration table. `runStudy` refuses a config that
+still sets a 0.110 field with `HUMANISH_STUDY_V2_UNSUPPORTED`, so a budget left in
+`execution.caps` cannot run uncapped. Study files and CLI commands are unchanged, except two JSON
+outputs: `humanish study show --json` prints the v3 config, and `humanish study check --json`
+names a participant's target `participants[<i>].target`. The `--env-file` and `cleanup` aliases
+still work and are removed in 0.112.0, on or after 2026-11-03.
+
+[Release notes](https://github.com/danielgwilson/humanish/releases/tag/v0.111.0)
+
+## 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/CONTEXT.md

@@ -18,7 +18,7 @@ bundle and output fields keep older spellings; the second table maps them.
 | persona             | Who a participant is: traits, background, device. `humanish/personas/<id>.yaml`.                                                                                                                                                                                                                                                                                                                                                                                                                                                      | `src/study/persona.ts`, `src/study/persona-resolve.ts`                                                                                                                                                                                                                                                                                                                                                      |
 | mission             | The free-form brief a model-driven participant receives: `actor.mission`. `actor.tasks[]` adds discrete tasks: each has a `goal` the participant sees and an optional `success` check it does not.                                                                                                                                                                                                                                                                                                                                    | `StudyActor` in `src/study/types.ts`                                                                                                                                                                                                                                                                                                                                                                        |
 | assignment          | What one participant was asked to do: the mission, a `participants` entry's `instruction` or the homogeneous `participants.instruction` (recorded as `focus`), and the tasks. Each stream records it as `streams[].assignment`.                                                                                                                                                                                                                                                                                                       | `participantAssignment` in `src/study/participant-assignment.ts`; `RunParticipantAssignment` in `src/run/streams.ts`                                                                                                                                                                                                                                                                                        |
-| scenario            | A scenario file, `humanish/scenarios/<id>.yaml` (`humanish.scenario.v1`): a goal and ordered steps with expectations. A scripted study names one in `scenario:`, and only the scripted route executes those steps. A v2 study file's `scenario` block held run settings (`mode`, `caps`, `ref`), which v3 moves to the top level. A model-driven participant follows its mission.                                                                                                                                                     | `StudyScenario` in `src/study/types.ts`; `src/routes/scripted/route.ts` resolves the scenario, and `executeBrowserPersonaStep` (`src/actors/scripted-browser/steps.ts`) runs each step                                                                                                                                                                                                                      |
+| scenario            | A scenario file, `humanish/scenarios/<id>.yaml` (`humanish.scenario.v1`): a goal and ordered steps with expectations. A scripted study names one in `scenario:`, and only the scripted route executes those steps. A v2 study file's `scenario` block held run settings (`mode`, `caps`, `ref`), which v3 moves to the top level. A model-driven participant follows its mission.                                                                                                                                                     | `scenario` in `StudyConfig` (`src/study/types.ts`); `src/routes/scripted/route.ts` resolves the scenario, and `executeBrowserPersonaStep` (`src/actors/scripted-browser/steps.ts`) runs each step                                                                                                                                                                                                           |
 | surface             | One browser viewport that a scripted run replays its journey on: `desktop` or `mobile`. A scripted study runs the desktop surface by default, and `surfaces: [desktop, mobile]` adds the mobile one. Each surface writes `actor-<surface>.json` and `traces/<surface>.json`.                                                                                                                                                                                                                                                          | `BrowserSurface` and `browserSurfaces` in `src/actors/scripted-browser/types.ts`; the plan's `surfaces` in `src/routes/scripted/plan.ts`                                                                                                                                                                                                                                                                    |
 | journey             | A scenario's `browser.steps` parsed into ordered steps with a goal and a start path. The scripted route replays it once on each surface, and each surface's session reports the first step that did not pass.                                                                                                                                                                                                                                                                                                                         | `BrowserPersonaJourney` in `src/actors/scripted-browser/types.ts`; `parseBrowserPersonaJourneyFromScenario` in `src/actors/scripted-browser/journey.ts`                                                                                                                                                                                                                                                     |
 | subject             | The product under study, declared by `subject.source`: `clone`, `app-url`, `local-tree`, `terminal-product`, `desktop-cli`, `local-app` or `this-repo`. `run.json` records its provenance under `subject`.                                                                                                                                                                                                                                                                                                                            | `StudySubject` in `src/study/types.ts`, parsed in `src/study/parse/subject.ts`                                                                                                                                                                                                                                                                                                                              |
@@ -33,7 +33,7 @@ bundle and output fields keep older spellings; the second table maps them.
 | participant desktop | The desktop one computer-use or shared-world participant drives: a substrate plus the route's concerns, such as subject provisioning, comms and the participant's plan. It lives in the route, so `src/substrates/` holds only provider primitives ([ADR 0004](docs/decisions/0004-participant-desktops-stay-in-the-route.md)).                                                                                                                                                                                                       | `ParticipantDesktop` in `src/routes/computer-use/participant-desktop.ts`; `createE2BParticipantDesktop` in `src/routes/computer-use/e2b-desktop/desktop.ts`; the local VM's in `src/routes/computer-use/local-vm.ts`                                                                                                                                                                                        |
 | receipt             | A line in a run's `sandbox-receipts.ndjson` that records a sandbox's id, provider, the participant or subject it belongs to (`laneId`), and its time limit as soon as the sandbox is created, before any work runs in it. `humanish reclaim` kills sandboxes by these ids after an interrupted run.                                                                                                                                                                                                                                   | `SandboxReceipt` in `src/run/sandbox-receipts.ts`; `reclaimRunSandboxes` in `src/run/reclaim.ts`                                                                                                                                                                                                                                                                                                            |
 | owner tags          | The E2B metadata every sandbox humanish creates carries: `tool: humanish`, the run's `runId`, and `runKey`, a digest of the run directory's inode and creation time. The run journals them in an owner line before its first create. `humanish reclaim` lists sandboxes that match all three, which finds one whose id never reached a receipt.                                                                                                                                                                                       | `sandboxOwnerTags` in `src/run/sandbox-creates.ts`; `findE2BSandboxesByTags` in `src/substrates/e2b/sandbox.ts`                                                                                                                                                                                                                                                                                             |
-| topology            | Whether participants share one instance of the subject. `route: shared-world` gives one for all; every other route gives each participant its own (`per-lane-worlds`). `run.json` records it as `sharedWorld.topology`.                                                                                                                                                                                                                                                                                                               | `StudySubjectTopology` in `src/study/types.ts`                                                                                                                                                                                                                                                                                                                                                              |
+| topology            | Whether participants share one instance of the subject. `route: shared-world` gives one for all; every other route gives each participant its own (`per-lane-worlds`). `run.json` records it as `sharedWorld.topology`.                                                                                                                                                                                                                                                                                                               | `declaresSharedWorld` in `src/study/study-fields.ts`                                                                                                                                                                                                                                                                                                                                                        |
 | plane               | The one instance of the subject that a shared-world study's participants use together. A `provisioned` plane is a `clone` or `local-tree` subject that humanish serves in a sandbox, with a declared subject state. An `external-public` plane is a deployment already running at `subject.appUrl`, whose owner the study names in `subject.publicTarget.owner`. Each plane has at least two participants.                                                                                                                            | `SharedWorldPlane` in `src/study/plan-types.ts`; `src/routes/shared-world/`                                                                                                                                                                                                                                                                                                                                 |
 | stream              | One live or recorded view of a participant, such as a browser or a terminal, in `run.json` and the Observer.                                                                                                                                                                                                                                                                                                                                                                                                                          | `RunStream` in `src/run/streams.ts`                                                                                                                                                                                                                                                                                                                                                                         |
 | Observer            | The single-file review page built from `observer/observer-data.json` (`humanish.observer-data.v1`).                                                                                                                                                                                                                                                                                                                                                                                                                                   | `observer/` (the page), `src/observer/` (data, render, serve)                                                                                                                                                                                                                                                                                                                                               |

package/dist/actors/local-agent/claude-session.js

@@ -1,6 +1,6 @@
 // One Claude Code process as the computer-use brain, instead of a fresh `claude -p` per turn.
 //
-// Why: `actors[].localAgent: codex` already runs through a persistent app-server thread,
+// Why: `actor.localAgent: codex` already runs through a persistent app-server thread,
 // so the participant remembers what it tried. `claude` spawned `claude -p` per turn, so every
 // turn started cold. Measured on the same study with the same credentials (n=1 each): one-shot,
 // 188 actions over 90 turns and never finished; a thread that remembers, 21 actions over 8 turns

package/dist/actors/local-agent/cli.js

@@ -3,7 +3,7 @@
 // mapping and JSON reading the two Claude Code paths share, and the one-shot Claude Code provider.
 //
 // A developer trying humanish often already has a coding agent signed in (Codex on a ChatGPT plan,
-// Claude Code on a Max plan), so `actors[0].type: local-agent` lets that agent decide the next
+// Claude Code on a Max plan), so `actor.type: local-agent` lets that agent decide the next
 // action instead of a provider API key. Codex runs as a restricted app-server participant
 // (actors/codex/restricted-participant.ts) and Claude Code as one session for the whole run
 // (claude-session.ts). The one-shot provider below spawns `claude -p` per turn, with no memory of

package/dist/actors/scripted-browser/actor.d.ts

@@ -8,11 +8,11 @@ export interface ScriptedBrowserSessionOptions {
     evidenceAppUrl?: string;
     /** Defaults to loopback. Provisioned subjects drive a private URL but persist redacted labels. */
     urlPolicy?: ScriptedBrowserEvidenceUrlPolicy;
-    /** Parsed + validated by the backend (scenario.ref is consumed there, fail-closed). */
+    /** Parsed + validated by the backend (`scenario` is consumed there, fail-closed). */
     journey: BrowserPersonaJourney;
     /** One session per surface. */
     surface: BrowserSurface;
-    /** id = actors[0].persona ?? "scripted-journey"; promptDigest = journey.sourceDigest prefix
+    /** id = actor.persona ?? "scripted-journey"; promptDigest = journey.sourceDigest prefix
      *  (the step manifest is the "prompt"; no model prompt exists on this route). */
     persona: ActorPersonaRef;
     /** Journey wall-clock budget in ms; the route passes execution.timeoutMs or 300_000. */

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 { actorOf } from "../../study/study-fields.js";
 export function registerStudyCommands(parent, io) {
     const study = parent
         .command("study")
@@ -114,7 +115,7 @@ 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(", ")}`,
+        `actor: ${actorOf(config)?.type ?? ""}`,
         ...(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/participant-model.js

@@ -84,7 +84,7 @@ export async function startParticipantModel(spec, deps, executor) {
 /** The options the participant's session runs with: prompt, model settings, spend caps and callbacks. */
 export function participantSessionOptions(spec, deps, ready, provider, writeScreenshot) {
     const { executor, inbox } = ready;
-    // The fail-closed spend cap (execution.caps.maxUsd) is wired into the loop as maxUsd + an
+    // The fail-closed spend cap (caps.maxUsd) is wired into the loop as maxUsd + an
     // injected pure per-turn estimator keyed on the resolved model. Preflight already refused a
     // cap on an unpriced model, so the estimate is measurable whenever a cap is in force. The
     // model id here matches provider.version (openai-responses-cu resolves the default when unset).

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

@@ -7,15 +7,16 @@ 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";
+import { cloneTargetValidationReason, computerUseValidationReason, desktopMediaValidationReason, outputTokenLimitValidationReason, receivingEmailValidationReason, taskProtocolValidationReason, } 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 { 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];
@@ -83,12 +84,10 @@ function cuaStudyRejection(config, hasRunSession, driving, subjectRoute) {
 }
 /** A declaration this route cannot honor, for any subject or with the caller's own driver. */
 function unsupportedDeclarationReason(config, hasRunSession, driving, { inProcessRoute }) {
-    const reason = desktopMediaValidationReason(config) ||
-        outputTokenLimitValidationReason(config) ||
-        scenarioCapsValidationReason(config);
+    const reason = desktopMediaValidationReason(config) || outputTokenLimitValidationReason(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);
@@ -176,7 +175,7 @@ function driverReason(driving, { localAppSubject, inProcessRoute }) {
 }
 /** The participant roster, then the sandbox deadline its session budget derives. */
 function rosterShapeReason(config) {
-    // `lanes` XOR `count`/`laneFocus`, device XOR raw resolution, cap, unique ids,
+    // Device XOR raw resolution, cap, unique ids,
     // allowPublicTargets with more than one participant, clone.fanout.
     const fanoutReason = computerUseValidationReason(config);
     if (fanoutReason)
@@ -220,7 +219,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 +230,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 +291,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),
             ...(input.rerun === undefined ? {} : { rerun: rerunPlan(input.rerun) }),
             requirements: base.dryRun || runner.desktop === "in-process"
                 ? []

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

@@ -59,7 +59,7 @@ export async function liveCuaRejection(args) {
         };
     }
     // Fail-closed cap: a maxUsd cap needs a measurable per-turn estimate.
-    // If the operator set execution.caps.maxUsd but src/run/pricing.ts has no rate for the resolved
+    // If the operator set caps.maxUsd but src/run/pricing.ts has no rate for the resolved
     // model, the loop could not enforce the cap, and silently running uncapped would break the
     // runaway-retry protection. Refuse at preflight (before any sandbox/spend) rather than run
     // uncapped: an unenforceable cap is more dangerous than none. The operator picks a priced model

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

@@ -193,7 +193,7 @@ function computerUseExecutionFailures(outcomes, runId) {
     ];
 }
 /**
- * execution.caps.maxUsd is enforced inside each participant's loop independently, so an
+ * caps.maxUsd is enforced inside each participant's loop independently, so an
  * N-participant fan-out can spend up to N × maxUsd before any participant aborts, while the run cost summary reports the larger
  * aggregate. The warning names that ceiling, unless the study declared a shared maxTotalUsd budget.
  */

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

@@ -1,6 +1,6 @@
 // The computer-use route: a subject (an app-url the caller provisioned, or a repo the
 // humanish clones and serves in the sandbox) driven by a registry-resolved computer-use actor inside a
-// hosted E2B desktop. On this path `actors[].type` selects the actor: the
+// hosted E2B desktop. On this path `actor.type` selects the actor: the
 // descriptor returned by the registry runs the session; the route provisions the desktop and
 // subject, composes the prompt from config, persists the evidence bundle, and tears down.
 //
@@ -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/computer-use/types.d.ts

@@ -52,8 +52,8 @@ export interface ComputerUseRunInput {
     cwd: string;
     open?: boolean;
     runId?: string;
-    /** CLI `--count` override for the homogeneous fan-out participant count (ignored when a `lanes`
-     *  roster is declared; a roster's length is authoritative). */
+    /** CLI `--count` override for the homogeneous fan-out participant count (ignored when a `participants`
+     *  list is declared; a roster's length is authoritative). */
     countOverride?: number;
     /** Explicitly create a new run containing failed or selected participants from a prior fan-out run. */
     rerun?: {
@@ -182,7 +182,7 @@ export interface CuaParticipantSummary {
     concurrency: number;
     waves: number;
 }
-export type CuaActorStudyErrorCode = "HUMANISH_STUDY_ANALYSIS_INVALID" | "HUMANISH_STUDY_TASKS_UNSUPPORTED" | "HUMANISH_STUDY_OPTION_UNSUPPORTED" | "HUMANISH_STUDY_V2_UNSUPPORTED" | "HUMANISH_COMPUTER_USE_FAILED" | "HUMANISH_COMPUTER_USE_KEYS_MISSING" | "HUMANISH_COMPUTER_USE_AGENT_MISSING" | "HUMANISH_COMPUTER_USE_AGENT_SIGNIN_REQUIRED" | "HUMANISH_COMPUTER_USE_SUBJECT_ENV_MISSING" | "HUMANISH_COMPUTER_USE_ACTOR_UNSUPPORTED" | "HUMANISH_COMPUTER_USE_SUBJECT_INVALID" | "HUMANISH_COMPUTER_USE_SUBJECT_UNSAFE" | "HUMANISH_COMPUTER_USE_EXECUTOR_NO_PROVIDER" | "HUMANISH_COMPUTER_USE_LOCAL_APP_NO_EXECUTOR" | "HUMANISH_COMPUTER_USE_LOCAL_DESKTOP_MISSING" | "HUMANISH_COMPUTER_USE_FANOUT_INVALID" | "HUMANISH_COMPUTER_USE_RERUN_INVALID" | "HUMANISH_COMPUTER_USE_DEVICE_GEOMETRY" | "HUMANISH_RUN_ID_IN_USE" | "HUMANISH_COMPUTER_USE_UNPRICED_CAP" | "HUMANISH_COMPUTER_USE_COMMS_CATCH_UNREACHABLE" | "HUMANISH_COMPUTER_USE_COMMS_TOKEN_INVALID" | "HUMANISH_WATCH_ALLOW_REQUIRES_OAUTH" | "HUMANISH_WATCH_OAUTH_REQUIRES_TUNNEL" | "HUMANISH_WATCH_OPTION_CONFLICT" | "HUMANISH_WATCH_TUNNEL_REQUIRES_EXPOSE" | "HUMANISH_WATCH_EXPOSE_REQUIRES_EDGE_AUTH" | "HUMANISH_WATCH_EXPOSE_REQUIRES_LIVE_FOLLOW" | "HUMANISH_WATCH_SAFE_NOT_APPLICABLE" | "HUMANISH_SERVE_TUNNEL_NOT_FOUND" | "HUMANISH_SERVE_TUNNEL_START_FAILED";
+export type CuaActorStudyErrorCode = "HUMANISH_STUDY_ANALYSIS_INVALID" | "HUMANISH_STUDY_TASKS_UNSUPPORTED" | "HUMANISH_STUDY_OPTION_UNSUPPORTED" | "HUMANISH_STUDY_V2_UNSUPPORTED" | "HUMANISH_STUDY_INVALID" | "HUMANISH_COMPUTER_USE_FAILED" | "HUMANISH_COMPUTER_USE_KEYS_MISSING" | "HUMANISH_COMPUTER_USE_AGENT_MISSING" | "HUMANISH_COMPUTER_USE_AGENT_SIGNIN_REQUIRED" | "HUMANISH_COMPUTER_USE_SUBJECT_ENV_MISSING" | "HUMANISH_COMPUTER_USE_ACTOR_UNSUPPORTED" | "HUMANISH_COMPUTER_USE_SUBJECT_INVALID" | "HUMANISH_COMPUTER_USE_SUBJECT_UNSAFE" | "HUMANISH_COMPUTER_USE_EXECUTOR_NO_PROVIDER" | "HUMANISH_COMPUTER_USE_LOCAL_APP_NO_EXECUTOR" | "HUMANISH_COMPUTER_USE_LOCAL_DESKTOP_MISSING" | "HUMANISH_COMPUTER_USE_FANOUT_INVALID" | "HUMANISH_COMPUTER_USE_RERUN_INVALID" | "HUMANISH_COMPUTER_USE_DEVICE_GEOMETRY" | "HUMANISH_RUN_ID_IN_USE" | "HUMANISH_COMPUTER_USE_UNPRICED_CAP" | "HUMANISH_COMPUTER_USE_COMMS_CATCH_UNREACHABLE" | "HUMANISH_COMPUTER_USE_COMMS_TOKEN_INVALID" | "HUMANISH_WATCH_ALLOW_REQUIRES_OAUTH" | "HUMANISH_WATCH_OAUTH_REQUIRES_TUNNEL" | "HUMANISH_WATCH_OPTION_CONFLICT" | "HUMANISH_WATCH_TUNNEL_REQUIRES_EXPOSE" | "HUMANISH_WATCH_EXPOSE_REQUIRES_EDGE_AUTH" | "HUMANISH_WATCH_EXPOSE_REQUIRES_LIVE_FOLLOW" | "HUMANISH_WATCH_SAFE_NOT_APPLICABLE" | "HUMANISH_SERVE_TUNNEL_NOT_FOUND" | "HUMANISH_SERVE_TUNNEL_START_FAILED";
 /** Subject provenance projection: what the actor actually drove. */
 export interface CuaSubjectProjection {
     source: "app-url" | "clone" | "local-tree";
@@ -385,7 +385,7 @@ export interface ParticipantModelDeps {
     artifactRoot: PreparedOutputRoot;
     redactScreenshots: boolean;
     scrubKnownValues: (text: string) => string;
-    /** The study's shared spend ledger, present exactly when execution.caps.maxTotalUsd is set on a
+    /** The study's shared spend ledger, present exactly when caps.maxTotalUsd is set on a
      *  live run. Preflight already refused the cap on an unpriced model. */
     runBudget?: CuaRunBudget;
     /**

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,