humanish 0.104.3 → 0.106.0

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

@@ -0,0 +1,225 @@
+// Off-app email for one E2B desktop lane (#297): the in-sandbox catch the subject app sends to, the
+// persona's inbox surface, the real-email receiving surface, and the evidence drained at teardown.
+import { setTimeout as delay } from "node:timers/promises";
+import { buildOriginMap } from "../../../comms/capture-surface.js";
+import { FakeInbox } from "../../../comms/fake-inbox.js";
+import { deployReceivingInbox } from "../../../comms/receiving-surface.js";
+import { DEFAULT_SANDBOX_CATCH_PORT, collectCommsThread, deployCommsCatch, refreshInboxSurface, writeInboxSurface, } from "../../../comms/sandbox-catch.js";
+import { redactText, toErrorMessage } from "../../../evidence/redaction.js";
+import { writeContainedOutputFile } from "../../../run/contained-output.js";
+import { inboxRecipientFor, participantHasInboxRecipient } from "../participant-desktop.js";
+import { addressedRecipients } from "../../../lab/parse/comms.js";
+/** Mid-run inbox-surface render cadence (ms). Coarse enough that the per-tick `cat` + file writes stay
+ *  cheap; fine enough that a verification email is visible seconds after the app sends it. */
+const INBOX_SURFACE_CADENCE_MS = 2500;
+/**
+ * On an in-sandbox subject route, redirect the app's email-API sends into an in-sandbox catch
+ * (loopback) so its verification mail is CAPTURED, not sent to the internet. Undefined when the
+ * lab declares no fake email, which leaves the lane unchanged.
+ */
+export function planParticipantComms(config, targetUrl, inSandboxSubject) {
+    const email = inSandboxSubject && config.comms?.email?.kind === "fake" ? config.comms.email : undefined;
+    if (email === undefined)
+        return undefined;
+    const port = email.port ?? DEFAULT_SANDBOX_CATCH_PORT;
+    // The origin-rewrite map is identity on this same-sandbox route, but covers localhost/0.0.0.0
+    // alias skew and an operator-declared linkOrigin.
+    return {
+        email,
+        port,
+        smtpPort: email.smtp?.port,
+        inboxUrl: `http://127.0.0.1:${port}/inbox`,
+        originMap: buildOriginMap({
+            ...(config.subject.serve?.url === undefined
+                ? {}
+                : { internalServeUrl: config.subject.serve.url }),
+            reachableBaseUrl: targetUrl,
+            ...(email.linkOrigin === undefined ? {} : { linkOrigin: email.linkOrigin }),
+        }),
+        surfaceRecipients: addressedRecipients(email),
+    };
+}
+/** The env the subject app reads to reach the catch, injected at sandbox create so it boots with it. */
+export function participantCommsEnv(comms) {
+    if (comms === undefined)
+        return {};
+    // injectEnv is absent on an adopter-hosted plane (#328): there is no subject env to inject
+    // because the operator points their own app at their own catch.
+    const env = comms.email.injectEnv === undefined
+        ? {}
+        : { [comms.email.injectEnv]: `http://127.0.0.1:${comms.port}` };
+    // SMTP transport: the same idea as injectEnv, but an app that speaks SMTP needs a host and a port
+    // rather than a base URL. The catch accepts any credentials (loopback only), yet many apps refuse
+    // to boot unless the user/password vars exist at all, so those are injected when declared.
+    const smtp = comms.email.smtp;
+    if (smtp && comms.smtpPort !== undefined) {
+        env[smtp.hostEnv] = "127.0.0.1";
+        env[smtp.portEnv] = String(comms.smtpPort);
+        if (smtp.userEnv)
+            env[smtp.userEnv] = smtp.user ?? "humanish";
+        if (smtp.passwordEnv)
+            env[smtp.passwordEnv] = smtp.password ?? "humanish";
+    }
+    return env;
+}
+/**
+ * Start the in-sandbox email catch before the subject serve, so the app's send-API base URL
+ * resolves the moment it boots. A comms-declared lab that cannot stand the catch up fails closed
+ * rather than silently sending real mail.
+ */
+export async function startCommsCatch(shell, comms, requestTimeoutMs) {
+    const deployed = await deployCommsCatch(shell, {
+        port: comms.port,
+        ...(comms.smtpPort === undefined ? {} : { smtpPort: comms.smtpPort }),
+        requestTimeoutMs,
+    });
+    if (!deployed.ready) {
+        throw new Error(`comms email catch did not become ready on 127.0.0.1:${comms.port} in the subject sandbox`);
+    }
+    // Write the EMPTY inbox once up front so the persona's /inbox always resolves to the "No messages
+    // yet." page — never a bare 404 — the instant it navigates there, even before any mail arrives OR if
+    // the app sends to an address no declared recipient matches (the loop only re-renders on new mail).
+    await writeInboxSurface(shell, deployed.surfaceDir, [], {
+        originMap: comms.originMap,
+        requestTimeoutMs,
+    });
+    // The surface uses its OWN FakeInbox + cursor, independent of the teardown evidence drain (two
+    // readers of the append-only NDJSON — no double-count).
+    const stop = new AbortController();
+    let renderedCount = 0;
+    const loop = (async () => {
+        // Render-first (so even a short session gets a populated inbox), then refresh on a cadence. The
+        // cadence uses a REAL timer, NOT the injected instant clock: this loop is unbounded, so an instant
+        // sleep would busy-spin and starve the session's own timers. `stop` interrupts the wait
+        // (and clears the timer) so teardown never blocks for a full cadence. Each refresh
+        // is a full, idempotent rebuild; `renderedCount` only advances on a SUCCESSFUL render so a
+        // transient failure retries cleanly (no duplicate emails).
+        for (;;) {
+            try {
+                const refreshed = await refreshInboxSurface({
+                    shell,
+                    deployed,
+                    recipients: comms.surfaceRecipients,
+                    sinceCount: renderedCount,
+                    originMap: comms.originMap,
+                    requestTimeoutMs,
+                });
+                if (refreshed.rendered)
+                    renderedCount = refreshed.count;
+            }
+            catch {
+                // Never throw into the render loop; the teardown drain + by-id teardown must still run.
+            }
+            if (stop.signal.aborted)
+                break;
+            await delay(INBOX_SURFACE_CADENCE_MS, undefined, { signal: stop.signal }).catch(() => undefined);
+            if (stop.signal.aborted)
+                break;
+        }
+    })();
+    return {
+        deployed,
+        async stopSurface() {
+            stop.abort();
+            await loop.catch(() => undefined);
+        },
+    };
+}
+/** Stand up the real-email receiving surface and attach it to the lane; returns the inbox URL. */
+export async function attachReceivingInbox(shell, spec, deps, targetUrl) {
+    const { config } = deps;
+    const surface = await deployReceivingInbox(shell, {
+        leaseId: spec.streamId,
+        requestTimeoutMs: Math.min(deps.requestTimeoutMs, 30_000),
+    });
+    const email = config.comms?.email;
+    try {
+        await deps.receiving.attach(spec.planned.id, {
+            surface,
+            allowedOrigins: [...new Set([new URL(targetUrl).origin, ...(email?.allowedOrigins ?? [])])],
+            originMap: buildOriginMap({
+                ...(config.subject.serve?.url === undefined
+                    ? {}
+                    : { internalServeUrl: config.subject.serve.url }),
+                reachableBaseUrl: targetUrl,
+                ...(email?.linkOrigin === undefined ? {} : { linkOrigin: email.linkOrigin }),
+            }),
+        });
+    }
+    catch (error) {
+        await surface.stop().catch(() => { });
+        throw error;
+    }
+    return surface.url;
+}
+function optionalAddress(address) {
+    return address === undefined ? {} : { address };
+}
+/** The inbox the persona is told about: real receiving, the captured catch, or an external inbox. */
+export function participantInbox(args) {
+    const { spec, deps, receivingInboxUrl, comms } = args;
+    if (deps.receiving && receivingInboxUrl)
+        return {
+            url: receivingInboxUrl,
+            address: deps.receiving.address(spec.planned.id),
+            receiving: true,
+        };
+    if (comms && args.catchReady && participantHasInboxRecipient(comms.email, spec.planned.id))
+        return {
+            url: comms.inboxUrl,
+            ...optionalAddress(inboxRecipientFor(comms.email, spec.planned.id)?.address),
+        };
+    if (deps.externalComms && participantHasInboxRecipient(deps.externalComms.email, spec.planned.id))
+        return {
+            url: deps.externalComms.inboxUrl,
+            ...optionalAddress(inboxRecipientFor(deps.externalComms.email, spec.planned.id)?.address),
+        };
+    return undefined;
+}
+/**
+ * Before this lane's sandbox is torn down, drain everything the in-sandbox catch captured, route it
+ * into a host fake inbox addressed to the declared recipients, and write the digest-only thread
+ * artifact. Returns the artifact path when one was written. A drain failure is a warning and never
+ * breaks teardown: the sandbox must still be killed either way.
+ */
+export async function drainCommsEvidence(args) {
+    const { comms, deps, spec, warnings } = args;
+    try {
+        const commsChannel = new FakeInbox();
+        const commsInboxes = [];
+        for (const recipient of addressedRecipients(comms.email)) {
+            commsInboxes.push(await commsChannel.provisionAddress(recipient.participantId, recipient.address));
+        }
+        const collected = await collectCommsThread({
+            shell: args.shell,
+            deployed: args.deployed,
+            channel: commsChannel,
+            inboxes: commsInboxes,
+            requestTimeoutMs: deps.requestTimeoutMs,
+        });
+        if (collected.artifact) {
+            const path = deps.participantCount === 1 ? "comms/thread.json" : `comms/${spec.streamId}.thread.json`;
+            await writeContainedOutputFile(deps.artifactRoot, path, `${JSON.stringify(collected.artifact, null, 2)}\n`, "utf8");
+            return path;
+        }
+        if (collected.captured > 0) {
+            // Captured mail that matched no declared recipient must not vanish silently (invariant 6:
+            // honest signals): tell the operator to declare comms.email.recipients[].address to match
+            // the address the app actually sends to (e.g. the one the persona surface will sign up with).
+            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 {
+            // Zero captures is the silent-broken shape (#351): the app never posted to the catch at
+            // all, so the personas stared at an empty inbox. Most common cause: the app does not
+            // actually read the declared injectEnv var for its email API base URL.
+            const transportHint = comms.email.smtp
+                ? `Verify the app reads ${comms.email.smtp.hostEnv}/${comms.email.smtp.portEnv} for its SMTP host and port`
+                : `Verify the app reads ${comms.email.injectEnv} for its email API base URL (an SDK that ignores it sends real mail or throws)`;
+            warnings.push(`Comms catch captured ZERO email sends — the app never delivered mail through the catch. ${transportHint} and that the flow reached an email step.`);
+        }
+    }
+    catch (error) {
+        warnings.push(`Comms evidence collection failed (run continues; sandbox still torn down): ${redactText(deps.scrubKnownValues(toErrorMessage(error)))}`);
+    }
+    return undefined;
+}

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

@@ -0,0 +1,3 @@
+import type { ParticipantDesktop } from "../participant-desktop.js";
+import type { CuaParticipantDeps, DesktopParticipantRun } from "../types.js";
+export declare function createE2BParticipantDesktop(spec: DesktopParticipantRun, deps: CuaParticipantDeps, warnings: string[]): ParticipantDesktop;

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

@@ -0,0 +1,91 @@
+// E2B owns provisioning and final evidence; the participant runner only uses the ready port. The
+// lane's steps live in prepare.ts, start.ts and teardown.ts beside this file, and fill the state
+// record in state.ts in the order below.
+import { defaultSubjectPhaseSink } from "../../../subject/steps.js";
+import { createE2BDesktopExecutor } from "../../../substrates/e2b/desktop-executor.js";
+import { participantInbox, planParticipantComms } from "./comms.js";
+import { participantBrowserStateObserver } from "./fidelity.js";
+import { acquireParticipantDesktop, provisionParticipantSubject, verifyParticipantScreen, } from "./prepare.js";
+import { openParticipantSurface, startParticipantMedia, startParticipantStream } from "./start.js";
+import { desktopEvidenceOf, newParticipantState } from "./state.js";
+import { finishE2BDesktop } from "./teardown.js";
+export function createE2BParticipantDesktop(spec, deps, warnings) {
+    const targetUrl = spec.planned.targetUrl ?? deps.appUrl;
+    const state = newParticipantState(spec);
+    const ctx = {
+        spec,
+        deps,
+        warnings,
+        targetUrl,
+        desktopCliRoute: deps.desktopCliRoute === true,
+        // Off-app comms (#297): gated entirely on config.comms; no comms declared, no change.
+        comms: planParticipantComms(deps.config, targetUrl, deps.cloneRoute || deps.localTreeRoute === true),
+        // The default or injected sink sees every event, started and completed alike, so an operator
+        // watching stderr sees both halves of each phase; the state keeps only completed ones.
+        onSubjectPhase: (event) => {
+            if (event.ok !== undefined)
+                state.phaseRecords.push(event);
+            (deps.hooks.onPhase ?? defaultSubjectPhaseSink)(event, {
+                laneId: spec.planned.id,
+                laneIndex: spec.planned.index,
+                laneCount: deps.participantCount,
+            });
+        },
+    };
+    let preparationStarted = false;
+    let prepared = false;
+    let opened = false;
+    let finalization;
+    async function prepare() {
+        if (preparationStarted || finalization)
+            throw new Error("Participant desktop preparation can only start once, before finalization.");
+        preparationStarted = true;
+        const desktop = await acquireParticipantDesktop(ctx, state);
+        // The device claim is verified in the sandbox, and fails closed.
+        await verifyParticipantScreen(ctx, state, desktop);
+        await provisionParticipantSubject(ctx, state, desktop);
+        await startParticipantMedia(ctx, state, desktop);
+        await openParticipantSurface(ctx, state, desktop);
+        prepared = true;
+    }
+    async function openSession() {
+        const { desktop, allocation } = state;
+        if (!prepared || !desktop || !allocation || opened || finalization)
+            throw new Error("The participant desktop must be prepared and may only be opened once, before finalization.");
+        opened = true;
+        await startParticipantStream(ctx, state, desktop);
+        const inbox = participantInbox({
+            spec,
+            deps,
+            receivingInboxUrl: state.receivingInboxUrl,
+            comms: ctx.comms,
+            catchReady: state.commsCatch?.deployed.ready === true,
+        });
+        const executor = createE2BDesktopExecutor(desktop, state.launchedBrowserFamily === "chromium"
+            ? {
+                observeBrowserState: participantBrowserStateObserver({
+                    desktop,
+                    spec,
+                    deps,
+                    targetUrl,
+                    launchIdentity: state.browserLaunchIdentity,
+                    targetId: state.browserTargetId,
+                    fidelity: state.fidelity,
+                    warnings,
+                }),
+            }
+            : {});
+        return {
+            executor: allocation.open(state.speech?.wrap(executor) ?? executor).executor,
+            ...(inbox === undefined ? {} : { inbox }),
+        };
+    }
+    return {
+        prepare,
+        openSession,
+        snapshot: () => desktopEvidenceOf(state),
+        finalize({ failed }) {
+            return (finalization ??= finishE2BDesktop(ctx, state, failed));
+        },
+    };
+}

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

@@ -0,0 +1,65 @@
+import type { LabConfig } from "../../../lab/types.js";
+import type { RunDesktopGeometry } from "../../../run/streams.js";
+import type { DesktopBrowserFamily, DesktopBrowserLaunchIdentity } from "../../../substrates/e2b/desktop-browser.js";
+import { makeChromeBrowserStateObserver } from "../../../substrates/e2b/desktop-cdp.js";
+import { captureDesktopBrowserGeometry } from "../../../substrates/e2b/desktop-geometry.js";
+import type { E2BDesktopSandbox } from "../../../substrates/e2b/sdk.js";
+import type { CuaParticipantDeps, DesktopParticipantRun } from "../types.js";
+type BrowserGeometry = Awaited<ReturnType<typeof captureDesktopBrowserGeometry>>;
+/** The mobile emulation a lane applied, updated as later tabs are covered and at teardown. */
+export interface ParticipantFidelity {
+    applied: RunDesktopGeometry["fidelity"] | undefined;
+    emulatedTargetId: string | undefined;
+    holderName: string | undefined;
+}
+/** Only lanes on a mobile preset are emulated; the flags go on the browser command line. */
+export declare function mobileLaunchFlags(config: LabConfig, spec: DesktopParticipantRun): string[];
+/**
+ * Apply mobile fidelity to the launch page before the geometry capture and the participant's first
+ * observation. A request that cannot be applied fails the lane closed with the reason. Only lanes on
+ * a mobile preset are emulated: a run-wide flag must not hand a desktop or tablet lane an iPhone
+ * user agent (the first live proof did exactly that to the desktop newcomer beside the phone lane).
+ * Those lanes carry no fidelity block, which is honest.
+ */
+export declare function applyParticipantMobileFidelity(args: {
+    desktop: E2BDesktopSandbox;
+    spec: DesktopParticipantRun;
+    deps: CuaParticipantDeps;
+    targetUrl: string;
+    browserFamily: DesktopBrowserFamily;
+    launchIdentity: DesktopBrowserLaunchIdentity | undefined;
+    targetId: string | undefined;
+    warnings: string[];
+}): Promise<ParticipantFidelity>;
+/** The Chrome observer behind URL/text stop conditions and task criteria, watching for emulation drift. */
+export declare function participantBrowserStateObserver(args: {
+    desktop: E2BDesktopSandbox;
+    spec: DesktopParticipantRun;
+    deps: CuaParticipantDeps;
+    targetUrl: string;
+    launchIdentity: DesktopBrowserLaunchIdentity | undefined;
+    targetId: string | undefined;
+    fidelity: ParticipantFidelity;
+    warnings: string[];
+}): ReturnType<typeof makeChromeBrowserStateObserver>;
+/**
+ * The lane's final browser geometry, measured while the sandbox is alive. A final capture that
+ * measured EITHER field wins whole, so a partial final capture omits fields the launch-time capture
+ * had (honest omission); only a final capture that measured NOTHING falls back to the launch-time
+ * capture. Also reads the emulation holder's log into the fidelity block.
+ */
+export declare function finalParticipantGeometry(args: {
+    desktop: E2BDesktopSandbox;
+    spec: DesktopParticipantRun;
+    deps: CuaParticipantDeps;
+    targetUrl: string;
+    browserFamily: DesktopBrowserFamily;
+    launchIdentity: DesktopBrowserLaunchIdentity | undefined;
+    windowId: string | undefined;
+    targetId: string | undefined;
+    initial: BrowserGeometry | undefined;
+    geometry: RunDesktopGeometry;
+    fidelity: ParticipantFidelity;
+    warnings: string[];
+}): Promise<RunDesktopGeometry>;
+export {};

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

@@ -0,0 +1,156 @@
+// Device fidelity for one E2B desktop lane: mobile emulation beyond viewport size (#221), the
+// browser-state observer that watches it for drift (#623), and the final browser geometry.
+import { redactText, toErrorMessage } from "../../../evidence/redaction.js";
+import { readDetachedLog } from "../../../substrates/detached.js";
+import { applyMobileEmulation, DEFAULT_MOBILE_USER_AGENT, makeChromeBrowserStateObserver, } from "../../../substrates/e2b/desktop-cdp.js";
+import { captureDesktopBrowserGeometry } from "../../../substrates/e2b/desktop-geometry.js";
+import { e2bShell } from "../../../substrates/e2b/shell.js";
+/** Only lanes on a mobile preset are emulated; the flags go on the browser command line. */
+export function mobileLaunchFlags(config, spec) {
+    const requested = config.execution?.desktop?.fidelity;
+    if (!requested?.mobileEmulation || !spec.planned.device.preset.isMobile)
+        return [];
+    return [
+        `--user-agent=${requested.userAgent ?? DEFAULT_MOBILE_USER_AGENT}`,
+        ...(requested.touch === false ? [] : ["--touch-events=enabled"]),
+    ];
+}
+/** The launched browser's DevTools address, as far as the launch recorded it. */
+function cdpEndpoint(identity, targetUrl) {
+    return {
+        ...(identity?.cdpPort === undefined ? {} : { cdpPort: identity.cdpPort }),
+        ...(identity?.profileDir === undefined ? {} : { profileDir: identity.profileDir }),
+        targetUrl,
+    };
+}
+/**
+ * Apply mobile fidelity to the launch page before the geometry capture and the participant's first
+ * observation. A request that cannot be applied fails the lane closed with the reason. Only lanes on
+ * a mobile preset are emulated: a run-wide flag must not hand a desktop or tablet lane an iPhone
+ * user agent (the first live proof did exactly that to the desktop newcomer beside the phone lane).
+ * Those lanes carry no fidelity block, which is honest.
+ */
+export async function applyParticipantMobileFidelity(args) {
+    const { spec, deps } = args;
+    const request = deps.config.execution?.desktop?.fidelity;
+    const none = {
+        applied: undefined,
+        emulatedTargetId: undefined,
+        holderName: undefined,
+    };
+    if (!request?.mobileEmulation || !spec.planned.device.preset.isMobile)
+        return none;
+    if (args.browserFamily !== "chromium") {
+        throw new Error(`execution.desktop.fidelity.mobileEmulation needs Chrome or Chromium for participant ${spec.planned.id}; the launched browser family is ${args.browserFamily}. Set execution.desktop.browser: chrome.`);
+    }
+    const applied = await applyMobileEmulation(args.desktop, deps.requestTimeoutMs, cdpEndpoint(args.launchIdentity, args.targetUrl), {
+        width: spec.planned.device.preset.width,
+        height: spec.planned.device.preset.height,
+        deviceScaleFactor: request.deviceScaleFactor ?? spec.planned.device.preset.deviceScaleFactor,
+        touch: request.touch ?? true,
+        userAgent: request.userAgent ?? DEFAULT_MOBILE_USER_AGENT,
+    }, { targetId: args.targetId });
+    args.warnings.push(...applied.warnings);
+    return {
+        applied: applied.fidelity,
+        emulatedTargetId: applied.targetId,
+        holderName: applied.holderName,
+    };
+}
+/** The Chrome observer behind URL/text stop conditions and task criteria, watching for emulation drift. */
+export function participantBrowserStateObserver(args) {
+    const { spec, deps, fidelity, warnings } = args;
+    return makeChromeBrowserStateObserver(args.desktop, deps.requestTimeoutMs, cdpEndpoint(args.launchIdentity, args.targetUrl), {
+        targetId: args.targetId,
+        // Once per lane: a dark observation channel is a gap in the instrument, and the
+        // funnel's NEVER MEASURED count needs this line to explain itself (#514).
+        onUnavailable: (reason) => {
+            warnings.push(`Browser-state observer unavailable for participant ${spec.planned.id} (${redactText(deps.scrubKnownValues(reason))}); ` +
+                "urlIncludes/urlPathEquals/textIncludes stop conditions and task criteria are NOT being measured this session.");
+        },
+        drift: fidelity.emulatedTargetId === undefined
+            ? undefined
+            : {
+                emulatedTargetId: fidelity.emulatedTargetId,
+                expectedWidth: spec.planned.device.preset.width,
+                expectTouch: fidelity.applied?.requested.touch === true,
+                onDrift: (reason) => {
+                    warnings.push(`Mobile emulation drift for participant ${spec.planned.id}: ${reason} (#623).`);
+                },
+                onCovered: (coveredTargetId, read) => {
+                    // A later tab the page itself reported at the phone width: evidence that
+                    // the emulation followed the participant (#623), kept on the bundle.
+                    if (fidelity.applied === undefined)
+                        return;
+                    fidelity.applied = {
+                        ...fidelity.applied,
+                        laterTargets: [
+                            ...(fidelity.applied.laterTargets ?? []),
+                            { targetId: coveredTargetId, ...read },
+                        ],
+                    };
+                },
+            },
+    });
+}
+/**
+ * The lane's final browser geometry, measured while the sandbox is alive. A final capture that
+ * measured EITHER field wins whole, so a partial final capture omits fields the launch-time capture
+ * had (honest omission); only a final capture that measured NOTHING falls back to the launch-time
+ * capture. Also reads the emulation holder's log into the fidelity block.
+ */
+export async function finalParticipantGeometry(args) {
+    const { desktop, spec, deps, fidelity, warnings } = args;
+    const finalGeometry = await captureDesktopBrowserGeometry({
+        desktop,
+        browserFamily: args.browserFamily,
+        ...(args.launchIdentity === undefined ? {} : { launchIdentity: args.launchIdentity }),
+        ...(args.windowId === undefined ? {} : { browserWindowId: args.windowId }),
+        ...(args.targetId === undefined ? {} : { browserTargetId: args.targetId }),
+        participantId: spec.planned.id,
+        targetUrl: args.targetUrl,
+        requestedScreen: spec.planned.device.resolution,
+        requestTimeoutMs: deps.requestTimeoutMs,
+        pagePreference: "active",
+        resize: false,
+    }).catch((error) => ({
+        warnings: [
+            `Final browser geometry measurement failed for participant ${spec.planned.id}: ${redactText(deps.scrubKnownValues(toErrorMessage(error)))}`,
+        ],
+    }));
+    const chosenGeometry = finalGeometry.browserWindow !== undefined || finalGeometry.viewport !== undefined
+        ? finalGeometry
+        : (args.initial ?? finalGeometry);
+    const geometryWarnings = [
+        ...new Set([...(args.initial?.warnings ?? []), ...chosenGeometry.warnings].map((warning) => deps.scrubKnownValues(warning))),
+    ];
+    warnings.push(...geometryWarnings);
+    // The emulation holder's own log, after its announce line: which later targets it
+    // attached to, what it sent, and any reply that came back as an error (#623). Read while
+    // the sandbox is alive; the first live proof had no way to say what the holder did.
+    if (fidelity.applied !== undefined && fidelity.holderName !== undefined) {
+        const holderLog = await readDetachedLog(e2bShell(desktop), fidelity.holderName, deps.requestTimeoutMs).catch(() => "");
+        const lines = holderLog
+            .split("\n")
+            .map((line) => line.trim())
+            .filter((line) => line.startsWith("{"))
+            .slice(1, 51);
+        if (lines.length > 0)
+            fidelity.applied = {
+                ...fidelity.applied,
+                holderLog: lines.map((line) => deps.scrubKnownValues(line)),
+            };
+    }
+    const geometry = args.geometry;
+    return {
+        screen: geometry.screen,
+        ...(chosenGeometry.browserWindow === undefined
+            ? {}
+            : { browserWindow: chosenGeometry.browserWindow }),
+        ...(chosenGeometry.viewport === undefined ? {} : { viewport: chosenGeometry.viewport }),
+        ...(fidelity.applied === undefined ? {} : { fidelity: fidelity.applied }),
+        ...((geometry.warnings?.length ?? 0) + geometryWarnings.length === 0
+            ? {}
+            : { warnings: [...(geometry.warnings ?? []), ...geometryWarnings] }),
+    };
+}

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

@@ -0,0 +1,18 @@
+import { type E2BDesktopSandbox } from "../../../substrates/e2b/sdk.js";
+import type { E2BParticipantContext, E2BParticipantState } from "./state.js";
+export declare const CUA_ACTOR_LAB_PROVIDER_METADATA: {
+    readonly mode: "cua-actor-lab";
+    readonly 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.
+ */
+export declare function acquireParticipantDesktop(ctx: E2BParticipantContext, state: E2BParticipantState): Promise<E2BDesktopSandbox>;
+/**
+ * Verify the lane's screen in the sandbox. A mismatch fails the lane closed unless the run records
+ * requested and verified geometry side by side.
+ */
+export declare function verifyParticipantScreen(ctx: E2BParticipantContext, state: E2BParticipantState, desktop: E2BDesktopSandbox): Promise<void>;
+/** Install a desktop CLI, or clone or unpack the subject and serve it, in the sandbox. */
+export declare function provisionParticipantSubject(ctx: E2BParticipantContext, state: E2BParticipantState, desktop: E2BDesktopSandbox): Promise<void>;