browser-debugger-cli 0.7.2 → 0.9.0

package/dist/commands/stop.js

@@ -1,28 +1,26 @@
-import { runCommand } from '../commands/shared/CommandRunner.js';
-import { jsonOption } from '../commands/shared/commonOptions.js';
+import { runCommand } from './shared/CommandRunner.js';
+import { jsonOption } from './shared/commonOptions.js';
 import { stopSession } from '../ipc/client.js';
 import { IPCErrorCode } from '../ipc/index.js';
-import { performSessionCleanup } from '../session/cleanup.js';
-import { getSessionFilePath } from '../session/paths.js';
+import { IPCTimeoutError } from '../ipc/transport/index.js';
 import { joinLines } from '../ui/formatting.js';
-import { createLogger } from '../ui/logging/index.js';
-import { chromeKilledMessage, orphanedDaemonsCleanedMessage, warningMessage, } from '../ui/messages/commands.js';
+import { chromeClosedMessage, orphanedDaemonsCleanedMessage, warningMessage, } from '../ui/messages/commands.js';
 import { sessionStopped, STOP_MESSAGES, stopFailedError } from '../ui/messages/session.js';
+import { noActiveSessionMessage, sessionCommand, startSessionSuggestion, } from '../ui/messages/sessionCommand.js';
 import { getExitCodeForIPCError, isDaemonNotRunningError } from '../utils/errorMapping.js';
 import { getErrorMessage } from '../utils/errors.js';
 import { EXIT_CODES } from '../utils/exitCodes.js';
-const log = createLogger('cleanup');
 /**
  * Format stop result for human-readable output.
  *
  * @param data - Stop result data
  */
 function formatStop(data) {
-    const outputLine = data.stopped.bdg ? sessionStopped(getSessionFilePath('OUTPUT')) : undefined;
+    const outputLine = data.stopped.bdg ? sessionStopped() : undefined;
     const daemonsLine = data.stopped.daemons && data.orphanedDaemonsCount
         ? orphanedDaemonsCleanedMessage(data.orphanedDaemonsCount)
         : undefined;
-    return joinLines(outputLine, data.stopped.chrome && chromeKilledMessage(), daemonsLine, ...(data.warnings ?? []).map((warning) => warningMessage(warning)));
+    return joinLines(outputLine, data.stopped.chrome && chromeClosedMessage(), daemonsLine, ...(data.warnings ?? []).map((warning) => warningMessage(warning)));
 }
 /**
  * Register stop command
@@ -32,33 +30,24 @@ function formatStop(data) {
 export function registerStopCommand(program) {
     program
         .command('stop')
-        .description('Stop daemon and write collected telemetry to ~/.bdg/session.json')
-        .option('--kill-chrome', 'Also kill Chrome browser process', false)
+        .description('Stop daemon and close browser session')
+        .option('--kill-chrome', 'Kept for compatibility: Chrome launched by bdg is always closed on stop', false)
         .addOption(jsonOption())
-        .addHelpText('after', '\nOutput Location:\n  Default: ~/.bdg/session.json\n  Tip: Copy to custom location with: cp ~/.bdg/session.json /path/to/output.json')
         .action(async (options) => {
-        await runCommand(async (opts) => {
+        await runCommand(async () => {
             try {
                 const response = await stopSession();
                 if (response.status === 'ok') {
-                    const cleanupResult = await performSessionCleanup({
-                        killChrome: opts.killChrome,
-                        chromePid: response.chromePid,
-                    });
-                    if (cleanupResult.cleaned.chrome && !opts.json) {
-                        log.info(chromeKilledMessage(response.chromePid));
-                    }
                     return {
                         success: true,
                         data: {
                             stopped: {
                                 bdg: true,
-                                chrome: cleanupResult.cleaned.chrome,
-                                daemons: cleanupResult.cleaned.daemons,
+                                chrome: Boolean(response.chromePid),
+                                daemons: false,
                             },
-                            orphanedDaemonsCount: cleanupResult.orphanedDaemonsCount,
+                            orphanedDaemonsCount: 0,
                             message: response.message ?? STOP_MESSAGES.SUCCESS,
-                            ...(cleanupResult.warnings.length > 0 && { warnings: cleanupResult.warnings }),
                         },
                     };
                 }
@@ -66,10 +55,10 @@ export function registerStopCommand(program) {
                     if (response.errorCode === IPCErrorCode.NO_SESSION) {
                         return {
                             success: false,
-                            error: response.message ?? STOP_MESSAGES.NO_SESSION,
+                            error: response.message ?? noActiveSessionMessage(),
                             exitCode: EXIT_CODES.RESOURCE_NOT_FOUND,
                             errorContext: {
-                                suggestion: 'Start a session first with: bdg <url>',
+                                suggestion: startSessionSuggestion(),
                             },
                         };
                     }
@@ -79,20 +68,22 @@ export function registerStopCommand(program) {
                         error: response.message ?? STOP_MESSAGES.FAILED,
                         exitCode,
                         errorContext: {
-                            suggestion: 'Check session status with: bdg status',
+                            suggestion: `Check session status with: ${sessionCommand('bdg status')}`,
                         },
                     };
                 }
             }
             catch (error) {
+                if (error instanceof IPCTimeoutError)
+                    throw error;
                 const errorMessage = getErrorMessage(error);
                 if (isDaemonNotRunningError(errorMessage)) {
                     return {
                         success: false,
-                        error: STOP_MESSAGES.DAEMON_NOT_RUNNING,
+                        error: noActiveSessionMessage(),
                         exitCode: EXIT_CODES.RESOURCE_NOT_FOUND,
                         errorContext: {
-                            suggestion: 'Start a session first with: bdg <url>',
+                            suggestion: startSessionSuggestion(),
                         },
                     };
                 }
@@ -101,7 +92,7 @@ export function registerStopCommand(program) {
                     error: stopFailedError(errorMessage),
                     exitCode: EXIT_CODES.SOFTWARE_ERROR,
                     errorContext: {
-                        suggestion: 'Try: bdg cleanup --force to reset session state',
+                        suggestion: `Try: ${sessionCommand('bdg cleanup --force')} to reset session state`,
                     },
                 };
             }

package/dist/commands/tail.js

@@ -1,45 +1,28 @@
 /**
  * Tail command for continuous session monitoring.
  */
-import { jsonOption } from '../commands/shared/commonOptions.js';
-import { handleDaemonConnectionError } from '../commands/shared/daemonErrorHandler.js';
-import { fetchPreviewOutput } from '../commands/shared/dataFetcher.js';
-import { setupFollowMode } from '../commands/shared/followMode.js';
-import { positiveIntRule } from '../commands/shared/validation.js';
-import { OutputBuilder } from '../ui/OutputBuilder.js';
-import { CommandError } from '../ui/errors/index.js';
+import { jsonOption, showBothSectionsWhenBothRequested } from './shared/commonOptions.js';
+import { noteFollowConnected } from './shared/daemonErrorHandler.js';
+import { fetchPreviewOutput } from './shared/dataFetcher.js';
+import { followFetchFailure, setupFollowMode, } from './shared/followMode.js';
+import { handleValidationError } from './shared/handleValidationError.js';
+import { MAX_LAST_ITEMS, positiveIntRule } from './shared/validation.js';
 import { formatPreview } from '../ui/formatters/preview.js';
 import { followingPreviewMessage, stoppedFollowingPreviewMessage } from '../ui/messages/preview.js';
-import { EXIT_CODES } from '../utils/exitCodes.js';
 function parseOptions(options) {
-    const lastRule = positiveIntRule({ min: 1, max: 1000, default: 10 });
-    const intervalRule = positiveIntRule({ min: 100, max: 60000, default: 1000 });
+    const lastRule = positiveIntRule({
+        name: '--last',
+        min: 1,
+        max: MAX_LAST_ITEMS,
+        default: 10,
+        allowZeroForAll: true,
+    });
+    const intervalRule = positiveIntRule({ name: '--interval', min: 100, max: 60000, default: 1000 });
     return {
         lastN: lastRule.validate(options.last),
         interval: intervalRule.validate(options.interval),
     };
 }
-function handleValidationError(error, json) {
-    if (error instanceof CommandError) {
-        if (json) {
-            const errorOptions = {
-                exitCode: error.exitCode,
-            };
-            if (error.metadata.suggestion) {
-                errorOptions.suggestion = error.metadata.suggestion;
-            }
-            console.log(JSON.stringify(OutputBuilder.buildJsonError(error.message, errorOptions)));
-        }
-        else {
-            console.error(error.message);
-            if (error.metadata.suggestion)
-                console.error(error.metadata.suggestion);
-        }
-        process.exit(error.exitCode);
-    }
-    console.error(error instanceof Error ? error.message : String(error));
-    process.exit(EXIT_CODES.INVALID_ARGUMENTS);
-}
 function createPreviewOptions(options, lastN) {
     return {
         json: options.json,
@@ -59,9 +42,10 @@ export function registerTailCommand(program) {
         .option('-v, --verbose', 'Use verbose output with full URLs and formatting', false)
         .option('-n, --network', 'Show only network requests', false)
         .option('-c, --console', 'Show only console messages', false)
-        .option('--last <count>', 'Show last N items (network requests + console messages)', '10')
+        .option('--last <count>', 'Show last N items (network requests + console messages), 0 for all', '10')
         .option('--interval <ms>', 'Update interval in milliseconds', '1000')
         .action(async (options) => {
+        showBothSectionsWhenBothRequested(options);
         let lastN;
         let interval;
         try {
@@ -73,26 +57,20 @@ export function registerTailCommand(program) {
             handleValidationError(error, options.json ?? false);
         }
         const showPreview = async () => {
-            const result = await fetchPreviewOutput();
+            const result = await fetchPreviewOutput({ lastN });
             if (!result.success) {
-                const errorResult = handleDaemonConnectionError(result.error, {
-                    json: options.json,
-                    follow: true,
-                    retryIntervalMs: interval,
-                    exitCode: result.exitCode,
-                });
-                if (errorResult.shouldExit)
-                    process.exit(errorResult.exitCode);
-                return;
+                return followFetchFailure(result, { json: options.json, retryIntervalMs: interval });
             }
-            console.clear();
+            noteFollowConnected();
+            if (!options.json)
+                console.clear();
             console.log(formatPreview(result.data, createPreviewOptions(options, lastN)));
+            return undefined;
         };
         await setupFollowMode(showPreview, {
             startMessage: followingPreviewMessage,
             stopMessage: stoppedFollowingPreviewMessage,
             intervalMs: interval,
-            handleEpipe: true,
         });
     });
 }

package/dist/commands/types.d.ts

@@ -34,6 +34,8 @@ export interface CleanupResult {
         chrome: boolean;
         daemons: boolean;
     };
+    /** Directory deleted by `--purge` */
+    purged?: string;
     message: string;
     warnings?: string[];
 }

package/dist/commands.js

@@ -5,7 +5,9 @@ import { registerDetailsCommand } from './commands/details.js';
 import { registerFormInteractionCommands } from './commands/dom/formInteraction.js';
 import { registerDomCommands } from './commands/dom/index.js';
 import { registerNetworkCommands } from './commands/network/index.js';
+import { registerPageCommands } from './commands/page.js';
 import { registerPeekCommand } from './commands/peek.js';
+import { registerSessionsCommand } from './commands/sessions.js';
 import { registerStartCommands } from './commands/start.js';
 import { registerStatusCommand } from './commands/status.js';
 import { registerStopCommand } from './commands/stop.js';
@@ -26,6 +28,7 @@ export const commandRegistry = [
     registerStartCommands,
     addCommandGroup('Session Management:'),
     registerStatusCommand,
+    registerSessionsCommand,
     registerStopCommand,
     registerCleanupCommand,
     addCommandGroup('Data Inspection:'),
@@ -34,6 +37,7 @@ export const commandRegistry = [
     registerDetailsCommand,
     registerDomCommands,
     registerFormInteractionCommands,
+    registerPageCommands,
     addCommandGroup('CDP Commands:'),
     registerCdpCommand,
     addCommandGroup('Network Commands:'),

package/dist/connection/cdp.d.ts

@@ -79,8 +79,8 @@ export declare class CDPConnection implements CDPEventSource {
      * continue indefinitely.
      *
      * @param wsUrl - WebSocket debugger URL from CDP target
-     * @param options - Connection configuration options
-     * @throws Error if connection fails after all retries
+     * @param options - Connection configuration options (`signal` stops retrying)
+     * @throws Error if connection fails after all retries or is aborted
      */
     connect(wsUrl: string, options?: ConnectionOptions): Promise<void>;
     /**
@@ -90,9 +90,10 @@ export declare class CDPConnection implements CDPEventSource {
      * indefinitely without it, especially in network failure scenarios.
      *
      * @param wsUrl - WebSocket URL to connect to
-     * @param options - Connection configuration options
+     * @param options - Connection configuration options (`signal` ends a pending attempt)
      * @returns Promise that resolves when connection is established
      * @throws CDPTimeoutError if connection times out
+     * @throws CDPConnectionError if the attempt is aborted
      * @throws Error if WebSocket connection fails
      */
     private attemptConnection;
@@ -100,7 +101,9 @@ export declare class CDPConnection implements CDPEventSource {
      * Configure WebSocket event handlers for connection lifecycle.
      *
      * We handle close events asynchronously to prevent blocking the WebSocket
-     * event loop during cleanup and reconnection attempts.
+     * event loop during cleanup and reconnection attempts. A socket that never
+     * opened is a failed attempt, not a disconnect: `connect()` retries it, so it
+     * must not trigger `onDisconnect` or auto-reconnect.
      *
      * @param resolve - Promise resolve function for successful connection
      * @param reject - Promise reject function for connection failure
@@ -160,6 +163,9 @@ export declare class CDPConnection implements CDPEventSource {
     /**
      * Handle CDP events by notifying registered handlers.
      *
+     * Handlers also receive the event's session id, set for events of attached
+     * targets (iframes, workers) and absent for the page itself.
+     *
      * @param message - CDP message containing event data
      */
     private handleCDPEvent;
@@ -245,7 +251,7 @@ export declare class CDPConnection implements CDPEventSource {
      * instead of handler ID for easier resource management.
      *
      * @param event - CDP event name (e.g., 'Network.requestWillBeSent')
-     * @param handler - Callback function to handle the event
+     * @param handler - Callback receiving the event params and, for attached targets, their session id
      * @returns Cleanup function to unregister the handler
      * @typeParam T - Type of event parameters for type safety at call site
      *
@@ -259,7 +265,7 @@ export declare class CDPConnection implements CDPEventSource {
      * cleanup();
      * ```
      */
-    on<T = unknown>(event: string, handler: (params: T) => void): EventCleanup;
+    on<T = unknown>(event: string, handler: (params: T, sessionId?: string) => void): EventCleanup;
     /**
      * Remove a specific event handler.
      *

package/dist/connection/cdp.js

@@ -1,8 +1,9 @@
+import { setTimeout as sleep } from 'node:timers/promises';
 import WebSocket from 'ws';
 import { delay as asyncDelay } from '../utils/async.js';
 import { getErrorMessage } from '../utils/errors.js';
 import { DEFAULT_CDP_CONFIG, WEBSOCKET_CONFIG, UTF8_ENCODING } from './config.js';
-import { CDPConnectionError, CDPTimeoutError } from './errors.js';
+import { CDPConnectionError, CDPProtocolError, CDPTimeoutError } from './errors.js';
 const CONNECTION_TIMEOUT_ERROR = 'Connection timeout';
 const WEBSOCKET_CONNECTION_CLOSED_ERROR = 'WebSocket connection closed';
 const CONNECTION_CLOSED_ERROR = 'Connection closed';
@@ -14,6 +15,21 @@ const PONG_TIMEOUT_MESSAGE = 'Pong timeout - connection may be stale';
 const NO_PONG_RECEIVED_REASON = 'No pong received';
 const NORMAL_CLOSURE_REASON = 'Normal closure';
 const CONNECTION_ATTEMPT_FAILED_MESSAGE = (attempt, delay) => `Connection attempt ${attempt + 1} failed, retrying in ${delay}ms...`;
+const CONNECTION_ABORTED_ERROR = 'Connection attempts aborted';
+/**
+ * Wait between connection attempts, ending early when `signal` aborts.
+ *
+ * @param ms - Delay in milliseconds
+ * @param signal - Optional abort signal
+ */
+async function abortableDelay(ms, signal) {
+    if (!signal)
+        return asyncDelay(ms);
+    await sleep(ms, undefined, { signal }).catch((error) => {
+        if (!signal.aborted)
+            throw error;
+    });
+}
 const FAILED_CONNECT_ATTEMPTS_ERROR = (maxRetries, lastErrorMessage) => `Failed to connect after ${maxRetries} attempts: ${lastErrorMessage}`;
 const WEBSOCKET_CLOSED_MESSAGE = (code, reason) => `WebSocket closed: ${code} - ${reason}`;
 const RECONNECTING_MESSAGE = (delay, attempt, maxAttempts) => `Reconnecting in ${delay}ms... (attempt ${attempt}/${maxAttempts})`;
@@ -89,8 +105,8 @@ export class CDPConnection {
      * continue indefinitely.
      *
      * @param wsUrl - WebSocket debugger URL from CDP target
-     * @param options - Connection configuration options
-     * @throws Error if connection fails after all retries
+     * @param options - Connection configuration options (`signal` stops retrying)
+     * @throws Error if connection fails after all retries or is aborted
      */
     async connect(wsUrl, options = {}) {
         const maxRetries = options.maxRetries ?? this.config.maxConnectionRetries;
@@ -103,7 +119,7 @@ export class CDPConnection {
         this.isIntentionallyClosed = false;
         this.connectionOptions = options;
         let lastError;
-        for (let attempt = 0; attempt < maxRetries; attempt++) {
+        for (let attempt = 0; attempt < maxRetries && !options.signal?.aborted; attempt++) {
             try {
                 await this.attemptConnection(wsUrl, options);
                 this.reconnectAttempts = 0;
@@ -114,10 +130,13 @@ export class CDPConnection {
                 if (attempt < maxRetries - 1) {
                     const delay = this.calculateBackoffDelay(attempt, this.config.maxRetryDelay);
                     this.logger.info(CONNECTION_ATTEMPT_FAILED_MESSAGE(attempt, delay));
-                    await asyncDelay(delay);
+                    await abortableDelay(delay, options.signal);
                 }
             }
         }
+        if (options.signal?.aborted) {
+            throw new CDPConnectionError(CONNECTION_ABORTED_ERROR, lastError);
+        }
         throw new CDPConnectionError(FAILED_CONNECT_ATTEMPTS_ERROR(maxRetries, lastError?.message), lastError);
     }
     /**
@@ -127,9 +146,10 @@ export class CDPConnection {
      * indefinitely without it, especially in network failure scenarios.
      *
      * @param wsUrl - WebSocket URL to connect to
-     * @param options - Connection configuration options
+     * @param options - Connection configuration options (`signal` ends a pending attempt)
      * @returns Promise that resolves when connection is established
      * @throws CDPTimeoutError if connection times out
+     * @throws CDPConnectionError if the attempt is aborted
      * @throws Error if WebSocket connection fails
      */
     attemptConnection(wsUrl, options = {}) {
@@ -140,18 +160,35 @@ export class CDPConnection {
                 handshakeTimeout: WEBSOCKET_CONFIG.handshakeTimeout,
                 maxPayload: WEBSOCKET_CONFIG.maxPayload,
             });
+            const { signal } = options;
+            const onAbort = () => {
+                clearTimeout(connectTimeout);
+                reject(new CDPConnectionError(CONNECTION_ABORTED_ERROR));
+                this.ws?.close();
+            };
+            const settled = () => signal?.removeEventListener('abort', onAbort);
             const connectTimeout = setTimeout(() => {
+                settled();
                 reject(new CDPTimeoutError(CONNECTION_TIMEOUT_ERROR));
                 this.ws?.close();
             }, timeout);
-            this.setupWebSocketHandlers(resolve, reject, connectTimeout, options);
+            signal?.addEventListener('abort', onAbort, { once: true });
+            this.setupWebSocketHandlers(() => {
+                settled();
+                resolve();
+            }, (error) => {
+                settled();
+                reject(error);
+            }, connectTimeout, options);
         });
     }
     /**
      * Configure WebSocket event handlers for connection lifecycle.
      *
      * We handle close events asynchronously to prevent blocking the WebSocket
-     * event loop during cleanup and reconnection attempts.
+     * event loop during cleanup and reconnection attempts. A socket that never
+     * opened is a failed attempt, not a disconnect: `connect()` retries it, so it
+     * must not trigger `onDisconnect` or auto-reconnect.
      *
      * @param resolve - Promise resolve function for successful connection
      * @param reject - Promise reject function for connection failure
@@ -161,7 +198,9 @@ export class CDPConnection {
     setupWebSocketHandlers(resolve, reject, connectTimeout, options) {
         if (!this.ws)
             return;
+        let opened = false;
         this.ws.on('open', () => {
+            opened = true;
             clearTimeout(connectTimeout);
             this.missedPongs = 0;
             this.startKeepalive(options.keepaliveInterval ?? this.config.keepaliveInterval);
@@ -174,7 +213,7 @@ export class CDPConnection {
         this.ws.on('close', (code, reason) => {
             void (async () => {
                 this.stopKeepalive();
-                if (this.isIntentionallyClosed) {
+                if (this.isIntentionallyClosed || !opened) {
                     return;
                 }
                 this.logger.info(WEBSOCKET_CLOSED_MESSAGE(code, reason.toString()));
@@ -313,7 +352,8 @@ export class CDPConnection {
             this.pendingMessages.delete(message.id);
             clearTimeout(pending.timeout);
             if (message.error) {
-                pending.reject(new Error(message.error.message));
+                const { message: text, code, data } = message.error;
+                pending.reject(new CDPProtocolError(text, code, data));
             }
             else {
                 pending.resolve(message.result);
@@ -323,6 +363,9 @@ export class CDPConnection {
     /**
      * Handle CDP events by notifying registered handlers.
      *
+     * Handlers also receive the event's session id, set for events of attached
+     * targets (iframes, workers) and absent for the page itself.
+     *
      * @param message - CDP message containing event data
      */
     handleCDPEvent(message) {
@@ -330,7 +373,7 @@ export class CDPConnection {
             return;
         const handlers = this.eventHandlers.get(message.method);
         if (handlers) {
-            handlers.forEach((handler) => handler(message.params));
+            handlers.forEach((handler) => handler(message.params, message.sessionId));
         }
     }
     /**
@@ -400,7 +443,7 @@ export class CDPConnection {
      */
     startKeepalive(interval) {
         this.pingInterval = setInterval(() => {
-            if (this.ws && this.ws.readyState === WebSocket.OPEN) {
+            if (this.ws?.readyState === WebSocket.OPEN) {
                 this.missedPongs++;
                 if (this.missedPongs >= this.config.maxMissedPongs) {
                     this.logger.info(CONNECTION_LOST_MESSAGE);
@@ -463,7 +506,8 @@ export class CDPConnection {
      * @throws CDPTimeoutError if command times out (30s)
      */
     async send(method, params = {}, sessionId) {
-        if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
+        const ws = this.ws;
+        if (ws?.readyState !== WebSocket.OPEN) {
             throw new CDPConnectionError(NOT_CONNECTED_BROWSER_ERROR);
         }
         const id = ++this.messageId;
@@ -501,8 +545,7 @@ export class CDPConnection {
                 },
                 timeout,
             });
-            // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-            this.ws.send(JSON.stringify(message));
+            ws.send(JSON.stringify(message));
         });
     }
     /**
@@ -516,7 +559,7 @@ export class CDPConnection {
      * instead of handler ID for easier resource management.
      *
      * @param event - CDP event name (e.g., 'Network.requestWillBeSent')
-     * @param handler - Callback function to handle the event
+     * @param handler - Callback receiving the event params and, for attached targets, their session id
      * @returns Cleanup function to unregister the handler
      * @typeParam T - Type of event parameters for type safety at call site
      *

package/dist/connection/chromeIdentity.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Identity of the Chrome bdg launched.
+ *
+ * chrome-launcher only waits until something answers on 127.0.0.1:<port>. That
+ * may be another process: when 127.0.0.1:<port> is taken, Chrome listens on
+ * [::1]:<port> instead and the readiness check is answered by the other one.
+ *
+ * Chrome prints `DevTools listening on ws://<host>:<port>/devtools/browser/<id>`
+ * to stderr (chrome-launcher writes it to `chrome-err.log` in the profile).
+ * The browser path is unique per browser, so comparing it with the one
+ * 127.0.0.1:<port> reports tells whether that is the launched Chrome.
+ * (Chrome's `DevToolsActivePort` file holds the same, but Chrome writes it only
+ * for `--remote-debugging-port=0`.)
+ *
+ * A Chrome whose output lacks the line (stderr redirected, a Chromium build
+ * that does not print it) is accepted with a warning when its browser answers
+ * on 127.0.0.1 and nothing listens on [::1]: the port was free on both right
+ * before the launch, and a second listener is how a conflict shows.
+ */
+import { type StartupLogs } from './startupExit.js';
+/**
+ * The debugging endpoint a Chrome announced for itself.
+ */
+export interface DevToolsEndpoint {
+    /** Address the debugging server listens on (`127.0.0.1`, `[::1]`) */
+    host: string;
+    /** Port the debugging server listens on */
+    port: number;
+    /** Browser WebSocket path, `/devtools/browser/<id>` */
+    browserPath: string;
+}
+/**
+ * Find the endpoint Chrome announced in its output (the last announcement).
+ *
+ * @param lines - Chrome's output lines
+ * @returns Endpoint, or null if there is no complete announcement
+ */
+export declare function parseDevToolsListening(lines: readonly string[]): DevToolsEndpoint | null;
+/**
+ * Wait for Chrome to announce its endpoint.
+ *
+ * @param logs - Chrome's log positions from before the launch
+ * @param isRunning - Whether Chrome is still running (waiting stops when not)
+ * @param timeoutMs - Longest wait
+ * @returns Endpoint, or null if Chrome exited or announced none in time
+ */
+export declare function waitForDevToolsEndpoint(logs: StartupLogs, isRunning: () => boolean, timeoutMs?: number): Promise<DevToolsEndpoint | null>;
+/**
+ * Check that the Chrome answering on 127.0.0.1:<port> is the one just
+ * launched, so bdg never drives another session's browser.
+ *
+ * @param options - Chrome's log positions from before the launch, requested
+ *   port (free on 127.0.0.1 and ::1 right before the launch), Chrome's PID and
+ *   longest wait for its announcement
+ * @throws ChromeLaunchError: CHROME_DIED_AFTER_LAUNCH if Chrome exits first;
+ *   PORT_IN_USE if another browser or process answers on the port;
+ *   CHROME_LAUNCH_FAILED if Chrome announced nothing and nothing answers
+ */
+export declare function verifyLaunchedChrome(options: {
+    logs: StartupLogs;
+    port: number;
+    pid: number;
+    timeoutMs?: number;
+}): Promise<void>;
+//# sourceMappingURL=chromeIdentity.d.ts.map