humanish 0.139.1 → 0.141.0

package/dist/guest/bootstrap.js

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

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

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

package/dist/guest/display-config.js

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

package/dist/guest/external-links.d.ts

@@ -0,0 +1,14 @@
+import type { CuaExecutor } from "../actors/computer-use/loop.js";
+/** Where the image keeps the stand-ins. */
+export declare const GUEST_EXTERNAL_LINK_BIN = "/opt/humanish/control/bin";
+/**
+ * Write the browser profile's Preferences before the first launch, so the initial app's origin
+ * opens tel:, sms: and the other app schemes without Chromium's prompt. No initial URL, no file.
+ */
+export declare function prepareGuestBrowserProfile(profileDir: string, initialUrl: string | undefined): Promise<void>;
+/**
+ * The executor with each observation carrying the links appended to `log` since the previous
+ * observation, at most EXTERNAL_HANDOFF_LIMITS.perObservation. A line still being written waits
+ * for the next observation. Every other property of the executor is kept.
+ */
+export declare function withExternalHandoffs(executor: CuaExecutor, log: string): CuaExecutor;

package/dist/guest/external-links.js

@@ -0,0 +1,48 @@
+// Links the guest browser hands to another app (mailto:, tel:, sms:). The guest has no email,
+// phone or messaging app. The image's stand-ins for xdg-open and xdg-email, first on the guest's
+// search path, append each such link to a log in the runtime directory, and every observation the
+// executor returns carries the links appended since the previous one.
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { EXTERNAL_HANDOFF_LIMITS, externalHandoffOf, } from "../actors/computer-use/external-handoff.js";
+import { externalAppPreferences } from "../evidence/browser-hygiene.js";
+/** Where the image keeps the stand-ins. */
+export const GUEST_EXTERNAL_LINK_BIN = "/opt/humanish/control/bin";
+/**
+ * Write the browser profile's Preferences before the first launch, so the initial app's origin
+ * opens tel:, sms: and the other app schemes without Chromium's prompt. No initial URL, no file.
+ */
+export async function prepareGuestBrowserProfile(profileDir, initialUrl) {
+    const preferences = externalAppPreferences(initialUrl);
+    if (preferences === undefined)
+        return;
+    await mkdir(`${profileDir}/Default`, { recursive: true, mode: 0o700 });
+    await writeFile(`${profileDir}/Default/Preferences`, JSON.stringify(preferences), {
+        mode: 0o600,
+        flag: "wx",
+    });
+}
+/**
+ * The executor with each observation carrying the links appended to `log` since the previous
+ * observation, at most EXTERNAL_HANDOFF_LIMITS.perObservation. A line still being written waits
+ * for the next observation. Every other property of the executor is kept.
+ */
+export function withExternalHandoffs(executor, log) {
+    let consumed = 0;
+    return {
+        ...executor,
+        observe: async () => {
+            const observation = await executor.observe();
+            const text = await readFile(log, "utf8").catch(() => "");
+            const lines = text
+                .split("\n")
+                .slice(0, -1)
+                .slice(consumed, consumed + EXTERNAL_HANDOFF_LIMITS.perObservation);
+            consumed += lines.length;
+            const externalHandoffs = lines.flatMap((line) => {
+                const handoff = externalHandoffOf(line);
+                return handoff === undefined ? [] : [handoff];
+            });
+            return externalHandoffs.length === 0 ? observation : { ...observation, externalHandoffs };
+        },
+    };
+}

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

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

package/dist/guest/runtime-desktop.js

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

package/dist/guest/runtime.d.ts

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

package/dist/guest/runtime.js

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

package/dist/guest-runtime-main.js

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

package/dist/observer/data.d.ts

@@ -23,6 +23,10 @@ export interface ObserverData {
         state: "running" | "finished" | "interrupted" | "unknown";
         observedAt: string;
         source: "local-run-status";
+        /** Present while the run's own process analyzes it after the run ended: when it started. */
+        analysis?: {
+            startedAt: string;
+        };
     };
     run: {
         runId: string;

package/dist/observer/run-routes.js

@@ -15,7 +15,7 @@ import { displayedTraces, loadStreamTraces, } from "../run/stream-trace.js";
 import { isNodeError, isRecord } from "../run/type-guards.js";
 import { MAX_NOTE_FILE_BYTES, readRunNotes, RUN_NOTES_DIR, } from "../run/note-files.js";
 import { analysisCostOf, runCost, runCostLabel } from "../run/run-cost.js";
-import { RUN_STATUS_FILE, RUN_STATUS_STALE_MS, isRunStatusRecord, } from "../run/status.js";
+import { RUN_STATUS_FILE, RUN_STATUS_STALE_MS, runAnalysisPhase, isRunStatusRecord, } from "../run/status.js";
 import { renderObserverHtml } from "./artifact.js";
 import { parseFeedCursors } from "./feed-cursors.js";
 import { observerFeedBody } from "./page-data.js";
@@ -98,7 +98,9 @@ export async function serveRunPath(runRoot, relativePath, response, runtimeStrea
     const derivedRoot = cleanedRelativePath.split("/")[0];
     const derivedLeaf = path.posix.basename(cleanedRelativePath);
     // Local-only files (raw sandbox ids, the recording pid) are read in process, never served.
-    if (derivedRoot === ".analysis-lock" ||
+    if (
+    // `.analysis-lock-stale-*` is a lock whose dead owner's next writer moved it aside.
+    derivedRoot?.startsWith(".analysis-lock") === true ||
         derivedLeaf.startsWith(".humanish-write-") ||
         isAnalysisRecordPath(cleanedRelativePath) ||
         isLocalOnlyRunFile(cleanedRelativePath)) {
@@ -330,9 +332,16 @@ function withLocalRunStatus(record, input, outcome) {
             state = "running";
         }
     }
+    // The run's own process analyzes it after the run ended; the bundle outcome does not say so.
+    const analysis = timestampsValid ? runAnalysisPhase(record, now) : undefined;
     return {
         ...data,
-        runtime: { state, observedAt: new Date(now).toISOString(), source: "local-run-status" },
+        runtime: {
+            state,
+            observedAt: new Date(now).toISOString(),
+            source: "local-run-status",
+            ...(analysis?.state === "running" ? { analysis: { startedAt: analysis.startedAt } } : {}),
+        },
     };
 }
 /** internal: exported for the stream lifecycle tests. */