humanish 0.139.1 → 0.141.0

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/run-study-events.d.ts

@@ -19,7 +19,8 @@ export type SetupTarget = {
     readonly participant: ParticipantRef;
 };
 /**
- * What a run reports while it runs. `plan` comes from computer use only; the other routes run from
+ * What a run reports while it runs. `run-started` comes from every route that records a run, once
+ * its run id exists. `plan` comes from computer use only; the other routes run from
  * the study plan but do not emit it. `subject-phase` comes from computer use (participant target)
  * and shared world (subject target).
  */
@@ -40,6 +41,11 @@ export type StudyEvent = {
     at: string;
     ok?: boolean;
     durationMs?: number;
+}
+/** The run's directory and status.json exist: `runId` names it from here on. */
+ | {
+    type: "run-started";
+    runId: string;
 } | {
     type: "analysis-started";
 } | {

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

@@ -5,6 +5,7 @@ import { failureTail } from "../../evidence/redaction.js";
 import { isHttpUrl } from "../../study/parse/subject.js";
 import { runDetachedStep } from "../detached.js";
 import { shellQuote } from "../shell.js";
+import { externalLinkHandlerSetup } from "./desktop-handoff.js";
 import { e2bShell } from "./shell.js";
 // Settle after opening the browser or the terminal, before the first screenshot: long enough for
 // a cold browser and page load to paint (2 s captured a blank desktop; the render needs 6-9 s).
@@ -210,7 +211,8 @@ extraChromiumFlags = [], environment) {
             `target_url=${shellQuote(targetUrl)}`,
             `browser_preference=${shellQuote(requestedBrowser)}`,
             "profile_dir=",
-            `chrome_preferences_json=${shellQuote(chromiumEvidenceProfilePreferencesJson())}`,
+            `chrome_preferences_json=${shellQuote(chromiumEvidenceProfilePreferencesJson(targetUrl))}`,
+            externalLinkHandlerSetup(),
             "prepare_profile() {",
             '  profile_dir="$(mktemp -d /tmp/humanish-chrome-profile.XXXXXX)"',
             '  mkdir -p "$profile_dir/Default"',

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/e2b/desktop-executor.d.ts

@@ -1,4 +1,5 @@
 import type { CuaExecutor, CuaObservation } from "../../actors/computer-use/loop.js";
+import type { ExternalHandoff } from "../../actors/computer-use/external-handoff.js";
 /**
  * The minimal slice of the @e2b/desktop Sandbox the executor depends on: a structural subset of
  * the SDK class (checked against 2.4.0), so a Sandbox satisfies it with no adapter. Methods are typed to return `Promise<void> | void` (and the
@@ -65,6 +66,12 @@ export interface E2BDesktopExecutorOptions {
      * never persists raw URL/title/text; it only uses them in memory to decide whether to stop.
      */
     observeBrowserState?: () => Promise<Pick<CuaObservation, "url" | "title" | "text" | "scrollY">>;
+    /**
+     * Optional read of the links the browser handed to another app since the last read
+     * (desktop-handoff.ts). It runs beside the browser probe and the screenshot; a read that fails
+     * leaves its links for the next one.
+     */
+    readExternalHandoffs?: () => Promise<readonly ExternalHandoff[]>;
 }
 /** The stage of a `type` action that failed. */
 export type CuaTypePhase = "desktop-write" | "text-tempfile" | "text-command";

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

@@ -151,10 +151,13 @@ export function createE2BDesktopExecutor(desktop, options = {}) {
             // Probe browser state before the screenshot so a deterministic stopWhen match
             // and its persisted frame describe the same settled surface as closely as the
             // desktop substrate allows.
+            const handoffs = options.readExternalHandoffs?.().catch(() => []);
             const browserState = await options.observeBrowserState?.().catch(() => undefined);
             const raw = await desktop.screenshot();
             const screenshot = toBuffer(raw);
+            const externalHandoffs = (await handoffs) ?? [];
             return {
+                ...(externalHandoffs.length === 0 ? {} : { externalHandoffs }),
                 screenshot,
                 stateSignature: perceptualSignature(screenshot),
                 ...(browserState?.url === undefined ? {} : { url: browserState.url }),

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

@@ -0,0 +1,22 @@
+import { type ExternalHandoff } from "../../actors/computer-use/external-handoff.js";
+import { type Shell } from "../shell.js";
+/**
+ * One stand-in, installed in `bin`, appending to `log` (a shell word). `$0` names the command it
+ * stands in for. The local guest image ships the same script
+ * (runtime/browser-guest/control/root/opt/humanish/control/bin/xdg-open).
+ */
+export declare function externalLinkStandIn(bin: string, log: string): string;
+/**
+ * Shell lines for the browser launch script, run before the browser starts: they install the
+ * stand-ins and put them first on the search path for every command the script starts after them.
+ */
+export declare function externalLinkHandlerSetup(dir?: string): string;
+/**
+ * Returns a read of the links handed off since the previous read, oldest first and at most
+ * EXTERNAL_HANDOFF_LIMITS.perObservation at a time. Reads run one at a time, so a retried
+ * observation cannot return a link twice. A line still being written is left for the next read.
+ */
+export declare function externalHandoffReader(shell: Pick<Shell, "run">, options: {
+    requestTimeoutMs: number;
+    dir?: string;
+}): () => Promise<ExternalHandoff[]>;

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

@@ -0,0 +1,86 @@
+// Links the participant's browser hands to another app (mailto:, tel:, sms:) on a hosted desktop.
+//
+// Chrome on Linux opens such a link by running `xdg-email` (mailto) or `xdg-open` (the rest) by
+// name, unless an XDG desktop portal answers on the session bus; the stock desktop runs none.
+// The stock desktop has no mail, phone or messaging app, so `xdg-open` ended in XFCE's "Choose
+// Preferred Application" dialog, which participants reported as a fault of the app under test.
+// The browser launch puts stand-ins for both commands first on the browser's search path. A stand-in
+// appends the link to a log and exits; a web or file link goes on to the desktop's own command.
+// The executor reads the log on each observation, and the participant loop records each link
+// and tells the participant what happened. Chrome's own "Open xdg-open?" prompt for tel: and
+// the other non-mailto schemes is answered by the profile preference in
+// src/evidence/browser-hygiene.ts; Chrome never prompts for mailto.
+import { EXTERNAL_HANDOFF_LIMITS, externalHandoffOf, } from "../../actors/computer-use/external-handoff.js";
+import { shellQuote } from "../shell.js";
+/** Where the stand-ins and their log live on the desktop. */
+const EXTERNAL_LINK_DIR = "/tmp/humanish-external-links";
+const LINK_LENGTH = 4096;
+/**
+ * One stand-in, installed in `bin`, appending to `log` (a shell word). `$0` names the command it
+ * stands in for. The local guest image ships the same script
+ * (runtime/browser-guest/control/root/opt/humanish/control/bin/xdg-open).
+ */
+export function externalLinkStandIn(bin, log) {
+    return [
+        "#!/bin/sh",
+        "# Installed by humanish for a study participant's browser: this desktop has no app for this",
+        "# link, so the link is written down for the study instead of opening a chooser dialog.",
+        `bin=${shellQuote(bin)}`,
+        "url=",
+        'for arg in "$@"; do case "$arg" in -*) ;; *) url=$arg; break ;; esac; done',
+        'case "$url" in',
+        "  [Hh][Tt][Tt][Pp]:*|[Hh][Tt][Tt][Pp][Ss]:*|[Ff][Ii][Ll][Ee]:*) ;;",
+        "  [A-Za-z]*:*)",
+        `    printf '%s\\n' "$(printf '%s' "$url" | tr -d '\\r\\n' | cut -c 1-${LINK_LENGTH})" >> ${log}`,
+        "    exit 0 ;;",
+        "esac",
+        // Anything else goes to the desktop's own command, found on the search path without this
+        // directory.
+        "set -f",
+        "real=",
+        "IFS=:",
+        'for entry in $PATH; do [ "$entry" = "$bin" ] || real=${real:+$real:}$entry; done',
+        'PATH=$real exec "${0##*/}" "$@"',
+        "",
+    ].join("\n");
+}
+/**
+ * Shell lines for the browser launch script, run before the browser starts: they install the
+ * stand-ins and put them first on the search path for every command the script starts after them.
+ */
+export function externalLinkHandlerSetup(dir = EXTERNAL_LINK_DIR) {
+    const bin = `${dir}/bin`;
+    return [
+        `mkdir -p ${shellQuote(bin)}`,
+        `touch ${shellQuote(`${dir}/links.log`)}`,
+        `printf '%s' ${shellQuote(externalLinkStandIn(bin, shellQuote(`${dir}/links.log`)))} > ${shellQuote(`${bin}/xdg-open`)}`,
+        `cp ${shellQuote(`${bin}/xdg-open`)} ${shellQuote(`${bin}/xdg-email`)}`,
+        `chmod 755 ${shellQuote(`${bin}/xdg-open`)} ${shellQuote(`${bin}/xdg-email`)}`,
+        `export PATH=${shellQuote(bin)}:"$PATH"`,
+    ].join("\n");
+}
+/**
+ * Returns a read of the links handed off since the previous read, oldest first and at most
+ * EXTERNAL_HANDOFF_LIMITS.perObservation at a time. Reads run one at a time, so a retried
+ * observation cannot return a link twice. A line still being written is left for the next read.
+ */
+export function externalHandoffReader(shell, options) {
+    const log = `${options.dir ?? EXTERNAL_LINK_DIR}/links.log`;
+    let consumed = 0;
+    let previous = Promise.resolve();
+    const read = async () => {
+        const result = await shell.run(`tail -n +${consumed + 1} ${shellQuote(log)} 2>/dev/null | head -n ${EXTERNAL_HANDOFF_LIMITS.perObservation}`, { requestTimeoutMs: options.requestTimeoutMs, timeoutMs: 10_000 });
+        const lines = result.stdout.split("\n");
+        lines.pop();
+        consumed += lines.length;
+        return lines.flatMap((line) => {
+            const handoff = externalHandoffOf(line);
+            return handoff === undefined ? [] : [handoff];
+        });
+    };
+    return () => {
+        const next = previous.then(read, read);
+        previous = next.catch(() => undefined);
+        return next;
+    };
+}

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.3/runtime-linux-amd64.tar.gz",
+    sha256: "6fc19792e9b8f414165a73470526cc414c98d0ad368210c5e95daf29469b8dbd",
+    bytes: 597049520,
+    image: "sha256:4672388737bd7d136910fca6f8b6d99e09fbe96c13e1b100491c05444e7d267a",
 };
 /** 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.4/runtime-linux-arm64.tar.gz",
+        sha256: "d590de49a86eabe1cd09d7556aa75b2ebd62bc2c88fe37122e2af315c478c901",
+        bytes: 583551803,
+        image: "sha256:4606122520504f7f587f52b872165e6ab900be0ba3eca933b2f6dd3b9dcde723",
     },
 };
 /** 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 } : {}),
         },
     };
 }