browser-debugger-cli 0.7.1 → 0.8.0

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/diagnostics.d.ts

@@ -13,13 +13,4 @@ export interface ChromeDiagnostics {
  * @returns Chrome diagnostics information
  */
 export declare function getChromeDiagnostics(): ChromeDiagnostics;
-/**
- * Get formatted Chrome diagnostics for error messages.
- *
- * Retrieves Chrome installation information and formats it for display
- * in error messages. Uses cached diagnostics to avoid repeated filesystem scans.
- *
- * @returns Array of formatted diagnostic strings
- */
-export declare function getFormattedDiagnostics(): string[];
 //# sourceMappingURL=diagnostics.d.ts.map

package/dist/connection/diagnostics.js

@@ -1,6 +1,5 @@
 import * as chromeLauncher from 'chrome-launcher';
 import { createLogger } from '../ui/logging/index.js';
-import { formatDiagnosticsForError } from '../ui/messages/chrome.js';
 import { getErrorMessage } from '../utils/errors.js';
 const log = createLogger('diagnostics');
 /**
@@ -38,16 +37,4 @@ export function getChromeDiagnostics() {
     };
     return cachedDiagnostics;
 }
-/**
- * Get formatted Chrome diagnostics for error messages.
- *
- * Retrieves Chrome installation information and formats it for display
- * in error messages. Uses cached diagnostics to avoid repeated filesystem scans.
- *
- * @returns Array of formatted diagnostic strings
- */
-export function getFormattedDiagnostics() {
-    const diagnostics = getChromeDiagnostics();
-    return formatDiagnosticsForError(diagnostics);
-}
 //# sourceMappingURL=diagnostics.js.map

package/dist/connection/errors.d.ts

@@ -3,16 +3,29 @@
  *
  * Provides structured error handling for CDP connections and Chrome launches.
  */
+import type { IssueDetails } from '../errors/issues.js';
+/**
+ * Options accepted by ConnectionError subclasses.
+ */
+export interface ConnectionErrorOptions {
+    /** Underlying error that triggered this one. */
+    cause?: Error;
+    /** Structured issue payload for boundary formatters. */
+    issue?: IssueDetails;
+}
 /**
  * Base error class for all connection-related errors.
  *
  * Extends native Error with error codes for programmatic handling,
  * exit codes for semantic exit codes, and cause chaining for nested errors.
+ * Optionally carries a structured {@link IssueDetails} payload so callers at
+ * the UI boundary can format messages deterministically.
  */
 export declare abstract class ConnectionError extends Error {
     abstract readonly code: string;
     abstract readonly exitCode: number;
-    constructor(message: string, cause?: Error);
+    readonly issue?: IssueDetails;
+    constructor(message: string, options?: ConnectionErrorOptions | Error);
 }
 /**
  * CDP connection failed (network/protocol issues).
@@ -49,4 +62,26 @@ export declare class CDPTimeoutError extends ConnectionError {
     readonly code = "CDP_TIMEOUT_ERROR";
     readonly exitCode: 102;
 }
+/**
+ * An error Chrome returned for a CDP command (e.g. invalid parameters, no
+ * node with the given id), with its JSON-RPC code and detail.
+ */
+export declare class CDPProtocolError extends Error {
+    readonly code: number | undefined;
+    readonly data: string | undefined;
+    readonly name = "CDPProtocolError";
+    /**
+     * @param message - Chrome's error message
+     * @param code - JSON-RPC error code
+     * @param data - Chrome's detail (e.g. which parameter is missing)
+     */
+    constructor(message: string, code: number | undefined, data: string | undefined);
+    /**
+     * Whether the command itself was wrong (method or parameters), as opposed
+     * to failing on the page's state.
+     *
+     * @returns True for a user error
+     */
+    isRequestError(): boolean;
+}
 //# sourceMappingURL=errors.d.ts.map

package/dist/connection/errors.js

@@ -9,13 +9,23 @@ import { EXIT_CODES } from '../utils/exitCodes.js';
  *
  * Extends native Error with error codes for programmatic handling,
  * exit codes for semantic exit codes, and cause chaining for nested errors.
+ * Optionally carries a structured {@link IssueDetails} payload so callers at
+ * the UI boundary can format messages deterministically.
  */
 export class ConnectionError extends Error {
-    constructor(message, cause) {
+    issue;
+    constructor(message, options) {
         super(message);
         this.name = this.constructor.name;
-        if (cause) {
-            this.cause = cause;
+        if (options instanceof Error) {
+            this.cause = options;
+            return;
+        }
+        if (options?.cause) {
+            this.cause = options.cause;
+        }
+        if (options?.issue) {
+            this.issue = options.issue;
         }
     }
 }
@@ -54,4 +64,34 @@ export class CDPTimeoutError extends ConnectionError {
     code = 'CDP_TIMEOUT_ERROR';
     exitCode = EXIT_CODES.CDP_TIMEOUT;
 }
+/** JSON-RPC error codes that mean the request itself was wrong */
+const REQUEST_ERROR_CODES = new Set([-32600, -32601, -32602]);
+/**
+ * An error Chrome returned for a CDP command (e.g. invalid parameters, no
+ * node with the given id), with its JSON-RPC code and detail.
+ */
+export class CDPProtocolError extends Error {
+    code;
+    data;
+    name = 'CDPProtocolError';
+    /**
+     * @param message - Chrome's error message
+     * @param code - JSON-RPC error code
+     * @param data - Chrome's detail (e.g. which parameter is missing)
+     */
+    constructor(message, code, data) {
+        super(data ? `${message}: ${data}` : message);
+        this.code = code;
+        this.data = data;
+    }
+    /**
+     * Whether the command itself was wrong (method or parameters), as opposed
+     * to failing on the page's state.
+     *
+     * @returns True for a user error
+     */
+    isRequestError() {
+        return this.code !== undefined && REQUEST_ERROR_CODES.has(this.code);
+    }
+}
 //# sourceMappingURL=errors.js.map

package/dist/connection/handlers.d.ts

@@ -1,6 +1,6 @@
-import type ProtocolMapping from 'devtools-protocol/types/protocol-mapping';
-import type { CDPConnection } from '../connection/cdp.js';
-import type { EventParams, TypedCDPConnection } from '../connection/typed-cdp.js';
+import type { ProtocolMapping } from 'devtools-protocol/types/protocol-mapping.js';
+import type { CDPConnection } from './cdp.js';
+import type { EventParams, TypedCDPConnection } from './typed-cdp.js';
 /**
  * Registry for managing CDP event handlers with automatic cleanup.
  *
@@ -26,7 +26,7 @@ export declare class CDPHandlerRegistry {
      *
      * @param typed - Typed CDP connection instance
      * @param event - CDP event name (autocomplete available)
-     * @param handler - Event handler with type-safe parameters
+     * @param handler - Event handler with type-safe parameters and the session id of attached targets
      *
      * @example
      * ```typescript
@@ -39,7 +39,7 @@ export declare class CDPHandlerRegistry {
      * });
      * ```
      */
-    registerTyped<T extends keyof ProtocolMapping.Events>(typed: TypedCDPConnection, event: T, handler: (params: EventParams<T>) => void): void;
+    registerTyped<T extends keyof ProtocolMapping.Events>(typed: TypedCDPConnection, event: T, handler: (params: EventParams<T>, sessionId?: string) => void): void;
     /**
      * Remove all registered event handlers and clear the registry.
      */

package/dist/connection/handlers.js

@@ -26,7 +26,7 @@ export class CDPHandlerRegistry {
      *
      * @param typed - Typed CDP connection instance
      * @param event - CDP event name (autocomplete available)
-     * @param handler - Event handler with type-safe parameters
+     * @param handler - Event handler with type-safe parameters and the session id of attached targets
      *
      * @example
      * ```typescript

package/dist/connection/inFlightRequests.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Track network requests in flight, keyed by requestId.
+ *
+ * A plain counter breaks on redirects (Chrome sends `requestWillBeSent` once
+ * per hop but `loadingFinished` once per chain, so the count never returns to
+ * zero) and on requests that started before tracking began (their completion
+ * drives the count negative). A set of request ids has neither problem.
+ */
+import type { CDPConnection } from './cdp.js';
+/**
+ * Live view of in-flight requests.
+ */
+export interface InFlightRequests {
+    /** Number of requests currently in flight */
+    readonly count: number;
+    /** Distinct requests started since tracking began */
+    readonly started: number;
+    /** Timestamp (ms) of the last request start or completion */
+    readonly lastActivity: number;
+    /** Stop listening to CDP events */
+    dispose: () => void;
+}
+/**
+ * Start tracking in-flight requests on a CDP connection.
+ *
+ * The caller is responsible for `Network.enable`.
+ *
+ * @param cdp - CDP connection
+ * @param onChange - Called after every start or completion
+ * @returns Live tracker
+ */
+export declare function trackInFlightRequests(cdp: CDPConnection, onChange?: () => void): InFlightRequests;
+//# sourceMappingURL=inFlightRequests.d.ts.map

package/dist/connection/inFlightRequests.js

@@ -0,0 +1,52 @@
+/**
+ * Track network requests in flight, keyed by requestId.
+ *
+ * A plain counter breaks on redirects (Chrome sends `requestWillBeSent` once
+ * per hop but `loadingFinished` once per chain, so the count never returns to
+ * zero) and on requests that started before tracking began (their completion
+ * drives the count negative). A set of request ids has neither problem.
+ */
+/**
+ * Start tracking in-flight requests on a CDP connection.
+ *
+ * The caller is responsible for `Network.enable`.
+ *
+ * @param cdp - CDP connection
+ * @param onChange - Called after every start or completion
+ * @returns Live tracker
+ */
+export function trackInFlightRequests(cdp, onChange) {
+    const inFlight = new Set();
+    const seen = new Set();
+    let lastActivity = Date.now();
+    const onStarted = (params) => {
+        inFlight.add(params.requestId);
+        seen.add(params.requestId);
+        lastActivity = Date.now();
+        onChange?.();
+    };
+    const onFinished = (params) => {
+        if (!inFlight.delete(params.requestId))
+            return;
+        lastActivity = Date.now();
+        onChange?.();
+    };
+    const cleanups = [
+        cdp.on('Network.requestWillBeSent', onStarted),
+        cdp.on('Network.loadingFinished', onFinished),
+        cdp.on('Network.loadingFailed', onFinished),
+    ];
+    return {
+        get count() {
+            return inFlight.size;
+        },
+        get started() {
+            return seen.size;
+        },
+        get lastActivity() {
+            return lastActivity;
+        },
+        dispose: () => cleanups.forEach((cleanup) => cleanup()),
+    };
+}
+//# sourceMappingURL=inFlightRequests.js.map

package/dist/connection/launcher/binaryResolver.js

@@ -5,9 +5,7 @@
  * and validates that the binary exists and is executable.
  */
 import * as fs from 'fs';
-import { getFormattedDiagnostics } from '../../connection/diagnostics.js';
-import { ChromeLaunchError } from '../../connection/errors.js';
-import { chromeBinaryOverrideNotFound, chromeBinaryOverrideNotExecutable, chromeBinaryOverrideIsDirectory, } from '../../ui/messages/chrome.js';
+import { ChromeLaunchError } from '../errors.js';
 import { getErrorMessage } from '../../utils/errors.js';
 /**
  * Resolve Chrome binary path from options or environment variable.
@@ -45,13 +43,22 @@ export function resolveChromeBinary(options) {
     }
     const sourceLabel = options.chromePath ? 'chromePath option' : 'CHROME_PATH';
     if (!fs.existsSync(chromePath)) {
-        const diagnostics = getFormattedDiagnostics();
-        throw new ChromeLaunchError(`${chromeBinaryOverrideNotFound(chromePath, sourceLabel)}\n\n${diagnostics.join('\n')}`);
+        throw new ChromeLaunchError(`Chrome binary override (${sourceLabel}) points to "${chromePath}", but that file does not exist.`, {
+            issue: {
+                code: 'CHROME_BINARY_NOT_FOUND',
+                context: { chromePath, source: sourceLabel },
+            },
+        });
     }
     try {
         const stats = fs.statSync(chromePath);
         if (stats.isDirectory()) {
-            throw new ChromeLaunchError(chromeBinaryOverrideIsDirectory(chromePath, sourceLabel));
+            throw new ChromeLaunchError(`Chrome binary override (${sourceLabel}) points to "${chromePath}", which is a directory.`, {
+                issue: {
+                    code: 'CHROME_BINARY_IS_DIRECTORY',
+                    context: { chromePath, source: sourceLabel },
+                },
+            });
         }
         fs.accessSync(chromePath, fs.constants.X_OK);
     }
@@ -59,7 +66,13 @@ export function resolveChromeBinary(options) {
         if (error instanceof ChromeLaunchError) {
             throw error;
         }
-        throw new ChromeLaunchError(`${chromeBinaryOverrideNotExecutable(chromePath, sourceLabel)}\n\n${getErrorMessage(error)}`, error instanceof Error ? error : undefined);
+        throw new ChromeLaunchError(`Chrome binary override (${sourceLabel}) points to "${chromePath}", but it is not executable.`, {
+            ...(error instanceof Error && { cause: error }),
+            issue: {
+                code: 'CHROME_BINARY_NOT_EXECUTABLE',
+                context: { chromePath, source: sourceLabel, reason: getErrorMessage(error) },
+            },
+        });
     }
     return chromePath;
 }