humanish 0.139.0 → 0.140.0

package/dist/study/doctor.js

@@ -1,10 +1,11 @@
 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";
 import { localAgentReady, localAgentVersionRefusal, } from "../actors/local-agent/cli.js";
 import { protocolAdditionsWarning, protocolIncompatibilityMessage, } from "../actors/codex/protocol-compat.js";
+import { operatorInstructionsWarning } from "../actors/codex/operator-instructions.js";
 import { admissionRule } from "../analysis/admission.js";
 import { automaticAnalysisBudget } from "../analysis/automatic-config.js";
 import { externalCatchHealthy } from "../comms/sandbox-catch.js";
@@ -90,6 +91,8 @@ function codexRecovery(readiness, fallback) {
             return codexVersionRecovery(readiness.detectedCliVersion, readiness.installation);
         case "codex_incompatible_release":
             return `${protocolIncompatibilityMessage(readiness.detectedCliVersion, readiness.protocolIncompatibilities ?? [])} ${codexInstallAdvice(readiness.installation)} Then sign in with a ChatGPT account (\`codex login\`).`;
+        case "codex_unsafe_configuration":
+            return unsafeConfigurationRecovery(readiness.refusalReason, fallback);
         case "codex_login_required":
             return "Codex is installed but not signed in. Run `codex login` and sign in with a ChatGPT account.";
         case "codex_unsupported_auth":
@@ -107,6 +110,12 @@ function codexRecovery(readiness, fallback) {
             return fallback;
     }
 }
+/** What the refused setting is and how to change it; the fallback when no reason was recorded. */
+function unsafeConfigurationRecovery(reason, fallback) {
+    if (reason === undefined)
+        return fallback;
+    return `humanish stopped the Codex launch because ${reason}. Change that setting in the Codex config (~/.codex/config.toml, a profile, or a system config) if you want hosted participants to use it, then rerun doctor.`;
+}
 /** Shared read-only Codex account check for local participants in doctor and the TUI. */
 export async function localCodexParticipantCheck(args) {
     const readiness = await (args.readiness ?? codexAccountReadiness)(args.env).catch(() => ({ ready: false, errorCode: "codex_unavailable" }));
@@ -195,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));
@@ -222,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)
@@ -243,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. */
@@ -320,6 +334,7 @@ async function hostedCodexParticipantCheck(args, actor) {
         ...(actor?.reasoningEffort === undefined ? {} : { reasoningEffort: actor.reasoningEffort }),
     };
     const readiness = await (args.codexParticipantReadiness ?? hostedCodexReadiness)(args.env, declared).catch(() => ({ ready: false, errorCode: "codex_unavailable" }));
+    const operatorNote = operatorInstructionsWarning(readiness.operatorInstructionFiles);
     const account = readiness.authentication === "api-key"
         ? "an API key, which bills its usage to that key"
         : "a ChatGPT account";
@@ -327,7 +342,7 @@ async function hostedCodexParticipantCheck(args, actor) {
         name: "local participant authentication",
         ok: readiness.ready,
         message: readiness.ready
-            ? readyMessage(`Codex CLI ${readiness.cliVersion ?? "(unknown release)"} passed the operator handshake without a turn (initialize, config/read, account/read and an ephemeral thread/start): model ${readiness.resolvedModel ?? "(not reported)"} on ${account}. E2B supplies the desktop; no OpenAI API key is required for this participant.`, readiness)
+            ? readyMessage(`Codex CLI ${readiness.cliVersion ?? "(unknown release)"} passed the operator handshake without a turn (initialize, config/read, account/read and an ephemeral thread/start): model ${readiness.resolvedModel ?? "(not reported)"} on ${account}. E2B supplies the desktop; no OpenAI API key is required for this participant.${operatorNote === undefined ? "" : ` ${operatorNote}`}`, readiness)
             : `Hosted Codex participant setup is unavailable (${readiness.errorCode}). ${codexRecovery(readiness, "Check `codex login status` and the operator's Codex configuration, then rerun doctor.")} No API fallback is used.`,
     };
 }
@@ -374,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 } : {}),
         },
     };
 }

package/docs/contracts/study-analysis.md

@@ -3,15 +3,16 @@
 Study analysis is an independent interpretation of retained participant evidence.
 It is separate from the participant's account, recorded outcome, and the run's
 deterministic review verdict. Opening an Observer never starts a provider request.
-Supported live runs request analysis on completion by default, with a separate
-$3 cap on its expected cost. Set `review.analysis: false` to disable that request;
-see [automatic analysis](../product/automatic-analysis.md).
+Supported live runs request analysis on completion by default. A study that declares no analyst
+gets the Codex account analyst when its participant is a Codex `local-agent`, and the OpenAI
+analyst with a separate $10 cap on its expected cost otherwise. Set `review.analysis: false` to
+disable that request; see [automatic analysis](../product/automatic-analysis.md).
 
 ## Invocation
 
 ```bash
-humanish analyze --run latest --max-cost 3 --dry-run --json
-humanish analyze --run latest --max-cost 3 --json
+humanish analyze --run latest --max-cost 10 --dry-run --json
+humanish analyze --run latest --max-cost 10 --json
 humanish observe --run latest
 humanish analyze list --run latest --json
 humanish analyze show --run latest --json
@@ -116,9 +117,11 @@ the current merge instructions, billed $1.92, most of its input served from the
 provider's prompt cache, and each of its 466 citations resolved. Two runs do not
 calibrate the merge request's estimate.
 
-## Explicit Codex account analysis
+## Codex account analysis
 
-An existing completed recording can use a separate restricted Codex analyst:
+A study whose participant is a Codex `local-agent` uses this analyst unless it declares another,
+and any study can select it with `review.analysis.provider: codex`. An existing completed
+recording can use it too:
 
 ```bash
 humanish analyze --run latest --provider codex --dry-run --json
@@ -486,7 +489,10 @@ The states without findings:
 - `skipped`: the automatic analysis was skipped or refused, for example without
   `OPENAI_API_KEY`, or the run's study file sets `review.analysis: false`
   (`AUTOMATIC_ANALYSIS_DISABLED`, read from the file when the view is built). `next` is
-  `analyze --max-cost 3`, which runs an analysis anyway. For an analysis refused for its
+  `analyze --max-cost 10`, which runs an analysis anyway. For a skip without `OPENAI_API_KEY`
+  on a machine where Codex is signed in with a ChatGPT account (read when the view is built),
+  `next` is `analyze --provider codex` and the message names `review.analysis.provider: codex`
+  in the run's study file; otherwise the message says to set the key. For an analysis refused for its
   cost, the message gives the expected cost, the worst case and the cap, and `next` sets
   `--max-cost` to the worst case rounded up.
 - `failed`: the latest attempt failed or was cancelled and no usable version exists. `next`

package/docs/principles/invariants-and-defaults.md

@@ -90,7 +90,7 @@ silently drifting from one is not.
 | Default                                     | Why it is the default                                                                                                                                                                                                                                               | Legitimate override                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
 | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | Dry-run                                     | Spend safety (the live-spend rule sets the floor; dry-run keeps it far away)                                                                                                                                                                                        | `mode: live`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
-| Post-run analysis on supported live studies | Findings accompany the recording; a separate $3 cap on its expected cost is visible before execution                                                                                                                                                                | `review.analysis: false` disables it; an explicit mapping sets another analysis budget. Dry-run and unsupported routes never dispatch; missing default credentials produce a recorded skip                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| Post-run analysis on supported live studies | Findings accompany the recording; a Codex participant's run is analyzed by the same account, and otherwise a separate $10 cap on its expected cost is visible before execution                                                                                      | `review.analysis: false` disables it; an explicit mapping sets another analysis budget. Dry-run and unsupported routes never dispatch; missing default credentials produce a recorded skip                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
 | Separate worlds (`per-lane-worlds`)         | Isolation, attribution, reproducibility                                                                                                                                                                                                                             | `route: shared-world`: N participants against one mutable plane for scenarios that are about interaction between participants. Participants run at once, as many as `execution.concurrency` (two or more) and the E2B plan's limit allow, unless the study declares when each one starts (`participants[].startAfterMs`). The plane is one getHost-exposed subject sandbox with synthetic seeded data, or an operator-owned public deployment (external-public), driven by N actor sandboxes. The bundle declares the weaker `attributionClass: shared-world` and a verify-enforced `attributionLimits` ceiling (`best-effort-causal-attribution` and the rest of the concurrent set). Sequential turns at `execution.concurrency: 1` were removed in 0.106.0. |
 | External key placement                      | Smallest blast radius: when the keyed process (e.g. a computer-use provider loop) runs outside the sandbox, its key never enters                                                                                                                                    | In-sandbox placement when the keyed process runs inside (an agent harness under test); declared per actor type, with a spend budget                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
 | Loopback entry URLs                         | Public-safety: never drive third-party sites unbidden                                                                                                                                                                                                               | `policies.allowPublicTargets` for an owner-declared deployment/preview (a Vercel preview of your own app). Multi-participant public/preview fan-out needs explicit `participants[].target` for every participant, so the adapter-owned topology is declared rather than inferred. Provisioned clone subjects always serve in-sandbox on loopback                                                                                                                                                                                                                                                                                                                                                                                                               |