humanish 0.15.3 → 0.17.0

package/dist/serve-tunnel.d.ts

@@ -0,0 +1,16 @@
+import { spawn } from "node:child_process";
+export type ServeTunnelErrorCode = "HUMANISH_SERVE_TUNNEL_NOT_FOUND" | "HUMANISH_SERVE_TUNNEL_START_FAILED";
+export declare class ServeTunnelError extends Error {
+    readonly code: ServeTunnelErrorCode;
+    constructor(code: ServeTunnelErrorCode, message: string);
+}
+export interface ServeTunnel {
+    url: string;
+    close(): Promise<void>;
+}
+export declare function startNgrokTunnel(options: {
+    port: number;
+    domain?: string;
+    timeoutMs?: number;
+    spawnImpl?: typeof spawn;
+}): Promise<ServeTunnel>;

package/dist/serve-tunnel.js

@@ -0,0 +1,104 @@
+import { spawn } from "node:child_process";
+export class ServeTunnelError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "ServeTunnelError";
+        this.code = code;
+    }
+}
+export async function startNgrokTunnel(options) {
+    const spawnImpl = options.spawnImpl ?? spawn;
+    const timeoutMs = options.timeoutMs ?? 15_000;
+    const args = [
+        "http",
+        "--log",
+        "stdout",
+        "--log-format",
+        "json",
+        ...(options.domain ? ["--url", options.domain] : []),
+        String(options.port)
+    ];
+    const child = spawnImpl("ngrok", args, { stdio: ["ignore", "pipe", "ignore"] });
+    const url = await new Promise((resolve, reject) => {
+        let settled = false;
+        let buffered = "";
+        const settle = (outcome) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            clearTimeout(timer);
+            if ("url" in outcome) {
+                resolve(outcome.url);
+            }
+            else {
+                killChild(child);
+                reject(outcome.error);
+            }
+        };
+        const timer = setTimeout(() => {
+            settle({
+                error: new ServeTunnelError("HUMANISH_SERVE_TUNNEL_START_FAILED", `ngrok did not report a started tunnel within ${timeoutMs}ms.`)
+            });
+        }, timeoutMs);
+        child.once("error", (error) => {
+            settle({
+                error: error.code === "ENOENT"
+                    ? new ServeTunnelError("HUMANISH_SERVE_TUNNEL_NOT_FOUND", "ngrok binary not found on PATH. Install ngrok, or run your own tunnel and pass --public-url <origin>.")
+                    : new ServeTunnelError("HUMANISH_SERVE_TUNNEL_START_FAILED", `ngrok failed to start: ${error.message}`)
+            });
+        });
+        child.once("exit", (code) => {
+            settle({
+                error: new ServeTunnelError("HUMANISH_SERVE_TUNNEL_START_FAILED", `ngrok exited (${code ?? "signal"}) before reporting a started tunnel.`)
+            });
+        });
+        child.stdout?.setEncoding("utf8");
+        child.stdout?.on("data", (chunk) => {
+            buffered += chunk;
+            const lines = buffered.split("\n");
+            buffered = lines.pop() ?? "";
+            for (const line of lines) {
+                let parsed;
+                try {
+                    parsed = JSON.parse(line);
+                }
+                catch {
+                    continue;
+                }
+                if (typeof parsed === "object"
+                    && parsed !== null
+                    && parsed.msg === "started tunnel"
+                    && typeof parsed.url === "string") {
+                    settle({ url: parsed.url });
+                    return;
+                }
+            }
+        });
+    });
+    return {
+        url,
+        close: async () => {
+            await killChild(child);
+        }
+    };
+}
+function killChild(child) {
+    return new Promise((resolve) => {
+        if (child.exitCode !== null || child.signalCode !== null) {
+            resolve();
+            return;
+        }
+        child.once("exit", () => resolve());
+        // Reclamation stays scoped to the exact child this call created.
+        child.kill("SIGTERM");
+        setTimeout(() => {
+            if (child.exitCode === null && child.signalCode === null) {
+                child.kill("SIGKILL");
+            }
+            resolve();
+        }, 2_000).unref();
+    });
+}
+//# sourceMappingURL=serve-tunnel.js.map

package/dist/serve-tunnel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"serve-tunnel.js","sourceRoot":"","sources":["../src/serve-tunnel.ts"],"names":[],"mappings":"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"}

package/dist/shared-world-lab.d.ts

@@ -11,7 +11,7 @@ import { type LabConfig, type LabSubjectStateCheckpoint } from "./lab-config.js"
 import { renderObserver, type ObserverResult } from "./observer.js";
 import type { LocalTreeArchive } from "./source-archive.js";
 import type { StopWhen } from "./stop-conditions.js";
-import { type RunBundle, type RunSubjectProvenance, type SharedWorldCheckpoint } from "./run.js";
+import { type RunBundle, type RunDesktopGeometry, type RunSubjectProvenance, type SharedWorldCheckpoint } from "./run.js";
 export declare const SHARED_WORLD_LAB_SCHEMA = "humanish.shared-world-lab-result.v1";
 export declare const SHARED_WORLD_LAB_PROVIDER_METADATA: {
     readonly mode: "shared-world-lab";
@@ -156,6 +156,7 @@ interface RoleOutcome {
     sessionError?: string;
     screenshots: string[];
     desktopBrowser?: DesktopBrowserEvidence;
+    desktopGeometry?: RunDesktopGeometry;
     /** Set when fail-fast skipped this role before it ran. */
     skippedReason?: string;
     noEngagement: boolean;
@@ -163,6 +164,23 @@ interface RoleOutcome {
     /** The checkpoint snapshot taken AFTER this role's turn (absent for skipped roles). */
     afterCheckpoint?: SharedWorldCheckpoint;
 }
+/**
+ * Self-match-proof pkill/pgrep -f pattern for a seat's unique profile dir: bracket the first
+ * character so the in-sandbox shell running the termination script (whose own command line
+ * carries this pattern) can never match itself. Exported (pure) for contract tests.
+ */
+export declare function seatProfilePkillPattern(profileDir: string): string;
+/**
+ * Build the in-sandbox command that ends ONE seat's browser when its turn ends (pure; exported
+ * for contract tests). All roles share the ONE desktop, so a prior seat's browser left alive
+ * could keep polling/holding websockets and mutating the shared plane during a later role's
+ * turn, with its authenticated window one Alt-Tab away from the current actor. The recorded
+ * launch PID (a setsid session leader) is the primary kill (its process group takes the whole
+ * browser tree); pkill -f on the seat's unique profile dir is the fallback; a short bounded
+ * wait escalates to SIGKILL. Exit is always 0: a termination failure degrades to the caller's
+ * warning, never a failed run.
+ */
+export declare function buildSeatBrowserTerminationCommand(processId: string | undefined, profileDir: string): string;
 /** Combine a snapshot's per-probe digests into ONE sha256-16 (digest-only; no raw value). */
 export declare function combineCheckpointDigest(parts: string[]): string;
 /**
@@ -201,6 +219,7 @@ export declare function buildSharedWorldBundle(args: {
     subject: RunSubjectProvenance;
     sandboxResolution: [number, number];
     sandboxPreset: DevicePreset;
+    desktopGeometry?: RunDesktopGeometry;
     seedDigest: string;
     subjectCommit?: string;
     failFastReason?: string;

package/dist/shared-world-lab.js

@@ -17,16 +17,16 @@
 // persist DIGEST-ONLY. The concurrent (getHost) topology, a handoff/barrier grammar, an onTurn
 // hook, and real per-role login are named NON-GOALS (PR2+).
 //
-// FIDELITY NOTE: one sandbox has ONE desktop geometry, so a role's `device` is a PROMPT SIGNAL
-// (composed into its persona context) — physical per-role geometry is the concurrent topology's
-// job. Each role's stream viewport records the sandbox's actual rendered resolution (honest).
+// FIDELITY NOTE: one sandbox has ONE screen geometry, so a role's `device` is a PROMPT SIGNAL
+// (composed into its persona context) — physical per-role screen geometry is the concurrent
+// topology's job. Each role records its measured browser viewport separately from that screen.
 import { randomBytes } from "node:crypto";
 import path from "node:path";
 import { runDesktopCommandOrThrow, toErrorMessage } from "./command-failure.js";
 import { adapterScoreFailureMessage, applyBrowserAdapterHooks } from "./adapter-extension.js";
 import { actorRegistry, isCuaActorDescriptor } from "./actor-registry.js";
 import { CHROMIUM_EVIDENCE_HYGIENE_FLAGS, chromiumEvidenceProfilePreferencesJson } from "./browser-evidence-hygiene.js";
-import { commandDigestOf, composeLaneInstructions, defaultPackLocalTree, makeChromeBrowserStateObserver, makeLaneWriteScreenshot, provisionCloneSubject, provisionLocalTreeSubject, resolveLaneDevice, resolveSubjectState, SUBJECT_DIR } from "./cua-actor-lab.js";
+import { commandDigestOf, composeLaneInstructions, defaultPackLocalTree, makeChromeBrowserStateObserver, captureDesktopBrowserGeometry, inspectDesktopScreenGeometry, makeLaneWriteScreenshot, provisionCloneSubject, provisionLocalTreeSubject, resolveLaneDevice, resolveSubjectState, SUBJECT_DIR, desktopBrowserFamily } from "./cua-actor-lab.js";
 import { createDesktopSandbox, loadE2BDesktopModule } from "./e2b-desktop-launch.js";
 import { runDetachedStep } from "./e2b-detached.js";
 import { resolveSeatUrl, sharedWorldValidationReason } from "./lab-config.js";
@@ -43,6 +43,8 @@ export const SHARED_WORLD_LAB_PROVIDER_METADATA = {
 const DEFAULT_SESSION_TIMEOUT_MS = 300_000;
 // Settle after opening a seat's browser, before the session's first screenshot.
 const BROWSER_SETTLE_MS = 8_000;
+// In-sandbox budget for ending one seat's browser at turn end (TERM, short wait, KILL).
+const SEAT_BROWSER_TERMINATION_TIMEOUT_MS = 15_000;
 // Server-side reclamation buffer past the loop's own wall-clock stop.
 const SANDBOX_TIMEOUT_BUFFER_MS = 10 * 60_000;
 // Room for the one-time clone/install/build/start/probe + the sequential per-role sessions.
@@ -90,15 +92,27 @@ async function launchSeatBrowser(desktop, args) {
         "  local label=\"$1\"",
         "  local binary=\"$2\"",
         "  if ! command -v \"$binary\" >/dev/null 2>&1; then return 127; fi",
-        "  echo \"HUMANISH_BROWSER_RESOLVED=$label\"",
-        "  pkill -f '[r]emote-debugging-port=9222' 2>/dev/null || true",
         "  prepare_chrome_profile",
-        "  setsid -f \"$binary\" --new-window --remote-debugging-address=127.0.0.1 --remote-debugging-port=9222 --user-data-dir=\"$profile_dir\" \"${chrome_debug_flags[@]}\" \"$seat_url\" > /dev/null 2>&1 < /dev/null",
+        "  rm -f \"$profile_dir/DevToolsActivePort\"",
+        "  setsid \"$binary\" --new-window --remote-debugging-address=127.0.0.1 --remote-debugging-port=0 --user-data-dir=\"$profile_dir\" \"${chrome_debug_flags[@]}\" \"$seat_url\" > /dev/null 2>&1 < /dev/null &",
+        "  local launch_pid=$!",
+        "  echo \"HUMANISH_BROWSER_RESOLVED=$label\"",
+        "  echo \"HUMANISH_BROWSER_PID=$launch_pid\"",
+        "  for _ in $(seq 1 30); do",
+        "    if [ -s \"$profile_dir/DevToolsActivePort\" ]; then",
+        "      head -n 1 \"$profile_dir/DevToolsActivePort\" | sed 's/^/HUMANISH_BROWSER_CDP_PORT=/'",
+        "      break",
+        "    fi",
+        "    sleep 0.1",
+        "  done",
         "}",
         "launch_firefox() {",
         "  if ! command -v firefox >/dev/null 2>&1; then return 127; fi",
+        "  setsid firefox --new-instance --no-remote --new-window --profile \"$profile_dir\" \"$seat_url\" > /dev/null 2>&1 < /dev/null &",
+        "  local launch_pid=$!",
         "  echo \"HUMANISH_BROWSER_RESOLVED=firefox\"",
-        "  setsid -f firefox --new-window --profile \"$profile_dir\" \"$seat_url\" > /dev/null 2>&1 < /dev/null",
+        "  echo \"HUMANISH_BROWSER_PID=$launch_pid\"",
+        "  echo \"HUMANISH_BROWSER_PROFILE_DIR=$profile_dir\"",
         "}",
         "case \"$browser_preference\" in",
         "  chrome)",
@@ -121,15 +135,60 @@ async function launchSeatBrowser(desktop, args) {
     if (args.browserPreference !== undefined && args.browserPreference !== "default" && result.exitCode !== undefined && result.exitCode !== 0) {
         throw new Error(`requested desktop browser "${args.browserPreference}" could not be launched for shared-world seat`);
     }
-    if (args.browserPreference === undefined) {
-        return undefined;
-    }
     const resolved = (result.stdout ?? "").match(/^HUMANISH_BROWSER_RESOLVED=(\S+)$/m)?.[1];
+    const processId = (result.stdout ?? "").match(/^HUMANISH_BROWSER_PID=(\d+)$/m)?.[1];
+    const profileDir = (result.stdout ?? "").match(/^HUMANISH_BROWSER_PROFILE_DIR=(\S+)$/m)?.[1] ?? args.profileDir;
+    const cdpPortRaw = (result.stdout ?? "").match(/^HUMANISH_BROWSER_CDP_PORT=(\d+)$/m)?.[1];
+    const cdpPort = cdpPortRaw === undefined ? undefined : Number(cdpPortRaw);
     return {
-        requested,
-        ...(resolved === undefined ? {} : { resolved })
+        family: desktopBrowserFamily(resolved ?? requested),
+        ...(processId === undefined
+            ? {}
+            : { identity: { processId, profileDir, targetUrl: args.seatUrl, ...(cdpPort === undefined ? {} : { cdpPort }) } }),
+        ...(args.browserPreference === undefined
+            ? {}
+            : { evidence: { requested, ...(resolved === undefined ? {} : { resolved }) } })
     };
 }
+/**
+ * Self-match-proof pkill/pgrep -f pattern for a seat's unique profile dir: bracket the first
+ * character so the in-sandbox shell running the termination script (whose own command line
+ * carries this pattern) can never match itself. Exported (pure) for contract tests.
+ */
+export function seatProfilePkillPattern(profileDir) {
+    const head = profileDir.slice(0, 1);
+    const tail = profileDir.slice(1).replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    return `[${head}]${tail}`;
+}
+/**
+ * Build the in-sandbox command that ends ONE seat's browser when its turn ends (pure; exported
+ * for contract tests). All roles share the ONE desktop, so a prior seat's browser left alive
+ * could keep polling/holding websockets and mutating the shared plane during a later role's
+ * turn, with its authenticated window one Alt-Tab away from the current actor. The recorded
+ * launch PID (a setsid session leader) is the primary kill (its process group takes the whole
+ * browser tree); pkill -f on the seat's unique profile dir is the fallback; a short bounded
+ * wait escalates to SIGKILL. Exit is always 0: a termination failure degrades to the caller's
+ * warning, never a failed run.
+ */
+export function buildSeatBrowserTerminationCommand(processId, profileDir) {
+    return [
+        "set -u",
+        `launch_pid=${shellQuote(processId ?? "")}`,
+        `profile_pattern=${shellQuote(seatProfilePkillPattern(profileDir))}`,
+        'if [ -n "$launch_pid" ]; then',
+        '  kill -TERM -- "-$launch_pid" 2>/dev/null || kill -TERM "$launch_pid" 2>/dev/null || true',
+        "fi",
+        'pkill -TERM -f "$profile_pattern" 2>/dev/null || true',
+        "for _ in $(seq 1 20); do",
+        '  if ! pgrep -f "$profile_pattern" >/dev/null 2>&1; then',
+        "    exit 0",
+        "  fi",
+        "  sleep 0.1",
+        "done",
+        'pkill -KILL -f "$profile_pattern" 2>/dev/null || true',
+        "exit 0"
+    ].join("\n");
+}
 /** Combine a snapshot's per-probe digests into ONE sha256-16 (digest-only; no raw value). */
 export function combineCheckpointDigest(parts) {
     return commandDigestOf(parts.join("\n"));
@@ -300,6 +359,9 @@ export async function runSharedWorldLab(options) {
     let sandboxId;
     let killed = false;
     let failFastReason;
+    let sharedScreenGeometry = {
+        screen: { requested: { width: sandboxResolution[0], height: sandboxResolution[1] } }
+    };
     // Pack the working tree ONCE per run, on the host, BEFORE any sandbox is created (mirrors the
     // cua route's ordering): a packing failure fails the run closed here, never spending sandbox
     // cost. Dry-run packs nothing (no fs side effects; the contract bundle carries no archiveSha256).
@@ -353,6 +415,23 @@ export async function runSharedWorldLab(options) {
             if (hooks.prepareDesktop) {
                 await hooks.prepareDesktop(desktop);
             }
+            const screenGeometry = await inspectDesktopScreenGeometry({
+                desktop,
+                laneId: "shared-world",
+                requestedScreen: sandboxResolution,
+                requestTimeoutMs
+            });
+            if (screenGeometry.verified) {
+                sharedScreenGeometry = {
+                    screen: { ...sharedScreenGeometry.screen, verified: screenGeometry.verified }
+                };
+            }
+            if (screenGeometry.warning) {
+                warnings.push(screenGeometry.warning);
+                sharedScreenGeometry = { ...sharedScreenGeometry, warnings: [screenGeometry.warning] };
+            }
+            if (screenGeometry.error)
+                throw new Error(screenGeometry.error);
             // Provision the shared plane ONCE: clone + install/build + seed + serve + readiness probe
             // (clone route), or upload/extract the once-per-run packed archive + the SAME shared serve
             // pipeline (local-tree route). One stderr line per phase boundary by default; hooks.onPhase
@@ -418,15 +497,38 @@ export async function runSharedWorldLab(options) {
                 let session;
                 let sessionError;
                 let desktopBrowser;
+                let launchedBrowserFamily = "unknown";
+                let browserLaunchIdentity;
+                let browserLaunched = false;
+                let initialBrowserGeometry;
+                let browserWindowId;
+                let browserTargetId;
+                let desktopGeometry = sharedScreenGeometry;
                 try {
                     // Fresh isolated browser profile per seat, opened at the role's same-origin loopback entry.
-                    desktopBrowser = await launchSeatBrowser(desktop, {
+                    const browserLaunch = await launchSeatBrowser(desktop, {
                         ...(config.execution?.desktop?.browser === undefined ? {} : { browserPreference: config.execution.desktop.browser }),
                         profileDir: spec.profileDir,
                         seatUrl: spec.seatUrl,
                         requestTimeoutMs
                     });
+                    desktopBrowser = browserLaunch.evidence;
+                    launchedBrowserFamily = browserLaunch.family;
+                    browserLaunchIdentity = browserLaunch.identity;
+                    browserLaunched = true;
                     await desktop.wait(BROWSER_SETTLE_MS).catch(() => undefined);
+                    const browserGeometry = await captureDesktopBrowserGeometry({
+                        desktop,
+                        browserFamily: launchedBrowserFamily,
+                        ...(browserLaunchIdentity === undefined ? {} : { launchIdentity: browserLaunchIdentity }),
+                        laneId: spec.roleId,
+                        targetUrl: spec.seatUrl,
+                        requestedScreen: sandboxResolution,
+                        requestTimeoutMs
+                    });
+                    initialBrowserGeometry = browserGeometry;
+                    browserWindowId = browserGeometry.browserWindowId;
+                    browserTargetId = browserGeometry.browserTargetId;
                     const sessionOptions = {
                         instructions: spec.instructions,
                         persona: spec.persona,
@@ -436,9 +538,17 @@ export async function runSharedWorldLab(options) {
                             ...(config.actors[0]?.model ? { model: config.actors[0].model } : {})
                         },
                         desktop: desktop,
-                        executorOptions: {
-                            observeBrowserState: makeChromeBrowserStateObserver(desktop, requestTimeoutMs)
-                        },
+                        ...(launchedBrowserFamily === "chromium"
+                            ? {
+                                executorOptions: {
+                                    observeBrowserState: makeChromeBrowserStateObserver(desktop, requestTimeoutMs, {
+                                        ...(browserLaunchIdentity?.cdpPort === undefined ? {} : { cdpPort: browserLaunchIdentity.cdpPort }),
+                                        ...(browserLaunchIdentity?.profileDir === undefined ? {} : { profileDir: browserLaunchIdentity.profileDir }),
+                                        targetUrl: spec.seatUrl
+                                    }, browserTargetId)
+                                }
+                            }
+                            : {}),
                         redactScreenshots,
                         scrubText: scrubKnownValues,
                         writeScreenshot,
@@ -449,6 +559,49 @@ export async function runSharedWorldLab(options) {
                 catch (error) {
                     sessionError = redactText(scrubKnownValues(toErrorMessage(error)));
                 }
+                if (browserLaunched) {
+                    const finalGeometry = await captureDesktopBrowserGeometry({
+                        desktop,
+                        browserFamily: launchedBrowserFamily,
+                        ...(browserLaunchIdentity === undefined ? {} : { launchIdentity: browserLaunchIdentity }),
+                        ...(browserWindowId === undefined ? {} : { browserWindowId }),
+                        ...(browserTargetId === undefined ? {} : { browserTargetId }),
+                        laneId: spec.roleId,
+                        targetUrl: spec.seatUrl,
+                        requestedScreen: sandboxResolution,
+                        requestTimeoutMs,
+                        resize: false
+                    }).catch((error) => ({
+                        warnings: [`Final browser geometry measurement failed for lane ${spec.roleId}: ${redactText(scrubKnownValues(toErrorMessage(error)))}`]
+                    }));
+                    // Chosen capture rule (mirrors runCuaLane): seat-end-if-it-measured-anything, else
+                    // seat-open. A seat-end capture that measured EITHER field wins whole, so a partial
+                    // seat-end capture omits fields the seat-open capture had (honest omission); only a
+                    // seat-end capture that measured NOTHING falls back to the seat-open capture.
+                    const chosenGeometry = finalGeometry.browserWindow !== undefined || finalGeometry.viewport !== undefined
+                        ? finalGeometry
+                        : initialBrowserGeometry ?? finalGeometry;
+                    const geometryWarnings = [...new Set(chosenGeometry.warnings.map((warning) => scrubKnownValues(warning)))];
+                    warnings.push(...geometryWarnings);
+                    desktopGeometry = {
+                        ...sharedScreenGeometry,
+                        ...(chosenGeometry.browserWindow === undefined ? {} : { browserWindow: chosenGeometry.browserWindow }),
+                        ...(chosenGeometry.viewport === undefined ? {} : { viewport: chosenGeometry.viewport }),
+                        ...((sharedScreenGeometry.warnings?.length ?? 0) + geometryWarnings.length === 0
+                            ? {}
+                            : { warnings: [...(sharedScreenGeometry.warnings ?? []), ...geometryWarnings] })
+                    };
+                    // End THIS seat's browser now that its turn (and its final geometry capture) is done:
+                    // every role shares the ONE desktop, so this is the per-seat identity boundary. Runs
+                    // after the final seat too. Bounded + best-effort: a failure degrades to an explicit
+                    // warning (the run continues), never a hang.
+                    try {
+                        await desktop.commands.run(buildSeatBrowserTerminationCommand(browserLaunchIdentity?.processId, spec.profileDir), { requestTimeoutMs, timeoutMs: SEAT_BROWSER_TERMINATION_TIMEOUT_MS });
+                    }
+                    catch (error) {
+                        warnings.push(`Seat browser termination failed for role ${spec.roleId} (run continues; the seat's browser may remain open on the shared desktop): ${redactText(scrubKnownValues(toErrorMessage(error)))}`);
+                    }
+                }
                 if (session) {
                     await writeContainedOutputFile(runPaths, spec.traceArtifactPath, `${JSON.stringify(session.trace, null, 2)}\n`, "utf8");
                     if (session.trace.redaction.screenshots === "raw") {
@@ -482,6 +635,7 @@ export async function runSharedWorldLab(options) {
                     ...(sessionError === undefined ? {} : { sessionError }),
                     screenshots,
                     ...(desktopBrowser === undefined ? {} : { desktopBrowser }),
+                    desktopGeometry,
                     noEngagement,
                     harnessError,
                     afterCheckpoint
@@ -566,6 +720,7 @@ export async function runSharedWorldLab(options) {
         subject,
         sandboxResolution,
         sandboxPreset,
+        desktopGeometry: sharedScreenGeometry,
         seedDigest: seedRecipeDigest(config),
         ...(planeCommit === undefined ? {} : { subjectCommit: planeCommit }),
         ...(failFastReason === undefined ? {} : { failFastReason })
@@ -719,6 +874,9 @@ export function buildSharedWorldBundle(args) {
     roleSpecs.forEach((spec, index) => {
         const outcome = roleOutcomes[index];
         const session = outcome?.session;
+        const desktopGeometry = outcome?.desktopGeometry ?? args.desktopGeometry ?? {
+            screen: { requested: { width: args.sandboxResolution[0], height: args.sandboxResolution[1] } }
+        };
         const screenshots = outcome?.screenshots ?? [];
         const lastScreenshot = screenshots[screenshots.length - 1];
         const status = outcome?.skippedReason !== undefined
@@ -768,12 +926,17 @@ export function buildSharedWorldBundle(args) {
             embed: lastScreenshot
                 ? { kind: "screenshot", url: lastScreenshot, title: `Shared desktop, role ${spec.roleId} (${screenshotMode})` }
                 : { kind: "placeholder", title: `Shared desktop, role ${spec.roleId}` },
-            viewport: {
-                width: args.sandboxResolution[0],
-                height: args.sandboxResolution[1],
-                deviceScaleFactor: args.sandboxPreset.deviceScaleFactor,
-                isMobile: args.sandboxPreset.isMobile
-            },
+            ...(desktopGeometry.viewport === undefined
+                ? {}
+                : {
+                    viewport: {
+                        width: desktopGeometry.viewport.width,
+                        height: desktopGeometry.viewport.height,
+                        deviceScaleFactor: desktopGeometry.viewport.deviceScaleFactor,
+                        isMobile: args.sandboxPreset.isMobile
+                    }
+                }),
+            desktopGeometry,
             ui: {
                 route: spec.seatUrl,
                 intent: `Watch role ${spec.roleId} (${spec.persona.id}) drive the SHARED app (one plane; sequential turn).`,
@@ -841,6 +1004,17 @@ export function buildSharedWorldBundle(args) {
                 streamId: spec.streamId
             });
         }
+        for (const warning of desktopGeometry.warnings ?? []) {
+            events.push({
+                id: nextEventId(`geometry-warning-${spec.roleId}`),
+                at: createdAt,
+                level: "warn",
+                type: "shared-world.geometry.warning",
+                message: warning,
+                simId: spec.simId,
+                streamId: spec.streamId
+            });
+        }
     });
     // Build the shared-world evidence block (the timeline + plane + attribution ceiling).
     const seedDigest = args.seedDigest;