humanish 0.110.2 → 0.110.4

package/dist/evidence/redaction.js

@@ -58,6 +58,16 @@ const CREDENTIAL_PARAMETER = [
 // Upper-case variable names that hold a credential, as an env file, a shell or a JSON dump writes
 // them: GITHUB_TOKEN, VERCEL_TOKEN, AWS_SECRET_ACCESS_KEY, DATABASE_PASSWORD.
 const CREDENTIAL_VARIABLE = String.raw `\b(?:[A-Z][A-Z0-9_]{0,48}_)?(?:TOKEN|SECRET|SECRET_KEY|PASSWORD|PASSWD|API_KEY|APIKEY|ACCESS_KEY|PRIVATE_KEY)`;
+// The public E2B pages its errors link to, which name no sandbox and carry no credential: the
+// dashboard as the SDK's missing-key error names it (https://e2b.dev/dashboard?tab=keys), with no
+// path below /dashboard and no query but one short `tab`, and a docs page as the API's 401 names
+// it (https://docs.e2b.dev/api-key), whose path segments hold only letters and hyphens and which
+// has no query. Neither has user info, and only closing punctuation, ")" included, may follow
+// before the next space or the end of the text.
+const E2B_PUBLIC_PAGE = [
+    String.raw `(?:www\.)?e2b\.dev\/dashboard\/?(?:\?tab=[a-z]{1,16})?`,
+    String.raw `(?:docs\.e2b\.dev|(?:www\.)?e2b\.dev\/docs)(?:\/[a-z][a-z-]{0,39}){0,8}\/?`,
+].join("|");
 // A pattern that matches a credential by its context puts the context in a `keep` group, which
 // redaction leaves in place: `?token=[REDACTED_SECRET]`. Context goes in a group and not in a
 // lookbehind, because a pattern that starts with a lookbehind is tried at every position of the
@@ -106,10 +116,11 @@ const SECRET_PATTERNS = [
     // bounded, so a long run of `TOKEN=` costs linear time.
     new RegExp(String.raw `(?<keep>${CREDENTIAL_VARIABLE}${QUOTE}[ \t]{0,4}[:=][ \t]{0,4}${QUOTE})${notAPlaceholder(VARIABLE_END)}${NOT_A_NUMBER}(?=[^\s"'\\,;&]{0,255}[0-9])(?=[^\s"'\\,;&]{0,255}[A-Za-z])[^\s"'\\,;&]{16}[^\s"'\\,;&]*`, "g"),
     // Any URL on an E2B host: a sandbox host names its sandbox, and a stream URL carries its auth
-    // key. One URL is exempt: E2B's dashboard, as the SDK's missing-key error names it
-    // (https://e2b.dev/dashboard?tab=keys), with no userinfo, no path below /dashboard, no query but
-    // one short `tab`, and only closing punctuation before the next space or ")".
-    /(?!https:\/\/(?:www\.)?e2b\.dev\/dashboard\/?(?:\?tab=[a-z]{1,16})?[.,;:!?'"]*(?:[)\s]|$))https?:\/\/[^/\s]*e2b[^)\s]+/gi,
+    // key. The slashes may be JSON-escaped (`https:\/\/`). User info runs to its last `@`, as a URL
+    // parser reads it, and may hold any character but a slash or space. The host part stops at a
+    // backslash, quote or angle bracket, so a URL followed by an escaped line break and an `E2B_...`
+    // variable in JSON text is not read as an E2B host. A public page followed by `)@` is user info.
+    new RegExp(String.raw `(?!https:\/\/(?:${E2B_PUBLIC_PAGE})[.,;:!?'")]*(?:\s|$))https?:\\?\/\\?\/(?:[^/\s@]*@)*[^/\s\\"'<>@]*e2b[^)\s]+`, "gi"),
     /BEGIN (RSA|OPENSSH|PRIVATE) KEY/gi,
 ];
 const LOCAL_PATH_PATTERNS = [

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-runs.d.ts

@@ -3,7 +3,7 @@ import { type StudyConfig } from "../../study/types.js";
 import { type ResolvedPersona } from "../../study/persona.js";
 import { type RunRerunLineage } from "../../run/bundle.js";
 import type { PreparedSelectedOutputDirectory } from "../../run/contained-output.js";
-import { type CuaActorStudyErrorCode, type CuaParticipantPlan, type CuaParticipantPlanEntry, type DesktopParticipantRun } from "./types.js";
+import { type CuaActorStudyErrorCode, type CuaParticipantPlan, type CuaParticipantPlanEntry, type DesktopParticipantRun, type ParticipantRunsAndPlan } from "./types.js";
 export declare function defaultSessionTimeoutMs(config: StudyConfig): number;
 /** Per-participant sandbox deadline (each one owns its own desktop). Mirrors the
  *  single-participant formula verbatim so N=1 stays byte-stable: explicit sandboxTimeoutMs, else session budget + (clone
@@ -21,17 +21,14 @@ export declare function resolveParticipantSandboxMs(config: StudyConfig): number
  */
 export declare function boundedConcurrency(declared: number | undefined, participantCount: number): number;
 /**
- * Pure pre-flight plan resolver (runs in dry-run and live). Returns the participant table, the
- * effective concurrency, the wave count, the per-participant session budget, and the worst-case total
- * sandbox-minutes, before any sandbox or provider call. The same plan appears in dry-run,
- * marked $0 (dryRun: true).
+ * Build the participant runs and the public plan from a computer-use plan (pure). The same plan
+ * appears in dry-run and live, marked $0 for a dry run. `env` may lower the planned concurrency;
+ * `personas` are the compiled committed personas the prompts carry.
  */
-export declare function resolveCuaParticipantPlan(config: StudyConfig, opts?: {
-    countOverride?: number;
+export declare function participantRunsAndPlan(plan: ComputerUsePlan, opts?: {
     env?: Record<string, string | undefined>;
-    dryRun?: boolean;
     personas?: Map<string, ResolvedPersona>;
-}): CuaParticipantPlan;
+}): ParticipantRunsAndPlan;
 /** Print the participant plan to stderr before any sandbox/provider call (public-safe: ids, devices,
  *  digests, and budgets only; no prompt text, no secrets). */
 export declare function emitPreflightPlan(participantPlan: CuaParticipantPlan, studyId: string): void;

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

@@ -4,7 +4,6 @@
 // compiles the committed personas first and narrows a rerun to its selected participants.
 import { isLocalBrowserStudy, LOCAL_BROWSER_LIFETIME_MS, } from "../../substrates/local/runtime-config.js";
 import { DEFAULT_STATE_STEP_TIMEOUT_MS } from "../../subject/state.js";
-import { computerUseParticipants, } from "../../study/plan-participants.js";
 import { resolveParticipant } from "../../run/participant.js";
 import {} from "../../study/types.js";
 import { scrubPersonaBrief } from "../../study/persona.js";
@@ -71,23 +70,17 @@ function envLoweredConcurrency(planned, participantCount, env) {
     }
     return { bound: planned };
 }
-/** The same inputs from a config, for callers that have no plan. */
-function plannedParticipantsOf(config, countOverride) {
-    const participants = computerUseParticipants(config, countOverride);
-    return {
-        participants,
-        concurrency: boundedConcurrency(config.execution?.concurrency, participants.length),
-        sessionBudgetMs: config.execution?.timeoutMs ?? defaultSessionTimeoutMs(config),
-        sandboxMs: resolveParticipantSandboxMs(config),
-        desktopCli: config.subject.source === "desktop-cli",
-    };
-}
-/** Build the participant runs and the public plan from the planned participants (pure). */
-function participantRunsAndPlan(planned, opts = {}) {
+/**
+ * Build the participant runs and the public plan from a computer-use plan (pure). The same plan
+ * appears in dry-run and live, marked $0 for a dry run. `env` may lower the planned concurrency;
+ * `personas` are the compiled committed personas the prompts carry.
+ */
+export function participantRunsAndPlan(plan, opts = {}) {
     const env = opts.env ?? {};
     // Who each participant is (id, persona, focus, device, limits) comes from the plan; this adds
     // what the route derives from it: the prompt, bundle ids and artifact paths.
-    const { participants } = planned;
+    const { participants } = plan.runner;
+    const desktopCli = plan.runner.subject.kind === "desktop-cli";
     const participantCount = participants.length;
     const runs = participants.map((participant) => {
         const mission = participant.assignment.mission ?? DEFAULT_MISSION;
@@ -102,7 +95,7 @@ function participantRunsAndPlan(planned, opts = {}) {
             ...(resolvedPersona === undefined ? {} : { resolvedPersona }),
             ...(focus === undefined ? {} : { instruction: focus }),
             device: { name: device.name, preset: device.preset },
-            ...(planned.desktopCli ? { surface: "desktop-cli" } : {}),
+            ...(desktopCli ? { surface: "desktop-cli" } : {}),
         });
         const run = resolveParticipant(participant, {
             persona: composed.persona,
@@ -119,9 +112,9 @@ function participantRunsAndPlan(planned, opts = {}) {
             traceArtifactPath: participantCount === 1 ? "actor.json" : `actors/${run.streamId}.json`,
         };
     });
-    const resolved = envLoweredConcurrency(planned.concurrency, participantCount, env);
+    const resolved = envLoweredConcurrency(plan.concurrency, participantCount, env);
     const concurrency = resolved.bound;
-    const { sessionBudgetMs, sandboxMs } = planned;
+    const { sessionBudgetMs, sandboxMs } = plan;
     const participantPlan = {
         strategy: CUA_FANOUT_STRATEGY,
         laneCount: participantCount,
@@ -132,7 +125,7 @@ function participantRunsAndPlan(planned, opts = {}) {
         waves: Math.ceil(participantCount / concurrency),
         perLaneSessionBudgetMs: sessionBudgetMs,
         worstCaseSandboxMinutes: Math.round((participantCount * sandboxMs) / 60_000),
-        dryRun: opts.dryRun === true,
+        dryRun: plan.dryRun,
         lanes: runs.map((spec) => ({
             id: spec.planned.id,
             ...(spec.planned.labels.actorType === undefined
@@ -162,16 +155,6 @@ function participantRunsAndPlan(planned, opts = {}) {
     };
     return { runs, participantPlan };
 }
-/**
- * Pure pre-flight plan resolver (runs in dry-run and live). Returns the participant table, the
- * effective concurrency, the wave count, the per-participant session budget, and the worst-case total
- * sandbox-minutes, before any sandbox or provider call. The same plan appears in dry-run,
- * marked $0 (dryRun: true).
- */
-export function resolveCuaParticipantPlan(config, opts = {}) {
-    const { countOverride, ...rest } = opts;
-    return participantRunsAndPlan(plannedParticipantsOf(config, countOverride), rest).participantPlan;
-}
 /** Print the participant plan to stderr before any sandbox/provider call (public-safe: ids, devices,
  *  digests, and budgets only; no prompt text, no secrets). */
 export function emitPreflightPlan(participantPlan, studyId) {
@@ -216,13 +199,10 @@ export async function loadCuaParticipants(args) {
     // Compile any committed personas before planning, so the plan builder stays pure and each participant's
     // prompt carries real behavioral directives rather than a bare `Persona: <id>.` label.
     const personas = await compileParticipantPersonas(args.projectRoot, participants.map((participant) => participant.personaId));
-    const { runs: participantRuns, participantPlan } = participantRunsAndPlan({
-        participants,
-        concurrency: plan.concurrency,
-        sessionBudgetMs: plan.sessionBudgetMs,
-        sandboxMs: plan.sandboxMs,
-        desktopCli: plan.runner.subject.kind === "desktop-cli",
-    }, { env: args.env, dryRun: plan.dryRun, personas });
+    const { runs: participantRuns, participantPlan } = participantRunsAndPlan(plan, {
+        env: args.env,
+        personas,
+    });
     const rerun = plan.rerun;
     if (!rerun)
         return { ok: true, participantRuns, participantPlan };

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

@@ -1,7 +1,7 @@
 import { type CuaActorDescriptor } from "../../actors/registry.js";
 import type { ComputerUsePlan, ComputerUseRunner, RoutePlanResult, RouteRefusal } from "../../study/plan-types.js";
 import type { StudyConfig, StudySubjectState } from "../../study/types.js";
-import { type CuaActorStudyErrorCode, type RunCuaActorStudyOptions } from "./types.js";
+import { type ComputerUseRunInput, type CuaActorStudyErrorCode } from "./types.js";
 /** The error a computer-use study returns before a run starts. */
 export interface ComputerUseRefusal extends RouteRefusal<"computer-use", CuaActorStudyErrorCode> {
     /**
@@ -44,5 +44,5 @@ export declare function planComputerUseStudy(config: StudyConfig, input: {
     /** Which of the caller's driving homes are set; neither when absent. */
     readonly driving?: CallerDriving;
     readonly countOverride?: number;
-    readonly rerun?: RunCuaActorStudyOptions["rerun"];
+    readonly rerun?: ComputerUseRunInput["rerun"];
 }): ComputerUsePlanResult;

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,8 +232,8 @@ 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")
-        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. Run the study with runStudy or runConcurrentSharedWorld.", actor);
+    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.
     const source = config.subject.source;
@@ -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.d.ts

@@ -1,33 +1,20 @@
+import { type RefusedStudy } from "../../run/route-shell.js";
 import type { ComputerUsePlan } from "../../study/plan-types.js";
 import type { AdmittedPlan } from "../../run-study.js";
 import type { StudyConfig } from "../../study/types.js";
 import { type ComputerUseRefusal } from "./plan.js";
-import { type ComputerUseRunInput, type CuaActorStudyResult, type RunCuaActorStudyOptions } from "./types.js";
-/**
- * Plans and runs a computer-use study in one call. It is not exported from src/index.ts; tests call
- * it. It plans the config with planComputerUseStudy and runs
- * the plan with runComputerUsePlan, whose run scope and withTransientCommsSecrets wrapper cover the
- * run and its analysis.
- */
-export declare function runCuaActorStudy(options: RunCuaActorStudyOptions): Promise<CuaActorStudyResult>;
+import { type ComputerUseRunInput, type CuaActorStudyResult } from "./types.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
  * the personas are read.
  */
-export declare function computerUseStudyRefusal(options: RunCuaActorStudyOptions, refusal: ComputerUseRefusal): Promise<CuaActorStudyResult>;
+export declare function computerUseStudyRefusal(options: ComputerUseRunInput & RefusedStudy, refusal: ComputerUseRefusal): Promise<CuaActorStudyResult>;
 /**
  * runStudyWith's step for a computer-use plan. It runs the plan's local checks (admitCuaRun: the
  * participants, the preflight plan, the keys, the local agent, subject env and caps, and the
  * local-tree archive) before any run scope opens, so the CLI can present their refusal before it
- * loads a declared scorer, and returns the run that continues from them with that scorer.
+ * loads a declared scorer, and returns the run that continues from them with that scorer. The
+ * run and its analysis share one scope for the email secrets it registers.
  */
 export declare function admitComputerUsePlan(plan: ComputerUsePlan, input: ComputerUseRunInput, config: StudyConfig): Promise<AdmittedPlan<"computer-use">>;
-/**
- * Run a computer-use plan: its local checks, then the run. The run scope in runAdmittedCuaRun
- * finalizes any status record the run opened, on every exit, so a test or library caller does not
- * leave the 5 s status cadence writing into a directory something else is deleting (an unrelated
- * ENOTEMPTY). Participants, the brain, the subject, the caps and the residual config come from the
- * plan. `config` is what the caller's createProvider and inProcess executor receive.
- */
-export declare function runComputerUsePlan(plan: ComputerUsePlan, input: ComputerUseRunInput, config: StudyConfig): Promise<CuaActorStudyResult>;

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

@@ -21,39 +21,18 @@
 //   harness errors are redacted at this boundary; the bundle's `stream.actor` carries the
 //   conformant humanish.actor-trace.v1 projection, whose `redaction.screenshots` records the
 //   run's actual mode ("raw" | "blurred" | "n/a"), and every label downstream derives from it.
-import { withTransientCommsSecrets } from "../../run/transient-comms-secrets.js";
 import path from "node:path";
-import { completeAutomaticAnalysis } from "../../analysis/automatic-completion.js";
-import { runScope } from "../../run/run.js";
-import { resolveAutomaticAnalysis } from "../../analysis/automatic-config.js";
+import {} from "../../run/run.js";
+import { admitRoute, completeRefusalAnalysis } from "../../run/route-shell.js";
 import { browserRouteScorer } from "../../study/adapter-scorer-loader.js";
 import { withLateScorer } from "../../study/route-inputs.js";
-import { callerDrivingOf, planComputerUseStudy } from "./plan.js";
+import {} from "./plan.js";
 import { finishCuaRun } from "./result.js";
 import { runStudyParticipants } from "./live-phase.js";
 import { admitCuaRun, refuseCuaStudy, startCuaRun } from "./setup.js";
 import {} from "./types.js";
 import { studyResultIdentity } from "../../run/study-result.js";
-/**
- * Plans and runs a computer-use study in one call. It is not exported from src/index.ts; tests call
- * it. It plans the config with planComputerUseStudy and runs
- * the plan with runComputerUsePlan, whose run scope and withTransientCommsSecrets wrapper cover the
- * run and its analysis.
- */
-export async function runCuaActorStudy(options) {
-    const { config, dryRun, ...input } = options;
-    // planComputerUseStudy makes every configuration refusal, in the order this route always has.
-    const planned = planComputerUseStudy(config, {
-        dryRun,
-        hasRunSession: input.deps?.runSession !== undefined,
-        driving: callerDrivingOf(input),
-        ...(input.countOverride === undefined ? {} : { countOverride: input.countOverride }),
-        ...(input.rerun === undefined ? {} : { rerun: input.rerun }),
-    });
-    if (planned.ok)
-        return runComputerUsePlan(planned.plan, input, config);
-    return computerUseStudyRefusal(options, planned.refusal);
-}
+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
@@ -66,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 ?? "",
@@ -75,66 +54,27 @@ export async function computerUseStudyRefusal(options, refusal) {
             error: { code: refusal.code, message: refusal.message },
         };
     // The other refusals come after the cwd checks, and the participant cap after the personas are read.
-    const analysis = resolveAutomaticAnalysis(config.review?.analysis);
-    return completeAutomaticAnalysis(await refuseCuaStudy(options, refusal), undefined, analysis.ok ? analysis.config : undefined, options, { trigger: config.review?.analysis === undefined ? "default" : "explicit" });
+    return completeRefusalAnalysis(await refuseCuaStudy(options, refusal), config, options);
 }
 /**
  * runStudyWith's step for a computer-use plan. It runs the plan's local checks (admitCuaRun: the
  * participants, the preflight plan, the keys, the local agent, subject env and caps, and the
  * local-tree archive) before any run scope opens, so the CLI can present their refusal before it
- * loads a declared scorer, and returns the run that continues from them with that scorer.
- */
-export async function admitComputerUsePlan(plan, input, config) {
-    const admission = await admitCuaRun(plan, input, config);
-    if (!admission.ok)
-        return {
-            ok: false,
-            outcome: cuaOutcome(await completeCuaAnalysis(plan, input, admission.result, undefined)),
-        };
-    return {
-        ok: true,
-        run: async (scorer) => {
-            // The scorer joins the input only; the runSession, provider and desktop the checks admitted
-            // stay the ones the run uses.
-            const running = withLateScorer(input, scorer, browserRouteScorer);
-            return cuaOutcome(await runAdmittedCuaRun(plan, running, admission.admitted));
-        },
-    };
-}
-function cuaOutcome(result) {
-    return { route: "computer-use", result };
-}
-/**
- * Run a computer-use plan: its local checks, then the run. The run scope in runAdmittedCuaRun
- * finalizes any status record the run opened, on every exit, so a test or library caller does not
- * leave the 5 s status cadence writing into a directory something else is deleting (an unrelated
- * ENOTEMPTY). Participants, the brain, the subject, the caps and the residual config come from the
- * plan. `config` is what the caller's createProvider and inProcess executor receive.
- */
-export async function runComputerUsePlan(plan, input, config) {
-    const admission = await admitCuaRun(plan, input, config);
-    if (!admission.ok)
-        return completeCuaAnalysis(plan, input, admission.result, undefined);
-    return runAdmittedCuaRun(plan, input, admission.admitted);
-}
-/**
- * Runs an admitted plan in its own run scope, then its automatic analysis. The
- * withTransientCommsSecrets wrapper scopes any email secret the run registers to this run and its
- * analysis.
+ * loads a declared scorer, and returns the run that continues from them with that scorer. The
+ * run and its analysis share one scope for the email secrets it registers.
  */
-function runAdmittedCuaRun(plan, input, admitted) {
-    return withTransientCommsSecrets(async () => {
-        const { result, finished } = await runScope((scope) => runPlanInScope(plan, input, admitted, scope));
-        return completeCuaAnalysis(plan, input, result, finished);
-    });
-}
-function completeCuaAnalysis(plan, input, result, finished) {
+export function admitComputerUsePlan(plan, input, config) {
     // A local VM study whose cleanup is unconfirmed records a skip instead of analyzing.
-    const refusal = input.localVm?.analysisRefusal;
-    return completeAutomaticAnalysis(result, finished, plan.analysis?.config, input, {
-        ...(plan.analysis === undefined ? {} : { trigger: plan.analysis.trigger }),
-        preferLargerOutput: plan.analysis?.preferLargerOutput === true,
-        ...(refusal === undefined ? {} : { refusal }),
+    const analysisRefusal = input.localVm?.analysisRefusal;
+    return admitRoute({
+        route: "computer-use",
+        analysis: plan.analysis,
+        input,
+        admit: () => admitCuaRun(plan, input, config),
+        withScorer: (base, scorer) => withLateScorer(base, scorer, browserRouteScorer),
+        runInScope: (admitted, running, scope) => runPlanInScope(plan, running, admitted, scope),
+        ...(analysisRefusal === undefined ? {} : { analysisRefusal }),
+        commsSecrets: true,
     });
 }
 async function runPlanInScope(plan, input, admitted, scope) {

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

@@ -1,4 +1,5 @@
 import { type RunScope } from "../../run/run.js";
+import type { RefusedStudy } from "../../run/route-shell.js";
 import type { CuaActorDescriptor } from "../../actors/registry.js";
 import type { StudyCommsEmail, StudyCommsExternal, StudyConfig } from "../../study/types.js";
 import { type RunRerunLineage } from "../../run/bundle.js";
@@ -8,12 +9,12 @@ import type { ComputerUsePlan } from "../../study/plan-types.js";
 import { trackRuntimeStreams, type LiveTraceFlush } from "./live-flush.js";
 import { type CuaRunBundleBase } from "./bundle.js";
 import { projectParticipantSubjects } from "./subject-projection.js";
-import { type CuaActorStudyErrorCode, type CuaActorStudyResult, type CuaParticipantDeps, type CuaParticipantPlan, type DesktopParticipantRun, type CuaSubjectProjection, type CuaSubjectProvenanceArg, type ComputerUseRunInput, type RunCuaActorStudyOptions } from "./types.js";
+import { type CuaActorStudyErrorCode, type CuaActorStudyResult, type CuaParticipantDeps, type CuaParticipantPlan, type DesktopParticipantRun, type CuaSubjectProjection, type CuaSubjectProvenanceArg, type ComputerUseRunInput } from "./types.js";
 /**
  * The envelope of a refusal the plan left for after the cwd checks. The participant cap and
  * in-process fan-out refusals come after the committed personas are read, so a persona-file error still wins.
  */
-export declare function refuseCuaStudy(options: RunCuaActorStudyOptions, refusal: ComputerUseRefusal): Promise<CuaActorStudyResult>;
+export declare function refuseCuaStudy(options: ComputerUseRunInput & RefusedStudy, refusal: ComputerUseRefusal): Promise<CuaActorStudyResult>;
 export type AdmittedCuaRun = Extract<Awaited<ReturnType<typeof admitCuaRun>>, {
     ok: true;
 }>["admitted"];

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

@@ -19,7 +19,7 @@ import { type E2BDesktopModule } from "../../substrates/e2b/sdk.js";
 import { type DesktopResourceObservation } from "../../substrates/e2b/desktop-resources.js";
 import { type DetachedTimers } from "../../substrates/detached.js";
 import type { Brain, ComputerUsePlan, ComputerUseRunner, ResidualConfig } from "../../study/plan-types.js";
-import { type StudyCommsEmail, type StudyConfig } from "../../study/types.js";
+import { type StudyCommsEmail } from "../../study/types.js";
 import { type ObserverResult } from "../../observer/render.js";
 import { type BundleRun, type RunBundle, type RunRerunLineage, type RunScorerProvenance, type RunSubjectProvenance, type RunSubjectStateStepRecord } from "../../run/bundle.js";
 import { type RunDesktopGeometry } from "../../run/streams.js";
@@ -31,11 +31,6 @@ export declare const CUA_FANOUT_STRATEGY: "per-lane-worlds";
 export declare const CUA_MAX_CONCURRENCY_ENV = "HUMANISH_CUA_MAX_CONCURRENCY";
 export declare const DEFAULT_APP_URL_SESSION_TIMEOUT_MS: number;
 export declare const MIN_DERIVED_SESSION_TIMEOUT_MS: number;
-/**
- * What a computer-use run takes besides its plan and config. The count override and rerun go to
- * participant building with the config.
- */
-export type ComputerUseRunInput = Omit<RunCuaActorStudyOptions, "config" | "dryRun">;
 /**
  * What runStudyWith's local VM study gives a computer-use run: the desktop each participant runs on, the
  * reason automatic analysis must not run (the study's cleanup is unconfirmed), and the signal its
@@ -47,13 +42,14 @@ export interface LocalVmInput {
     readonly analysisRefusal: () => AutomaticAnalysisRefusal | undefined;
     readonly signal?: AbortSignal;
 }
-export interface RunCuaActorStudyOptions {
+/**
+ * What a computer-use run takes besides its plan and config. The count override and rerun go to
+ * participant building with the config.
+ */
+export interface ComputerUseRunInput {
     /** Cancels post-run analysis only. */
     analysisSignal?: AbortSignal;
     cwd: string;
-    config: StudyConfig;
-    /** Resolved upstream (scenario.mode + CLI override); defaults safe (dry-run). */
-    dryRun: boolean;
     open?: boolean;
     runId?: string;
     /** CLI `--count` override for the homogeneous fan-out participant count (ignored when a `lanes`

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.d.ts

@@ -1,28 +1,15 @@
 import type { ScriptedPlan } from "../../study/plan-types.js";
 import type { AdmittedPlan } from "../../run-study.js";
+import { type RefusedStudy } from "../../run/route-shell.js";
 import { type ScriptedRefusal } from "./plan.js";
-import { type RunScriptedBrowserStudyOptions, type ScriptedBrowserStudyResult, type ScriptedRunInput } from "./types.js";
-/**
- * The config-taking entry point. It plans, returns a refusal with the envelope the route has always
- * returned at that refusal's stage, and otherwise runs the plan.
- */
-export declare function runScriptedBrowserStudy(options: RunScriptedBrowserStudyOptions): Promise<ScriptedBrowserStudyResult>;
+import { type ScriptedBrowserStudyResult, type ScriptedRunInput } from "./types.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.
  */
-export declare function scriptedStudyRefusal(options: RunScriptedBrowserStudyOptions, refusal: ScriptedRefusal): Promise<ScriptedBrowserStudyResult>;
+export declare function scriptedStudyRefusal(options: ScriptedRunInput & RefusedStudy, refusal: ScriptedRefusal): Promise<ScriptedBrowserStudyResult>;
 /**
  * runStudyWith's step for a scripted plan. It takes no scorer, and its local checks (keys, a browser)
  * run inside the run, so it returns the run.
  */
-export declare function admitScriptedPlan(plan: ScriptedPlan, input: ScriptedRunInput): AdmittedPlan<"scripted">;
-/**
- * Run a scripted plan. The run scope gives a direct library caller the same status-record lifetime
- * the CLI gets: returning from this function finalizes any record the run opened, whichever of its
- * fail-closed exits it took. Each route opens its own scope; `runStudyWith` opens none. Without this a
- * test or an adopter calling the route directly leaves
- * the 5s cadence ticking into a directory something else is deleting, which surfaces as an
- * unrelated ENOTEMPTY.
- */
-export declare function runScriptedPlan(plan: ScriptedPlan, input: ScriptedRunInput): Promise<ScriptedBrowserStudyResult>;
+export declare function admitScriptedPlan(plan: ScriptedPlan, input: ScriptedRunInput): Promise<AdmittedPlan<"scripted">>;