humanish 0.139.0 → 0.140.0

package/dist/guest/bootstrap.js

@@ -3,9 +3,10 @@ import { validateBrowserControlIdentity, sameBrowserControlIdentity, } from "../
 import { ComputerUseExecutorError } from "../actors/computer-use/executor-error.js";
 import { createBrowserControlClient } from "../browser-control/client.js";
 import { guestMediaConfigSchema } from "./media-config.js";
+import { guestDisplayConfigSchema } from "./display-config.js";
 export const GUEST_BOOTSTRAP_VERSION = 1;
 export const GUEST_BOOTSTRAP_LIMITS = Object.freeze({
-    bytes: 65_536 + 1024,
+    bytes: 65_536 + 2048,
     readyBytes: 1024,
     initialUrlBytes: 65_536,
     admissionMs: 5000,
@@ -42,7 +43,7 @@ export function guestReadyTimeoutMs(initialUrl) {
             ? 0
             : GUEST_BOOTSTRAP_LIMITS.navigationMs + GUEST_BOOTSTRAP_LIMITS.paintMs));
 }
-function canonical(identity, ready, initialUrl, media, recording) {
+function canonical(identity, ready, initialUrl, media, recording, display) {
     const { generation, challenge, runtimeRevision } = validateBrowserControlIdentity(identity);
     const fixed = { generation, challenge, runtimeRevision };
     if (initialUrl !== undefined && (ready || validateGuestInitialUrl(initialUrl) !== initialUrl))
@@ -52,6 +53,8 @@ function canonical(identity, ready, initialUrl, media, recording) {
     if (recording !== undefined &&
         (ready || !desktopRecordingConfigSchema.safeParse(recording).success))
         throw refused();
+    if (display !== undefined && (ready || !guestDisplayConfigSchema.safeParse(display).success))
+        throw refused();
     return JSON.stringify(ready
         ? { version: 1, ready: true, identity: fixed }
         : {
@@ -62,10 +65,11 @@ function canonical(identity, ready, initialUrl, media, recording) {
             ...(recording === undefined
                 ? {}
                 : { recording: desktopRecordingConfigSchema.parse(recording) }),
+            ...(display === undefined ? {} : { display: guestDisplayConfigSchema.parse(display) }),
         });
 }
-export function encodeGuestBootstrap(identity, ready = false, initialUrl, media, recording) {
-    const bytes = Buffer.from(canonical(identity, ready, initialUrl, media, recording));
+export function encodeGuestBootstrap(identity, ready = false, initialUrl, media, recording, display) {
+    const bytes = Buffer.from(canonical(identity, ready, initialUrl, media, recording, display));
     if (bytes.length > (ready ? GUEST_BOOTSTRAP_LIMITS.readyBytes : GUEST_BOOTSTRAP_LIMITS.bytes))
         throw refused();
     const frame = Buffer.alloc(4 + bytes.length);
@@ -89,16 +93,18 @@ function parseBootstrap(bytes, revision, ready) {
         const initialUrl = "initialUrl" in value ? value.initialUrl : undefined;
         const media = "media" in value ? guestMediaConfigSchema.parse(value.media) : undefined;
         const recording = "recording" in value ? desktopRecordingConfigSchema.parse(value.recording) : undefined;
+        const display = "display" in value ? guestDisplayConfigSchema.parse(value.display) : undefined;
         if (initialUrl !== undefined && typeof initialUrl !== "string")
             throw refused();
         if (identity.runtimeRevision !== revision ||
-            canonical(identity, ready, initialUrl, media, recording) !== bytes.toString("ascii"))
+            canonical(identity, ready, initialUrl, media, recording, display) !== bytes.toString("ascii"))
             throw refused();
         return {
             identity,
             ...(initialUrl === undefined ? {} : { initialUrl }),
             ...(media === undefined ? {} : { media }),
             ...(recording === undefined ? {} : { recording }),
+            ...(display === undefined ? {} : { display }),
         };
     }
     catch {
@@ -116,6 +122,7 @@ export class GuestBootstrapReader {
     initialUrl;
     media;
     recording;
+    display;
     resolve;
     reject;
     header = Buffer.alloc(4);
@@ -190,6 +197,7 @@ export class GuestBootstrapReader {
                 this.initialUrl = parsed.initialUrl;
                 this.media = parsed.media;
                 this.recording = parsed.recording;
+                this.display = parsed.display;
                 this.admitted = true;
                 clearTimeout(this.timer);
                 this.resolve(parsed.identity);
@@ -244,9 +252,9 @@ export class GuestBootstrapReader {
     }
 }
 /** Fixed preface on an already acquired Firecracker stream; no path discovery/retry. */
-export async function connectGuestBootstrap(stream, identity, signal, initialUrl, media, recording) {
+export async function connectGuestBootstrap(stream, identity, signal, initialUrl, media, recording, display) {
     validateBrowserControlIdentity(identity);
-    const request = encodeGuestBootstrap(identity, false, initialUrl, media, recording);
+    const request = encodeGuestBootstrap(identity, false, initialUrl, media, recording, display);
     await new Promise((resolve, reject) => {
         let bytes = Buffer.alloc(0), done = false;
         const timer = setTimeout(() => finish(new ComputerUseExecutorError("deadline_exceeded", "not_dispatched")), GUEST_BOOTSTRAP_LIMITS.connectMs);

package/dist/guest/display-config.d.ts

@@ -0,0 +1,31 @@
+import { z } from "zod";
+/** The screen a guest starts when the bootstrap names none. */
+export declare const DEFAULT_GUEST_SCREEN: Readonly<{
+    width: 960;
+    height: 720;
+}>;
+/**
+ * The screens a guest admits. The narrowest is the narrowest window Chromium renders; the widest
+ * is the widest device preset. At 1920×1200 an uncompressed 24-bit frame is 6.9 MB, so every
+ * capture fits the 8 MiB browser-control PNG limit. Below 480 pixels high the page area under
+ * Chromium's toolbar is too short to use.
+ */
+export declare const GUEST_SCREEN_LIMITS: Readonly<{
+    minWidth: 500;
+    maxWidth: 1920;
+    minHeight: 480;
+    maxHeight: 1200;
+}>;
+/** One participant's Xvfb screen, and the mobile emulation its pages get, if any. */
+export declare const guestDisplayConfigSchema: z.ZodObject<{
+    width: z.ZodNumber;
+    height: z.ZodNumber;
+    mobileEmulation: z.ZodOptional<z.ZodObject<{
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+        deviceScaleFactor: z.ZodNumber;
+        touch: z.ZodBoolean;
+        userAgent: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type GuestDisplayConfig = z.infer<typeof guestDisplayConfigSchema>;

package/dist/guest/display-config.js

@@ -0,0 +1,35 @@
+import { z } from "zod";
+import { MIN_DESKTOP_RENDER_WIDTH } from "../study/device-presets.js";
+/** The screen a guest starts when the bootstrap names none. */
+export const DEFAULT_GUEST_SCREEN = Object.freeze({ width: 960, height: 720 });
+/**
+ * The screens a guest admits. The narrowest is the narrowest window Chromium renders; the widest
+ * is the widest device preset. At 1920×1200 an uncompressed 24-bit frame is 6.9 MB, so every
+ * capture fits the 8 MiB browser-control PNG limit. Below 480 pixels high the page area under
+ * Chromium's toolbar is too short to use.
+ */
+export const GUEST_SCREEN_LIMITS = Object.freeze({
+    minWidth: MIN_DESKTOP_RENDER_WIDTH,
+    maxWidth: 1920,
+    minHeight: 480,
+    maxHeight: 1200,
+});
+const side = (max) => z.number().int().min(1).max(max);
+/** One participant's Xvfb screen, and the mobile emulation its pages get, if any. */
+export const guestDisplayConfigSchema = z
+    .object({
+    width: z.number().int().min(GUEST_SCREEN_LIMITS.minWidth).max(GUEST_SCREEN_LIMITS.maxWidth),
+    height: z.number().int().min(GUEST_SCREEN_LIMITS.minHeight).max(GUEST_SCREEN_LIMITS.maxHeight),
+    mobileEmulation: z
+        .object({
+        width: side(GUEST_SCREEN_LIMITS.maxWidth),
+        height: side(GUEST_SCREEN_LIMITS.maxHeight),
+        deviceScaleFactor: z.number().positive().max(4),
+        touch: z.boolean(),
+        // The bootstrap frame is ASCII; a launch flag carries it too.
+        userAgent: z.string().regex(/^[\x20-\x7e]{1,512}$/),
+    })
+        .strict()
+        .optional(),
+})
+    .strict();

package/dist/guest/runtime-desktop.d.ts

@@ -1,5 +1,6 @@
 import { type Stats } from "node:fs";
 import { type BrowserContext, type Page } from "playwright-core";
+import { type GuestDisplayConfig } from "./display-config.js";
 import type { GuestRuntimeDesktop } from "./runtime.js";
 import type { GuestMediaConfig } from "./media-config.js";
 import { type GuestDesktopMediaOptions } from "./desktop-media.js";
@@ -10,7 +11,7 @@ export declare const GUEST_RUNTIME_PATHS: Readonly<{
     run: "/run/humanish";
     home: "/home/humanish";
 }>;
-export type GuestRuntimePhase = "layout" | "xauthority" | "display" | "window_manager" | "media" | "recording" | "browser" | "sandbox" | "focus" | "fixture" | "navigation";
+export type GuestRuntimePhase = "layout" | "xauthority" | "display" | "window_manager" | "media" | "recording" | "browser" | "sandbox" | "emulation" | "focus" | "fixture" | "navigation";
 /** Initial document only: do not wait for app data, subresources or network idle. */
 export declare function navigateGuestInitialPage(page: Pick<Page, "goto" | "waitForFunction">, initialUrl: string, signal: AbortSignal): Promise<void>;
 /** /run/humanish and /home/humanish: real directories private to the guest user. */
@@ -19,7 +20,11 @@ export declare function isPrivateGuestDirectory(stat: Pick<Stats, "isDirectory"
 export declare function isPinnedOpenboxConfig(stat: Pick<Stats, "isFile" | "uid" | "gid" | "nlink" | "size" | "mode">): boolean;
 /** chrome://sandbox must report every namespace and seccomp feature and the overall verdict. */
 export declare function isAdequatelySandboxed(report: string): boolean;
-export declare function chromiumLaunchArgs(media: GuestMediaConfig | undefined): string[];
+/**
+ * The window leaves 20 pixels above and below it on the participant's screen. A mobile participant's
+ * user agent and touch flags reach every page and worker; CDP emulation sets the viewport.
+ */
+export declare function chromiumLaunchArgs(media: GuestMediaConfig | undefined, display?: GuestDisplayConfig): string[];
 /** The devices to start; the permission policy only changes Chromium's flags. */
 export declare function desktopMediaRequest(media: GuestMediaConfig): GuestDesktopMediaOptions["media"];
 /** Audio needs Pulse, which only the microphone path starts. */
@@ -27,7 +32,7 @@ export declare function recorderAudio(recording: DesktopRecordingConfig, media:
     audioSources: DesktopRecordingAudioSource[];
     pulseReady: boolean;
 };
-/** Fixed guest layout with an optional admitted initial loopback app URL. */
+/** Fixed guest layout with an optional admitted initial loopback app URL and participant screen. */
 export declare function createGuestRuntimeDesktop(options: {
     signal: AbortSignal;
     onTerminal(): void;
@@ -35,6 +40,7 @@ export declare function createGuestRuntimeDesktop(options: {
     initialUrl?: string;
     media?: GuestMediaConfig;
     recording?: DesktopRecordingConfig;
+    display?: GuestDisplayConfig;
 }): Promise<GuestRuntimeDesktop & {
     readonly owner: {
         context: BrowserContext;

package/dist/guest/runtime-desktop.js

@@ -3,6 +3,8 @@ import { constants } from "node:fs";
 import { lstat, mkdir, open, rm } from "node:fs/promises";
 import { setTimeout as delay } from "node:timers/promises";
 import { chromium } from "playwright-core";
+import { DEFAULT_GUEST_SCREEN } from "./display-config.js";
+import { mobileEmulationCommands, mobileEmulationLaunchFlags, } from "../study/mobile-emulation.js";
 import { createGuestDesktopNativeTools } from "./desktop-native.js";
 import { createGuestChromiumText } from "./chromium-text.js";
 import { createGuestBrowserTools } from "./browser-tools.js";
@@ -33,16 +35,18 @@ const GUEST_RUNTIME_ENV = Object.freeze({
     TMPDIR: "/tmp",
 });
 const CONFIG_SHA = "4ae1c52eab748a3624b3948ce792647be258caba70c8c72038b9a43be6459552";
-const XVFB_ARGS = Object.freeze([
-    ":0",
-    "-screen",
-    "0",
-    "960x720x24",
-    "-nolisten",
-    "tcp",
-    "-auth",
-    GUEST_RUNTIME_ENV.XAUTHORITY,
-]);
+function xvfbArgs(screen) {
+    return [
+        ":0",
+        "-screen",
+        "0",
+        `${screen.width}x${screen.height}x24`,
+        "-nolisten",
+        "tcp",
+        "-auth",
+        GUEST_RUNTIME_ENV.XAUTHORITY,
+    ];
+}
 const SANDBOX_FEATURES = ["PID namespaces", "Network namespaces", "Seccomp-BPF sandbox"];
 const RECORDING_PATH = `${GUEST_RUNTIME_PATHS.home}/desktop-recording.mp4`;
 /** Initial document only: do not wait for app data, subresources or network idle. */
@@ -86,10 +90,16 @@ export function isAdequatelySandboxed(report) {
     return (SANDBOX_FEATURES.every((label) => new RegExp(label + "\\s+Yes").test(report)) &&
         report.includes("You are adequately sandboxed"));
 }
-export function chromiumLaunchArgs(media) {
+/**
+ * The window leaves 20 pixels above and below it on the participant's screen. A mobile participant's
+ * user agent and touch flags reach every page and worker; CDP emulation sets the viewport.
+ */
+export function chromiumLaunchArgs(media, display) {
+    const screen = display ?? DEFAULT_GUEST_SCREEN;
     return [
-        "--window-size=960,680",
+        `--window-size=${screen.width},${screen.height - 40}`,
         "--window-position=0,20",
+        ...mobileEmulationLaunchFlags(display?.mobileEmulation),
         "--disable-background-networking",
         "--disable-component-update",
         "--no-first-run",
@@ -162,12 +172,12 @@ async function waitForDisplay(processes, signal, check) {
     throw setupFailed();
 }
 /** A recorder that fails to start leaves the desktop usable; finishRecording reports it. */
-async function startGuestRecorder(recording, media, env, signal) {
+async function startGuestRecorder(recording, media, screen, env, signal) {
     try {
         return await startDesktopRecorder({
             display: ":0",
-            width: 960,
-            height: 720,
+            width: screen.width,
+            height: screen.height,
             outputPath: RECORDING_PATH,
             env,
             signal,
@@ -178,7 +188,7 @@ async function startGuestRecorder(recording, media, env, signal) {
         return undefined;
     }
 }
-async function launchGuestBrowser(state, media, check) {
+async function launchGuestBrowser(state, media, display, check) {
     state.pendingContext = chromium.launchPersistentContext(`${GUEST_RUNTIME_PATHS.home}/browser`, {
         executablePath: "/usr/bin/chromium",
         headless: false,
@@ -186,7 +196,7 @@ async function launchGuestBrowser(state, media, check) {
         viewport: null,
         env: state.recorder?.env ?? state.media?.env ?? GUEST_RUNTIME_ENV,
         timeout: 25_000,
-        args: chromiumLaunchArgs(media),
+        args: chromiumLaunchArgs(media, display),
     });
     // A browser that finishes launching after the stop is closed here; teardown may not see it.
     void state.pendingContext.then((browser) => {
@@ -216,6 +226,25 @@ async function verifyBrowserSandbox(context, page, check) {
     check();
     return report;
 }
+/** Sends the emulation commands over a page session that stays attached, so they hold. */
+async function emulateOn(context, page, request) {
+    const session = await context.newCDPSession(page);
+    for (const { method, params } of mobileEmulationCommands(request))
+        // Playwright types send by protocol method; these names come from the fixed list.
+        await session.send(method, params);
+}
+/**
+ * Emulate a phone on the launch page before it navigates, so the first document loads with the
+ * phone's viewport, touch and user agent. Tabs opened later get the same overrides when they open;
+ * a tab that closes before that is left alone.
+ */
+async function emulateMobile(browser, request, check) {
+    await emulateOn(browser.context, browser.page, request);
+    check();
+    browser.context.on("page", (page) => {
+        void emulateOn(browser.context, page, request).catch(() => { });
+    });
+}
 /** Text actions run only while the browser window that setup saw still has focus. */
 function focusGuard(native, window) {
     return async (actionSignal) => {
@@ -223,7 +252,7 @@ function focusGuard(native, window) {
             throw new ComputerUseExecutorError("action_rejected", "not_dispatched");
     };
 }
-async function createGuestExecutorFor(state, browser, signal, onTerminal, check) {
+async function createGuestExecutorFor(state, browser, screen, signal, onTerminal, check) {
     const native = createGuestDesktopNativeTools({
         display: ":0",
         temporaryDirectory: `${GUEST_RUNTIME_PATHS.run}/capture`,
@@ -236,8 +265,8 @@ async function createGuestExecutorFor(state, browser, signal, onTerminal, check)
         assertFocusedWindow: focusGuard(native, window),
     });
     return createGuestDesktopExecutor({
-        width: 960,
-        height: 720,
+        width: screen.width,
+        height: screen.height,
         tools: createGuestBrowserTools(native, state.content),
         authoritySignal: signal,
         onTerminal,
@@ -329,10 +358,11 @@ function closeGuestRuntimeDesktop(state, processes, controller, detach) {
     controller.abort();
     return state.closing;
 }
-/** Fixed guest layout with an optional admitted initial loopback app URL. */
+/** Fixed guest layout with an optional admitted initial loopback app URL and participant screen. */
 export async function createGuestRuntimeDesktop(options) {
     if (options.initialUrl !== undefined)
         validateGuestInitialUrl(options.initialUrl);
+    const screen = options.display ?? DEFAULT_GUEST_SCREEN;
     const controller = new AbortController();
     const signal = AbortSignal.any([options.signal, controller.signal]);
     const state = { stopping: false };
@@ -363,7 +393,7 @@ export async function createGuestRuntimeDesktop(options) {
         progress("xauthority");
         await authorizeDisplay(processes, check);
         progress("display");
-        processes.spawn("/usr/bin/Xvfb", XVFB_ARGS, undefined, true);
+        processes.spawn("/usr/bin/Xvfb", xvfbArgs(screen), undefined, true);
         await waitForDisplay(processes, signal, check);
         progress("window_manager");
         processes.spawn("/usr/bin/openbox", ["--config-file", `${GUEST_RUNTIME_PATHS.root}/openbox.xml`], undefined, true);
@@ -381,15 +411,19 @@ export async function createGuestRuntimeDesktop(options) {
         if (options.recording !== undefined) {
             progress("recording");
             const env = state.media?.env ?? GUEST_RUNTIME_ENV;
-            state.recorder = await startGuestRecorder(options.recording, options.media, env, signal);
+            state.recorder = await startGuestRecorder(options.recording, options.media, screen, env, signal);
             check();
         }
         progress("browser");
-        const browser = await launchGuestBrowser(state, options.media, check);
+        const browser = await launchGuestBrowser(state, options.media, options.display, check);
         progress("sandbox");
         const sandboxReport = await verifyBrowserSandbox(browser.context, browser.page, check);
+        if (options.display?.mobileEmulation !== undefined) {
+            progress("emulation");
+            await emulateMobile(browser, options.display.mobileEmulation, check);
+        }
         progress("focus");
-        const executor = await createGuestExecutorFor(state, browser, signal, options.onTerminal, check);
+        const executor = await createGuestExecutorFor(state, browser, screen, signal, options.onTerminal, check);
         if (options.initialUrl !== undefined) {
             progress("navigation");
             await navigateGuestInitialPage(browser.page, options.initialUrl, signal);

package/dist/guest/runtime.d.ts

@@ -1,6 +1,7 @@
 import type { Duplex, Readable } from "node:stream";
 import type { CuaExecutor } from "../actors/computer-use/loop.js";
 import type { GuestMediaConfig } from "./media-config.js";
+import type { GuestDisplayConfig } from "./display-config.js";
 import type { DesktopRecordingConfig, DesktopRecordingMetadata } from "../evidence/desktop-recording-types.js";
 export interface GuestRuntimeDesktop {
     executor: CuaExecutor;
@@ -18,7 +19,7 @@ export interface GuestRuntimeOptions {
     signal: AbortSignal;
     /** Fixed private supervision channel, not browser-control output. */
     marker(value: "A" | "R"): void;
-    createDesktop(signal: AbortSignal, onTerminal: () => void, initialUrl?: string, media?: GuestMediaConfig, recording?: DesktopRecordingConfig): Promise<GuestRuntimeDesktop>;
+    createDesktop(signal: AbortSignal, onTerminal: () => void, initialUrl?: string, media?: GuestMediaConfig, recording?: DesktopRecordingConfig, display?: GuestDisplayConfig): Promise<GuestRuntimeDesktop>;
 }
 /** One admitted desktop and one dispatcher. The owner retains physical teardown. */
 export declare function runGuestRuntime(options: GuestRuntimeOptions): Promise<{

package/dist/guest/runtime.js

@@ -83,7 +83,7 @@ export async function runGuestRuntime(options) {
             void close();
         }, guestReadyTimeoutMs(reader.initialUrl));
         options.marker("A");
-        preparing = options.createDesktop(authority, terminal, reader.initialUrl, reader.media, reader.recording);
+        preparing = options.createDesktop(authority, terminal, reader.initialUrl, reader.media, reader.recording, reader.display);
         desktop = await Promise.race([
             preparing,
             new Promise((_, reject) => {

package/dist/guest-runtime-main.js

@@ -27,12 +27,13 @@ try {
             if (writeSync(Number(markerFd), value) !== 1)
                 throw new Error();
         },
-        createDesktop: (signal, onTerminal, initialUrl, media, recording) => createGuestRuntimeDesktop({
+        createDesktop: (signal, onTerminal, initialUrl, media, recording, display) => createGuestRuntimeDesktop({
             signal,
             onTerminal,
             ...(initialUrl === undefined ? {} : { initialUrl }),
             ...(media === undefined ? {} : { media }),
             ...(recording === undefined ? {} : { recording }),
+            ...(display === undefined ? {} : { display }),
         }),
     });
     const result = await runtime.closed;

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

@@ -2,18 +2,17 @@
 // browser-state observer that watches it for drift, 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 { applyMobileEmulation, makeChromeBrowserStateObserver, } from "../../../substrates/e2b/desktop-cdp.js";
+import { mobileEmulationLaunchFlags, participantMobileEmulation, } from "../../../study/mobile-emulation.js";
 import { captureDesktopBrowserGeometry } from "../../../substrates/e2b/desktop-geometry.js";
 import { e2bShell } from "../../../substrates/e2b/shell.js";
+/** The participant's emulation request; see participantMobileEmulation for who gets one. */
+function emulationFor(residual, spec) {
+    return participantMobileEmulation(residual.execution?.desktop?.fidelity, spec.planned.device.preset);
+}
 /** Only participants on a mobile preset are emulated; the flags go on the browser command line. */
 export function mobileLaunchFlags(residual, spec) {
-    const requested = residual.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"]),
-    ];
+    return mobileEmulationLaunchFlags(emulationFor(residual, spec));
 }
 /** The launched browser's DevTools address, as far as the launch recorded it. */
 export function cdpEndpoint(identity, targetUrl) {
@@ -33,24 +32,18 @@ export function cdpEndpoint(identity, targetUrl) {
  */
 export async function applyParticipantMobileFidelity(args) {
     const { spec, deps } = args;
-    const request = deps.residual.execution?.desktop?.fidelity;
+    const request = emulationFor(deps.residual, spec);
     const none = {
         applied: undefined,
         emulatedTargetId: undefined,
         holderName: undefined,
     };
-    if (!request?.mobileEmulation || !spec.planned.device.preset.isMobile)
+    if (request === undefined)
         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,
-    }, {
+    const applied = await applyMobileEmulation(args.desktop, deps.requestTimeoutMs, cdpEndpoint(args.launchIdentity, args.targetUrl), request, {
         targetId: args.targetId,
         ...(args.network === undefined ? {} : { network: args.network.request }),
     });

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

@@ -3,7 +3,9 @@ import path from "node:path";
 import { participantList } from "../../study/study-fields.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 { localBrowserDefaults, localBrowserUnsupportedReason, localGuestDisplay, } from "../../substrates/local/runtime-config.js";
+import { mobileEmulationCommands } from "../../study/mobile-emulation.js";
+import { declaredScreenForRender } from "../../substrates/e2b/desktop-geometry.js";
 import { localRuntimeCapacity, prepareLocalRuntime } from "../../substrates/local/runtime.js";
 import { dockerCommandLine, usesLima } from "../../substrates/local/runtime-host.js";
 import { outOfMemoryMessage } from "../../substrates/local/capacity.js";
@@ -52,6 +54,30 @@ function mediaEvidence(media) {
         },
     };
 }
+/**
+ * The geometry a local participant records when its guest emulates a phone: the requested screen
+ * and the emulation the guest applied before the first page loaded. The guest does not read back
+ * what the page reports, so the block has no `resolved` part and says so.
+ */
+function emulatedGeometry(run, display) {
+    const { device } = run.planned;
+    const declared = declaredScreenForRender(device.preset, device.name, device.resolution);
+    const request = display.mobileEmulation;
+    return {
+        screen: {
+            requested: { width: display.width, height: display.height },
+            ...(declared === undefined ? {} : { declared }),
+        },
+        fidelity: {
+            tier: "mobile-emulated",
+            requested: request,
+            applied: mobileEmulationCommands(request).map((command) => command.method),
+        },
+        warnings: [
+            `Mobile emulation was applied for participant ${run.planned.id} in the local guest, which does not read back the page's own report; desktopGeometry.fidelity carries the request without a resolved block.`,
+        ],
+    };
+}
 /** One participant's Firecracker desktop and optional captured inbox, released in finalize. */
 function createLocalParticipantDesktop(context, run, warnings, artifactRoot) {
     const { config, media, recording, state } = context;
@@ -71,11 +97,13 @@ function createLocalParticipantDesktop(context, run, warnings, artifactRoot) {
             const runtime = await context.assets();
             if (address && email?.kind === "fake" && email.external)
                 inbox = await startLocalCapturedInbox(email.external, address);
+            const display = localGuestDisplay(config, run.planned.device);
             session = await createLocalFirecrackerDesktop({
                 assets: runtime,
                 ...(inbox ? { inboxUrl: inbox.url } : {}),
                 ...(media === undefined ? {} : { media }),
                 ...(recording === undefined ? {} : { recording }),
+                ...(display === undefined ? {} : { display }),
                 appUrl: run.planned.targetUrl ?? config.subject.appUrl,
                 outputRoot: path.join(context.cwd, ".humanish", "local-runtime"),
                 ...(context.signal === undefined ? {} : { signal: context.signal }),
@@ -83,6 +111,11 @@ function createLocalParticipantDesktop(context, run, warnings, artifactRoot) {
             state.sessions.push(session);
             if (media !== undefined)
                 evidence.desktopBrowser = mediaEvidence(media);
+            if (display?.mobileEmulation !== undefined)
+                evidence.desktopGeometry = emulatedGeometry(run, {
+                    ...display,
+                    mobileEmulation: display.mobileEmulation,
+                });
         },
         async openSession() {
             if (!session)

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

@@ -343,7 +343,7 @@ export function planComputerUseStudy(config, input) {
             ...(actor === undefined ? {} : { actor }),
         },
     });
-    const analysis = resolveAutomaticAnalysis(config.review?.analysis);
+    const analysis = resolveAutomaticAnalysis(config.review?.analysis, config.actor);
     if (!analysis.ok)
         return refuse("before-scope", "HUMANISH_STUDY_ANALYSIS_INVALID", analysis.message);
     const tasksReason = taskProtocolValidationReason(config, true);

package/dist/routes/scripted/plan.js

@@ -34,7 +34,7 @@ export function planScriptedStudy(config, input) {
     const beforeScope = { beforeScope: true };
     if (String(config.comms?.email?.kind) === "real")
         return refuse("HUMANISH_SCRIPTED_SCENARIO_INVALID", "Real email receiving is unsupported on the scripted route. Use a supported hosted computer-use browser study.", beforeScope);
-    const analysis = resolveAutomaticAnalysis(config.review?.analysis);
+    const analysis = resolveAutomaticAnalysis(config.review?.analysis, config.actor);
     if (!analysis.ok)
         return refuse("HUMANISH_STUDY_ANALYSIS_INVALID", analysis.message, beforeScope);
     const tasksReason = taskProtocolValidationReason(config, false);

package/dist/routes/shared-world/plan.js

@@ -38,7 +38,7 @@ export function planSharedWorldStudy(config, input) {
         networkCaptureValidationReason(config, "shared-world");
     if (mediaReason)
         return refuse(invalid, mediaReason);
-    const analysis = resolveAutomaticAnalysis(config.review?.analysis);
+    const analysis = resolveAutomaticAnalysis(config.review?.analysis, config.actor);
     if (!analysis.ok)
         return refuse("HUMANISH_STUDY_ANALYSIS_INVALID", analysis.message);
     const tasksReason = taskProtocolValidationReason(config, false);

package/dist/routes/terminal/plan.js

@@ -39,7 +39,7 @@ export function planTerminalStudy(config, input) {
     const modal = sandboxProvider === "modal" ? modalRefusal(config) : undefined;
     if (modal !== undefined)
         return refuse(modal.code, modal.message);
-    const analysis = resolveAutomaticAnalysis(config.review?.analysis);
+    const analysis = resolveAutomaticAnalysis(config.review?.analysis, config.actor);
     if (!analysis.ok)
         return refuse("HUMANISH_STUDY_ANALYSIS_INVALID", analysis.message);
     const tasksReason = taskProtocolValidationReason(config, false);

package/dist/run/route-shell.js

@@ -42,7 +42,7 @@ export async function admitRoute(shell) {
  * or default analysis is recorded as skipped.
  */
 export function completeRefusalAnalysis(refused, config, input) {
-    const analysis = resolveAutomaticAnalysis(config.review?.analysis);
+    const analysis = resolveAutomaticAnalysis(config.review?.analysis, config.actor);
     return completeAutomaticAnalysis(refused, undefined, analysis.ok ? analysis.config : undefined, input, { trigger: config.review?.analysis === undefined ? "default" : "explicit" });
 }
 /** A result as its route's outcome. StudyOutcome pairs each route with its result type. */

package/dist/study/doctor.d.ts

@@ -22,10 +22,13 @@ type CodexReadiness = {
     protocolIncompatibilities?: readonly string[];
     /** Schema values beyond the baseline, recorded by a launch that passed. */
     protocolAdditions?: readonly string[];
+    /** What in the operator's Codex setup the launch refused, without paths or values. */
+    refusalReason?: string;
 };
 /** What doctor's hosted Codex participant check found: a readiness result and what it admitted. */
 type HostedCodexReadiness = CodexReadiness & {
     cliVersion?: string;
+    operatorInstructionFiles?: readonly string[];
     resolvedModel?: string;
     authentication?: "chatgpt-account" | "api-key";
 };