@omercnet/paseo-shared-browser 1.2.2 → 2.0.0-next.244.1

package/server/tab-close-confirmation.test.ts

@@ -0,0 +1,97 @@
+import { afterEach, beforeEach, expect, it, vi } from "vitest";
+import { createRuntimeOwner } from "./runtime-owner";
+
+type Owner = Awaited<ReturnType<typeof createRuntimeOwner>>;
+type Owned = Parameters<Owner["request"]>[0];
+
+beforeEach(() => vi.useFakeTimers());
+afterEach(() => vi.useRealTimers());
+
+async function fixture(lingerSnapshots: number | null) {
+  const owner = await createRuntimeOwner({ virtualDisplay: false, nativeVideo: false });
+  const state = { ids: ["root", "closing"], closing: false, polls: 0, next: 0 };
+  const native = {
+    targets: vi.fn(async () => {
+      if (state.closing && lingerSnapshots !== null && state.polls++ >= lingerSnapshots) {
+        state.ids = state.ids.filter((id) => id !== "closing");
+      } else if (state.closing && lingerSnapshots === null) {
+        state.polls++;
+      }
+      return state.ids.map((targetId) => ({ targetId, title: targetId, url: "about:blank" }));
+    }),
+    closeTarget: vi.fn(async () => {
+      state.closing = true;
+    }),
+    createTarget: vi.fn(async () => {
+      const id = `new-${++state.next}`;
+      state.ids.unshift(id);
+      return id;
+    }),
+    selectTarget: vi.fn(async () => {}),
+  };
+  const owned = {
+    runtimeId: "review-runtime",
+    runtime: native,
+    rootTargetId: "root",
+    runtimeOptions: {},
+    tabs: new Map(),
+    tabOrder: ["root", "closing"],
+    display: null,
+    displayNotice: null,
+  } as unknown as Owned;
+  return { owner, owned, native, state };
+}
+
+it("confirms an acknowledged close only after the target disappears without replay", async () => {
+  const f = await fixture(2);
+  const pending = f.owner.request(f.owned, "tabs.close", { targetId: "closing" });
+  await vi.runAllTimersAsync();
+  await expect(pending).resolves.toBeNull();
+  expect(f.native.closeTarget).toHaveBeenCalledTimes(1);
+  expect(f.state.polls).toBe(3);
+  expect(
+    ((await f.owner.request(f.owned, "tabs.list", null)) as { targetId: string }[]).map(
+      (x) => x.targetId,
+    ),
+  ).toEqual(["root"]);
+});
+
+it("fails explicitly, without replaying close or reordering, when the target never disappears", async () => {
+  const f = await fixture(null);
+  const outcome = f.owner.request(f.owned, "tabs.close", { targetId: "closing" }).then(
+    () => "ok",
+    (error) => String(error),
+  );
+  await vi.runAllTimersAsync();
+  expect(await outcome).toContain(
+    "CdpUnknownOutcomeError: Browser tab close could not be confirmed",
+  );
+  expect(f.native.closeTarget).toHaveBeenCalledTimes(1);
+  expect(f.state.polls).toBe(20);
+  const ids = (await f.owner.request(f.owned, "tabs.list", null)) as { targetId: string }[];
+  expect(ids.map((tab) => tab.targetId)).toEqual(["root", "closing"]);
+});
+
+it("retains known ordering across unordered snapshots and appends explicit creations", async () => {
+  const f = await fixture(null);
+  f.state.ids = ["third", "closing", "root"];
+  const ids = async () =>
+    ((await f.owner.request(f.owned, "tabs.list", null)) as { targetId: string }[]).map(
+      (x) => x.targetId,
+    );
+  expect(await ids()).toEqual(["root", "closing", "third"]);
+  f.state.ids = ["closing", "root", "third"];
+  expect(await ids()).toEqual(["root", "closing", "third"]);
+  await f.owner.request(f.owned, "tabs.create", null);
+  await f.owner.request(f.owned, "tabs.create", null);
+  expect(await ids()).toEqual(["root", "closing", "third", "new-1", "new-2"]);
+});
+
+it("preserves the existing last-tab refusal", async () => {
+  const f = await fixture(null);
+  f.state.ids = ["root"];
+  await expect(f.owner.request(f.owned, "tabs.close", { targetId: "root" })).rejects.toThrow(
+    "last browser tab",
+  );
+  expect(f.native.closeTarget).not.toHaveBeenCalled();
+});

package/server/video-source-recovery.test.ts

@@ -0,0 +1,20 @@
+import { expect, it } from "vitest";
+import { createVideoSourceRecovery } from "./video-source-recovery";
+
+it("uses monotonic cooldown and clears permanent refusal only on exact configuration replacement", () => {
+  let now = 0;
+  const recovery = createVideoSourceRecovery(() => now);
+  const context = { connection: {}, page: {}, viewport: {}, attachmentGeneration: 0 };
+  recovery.failed(context, "startup");
+  expect(recovery.blocked(context)).toBe("startup");
+  now = 2999;
+  expect(recovery.blocked(context)).toBe("startup");
+  now = 3000;
+  expect(recovery.blocked(context)).toBeNull();
+  recovery.failed(context, "source-dimensions");
+  now = 1_000_000;
+  expect(recovery.blocked({ ...context })).toBe("source-dimensions");
+  expect(recovery.blocked({ ...context, viewport: {} })).toBeNull();
+  recovery.failed(context, "source-dimensions");
+  expect(recovery.blocked({ ...context, attachmentGeneration: 1 })).toBeNull();
+});

package/server/video-source-recovery.ts

@@ -0,0 +1,64 @@
+/** Native source recovery is viewing-only and never retries a browser mutation.
+ * Transient failures wait three monotonic seconds after failure admission, and
+ * retirement independently gates replacement. A proven
+ * size mismatch remains blocked until the owning attachment or viewport changes.
+ */
+import { performance } from "node:perf_hooks";
+
+export const VIDEO_SOURCE_RECOVERY_COOLDOWN_MS = 3_000;
+export type VideoSourceFailureCode =
+  | "startup"
+  | "source-stopped"
+  | "source-reset"
+  | "source-dimensions";
+export interface VideoSourceRecoveryContext {
+  connection: unknown;
+  page: unknown;
+  viewport: unknown;
+  attachmentGeneration: number;
+}
+
+/** Keep failure admission separate from track lifetime, so demand cannot pin a
+ * failed source and a stopped permanent failure cannot spin up replacements. */
+export function createVideoSourceRecovery(now: () => number = () => performance.now()) {
+  let context: VideoSourceRecoveryContext | null = null;
+  let failure: VideoSourceFailureCode | null = null;
+  let retryAfter = 0;
+  const sameContext = (value: VideoSourceRecoveryContext): boolean => {
+    if (context === null) {
+      return false;
+    }
+    return (
+      value.connection === context.connection &&
+      value.page === context.page &&
+      value.viewport === context.viewport &&
+      value.attachmentGeneration === context.attachmentGeneration
+    );
+  };
+  const selectContext = (value: VideoSourceRecoveryContext) => {
+    if (sameContext(value)) {
+      return;
+    }
+    context = { ...value };
+    failure = null;
+    retryAfter = 0;
+  };
+  return {
+    /** Returns a private reason while acquisition is blocked. Document changes
+     * alone cannot cure a mismatch in this exact configured pixel geometry. */
+    blocked(value: VideoSourceRecoveryContext): VideoSourceFailureCode | null {
+      selectContext(value);
+      if (failure === "source-dimensions" || now() < retryAfter) {
+        return failure;
+      }
+      return null;
+    },
+    /** Start the cooldown before asynchronous retirement, closing the admission
+     * gap even when cleanup is slow. Cleanup completion remains mandatory. */
+    failed(value: VideoSourceRecoveryContext, code: VideoSourceFailureCode): void {
+      selectContext(value);
+      failure = code;
+      retryAfter = now() + VIDEO_SOURCE_RECOVERY_COOLDOWN_MS;
+    },
+  };
+}

package/server/viewer-capture-lifetime.ts

@@ -0,0 +1,51 @@
+/**
+ * Releases optional capture resources when their last viewer lease expires.
+ * Pixel receipts are not ownership: failed startup can still own a track/helper.
+ * The browser itself stays alive. Callers recheck current viewers before cleanup.
+ */
+export interface ViewerCaptureLifetime {
+  /** Start or refresh cleanup scheduling after capture is attempted. */
+  arm(): void;
+  /** Cancel this lifetime during explicit cleanup or session disposal. */
+  cancel(): void;
+}
+
+/** Own one unreferenced timer per session, using current viewer expiry facts. */
+export function createViewerCaptureLifetime(options: {
+  now(): number;
+  latestExpiry(): number | null;
+  onExpired(): Promise<void>;
+}): ViewerCaptureLifetime {
+  let timer: ReturnType<typeof setTimeout> | null = null;
+  let revision = 0;
+
+  function cancel(): void {
+    revision += 1;
+    if (timer) clearTimeout(timer);
+    timer = null;
+  }
+
+  function arm(): void {
+    cancel();
+    const expiry = options.latestExpiry();
+    if (expiry === null) return;
+    const scheduledRevision = revision;
+    timer = setTimeout(
+      async () => {
+        timer = null;
+        if (scheduledRevision !== revision) return;
+        const currentExpiry = options.latestExpiry();
+        if (currentExpiry !== null && currentExpiry > options.now()) {
+          arm();
+          return;
+        }
+        // A slow cleanup must not clear a newer viewer's schedule or replay work.
+        await options.onExpired().catch(() => undefined);
+      },
+      Math.max(1, expiry - options.now()),
+    );
+    timer.unref?.();
+  }
+
+  return { arm, cancel };
+}

package/server/virtual-display.test.ts

@@ -0,0 +1,184 @@
+import { EventEmitter } from "node:events";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { Readable } from "node:stream";
+import { beforeEach, expect, it, vi } from "vitest";
+import { createPrivateVirtualDisplay, encodeDisplayAuthority } from "./virtual-display";
+
+/** Host-native path: production joins with the platform separator. */
+const fixtureDirectory = join(tmpdir(), "private-display-fixture");
+
+const fake = vi.hoisted(() => ({
+  access: vi.fn(),
+  chmod: vi.fn(),
+  mkdtemp: vi.fn(),
+  rm: vi.fn(),
+  writeFile: vi.fn(),
+  spawn: vi.fn(),
+  connect: vi.fn(),
+}));
+vi.mock("node:fs/promises", () => fake);
+vi.mock("node:child_process", () => ({ spawn: fake.spawn }));
+vi.mock("node:net", () => ({ createConnection: fake.connect }));
+
+let child: EventEmitter & {
+  pid: number;
+  exitCode: number | null;
+  signalCode: string | null;
+  stdio: unknown[];
+  kill: ReturnType<typeof vi.fn>;
+};
+let ready: Readable;
+beforeEach(() => {
+  vi.clearAllMocks();
+  fake.access.mockResolvedValue(undefined);
+  fake.chmod.mockResolvedValue(undefined);
+  fake.mkdtemp.mockResolvedValue(fixtureDirectory);
+  fake.writeFile.mockResolvedValue(undefined);
+  fake.rm.mockResolvedValue(undefined);
+  ready = new Readable({ read() {} });
+  child = Object.assign(new EventEmitter(), {
+    pid: 123,
+    exitCode: null,
+    signalCode: null,
+    stdio: [null, null, null, ready],
+    kill: vi.fn(() => {
+      child.signalCode = "SIGTERM";
+      child.emit("exit", null, "SIGTERM");
+      return true;
+    }),
+  });
+  fake.spawn.mockImplementation((_path, args) => {
+    queueMicrotask(() => ready.push(`${args[0].slice(1)}\n`));
+    return child;
+  });
+  fake.connect.mockImplementation(() => {
+    const socket = Object.assign(new EventEmitter(), {
+      destroy: vi.fn(),
+      write: vi.fn((packet: Buffer) => {
+        const response = Buffer.alloc(8);
+        response[0] = packet.readUInt16LE(8) === 16 ? 1 : 0;
+        response.writeUInt16LE(11, 2);
+        queueMicrotask(() => socket.emit("data", response));
+      }),
+    });
+    queueMicrotask(() => socket.emit("connect"));
+    return socket;
+  });
+});
+
+it("keeps non-Linux and missing Xvfb on the original path without side effects", async () => {
+  expect(await createPrivateVirtualDisplay({ platform: "win32" })).toBeNull();
+  expect(fake.access).not.toHaveBeenCalled();
+  fake.access.mockRejectedValue(Object.assign(new Error(), { code: "ENOENT" }));
+  expect(await createPrivateVirtualDisplay({ platform: "linux" })).toBeNull();
+  expect(fake.spawn).not.toHaveBeenCalled();
+  expect(fake.mkdtemp).not.toHaveBeenCalled();
+});
+
+it("uses an authenticated private high abstract-only display and idempotent cleanup", async () => {
+  const originalDisplay = process.env.DISPLAY;
+  const display = await createPrivateVirtualDisplay({ platform: "linux" });
+  expect(display).not.toBeNull();
+  const args = fake.spawn.mock.calls[0]![1] as string[];
+  expect(Number(args[0]!.slice(1))).toBeGreaterThanOrEqual(20_000);
+  expect(args).toEqual([
+    args[0],
+    "-screen",
+    "0",
+    "3840x3840x24",
+    "-nolisten",
+    "unix",
+    "-nolisten",
+    "tcp",
+    "-nolock",
+    "-auth",
+    join(fixtureDirectory, "authority"),
+    "-displayfd",
+    "3",
+  ]);
+  expect(fake.chmod).toHaveBeenCalledWith(fixtureDirectory, 0o700);
+  expect(fake.writeFile.mock.calls[0]![2]).toEqual({ mode: 0o600, flag: "wx" });
+  expect(fake.connect).toHaveBeenCalledTimes(2); // Authorized and anonymous denial.
+  expect(fake.connect.mock.calls[0]![0].path).toBe(`\0/tmp/.X11-unix/X${args[0]!.slice(1)}`);
+  expect(process.env.DISPLAY).toBe(originalDisplay);
+  display!.assertAvailable();
+  await display!.stop();
+  await display!.stop();
+  expect(child.kill).toHaveBeenCalledTimes(1);
+  expect(fake.rm).toHaveBeenCalledTimes(1);
+  expect(() => display!.assertAvailable()).toThrow("ended");
+});
+
+it("refuses a changed readiness identity before transmitting the secret", async () => {
+  fake.spawn.mockImplementation(() => {
+    queueMicrotask(() => ready.push("0\n"));
+    return child;
+  });
+  await expect(createPrivateVirtualDisplay({ platform: "linux" })).rejects.toThrow(
+    "identity changed",
+  );
+  expect(fake.connect).not.toHaveBeenCalled();
+  expect(child.kill).toHaveBeenCalledTimes(1);
+  expect(fake.rm).toHaveBeenCalledTimes(1);
+});
+
+it("bounds a never-ready child and removes its authority file", async () => {
+  fake.spawn.mockReturnValue(child);
+  await expect(createPrivateVirtualDisplay({ platform: "linux", timeoutMs: 5 })).rejects.toThrow(
+    "not ready",
+  );
+  expect(child.kill).toHaveBeenCalledTimes(1);
+  expect(fake.rm).toHaveBeenCalledTimes(1);
+});
+
+it("handles spawn failure and prevents silent headless fallback", async () => {
+  fake.spawn.mockImplementation(() => {
+    queueMicrotask(() => child.emit("error", new Error("fixture spawn failure")));
+    return child;
+  });
+  await expect(createPrivateVirtualDisplay({ platform: "linux" })).rejects.toThrow(
+    "failed to start",
+  );
+  expect(fake.rm).toHaveBeenCalledTimes(1);
+});
+
+it("refuses a display which accepts clients without the private cookie", async () => {
+  fake.connect.mockImplementation(() => {
+    const socket = Object.assign(new EventEmitter(), {
+      destroy: vi.fn(),
+      write: () => {
+        const response = Buffer.alloc(8);
+        response[0] = 1;
+        response.writeUInt16LE(11, 2);
+        queueMicrotask(() => socket.emit("data", response));
+      },
+    });
+    queueMicrotask(() => socket.emit("connect"));
+    return socket;
+  });
+  await expect(createPrivateVirtualDisplay({ platform: "linux" })).rejects.toThrow(
+    "unauthenticated",
+  );
+  expect(child.kill).toHaveBeenCalledTimes(1);
+});
+
+it("invalidates on unexpected child exit without starting a replacement", async () => {
+  const display = await createPrivateVirtualDisplay({ platform: "linux" });
+  child.exitCode = 1;
+  child.emit("exit", 1);
+  expect(() => display!.assertAvailable()).toThrow("ended");
+  await display!.stop();
+  expect(fake.spawn).toHaveBeenCalledTimes(1);
+  expect(child.kill).not.toHaveBeenCalled();
+});
+
+it("encodes the display-scoped authority format and rejects malformed inputs", () => {
+  const cookie = Buffer.alloc(16, 7);
+  const authority = encodeDisplayAuthority("23067", cookie);
+  expect(authority.readUInt16BE(0)).toBe(65_535);
+  expect(authority.includes(Buffer.from("MIT-MAGIC-COOKIE-1"))).toBe(true);
+  expect(authority.subarray(-16)).toEqual(cookie);
+  expect(() => encodeDisplayAuthority("0", cookie)).toThrow();
+  expect(() => encodeDisplayAuthority("23067", Buffer.alloc(2))).toThrow();
+});

package/server/virtual-display.ts

@@ -0,0 +1,236 @@
+/**
+ * Owns one authenticated, invisible Linux X display per browser runtime. Abstract
+ * Unix transport avoids WSLg's protected pathname directory; TCP is never enabled.
+ * The display stays alive across CDP reconnects. Startup failure is definitive:
+ * callers must not silently relaunch a partly initialized browser headlessly.
+ */
+import { type ChildProcess, spawn } from "node:child_process";
+import { randomBytes, randomInt } from "node:crypto";
+import { constants } from "node:fs";
+import { access, chmod, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { createConnection } from "node:net";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { Readable } from "node:stream";
+import { MAX_VIEWPORT } from "../shared/viewport-limits";
+import { RuntimeLostError } from "./runtime-protocol";
+
+const AUTH_NAME = "MIT-MAGIC-COOKIE-1";
+const STARTUP_MS = 5_000;
+
+/** Fixed-text startup failure; safe to show operators because it never embeds paths or secrets. */
+export class PrivateDisplayError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "PrivateDisplayError";
+  }
+}
+
+export interface PrivateVirtualDisplay {
+  readonly launchEnvironment: Readonly<{ DISPLAY: string; XAUTHORITY: string }>;
+  /** Throws RuntimeLostError after the display exits; it never creates a replacement display. */
+  assertAvailable(): void;
+  /** Idempotently terminates only the owned child and removes its private auth file. */
+  stop(): Promise<void>;
+}
+
+/** Serializes a FamilyWild Xauthority record, scoped to this display and cookie. */
+export function encodeDisplayAuthority(display: string, cookie: Buffer): Buffer {
+  if (!/^\d{4,5}$/.test(display) || Number(display) > 65_535 || cookie.length !== 16) {
+    throw new PrivateDisplayError("Invalid private display authority");
+  }
+  const fields = [Buffer.alloc(0), Buffer.from(display), Buffer.from(AUTH_NAME), cookie];
+  const family = Buffer.alloc(2);
+  family.writeUInt16BE(65_535);
+  return Buffer.concat([
+    family,
+    ...fields.flatMap((field) => {
+      const length = Buffer.alloc(2);
+      length.writeUInt16BE(field.length);
+      return [length, field];
+    }),
+  ]);
+}
+
+/** Performs a bounded X11 setup exchange to prove the owned secret is accepted. */
+export async function authenticateDisplay(display: string, cookie: Buffer): Promise<boolean> {
+  return await new Promise((resolve) => {
+    const socket = createConnection({ path: `\0/tmp/.X11-unix/X${display}` });
+    let settled = false;
+    let received = Buffer.alloc(0);
+    const finish = (ready: boolean) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      socket.destroy();
+      resolve(ready);
+    };
+    const timer = setTimeout(() => finish(false), 200);
+    socket.once("error", () => finish(false));
+    socket.once("close", () => finish(false));
+    socket.once("connect", () => {
+      const name = Buffer.from(AUTH_NAME);
+      const header = Buffer.alloc(12);
+      header[0] = 0x6c; // X11 little-endian client, protocol 11.
+      header.writeUInt16LE(11, 2);
+      header.writeUInt16LE(name.length, 6);
+      header.writeUInt16LE(cookie.length, 8);
+      socket.write(Buffer.concat([header, name, Buffer.alloc(2), cookie]));
+    });
+    socket.on("data", (chunk) => {
+      if (received.length + chunk.length > 32_768) return finish(false);
+      received = Buffer.concat([received, chunk]);
+      if (received.length >= 8) {
+        finish(received[0] === 1 && received.readUInt16LE(2) === 11);
+      }
+    });
+  });
+}
+
+/** Reads only the exact child readiness FD before sending its cookie to a socket. */
+async function waitDisplayReady(
+  child: ChildProcess,
+  display: string,
+  timeoutMs: number,
+): Promise<void> {
+  await new Promise<void>((resolve, reject) => {
+    const ready = child.stdio[3] as Readable;
+    let response = "";
+    const finish = (error?: Error) => {
+      clearTimeout(timer);
+      ready.removeListener("data", onData);
+      ready.removeListener("error", onError);
+      child.removeListener("error", onError);
+      child.removeListener("exit", onExit);
+      ready.destroy();
+      if (error) reject(error);
+      else resolve();
+    };
+    const onError = () =>
+      finish(new PrivateDisplayError("Private browser display failed to start"));
+    const onExit = () =>
+      finish(new PrivateDisplayError("Private browser display ended before readiness"));
+    const onData = (chunk: Buffer) => {
+      response += chunk.toString("ascii");
+      if (response.length > 16)
+        return finish(new PrivateDisplayError("Invalid private display readiness"));
+      if (response.includes("\n")) {
+        finish(
+          response === `${display}\n`
+            ? undefined
+            : new PrivateDisplayError("Private display identity changed"),
+        );
+      }
+    };
+    const timer = setTimeout(
+      () => finish(new PrivateDisplayError("Private browser display was not ready")),
+      timeoutMs,
+    );
+    ready.on("data", onData);
+    ready.once("error", onError);
+    child.once("error", onError);
+    child.once("exit", onExit);
+  });
+}
+
+/** Stops a spawned child before deleting the secret it may still be reading. */
+async function stopDisplayChild(child: ChildProcess): Promise<void> {
+  if (child.exitCode !== null || child.signalCode !== null || !child.pid) return;
+  await new Promise<void>((resolve) => {
+    const timer = setTimeout(() => child.kill("SIGKILL"), 1_000);
+    child.once("exit", () => {
+      clearTimeout(timer);
+      resolve();
+    });
+    child.kill("SIGTERM");
+  });
+}
+
+/**
+ * Starts Xvfb only for Linux hidden browsers when the existing executable exists.
+ * Absence returns null. Present-but-broken Xvfb fails closed with bounded cleanup.
+ * No process.env mutation, network listener, host display, or dependency install.
+ * One 3840x3840x24 framebuffer is bounded at about 57 MiB before server overhead;
+ * Chromium CPU/memory costs remain those of the existing browser runtime.
+ */
+export async function createPrivateVirtualDisplay(
+  options: { platform?: NodeJS.Platform; executablePath?: string; timeoutMs?: number } = {},
+): Promise<PrivateVirtualDisplay | null> {
+  if ((options.platform ?? process.platform) !== "linux") return null;
+  const executable = options.executablePath ?? "/usr/bin/Xvfb";
+  try {
+    await access(executable, constants.X_OK);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return null;
+    throw new PrivateDisplayError("Private browser display executable is not usable");
+  }
+  const display = String(randomInt(20_000, 60_000));
+  const directory = await mkdtemp(join(tmpdir(), "paseo-browser-display-"));
+  const authPath = join(directory, "authority");
+  const cookie = randomBytes(16);
+  let child: ChildProcess | null = null;
+  let stopPromise: Promise<void> | null = null;
+  let exited = false;
+  const stop = () =>
+    (stopPromise ??= (async () => {
+      exited = true;
+      try {
+        if (child) await stopDisplayChild(child);
+      } finally {
+        await rm(directory, { recursive: true, force: true });
+      }
+    })());
+  try {
+    await chmod(directory, 0o700);
+    await writeFile(authPath, encodeDisplayAuthority(display, cookie), { mode: 0o600, flag: "wx" });
+    child = spawn(
+      executable,
+      [
+        `:${display}`,
+        "-screen",
+        "0",
+        `${MAX_VIEWPORT.width}x${MAX_VIEWPORT.height}x24`,
+        "-nolisten",
+        "unix",
+        "-nolisten",
+        "tcp",
+        "-nolock",
+        "-auth",
+        authPath,
+        "-displayfd",
+        "3",
+      ],
+      { stdio: ["ignore", "ignore", "ignore", "pipe"] },
+    );
+    child.once("error", () => {
+      exited = true;
+    });
+    child.once("exit", () => {
+      exited = true;
+    });
+    // An explicit high display plus readiness FD does not invoke Xvfb's scan
+    // starting at :0. The child's pipe proves it bound that exact listener first.
+    await waitDisplayReady(
+      child,
+      display,
+      Math.min(STARTUP_MS, Math.max(1, options.timeoutMs ?? STARTUP_MS)),
+    );
+    if (exited || !(await authenticateDisplay(display, cookie))) {
+      throw new PrivateDisplayError("Private browser display authentication failed");
+    }
+    if (await authenticateDisplay(display, Buffer.alloc(0))) {
+      throw new PrivateDisplayError("Private browser display accepted an unauthenticated client");
+    }
+    if (exited) throw new PrivateDisplayError("Private browser display ended");
+    return {
+      launchEnvironment: Object.freeze({ DISPLAY: `:${display}`, XAUTHORITY: authPath }),
+      assertAvailable() {
+        if (exited) throw new RuntimeLostError("Private browser display ended");
+      },
+      stop,
+    };
+  } catch (error) {
+    await stop();
+    throw error;
+  }
+}