humanish 0.15.3 → 0.16.0

package/dist/cua-actor-lab.js

@@ -58,7 +58,7 @@ const DEFAULT_SESSION_TIMEOUT_MS = 300_000;
 // Settle after opening the browser, before the first screenshot — long enough for a cold
 // browser + page load to paint (2s captured a blank desktop; the render empirically needs ~6-9s).
 const BROWSER_SETTLE_MS = 8_000;
-// Device/viewport comes from the named-preset registry (device-presets.ts), selectable per run
+// Device/screen size comes from the named-preset registry (device-presets.ts), selectable per run
 // via execution.desktop.device (default `desktop`=1440x950). NOTE: this is run-wide for now; a
 // per-PERSONA device dimension (N personas × devices, as the bespoke sims author) lands with
 // fan-out. On this E2B-desktop route only width/height physically render — isMobile/DSF are
@@ -403,31 +403,34 @@ export function makeLaneWriteScreenshot(artifactRoot, spec, screenshots) {
     };
 }
 /**
- * Verify the desktop geometry IN-SANDBOX (the per-lane device claim is checked, never assumed).
- * Returns a fail-closed DEVICE_GEOMETRY message on a PARSEABLE mismatch. When xdpyinfo is
- * unavailable or unparseable (only in fakes — a real E2B desktop always answers), it cannot be
- * verified, so the lane proceeds with the requested geometry (no false failure).
+ * Verify the desktop screen geometry IN-SANDBOX (the per-lane device claim is checked, never
+ * assumed). A parseable mismatch fails closed. Unavailable/unparseable evidence is returned as
+ * an explicit warning: the lane may still run, but its bundle records only the requested screen
+ * and never upgrades that request into a verified measurement.
  */
-async function checkLaneGeometry(desktop, spec, requestTimeoutMs) {
+export async function inspectDesktopScreenGeometry(args) {
     let out = "";
     try {
-        const result = await desktop.commands.run("xdpyinfo 2>/dev/null | grep -i dimensions || true", { requestTimeoutMs });
+        const result = await args.desktop.commands.run("xdpyinfo 2>/dev/null | grep -i dimensions || true", { requestTimeoutMs: args.requestTimeoutMs });
         out = (result.stdout ?? "").trim();
     }
     catch {
-        return undefined;
+        return { warning: `Desktop screen geometry could not be measured for lane ${args.laneId}; requested geometry remains unverified.` };
     }
     const match = out.match(/(\d+)\s*x\s*(\d+)\s*pixels/i);
     if (!match) {
-        return undefined;
+        return { warning: `Desktop screen geometry could not be parsed for lane ${args.laneId}; requested geometry remains unverified.` };
     }
     const width = Number(match[1]);
     const height = Number(match[2]);
-    const [expectedWidth, expectedHeight] = spec.resolution;
+    const [expectedWidth, expectedHeight] = args.requestedScreen;
     if (width === expectedWidth && height === expectedHeight) {
-        return undefined;
+        return { verified: { width, height, source: "xdpyinfo" } };
     }
-    return `HUMANISH_CUA_LAB_DEVICE_GEOMETRY: lane ${spec.laneId} requested a ${expectedWidth}x${expectedHeight} desktop but xdpyinfo reports ${width}x${height} in-sandbox; the per-lane device geometry is unverified (fail-closed).`;
+    return {
+        verified: { width, height, source: "xdpyinfo" },
+        error: `HUMANISH_CUA_LAB_DEVICE_GEOMETRY: lane ${args.laneId} requested a ${expectedWidth}x${expectedHeight} desktop but xdpyinfo reports ${width}x${height} in-sandbox; the per-lane device geometry is unverified (fail-closed).`
+    };
 }
 /** A blocked lane outcome (pipeline gate / fail-fast skipped it before it ran). */
 function blockedLaneOutcome(spec, reason) {
@@ -445,27 +448,58 @@ function blockedLaneOutcome(spec, reason) {
         harnessError: false
     };
 }
-async function findVisibleBrowserWindowId(desktop, requestTimeoutMs) {
+async function findVisibleBrowserWindowId(desktop, requestTimeoutMs, browserFamily, launchIdentity) {
+    if (browserFamily === "unknown")
+        return undefined;
+    // The candidate loop keeps the LAST identity match: with a launch identity the match is
+    // unique anyway, and without one every family candidate matches, so the newest visible
+    // window of the launched family wins (the window this lane just opened).
+    const finder = browserFamily === "firefox"
+        ? [
+            "find_firefox_window() {",
+            "  timeout 2s xdotool search --onlyvisible --class 'firefox|Firefox' 2>/dev/null || true",
+            "}",
+            "window_id=",
+            "for _ in $(seq 1 10); do",
+            "  for candidate in $(find_firefox_window); do",
+            "    window_pid=\"$(xdotool getwindowpid \"$candidate\" 2>/dev/null || true)\"",
+            "    if matches_launch_identity \"$window_pid\"; then window_id=\"$candidate\"; fi",
+            "  done",
+            "  if [ -n \"$window_id\" ]; then break; fi",
+            "  sleep 0.5",
+            "done"
+        ]
+        : [
+            "find_chrome_window() {",
+            "  timeout 2s xdotool search --onlyvisible --class 'google-chrome|Google-chrome|chromium|Chromium|chrome|Chrome' 2>/dev/null || true",
+            "}",
+            "window_id=",
+            "for _ in $(seq 1 10); do",
+            "  for candidate in $(find_chrome_window); do",
+            "    window_pid=\"$(xdotool getwindowpid \"$candidate\" 2>/dev/null || true)\"",
+            "    if matches_launch_identity \"$window_pid\"; then window_id=\"$candidate\"; fi",
+            "  done",
+            "  if [ -n \"$window_id\" ]; then break; fi",
+            "  sleep 0.5",
+            "done"
+        ];
     const result = await desktop.commands.run([
         "set -euo pipefail",
         "export DISPLAY=\"${DISPLAY:-:0}\"",
-        "find_chrome_window() {",
-        "  timeout 2s xdotool search --onlyvisible --class 'google-chrome|Google-chrome|chromium|Chromium|chrome|Chrome' 2>/dev/null | tail -n 1 || true",
-        "}",
-        "find_firefox_window() {",
-        "  timeout 2s xdotool search --onlyvisible --class 'firefox|Firefox' 2>/dev/null | tail -n 1 || true",
-        "}",
-        "find_named_window() {",
-        "  timeout 2s xdotool search --onlyvisible --name 'Google Chrome|Chromium|Mozilla Firefox|127[.]0[.]0[.]1|localhost|e2b[.]app|e2b[.]dev' 2>/dev/null | tail -n 1 || true",
+        `launch_pid=${shellSingleQuote(launchIdentity?.processId ?? "")}`,
+        `profile_dir=${shellSingleQuote(launchIdentity?.profileDir ?? "")}`,
+        "matches_launch_identity() {",
+        "  if [ -z \"$launch_pid\" ] && [ -z \"$profile_dir\" ]; then return 0; fi",
+        "  local current=\"${1:-}\"",
+        "  while [[ \"$current\" =~ ^[0-9]+$ ]] && [ \"$current\" -gt 1 ]; do",
+        "    cmdline=\"$(tr '\\0' ' ' < \"/proc/$current/cmdline\" 2>/dev/null || true)\"",
+        "    if [ -n \"$profile_dir\" ] && [[ \"$cmdline\" == *\"$profile_dir\"* ]]; then return 0; fi",
+        "    if [ \"$current\" = \"$launch_pid\" ]; then return 0; fi",
+        "    current=\"$(ps -o ppid= -p \"$current\" 2>/dev/null | tr -d ' ' || true)\"",
+        "  done",
+        "  return 1",
         "}",
-        "window_id=",
-        "for _ in $(seq 1 10); do",
-        "  window_id=\"$(find_chrome_window)\"",
-        "  if [ -z \"$window_id\" ]; then window_id=\"$(find_firefox_window)\"; fi",
-        "  if [ -z \"$window_id\" ]; then window_id=\"$(find_named_window)\"; fi",
-        "  if [ -n \"$window_id\" ]; then break; fi",
-        "  sleep 0.5",
-        "done",
+        ...finder,
         "if [ -n \"$window_id\" ]; then printf 'WINDOW_ID=%s\\n' \"$window_id\"; fi"
     ].join("\n"), {
         requestTimeoutMs,
@@ -511,9 +545,10 @@ async function openDesktopBrowserTarget(desktop, targetUrl, requestTimeoutMs, br
             "set -euo pipefail",
             `target_url=${shellSingleQuote(targetUrl)}`,
             `browser_preference=${shellSingleQuote(requestedBrowser)}`,
-            "chrome_profile_dir=/tmp/humanish-chrome-profile",
+            "chrome_profile_dir=",
             `chrome_preferences_json=${shellSingleQuote(chromiumEvidenceProfilePreferencesJson())}`,
             "prepare_chrome_profile() {",
+            "  chrome_profile_dir=\"$(mktemp -d /tmp/humanish-chrome-profile.XXXXXX)\"",
             "  mkdir -p \"$chrome_profile_dir/Default\"",
             "  printf '%s\\n' \"$chrome_preferences_json\" > \"$chrome_profile_dir/Default/Preferences\"",
             "}",
@@ -523,38 +558,53 @@ async function openDesktopBrowserTarget(desktop, targetUrl, requestTimeoutMs, br
             "  shift 2",
             "  if command -v \"$binary\" >/dev/null 2>&1; then",
             "    nohup \"$binary\" \"$@\" \"$target_url\" >/tmp/humanish-browser-open.log 2>&1 &",
+            "    local launch_pid=$!",
             "    printf 'HUMANISH_BROWSER_RESOLVED=%s\\n' \"$label\"",
+            "    printf 'HUMANISH_BROWSER_PID=%s\\n' \"$launch_pid\"",
+            "    printf 'HUMANISH_BROWSER_PROFILE_DIR=%s\\n' \"$chrome_profile_dir\"",
+            "    if [[ \"$label\" =~ ^(google-chrome|google-chrome-stable|chromium|chromium-browser)$ ]]; then",
+            "      for _ in $(seq 1 30); do",
+            "        if [ -s \"$chrome_profile_dir/DevToolsActivePort\" ]; then",
+            "          head -n 1 \"$chrome_profile_dir/DevToolsActivePort\" | sed 's/^/HUMANISH_BROWSER_CDP_PORT=/'",
+            "          break",
+            "        fi",
+            "        sleep 0.1",
+            "      done",
+            "    fi",
             "    return 0",
             "  fi",
             "  return 1",
             "}",
-            `chrome_debug_flags=(--remote-debugging-address=127.0.0.1 --remote-debugging-port=9222 "--user-data-dir=$chrome_profile_dir" ${chromiumFlags})`,
-            "prepare_chrome_profile",
+            `chrome_debug_flags=(--remote-debugging-address=127.0.0.1 --remote-debugging-port=0 ${chromiumFlags})`,
             "open_target() {",
             "  case \"$browser_preference\" in",
             "    chrome)",
-            "      launch_browser google-chrome google-chrome --new-window \"${chrome_debug_flags[@]}\" && return 0",
-            "      launch_browser google-chrome-stable google-chrome-stable --new-window \"${chrome_debug_flags[@]}\" && return 0",
+            "      prepare_chrome_profile",
+            "      launch_browser google-chrome google-chrome --new-window \"--user-data-dir=$chrome_profile_dir\" \"${chrome_debug_flags[@]}\" && return 0",
+            "      launch_browser google-chrome-stable google-chrome-stable --new-window \"--user-data-dir=$chrome_profile_dir\" \"${chrome_debug_flags[@]}\" && return 0",
             "      echo 'requested browser chrome was not found' >&2",
             "      return 127",
             "      ;;",
             "    chromium)",
-            "      launch_browser chromium chromium --new-window \"${chrome_debug_flags[@]}\" && return 0",
-            "      launch_browser chromium-browser chromium-browser --new-window \"${chrome_debug_flags[@]}\" && return 0",
+            "      prepare_chrome_profile",
+            "      launch_browser chromium chromium --new-window \"--user-data-dir=$chrome_profile_dir\" \"${chrome_debug_flags[@]}\" && return 0",
+            "      launch_browser chromium-browser chromium-browser --new-window \"--user-data-dir=$chrome_profile_dir\" \"${chrome_debug_flags[@]}\" && return 0",
             "      echo 'requested browser chromium was not found' >&2",
             "      return 127",
             "      ;;",
             "    firefox)",
-            "      launch_browser firefox firefox --new-window && return 0",
+            "      prepare_chrome_profile",
+            "      launch_browser firefox firefox --new-instance --no-remote --new-window --profile \"$chrome_profile_dir\" && return 0",
             "      echo 'requested browser firefox was not found' >&2",
             "      return 127",
             "      ;;",
             "    default)",
-            "      launch_browser google-chrome google-chrome --new-window \"${chrome_debug_flags[@]}\" && return 0",
-            "      launch_browser google-chrome-stable google-chrome-stable --new-window \"${chrome_debug_flags[@]}\" && return 0",
-            "      launch_browser chromium chromium --new-window \"${chrome_debug_flags[@]}\" && return 0",
-            "      launch_browser chromium-browser chromium-browser --new-window \"${chrome_debug_flags[@]}\" && return 0",
-            "      launch_browser firefox firefox --new-window && return 0",
+            "      prepare_chrome_profile",
+            "      launch_browser google-chrome google-chrome --new-window \"--user-data-dir=$chrome_profile_dir\" \"${chrome_debug_flags[@]}\" && return 0",
+            "      launch_browser google-chrome-stable google-chrome-stable --new-window \"--user-data-dir=$chrome_profile_dir\" \"${chrome_debug_flags[@]}\" && return 0",
+            "      launch_browser chromium chromium --new-window \"--user-data-dir=$chrome_profile_dir\" \"${chrome_debug_flags[@]}\" && return 0",
+            "      launch_browser chromium-browser chromium-browser --new-window \"--user-data-dir=$chrome_profile_dir\" \"${chrome_debug_flags[@]}\" && return 0",
+            "      launch_browser firefox firefox --new-instance --no-remote --new-window --profile \"$chrome_profile_dir\" && return 0",
             "      launch_browser xdg-open xdg-open && return 0",
             "      echo 'no browser opener found' >&2",
             "      return 127",
@@ -571,9 +621,18 @@ async function openDesktopBrowserTarget(desktop, targetUrl, requestTimeoutMs, br
             throw new Error(`browser launch failed with exit ${result.exitCode}: ${tailOf(result.stderr ?? result.stdout ?? "")}`);
         }
         const resolved = (result.stdout ?? "").match(/^HUMANISH_BROWSER_RESOLVED=(\S+)$/m)?.[1];
-        return browserPreference === undefined ? undefined : {
-            requested: requestedBrowser,
-            ...(resolved === undefined ? {} : { resolved })
+        const processId = (result.stdout ?? "").match(/^HUMANISH_BROWSER_PID=(\d+)$/m)?.[1];
+        const profileDir = (result.stdout ?? "").match(/^HUMANISH_BROWSER_PROFILE_DIR=(\S+)$/m)?.[1];
+        const cdpPortRaw = (result.stdout ?? "").match(/^HUMANISH_BROWSER_CDP_PORT=(\d+)$/m)?.[1];
+        const cdpPort = cdpPortRaw === undefined ? undefined : Number(cdpPortRaw);
+        return {
+            family: desktopBrowserFamily(resolved ?? requestedBrowser),
+            ...(processId === undefined || profileDir === undefined
+                ? {}
+                : { identity: { processId, profileDir, targetUrl, ...(cdpPort === undefined ? {} : { cdpPort }) } }),
+            ...(browserPreference === undefined
+                ? {}
+                : { evidence: { requested: requestedBrowser, ...(resolved === undefined ? {} : { resolved }) } })
         };
     }
     if (browserPreference === undefined || browserPreference === "default") {
@@ -583,20 +642,68 @@ async function openDesktopBrowserTarget(desktop, targetUrl, requestTimeoutMs, br
         else {
             await desktop.launch("google-chrome", targetUrl);
         }
-        return browserPreference === undefined ? undefined : { requested: requestedBrowser };
+        return {
+            family: desktop.open ? "unknown" : "chromium",
+            ...(browserPreference === undefined ? {} : { evidence: { requested: requestedBrowser } })
+        };
     }
     const launchTarget = requestedBrowser === "chrome" ? "google-chrome"
         : requestedBrowser === "chromium" ? "chromium"
             : requestedBrowser === "firefox" ? "firefox"
                 : "google-chrome";
     await desktop.launch(launchTarget, targetUrl);
-    return { requested: requestedBrowser, resolved: launchTarget };
+    return {
+        family: desktopBrowserFamily(launchTarget),
+        evidence: { requested: requestedBrowser, resolved: launchTarget }
+    };
+}
+export function desktopBrowserFamily(value) {
+    if (value === "firefox")
+        return "firefox";
+    if (value === "chrome" || value === "chromium" || value === "google-chrome" || value === "google-chrome-stable" || value === "chromium-browser") {
+        return "chromium";
+    }
+    return "unknown";
+}
+/**
+ * Observe-time CDP port resolution lines (pure; exported for contract tests): cached
+ * launch-time port first, then a re-read of the profile's DevToolsActivePort marker, then the
+ * legacy fixed 9222. The re-read is a local best-effort file read inside the already
+ * time-bounded observer command, so a missing/garbled marker degrades to the fallback,
+ * never a hang.
+ */
+export function chromeCdpPortResolutionScript(endpoint) {
+    return [
+        `let cdpPort = ${endpoint.cdpPort === undefined ? "undefined" : JSON.stringify(endpoint.cdpPort)};`,
+        `const cdpProfileDir = ${JSON.stringify(endpoint.profileDir ?? "")};`,
+        "if (cdpPort === undefined && cdpProfileDir) {",
+        "  try {",
+        "    const { readFileSync } = await import('node:fs');",
+        "    const marker = readFileSync(cdpProfileDir + '/DevToolsActivePort', 'utf8');",
+        "    const parsed = Number.parseInt(String(marker.split('\\n')[0] ?? ''), 10);",
+        "    if (Number.isInteger(parsed) && parsed > 0) cdpPort = parsed;",
+        "  } catch {}",
+        "}",
+        "if (cdpPort === undefined) cdpPort = 9222;"
+    ];
 }
-export function makeChromeBrowserStateObserver(desktop, requestTimeoutMs) {
+/** Shared CDP page-selection preamble: pinned target id first, then this lane's target URL,
+ *  then a single-page fallback; never an arbitrary page from a multi-page endpoint. */
+function chromeCdpPageSelectionScript(endpoint, targetId) {
+    return [
+        ...chromeCdpPortResolutionScript(endpoint),
+        "const pages = await fetch('http://127.0.0.1:' + cdpPort + '/json').then((r) => r.json()).catch(() => []);",
+        `const expectedTargetId = ${JSON.stringify(targetId ?? "")};`,
+        `const expectedTargetUrl = ${JSON.stringify(endpoint.targetUrl)};`,
+        "const normalizeUrl = (value) => String(value || '').replace(/\\/$/, '');",
+        "const httpPages = Array.isArray(pages) ? pages.filter((entry) => entry && entry.type === 'page' && /^https?:/.test(String(entry.url || ''))) : [];",
+        "const page = expectedTargetId ? httpPages.find((entry) => entry.id === expectedTargetId) : (httpPages.find((entry) => normalizeUrl(entry.url) === normalizeUrl(expectedTargetUrl)) || (httpPages.length === 1 ? httpPages[0] : undefined));"
+    ];
+}
+export function makeChromeBrowserStateObserver(desktop, requestTimeoutMs, endpoint, targetId) {
     return async () => {
         const script = [
-            "const pages = await fetch('http://127.0.0.1:9222/json').then((r) => r.json()).catch(() => []);",
-            "const page = Array.isArray(pages) ? pages.find((entry) => entry && entry.type === 'page' && /^https?:/.test(String(entry.url || ''))) : undefined;",
+            ...chromeCdpPageSelectionScript(endpoint, targetId),
             "if (!page) { console.log('{}'); process.exit(0); }",
             "let text = '';",
             "let url = String(page.url || '');",
@@ -648,6 +755,153 @@ export function makeChromeBrowserStateObserver(desktop, requestTimeoutMs) {
         }
     };
 }
+/**
+ * Read the running browser's actual outer-window bounds and CSS layout viewport through the
+ * already-enabled local Chrome DevTools endpoint. The returned values come from `window.*` in
+ * the target page; requested E2B resolution is deliberately not an input to this function.
+ */
+export function makeChromeDesktopGeometryObserver(desktop, requestTimeoutMs, endpoint, targetId) {
+    return async () => {
+        const script = [
+            ...chromeCdpPageSelectionScript(endpoint, targetId),
+            "if (!page || typeof WebSocket !== 'function' || !page.webSocketDebuggerUrl) { console.log('{}'); process.exit(0); }",
+            "const ws = new WebSocket(page.webSocketDebuggerUrl);",
+            "const result = await new Promise((resolve) => {",
+            "  const timer = setTimeout(() => resolve(undefined), 1500);",
+            "  ws.onopen = () => ws.send(JSON.stringify({ id: 1, method: 'Runtime.evaluate', params: { returnByValue: true, expression: '({ browserWindow: { x: window.screenX, y: window.screenY, width: window.outerWidth, height: window.outerHeight }, viewport: { width: window.innerWidth, height: window.innerHeight, deviceScaleFactor: window.devicePixelRatio } })' } }));",
+            "  ws.onmessage = (event) => {",
+            "    try {",
+            "      const payload = JSON.parse(String(event.data));",
+            "      if (payload.id !== 1) return;",
+            "      clearTimeout(timer);",
+            "      resolve(payload.result && payload.result.result && payload.result.result.value);",
+            "    } catch { clearTimeout(timer); resolve(undefined); }",
+            "  };",
+            "  ws.onerror = () => { clearTimeout(timer); resolve(undefined); };",
+            "}).finally(() => { try { ws.close(); } catch {} });",
+            "console.log(JSON.stringify(result ? { ...result, targetId: String(page.id || '') } : {}));"
+        ].join("\n");
+        const result = await desktop.commands.run(`node --input-type=module -e ${shellSingleQuote(script)}`, {
+            requestTimeoutMs,
+            timeoutMs: 5_000
+        });
+        if (result.exitCode !== undefined && result.exitCode !== 0) {
+            return undefined;
+        }
+        try {
+            const parsed = JSON.parse((result.stdout ?? "{}").trim() || "{}");
+            if (!parsed || typeof parsed !== "object")
+                return undefined;
+            const record = parsed;
+            const rawWindow = record.browserWindow;
+            const rawViewport = record.viewport;
+            if (!isMeasuredRect(rawWindow) || !isMeasuredViewport(rawViewport))
+                return undefined;
+            return {
+                browserWindow: { ...rawWindow, source: "cdp" },
+                viewport: { ...rawViewport, source: "cdp" },
+                ...(typeof record.targetId === "string" && record.targetId.length > 0 ? { targetId: record.targetId } : {})
+            };
+        }
+        catch {
+            return undefined;
+        }
+    };
+}
+function isMeasuredRect(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const record = value;
+    return Number.isFinite(record.x)
+        && Number.isFinite(record.y)
+        && isPositiveMeasurement(record.width)
+        && isPositiveMeasurement(record.height);
+}
+function isMeasuredViewport(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const record = value;
+    return isPositiveMeasurement(record.width)
+        && isPositiveMeasurement(record.height)
+        && isPositiveMeasurement(record.deviceScaleFactor);
+}
+function isPositiveMeasurement(value) {
+    return typeof value === "number" && Number.isFinite(value) && value > 0;
+}
+async function measureBrowserWindowWithXdotool(desktop, windowId, requestTimeoutMs) {
+    const result = await desktop.commands.run([
+        "set -euo pipefail",
+        `win=${shellSingleQuote(windowId)}`,
+        "xdotool getwindowgeometry --shell \"$win\" 2>/dev/null || true"
+    ].join("\n"), { requestTimeoutMs, timeoutMs: 5_000 });
+    const output = result.stdout ?? "";
+    const read = (name) => {
+        const raw = output.match(new RegExp(`^${name}=(-?\\d+)$`, "m"))?.[1];
+        if (raw === undefined)
+            return undefined;
+        const value = Number(raw);
+        return Number.isFinite(value) ? value : undefined;
+    };
+    const x = read("X");
+    const y = read("Y");
+    const width = read("WIDTH");
+    const height = read("HEIGHT");
+    if (x === undefined || y === undefined || width === undefined || height === undefined || width <= 0 || height <= 0) {
+        return undefined;
+    }
+    return { x, y, width, height, source: "xdotool" };
+}
+/** Shared hosted-browser geometry capture used by per-lane and sequential shared-world routes. */
+export async function captureDesktopBrowserGeometry(args) {
+    const warnings = [];
+    let browserWindowId = args.browserWindowId;
+    if (browserWindowId === undefined && args.browserFamily !== "unknown") {
+        browserWindowId = await findVisibleBrowserWindowId(args.desktop, args.requestTimeoutMs, args.browserFamily, args.launchIdentity).catch((error) => {
+            warnings.push(`Browser window lookup failed for lane ${args.laneId}: ${redactText(toErrorMessage(error))}`);
+            return undefined;
+        });
+    }
+    let xdotoolWindow;
+    if (browserWindowId !== undefined) {
+        if (args.resize !== false) {
+            await fillDesktopBrowserWindow(args.desktop, browserWindowId, args.requestedScreen, args.requestTimeoutMs);
+            // Let the window manager apply the resize before querying both X and page layout geometry.
+            await args.desktop.wait(250).catch(() => undefined);
+        }
+        xdotoolWindow = await measureBrowserWindowWithXdotool(args.desktop, browserWindowId, args.requestTimeoutMs)
+            .catch(() => undefined);
+    }
+    else {
+        warnings.push(`Browser window bounds could not be measured for lane ${args.laneId}; the live stream will use the full desktop.`);
+    }
+    const chromeGeometry = args.browserFamily === "chromium"
+        ? await makeChromeDesktopGeometryObserver(args.desktop, args.requestTimeoutMs, {
+            ...(args.launchIdentity?.cdpPort === undefined ? {} : { cdpPort: args.launchIdentity.cdpPort }),
+            ...(args.launchIdentity?.profileDir === undefined ? {} : { profileDir: args.launchIdentity.profileDir }),
+            targetUrl: args.targetUrl
+        }, args.browserTargetId)().catch(() => undefined)
+        : undefined;
+    const browserWindow = chromeGeometry?.browserWindow ?? xdotoolWindow;
+    const viewport = chromeGeometry?.viewport;
+    if (!browserWindow) {
+        warnings.push(`Browser outer bounds could not be measured for lane ${args.laneId}.`);
+    }
+    else if (browserWindow.width !== args.requestedScreen[0] || browserWindow.height !== args.requestedScreen[1]) {
+        warnings.push(`Browser window fill did not reach the requested ${args.requestedScreen[0]}x${args.requestedScreen[1]} screen for lane ${args.laneId}; measured outer bounds are ${browserWindow.width}x${browserWindow.height}.`);
+    }
+    if (!viewport) {
+        warnings.push(args.browserFamily === "firefox"
+            ? `Browser CSS viewport measurement is unavailable for Firefox on lane ${args.laneId}; stream.viewport is omitted instead of reading a different browser's CDP endpoint.`
+            : `Browser CSS viewport could not be measured for lane ${args.laneId}; stream.viewport is omitted instead of copying the requested screen resolution.`);
+    }
+    return {
+        ...(browserWindowId === undefined ? {} : { browserWindowId }),
+        ...(chromeGeometry?.targetId === undefined ? {} : { browserTargetId: chromeGeometry.targetId }),
+        ...(browserWindow === undefined ? {} : { browserWindow }),
+        ...(viewport === undefined ? {} : { viewport }),
+        warnings
+    };
+}
 function shellSingleQuote(value) {
     return `'${value.replace(/'/g, "'\\''")}'`;
 }
@@ -714,6 +968,15 @@ export async function runCuaLane(spec, deps) {
     let streamUrl;
     let subjectCommit;
     let desktopBrowser;
+    let launchedBrowserFamily = "unknown";
+    let browserLaunchIdentity;
+    let browserLaunched = false;
+    let initialBrowserGeometry;
+    let browserWindowId;
+    let browserTargetId;
+    let desktopGeometry = {
+        screen: { requested: { width: spec.resolution[0], height: spec.resolution[1] } }
+    };
     let provisioned = false;
     let signaled = false;
     const signal = (ok) => {
@@ -754,12 +1017,37 @@ export async function runCuaLane(spec, deps) {
             await deps.hooks.prepareDesktop(desktop, { laneId: spec.laneId, laneIndex: spec.laneIndex, laneCount: deps.laneCount });
         }
         // Per-lane geometry assertion (fail-closed) — the device claim is verified in-sandbox.
-        const geometryError = await checkLaneGeometry(desktop, spec, deps.requestTimeoutMs);
-        if (geometryError) {
-            sessionError = geometryError;
+        const screenGeometry = await inspectDesktopScreenGeometry({
+            desktop,
+            laneId: spec.laneId,
+            requestedScreen: spec.resolution,
+            requestTimeoutMs: deps.requestTimeoutMs
+        });
+        if (screenGeometry.verified) {
+            desktopGeometry = {
+                ...desktopGeometry,
+                screen: { ...desktopGeometry.screen, verified: screenGeometry.verified }
+            };
+        }
+        if (screenGeometry.warning) {
+            warnings.push(screenGeometry.warning);
+            desktopGeometry = { ...desktopGeometry, warnings: [screenGeometry.warning] };
+        }
+        if (screenGeometry.error && deps.screenMismatchPolicy !== "record-evidence") {
+            sessionError = screenGeometry.error;
             failureCode = "HUMANISH_CUA_LAB_DEVICE_GEOMETRY";
         }
         else {
+            if (screenGeometry.error && screenGeometry.verified) {
+                // record-evidence policy: the bundle keeps requested vs verified as separate facts and
+                // discloses the divergence instead of failing this lane's world mid-flight.
+                const mismatchWarning = deps.scrubKnownValues(`Lane ${spec.laneId} requested a ${spec.resolution[0]}x${spec.resolution[1]} screen but xdpyinfo reports ${screenGeometry.verified.width}x${screenGeometry.verified.height}; recording requested vs verified separately instead of failing the lane closed.`);
+                warnings.push(mismatchWarning);
+                desktopGeometry = {
+                    ...desktopGeometry,
+                    warnings: [...(desktopGeometry.warnings ?? []), mismatchWarning]
+                };
+            }
             if (cloneRoute && serve && subjectRepo) {
                 subjectCommit = await provisionCloneSubject(desktop, {
                     repo: subjectRepo,
@@ -793,20 +1081,28 @@ export async function runCuaLane(spec, deps) {
                     ...(deps.hooks.detachedTimers ?? {})
                 });
             }
-            desktopBrowser = await openDesktopBrowserTarget(desktop, targetUrl, deps.requestTimeoutMs, config.execution?.desktop?.browser);
+            const browserLaunch = await openDesktopBrowserTarget(desktop, targetUrl, deps.requestTimeoutMs, config.execution?.desktop?.browser);
+            desktopBrowser = browserLaunch.evidence;
+            launchedBrowserFamily = browserLaunch.family;
+            browserLaunchIdentity = browserLaunch.identity;
+            browserLaunched = true;
             await desktop.wait(BROWSER_SETTLE_MS).catch(() => undefined);
             // World is ready: release the pipeline gate so the remaining lanes may start.
             provisioned = true;
             signal(true);
             try {
-                const browserWindowId = await findVisibleBrowserWindowId(desktop, deps.requestTimeoutMs)
-                    .catch((error) => {
-                    warnings.push(`Browser window lookup failed before live stream start (falling back to desktop stream): ${redactText(deps.scrubKnownValues(toErrorMessage(error)))}`);
-                    return undefined;
+                const browserGeometry = await captureDesktopBrowserGeometry({
+                    desktop,
+                    browserFamily: launchedBrowserFamily,
+                    ...(browserLaunchIdentity === undefined ? {} : { launchIdentity: browserLaunchIdentity }),
+                    laneId: spec.laneId,
+                    targetUrl,
+                    requestedScreen: spec.resolution,
+                    requestTimeoutMs: deps.requestTimeoutMs
                 });
-                if (browserWindowId !== undefined) {
-                    await fillDesktopBrowserWindow(desktop, browserWindowId, spec.resolution, deps.requestTimeoutMs);
-                }
+                initialBrowserGeometry = browserGeometry;
+                browserWindowId = browserGeometry.browserWindowId;
+                browserTargetId = browserGeometry.browserTargetId;
                 await startDesktopStream(desktop, browserWindowId);
                 const candidateStreamUrl = desktop.stream.getUrl({
                     authKey: desktop.stream.getAuthKey(),
@@ -840,9 +1136,17 @@ export async function runCuaLane(spec, deps) {
                     ...(config.actors[0]?.model ? { model: config.actors[0].model } : {})
                 },
                 desktop: desktop,
-                executorOptions: {
-                    observeBrowserState: makeChromeBrowserStateObserver(desktop, deps.requestTimeoutMs)
-                },
+                ...(launchedBrowserFamily === "chromium"
+                    ? {
+                        executorOptions: {
+                            observeBrowserState: makeChromeBrowserStateObserver(desktop, deps.requestTimeoutMs, {
+                                ...(browserLaunchIdentity?.cdpPort === undefined ? {} : { cdpPort: browserLaunchIdentity.cdpPort }),
+                                ...(browserLaunchIdentity?.profileDir === undefined ? {} : { profileDir: browserLaunchIdentity.profileDir }),
+                                targetUrl
+                            }, browserTargetId)
+                        }
+                    }
+                    : {}),
                 redactScreenshots: deps.redactScreenshots,
                 scrubText: deps.scrubKnownValues,
                 writeScreenshot,
@@ -859,6 +1163,39 @@ export async function runCuaLane(spec, deps) {
             signal(false);
         }
         if (desktop && desktopModule) {
+            if (browserLaunched) {
+                const finalGeometry = await captureDesktopBrowserGeometry({
+                    desktop,
+                    browserFamily: launchedBrowserFamily,
+                    ...(browserLaunchIdentity === undefined ? {} : { launchIdentity: browserLaunchIdentity }),
+                    ...(browserWindowId === undefined ? {} : { browserWindowId }),
+                    ...(browserTargetId === undefined ? {} : { browserTargetId }),
+                    laneId: spec.laneId,
+                    targetUrl,
+                    requestedScreen: spec.resolution,
+                    requestTimeoutMs: deps.requestTimeoutMs,
+                    resize: false
+                }).catch((error) => ({
+                    warnings: [`Final browser geometry measurement failed for lane ${spec.laneId}: ${redactText(deps.scrubKnownValues(toErrorMessage(error)))}`]
+                }));
+                // Chosen capture rule: final-if-it-measured-anything, else launch-time. A final capture
+                // that measured EITHER field wins whole, so a partial final capture omits fields the
+                // launch-time capture had (honest omission); only a final capture that measured NOTHING
+                // falls back to the launch-time capture.
+                const chosenGeometry = finalGeometry.browserWindow !== undefined || finalGeometry.viewport !== undefined
+                    ? finalGeometry
+                    : initialBrowserGeometry ?? finalGeometry;
+                const geometryWarnings = [...new Set(chosenGeometry.warnings.map((warning) => deps.scrubKnownValues(warning)))];
+                warnings.push(...geometryWarnings);
+                desktopGeometry = {
+                    screen: desktopGeometry.screen,
+                    ...(chosenGeometry.browserWindow === undefined ? {} : { browserWindow: chosenGeometry.browserWindow }),
+                    ...(chosenGeometry.viewport === undefined ? {} : { viewport: chosenGeometry.viewport }),
+                    ...((desktopGeometry.warnings?.length ?? 0) + geometryWarnings.length === 0
+                        ? {}
+                        : { warnings: [...(desktopGeometry.warnings ?? []), ...geometryWarnings] })
+                };
+            }
             const failed = sessionError !== undefined || session === undefined;
             // Each route's own keep flag gates its own lane only: a clone.keep can never leak into
             // a local-tree lane's teardown decision, and vice versa.
@@ -917,6 +1254,7 @@ export async function runCuaLane(spec, deps) {
         screenshots,
         ...(subjectCommit === undefined ? {} : { subjectCommit }),
         ...(desktopBrowser === undefined ? {} : { desktopBrowser }),
+        desktopGeometry,
         stateStepRecords,
         phaseRecords,
         warnings,
@@ -1769,7 +2107,8 @@ function buildSingleLaneBundle(args) {
         mission: spec.instructions,
         persona: spec.persona,
         resolution: spec.resolution,
-        deviceScaleFactor: spec.devicePreset.deviceScaleFactor,
+        desktopRoute: !args.inProcessRoute,
+        ...(outcome?.desktopGeometry === undefined ? {} : { desktopGeometry: outcome.desktopGeometry }),
         isMobile: spec.devicePreset.isMobile,
         runId: args.runId,
         screenshots: outcome?.screenshots ?? [],
@@ -2131,6 +2470,11 @@ export function buildCuaBundle(args) {
             ?? args.sessionError
             ?? "Contract bundle only: dry-run produced the evidence shape without launching a desktop or spending provider tokens.";
     const lastScreenshot = args.screenshots[args.screenshots.length - 1];
+    const desktopGeometry = args.desktopRoute === false
+        ? undefined
+        : args.desktopGeometry ?? {
+            screen: { requested: { width: args.resolution[0], height: args.resolution[1] } }
+        };
     // Honest labels (invariant 6: claims match mechanism): every screenshot label names the
     // run's ACTUAL mode. The session trace is the evidence-of-record; the capture policy covers
     // frames written before a mid-session failure produced a trace.
@@ -2174,12 +2518,17 @@ export function buildCuaBundle(args) {
         embed: lastScreenshot
             ? { kind: "screenshot", url: lastScreenshot, title: `CUA desktop (${screenshotMode})` }
             : { kind: "placeholder", title: "CUA desktop" },
-        viewport: {
-            width: args.resolution[0],
-            height: args.resolution[1],
-            deviceScaleFactor: args.deviceScaleFactor ?? 1,
-            ...(args.isMobile === undefined ? {} : { isMobile: args.isMobile })
-        },
+        ...(desktopGeometry?.viewport === undefined
+            ? {}
+            : {
+                viewport: {
+                    width: desktopGeometry.viewport.width,
+                    height: desktopGeometry.viewport.height,
+                    deviceScaleFactor: desktopGeometry.viewport.deviceScaleFactor,
+                    ...(args.isMobile === undefined ? {} : { isMobile: args.isMobile })
+                }
+            }),
+        ...(desktopGeometry === undefined ? {} : { desktopGeometry }),
         ui: {
             route: publicAppUrl,
             intent: "Watch the computer-use actor drive the subject app in a hosted desktop browser.",
@@ -2293,6 +2642,17 @@ export function buildCuaBundle(args) {
             streamId: "stream-001"
         });
     }
+    for (const warning of desktopGeometry?.warnings ?? []) {
+        events.push({
+            id: `event-${String(phaseEventSeq++).padStart(3, "0")}-geometry-warning`,
+            at: args.createdAt,
+            level: "warn",
+            type: "cua-lab.geometry.warning",
+            message: warning,
+            simId: "sim-001",
+            streamId: "stream-001"
+        });
+    }
     const review = {
         schema: REVIEW_SCHEMA,
         verdict: args.inProgress === true
@@ -2439,6 +2799,9 @@ export function buildCuaFanoutBundle(args) {
         const publicLaneAppUrl = publicSafeAppUrlLabel(laneAppUrl);
         const subject = args.laneSubjects[index];
         const session = outcome?.session;
+        const desktopGeometry = outcome?.desktopGeometry ?? {
+            screen: { requested: { width: spec.resolution[0], height: spec.resolution[1] } }
+        };
         const screenshots = outcome?.screenshots ?? [];
         const lastScreenshot = screenshots[screenshots.length - 1];
         const status = args.inProgress === true && outcome === undefined
@@ -2498,12 +2861,17 @@ export function buildCuaFanoutBundle(args) {
             embed: lastScreenshot
                 ? { kind: "screenshot", url: lastScreenshot, title: `CUA desktop ${spec.laneId} (${screenshotMode})` }
                 : { kind: "placeholder", title: `CUA desktop ${spec.laneId}` },
-            viewport: {
-                width: spec.resolution[0],
-                height: spec.resolution[1],
-                deviceScaleFactor: spec.devicePreset.deviceScaleFactor,
-                isMobile: spec.devicePreset.isMobile
-            },
+            ...(desktopGeometry.viewport === undefined
+                ? {}
+                : {
+                    viewport: {
+                        width: desktopGeometry.viewport.width,
+                        height: desktopGeometry.viewport.height,
+                        deviceScaleFactor: desktopGeometry.viewport.deviceScaleFactor,
+                        isMobile: spec.devicePreset.isMobile
+                    }
+                }),
+            desktopGeometry,
             ui: {
                 route: publicLaneAppUrl,
                 intent: `Watch lane ${spec.laneId} (${spec.persona.id}/${spec.deviceName}) drive the subject app in its own hosted desktop.`,
@@ -2628,6 +2996,17 @@ export function buildCuaFanoutBundle(args) {
                 streamId: spec.streamId
             });
         }
+        for (const warning of desktopGeometry.warnings ?? []) {
+            events.push({
+                id: nextEventId(`geometry-warning-${spec.laneId}`),
+                at: args.createdAt,
+                level: "warn",
+                type: "cua-lab.geometry.warning",
+                message: warning,
+                simId: spec.simId,
+                streamId: spec.streamId
+            });
+        }
         // Persisted per-lane phase trail (real boot timing): one RunEvent per COMPLETED phase
         // boundary this lane recorded (started events never persist here; they carry no durationMs).
         for (const phase of outcome?.phaseRecords ?? []) {