browser-commander 0.31.1 → 0.32.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # 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
+
+- 9f486af: Preserve native Playwright text selectors and CSS sibling positions. Resolve nonnative text matches to unique ancestor paths so interactions keep their intended target across Playwright, Puppeteer, and Selenium.
+
+  Retain sanitized engine failures alongside Chrome stderr in launch error messages. Identify attachment stages and optionally log their timing with verbose mode; wait for actual child exit before profile cleanup, and verify readiness, cleanup ownership, and fresh-profile startup on macOS in CI.
+
 ## 0.31.1
 
 ### 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.1",
+  "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/connection-stage.js

@@ -0,0 +1,23 @@
+/** Identify attachment failures; optional logs contain stage names and timings. */
+export async function connectionStage(options, stage, work) {
+  const start = performance.now();
+  const report = (state) => {
+    if (options.verbose) {
+      console.log(
+        `Browser attachment ${stage} ${state} after ${Math.round(performance.now() - start)}ms`
+      );
+    }
+  };
+  report('started');
+  try {
+    const result = await work();
+    report('completed');
+    return result;
+  } catch (error) {
+    if (error && typeof error === 'object' && Object.isExtensible(error)) {
+      error.attachmentStage ??= stage;
+    }
+    report('failed');
+    throw error;
+  }
+}

package/src/browser/connector.js

@@ -1,4 +1,5 @@
 import { attachDownloads } from '../downloads/attach.js';
+import { connectionStage } from './connection-stage.js';
 import { connectWebDriver, launchWebDriver } from './webdriver.js';
 import {
   loadStorageState,
@@ -282,7 +283,9 @@ async function connectPlaywright({ options, loadPlaywright, storageState }) {
   const settings = buildPlaywrightConnectOptions(options);
   let browser;
   try {
-    browser = await chromium.connectOverCDP(endpoint, settings);
+    browser = await connectionStage(options, 'engine-connect', () =>
+      chromium.connectOverCDP(endpoint, settings)
+    );
   } catch (error) {
     if (
       settings.noDefaults !== undefined ||
@@ -291,21 +294,26 @@ async function connectPlaywright({ options, loadPlaywright, storageState }) {
     ) {
       throw error;
     }
-    browser = await chromium.connectOverCDP(endpoint, {
-      ...settings,
-      noDefaults: true,
-    });
+    browser = await connectionStage(options, 'engine-connect', () =>
+      chromium.connectOverCDP(endpoint, { ...settings, noDefaults: true })
+    );
   }
   try {
     const context = browser.contexts()[0];
     if (!context) {
       throw new Error('Connected Playwright browser has no default context');
     }
-    const page =
-      (await pickForegroundPage(context.pages(), options)) ??
-      (await context.newPage());
+    const page = await connectionStage(
+      options,
+      'page-selection',
+      async () =>
+        (await pickForegroundPage(context.pages(), options)) ??
+        (await context.newPage())
+    );
 
-    await restorePlaywrightStorageState({ context, storageState });
+    await connectionStage(options, 'storage-restore', () =>
+      restorePlaywrightStorageState({ context, storageState })
+    );
     return { browser, page, detach: browser.close?.bind(browser) };
   } catch (error) {
     await ignoreCleanup(() => browser.close?.());
@@ -316,15 +324,21 @@ async function connectPlaywright({ options, loadPlaywright, storageState }) {
 async function connectPuppeteer({ options, loadPuppeteer, storageState }) {
   const puppeteerModule = await loadPuppeteer();
   const puppeteer = puppeteerModule.default ?? puppeteerModule;
-  const browser = await puppeteer.connect(
-    buildPuppeteerConnectOptions(options)
+  const browser = await connectionStage(options, 'engine-connect', () =>
+    puppeteer.connect(buildPuppeteerConnectOptions(options))
   );
   try {
-    const page =
-      (await pickForegroundPage(await browser.pages(), options)) ??
-      (await browser.newPage());
+    const page = await connectionStage(
+      options,
+      'page-selection',
+      async () =>
+        (await pickForegroundPage(await browser.pages(), options)) ??
+        (await browser.newPage())
+    );
 
-    await restorePuppeteerStorageState({ page, storageState });
+    await connectionStage(options, 'storage-restore', () =>
+      restorePuppeteerStorageState({ page, storageState })
+    );
     return { browser, page, detach: browser.disconnect?.bind(browser) };
   } catch (error) {
     await ignoreCleanup(() => browser.disconnect?.());

package/src/browser/launch-diagnostics.js

@@ -7,10 +7,11 @@ export class BrowserLaunchError extends Error {
     exitCode = null,
     signal = null,
     stderrTail = '',
+    attachmentStage,
     cause,
   }) {
     super(
-      `Browser launch failed (${phase}: ${category}): ${stderrTail || cause?.message || ''}`,
+      `Browser launch failed (${phase}: ${category}): ${cause?.message || ''}${stderrTail ? `\nBrowser stderr:\n${stderrTail}` : ''}`,
       { cause }
     );
     this.name = 'BrowserLaunchError';
@@ -21,6 +22,7 @@ export class BrowserLaunchError extends Error {
       exitCode,
       signal,
       stderrTail,
+      ...(attachmentStage ? { attachmentStage } : {}),
     });
   }
 }
@@ -98,5 +100,6 @@ export function launchFailure(
     signal: browserProcess?.signalCode ?? null,
     stderrTail: scrub(browserProcess?.stderrTail ?? cause?.stderrTail ?? ''),
     cause: safeCause,
+    attachmentStage: cause?.attachmentStage,
   });
 }

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 = {