humanish 0.106.0 → 0.107.0

package/dist/routes/computer-use/e2b-desktop/prepare.js

@@ -1,5 +1,5 @@
-// The first half of an E2B desktop lane's preparation: acquire the sandbox, verify its screen, and
-// provision the subject. Each step fills the lane's state; a step that cannot proceed throws.
+// The first half of an E2B desktop participant's preparation: acquire the sandbox, verify its screen, and
+// provision the subject. Each step fills the participant's state; a step that cannot proceed throws.
 import { redactText } from "../../../evidence/redaction.js";
 import { provisionCloneSubject } from "../../../subject/clone.js";
 import { provisionDesktopCli } from "../../../subject/desktop-cli.js";
@@ -10,22 +10,24 @@ import { acquireE2BDesktopSandbox, e2bDesktopTemplate } from "../../../substrate
 import { loadE2BDesktopModule } from "../../../substrates/e2b/sdk.js";
 import { e2bShell } from "../../../substrates/e2b/shell.js";
 import { attachReceivingInbox, participantCommsEnv, startCommsCatch } from "./comms.js";
+import { participantSubjectEnv } from "../types.js";
 export const CUA_ACTOR_LAB_PROVIDER_METADATA = {
     mode: "cua-actor-lab",
     tool: "humanish",
 };
 /**
- * Create the lane's sandbox, record its resources, run the adopter's prepare hook, and attach the
- * lane's inbox and comms catch. Returns the sandbox, which the later steps drive.
+ * Create the participant's sandbox, record its resources, run the adopter's prepare hook, and attach the
+ * participant's inbox and comms catch. Returns the sandbox, which the later steps drive.
  */
 export async function acquireParticipantDesktop(ctx, state) {
     const { spec, deps, warnings } = ctx;
-    const { config, subjectEnvNames, env } = deps;
-    const subjectEnvValues = config.subject.envValues ?? {};
+    const { residual, env } = deps;
+    const subjectEnvNames = participantSubjectEnv(deps.subject);
+    const subjectEnvValues = residual.subject.envValues ?? {};
     // Off-app comms (#297): the base-URL env is injected at sandbox create, so the app reads it at
     // boot; the catch starts right after create.
     const commsEnv = participantCommsEnv(ctx.comms);
-    const desktopModule = await (deps.hooks.loadDesktopModule ?? loadE2BDesktopModule)();
+    const desktopModule = await (deps.desktopModule ?? loadE2BDesktopModule)();
     // An explicit template wins. Speech gets the versioned media image; ordinary
     // browser studies retain the SDK default desktop.
     const acquired = await acquireE2BDesktopSandbox({
@@ -36,7 +38,7 @@ export async function acquireParticipantDesktop(ctx, state) {
             timeoutMs: deps.sandboxMs,
             metadata: {
                 ...CUA_ACTOR_LAB_PROVIDER_METADATA,
-                labId: config.id,
+                labId: deps.labId,
                 simId: spec.recordId,
                 laneId: spec.planned.id,
                 laneIndex: String(spec.planned.index),
@@ -62,7 +64,7 @@ export async function acquireParticipantDesktop(ctx, state) {
             dpi: 96,
             lifecycle: { onTimeout: "kill" },
         },
-        template: e2bDesktopTemplate(config),
+        template: e2bDesktopTemplate(residual),
         retry: {
             // The default loader reclaims an acquired handle before retrying failed desktop startup.
             // Its error names the cleanup outcome; pre-construction allocation failures remain unowned.
@@ -76,7 +78,7 @@ export async function acquireParticipantDesktop(ctx, state) {
                 });
             },
         },
-        // The receipt is on disk before any work, so `humanish reclaim` can kill this lane's
+        // The receipt is on disk before any work, so `humanish reclaim` can kill this participant's
         // sandbox by exact id after an interrupt.
         receipt: { root: deps.artifactRoot, participantId: spec.planned.id, now: deps.now },
     });
@@ -92,13 +94,10 @@ export async function acquireParticipantDesktop(ctx, state) {
     if ("reason" in desktopResources) {
         warnings.push(`Desktop resource size unavailable (${desktopResources.reason}); compute cost remains unpriced.`);
     }
-    if (deps.hooks.prepareDesktop) {
-        await deps.hooks.prepareDesktop(desktop, {
-            laneId: spec.planned.id,
-            laneIndex: spec.planned.index,
-            laneCount: deps.participantCount,
-        });
-    }
+    await deps.prepareDesktop?.(desktop, {
+        kind: "participant",
+        participant: { id: spec.planned.id, index: spec.planned.index, count: deps.participantCount },
+    });
     if (deps.receiving) {
         state.receivingInboxUrl = await attachReceivingInbox(shell, spec, { ...deps, receiving: deps.receiving }, ctx.targetUrl);
         state.commsArtifactPath = "comms/receiving.json";
@@ -108,7 +107,7 @@ export async function acquireParticipantDesktop(ctx, state) {
     return desktop;
 }
 /**
- * Verify the lane's screen in the sandbox. A mismatch fails the lane closed unless the run records
+ * Verify the participant's screen in the sandbox. A mismatch fails the participant closed unless the run records
  * requested and verified geometry side by side.
  */
 export async function verifyParticipantScreen(ctx, state, desktop) {
@@ -135,7 +134,7 @@ export async function verifyParticipantScreen(ctx, state, desktop) {
     }
     if (screenGeometry.error && screenGeometry.verified) {
         // record-evidence policy: the bundle keeps requested vs verified as separate facts and
-        // discloses the divergence instead of failing this lane's world mid-flight.
+        // discloses the divergence instead of failing this participant's world mid-flight.
         const mismatchWarning = deps.scrubKnownValues(`Participant ${spec.planned.id} requested a ${spec.planned.device.resolution[0]}x${spec.planned.device.resolution[1]} screen but xdpyinfo reports ${screenGeometry.verified.width}x${screenGeometry.verified.height}; recording requested vs verified separately instead of failing the participant closed.`);
         warnings.push(mismatchWarning);
         state.desktopGeometry = {
@@ -147,28 +146,26 @@ export async function verifyParticipantScreen(ctx, state, desktop) {
 /** Install a desktop CLI, or clone or unpack the subject and serve it, in the sandbox. */
 export async function provisionParticipantSubject(ctx, state, desktop) {
     const { deps } = ctx;
-    const { config, cloneRoute, localTreeRoute, serve, subjectRepo } = deps;
+    const { residual, subject } = deps;
     const shell = e2bShell(desktop);
-    if (ctx.desktopCliRoute) {
+    if (subject.kind === "desktop-cli") {
         // Prepare the runtime and any declared product install, UNKEYED. With install omitted,
         // the participant discovers and installs the product from its public surfaces.
         await provisionDesktopCli(shell, {
-            product: config.subject.product?.name ?? "",
-            ...(config.subject.product?.install === undefined
-                ? {}
-                : { install: config.subject.product.install }),
+            product: subject.product.name,
+            ...(subject.product.install === undefined ? {} : { install: subject.product.install }),
             requestTimeoutMs: deps.requestTimeoutMs,
             scrub: deps.scrubKnownValues,
             onPhase: ctx.onSubjectPhase,
         });
     }
-    if (cloneRoute && serve && subjectRepo) {
+    if (subject.kind === "clone") {
         state.subjectCommit = await provisionCloneSubject(shell, {
-            repo: subjectRepo,
-            depth: config.subject.clone?.depth ?? 1,
-            serve,
-            ...(config.subject.state === undefined ? {} : { state: config.subject.state }),
-            hasGithubToken: deps.hasGithubToken,
+            repo: subject.repo,
+            depth: residual.subject.clone?.depth ?? 1,
+            serve: subject.serve,
+            ...(subject.state === undefined ? {} : { state: subject.state }),
+            hasGithubToken: subject.env.includes("GITHUB_TOKEN"),
             requestTimeoutMs: deps.requestTimeoutMs,
             scrub: deps.scrubKnownValues,
             onCommit: (commit) => {
@@ -178,21 +175,21 @@ export async function provisionParticipantSubject(ctx, state, desktop) {
                 state.stateStepRecords.push(record);
             },
             onPhase: ctx.onSubjectPhase,
-            ...deps.hooks.detachedTimers,
+            ...deps.detachedTimers,
         });
     }
-    else if (localTreeRoute && serve && deps.localTreeArchiveBuffer) {
+    else if (subject.kind === "local-tree" && deps.localTreeArchiveBuffer) {
         await provisionLocalTreeSubject(shell, {
             archiveBuffer: deps.localTreeArchiveBuffer,
-            serve,
-            ...(config.subject.state === undefined ? {} : { state: config.subject.state }),
+            serve: subject.serve,
+            ...(subject.state === undefined ? {} : { state: subject.state }),
             requestTimeoutMs: deps.requestTimeoutMs,
             scrub: deps.scrubKnownValues,
             onStateStep: (record) => {
                 state.stateStepRecords.push(record);
             },
             onPhase: ctx.onSubjectPhase,
-            ...deps.hooks.detachedTimers,
+            ...deps.detachedTimers,
         });
     }
 }

package/dist/routes/computer-use/e2b-desktop/start.d.ts

@@ -9,6 +9,6 @@ export declare function startParticipantMedia(ctx: E2BParticipantContext, state:
 export declare function openParticipantSurface(ctx: E2BParticipantContext, state: E2BParticipantState, desktop: E2BDesktopSandbox): Promise<void>;
 /**
  * Measure the browser window and start the live stream. A stream that cannot start is a warning;
- * unusable browser geometry fails the lane before any participant action.
+ * unusable browser geometry fails the participant before any action.
  */
 export declare function startParticipantStream(ctx: E2BParticipantContext, state: E2BParticipantState, desktop: E2BDesktopSandbox): Promise<void>;

package/dist/routes/computer-use/e2b-desktop/start.js

@@ -1,6 +1,6 @@
-// The second half of an E2B desktop lane's preparation, and the start of its session: speech and
+// The second half of an E2B desktop participant's preparation, and the start of its session: speech and
 // recording, then the browser or terminal the participant sees, then the live stream. Each step
-// fills the lane's state.
+// fills the participant's state.
 import { redactText, toErrorMessage } from "../../../evidence/redaction.js";
 import { CHROME_DEVTOOLS_PORT, DESKTOP_SETTLE_MS, openDesktopBrowserTarget, openDesktopTerminal, startDesktopStream, } from "../../../substrates/e2b/desktop-browser.js";
 import { captureDesktopBrowserGeometry } from "../../../substrates/e2b/desktop-geometry.js";
@@ -10,7 +10,7 @@ import { applyParticipantMobileFidelity, mobileLaunchFlags } from "./fidelity.js
 /** Start the declared speech worker and screen recording. A recording that cannot start is a warning. */
 export async function startParticipantMedia(ctx, state, desktop) {
     const { spec, deps, warnings } = ctx;
-    const requestedMedia = deps.config.execution?.desktop?.media;
+    const requestedMedia = deps.residual.execution?.desktop?.media;
     if (!ctx.desktopCliRoute && requestedMedia?.microphone?.source === "speech") {
         state.speech = await startE2BDesktopMedia({
             desktop,
@@ -20,7 +20,7 @@ export async function startParticipantMedia(ctx, state, desktop) {
             requestTimeoutMs: deps.requestTimeoutMs,
         });
     }
-    const requestedRecording = deps.config.execution?.desktop?.recording;
+    const requestedRecording = deps.residual.execution?.desktop?.recording;
     if (requestedRecording) {
         try {
             state.recording = await startE2BDesktopRecording({
@@ -43,28 +43,28 @@ export async function startParticipantMedia(ctx, state, desktop) {
  */
 export async function openParticipantSurface(ctx, state, desktop) {
     const { spec, deps, warnings, targetUrl } = ctx;
-    const { config } = deps;
-    if (ctx.desktopCliRoute) {
+    const { residual, subject } = deps;
+    if (subject.kind === "desktop-cli") {
         // A terminal window, opened the way the browser is opened on every other route: the
         // participant arrives at a desktop with the thing they were asked to use already in front
         // of them. They can still open another from the dock — that is the point of a desktop.
-        await openDesktopTerminal(desktop, deps.requestTimeoutMs, config.subject.product?.workdir);
+        await openDesktopTerminal(desktop, deps.requestTimeoutMs, subject.product.workdir);
         await desktop.wait(DESKTOP_SETTLE_MS).catch(() => undefined);
         return;
     }
-    const requestedMedia = config.execution?.desktop?.media;
+    const requestedMedia = residual.execution?.desktop?.media;
     // A declared camera (#509) is in place before the browser starts: the feed is generated or
-    // uploaded first, and a feed that cannot be produced fails the lane closed here.
+    // uploaded first, and a feed that cannot be produced fails the participant closed here.
     const mediaEvidence = requestedMedia === undefined
         ? undefined
-        : await prepareDesktopMedia(desktop, requestedMedia, config.policies?.mediaPermission ?? "prompt", deps.labCwd, deps.requestTimeoutMs);
-    const emulationFlags = mobileLaunchFlags(config, spec);
-    const browserLaunch = await openDesktopBrowserTarget(desktop, targetUrl, deps.requestTimeoutMs, config.execution?.desktop?.browser, [...emulationFlags, ...(mediaEvidence?.flags ?? [])], state.speech?.env ?? state.recording?.env);
+        : await prepareDesktopMedia(desktop, requestedMedia, residual.policies?.mediaPermission ?? "prompt", deps.labCwd, deps.requestTimeoutMs);
+    const emulationFlags = mobileLaunchFlags(residual, spec);
+    const browserLaunch = await openDesktopBrowserTarget(desktop, targetUrl, deps.requestTimeoutMs, residual.execution?.desktop?.browser, [...emulationFlags, ...(mediaEvidence?.flags ?? [])], state.speech?.env ?? state.recording?.env);
     state.desktopBrowser =
         mediaEvidence === undefined
             ? browserLaunch.evidence
             : {
-                requested: config.execution?.desktop?.browser ?? "default",
+                requested: residual.execution?.desktop?.browser ?? "default",
                 ...browserLaunch.evidence,
                 media: mediaEvidence,
             };
@@ -77,7 +77,7 @@ export async function openParticipantSurface(ctx, state, desktop) {
     noteDevToolsReadiness(ctx, browserLaunch.devTools, emulationFlags.length > 0);
     await desktop.wait(DESKTOP_SETTLE_MS).catch(() => undefined);
     // Mobile fidelity (#221) is applied outside startParticipantStream's best-effort catch, so a request
-    // that cannot be applied fails the lane closed.
+    // that cannot be applied fails the participant closed.
     state.fidelity = await applyParticipantMobileFidelity({
         desktop,
         spec,
@@ -90,14 +90,14 @@ export async function openParticipantSurface(ctx, state, desktop) {
     });
 }
 /**
- * DevTools answering later than this after launch is recorded as a warning on the lane. Six live
+ * DevTools answering later than this after launch is recorded as a warning on the participant. Six live
  * launches answered in 4.8-7.7 s; the reads this wait now guards used to give up at about 11 s.
  */
 const SLOW_DEVTOOLS_MS = 10_000;
 /**
  * Records how Chrome's DevTools port answered after launch, as a timed phase in the bundle. A
- * device-emulated lane fails closed when the port never answered, because emulation is applied
- * over DevTools. Other lanes continue with a warning: their DevTools reads already degrade to
+ * device-emulated participant fails closed when the port never answered, because emulation is applied
+ * over DevTools. Other participants continue with a warning: their DevTools reads already degrade to
  * warnings of their own.
  */
 function noteDevToolsReadiness(ctx, devTools, emulated) {
@@ -132,7 +132,7 @@ function noteDevToolsReadiness(ctx, devTools, emulated) {
 }
 /**
  * Measure the browser window and start the live stream. A stream that cannot start is a warning;
- * unusable browser geometry fails the lane before any participant action.
+ * unusable browser geometry fails the participant before any action.
  */
 export async function startParticipantStream(ctx, state, desktop) {
     const { spec, deps, warnings } = ctx;
@@ -156,8 +156,8 @@ export async function startParticipantStream(ctx, state, desktop) {
             state.browserWindowId = browserGeometry.browserWindowId;
             state.browserTargetId = browserGeometry.browserTargetId;
         }
-        // A browser lane streams its browser window when one was found. A CLI lane has no window id
-        // and streams the whole desktop: a person studying a terminal app opens other windows, and
+        // A browser participant streams its browser window when one was found. A CLI participant has
+        // no window id and streams the whole desktop: a person studying a terminal app opens other windows, and
         // a stream bound to the first one would quietly stop being evidence.
         await startDesktopStream(desktop, state.browserWindowId);
         const candidateStreamUrl = desktop.stream.getUrl({
@@ -168,8 +168,9 @@ export async function startParticipantStream(ctx, state, desktop) {
         });
         if (typeof candidateStreamUrl === "string" && candidateStreamUrl.trim().length > 0) {
             state.streamUrl = candidateStreamUrl;
-            await deps.hooks.onRuntimeStreamReady?.({
-                laneId: spec.planned.id,
+            await deps.onStream({
+                type: "ready",
+                participantId: spec.planned.id,
                 sandboxId: desktop.sandboxId,
                 simId: spec.recordId,
                 streamId: spec.streamId,
@@ -184,7 +185,7 @@ export async function startParticipantStream(ctx, state, desktop) {
         warnings.push(`Live desktop stream unavailable (run continues; evidence still captured): ${redactText(deps.scrubKnownValues(toErrorMessage(error)))}`);
     }
     // This is outside the stream's best-effort catch: unusable geometry is a harness failure,
-    // never a participant finding about missing controls. Both per-lane and shared-world seats
+    // never a participant finding about missing controls. Both computer-use and shared-world participants
     // use this route.
     if (state.initialBrowserGeometry?.unusable !== undefined) {
         state.failureCode = "HUMANISH_CUA_LAB_DEVICE_GEOMETRY";

package/dist/routes/computer-use/e2b-desktop/state.d.ts

@@ -12,11 +12,11 @@ import type { E2BDesktopSandbox } from "../../../substrates/e2b/sdk.js";
 import type { ParticipantDesktopEvidence } from "../participant-desktop.js";
 import type { ParticipantComms, RunningCommsCatch } from "./comms.js";
 import type { ParticipantFidelity } from "./fidelity.js";
-import type { CuaActorLabErrorCode, CuaParticipantDeps, DesktopParticipantRun } from "../types.js";
-/** What every step of one lane reads: its spec, the run's dependencies and where it points. */
+import type { CuaActorLabErrorCode, E2BDesktopDeps, DesktopParticipantRun, SandboxReleaseFact } from "../types.js";
+/** What every step of one participant reads: its spec, the run's dependencies and where it points. */
 export interface E2BParticipantContext {
     readonly spec: DesktopParticipantRun;
-    readonly deps: CuaParticipantDeps;
+    readonly deps: E2BDesktopDeps;
     readonly warnings: string[];
     readonly targetUrl: string;
     readonly desktopCliRoute: boolean;
@@ -37,6 +37,7 @@ export interface E2BParticipantState {
     sandboxTornDownAtMs: number | undefined;
     desktopResources: DesktopResourceObservation | undefined;
     released: boolean;
+    sandboxRelease: SandboxReleaseFact | undefined;
     failureCode: CuaActorLabErrorCode | undefined;
     commsCatch: RunningCommsCatch | undefined;
     commsArtifactPath: string | undefined;
@@ -61,5 +62,5 @@ export interface E2BParticipantState {
     streamUrl: string | undefined;
 }
 export declare function newParticipantState(spec: DesktopParticipantRun): E2BParticipantState;
-/** The lane's outcome evidence, read from its state. */
+/** The participant's outcome evidence, read from its state. */
 export declare function desktopEvidenceOf(state: E2BParticipantState): ParticipantDesktopEvidence;

package/dist/routes/computer-use/e2b-desktop/state.js

@@ -1,5 +1,5 @@
-// What one E2B desktop lane records as it runs. The prepare, start and teardown steps fill one
-// record in order, and desktopEvidenceOf reads it for the lane's outcome.
+// What one E2B desktop participant records as it runs. The prepare, start and teardown steps fill one
+// record in order, and desktopEvidenceOf reads it for the participant's outcome.
 import { declaredScreenForRender, } from "../../../substrates/e2b/desktop-geometry.js";
 export function newParticipantState(spec) {
     const declaredScreen = declaredScreenForRender(spec.planned.device.preset, spec.planned.device.name, spec.planned.device.resolution);
@@ -11,6 +11,7 @@ export function newParticipantState(spec) {
         sandboxTornDownAtMs: undefined,
         desktopResources: undefined,
         released: false,
+        sandboxRelease: undefined,
         failureCode: undefined,
         commsCatch: undefined,
         commsArtifactPath: undefined,
@@ -42,7 +43,7 @@ export function newParticipantState(spec) {
         streamUrl: undefined,
     };
 }
-/** The lane's outcome evidence, read from its state. */
+/** The participant's outcome evidence, read from its state. */
 export function desktopEvidenceOf(state) {
     // Host-side approximation of the E2B desktop's billed lifetime; feeds the desktop-minute cost
     // estimate. Never negative.
@@ -54,6 +55,7 @@ export function desktopEvidenceOf(state) {
         ...(desktopDurationMs === undefined ? {} : { desktopDurationMs }),
         ...(state.desktopResources === undefined ? {} : { desktopResources: state.desktopResources }),
         released: state.released,
+        ...(state.sandboxRelease === undefined ? {} : { sandboxRelease: state.sandboxRelease }),
         streamUrlPresent: state.streamUrl !== undefined,
         ...(state.subjectCommit === undefined ? {} : { subjectCommit: state.subjectCommit }),
         ...(state.desktopBrowser === undefined ? {} : { desktopBrowser: state.desktopBrowser }),

package/dist/routes/computer-use/e2b-desktop/teardown.d.ts

@@ -1,6 +1,6 @@
 import type { E2BParticipantContext, E2BParticipantState } from "./state.js";
 /**
- * Finish a lane: collect its final geometry and comms evidence, then stop its media and release
+ * Finish a participant: collect its final geometry and comms evidence, then stop its media and release
  * its sandbox. Evidence failures are warnings; the release always runs.
  */
 export declare function finishE2BDesktop(ctx: E2BParticipantContext, state: E2BParticipantState, failed: boolean): Promise<void>;

package/dist/routes/computer-use/e2b-desktop/teardown.js

@@ -1,4 +1,4 @@
-// Teardown for one E2B desktop lane: its final geometry and comms evidence are collected, then the
+// Teardown for one E2B desktop participant: its final geometry and comms evidence are collected, then the
 // recording and speech worker, then the sandbox is released by id (or kept for debugging), with a
 // warning for every outcome that is not a confirmed release.
 import { collectDesktopRecording } from "../../../evidence/desktop-recording-artifact.js";
@@ -8,14 +8,14 @@ import { e2bShell } from "../../../substrates/e2b/shell.js";
 import { drainCommsEvidence } from "./comms.js";
 import { finalParticipantGeometry } from "./fidelity.js";
 /**
- * Each route's own keep flag gates its own lane only: a clone.keep can never leak into a local-tree
- * lane's teardown decision, and vice versa.
+ * Each route's own keep flag gates its own participants only: a clone.keep can never leak into a
+ * local-tree participant's teardown decision, and vice versa.
  */
 function participantKeepReason(deps) {
-    const { config, cloneRoute, localTreeRoute } = deps;
-    if (cloneRoute && config.subject.clone?.keep === true)
+    const { residual, subject } = deps;
+    if (subject.kind === "clone" && residual.subject.clone?.keep === true)
         return "subject.clone.keep";
-    if (localTreeRoute && config.subject.localTree?.keep === true)
+    if (subject.kind === "local-tree" && residual.subject.localTree?.keep === true)
         return "subject.localTree.keep";
     return undefined;
 }
@@ -38,17 +38,18 @@ async function stopParticipantMedia(args) {
     return evidence;
 }
 /**
- * Release the lane's sandbox, or keep it when a keep flag is set and the lane failed. Returns true
- * only when the release is confirmed. A kept or unconfirmed sandbox can still accrue compute cost,
- * which the warnings say.
+ * Release the participant's sandbox, or keep it when a keep flag is set and the participant failed. `released`
+ * is true only when the release is confirmed; otherwise `sandboxRelease` says why. A kept or
+ * unconfirmed sandbox can still accrue compute cost, which the warnings say.
  */
 async function releaseParticipantDesktop(args) {
     const { allocation, keepReason, deps, warnings } = args;
     const keepForDebug = keepReason !== undefined && args.failed;
     const released = await allocation.close({ retainForDebug: keepForDebug });
     if (released.status === "retained") {
-        warnings.push(`Sandbox ${allocation.resourceId} kept for debugging (${keepReason} on failure); reclaim it via E2B or it will be killed on its server-side timeout.`);
-        return false;
+        const warning = `Sandbox ${allocation.resourceId} kept for debugging (${keepReason} on failure); reclaim it via E2B or it will be killed on its server-side timeout.`;
+        warnings.push(warning);
+        return { released: false, sandboxRelease: { state: "retained", warning } };
     }
     const reading = readE2BRelease(released, {
         label: "Sandbox",
@@ -57,10 +58,18 @@ async function releaseParticipantDesktop(args) {
     });
     if (reading.warning)
         warnings.push(reading.warning);
-    return reading.released;
+    if (reading.released)
+        return { released: true };
+    return {
+        released: false,
+        sandboxRelease: {
+            state: "unconfirmed",
+            warning: reading.warning ?? "Sandbox release is unconfirmed.",
+        },
+    };
 }
 /**
- * Finish a lane: collect its final geometry and comms evidence, then stop its media and release
+ * Finish a participant: collect its final geometry and comms evidence, then stop its media and release
  * its sandbox. Evidence failures are warnings; the release always runs.
  */
 export async function finishE2BDesktop(ctx, state, failed) {
@@ -122,24 +131,27 @@ export async function finishE2BDesktop(ctx, state, failed) {
             mediaStop: state.mediaStop,
             warnings,
         });
-        state.released = await releaseParticipantDesktop({
+        const release = await releaseParticipantDesktop({
             allocation,
             keepReason: participantKeepReason(deps),
             failed,
             deps,
             warnings,
         });
+        state.released = release.released;
+        state.sandboxRelease = release.sandboxRelease;
         // Close the observed span. A kept or unconfirmed sandbox can still accrue compute cost; the
         // summary records that remaining lifetime as unknown instead of calling this complete.
         state.sandboxTornDownAtMs = deps.now();
-        // The lane's live stream is now a dead page whichever teardown path ran (released, kept, or
+        // The participant's live stream is now a dead page whichever teardown path ran (released, kept, or
         // release-failed-awaiting-TTL); tell the watch overlay so the tile falls back to recorded
         // evidence instead of "sandbox not found" (#357). Guarded: a viewer callback must never
         // break teardown.
         if (state.streamUrl !== undefined) {
             try {
-                await deps.hooks.onRuntimeStreamEnded?.({
-                    laneId: spec.planned.id,
+                await deps.onStream({
+                    type: "ended",
+                    participantId: spec.planned.id,
                     simId: spec.recordId,
                     streamId: spec.streamId,
                 });

package/dist/routes/computer-use/external-comms.d.ts

@@ -2,12 +2,12 @@ import type { LabCommsEmail, LabCommsExternal } from "../../lab/types.js";
 import type { PreparedRunArtifactPaths } from "../../run/paths.js";
 import type { DesktopParticipantRun, ParticipantRunOutcome } from "./types.js";
 /**
- * Adopter-hosted drain (#380): once per RUN, after every lane finished — the catch is one
+ * Adopter-hosted drain (#380): once per RUN, after every participant finished — the catch is one
  * shared external endpoint, not a per-sandbox file. Same routing and digest-only artifact as
- * the in-sandbox drain; the artifact is registered on every lane that declared a recipient
+ * the in-sandbox drain; the artifact is registered on every participant that declared a recipient
  * address, since the thread carries each inbox's mail. A drain failure never fails the run.
  *
- * Returns the warnings the drain produced; lanes that received mail get `commsArtifactPath`.
+ * Returns the warnings the drain produced; participants that received mail get `commsArtifactPath`.
  */
 export declare function drainExternalComms(args: {
     externalCommsConfig: LabCommsExternal;
@@ -16,5 +16,5 @@ export declare function drainExternalComms(args: {
     runPaths: PreparedRunArtifactPaths;
     participantRuns: readonly DesktopParticipantRun[];
     outcomes: ParticipantRunOutcome[];
-    scrubKnownValues: (text: string) => string;
+    knownSecretValues: readonly string[];
 }): Promise<string[]>;

package/dist/routes/computer-use/external-comms.js

@@ -1,55 +1,31 @@
-import { FakeInbox } from "../../comms/fake-inbox.js";
-import { collectExternalCommsThread } from "../../comms/sandbox-catch.js";
-import { redactText, toErrorMessage } from "../../evidence/redaction.js";
-import { writeContainedOutputFile } from "../../run/contained-output.js";
+import { collectExternalCommsEvidence } from "../../comms/external-evidence.js";
 import { participantHasInboxRecipient } from "./participant-desktop.js";
-import { addressedRecipients } from "../../lab/parse/comms.js";
 /**
- * Adopter-hosted drain (#380): once per RUN, after every lane finished — the catch is one
+ * Adopter-hosted drain (#380): once per RUN, after every participant finished — the catch is one
  * shared external endpoint, not a per-sandbox file. Same routing and digest-only artifact as
- * the in-sandbox drain; the artifact is registered on every lane that declared a recipient
+ * the in-sandbox drain; the artifact is registered on every participant that declared a recipient
  * address, since the thread carries each inbox's mail. A drain failure never fails the run.
  *
- * Returns the warnings the drain produced; lanes that received mail get `commsArtifactPath`.
+ * Returns the warnings the drain produced; participants that received mail get `commsArtifactPath`.
  */
 export async function drainExternalComms(args) {
-    const { externalCommsConfig, externalCommsEmail, env, runPaths, participantRuns, outcomes, scrubKnownValues, } = args;
-    const warnings = [];
-    try {
-        const commsChannel = new FakeInbox();
-        const commsInboxes = [];
-        for (const recipient of addressedRecipients(externalCommsEmail)) {
-            commsInboxes.push(await commsChannel.provisionAddress(recipient.participantId, recipient.address));
-        }
-        const authToken = externalCommsConfig.authTokenEnv === undefined
-            ? undefined
-            : env[externalCommsConfig.authTokenEnv];
-        const collected = await collectExternalCommsThread({
-            external: { ...externalCommsConfig, ...(authToken === undefined ? {} : { authToken }) },
-            channel: commsChannel,
-            inboxes: commsInboxes,
-        });
-        if (collected.artifact) {
-            const commsPath = "comms/thread.json";
-            await writeContainedOutputFile(runPaths, commsPath, `${JSON.stringify(collected.artifact, null, 2)}\n`, "utf8");
-            for (const [index, outcome] of outcomes.entries()) {
-                const participantId = participantRuns[index]?.planned.id;
-                if (participantId !== undefined &&
-                    outcome.commsArtifactPath === undefined &&
-                    participantHasInboxRecipient(externalCommsEmail, participantId)) {
-                    outcome.commsArtifactPath = commsPath;
-                }
+    const { externalCommsEmail, participantRuns, outcomes } = args;
+    const { path: commsPath, warnings } = await collectExternalCommsEvidence({
+        external: args.externalCommsConfig,
+        email: externalCommsEmail,
+        env: args.env,
+        runPaths: args.runPaths,
+        knownSecretValues: args.knownSecretValues,
+    });
+    if (commsPath !== undefined) {
+        for (const [index, outcome] of outcomes.entries()) {
+            const participantId = participantRuns[index]?.planned.id;
+            if (participantId !== undefined &&
+                outcome.commsArtifactPath === undefined &&
+                participantHasInboxRecipient(externalCommsEmail, participantId)) {
+                outcome.commsArtifactPath = commsPath;
             }
         }
-        else if (collected.captured > 0) {
-            warnings.push(`Comms catch captured ${collected.captured} email send(s) but none matched a declared recipient inbox — no comms evidence written. Declare comms.email.recipients[].address to match the address the app sends to.`);
-        }
-        else {
-            warnings.push(`Comms catch captured ZERO email sends — your app never delivered mail through the catch at ${externalCommsConfig.catchBaseUrl}. Verify the app's email-API base URL points at it and that the flow reached an email step.`);
-        }
-    }
-    catch (error) {
-        warnings.push(`Comms evidence collection failed against the adopter-hosted catch (run continues): ${redactText(scrubKnownValues(toErrorMessage(error)))}`);
     }
     return warnings;
 }

package/dist/routes/computer-use/fanout-bundle.d.ts

@@ -1,10 +1,10 @@
 import { type RunBundle } from "../../run/bundle.js";
 import type { CuaFanoutBundleArgs } from "./types.js";
 /**
- * Project N>1 fan-out lanes into a humanish.run-bundle.v1 (the evidence schema is unchanged; this
- * is a new producer for the multi-stream shape). One sim + one stream per lane; per-lane
+ * Project N>1 fan-out participants into a humanish.run-bundle.v1 (the evidence schema is unchanged; this
+ * is a new producer for the multi-stream shape). One sim + one stream per participant; per-participant
  * provenance/session events; a recorded `cua-lab.fanout.plan` event (and a `cua-lab.fanout.fail-fast`
- * event when a harness error skipped queued lanes). N-ary verify/Observer already handle multiple
+ * event when a harness error skipped queued participants). N-ary verify/Observer already handle multiple
  * streams. A single-participant run without a rerun never reaches here: buildCuaRunBundle
  * (bundle.ts) sends it to buildSingleParticipantBundle (single-bundle.ts).
  */