humanish 0.139.1 → 0.140.0

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.js

@@ -1,5 +1,5 @@
 import path from "node:path";
-import { isLocalBrowserStudy } from "../substrates/local/runtime-config.js";
+import { isLocalBrowserStudy, localStudySetsScreens } from "../substrates/local/runtime-config.js";
 import { localRuntimeStatus } from "../substrates/local/runtime.js";
 import { capacityShortfall, describeCapacity, } from "../substrates/local/capacity.js";
 import { keyNamesOf, requiredKeys, requiredSubjectEnv } from "./requirements.js";
@@ -204,7 +204,7 @@ export async function studySetupChecks(args) {
     if (route === "scripted")
         checks.push(await scriptedBrowserCheck());
     checks.push(...subjectEnvChecks(requiredSubjectEnv(requirements), args));
-    const analysis = automaticAnalysisBudget(config.review?.analysis, route);
+    const analysis = automaticAnalysisBudget(config.review?.analysis, route, undefined, config.actor);
     if (analysis)
         checks.push(await analysisCheck(analysis, args, checkAccount));
     checks.push(checkScope(analysis));
@@ -231,10 +231,13 @@ async function localBrowserChecks(config, args, desktopsAtOnce) {
             media: config.execution?.desktop?.media !== undefined ||
                 config.execution?.desktop?.recording !== undefined,
         })))();
+    const screens = runtime.installed && runtime.assets?.displaySizes !== true && localStudySetsScreens(config)
+        ? "The installed local runtime starts every participant at 960×720, and this study sets other screen sizes. Omit device and resolution, use a hosted desktop, or set HUMANISH_LOCAL_RUNTIME_IMAGE to a runtime built from current source."
+        : undefined;
     checks.push({
         name: "local browser runtime",
-        ok: runtime.ok,
-        message: runtime.message,
+        ok: runtime.ok && screens === undefined,
+        message: screens ?? runtime.message,
         ...(runtime.ok && !runtime.installed ? { status: "note" } : {}),
     });
     if (runtime.capacity !== undefined && desktopsAtOnce !== undefined)
@@ -252,7 +255,9 @@ async function localBrowserChecks(config, args, desktopsAtOnce) {
     }
     return {
         checks,
-        ...(runtime.ok && runtime.installed ? {} : { next: runtime.message }),
+        ...(runtime.ok && runtime.installed && screens === undefined
+            ? {}
+            : { next: screens ?? runtime.message }),
     };
 }
 /** Whether the desktops the study runs at once fit the VM or this machine, and why. */
@@ -384,7 +389,7 @@ async function analysisCheck(analysis, args, checkAccount) {
         ...(keyed ? {} : { status: "note" }),
         message: keyed
             ? `OPENAI_API_KEY is present for the separate automatic analysis request; model access and quota are not tested. The analysis is refused before it starts if ${admissionRule(`$${analysis.maxCostUsd}`)}; this is not a billing cap. Participant readiness is independent.`
-            : "Will be skipped: OPENAI_API_KEY is missing. The participant may run, but there will be no automatic findings report. Add an OpenAI API key or set review.analysis: false deliberately.",
+            : "Will be skipped: OPENAI_API_KEY is missing. The participant may run, but there will be no automatic findings report. Add an OpenAI API key, or set review.analysis.provider: codex to have a signed-in Codex account analyze the run instead, or set review.analysis: false deliberately.",
     };
 }
 /** What doctor checked and what it did not. */

package/dist/study/init-templates.js

@@ -62,6 +62,7 @@ Studies:
 - private or machine-local studies live in ignored .humanish/studies/*.yaml or
   .humanish/local/studies/*.yaml;
 - run a study with \`${command} run <study>\`, or \`${command} watch <study>\` to stay attached;
+- a live run ends with findings from a separate analyst; \`${command} review --run latest\` shows them;
 - files under humanish/labs/ move there with \`${command} migrate\`.
 
 Format standard:
@@ -79,12 +80,17 @@ Format standard:
  */
 function tryLiveStudy(actor, localAgent = "codex") {
     const account = actor === "local-agent";
+    const analyst = localAgent === "codex"
+        ? `The analysis after the run uses the same Codex account. Set review.analysis: false to skip
+  it.`
+        : `When OPENAI_API_KEY is set, the analysis after the run bills it: humanish refuses that request
+  before it starts if its estimate is over $${DEFAULT_ANALYSIS_MAX_COST_USD}. With Codex also signed
+  in, review.analysis.provider: codex has its account analyze the run instead. Set
+  review.analysis: false to skip it.`;
     const needs = account
         ? `  Needs E2B_API_KEY and the coding agent signed in on this machine. Cost: one small task, a few
   E2B desktop minutes and the agent's account usage. humanish cannot put a dollar cap on account
-  usage, so the ten-minute session limit below bounds the run. When OPENAI_API_KEY is set, the
-  analysis after the run bills it: humanish refuses that request before it starts if its estimate
-  is over $${DEFAULT_ANALYSIS_MAX_COST_USD}. Set review.analysis: false to skip it.`
+  usage, so the ten-minute session limit below bounds the run. ${analyst}`
         : `  Needs E2B_API_KEY and OPENAI_API_KEY. Cost: one small task with a $2 cap on estimated model
   spend. The run stops before its next model request once the estimate passes $2, so the last
   request can go slightly over, and hosted desktop time is billed separately. The analysis after

package/dist/study/mobile-emulation.d.ts

@@ -0,0 +1,27 @@
+import type { DevicePreset } from "./device-presets.js";
+import type { StudyDesktopFidelity } from "./types.js";
+/** The CDP Emulation overrides one participant's Chromium pages get. */
+export interface MobileEmulationRequest {
+    width: number;
+    height: number;
+    deviceScaleFactor: number;
+    touch: boolean;
+    userAgent: string;
+}
+/**
+ * The emulation a participant gets, or undefined. Only a participant on a mobile preset is
+ * emulated: a run-wide `mobileEmulation` must not hand a desktop or tablet participant beside a
+ * phone participant an iPhone user agent. Hosted and local desktops both read this.
+ */
+export declare function participantMobileEmulation(fidelity: StudyDesktopFidelity | undefined, preset: DevicePreset): MobileEmulationRequest | undefined;
+/** Chromium flags that carry the user agent and touch support to every page and worker. */
+export declare function mobileEmulationLaunchFlags(request: MobileEmulationRequest | undefined): string[];
+/**
+ * The CDP commands that apply a request to one page, in order. The local guest sends these over
+ * its own page session; the hosted desktop's in-sandbox probe sends the same Emulation domain.
+ * Touch adds mouse-to-touch conversion, since participants drive a desktop pointer.
+ */
+export declare function mobileEmulationCommands(request: MobileEmulationRequest): {
+    method: string;
+    params: Record<string, unknown>;
+}[];

package/dist/study/mobile-emulation.js

@@ -0,0 +1,60 @@
+/** The user agent a mobile-emulated participant presents unless the study sets its own. */
+const DEFAULT_MOBILE_USER_AGENT = "Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.0 Mobile/15E148 Safari/604.1";
+/**
+ * The emulation a participant gets, or undefined. Only a participant on a mobile preset is
+ * emulated: a run-wide `mobileEmulation` must not hand a desktop or tablet participant beside a
+ * phone participant an iPhone user agent. Hosted and local desktops both read this.
+ */
+export function participantMobileEmulation(fidelity, preset) {
+    if (!fidelity?.mobileEmulation || !preset.isMobile)
+        return undefined;
+    return {
+        width: preset.width,
+        height: preset.height,
+        deviceScaleFactor: fidelity.deviceScaleFactor ?? preset.deviceScaleFactor,
+        touch: fidelity.touch ?? true,
+        userAgent: fidelity.userAgent ?? DEFAULT_MOBILE_USER_AGENT,
+    };
+}
+/** Chromium flags that carry the user agent and touch support to every page and worker. */
+export function mobileEmulationLaunchFlags(request) {
+    if (request === undefined)
+        return [];
+    return [
+        `--user-agent=${request.userAgent}`,
+        ...(request.touch ? ["--touch-events=enabled"] : []),
+    ];
+}
+/**
+ * The CDP commands that apply a request to one page, in order. The local guest sends these over
+ * its own page session; the hosted desktop's in-sandbox probe sends the same Emulation domain.
+ * Touch adds mouse-to-touch conversion, since participants drive a desktop pointer.
+ */
+export function mobileEmulationCommands(request) {
+    return [
+        {
+            method: "Emulation.setDeviceMetricsOverride",
+            params: {
+                width: request.width,
+                height: request.height,
+                deviceScaleFactor: request.deviceScaleFactor,
+                mobile: true,
+                screenWidth: request.width,
+                screenHeight: request.height,
+            },
+        },
+        ...(request.touch
+            ? [
+                {
+                    method: "Emulation.setTouchEmulationEnabled",
+                    params: { enabled: true, maxTouchPoints: 5 },
+                },
+                {
+                    method: "Emulation.setEmitTouchEventsForMouse",
+                    params: { enabled: true, configuration: "mobile" },
+                },
+            ]
+            : []),
+        { method: "Emulation.setUserAgentOverride", params: { userAgent: request.userAgent } },
+    ];
+}

package/dist/study/plan.js

@@ -41,7 +41,7 @@ function planPreview(config, options, input) {
     });
     if (String(config.comms?.email?.kind) === "real")
         return refuse("HUMANISH_STUDY_COMMS_UNSUPPORTED", "Real email receiving is unsupported on the preview route. Use a supported hosted computer-use study.");
-    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 unsupported = automaticAnalysisRouteReason(config);

package/dist/study/preflight-result.js

@@ -7,7 +7,7 @@ import { computerUseParticipantCount } from "./routing.js";
 export const STUDY_CHECK_SCHEMA = "humanish.study-check.v1";
 export function finalize(ctx, args) {
     const checks = [...ctx.checks, ...(args?.check ? [args.check] : []), ...(args?.checks ?? [])];
-    const analysis = automaticAnalysisBudget(ctx.config.review?.analysis, ctx.route, computerUseParticipantCount(ctx.config));
+    const analysis = automaticAnalysisBudget(ctx.config.review?.analysis, ctx.route, computerUseParticipantCount(ctx.config), ctx.config.actor);
     return {
         schema: STUDY_CHECK_SCHEMA,
         ...(analysis ? { analysis } : {}),

package/dist/study/summary.js

@@ -123,7 +123,7 @@ export async function readStudySummary(cwd, study, options = {}) {
             missingKeys = missing;
     }
     // Computed once: a test-then-use pair reads as though the two calls could differ.
-    const analysis = automaticAnalysisBudget(inspected.config.review?.analysis, route, computerUseParticipantCount(inspected.config));
+    const analysis = automaticAnalysisBudget(inspected.config.review?.analysis, route, computerUseParticipantCount(inspected.config), inspected.config.actor);
     const subject = subjectOf(config);
     const participants = participantsOf(inspected.config);
     const caps = summaryCapsOf(inspected.config);

package/dist/study/warnings.js

@@ -1,6 +1,7 @@
 import { cli } from "../cli/invocation.js";
 import { isComputerUseComposition, isScriptedBrowserComposition, isSharedWorldComposition, isTerminalProductComposition, } from "./routing.js";
 import { DESKTOP_FILES_ROUTE_REASON } from "./desktop-files.js";
+import { isLocalBrowserStudy } from "../substrates/local/runtime-config.js";
 import { computerUseParticipants, declaredParticipantIds, sharedWorldParticipants, } from "./plan-participants.js";
 import { addressedRecipients } from "./parse/comms.js";
 import { participantList, participantInstruction, declaredParticipantCount, } from "./study-fields.js";
@@ -198,8 +199,10 @@ const CONFIG_ROWS = [
     },
     {
         field: "execution.desktop.fidelity",
-        reason: "mobile emulation is applied only to computer-use participants in hosted Chromium on execution.target: e2b-desktop",
-        applies: (config, routes) => !routes.hostedCuaBrowser && config.execution?.desktop?.fidelity !== undefined,
+        reason: "mobile emulation is applied only to computer-use participants in Chromium on a hosted desktop or execution.target: local",
+        applies: (config, routes) => !routes.hostedCuaBrowser &&
+            !isLocalBrowserStudy(config) &&
+            config.execution?.desktop?.fidelity !== undefined,
     },
     {
         field: "execution.desktop.sandboxTimeoutMs",

package/dist/substrates/e2b/cdp-probe.d.ts

@@ -1,4 +1,5 @@
 import { type ChromeNetworkCaptureRequest } from "./cdp-network-capture.js";
+import type { MobileEmulationRequest } from "../../study/mobile-emulation.js";
 /** Which target to attribute when the endpoint lists several pages. */
 export type ChromeCdpPagePreference = "pinned" | "active";
 export interface ChromeCdpProbeArgs {
@@ -37,12 +38,7 @@ export interface ChromeCdpProbeArgs {
     network?: ChromeNetworkCaptureRequest;
 }
 /** Mobile emulation request: the CDP Emulation domain applied to one page target. */
-export interface ChromeMobileEmulationRequest {
-    width: number;
-    height: number;
-    deviceScaleFactor: number;
-    touch: boolean;
-    userAgent: string;
+export interface ChromeMobileEmulationRequest extends MobileEmulationRequest {
     platform?: string;
 }
 /** What the page reports after emulation: the proof, never copied from the request. */

package/dist/substrates/e2b/desktop-cdp.d.ts

@@ -66,8 +66,6 @@ export declare function makeChromeBrowserStateObserver(desktop: E2BDesktopSandbo
     text?: string;
     scrollY?: number;
 }>;
-/** The user agent a mobile-emulated participant presents unless the study sets its own. */
-export declare const DEFAULT_MOBILE_USER_AGENT = "Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.0 Mobile/15E148 Safari/604.1";
 /**
  * Apply mobile emulation to the participant's launch page and read back what the page reports.
  * Fails closed: a request that cannot be applied throws, because a desktop run labelled mobile is

package/dist/substrates/e2b/desktop-cdp.js

@@ -97,8 +97,6 @@ export function makeChromeBrowserStateObserver(desktop, requestTimeoutMs, endpoi
         };
     };
 }
-/** The user agent a mobile-emulated participant presents unless the study sets its own. */
-export const DEFAULT_MOBILE_USER_AGENT = "Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.0 Mobile/15E148 Safari/604.1";
 /**
  * Apply mobile emulation to the participant's launch page and read back what the page reports.
  * Fails closed: a request that cannot be applied throws, because a desktop run labelled mobile is

package/dist/substrates/local/firecracker-desktop.d.ts

@@ -2,11 +2,14 @@ import type { Writable } from "node:stream";
 import { type DesktopRecordingConfig, type DesktopRecordingMetadata } from "../../evidence/desktop-recording-types.js";
 import { type DesktopSession } from "../desktop-session.js";
 import { type GuestMediaConfig } from "../../guest/media-config.js";
+import { type GuestDisplayConfig } from "../../guest/display-config.js";
 /** The installed runtime image; `humanish runtime setup` chooses it, never a participant. */
 export interface LocalFirecrackerAssets {
     image: string;
     runtimeRevision: string;
     media?: boolean;
+    /** The guest starts the screen and emulation a bootstrap names; older images are 960×720 only. */
+    displaySizes?: boolean;
 }
 export interface LocalFirecrackerDesktop extends DesktopSession {
     finishRecording(destination: Writable): Promise<DesktopRecordingMetadata>;
@@ -26,6 +29,8 @@ interface LocalFirecrackerOptions {
     signal?: AbortSignal;
     media?: GuestMediaConfig;
     recording?: DesktopRecordingConfig;
+    /** The participant's screen and mobile emulation; absent is the guest's 960×720 default. */
+    display?: GuestDisplayConfig;
     inboxUrl?: string;
 }
 /** One VM with opaque TCP forwards to the selected app and optional scoped inbox. */

package/dist/substrates/local/firecracker-desktop.js

@@ -9,6 +9,7 @@ import { ownDesktopAllocation, } from "../desktop-session.js";
 import { runtimeDocker, runtimeExec, usesLima } from "./runtime-host.js";
 import { openLimaTunnel } from "./runtime-ssh.js";
 import { guestMediaConfigSchema } from "../../guest/media-config.js";
+import { guestDisplayConfigSchema } from "../../guest/display-config.js";
 import { cli } from "../../cli/invocation.js";
 import { DESKTOP_RESERVATION } from "./capacity.js";
 const docker = async (args) => (await runtimeDocker(args, {}, 60_000)).stdout.trim();
@@ -55,6 +56,11 @@ function checkDesktopOptions(options) {
         if (options.assets.media !== true)
             throw new Error(`This runtime does not include the recorder. Run ${cli("runtime setup --media")}.`);
     }
+    if (options.display !== undefined) {
+        const { width, height } = guestDisplayConfigSchema.parse(options.display);
+        if (options.assets.displaySizes !== true)
+            throw new Error(`This local runtime starts every participant at 960×720, so it cannot start the ${width}×${height} screen this participant needs. Omit device and resolution, use a hosted desktop, or set HUMANISH_LOCAL_RUNTIME_IMAGE to a runtime built from current source.`);
+    }
     let url;
     try {
         url = new URL(validateGuestInitialUrl(options.appUrl));
@@ -261,7 +267,7 @@ async function bootstrapGuest(stream, options, url, signal) {
         runtimeRevision: options.assets.runtimeRevision,
     };
     try {
-        return await connectGuestBootstrap(stream, identity, signal, url.href, options.media, options.recording);
+        return await connectGuestBootstrap(stream, identity, signal, url.href, options.media, options.recording, options.display);
     }
     catch (error) {
         signal.throwIfAborted();

package/dist/substrates/local/runtime-config.d.ts

@@ -1,6 +1,18 @@
 import type { StudyConfig } from "../../study/types.js";
+import { type DevicePreset } from "../../study/device-presets.js";
+import { type GuestDisplayConfig } from "../../guest/display-config.js";
 export declare const LOCAL_BROWSER_LIFETIME_MS: number;
 export declare function isLocalBrowserStudy(config: StudyConfig): boolean;
 /** Defaults for the explicitly selected local substrate; hosted configurations are untouched. */
 export declare function localBrowserDefaults(config: StudyConfig): StudyConfig;
 export declare function localBrowserUnsupportedReason(config: StudyConfig): string | undefined;
+/**
+ * The screen a local participant's guest starts, with mobile emulation where hosted desktops apply
+ * it. Undefined is the guest's 960×720 default, which every installed runtime supports.
+ */
+export declare function localGuestDisplay(config: StudyConfig, device: {
+    preset: DevicePreset;
+    resolution: readonly [number, number];
+}): GuestDisplayConfig | undefined;
+/** Whether any participant of a local study needs a screen other than the guest's default. */
+export declare function localStudySetsScreens(config: StudyConfig): boolean;

package/dist/substrates/local/runtime-config.js

@@ -1,4 +1,7 @@
 import { participantList } from "../../study/study-fields.js";
+import { DEVICE_PRESET_NAMES, resolveParticipantDevice, } from "../../study/device-presets.js";
+import { participantMobileEmulation } from "../../study/mobile-emulation.js";
+import { DEFAULT_GUEST_SCREEN, GUEST_SCREEN_LIMITS, } from "../../guest/display-config.js";
 // The runtime image enforces a 30-minute lifetime; reserve setup/teardown room.
 export const LOCAL_BROWSER_LIFETIME_MS = 30 * 60_000;
 const MAX_SESSION_MS = 20 * 60_000;
@@ -24,12 +27,18 @@ export function localBrowserDefaults(config) {
             timeoutMs: config.execution?.timeoutMs ?? MAX_SESSION_MS,
             desktop: {
                 ...config.execution?.desktop,
-                resolution: config.execution?.desktop?.resolution ?? [960, 720],
+                // A named device governs the screen when the study sets one; resolution would override it.
+                ...(config.execution?.desktop?.device !== undefined ||
+                    participantList(config)?.some((entry) => entry.device !== undefined)
+                    ? {}
+                    : {
+                        resolution: config.execution?.desktop?.resolution ?? [
+                            DEFAULT_GUEST_SCREEN.width,
+                            DEFAULT_GUEST_SCREEN.height,
+                        ],
+                    }),
             },
         },
-        ...(config.review?.analysis === undefined && actor.type === "local-agent"
-            ? { review: { ...config.review, analysis: { provider: "codex" } } }
-            : {}),
     };
 }
 export function localBrowserUnsupportedReason(config) {
@@ -42,20 +51,19 @@ export function localBrowserUnsupportedReason(config) {
         (actor.type === "local-agent" && actor.localAgent !== undefined && actor.localAgent !== "codex")) {
         return "Local browser studies support only Codex local-agent or openai-computer-use participants.";
     }
-    if (desktop?.resolution?.[0] !== 960 ||
-        desktop.resolution[1] !== 720 ||
-        desktop.device !== undefined ||
-        (desktop.browser !== undefined && !["default", "chromium"].includes(desktop.browser)) ||
-        participantList(config)?.some((entry) => entry.device !== undefined) ||
-        desktop.template !== undefined ||
-        desktop.sandboxTimeoutMs !== undefined) {
-        return "The local browser runtime currently uses a 960×720 Chromium desktop. Omit hosted templates, device presets and sandboxTimeoutMs.";
+    if ((desktop?.browser !== undefined && !["default", "chromium"].includes(desktop.browser)) ||
+        desktop?.template !== undefined ||
+        desktop?.sandboxTimeoutMs !== undefined) {
+        return "The local browser runtime runs Chromium and has no hosted templates or sandboxTimeoutMs. Remove execution.desktop.browser, template and sandboxTimeoutMs, or use a hosted desktop.";
     }
+    const screenReason = localScreenReason(config);
+    if (screenReason)
+        return screenReason;
     if (config.comms !== undefined &&
         (config.comms.email?.kind !== "fake" || !config.comms.email.external)) {
         return "Local browser inboxes require captured email with comms.email.external.catchBaseUrl. Run humanish comms catch and point your app's email sends at it. Real receiving requires a supported hosted route.";
     }
-    if (desktop.media?.camera !== undefined && desktop.media.camera.source !== "synthetic") {
+    if (desktop?.media?.camera !== undefined && desktop.media.camera.source !== "synthetic") {
         return "Local cameras currently use source: synthetic. Camera files remain supported on hosted desktops.";
     }
     if (actor.type === "local-agent" &&
@@ -87,3 +95,37 @@ export function localBrowserUnsupportedReason(config) {
     }
     return undefined;
 }
+/** Why a participant's screen does not fit the local guest, or undefined. */
+function localScreenReason(config) {
+    const limits = GUEST_SCREEN_LIMITS;
+    for (const entry of participantList(config) ?? [{}]) {
+        const [width, height] = resolveParticipantDevice(config, entry.device).resolution;
+        if (width < limits.minWidth ||
+            width > limits.maxWidth ||
+            height < limits.minHeight ||
+            height > limits.maxHeight)
+            return `Local browser desktops support screens up to ${limits.maxWidth}×${limits.maxHeight} and at least ${limits.minHeight} pixels high; this study asks for ${width}×${height}. Use a device preset (${DEVICE_PRESET_NAMES.join(", ")}), a resolution within those bounds, or a hosted desktop.`;
+    }
+    const userAgent = config.execution?.desktop?.fidelity?.userAgent;
+    if (userAgent !== undefined && !/^[\x20-\x7e]{1,512}$/.test(userAgent))
+        return "Local browser desktops take an execution.desktop.fidelity.userAgent of at most 512 printable ASCII characters. Shorten it or remove non-ASCII characters.";
+    return undefined;
+}
+/**
+ * The screen a local participant's guest starts, with mobile emulation where hosted desktops apply
+ * it. Undefined is the guest's 960×720 default, which every installed runtime supports.
+ */
+export function localGuestDisplay(config, device) {
+    const mobileEmulation = participantMobileEmulation(config.execution?.desktop?.fidelity, device.preset);
+    const [width, height] = device.resolution;
+    if (mobileEmulation === undefined &&
+        width === DEFAULT_GUEST_SCREEN.width &&
+        height === DEFAULT_GUEST_SCREEN.height)
+        return undefined;
+    return { width, height, ...(mobileEmulation === undefined ? {} : { mobileEmulation }) };
+}
+/** Whether any participant of a local study needs a screen other than the guest's default. */
+export function localStudySetsScreens(config) {
+    const study = localBrowserDefaults(config);
+    return (participantList(study) ?? [{}]).some((entry) => localGuestDisplay(study, resolveParticipantDevice(study, entry.device)) !== undefined);
+}

package/dist/substrates/local/runtime-release.js

@@ -1,18 +1,18 @@
 /** Updated with the verified, public runtime artifact before release. */
 const LOCAL_RUNTIME_RELEASE = {
-    url: "https://github.com/danielgwilson/humanish/releases/download/runtime-2026.09.28.1/runtime-linux-amd64.tar.gz",
-    sha256: "224be52467d6a808c79f156c6537d8a34c2dfb7b71daa836d34c8611fbbb6647",
-    bytes: 596142100,
-    image: "sha256:89cec77ea8097d32f3ef14bf2bdb0a93ffd25c3975913f8c5ffc6a2f360482a2",
+    url: "https://github.com/danielgwilson/humanish/releases/download/runtime-2026.10.21.1/runtime-linux-amd64.tar.gz",
+    sha256: "1de53db000f661e91ff6ea9a2eb8198b08b850621cf63d8ce7c1b046f5035faf",
+    bytes: 597029770,
+    image: "sha256:c805c310b7b086276efa74ea5735e8b559457c7edba85c5c9e3ac7934e8760f2",
 };
 /** Architecture-specific artifacts; each retains matching sources and notices. */
 export const LOCAL_RUNTIME_RELEASES = {
     amd64: LOCAL_RUNTIME_RELEASE,
     arm64: {
-        url: "https://github.com/danielgwilson/humanish/releases/download/runtime-2026.09.28.2/runtime-linux-arm64.tar.gz",
-        sha256: "d03e1b6335bea76a22bf88ca9aa8dc1f4fe0af16fba02c654a333766e27cd2ea",
-        bytes: 582661785,
-        image: "sha256:c3d584d9586d2e86833ee8d050c43774d456c6c4f8f3c9a53194bd90910fa938",
+        url: "https://github.com/danielgwilson/humanish/releases/download/runtime-2026.10.21.2/runtime-linux-arm64.tar.gz",
+        sha256: "ea7a42e12eae3b4d9140fff41e4e3512930202f9ccbb688497b146634d1cef10",
+        bytes: 583555960,
+        image: "sha256:e21c33b4745afdb3bac6a69c76606814348032ee661228c9bfdd9c7d06591a28",
     },
 };
 /** Media assets are separate so ordinary browser studies keep the smaller download. */

package/dist/substrates/local/runtime.js

@@ -164,6 +164,7 @@ async function engineStatus(options, architecture, lima) {
             image: image.Id,
             runtimeRevision: revision,
             ...(labels["to.humanish.runtime.media"] === "1" ? { media: true } : {}),
+            ...(labels["to.humanish.runtime.display-sizes"] === "1" ? { displaySizes: true } : {}),
         },
     };
 }