humanish 0.106.1 → 0.107.0

package/dist/routes/computer-use/participant-runs.d.ts

@@ -5,8 +5,8 @@ import { type RunRerunLineage } from "../../run/bundle.js";
 import type { PreparedSelectedOutputDirectory } from "../../run/contained-output.js";
 import { type CuaActorLabErrorCode, type CuaParticipantPlan, type CuaParticipantPlanEntry, type DesktopParticipantRun } from "./types.js";
 export declare function defaultSessionTimeoutMs(config: LabConfig): number;
-/** Per-lane sandbox deadline (each lane owns its own desktop). Mirrors the single-lane formula
- *  verbatim so N=1 stays byte-stable: explicit sandboxTimeoutMs, else session budget + (clone
+/** 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
  *  or local-tree: provision budget + Σ state-step budgets) + the server-side
  *  reclamation buffer. Local-tree shares the clone route's provisioning budget: it swaps a
  *  git clone for an upload+extract, but the shared install/build/state/start/probe pipeline
@@ -21,8 +21,8 @@ export declare function resolveParticipantSandboxMs(config: LabConfig): number;
  */
 export declare function boundedConcurrency(declared: number | undefined, participantCount: number): number;
 /**
- * Pure pre-flight plan resolver (runs in dry-run AND live). Returns the lane table, the
- * effective concurrency, the wave count, the per-lane session budget, and the worst-case total
+ * 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).
  */
@@ -32,7 +32,7 @@ export declare function resolveCuaParticipantPlan(config: LabConfig, opts?: {
     dryRun?: boolean;
     personas?: Map<string, ResolvedPersona>;
 }): CuaParticipantPlan;
-/** Print the lane plan to stderr BEFORE any sandbox/provider call (public-safe: ids, devices,
+/** 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, labId: string): void;
 export declare function formatParticipantPlanEntry(entry: CuaParticipantPlanEntry): string;
@@ -63,5 +63,5 @@ export declare function loadCuaParticipants(args: {
     code: CuaActorLabErrorCode;
     message: string;
 }>;
-/** Scrub known secret values from each lane's declarative snapshot before any bundle uses it. */
+/** Scrub known secret values from each participant's declarative snapshot before any bundle uses it. */
 export declare function sanitizeParticipantRuns(runs: readonly DesktopParticipantRun[], scrub: (text: string) => string): void;

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

@@ -26,8 +26,8 @@ export function defaultSessionTimeoutMs(config) {
     const room = MAX_SANDBOX_MS - SUBJECT_PROVISION_BUDGET_MS - stateBudgetMs - SANDBOX_TIMEOUT_BUFFER_MS;
     return Math.max(MIN_DERIVED_SESSION_TIMEOUT_MS, Math.min(DEFAULT_APP_URL_SESSION_TIMEOUT_MS, room));
 }
-/** Per-lane sandbox deadline (each lane owns its own desktop). Mirrors the single-lane formula
- *  verbatim so N=1 stays byte-stable: explicit sandboxTimeoutMs, else session budget + (clone
+/** 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
  *  or local-tree: provision budget + Σ state-step budgets) + the server-side
  *  reclamation buffer. Local-tree shares the clone route's provisioning budget: it swaps a
  *  git clone for an upload+extract, but the shared install/build/state/start/probe pipeline
@@ -162,8 +162,8 @@ function participantRunsAndPlan(planned, opts = {}) {
     return { runs, participantPlan };
 }
 /**
- * Pure pre-flight plan resolver (runs in dry-run AND live). Returns the lane table, the
- * effective concurrency, the wave count, the per-lane session budget, and the worst-case total
+ * 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).
  */
@@ -171,11 +171,11 @@ export function resolveCuaParticipantPlan(config, opts = {}) {
     const { countOverride, ...rest } = opts;
     return participantRunsAndPlan(plannedParticipantsOf(config, countOverride), rest).participantPlan;
 }
-/** Print the lane plan to stderr BEFORE any sandbox/provider call (public-safe: ids, devices,
+/** 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, labId) {
     const lines = [];
-    lines.push(`humanish cua fan-out plan (${labId}): ${participantPlan.laneCount} participant(s), strategy ${participantPlan.strategy}, concurrency ${participantPlan.concurrency}${participantPlan.envLoweredConcurrencyFrom === undefined ? "" : ` (lowered from ${participantPlan.envLoweredConcurrencyFrom} by ${CUA_MAX_CONCURRENCY_ENV})`}, ${participantPlan.waves} wave(s).`);
+    lines.push(`humanish computer-use fan-out plan (${labId}): ${participantPlan.laneCount} participant(s), strategy ${participantPlan.strategy}, concurrency ${participantPlan.concurrency}${participantPlan.envLoweredConcurrencyFrom === undefined ? "" : ` (lowered from ${participantPlan.envLoweredConcurrencyFrom} by ${CUA_MAX_CONCURRENCY_ENV})`}, ${participantPlan.waves} wave(s).`);
     lines.push(`  session budget ${Math.round(participantPlan.perLaneSessionBudgetMs / 1000)}s per participant; worst-case ~${participantPlan.worstCaseSandboxMinutes} sandbox-minutes total${participantPlan.dryRun ? " (dry-run: $0)" : ""}.`);
     for (const entry of participantPlan.lanes) {
         lines.push(`  - ${formatParticipantPlanEntry(entry)}`);
@@ -212,7 +212,7 @@ export async function compileParticipantPersonas(projectRoot, personaIds) {
 export async function loadCuaParticipants(args) {
     const { plan } = args;
     const { participants } = plan.runner;
-    // Compile any committed personas BEFORE planning, so the plan builder stays pure and each lane's
+    // 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 (#381).
     const personas = await compileParticipantPersonas(args.projectRoot, participants.map((participant) => participant.personaId));
     const { runs: participantRuns, participantPlan } = participantRunsAndPlan({
@@ -244,7 +244,7 @@ export async function loadCuaParticipants(args) {
         rerunLineage: selected.rerun,
     };
 }
-/** Scrub known secret values from each lane's declarative snapshot before any bundle uses it. */
+/** Scrub known secret values from each participant's declarative snapshot before any bundle uses it. */
 export function sanitizeParticipantRuns(runs, scrub) {
     for (const spec of runs) {
         if (spec.evidenceAssignment)

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

@@ -1,14 +1,13 @@
 import { type CuaActorDescriptor } from "../../actors/registry.js";
-import type { ComputerUsePlan, RoutePlanResult, RouteRefusal } from "../../lab/plan-types.js";
-import type { LabConfig, LabSubjectServe, LabSubjectState } from "../../lab/types.js";
-import type { RunLabProvenance } from "../../run/status.js";
-import { type CuaActorLabErrorCode, type CuaActorLabHooks, type RunCuaActorLabOptions } from "./types.js";
+import type { ComputerUsePlan, ComputerUseRunner, RoutePlanResult, RouteRefusal } from "../../lab/plan-types.js";
+import type { LabConfig, LabSubjectState } from "../../lab/types.js";
+import { type CuaActorLabErrorCode, type RunCuaActorLabOptions } from "./types.js";
 /** The error a computer-use lab returns before a run starts. */
 export interface ComputerUseRefusal extends RouteRefusal<"computer-use", CuaActorLabErrorCode> {
     /**
      * Where the route returns it. "before-scope": analysis and tasks, returned before the run scope
      * with no automatic-analysis record. "in-scope": after the cwd checks. "after-personas": after
-     * the route reads committed persona files, so a persona-file error still wins over the lane cap
+     * the route reads committed persona files, so a persona-file error still wins over the participant cap
      * and in-process fan-out.
      */
     readonly stage: "before-scope" | "in-scope" | "after-personas";
@@ -18,39 +17,32 @@ export interface ComputerUseRefusal extends RouteRefusal<"computer-use", CuaActo
 export type ComputerUsePlanResult = RoutePlanResult<ComputerUsePlan, ComputerUseRefusal>;
 /** The registered descriptor for a planned actor id; planComputerUseLab checked the registry. */
 export declare function cuaDescriptorOf(actor: string): CuaActorDescriptor;
-/** Which subject route a computer-use lab takes, derived once from its config and hooks. */
-export interface CuaSubjectRoute {
-    cloneRoute: boolean;
-    /** A CLI studied at a desktop: nothing cloned, no browser, a terminal instead. */
-    desktopCliRoute: boolean;
-    localTreeRoute: boolean;
-    /**
-     * Clone and local-tree both provision the subject in-sandbox (clone via git, local-tree via
-     * pack+upload) and share the install/build/state/start/probe pipeline, so every seam that gates
-     * on "does this route provision a subject" is keyed on this union.
-     */
-    provisionedRoute: boolean;
-    localAppSubject: boolean;
-    /** A caller-supplied executor drives the subject in-process; no desktop is created. */
-    inProcessRoute: boolean;
-    serve: LabSubjectServe | undefined;
-    appUrl: string;
-    subjectRepo: string | undefined;
-    subjectEnvNames: string[];
+/** Which of the caller's driving homes, createProvider and inProcess, a run has. */
+export interface CallerDriving {
+    readonly inProcess: boolean;
+    readonly createProvider: boolean;
 }
-export declare function cuaSubjectRoute(config: LabConfig, hooks: CuaActorLabHooks): CuaSubjectRoute;
+/** The driving a computer-use run's options carry. */
+export declare function callerDrivingOf(options: {
+    readonly inProcess?: unknown;
+    readonly createProvider?: unknown;
+}): CallerDriving;
 /** The state a planned run's provisioned subject declares. Other subjects declare none. */
 export declare function cuaDeclaredState(plan: ComputerUsePlan): LabSubjectState | undefined;
-/** The route facts a planned run takes: its runner's desktop and subject. */
-export declare function cuaSubjectRouteOf(plan: ComputerUsePlan): CuaSubjectRoute;
+/** The URL a refused lab's result names, from its declaration: a provisioned subject's serve URL. */
+export declare function declaredAppUrl(config: LabConfig): string;
+/** The URL a planned run's participants open: a provisioned subject's served URL, else its own. */
+export declare function plannedAppUrl(subject: ComputerUseRunner["subject"]): string;
 /**
  * Plan a computer-use lab. It is called for any config handed to the computer-use runner, not only
  * one routeOf sends here, so a config for another route gets this route's refusal.
  */
 export declare function planComputerUseLab(config: LabConfig, input: {
     readonly dryRun: boolean;
-    readonly lab?: RunLabProvenance;
-    readonly hooks?: CuaActorLabHooks;
+    /** Whether deps.runSession is set: a caller's session runner cannot enforce maxOutputTokens. */
+    readonly hasRunSession?: boolean;
+    /** Which of the caller's driving homes are set; neither when absent. */
+    readonly driving?: CallerDriving;
     readonly countOverride?: number;
     readonly rerun?: RunCuaActorLabOptions["rerun"];
 }): ComputerUsePlanResult;

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

@@ -15,7 +15,6 @@ import { isLocalBrowserLab } 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 { participantDesktopOf } from "./participant-desktop.js";
 /** The registered descriptor for a planned actor id; planComputerUseLab checked the registry. */
 export function cuaDescriptorOf(actor) {
     const descriptor = actorRegistry[actor];
@@ -23,7 +22,7 @@ export function cuaDescriptorOf(actor) {
         throw new Error(`planned actor "${actor}" is not a registered computer-use actor`);
     return descriptor;
 }
-export function cuaSubjectRoute(config, hooks) {
+function declaredSubjectRoute(config, driving) {
     const cloneRoute = config.subject.source === "clone";
     const localTreeRoute = config.subject.source === "local-tree";
     const provisionedRoute = cloneRoute || localTreeRoute;
@@ -34,34 +33,36 @@ export function cuaSubjectRoute(config, hooks) {
         localTreeRoute,
         provisionedRoute,
         localAppSubject: config.subject.source === "local-app",
-        inProcessRoute: hooks.buildExecutor !== undefined,
+        inProcessRoute: driving.inProcess,
         serve,
         appUrl: (provisionedRoute ? serve?.url : config.subject.appUrl) ?? "",
         subjectRepo: cloneRoute ? (config.subject.repos?.[0] ?? "") : undefined,
         subjectEnvNames: provisionedRoute ? (config.subject.env ?? []) : [],
     };
 }
+/** The driving a computer-use run's options carry. */
+export function callerDrivingOf(options) {
+    return {
+        inProcess: options.inProcess !== undefined,
+        createProvider: options.createProvider !== undefined,
+    };
+}
 /** The state a planned run's provisioned subject declares. Other subjects declare none. */
 export function cuaDeclaredState(plan) {
     const { subject } = plan.runner;
     return subject.kind === "clone" || subject.kind === "local-tree" ? subject.state : undefined;
 }
-/** The route facts a planned run takes: its runner's desktop and subject. */
-export function cuaSubjectRouteOf(plan) {
-    const { desktop, subject } = plan.runner;
-    const provisioned = subject.kind === "clone" || subject.kind === "local-tree" ? subject : undefined;
-    return {
-        cloneRoute: subject.kind === "clone",
-        desktopCliRoute: subject.kind === "desktop-cli",
-        localTreeRoute: subject.kind === "local-tree",
-        provisionedRoute: provisioned !== undefined,
-        localAppSubject: subject.kind === "local-app",
-        inProcessRoute: desktop === "in-process",
-        serve: provisioned?.serve,
-        appUrl: provisioned?.serve.url ?? ("appUrl" in subject ? subject.appUrl : ""),
-        subjectRepo: subject.kind === "clone" ? subject.repo : undefined,
-        subjectEnvNames: [...(provisioned?.env ?? [])],
-    };
+/** The URL a refused lab's result names, from its declaration: a provisioned subject's serve URL. */
+export function declaredAppUrl(config) {
+    const { subject } = config;
+    const provisioned = subject.source === "clone" || subject.source === "local-tree";
+    return (provisioned ? subject.serve?.url : subject.appUrl) ?? "";
+}
+/** The URL a planned run's participants open: a provisioned subject's served URL, else its own. */
+export function plannedAppUrl(subject) {
+    if (subject.kind === "clone" || subject.kind === "local-tree")
+        return subject.serve.url;
+    return "appUrl" in subject ? subject.appUrl : "";
 }
 const invalid = (message) => ({
     code: "HUMANISH_CUA_LAB_SUBJECT_INVALID",
@@ -72,22 +73,22 @@ const invalid = (message) => ({
  * is touched. The parser enforces most of these too; the engine repeats them for library callers
  * that hand it a config directly. The groups run in this order, and each returns its first reason.
  */
-function cuaLabRejection(config, hooks, subjectRoute) {
-    return (unsupportedDeclarationReason(config, hooks, subjectRoute) ??
+function cuaLabRejection(config, hasRunSession, driving, subjectRoute) {
+    return (unsupportedDeclarationReason(config, hasRunSession, driving, subjectRoute) ??
         subjectStructureReason(config, subjectRoute) ??
         entryTargetReason(config, subjectRoute) ??
-        driverReason(config, hooks, subjectRoute) ??
+        driverReason(driving, subjectRoute) ??
         rosterShapeReason(config));
 }
 /** A declaration this route cannot honor, for any subject or with the caller's own driver. */
-function unsupportedDeclarationReason(config, hooks, { inProcessRoute }) {
+function unsupportedDeclarationReason(config, hasRunSession, driving, { inProcessRoute }) {
     const reason = desktopMediaValidationReason(config) ||
         outputTokenLimitValidationReason(config) ||
         scenarioCapsValidationReason(config);
     if (reason)
         return invalid(reason);
     if (config.actors[0]?.maxOutputTokens !== undefined &&
-        (hooks.runSession || hooks.buildProvider || hooks.buildExecutor))
+        (hasRunSession || driving.createProvider || driving.inProcess))
         return invalid("maxOutputTokens cannot be enforced by a custom runSession/provider/executor route.");
     const receivingReason = receivingEmailValidationReason(config);
     if (receivingReason)
@@ -151,14 +152,14 @@ function entryTargetReason(config, subjectRoute) {
             : "subject.appUrl and actors[0].lanes[].target entries must be valid http(s) URLs.",
     };
 }
-/** Something to drive the subject: the caller's executor with its provider, or a local desktop. */
-function driverReason(config, hooks, { localAppSubject, inProcessRoute }) {
+/** Something to drive the subject: the caller's executor with its provider. */
+function driverReason(driving, { localAppSubject, inProcessRoute }) {
     // A custom executor needs a custom provider too: the default OpenAI provider is vision-based
     // and would fail closed against an executor that returns no screenshot.
-    if (hooks.buildExecutor !== undefined && hooks.buildProvider === undefined)
+    if (driving.inProcess && !driving.createProvider)
         return {
             code: "HUMANISH_CUA_LAB_EXECUTOR_NO_PROVIDER",
-            message: "cuaHooks.buildExecutor requires cuaHooks.buildProvider — a state-driven executor returns no screenshot, so it must be paired with a NON-vision provider (the default OpenAI computer-use provider is vision-based and would fail closed).",
+            message: "RunLabOptions.inProcess requires RunLabOptions.createProvider — a state-driven executor returns no screenshot, so it must be paired with a NON-vision provider (the default OpenAI computer-use provider is vision-based and would fail closed).",
         };
     // There is no built-in in-process driver for a local app.
     if (localAppSubject && !inProcessRoute)
@@ -166,21 +167,12 @@ function driverReason(config, hooks, { localAppSubject, inProcessRoute }) {
             code: "HUMANISH_CUA_LAB_LOCAL_APP_NO_EXECUTOR",
             message: "subject.source: local-app has no built-in driver. Supply one through runLab(config, { inProcess: { executor }, createProvider }); a state-driven executor needs a non-vision provider.",
         };
-    // runLab gives a local browser study its desktop lane; a direct route call or an in-process
-    // executor on the same lab has none.
-    if (config.subject.source === "app-url" &&
-        config.execution?.target === "local" &&
-        participantDesktopOf(hooks) === undefined)
-        return {
-            code: "HUMANISH_CUA_LAB_LOCAL_DESKTOP_MISSING",
-            message: "An app-url lab with execution.target: local needs a local desktop. runLab starts one; a direct route call or an in-process executor does not.",
-        };
     return undefined;
 }
-/** The lane roster, then the sandbox deadline its session budget derives. */
+/** 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,
-    // allowPublicTargets with more than one lane, clone.fanout.
+    // `lanes` XOR `count`/`laneFocus`, device XOR raw resolution, cap, unique ids,
+    // allowPublicTargets with more than one participant, clone.fanout.
     const fanoutReason = cuaLaneValidationReason(config);
     if (fanoutReason)
         return { code: "HUMANISH_CUA_LAB_FANOUT_INVALID", message: fanoutReason };
@@ -195,12 +187,17 @@ function rosterShapeReason(config) {
     const headroomMs = derivedSandboxMs - sessionMs;
     return invalid(`execution.timeoutMs ${Math.round(sessionMs / 60_000)}m derives a ${Math.round(derivedSandboxMs / 60_000)}m sandbox deadline, and a sandbox may not live longer than ${MAX_SANDBOX_MS / 60_000}m. The deadline is the session budget plus ${Math.round(headroomMs / 60_000)}m of provisioning and teardown headroom${provisionedRoute ? " (this route clones, installs, builds and serves the subject before the actor starts)" : ""}. Lower execution.timeoutMs to at most ${Math.round((MAX_SANDBOX_MS - headroomMs) / 60_000)}m, or set execution.desktop.sandboxTimeoutMs explicitly.`);
 }
+/** The plan's rerun: the source run and, when given, the participants to rerun. */
+function rerunPlan({ sourceRunId, participantIds, }) {
+    return { sourceRunId, ...(participantIds === undefined ? {} : { participantIds }) };
+}
 /**
  * Plan a computer-use lab. It is called for any config handed to the computer-use runner, not only
  * one routeOf sends here, so a config for another route gets this route's refusal.
  */
 export function planComputerUseLab(config, input) {
-    const hooks = input.hooks ?? {};
+    const hasRunSession = input.hasRunSession === true;
+    const driving = input.driving ?? { inProcess: false, createProvider: false };
     const refuse = (stage, code, message, actor) => ({
         ok: false,
         refusal: {
@@ -223,10 +220,10 @@ export function planComputerUseLab(config, input) {
     if (!descriptor || !isCuaActorDescriptor(descriptor))
         return refuse("in-scope", "HUMANISH_CUA_LAB_ACTOR_UNSUPPORTED", `actors[0].type "${actorType}" is not a registered computer-use actor.`);
     const actor = descriptor.id;
-    const rejection = cuaLabRejection(config, hooks, cuaSubjectRoute(config, hooks));
+    const rejection = cuaLabRejection(config, hasRunSession, driving, declaredSubjectRoute(config, driving));
     if (rejection)
         return refuse("in-scope", rejection.code, rejection.message, actor);
-    // A shared world runs every seat against one app; this route would run them as separate lanes.
+    // A shared world runs every seat 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 runLab
     // sends here, still gets that rule's message.
     if (config.subject.topology === "shared-world")
@@ -234,9 +231,9 @@ export function planComputerUseLab(config, input) {
     // 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 lab declares.
     const source = config.subject.source;
-    if (hooks.buildExecutor !== undefined &&
+    if (driving.inProcess &&
         (source === "clone" || source === "local-tree" || source === "desktop-cli"))
-        return refuse("in-scope", "HUMANISH_CUA_LAB_SUBJECT_INVALID", `cuaHooks.buildExecutor drives subject.appUrl in this process, and a ${source} subject needs the hosted desktop the in-process route never creates. Use an app-url or local-app subject with buildExecutor, or remove buildExecutor to run on a hosted desktop.`, actor);
+        return refuse("in-scope", "HUMANISH_CUA_LAB_SUBJECT_INVALID", `RunLabOptions.inProcess drives subject.appUrl in this process, and a ${source} subject needs the hosted desktop the in-process route never creates. Use an app-url or local-app subject with inProcess, or remove inProcess to run on a hosted desktop.`, actor);
     // The parser's rule; without a product the desktop study fails later.
     const productReason = desktopCliProductReason(config);
     if (productReason)
@@ -245,22 +242,25 @@ export function planComputerUseLab(config, input) {
     if (participants.length > MAX_CUA_LANES)
         return refuse("after-personas", "HUMANISH_CUA_LAB_FANOUT_INVALID", `Computer-use fan-out is capped at ${MAX_CUA_LANES} participants (resolved ${participants.length}); N concurrent paid desktops is real spend.`, actor);
     const [first, ...rest] = participants;
-    if (hooks.buildExecutor !== undefined && rest.length > 0)
-        return refuse("after-personas", "HUMANISH_CUA_LAB_FANOUT_INVALID", "Fan-out to more than one participant is not supported on the in-process route (RunLabOptions.inProcess, or the deprecated cuaHooks.buildExecutor): fan-out provisions one independent E2B desktop per participant, which the in-process route deliberately skips. Run a single in-process participant, or fan out on the E2B route.", actor);
+    if (driving.inProcess && rest.length > 0)
+        return refuse("after-personas", "HUMANISH_CUA_LAB_FANOUT_INVALID", "Fan-out to more than one participant is not supported on the in-process route (RunLabOptions.inProcess): fan-out provisions one independent E2B desktop per participant, which the in-process route deliberately skips. Run a single in-process participant, or fan out on the E2B route.", actor);
     if (first === undefined)
         throw new Error("computerUseParticipants returned no participant");
     const appUrl = config.subject.appUrl ?? "";
+    const declaredServeUrl = config.subject.serve?.url;
+    const serveUrl = declaredServeUrl === undefined ? {} : { serveUrl: declaredServeUrl };
     const appUrlSubject = {
         kind: "app-url",
         appUrl,
         publicTargets: config.policies?.allowPublicTargets === true,
+        ...serveUrl,
     };
     const product = config.subject.product;
     const hosted = source === "desktop-cli" && product !== undefined
-        ? { kind: "desktop-cli", product }
+        ? { kind: "desktop-cli", product, ...serveUrl }
         : (provisionedSubject(config) ?? appUrlSubject);
-    const brain = brainOf(config, hooks.buildProvider !== undefined);
-    const runner = hooks.buildExecutor !== undefined
+    const brain = brainOf(config, driving.createProvider);
+    const runner = driving.inProcess
         ? {
             desktop: "in-process",
             brain: callerBrainOf(config),
@@ -275,7 +275,6 @@ export function planComputerUseLab(config, input) {
     const provisioned = source === "clone" || source === "local-tree";
     const base = planBase(config, {
         dryRun: input.dryRun,
-        ...(input.lab === undefined ? {} : { lab: input.lab }),
         analysis,
     });
     return {
@@ -289,18 +288,11 @@ export function planComputerUseLab(config, input) {
             sessionBudgetMs: config.execution?.timeoutMs ?? defaultSessionTimeoutMs(config),
             sandboxMs: resolveParticipantSandboxMs(config),
             caps: capsOf(config),
-            ...(input.rerun === undefined
-                ? {}
-                : {
-                    rerun: {
-                        sourceRunId: input.rerun.sourceRunId,
-                        ...(input.rerun.laneIds === undefined ? {} : { participantIds: input.rerun.laneIds }),
-                    },
-                }),
+            ...(input.rerun === undefined ? {} : { rerun: rerunPlan(input.rerun) }),
             requirements: base.dryRun || runner.desktop === "in-process"
                 ? []
                 : desktopRequirements(config, {
-                    e2b: runner.desktop === "e2b-desktop" && hooks.createDesktopLane === undefined,
+                    e2b: runner.desktop === "e2b-desktop",
                     brain,
                     localVm: runner.desktop === "local-vm",
                     externalCatch: !provisioned,

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

@@ -1,6 +1,6 @@
 import type { Brain, ComputerUsePlan } from "../../lab/plan-types.js";
 import type { LabCommsExternal } from "../../lab/types.js";
-import type { CuaActorLabErrorCode, CuaActorLabHooks } from "./types.js";
+import type { CuaActorLabErrorCode } from "./types.js";
 /**
  * The first reason a live computer-use run cannot start on this machine: missing keys, a missing
  * or signed-out local agent, missing subject env, a spend cap with no price, or an unreachable
@@ -11,11 +11,9 @@ export declare function liveCuaRejection(args: {
     caps: ComputerUsePlan["caps"];
     /** The plan's brain: whether a local agent drives the participant, and the model a cap prices. */
     brain: Brain;
-    hooks: CuaActorLabHooks;
     env: Record<string, string | undefined>;
-    openaiApiKey: string;
-    e2bApiKey: string;
-    subjectEnvNames: string[];
+    /** The plan's requirements: which keys and subject env names this run needs. */
+    requirements: ComputerUsePlan["requirements"];
     externalCommsConfig: LabCommsExternal | undefined;
 }): Promise<{
     code: CuaActorLabErrorCode;

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

@@ -1,10 +1,11 @@
 import { pricedModel } from "../../lab/plan-base.js";
+import { missingKeys, missingSubjectEnv } from "../../lab/requirements.js";
 import { detectLocalAgents } from "../../actors/local-agent/cli.js";
 import { localAgentRefusal } from "../../actors/local-agent/readiness.js";
 import { describeMissingKeys } from "../../keys/key-resolution.js";
+import { catchTokenOf, catchTokenRefusal } from "../../comms/external-evidence.js";
 import { externalCatchHealthy } from "../../comms/sandbox-catch.js";
 import { MODEL_RATES } from "../../run/pricing.js";
-import { participantDesktopOf } from "./participant-desktop.js";
 /** The computer-use code for each local-agent refusal; shared-world keeps the same kinds. */
 const LOCAL_AGENT_REFUSAL_CODES = {
     "agent-missing": "HUMANISH_CUA_LAB_AGENT_MISSING",
@@ -19,19 +20,16 @@ const LOCAL_AGENT_REFUSAL_CODES = {
  * already paid for a desktop.
  */
 export async function liveCuaRejection(args) {
-    const { caps, brain, hooks, env, openaiApiKey, e2bApiKey, subjectEnvNames, externalCommsConfig } = args;
-    // The operator's own signed-in coding agent is the brain, so there is no provider key to ask
-    // for. E2B is still required: the persona needs a machine.
+    const { caps, brain, env, requirements, externalCommsConfig } = args;
+    // The plan lists OPENAI_API_KEY only for an openai brain (a signed-in local agent or the
+    // caller's provider needs none) and E2B_API_KEY only when this run creates hosted desktops.
     const localAgent = brain.kind === "local-agent" ? brain.agent : undefined;
-    const missingKeys = [
-        ...(openaiApiKey || localAgent || hooks.buildProvider ? [] : ["OPENAI_API_KEY"]),
-        ...(e2bApiKey || participantDesktopOf(hooks) !== undefined ? [] : ["E2B_API_KEY"]),
-    ];
-    if (missingKeys.length > 0) {
+    const missing = missingKeys(requirements, env);
+    if (missing.length > 0) {
         // The moment someone new actually hits the wall. If a signed-in coding agent is sitting
         // right there, say so HERE rather than making them go and find an API key — that detour is
         // where most people trying humanish stop.
-        const suggestion = missingKeys.includes("OPENAI_API_KEY")
+        const suggestion = missing.includes("OPENAI_API_KEY")
             ? await (async () => {
                 const ready = (await detectLocalAgents({ env })).filter((agent) => agent.authStatus === "authenticated");
                 return ready.length === 0
@@ -42,21 +40,22 @@ export async function liveCuaRejection(args) {
             : "";
         return {
             code: "HUMANISH_CUA_LAB_KEYS_MISSING",
-            message: `Live computer-use labs need ${missingKeys.join(" and ")} in the environment (values are never persisted). ${describeMissingKeys(missingKeys, env)}${suggestion}`,
+            message: `Live computer-use labs need ${missing.join(" and ")} in the environment (values are never persisted). ${describeMissingKeys(missing, env)}${suggestion}`,
         };
     }
-    if (localAgent && !hooks.buildProvider) {
+    // A caller's createProvider makes the brain `caller`, so only the lab's own local agent is checked.
+    if (localAgent) {
         // Refuse HERE, before a sandbox exists. "codex is not installed" discovered after the
         // machine is paid for is the same information delivered at the worst possible moment.
         const refusal = await localAgentRefusal({ agent: localAgent, env, caps });
         if (refusal)
             return { code: LOCAL_AGENT_REFUSAL_CODES[refusal.kind], message: refusal.message };
     }
-    const missingSubjectEnv = subjectEnvNames.filter((name) => !env[name]?.trim());
-    if (missingSubjectEnv.length > 0) {
+    const unsetSubjectEnv = missingSubjectEnv(requirements, env);
+    if (unsetSubjectEnv.length > 0) {
         return {
             code: "HUMANISH_CUA_LAB_SUBJECT_ENV_MISSING",
-            message: `subject.env declares ${missingSubjectEnv.join(", ")} but the environment does not provide ${missingSubjectEnv.length === 1 ? "it" : "them"} (pass via --env-file; values are never persisted).`,
+            message: `subject.env declares ${unsetSubjectEnv.join(", ")} but the environment does not provide ${unsetSubjectEnv.length === 1 ? "it" : "them"} (pass via --env-file; values are never persisted).`,
         };
     }
     // FAIL-CLOSED CAP TENSION (discipline #3): a maxUsd cap needs a MEASURABLE per-turn estimate.
@@ -76,9 +75,14 @@ export async function liveCuaRejection(args) {
         }
     }
     // Adopter-hosted comms catch (#380): fail closed BEFORE any sandbox is created — a comms lab
-    // whose catch is unreachable collects nothing while every lane still spends. The probe asserts
+    // whose catch is unreachable collects nothing while every participant still spends. The probe asserts
     // OUR service marker in /health, so an adopter's proxy answering 200 for everything cannot
     // pass for a catch.
+    const tokenRefusal = externalCommsConfig === undefined
+        ? undefined
+        : catchTokenRefusal(catchTokenOf(externalCommsConfig, env));
+    if (tokenRefusal !== undefined)
+        return { code: "HUMANISH_CUA_LAB_COMMS_TOKEN_INVALID", message: tokenRefusal };
     if (externalCommsConfig && !(await externalCatchHealthy(externalCommsConfig))) {
         return {
             code: "HUMANISH_CUA_LAB_COMMS_CATCH_UNREACHABLE",

package/dist/routes/computer-use/rerun-selection.js

@@ -99,13 +99,17 @@ function snapshotPriorParticipant(stream) {
     const reason = stream.ui?.state ?? stream.actor?.reason;
     const actions = stream.actor?.counts.actions ?? 0;
     const messages = stream.actor?.counts.messages ?? 0;
+    // The judge's status decides, so a participant the review counts as blocked is rerunnable. A
+    // bundle written before streams carried it falls back to the trace status and counts.
     const hollow = completionReason === "goal_satisfied" && actions === 0 && messages === 0;
-    const rerunnable = stream.status !== "passed" ||
-        actorStatus === "failed" ||
-        actorStatus === "blocked" ||
-        actorStatus === "timed_out" ||
-        completionReason === "harness_error" ||
-        hollow;
+    const rerunnable = stream.judgedStatus !== undefined
+        ? stream.judgedStatus !== "passed"
+        : stream.status !== "passed" ||
+            actorStatus === "failed" ||
+            actorStatus === "blocked" ||
+            actorStatus === "timed_out" ||
+            completionReason === "harness_error" ||
+            hollow;
     return {
         participantId: stream.laneId,
         previous: {

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

@@ -1,4 +1,4 @@
-import type { runLabParticipants } from "./run-lanes.js";
+import type { runLabParticipants } from "./live-phase.js";
 import type { CuaFinishFacts, CuaRunSetup } from "./setup.js";
 import { type CuaActorLabResult } from "./types.js";
 /** Builds and publishes the final bundle, runs the adapter hooks, renders the Observer and returns the result. */