humanish 0.106.1 → 0.107.0

package/dist/routes/computer-use/{fanout-lanes.js → fanout-records.js}

@@ -4,6 +4,10 @@ import { participantAssignment } from "../../lab/participant-assignment.js";
 import { participantEvent, participantRecord, participantStream, } from "../../run/participant-records.js";
 import { declaredScreenForRender } from "../../substrates/e2b/desktop-geometry.js";
 import { describeSubjectState, phaseEventIdSuffix, publicSafeAppUrlLabel } from "./bundle-parts.js";
+import { judgedStatus } from "../../run/judge.js";
+import { participantFactsOf } from "./participant-facts.js";
+import { participantSubjectEnv } from "./types.js";
+const describeEnvNames = (names) => names.length > 0 ? names.join(", ") : "none";
 function fanoutParticipantView(args, spec, index) {
     const { outcomes, plan } = args;
     const outcome = outcomes?.[index];
@@ -77,14 +81,15 @@ function fanoutParticipantRecord(args, spec, index, view) {
                     : outcome?.sessionError !== undefined
                         ? `Participant ${spec.planned.id} failed before a terminal session verdict: ${outcome.sessionError}`
                         : `Contract participant ${spec.planned.id} (${spec.persona.id}/${spec.planned.device.name}) for ${args.descriptor.id} against ${publicTargetUrl}.`,
-        startedAt: args.createdAt,
-        updatedAt: args.createdAt,
+        startedAt: args.run.createdAt,
+        updatedAt: args.run.createdAt,
     });
 }
 function fanoutParticipantStream(args, spec, view) {
     const { plan } = args;
     const { outcome, publicTargetUrl, session, desktopGeometry, screenshots } = view;
     const { lastScreenshot, status, reason, screenshotMode } = view;
+    const judged = outcome === undefined ? undefined : judgedStatus(participantFactsOf(outcome));
     return participantStream(spec, {
         ...(spec.evidenceAssignment === undefined
             ? {}
@@ -101,8 +106,9 @@ function fanoutParticipantStream(args, spec, view) {
         kind: "browser",
         label: `CUA participant ${spec.planned.id}: ${plan.labId}`,
         status,
+        ...(judged === undefined ? {} : { judgedStatus: judged }),
         transport: "snapshot",
-        updatedAt: args.createdAt,
+        updatedAt: args.run.createdAt,
         embed: lastScreenshot
             ? {
                 kind: "screenshot",
@@ -174,11 +180,11 @@ function fanoutSubjectEvents(ctx, spec, view) {
     const { publicTargetUrl, subject, session } = view;
     const events = [];
     const record = (event) => events.push(participantEvent(spec, event));
-    // Per-lane subject provenance (invariant 5).
-    if (args.cloneRoute && args.publicRepo) {
+    // Per-participant subject provenance (invariant 5).
+    if (args.plan.runner.subject.kind === "clone" && args.publicRepo) {
         record({
             id: nextEventId(`subject-${spec.planned.id}`),
-            at: args.createdAt,
+            at: args.run.createdAt,
             level: "info",
             type: "cua-lab.subject.provenance",
             message: `Participant ${spec.planned.id}: ${args.dryRun
@@ -187,13 +193,13 @@ function fanoutSubjectEvents(ctx, spec, view) {
                     ? session
                         ? `subject cloned from ${args.publicRepo}@${subject.commit} and served at ${publicTargetUrl} in-sandbox`
                         : `subject cloned from ${args.publicRepo}@${subject.commit}; serving did not complete (see session error)`
-                    : `subject clone attempted from ${args.publicRepo}; commit unresolved`} (subject env names: ${args.subjectEnvNames.length > 0 ? args.subjectEnvNames.join(", ") : "none"}; values never persisted); state: ${describeSubjectState(subject.state, args.dryRun)}.`,
+                    : `subject clone attempted from ${args.publicRepo}; commit unresolved`} (subject env names: ${describeEnvNames(participantSubjectEnv(args.plan.runner.subject))}; values never persisted); state: ${describeSubjectState(subject.state, args.dryRun)}.`,
         });
     }
     else if (subject.source === "local-tree") {
         record({
             id: nextEventId(`subject-${spec.planned.id}`),
-            at: args.createdAt,
+            at: args.run.createdAt,
             level: "info",
             type: "cua-lab.subject.provenance",
             message: `Participant ${spec.planned.id}: ${args.dryRun
@@ -202,13 +208,13 @@ function fanoutSubjectEvents(ctx, spec, view) {
                     ? session
                         ? `subject packed (archiveSha256 ${subject.archiveSha256}${subject.dirty === true ? ", dirty working tree" : subject.dirty === false ? ", clean working tree" : ""}) and served at ${publicTargetUrl} in-sandbox`
                         : `subject packed (archiveSha256 ${subject.archiveSha256}); serving did not complete (see session error)`
-                    : "subject local-tree packing attempted; archive digest unresolved"} (subject env names: ${args.subjectEnvNames.length > 0 ? args.subjectEnvNames.join(", ") : "none"}; values never persisted); state: ${describeSubjectState(subject.state, args.dryRun)}.`,
+                    : "subject local-tree packing attempted; archive digest unresolved"} (subject env names: ${describeEnvNames(participantSubjectEnv(args.plan.runner.subject))}; values never persisted); state: ${describeSubjectState(subject.state, args.dryRun)}.`,
         });
     }
     else {
         record({
             id: nextEventId(`subject-${spec.planned.id}`),
-            at: args.createdAt,
+            at: args.run.createdAt,
             level: "info",
             type: "cua-lab.subject.declared",
             message: `Participant ${spec.planned.id}: subject app declared at ${publicTargetUrl} (loopback inside the participant's own desktop sandbox).`,
@@ -221,11 +227,11 @@ function fanoutOutcomeEvents(ctx, spec, view) {
     const { outcome, session, desktopGeometry } = view;
     const events = [];
     const record = (event) => events.push(participantEvent(spec, event));
-    // Per-lane session event.
+    // Per-participant session event.
     if (session) {
         record({
             id: nextEventId(`session-${spec.planned.id}`),
-            at: args.createdAt,
+            at: args.run.createdAt,
             level: session.status === "passed" ? "info" : "warn",
             type: `cua-lab.session.${session.completionReason}`,
             message: `Participant ${spec.planned.id} ${session.status}: ${session.reason}`,
@@ -234,7 +240,7 @@ function fanoutOutcomeEvents(ctx, spec, view) {
     else if (args.inProgress === true && outcome === undefined) {
         record({
             id: nextEventId(`running-${spec.planned.id}`),
-            at: args.createdAt,
+            at: args.run.createdAt,
             level: "info",
             type: "cua-lab.session.running",
             message: `Participant ${spec.planned.id}: live computer-use session is running; terminal evidence has not been written yet.`,
@@ -243,7 +249,7 @@ function fanoutOutcomeEvents(ctx, spec, view) {
     else if (outcome?.skippedReason !== undefined) {
         record({
             id: nextEventId(`blocked-${spec.planned.id}`),
-            at: args.createdAt,
+            at: args.run.createdAt,
             level: "warn",
             type: "cua-lab.session.blocked",
             message: `Participant ${spec.planned.id} ${outcome.skippedReason}.`,
@@ -252,7 +258,7 @@ function fanoutOutcomeEvents(ctx, spec, view) {
     else if (outcome?.sessionError !== undefined) {
         record({
             id: nextEventId(`session-error-${spec.planned.id}`),
-            at: args.createdAt,
+            at: args.run.createdAt,
             level: "error",
             type: "cua-lab.session.error",
             message: `Participant ${spec.planned.id}: ${outcome.sessionError}`,
@@ -261,7 +267,7 @@ function fanoutOutcomeEvents(ctx, spec, view) {
     else {
         record({
             id: nextEventId(`contract-${spec.planned.id}`),
-            at: args.createdAt,
+            at: args.run.createdAt,
             level: "info",
             type: "cua-lab.contract.ready",
             message: `Participant ${spec.planned.id}: dry-run contract participant ready; switch scenario.mode to live for a real desktop session.`,
@@ -270,14 +276,14 @@ function fanoutOutcomeEvents(ctx, spec, view) {
     for (const warning of desktopGeometry.warnings ?? []) {
         record({
             id: nextEventId(`geometry-warning-${spec.planned.id}`),
-            at: args.createdAt,
+            at: args.run.createdAt,
             level: "warn",
             type: "cua-lab.geometry.warning",
             message: warning,
         });
     }
-    // Persisted per-lane phase trail (real boot timing): one RunEvent per COMPLETED phase
-    // boundary this lane recorded (started events never persist here; they carry no durationMs).
+    // Persisted per-participant phase trail (real boot timing): one RunEvent per COMPLETED phase
+    // boundary this participant recorded (started events never persist here; they carry no durationMs).
     for (const phase of outcome?.phaseRecords ?? []) {
         record({
             id: nextEventId(`phase-${spec.planned.id}-${phaseEventIdSuffix(phase.type)}`),

package/dist/routes/computer-use/in-process-desktop.d.ts

@@ -1,14 +1,7 @@
-import type { CuaActorDescriptor } from "../../actors/registry.js";
-import type { LabConfig } from "../../lab/types.js";
 import type { ParticipantDesktop } from "./participant-desktop.js";
-import type { CuaActorLabHooks } from "./types.js";
-/** What an in-process desktop reads: the caller's executor hook and the arguments it receives. */
-interface InProcessDesktopDeps {
-    config: LabConfig;
-    descriptor: CuaActorDescriptor;
-    appUrl: string;
-    hooks: Pick<CuaActorLabHooks, "buildExecutor">;
-}
+import type { CuaParticipantDeps } from "./types.js";
+/** What an in-process desktop reads: the caller's executor and the app it drives. */
+type InProcessDesktopDeps = Pick<CuaParticipantDeps, "appUrl" | "inProcessExecutor">;
 /**
  * The caller's executor as a participant desktop. prepare acquires nothing; openSession builds the
  * executor once; finalize is idempotent and has nothing to release; snapshot records no sandbox.

package/dist/routes/computer-use/in-process-desktop.js

@@ -19,15 +19,9 @@ export function createInProcessDesktop(deps) {
             if (!preparationStarted || opened || finalization)
                 throw new Error("The participant desktop must be prepared and may only be opened once, before finalization.");
             opened = true;
-            const buildExecutor = deps.hooks.buildExecutor;
-            if (buildExecutor === undefined)
-                throw new Error("The in-process route needs hooks.buildExecutor.");
-            const executor = await buildExecutor({
-                config: deps.config,
-                actor: deps.descriptor,
-                appUrl: deps.appUrl,
-            });
-            return { executor };
+            if (deps.inProcessExecutor === undefined)
+                throw new Error("The in-process route needs RunLabOptions.inProcess.");
+            return { executor: await deps.inProcessExecutor(deps.appUrl) };
         },
         finalize() {
             return (finalization ??= Promise.resolve());

package/dist/routes/computer-use/live-flush.d.ts

@@ -2,7 +2,8 @@ import type { ActorTokenUsage, ActorTraceItem } from "../../actors/contract.js";
 import type { CuaLiveMetadata } from "../../actors/computer-use/loop.js";
 import { type ObserverResult } from "../../observer/render.js";
 import type { RunBundle } from "../../run/bundle.js";
-import type { CuaActorLabHooks, DesktopParticipantRun } from "./types.js";
+import type { RunLabHomes } from "../../lab/run-lab-homes.js";
+import type { DesktopParticipantRun } from "./types.js";
 export interface LiveTraceFlush {
     /** Record a participant's recorded-so-far items; the bundle rewrite follows on the flush
      *  schedule. */
@@ -11,7 +12,7 @@ export interface LiveTraceFlush {
     stop: () => Promise<void>;
 }
 /**
- * Incremental live flush (#441): as each lane's loop reports its recorded-so-far items,
+ * Incremental live flush (#441): as each participant's loop reports its recorded-so-far items,
  * rewrite the in-progress bundle with per-stream `liveActor` partials so the attached
  * Observer's 5s poll sees the timeline grow. Throttled (one write per interval, trailing
  * write guaranteed). `write` is the run's `writeSnapshot`, which serializes writes and refuses
@@ -27,12 +28,13 @@ export declare function startLiveTraceFlush(args: {
     write: (bundle: RunBundle) => Promise<void>;
 }): LiveTraceFlush;
 /**
- * The live desktop views (runtime stream URLs) lanes report, attached to whichever Observer shows
+ * The live desktop views (runtime stream URLs) participants report, attached to whichever Observer shows
  * the run. The URLs carry auth, so they live in memory and on the Observer result, never in run
  * artifacts.
  */
-export declare function trackRuntimeStreams(hooks: CuaActorLabHooks): {
-    hooks: CuaActorLabHooks;
+export declare function trackRuntimeStreams(onStream: RunLabHomes["onStream"] | undefined): {
+    /** Records each stream for the Observer, after the caller's onStream. */
+    onStream: NonNullable<RunLabHomes["onStream"]>;
     /** From now on, keep this live Observer's stream list current. */
     showIn: (observer: ObserverResult & {
         ok: true;

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

@@ -1,8 +1,7 @@
 import { attachObserverRuntimeStreamUrls } from "../../observer/render.js";
 import {} from "../../observer/run-routes.js";
-import { HOOK_MEMBERS, withHookOverrides } from "../../lab/bag-overrides.js";
 /**
- * Incremental live flush (#441): as each lane's loop reports its recorded-so-far items,
+ * Incremental live flush (#441): as each participant's loop reports its recorded-so-far items,
  * rewrite the in-progress bundle with per-stream `liveActor` partials so the attached
  * Observer's 5s poll sees the timeline grow. Throttled (one write per interval, trailing
  * write guaranteed). `write` is the run's `writeSnapshot`, which serializes writes and refuses
@@ -12,12 +11,12 @@ import { HOOK_MEMBERS, withHookOverrides } from "../../lab/bag-overrides.js";
 export function startLiveTraceFlush(args) {
     const { bundle, participantRuns, model, write } = args;
     const streamIdByParticipant = new Map(participantRuns.map((spec) => [spec.planned.id, spec.streamId]));
-    // The persona each lane is running, so the live flush can say who is in it.
+    // The persona each participant is running, so the live flush can say who is in it.
     const personaByStream = new Map(participantRuns
         .map((spec) => [spec.streamId, spec.persona?.id])
         .filter((entry) => typeof entry[1] === "string"));
     const liveItemsByStream = new Map();
-    // Running token usage per lane, so a run in flight can price itself instead of reporting the
+    // Running token usage per participant, so a run in flight can price itself instead of reporting the
     // cost as unknown until the moment it ends.
     const liveUsageByStream = new Map();
     const liveMetadataByStream = new Map();
@@ -43,8 +42,8 @@ export function startLiveTraceFlush(args) {
                             liveActor: {
                                 schema: "humanish.live-actor.v1",
                                 updatedAt,
-                                // WHO is in this lane, carried while the run is live. Without it a surface
-                                // watching a live run can only name the lane, and "CUA browser — observer-live-
+                                // WHO this participant is, carried while the run is live. Without it a
+                                // surface watching a live run can only name the participant id, and "CUA browser — observer-live-
                                 // check" is the harness talking about itself where the participant should be.
                                 ...(personaByStream.get(stream.id) === undefined
                                     ? {}
@@ -114,34 +113,27 @@ export function startLiveTraceFlush(args) {
     return { flush, stop };
 }
 /**
- * The live desktop views (runtime stream URLs) lanes report, attached to whichever Observer shows
+ * The live desktop views (runtime stream URLs) participants report, attached to whichever Observer shows
  * the run. The URLs carry auth, so they live in memory and on the Observer result, never in run
  * artifacts.
  */
-export function trackRuntimeStreams(hooks) {
+export function trackRuntimeStreams(onStream) {
     let liveObserver;
     const urls = [];
     return {
-        // The caller's bag may be a class instance, so it is wrapped rather than spread.
-        hooks: withHookOverrides(hooks, HOOK_MEMBERS.cua, {
-            onRuntimeStreamReady: async (stream) => {
-                await hooks.onRuntimeStreamReady?.(stream);
-                urls.push({ streamId: stream.streamId, url: stream.url });
-                if (liveObserver)
-                    attachObserverRuntimeStreamUrls(liveObserver, urls);
-            },
-            onRuntimeStreamEnded: async (stream) => {
-                await hooks.onRuntimeStreamEnded?.(stream);
-                // Mark, never remove: the tile needs to KNOW the live view ended (and say so) rather than
-                // have the stream silently vanish from the overlay (#357).
-                for (const entry of urls) {
-                    if (entry.streamId === stream.streamId)
+        onStream: async (event) => {
+            await onStream?.(event);
+            if (event.type === "ready")
+                urls.push({ streamId: event.streamId, url: event.url });
+            // Mark, never remove: the tile needs to KNOW the live view ended (and say so) rather than
+            // have the stream silently vanish from the overlay (#357).
+            else
+                for (const entry of urls)
+                    if (entry.streamId === event.streamId)
                         entry.ended = true;
-                }
-                if (liveObserver)
-                    attachObserverRuntimeStreamUrls(liveObserver, urls);
-            },
-        }),
+            if (liveObserver)
+                attachObserverRuntimeStreamUrls(liveObserver, urls);
+        },
         showIn: (observer) => {
             liveObserver = observer;
         },

package/dist/routes/computer-use/{run-lanes.js → live-phase.js}

@@ -1,23 +1,24 @@
 // The computer-use run's live phase: the in-progress bundle and its live-trace flush, email
-// receiving, the lanes themselves, and the drain of an operator-hosted inbox.
+// receiving, the participants themselves, and the drain of an operator-hosted inbox.
 import { prepareReceivingRun } from "../../comms/receiving-runtime.js";
 import { liveObserverResult } from "../../observer/live.js";
 import { pricedModel } from "../../lab/plan-base.js";
-import { runAllCuaParticipants } from "./lanes.js";
+import { runAllCuaParticipants } from "./participant-execution.js";
 import { startLiveTraceFlush } from "./live-flush.js";
 import { drainExternalComms } from "./external-comms.js";
 import { buildCuaRunBundle, judgeComputerUseRun } from "./bundle.js";
-import {} from "./types.js";
+import { participantSubjectEnv } from "./types.js";
 /**
  * Runs the participants (a dry run runs none). Returns the refusal when real email setup fails, or
  * the participant outcomes and the warnings the finish records.
  */
 export async function runLabParticipants(setup, participants) {
-    const { plan, input, cwd, streams, descriptor, subjectRoute, run } = setup;
-    const { participantRuns, participantPlan, scrubKnownValues, bundleBase } = setup;
+    const { plan, input, cwd, streams, descriptor, run } = setup;
+    const { participantRuns, participantPlan, bundleBase } = setup;
     const { env, knownSecretValues, deps, liveTrace, externalComms, inProgress, fail } = participants;
     const { dryRun } = plan;
-    const { inProcessRoute, subjectEnvNames } = subjectRoute;
+    const inProcess = plan.runner.desktop === "in-process";
+    const subjectEnvNames = [...participantSubjectEnv(plan.runner.subject)];
     const { runId, paths: runPaths } = run;
     // A live run writes what it is doing AS IT DOES IT, whether or not anyone is currently watching.
     // This used to be gated on `options.onObserverReady` — the interactive Observer callback — so a
@@ -46,7 +47,7 @@ export async function runLabParticipants(setup, participants) {
         streams.showIn(liveObserver);
         if (input.onObserverReady)
             await input.onObserverReady(liveObserver);
-        // Incremental live flush (#441): as each lane's loop reports its recorded-so-far items,
+        // Incremental live flush (#441): as each participant's loop reports its recorded-so-far items,
         // rewrite the in-progress bundle with per-stream `liveActor` partials so the attached
         // Observer's 5s poll sees the timeline grow. The run refuses any snapshot once the final
         // write began; the route stops the flush timer on every exit below.
@@ -96,12 +97,12 @@ export async function runLabParticipants(setup, participants) {
             };
         }
     }
-    // Run lanes (dry-run runs none). In-process is always one lane.
+    // Run the participants (dry-run runs none). In-process is always one.
     let outcomes;
     let failFastReason;
     try {
         if (!dryRun)
-            ({ outcomes, failFastReason } = await runAllCuaParticipants(participantRuns, deps, participantPlan, inProcessRoute));
+            ({ outcomes, failFastReason } = await runAllCuaParticipants(participantRuns, deps, participantPlan, inProcess));
     }
     finally {
         try {
@@ -110,7 +111,7 @@ export async function runLabParticipants(setup, participants) {
         catch {
             receivingWarnings.push("Email finalization could not complete. Inspect humanish comms recover; provider cleanup remains unresolved.");
         }
-        // Stop the flush timer on every exit, including a throw from the lanes.
+        // Stop the flush timer on every exit, including a throw from the participants.
         await liveTrace.stop?.();
     }
     const externalCommsWarnings = !dryRun && externalComms && outcomes !== undefined
@@ -121,7 +122,7 @@ export async function runLabParticipants(setup, participants) {
             runPaths,
             participantRuns: participantRuns,
             outcomes,
-            scrubKnownValues,
+            knownSecretValues,
         })
         : [];
     return {

package/dist/routes/computer-use/local-tree-pack.d.ts

@@ -1,11 +1,11 @@
 import type { LabConfig } from "../../lab/types.js";
 import { type LocalTreeArchive } from "../../subject/local-tree-archive.js";
-import { type CuaActorLabHooks } from "./types.js";
+import type { LabDeps } from "../../lab/lab-deps.js";
 /**
  * Pack the working tree for a local-tree run and report what left the host on stderr, by counts
  * and digest only, never paths or file names.
  */
-export declare function packRunLocalTree(hooks: CuaActorLabHooks, config: {
+export declare function packRunLocalTree(deps: LabDeps, config: {
     readonly subject: Pick<LabConfig["subject"], "localTree">;
 }, cwd: string): Promise<{
     archive: LocalTreeArchive;
@@ -14,7 +14,7 @@ export declare function packRunLocalTree(hooks: CuaActorLabHooks, config: {
 /**
  * Default local-tree packing implementation: createLocalTreeArchive(root, opts) on the host,
  * then a single read of the produced archive file into an ArrayBuffer for upload. The DI seam
- * (CuaActorLabHooks.packLocalTree) overrides this in deterministic tests so they never require
+ * (LabDeps.packLocalTree) overrides this in deterministic tests so they never require
  * tar/git.
  */
 export declare function defaultPackLocalTree(args: {

package/dist/routes/computer-use/local-tree-pack.js

@@ -1,14 +1,13 @@
-// Packing the project's working tree once per local-tree run, on the host, for every lane to upload.
+// Packing the project's working tree once per local-tree run, on the host, for every participant to upload.
 import { readFile, rm } from "node:fs/promises";
 import path from "node:path";
 import { createLocalTreeArchive } from "../../subject/local-tree-archive.js";
-import {} from "./types.js";
 /**
  * Pack the working tree for a local-tree run and report what left the host on stderr, by counts
  * and digest only, never paths or file names.
  */
-export async function packRunLocalTree(hooks, config, cwd) {
-    const packLocalTree = hooks.packLocalTree ?? defaultPackLocalTree;
+export async function packRunLocalTree(deps, config, cwd) {
+    const packLocalTree = deps.packLocalTree ?? defaultPackLocalTree;
     const packed = await packLocalTree({
         root: cwd,
         ...(config.subject.localTree?.exclude === undefined
@@ -25,7 +24,7 @@ export async function packRunLocalTree(hooks, config, cwd) {
 /**
  * Default local-tree packing implementation: createLocalTreeArchive(root, opts) on the host,
  * then a single read of the produced archive file into an ArrayBuffer for upload. The DI seam
- * (CuaActorLabHooks.packLocalTree) overrides this in deterministic tests so they never require
+ * (LabDeps.packLocalTree) overrides this in deterministic tests so they never require
  * tar/git.
  */
 export async function defaultPackLocalTree(args) {

package/dist/routes/computer-use/local-vm.d.ts

@@ -1,20 +1,23 @@
-import type { RunLabOptions } from "../../run-lab.js";
+import type { InternalRunLabOptions } from "../../run-lab.js";
 import type { LabConfig } from "../../lab/types.js";
+import type { LocalVmInput } from "./types.js";
 import { type LocalFirecrackerAssets } from "../../substrates/local/firecracker-desktop.js";
-type LocalStudyOptions = RunLabOptions & {
+type LocalVmRunOptions = InternalRunLabOptions & {
     config: LabConfig;
     assets?: LocalFirecrackerAssets;
     signal?: AbortSignal;
 };
-/** A local browser study's bindings, and the cleanup of what its lanes started. */
-export interface LocalVmStudy {
-    /** The caller's runLab options with this study's desktop lane, provider and abort signal. */
-    readonly options: RunLabOptions;
+/** A local browser study's bindings, and the cleanup of what its participants started. */
+export interface LocalVmRun {
+    /** The caller's runLab options, with the account provider when the study runs one. */
+    readonly options: InternalRunLabOptions;
+    /** The desktop, the analysis gate and the abort signal the computer-use run takes. */
+    readonly localVm: LocalVmInput;
     close(): Promise<void>;
 }
 /**
  * Local desktop/provider composition: the options the lab is planned and run with. It throws before
- * anything starts on a lab the local study cannot run, or on a hook only an E2B desktop calls.
+ * anything starts on a lab the local study cannot run.
  */
-export declare function prepareLocalVmStudy(options: LocalStudyOptions): LocalVmStudy;
+export declare function prepareLocalVmRun(options: LocalVmRunOptions): LocalVmRun;
 export {};

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

@@ -1,30 +1,16 @@
 import { collectDesktopRecording } from "../../evidence/desktop-recording-artifact.js";
 import path from "node:path";
-import { inboxRecipientFor, PARTICIPANT_DESKTOP, } from "./participant-desktop.js";
-import { HOOK_MEMBERS, withHookOverrides } from "../../lab/bag-overrides.js";
-import { runCuaActorSession } from "../../actors/computer-use/actor.js";
+import { inboxRecipientFor, } from "./participant-desktop.js";
 import { createLocalFirecrackerDesktop, } from "../../substrates/local/firecracker-desktop.js";
 import { localBrowserDefaults, localBrowserUnsupportedReason, } from "../../substrates/local/runtime-config.js";
 import { prepareLocalRuntime } from "../../substrates/local/runtime.js";
+import { dockerCommandLine } from "../../substrates/local/runtime-host.js";
 import { checkRestrictedCodexAnalysisReadiness } from "../../analysis/restricted-codex.js";
 import { createRestrictedCodexParticipant } from "../../actors/codex/restricted-participant.js";
+import { withCloseReport } from "./participant-model.js";
 import { guestMediaConfigSchema } from "../../guest/media-config.js";
 import { startLocalCapturedInbox } from "../../substrates/local/captured-inbox.js";
-// These hooks act on an E2B desktop or the local-tree upload to it. The study runs on a
-// Firecracker desktop and never calls them, so a caller relying on one gets an error up front.
-const e2bDesktopHooks = [
-    "prepareDesktop",
-    "loadDesktopModule",
-    "onRuntimeStreamReady",
-    "packLocalTree",
-];
-function refuseE2BDesktopHooks(hooks) {
-    const present = e2bDesktopHooks.filter((name) => hooks?.[name] !== undefined);
-    if (present.length === 0)
-        return;
-    throw new Error(`A local browser study runs on a Firecracker desktop and does not call ${present.map((name) => `cuaHooks.${name}`).join(", ")}. These hooks apply only to E2B desktops.`);
-}
-function studyMedia(config) {
+function guestMedia(config) {
     const declaredMedia = config.execution?.desktop?.media;
     return declaredMedia === undefined
         ? undefined
@@ -34,7 +20,7 @@ function studyMedia(config) {
         });
 }
 /** The runtime image, prepared once per study on first use, after the account check. */
-function studyAssets(options, account, needsMedia) {
+function guestAssets(options, account, needsMedia) {
     let preparing;
     return () => (preparing ??= (async () => {
         if (account) {
@@ -64,7 +50,7 @@ function mediaEvidence(media) {
         },
     };
 }
-/** One lane's Firecracker desktop and optional captured inbox, released in finalize. */
+/** One participant's Firecracker desktop and optional captured inbox, released in finalize. */
 function createLocalParticipantDesktop(context, run, warnings, artifactRoot) {
     const { config, media, recording, state } = context;
     let session;
@@ -132,7 +118,14 @@ function createLocalParticipantDesktop(context, run, warnings, artifactRoot) {
                 }
                 if (!evidence.released) {
                     state.cleanupUnconfirmed = true;
-                    warnings.push("Local desktop cleanup is unconfirmed.");
+                    const warning = "Local desktop cleanup is unconfirmed.";
+                    warnings.push(warning);
+                    // No receipt names a local VM, so the record carries the command that removes it.
+                    evidence.sandboxRelease = {
+                        state: "unconfirmed",
+                        warning,
+                        recovery: `If container ${session.resourceId} is still listed by \`${dockerCommandLine(["ps"])}\`, remove it with \`${dockerCommandLine(["rm", "--force", "--volumes", session.resourceId])}\`.`,
+                    };
                 }
             })());
         },
@@ -141,40 +134,37 @@ function createLocalParticipantDesktop(context, run, warnings, artifactRoot) {
 }
 /** The Codex account participant, whose unconfirmed cleanup blocks the study's analysis. */
 function accountProvider(state) {
-    return {
-        async buildProvider({ executor }) {
-            const participant = createRestrictedCodexParticipant({
-                speechEnabled: executor?.speechEnabled === true,
-            });
-            state.participants.push(participant);
-            return Object.assign(participant.provider, {
-                async close() {
-                    if ((await participant.close()).status !== "confirmed") {
-                        state.cleanupUnconfirmed = true;
-                        throw new Error("Local participant cleanup is unconfirmed.");
-                    }
-                },
-            });
-        },
+    return async ({ executor }) => {
+        const participant = createRestrictedCodexParticipant({
+            speechEnabled: executor.speechEnabled === true,
+        });
+        state.participants.push(participant);
+        const provider = Object.assign(participant.provider, {
+            async close() {
+                if ((await participant.close()).status !== "confirmed") {
+                    state.cleanupUnconfirmed = true;
+                    throw new Error("Local participant cleanup is unconfirmed.");
+                }
+            },
+        });
+        // The participant runner reads the session's warnings and late refusal from the same, idempotent close.
+        return withCloseReport(provider, () => participant.close());
     };
 }
 /**
  * Local desktop/provider composition: the options the lab is planned and run with. It throws before
- * anything starts on a lab the local study cannot run, or on a hook only an E2B desktop calls.
+ * anything starts on a lab the local study cannot run.
  */
-export function prepareLocalVmStudy(options) {
+export function prepareLocalVmRun(options) {
     const config = localBrowserDefaults(options.config);
     const unsupported = localBrowserUnsupportedReason(config);
     if (unsupported)
         throw new Error(unsupported);
-    refuseE2BDesktopHooks(options.cuaHooks);
     const recording = config.execution?.desktop?.recording;
-    const media = studyMedia(config);
-    const callerHooks = options.cuaHooks;
+    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" && callerHooks?.buildProvider === undefined;
-    const baseRunSession = callerHooks?.runSession ?? runCuaActorSession;
+    const account = config.actors[0]?.type === "local-agent" && options.createProvider === undefined;
     const state = { sessions: [], participants: [], cleanupUnconfirmed: false };
     const context = {
         config,
@@ -182,33 +172,16 @@ export function prepareLocalVmStudy(options) {
         signal: options.signal,
         media,
         recording,
-        assets: studyAssets(options, account, media !== undefined || recording !== undefined),
+        assets: guestAssets(options, account, media !== undefined || recording !== undefined),
         state,
     };
     const { config: _config, assets: _assets, signal: _signal, ...runOptions } = options;
     return {
-        options: {
-            ...runOptions,
-            // Wrapped rather than spread for the same reason as cuaHooks below.
-            automaticAnalysis: withHookOverrides(options.automaticAnalysis, HOOK_MEMBERS.analysis, {
-                onStart() {
-                    if (state.cleanupUnconfirmed)
-                        throw new Error("Local study cleanup is unconfirmed.");
-                    return options.automaticAnalysis?.onStart?.();
-                },
-            }),
-            // These overrides go over the caller's hooks so this study's desktop always wins:
-            // participantDesktopOf takes [PARTICIPANT_DESKTOP] before a caller's createDesktopLane.
-            // The caller's bag may be a class instance, so it is wrapped rather than spread.
-            cuaHooks: withHookOverrides(callerHooks, HOOK_MEMBERS.cua, {
-                [PARTICIPANT_DESKTOP]: (run, warnings, artifactRoot) => createLocalParticipantDesktop(context, run, warnings, artifactRoot),
-                ...(account ? accountProvider(state) : {}),
-                ...(options.signal
-                    ? {
-                        runSession: (input) => baseRunSession({ ...input, signal: options.signal }),
-                    }
-                    : {}),
-            }),
+        options: account ? { ...runOptions, createProvider: accountProvider(state) } : runOptions,
+        localVm: {
+            desktop: (run, warnings, artifactRoot) => createLocalParticipantDesktop(context, run, warnings, artifactRoot),
+            analysisRefusal: () => state.cleanupUnconfirmed ? "AUTOMATIC_ANALYSIS_CLEANUP_UNCONFIRMED" : undefined,
+            ...(options.signal === undefined ? {} : { signal: options.signal }),
         },
         async close() {
             await Promise.allSettled(state.participants.map((participant) => participant.close()));