browser-commander 0.31.2 → 0.32.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.32.0
+
+### Minor Changes
+
+- dd4b3d5: Let an embedding supervisor own Ctrl+C and keep a launched browser across its own restarts (#174). `interruption: 'caller'` on `launchBrowser`, `launchRealBrowser`, `launchWebDriver` and `startProcess` stops SIGINT from being forwarded to the browser and its ChromeDriver and turns off the engines' `handleSIGINT`. A real launch's `detach()` and `handoff()` return a JSON hand-off naming the exact browser instance and tab, and `reconnectBrowser(handoff)` reattaches to that tab without launching or navigating, refusing a replaced browser or a closed tab with `BrowserHandoffError`. `close()` on either session closes the browser, waits for its process to exit and removes a temporary profile.
+
 ## 0.31.2
 
 ### Patch Changes

package/README.md

@@ -399,6 +399,7 @@ const { browser, page, close } = await launchBrowser({
   verbose: false, // Enable debug logging
   args: ['--no-sandbox'], // Custom Chrome args to append
   storageState: './session-state.json', // Saved cookies and localStorage, as a path or object
+  interruption: 'managed', // 'caller' leaves Ctrl+C (SIGINT) to your own handler
 });
 ```
 
@@ -472,6 +473,31 @@ const session = await launchRealBrowser({
 console.log(session.migration.migrated, session.migration.skipped);
 ```
 
+### detach() / reconnectBrowser(handoff)
+
+For an application that supervises the browser itself, `interruption:
+'caller'` keeps Ctrl+C from reaching the launched browser (and its
+ChromeDriver), so the application's own SIGINT handler decides what happens.
+A real launch can then hand the exact browser and tab to the next run:
+
+```javascript
+const session = await launchBrowser({ interruption: 'caller' });
+process.on('SIGINT', async () => {
+  // The browser keeps running; the hand-off names its instance and tab.
+  writeFileSync('handoff.json', JSON.stringify(await session.detach()));
+  process.exit(130);
+});
+
+// Next run: attach to that exact tab - no launch, no new page, no navigation.
+const again = await reconnectBrowser('handoff.json');
+await again.close(); // closes the browser and waits for its process to exit
+```
+
+`session.handoff()` returns the same JSON-serializable description without
+detaching. `reconnectBrowser` throws a `BrowserHandoffError` when the endpoint
+now belongs to another browser instance or the tab is gone. See
+[embedding: Ctrl+C ownership and browser hand-off](../docs/embedding-and-handoff.md).
+
 ### launchWebDriver(options) / connectWebDriver(options)
 
 The same engine is available through `launchBrowser({engine: 'selenium'})` and

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "browser-commander",
-  "version": "0.31.2",
+  "version": "0.32.0",
   "description": "Universal browser automation library that supports Playwright, Puppeteer, and Selenium with a unified API",
   "main": "src/index.js",
   "bin": {

package/src/browser/browser-handoff.js

@@ -0,0 +1,304 @@
+/**
+ * Hand a launched browser from one controller to the next (issue #174).
+ *
+ * An embedding supervisor that keeps a human-facing browser open across its
+ * own restarts needs three things from a launch:
+ *
+ * - interruption ownership: `launchBrowser({ interruption: 'caller' })`
+ *   leaves Ctrl+C to the supervisor's own SIGINT handler (see
+ *   `startProcess` in `utilities/subprocess.js`);
+ * - a `detach()` that stops this controller without touching the browser and
+ *   returns a JSON-serializable {@link BrowserHandoff} naming the exact
+ *   browser instance and tab;
+ * - {@link reconnectBrowser}, which attaches to that exact tab again - it
+ *   never launches a browser and never creates or navigates a page, so a page
+ *   waiting for a human (a login, a captcha) is found exactly as it was left.
+ *
+ * Whoever holds the hand-off owns the browser: `close()` on the launch result
+ * or on a reconnected session closes the browser, waits for the actual
+ * process to exit, and removes a temporary profile.
+ */
+
+import { readFileSync } from 'node:fs';
+import { connectBrowser } from './connector.js';
+import { removeUserDataDir } from './profile-directory.js';
+import { closeRemoteBrowser, probeSession } from './cdp-browser-endpoint.js';
+import { signalProcessTree } from '../utilities/subprocess.js';
+import { withDeadline } from '../traces/deadline.js';
+
+/** Version of the {@link BrowserHandoff} shape. */
+export const BROWSER_HANDOFF_VERSION = 1;
+
+/**
+ * @typedef {Object} BrowserHandoff
+ * @property {number} version - {@link BROWSER_HANDOFF_VERSION}
+ * @property {'playwright'|'puppeteer'|'selenium'} engine - Engine of the controller that handed off
+ * @property {string} cdpEndpoint - HTTP DevTools endpoint, such as http://127.0.0.1:9222
+ * @property {string} webSocketDebuggerUrl - Identity of the exact browser instance
+ * @property {string} targetId - DevTools target id of the exact tab
+ * @property {number|null} pid - Browser process id
+ * @property {string|null} userDataDir - Profile directory
+ * @property {boolean} temporaryProfile - Whether close() removes the profile
+ * @property {number|null} remoteDebuggingPort - Loopback CDP port
+ * @property {string|null} executablePath - Browser executable
+ */
+
+/** Raised when a hand-off no longer names a running browser or tab. */
+export class BrowserHandoffError extends Error {
+  constructor(message, { cause } = {}) {
+    super(message, cause ? { cause } : undefined);
+    this.name = 'BrowserHandoffError';
+  }
+}
+
+/** DevTools target id of an engine page: the exact tab, across controllers. */
+export async function pageTargetId({ engine, page, browser }) {
+  if (engine === 'selenium') {
+    // ChromeDriver window handles are target ids (older builds prefix them).
+    const handle = await browser.getWindowHandle();
+    return String(handle).replace(/^CDwindow-/, '');
+  }
+  const cdp =
+    engine === 'playwright'
+      ? await page.context().newCDPSession(page)
+      : await page.target().createCDPSession();
+  try {
+    return (await cdp.send('Target.getTargetInfo')).targetInfo.targetId;
+  } finally {
+    await cdp.detach().catch(() => {});
+  }
+}
+
+/** Describe the browser and tab a controller holds, for another controller. */
+async function describe(owner, page) {
+  const version = await probeSession(owner.cdpEndpoint);
+  if (!version?.webSocketDebuggerUrl) {
+    throw new BrowserHandoffError(
+      `No browser answers at ${owner.cdpEndpoint}; nothing to hand off`
+    );
+  }
+  return {
+    version: BROWSER_HANDOFF_VERSION,
+    engine: owner.engine,
+    cdpEndpoint: owner.cdpEndpoint,
+    webSocketDebuggerUrl: version.webSocketDebuggerUrl,
+    targetId: await pageTargetId({
+      engine: owner.engine,
+      page,
+      browser: owner.connectedBrowser(),
+    }),
+    pid: owner.pid() ?? null,
+    userDataDir: owner.userDataDir ?? null,
+    temporaryProfile: Boolean(owner.temporaryProfile),
+    remoteDebuggingPort: owner.remoteDebuggingPort ?? null,
+    executablePath: owner.executablePath ?? null,
+  };
+}
+
+/**
+ * Add `handoff()` and a hand-off returning `detach()` to a session.
+ *
+ * `state` is shared with the session's closer so that `close()` after
+ * `detach()` closes the browser over its WebSocket instead of the dropped
+ * engine connection.
+ */
+export function installHandoff(session, owner, state) {
+  const engineDetach = session.detach;
+  let detaching;
+  // Read by session persistence; not enumerable, so a launch result that
+  // spreads the session does not copy a value that goes stale.
+  Object.defineProperty(session, 'detached', {
+    configurable: true,
+    get: () => Boolean(state.detached),
+  });
+  session.handoff = async ({ page } = {}) => {
+    if (state.detached) {
+      return state.handoff;
+    }
+    return await describe(owner, page ?? session.page);
+  };
+  session.detach = ({ page } = {}) => {
+    detaching ??= (async () => {
+      const handoff = await session.handoff({ page });
+      state.handoff = handoff;
+      state.webSocketDebuggerUrl = handoff.webSocketDebuggerUrl;
+      state.detached = true;
+      await engineDetach?.();
+      owner.release?.();
+      return handoff;
+    })();
+    return detaching;
+  };
+  return session;
+}
+
+function readHandoff(handoff) {
+  let value = handoff;
+  if (typeof value === 'string') {
+    value = JSON.parse(
+      value.trimStart().startsWith('{') ? value : readFileSync(value, 'utf8')
+    );
+  }
+  for (const field of ['cdpEndpoint', 'webSocketDebuggerUrl', 'targetId']) {
+    if (typeof value?.[field] !== 'string' || !value[field]) {
+      throw new TypeError(`Browser hand-off is missing ${field}`);
+    }
+  }
+  if (value.version !== BROWSER_HANDOFF_VERSION) {
+    throw new TypeError(
+      `Unsupported browser hand-off version ${String(value.version)}`
+    );
+  }
+  return value;
+}
+
+function processRunning(pid) {
+  try {
+    process.kill(pid, 0);
+  } catch (error) {
+    return error.code === 'EPERM';
+  }
+  if (process.platform === 'linux') {
+    // A zombie still answers signal 0; its parent has not reaped it yet.
+    try {
+      const stat = readFileSync(`/proc/${pid}/stat`, 'utf8');
+      return stat.slice(stat.lastIndexOf(')') + 2)[0] !== 'Z';
+    } catch {
+      return false;
+    }
+  }
+  return true;
+}
+
+/** Wait until a process that is not necessarily our child has exited. */
+export async function waitForPidExit(pid, timeout) {
+  const deadline = Date.now() + timeout;
+  while (processRunning(pid)) {
+    if (Date.now() >= deadline) {
+      return false;
+    }
+    await new Promise((resolve) => setTimeout(resolve, 50));
+  }
+  return true;
+}
+
+/**
+ * Close a handed-off browser and wait for its process to exit: `Browser.close`
+ * first, SIGKILL to its process group if it is still running after
+ * `closeTimeout`, then remove a temporary profile.
+ */
+export async function closeHandedOffBrowser(handoff, { closeTimeout = 5000 }) {
+  const version = await probeSession(handoff.cdpEndpoint);
+  if (version?.webSocketDebuggerUrl === handoff.webSocketDebuggerUrl) {
+    await withDeadline(
+      closeRemoteBrowser(handoff.webSocketDebuggerUrl),
+      closeTimeout,
+      'browser close'
+    ).catch(() => {});
+  }
+  if (handoff.pid && !(await waitForPidExit(handoff.pid, closeTimeout))) {
+    signalProcessTree(handoff.pid, 'SIGKILL');
+    await waitForPidExit(handoff.pid, closeTimeout);
+  }
+  if (handoff.temporaryProfile && handoff.userDataDir) {
+    await removeUserDataDir(handoff.userDataDir);
+  }
+}
+
+/**
+ * Attach a new controller to the exact browser and tab a previous controller
+ * handed off with `detach()`.
+ *
+ * The endpoint must still belong to the same browser instance (its
+ * `webSocketDebuggerUrl` is compared) and the tab must still exist; otherwise
+ * this throws instead of launching a browser or opening a page. The result
+ * owns the browser like the launch did: `close()` closes it and waits for its
+ * process to exit, `detach()` hands it off again.
+ *
+ * @param {BrowserHandoff|string} handoff - The hand-off object, its JSON, or a path to a JSON file
+ * @param {Object} [options] - {@link connectBrowser} options; `engine` defaults to the hand-off's
+ * @param {number} [options.closeTimeout=5000] - How long close() waits before killing the process
+ * @returns {Promise<Object>} {@link connectBrowser} handles plus `close`, `detach`, `handoff`, `pid`, `cdpEndpoint`, `userDataDir`, `temporaryProfile`
+ */
+export async function reconnectBrowser(handoff, options = {}) {
+  return await reconnectBrowserWithDependencies(handoff, options);
+}
+
+export async function reconnectBrowserWithDependencies(
+  handoff,
+  options = {},
+  dependencies = {}
+) {
+  const descriptor = readHandoff(handoff);
+  const { closeTimeout = 5000, ...connectionOptions } = options;
+  const engine = options.engine ?? descriptor.engine ?? 'playwright';
+  const version = await probeSession(descriptor.cdpEndpoint);
+  if (version?.webSocketDebuggerUrl !== descriptor.webSocketDebuggerUrl) {
+    throw new BrowserHandoffError(
+      version
+        ? `${descriptor.cdpEndpoint} now belongs to another browser instance`
+        : `The handed-off browser no longer answers at ${descriptor.cdpEndpoint}`
+    );
+  }
+  const connect = dependencies.connect ?? connectBrowser;
+  let connection;
+  try {
+    connection = await connect({
+      ...connectionOptions,
+      engine,
+      cdpEndpoint: descriptor.cdpEndpoint,
+      targetId: descriptor.targetId,
+      fallback: false,
+    });
+  } catch (error) {
+    throw new BrowserHandoffError(
+      `Could not reattach to tab ${descriptor.targetId}: ${error.message}`,
+      { cause: error }
+    );
+  }
+  const state = { detached: false };
+  const owner = {
+    ...descriptor,
+    engine,
+    pid: () => descriptor.pid,
+    connectedBrowser: () => connection.browser,
+  };
+  const originalClose = connection.browser?.close;
+  let closing;
+  const close = () => {
+    closing ??= (async () => {
+      if (!state.detached) {
+        await connection.downloads?.dispose?.().catch(() => {});
+        if (engine === 'selenium') {
+          await connection.detach?.().catch(() => {});
+        }
+      }
+      await closeHandedOffBrowser(descriptor, { closeTimeout });
+      if (engine !== 'selenium') {
+        await Promise.resolve()
+          .then(() => originalClose?.call(connection.browser))
+          .catch(() => {});
+      }
+    })();
+    return closing;
+  };
+  if (connection.browser && engine !== 'selenium') {
+    // As for a launch, browser.close() closes the browser this session owns.
+    connection.browser.close = close;
+  }
+  const session = installHandoff(
+    {
+      ...connection,
+      close,
+      pid: descriptor.pid,
+      cdpEndpoint: descriptor.cdpEndpoint,
+      remoteDebuggingPort: descriptor.remoteDebuggingPort,
+      userDataDir: descriptor.userDataDir,
+      temporaryProfile: descriptor.temporaryProfile,
+      executablePath: descriptor.executablePath,
+    },
+    owner,
+    state
+  );
+  return session;
+}

package/src/browser/cdp-browser-endpoint.js

@@ -0,0 +1,55 @@
+/**
+ * A running Chromium-family browser addressed only by its DevTools endpoint:
+ * identify it, and ask it to shut down. Used by persistent sessions, their
+ * watchdog, and hand-off reconnection (issue #174), none of which hold an
+ * engine connection when they need to.
+ */
+
+/** `/json/version` of a CDP HTTP endpoint, or null when nothing answers. */
+export function probeSession(endpoint) {
+  return fetch(`${endpoint}/json/version`, {
+    signal: AbortSignal.timeout(1000),
+  })
+    .then((r) => (r.ok ? r.json() : null))
+    .catch(() => null);
+}
+
+/** Send `Browser.close` over a browser WebSocket and wait for the socket to close. */
+export async function closeRemoteBrowser(endpoint) {
+  await new Promise((resolve, reject) => {
+    const socket = new globalThis.WebSocket(endpoint);
+    let acknowledged = false;
+    const timer = setTimeout(() => {
+      socket.close();
+      reject(new Error('Browser.close timed out'));
+    }, 3000);
+    socket.onopen = () =>
+      socket.send(JSON.stringify({ id: 1, method: 'Browser.close' }));
+    socket.onclose = () => {
+      clearTimeout(timer);
+      resolve();
+    };
+    socket.onerror = () => {
+      // Chrome can close the TCP connection without a WebSocket close frame
+      // after acknowledging Browser.close. Its ensuing close event completes
+      // shutdown; a pre-acknowledgement connection error remains a failure.
+      if (!acknowledged) {
+        clearTimeout(timer);
+        reject(new Error('Browser.close connection failed'));
+      }
+    };
+    socket.onmessage = ({ data }) => {
+      const response = JSON.parse(data);
+      if (response.id !== 1) {
+        return;
+      }
+      if (response.error) {
+        clearTimeout(timer);
+        reject(new Error(response.error.message ?? 'Browser.close failed'));
+        socket.close();
+      } else {
+        acknowledged = true;
+      }
+    };
+  });
+}

package/src/browser/launcher.js

@@ -34,6 +34,7 @@ import {
   restorePuppeteerStorageState,
   restoreWebDriverStorageState,
 } from './storage-state.js';
+import { interruptionMode } from '../utilities/subprocess.js';
 
 /** How `launchBrowser` starts the browser (issue #103). */
 export const LAUNCH_MODES = Object.freeze(['real', 'engine']);
@@ -166,7 +167,12 @@ async function launchWithEngine(options, dependencies) {
     executablePath,
     automationParity,
     storageState,
+    interruption,
   } = options;
+  // The engines install their own SIGINT handler that closes the browser;
+  // with caller-owned interruption the embedder's handler decides (#174).
+  const signals =
+    interruptionMode(interruption) === 'caller' ? { handleSIGINT: false } : {};
   const chrome = resolveChromeArgs({
     args,
     extraArgs,
@@ -208,6 +214,7 @@ async function launchWithEngine(options, dependencies) {
           ignoreDefaultArgs: chrome.ignoreDefaultArgs,
           automationParity,
         }),
+        ...signals,
         ...(childEnv ? { env: childEnv } : {}),
       });
       page = browser.pages()[0] ?? (await browser.newPage());
@@ -223,6 +230,7 @@ async function launchWithEngine(options, dependencies) {
           automationParity,
         }),
         ...(slowMo ? { slowMo } : {}),
+        ...signals,
         ...(childEnv ? { env: childEnv } : {}),
       });
       page = (await browser.pages())[0] ?? (await browser.newPage());

package/src/browser/persistent-session.js

@@ -7,6 +7,10 @@ import { launchAndConnectRealBrowserWithDependencies } from './real-browser.js';
 import { assertDedicatedUserDataDir } from './system-browser.js';
 import { findSessionProcess } from './session-adoption.js';
 import { startDetachedProcess } from '../utilities/subprocess.js';
+import { closeRemoteBrowser, probeSession } from './cdp-browser-endpoint.js';
+import { pageTargetId } from './browser-handoff.js';
+
+export { closeRemoteBrowser, probeSession };
 
 export const SESSION_METADATA = '.browser-commander-session.json';
 const activity = new WeakMap();
@@ -27,13 +31,6 @@ export async function writeSessionMetadata(file, value) {
     await fs.rm(temporary, { force: true });
   }
 }
-export function probeSession(endpoint) {
-  return fetch(`${endpoint}/json/version`, {
-    signal: AbortSignal.timeout(1000),
-  })
-    .then((r) => (r.ok ? r.json() : null))
-    .catch(() => null);
-}
 export async function acquireLease(file, retries = 50) {
   let lease;
   try {
@@ -168,17 +165,7 @@ async function open(options, file, endpoint) {
   }
 }
 async function remember(page, engine, file, metadata, idleTimeoutMs) {
-  const cdp =
-    engine === 'playwright'
-      ? await page.context().newCDPSession(page)
-      : await page.target().createCDPSession();
-  try {
-    metadata.targetId = (
-      await cdp.send('Target.getTargetInfo')
-    ).targetInfo.targetId;
-  } finally {
-    await cdp.detach();
-  }
+  metadata.targetId = await pageTargetId({ engine, page });
   metadata.lastActive = Date.now();
   metadata.idleTimeoutMs = idleTimeoutMs;
   await writeSessionMetadata(file, metadata);
@@ -365,44 +352,6 @@ async function lifecycle(
   };
   return result;
 }
-export async function closeRemoteBrowser(endpoint) {
-  await new Promise((resolve, reject) => {
-    const socket = new globalThis.WebSocket(endpoint);
-    let acknowledged = false;
-    const timer = setTimeout(() => {
-      socket.close();
-      reject(new Error('Browser.close timed out'));
-    }, 3000);
-    socket.onopen = () =>
-      socket.send(JSON.stringify({ id: 1, method: 'Browser.close' }));
-    socket.onclose = () => {
-      clearTimeout(timer);
-      resolve();
-    };
-    socket.onerror = () => {
-      // Chrome can close the TCP connection without a WebSocket close frame
-      // after acknowledging Browser.close. Its ensuing close event completes
-      // shutdown; a pre-acknowledgement connection error remains a failure.
-      if (!acknowledged) {
-        clearTimeout(timer);
-        reject(new Error('Browser.close connection failed'));
-      }
-    };
-    socket.onmessage = ({ data }) => {
-      const response = JSON.parse(data);
-      if (response.id !== 1) {
-        return;
-      }
-      if (response.error) {
-        clearTimeout(timer);
-        reject(new Error(response.error.message ?? 'Browser.close failed'));
-        socket.close();
-      } else {
-        acknowledged = true;
-      }
-    };
-  });
-}
 /** Reuse an owned profile/port; detach survives the controller; close terminates it. */
 export async function connectOrLaunch(settings = {}) {
   const options = {

package/src/browser/real-browser.js

@@ -9,7 +9,9 @@ import { findBrowserSource } from './browser-sources.js';
 import { launchSafari } from './safari-launch.js';
 import { isSafariChannel } from './safari-support.js';
 
-import { startProcess } from '../utilities/subprocess.js';
+import { interruptionMode, startProcess } from '../utilities/subprocess.js';
+import { installHandoff } from './browser-handoff.js';
+import { closeRemoteBrowser } from './cdp-browser-endpoint.js';
 import { withDeadline } from '../traces/deadline.js';
 import {
   applyAutomationParityArgs,
@@ -256,8 +258,16 @@ export async function waitForCdpEndpoint({
   }
 }
 
-function spawnWithStartProcess(executablePath, args, { env, verbose }) {
-  return startProcess(executablePath, args, { env, forwardOutput: verbose });
+function spawnWithStartProcess(
+  executablePath,
+  args,
+  { env, verbose, interruption }
+) {
+  return startProcess(executablePath, args, {
+    env,
+    forwardOutput: verbose,
+    interruption,
+  });
 }
 
 async function waitForExit(browserProcess, timeout) {
@@ -310,12 +320,20 @@ function createCloser({
   closeTimeout,
   closeConnection,
   verbose,
+  handoffState = {},
 }) {
   const originalClose = closeConnection ?? browser?.close;
   let closing;
   const close = () => {
     closing ??= (async () => {
-      if (browserProcess.exitCode === null && originalClose) {
+      if (browserProcess.exitCode === null && handoffState.detached) {
+        // The engine connection was handed off; ask the browser directly.
+        await withDeadline(
+          closeRemoteBrowser(handoffState.webSocketDebuggerUrl),
+          closeTimeout,
+          'browser close'
+        ).catch(() => {});
+      } else if (browserProcess.exitCode === null && originalClose) {
         // A signal can sever the engine transport while its close RPC is pending.
         // Keep the existing close budget active until owned-process cleanup runs.
         await withDeadline(
@@ -348,6 +366,14 @@ function createCloser({
   return close;
 }
 
+/**
+ * Selenium attaches through a chromedriver the launch starts; the driver
+ * follows the browser's interruption ownership (issue #174).
+ */
+function driverInterruption(engine, interruption) {
+  return engine === 'selenium' ? { interruption } : {};
+}
+
 /**
  * Spawn a genuine installed Chrome-family browser with a dedicated profile,
  * wait for its loopback CDP endpoint, and attach through {@link connectBrowser}.
@@ -400,6 +426,7 @@ async function spawnOnFreePort({
   argOptions,
   env,
   verbose,
+  interruption,
   userDataDir,
   startupTimeout,
   dependencies,
@@ -421,6 +448,7 @@ async function spawnOnFreePort({
       browserProcess = await spawnBrowser(executablePath, browserArgs, {
         env,
         verbose: false,
+        interruption,
       });
     } catch (error) {
       throw launchFailure(error, {
@@ -650,8 +678,10 @@ export async function launchAndConnectRealBrowserWithDependencies(
     preferences,
     localState,
     firstRun,
+    interruption: requestedInterruption,
     ...connectionOptions
   } = options;
+  const interruption = interruptionMode(requestedInterruption);
   const argOptions = {
     headless,
     restrictions,
@@ -731,6 +761,7 @@ export async function launchAndConnectRealBrowserWithDependencies(
       argOptions,
       env: childEnv,
       verbose,
+      interruption,
       userDataDir,
       startupTimeout,
       dependencies,
@@ -756,9 +787,11 @@ export async function launchAndConnectRealBrowserWithDependencies(
       engine,
       cdpEndpoint: resolvedCdpEndpoint,
       ...connectionOptions,
+      ...driverInterruption(engine, interruption),
       seedCookies,
       verbose,
     });
+    const handoffState = { detached: false };
     const close = createCloser({
       engine,
       browser: connection.browser,
@@ -768,8 +801,9 @@ export async function launchAndConnectRealBrowserWithDependencies(
       closeTimeout,
       closeConnection: engine === 'selenium' ? connection.close : undefined,
       verbose,
+      handoffState,
     });
-    return await installSessionPersistence(
+    const session = await installSessionPersistence(
       {
         ...connection,
         close,
@@ -785,6 +819,23 @@ export async function launchAndConnectRealBrowserWithDependencies(
       },
       options
     );
+    return installHandoff(
+      session,
+      {
+        engine,
+        cdpEndpoint: resolvedCdpEndpoint,
+        userDataDir,
+        temporaryProfile,
+        remoteDebuggingPort: launched.port,
+        executablePath,
+        pid: () => browserProcess.pid,
+        connectedBrowser: () => connection.browser,
+        // The browser outlives this controller: no SIGINT forwarding, and
+        // its handle no longer keeps this program running.
+        release: () => browserProcess.detach?.(),
+      },
+      handoffState
+    );
   } catch (error) {
     if (browserProcess.exitCode === null) {
       browserProcess.kill();