browser-debugger-cli 0.15.0 → 0.16.0

package/dist/commands/shared/startHelpers.js

@@ -5,11 +5,12 @@
  * Handles IPC communication with daemon to start browser sessions.
  */
 import { timeoutError } from './CommandRunner.js';
+import { interruptExitCode, interruptSignal, } from './interrupt.js';
 import { landingPage } from './landingPage.js';
 import { DaemonError, SessionDirError } from '../../daemon/errors.js';
 import { launchDaemon } from '../../daemon/launcher.js';
 import { LAUNCHED_CHROME_DESCRIPTION, sessionAlreadyRunningError, alreadyRunningSuggestion, sessionTargetMismatchError, daemonNotRunningError, invalidResponseError, genericError, } from '../../errors/messages.js';
-import { startSession as sendStartSessionRequest } from '../../ipc/client.js';
+import { startSession as sendStartSessionRequest, stopSession as sendStopSessionRequest, } from '../../ipc/client.js';
 import { IPCErrorCode, } from '../../ipc/index.js';
 import { IPCTimeoutError } from '../../ipc/transport/index.js';
 import { isConnectionError } from '../../ipc/utils/errors.js';
@@ -24,12 +25,14 @@ import { getExitCodeForIPCError } from '../../utils/errorMapping.js';
 import { getErrorMessage } from '../../utils/errors.js';
 import { EXIT_CODES } from '../../utils/exitCodes.js';
 import { filterDefined } from '../../utils/objects.js';
+import { isProcessAlive } from '../../utils/process.js';
 const log = createLogger('bdg');
 /** How long a failed start waits for the daemons it spawned to exit */
 export const SPAWNED_DAEMON_EXIT_WAIT_MS = 3000;
 const DEFAULT_START_DEPS = {
     launch: launchDaemon,
     send: sendStartSessionRequest,
+    stop: sendStopSessionRequest,
     exitWaitMs: SPAWNED_DAEMON_EXIT_WAIT_MS,
 };
 /**
@@ -38,30 +41,55 @@ const DEFAULT_START_DEPS = {
  * Spawns the daemon if needed, sends `start_session_request`, then prints the
  * result as a JSON envelope (`--json`) or human-readable text, and exits.
  *
+ * Ctrl-C (or SIGTERM) cancels the start at any point until the outcome is
+ * printed: the connection is closed, so the daemon abandons the session (a
+ * daemon spawned but not yet asked is told to shut down, a session that has
+ * just started is stopped), and the command exits with 130 (143) once the
+ * daemon it spawned has exited (bounded, like a failed start), so a command
+ * run right after sees no session. A second signal exits at once.
+ *
+ * Race-free: {@link attemptStart} checks the interrupt last, synchronously,
+ * and only microtasks run between that check and the exit in
+ * {@link reportStartOutcome}; a signal handler runs as a macrotask, so a
+ * signal either lands before the check (the start is cancelled) or after the
+ * outcome has been printed.
+ *
  * @param url - Target URL to navigate to
  * @param options - Session configuration options
  * @param telemetry - Array of telemetry types to enable
  */
 export async function startSessionViaDaemon(url, options, telemetry) {
-    process.once('SIGINT', () => reportStartOutcome(interruptedOutcome('SIGINT'), options));
-    process.once('SIGTERM', () => reportStartOutcome(interruptedOutcome('SIGTERM'), options));
-    reportStartOutcome(await attemptStart(url, options, telemetry), options);
+    const interrupt = new AbortController();
+    for (const signal of ['SIGINT', 'SIGTERM']) {
+        process.on(signal, () => {
+            if (interrupt.signal.aborted)
+                reportStartOutcome(interruptedOutcome(signal), options);
+            interrupt.abort(signal);
+        });
+    }
+    reportStartOutcome(await attemptStart(url, options, telemetry, DEFAULT_START_DEPS, interrupt.signal), options);
 }
 /**
  * Start a session, retrying while the previous session shuts down. After a
  * failure the daemon reported (or a dropped connection), it waits for every
  * daemon the attempts spawned to exit ({@link afterSpawnedDaemonExit}).
  *
+ * An interrupt cancels the start whenever it arrives: a start that succeeded
+ * meanwhile is stopped ({@link cancelStartedSession}), and a failure keeps its
+ * message but exits 130 (143), also when the signal came during the wait.
+ *
  * @param url - Target URL
  * @param options - Session options
  * @param telemetry - Telemetry types
  * @param deps - How to reach the daemon (tests replace it)
- * @returns Start outcome, ready to report
+ * @param interrupt - Aborted (reason: the signal) on Ctrl-C or SIGTERM: the
+ *   start is cancelled and the daemon it spawned waited for like after a failure
+ * @returns Start outcome, ready to report (the interrupt is checked last)
  */
-export async function attemptStart(url, options, telemetry, deps = DEFAULT_START_DEPS) {
+export async function attemptStart(url, options, telemetry, deps = DEFAULT_START_DEPS, interrupt) {
     const spawned = [];
     const attempt = async () => {
-        const outcome = await requestSession(url, options, telemetry, deps);
+        const outcome = await requestSession(url, options, telemetry, deps, interrupt);
         if (!outcome.ok && outcome.spawned)
             spawned.push(outcome.spawned);
         return outcome;
@@ -69,10 +97,69 @@ export async function attemptStart(url, options, telemetry, deps = DEFAULT_START
     let outcome = await attempt();
     const deadline = Date.now() + SHUTDOWN_WAIT_MS;
     while (isShuttingDown(outcome) && Date.now() < deadline) {
-        await delay(SHUTDOWN_POLL_MS);
+        await delay(SHUTDOWN_POLL_MS, interrupt);
         outcome = await attempt();
     }
-    return afterSpawnedDaemonExit(outcome, spawned, deps.exitWaitMs);
+    return settleOutcome(outcome, spawned, deps, interrupt);
+}
+/**
+ * Settle the last attempt's outcome: a success is returned as is, or stopped
+ * when interrupted; a failure waits for the daemons the attempts spawned and
+ * takes the signal's exit code when interrupted.
+ *
+ * Race-free: for a success the interrupt is checked last, with no await
+ * between the check and the return (see {@link startSessionViaDaemon}).
+ *
+ * @param outcome - The last attempt's outcome
+ * @param spawned - Exiting daemons the attempts spawned
+ * @param deps - How to reach the daemon
+ * @param interrupt - Aborted on Ctrl-C or SIGTERM
+ * @returns Start outcome, ready to report
+ */
+async function settleOutcome(outcome, spawned, deps, interrupt) {
+    if (outcome.ok) {
+        const { spawned: daemon, ...started } = outcome;
+        return interrupt?.aborted
+            ? cancelStartedSession(started.data, daemon, deps, interrupt)
+            : started;
+    }
+    const failure = await afterSpawnedDaemonExit(outcome, spawned, deps.exitWaitMs);
+    return interrupt?.aborted ? withInterruptExitCode(failure, interrupt) : failure;
+}
+/**
+ * Cancel a start that succeeded after Ctrl-C (the response came before the
+ * interrupt closed the connection): the session is stopped, since nobody
+ * learns that it exists, and its daemon waited for like after a failure.
+ *
+ * @param data - The started session
+ * @param spawned - The daemon this attempt spawned, if any
+ * @param deps - How to reach the daemon
+ * @param interrupt - The aborted interrupt
+ * @returns The cancelled outcome (130, or 143 for SIGTERM)
+ */
+function cancelStartedSession(data, spawned, deps, interrupt) {
+    log.debug('Interrupted as the session started; stopping it');
+    deps.stop().catch((error) => {
+        log.debug(`Stopping the interrupted session failed: ${getErrorMessage(error)}`);
+    });
+    const daemon = spawned ?? {
+        pid: data.daemonPid,
+        hasExited: () => !isProcessAlive(data.daemonPid),
+    };
+    return afterSpawnedDaemonExit(cancelledOutcome(interrupt), [daemon], deps.exitWaitMs);
+}
+/**
+ * A failed start that was also interrupted: its message is kept (it says what
+ * went wrong), its exit code is the signal's.
+ *
+ * @param outcome - Failed start outcome
+ * @param interrupt - The aborted interrupt
+ * @returns The outcome exiting with 130 (143 for SIGTERM)
+ */
+function withInterruptExitCode(outcome, interrupt) {
+    return outcome.ok
+        ? outcome
+        : { ...outcome, exitCode: interruptExitCode(interruptSignal(interrupt)) };
 }
 /**
  * Let the daemons a failed start spawned finish exiting before the error is
@@ -110,16 +197,24 @@ export async function afterSpawnedDaemonExit(outcome, spawned, waitMs) {
     };
 }
 /**
- * The outcome of a start interrupted with Ctrl-C (the daemon notices the
- * closed connection and cancels the start).
+ * The outcome of a start interrupted with Ctrl-C or SIGTERM (the daemon
+ * notices the closed connection and cancels the start).
  *
  * @param signal - The signal that stopped the start
- * @returns Failed start outcome (exit 130)
+ * @returns Failed start outcome (exit 130 or 143)
  */
 function interruptedOutcome(signal) {
     const message = `Start cancelled (${signal === 'SIGINT' ? 'interrupted' : 'terminated'})`;
-    const exitCode = signal === 'SIGINT' ? EXIT_CODES.INTERRUPTED : EXIT_CODES.TERMINATED;
-    return { ok: false, error: message, human: message, exitCode };
+    return { ok: false, error: message, human: message, exitCode: interruptExitCode(signal) };
+}
+/**
+ * The outcome for a start whose interrupt signal has aborted.
+ *
+ * @param interrupt - Aborted interrupt signal (reason: the signal name)
+ * @returns Failed start outcome (exit 130, or 143 for SIGTERM)
+ */
+function cancelledOutcome(interrupt) {
+    return interruptedOutcome(interruptSignal(interrupt));
 }
 /** How long a new start waits for the previous session to finish shutting down */
 const SHUTDOWN_WAIT_MS = 15000;
@@ -144,9 +239,15 @@ function isShuttingDown(outcome) {
  * @param url - Target URL
  * @param options - Session options
  * @param telemetry - Telemetry types
- * @returns Start outcome
+ * @param deps - How to reach the daemon
+ * @param interrupt - Cancels the start when aborted
+ * @returns Start outcome, with the daemon it spawned for a started session or
+ *   an exiting daemon; interrupted before the request was sent, a daemon it
+ *   spawned is told to shut down (it hosts nothing) and waited for
  */
-async function requestSession(url, options, telemetry, deps) {
+async function requestSession(url, options, telemetry, deps, interrupt) {
+    if (interrupt?.aborted)
+        return cancelledOutcome(interrupt);
     let spawned;
     try {
         spawned = await deps.launch();
@@ -165,8 +266,25 @@ async function requestSession(url, options, telemetry, deps) {
         const exitCode = error instanceof DaemonError ? error.exitCode : EXIT_CODES.SOFTWARE_ERROR;
         return { ok: false, error: message, human: genericError(message), exitCode };
     }
-    const outcome = await sendStart(url, options, telemetry, deps.send);
-    return !outcome.ok && outcome.daemonExiting && spawned ? { ...outcome, spawned } : outcome;
+    if (interrupt?.aborted)
+        return cancelBeforeRequest(spawned, interrupt);
+    const outcome = await sendStart(url, options, telemetry, deps.send, interrupt);
+    return spawned && (outcome.ok || outcome.daemonExiting) ? { ...outcome, spawned } : outcome;
+}
+/**
+ * Cancel a start interrupted while its daemon was being spawned: the daemon
+ * would otherwise sit idle (and answer) until its idle timeout, so it is told
+ * to shut down and waited for like after a failure.
+ *
+ * @param spawned - The daemon this attempt spawned (undefined: one was already running)
+ * @param interrupt - The aborted interrupt
+ * @returns The cancelled outcome
+ */
+function cancelBeforeRequest(spawned, interrupt) {
+    if (!spawned)
+        return cancelledOutcome(interrupt);
+    spawned.stop();
+    return { ...cancelledOutcome(interrupt), daemonExiting: true, spawned };
 }
 /**
  * Ask the running daemon to start a session.
@@ -175,11 +293,13 @@ async function requestSession(url, options, telemetry, deps) {
  * @param options - Session options
  * @param telemetry - Telemetry types
  * @param send - Sends the request
- * @returns Start outcome; `daemonExiting` for a failure the daemon reported
- *   or a dropped connection, not for a timeout or an unexpected error (the
- *   daemon may still be starting the session then)
+ * @param interrupt - Cancels the request when aborted
+ * @returns Start outcome; `daemonExiting` for a failure the daemon reported,
+ *   a dropped connection or a cancelled start (the daemon abandons it), not
+ *   for a timeout or an unexpected error (the daemon may still be starting
+ *   the session then)
  */
-async function sendStart(url, options, telemetry, send) {
+async function sendStart(url, options, telemetry, send, interrupt) {
     try {
         log.debug('Connecting to daemon...');
         const response = await send(url, filterDefined({
@@ -194,7 +314,7 @@ async function sendStart(url, options, telemetry, send) {
             chromeFlags: options.chromeFlags,
             viewport: options.viewport,
             colorScheme: options.colorScheme,
-        }));
+        }), interrupt);
         if (response.status === 'error') {
             return { ...describeStartFailure(response, options), daemonExiting: true };
         }
@@ -210,6 +330,8 @@ async function sendStart(url, options, telemetry, send) {
         return { ok: true, data: response.data };
     }
     catch (error) {
+        if (interrupt?.aborted)
+            return { ...cancelledOutcome(interrupt), daemonExiting: true };
         if (error instanceof IPCTimeoutError) {
             const timeout = timeoutError(error);
             return {

package/dist/commands/types.d.ts

@@ -36,6 +36,11 @@ export interface CleanupResult {
     };
     /** Directory deleted by `--purge` */
     purged?: string;
+    /** Downloaded files cleanup left in place (not with `--purge`) */
+    downloadsKept?: {
+        dir: string;
+        files: number;
+    };
     message: string;
     warnings?: string[];
 }

package/dist/connection/cdp.js

@@ -1,4 +1,3 @@
-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';
@@ -16,20 +15,6 @@ 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})`;
@@ -130,7 +115,7 @@ 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 abortableDelay(delay, options.signal);
+                    await asyncDelay(delay, options.signal);
                 }
             }
         }

package/dist/connection/chromeIdentity.d.ts

@@ -17,6 +17,7 @@
  * 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 { ChromeLaunchError } from './errors.js';
 import { type StartupLogs } from './startupExit.js';
 /**
  * The debugging endpoint a Chrome announced for itself.
@@ -42,9 +43,24 @@ export declare function parseDevToolsListening(lines: readonly string[]): DevToo
  * @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
+ * @param signal - Ends the wait early when aborted
+ * @returns Endpoint, or null if Chrome exited, announced none in time or the
+ *   wait was aborted
  */
-export declare function waitForDevToolsEndpoint(logs: StartupLogs, isRunning: () => boolean, timeoutMs?: number): Promise<DevToolsEndpoint | null>;
+export declare function waitForDevToolsEndpoint(logs: StartupLogs, isRunning: () => boolean, timeoutMs?: number, signal?: AbortSignal): Promise<DevToolsEndpoint | null>;
+/**
+ * The error for a launch that was aborted (the session was stopped).
+ *
+ * @returns Launch error
+ */
+export declare function launchAbortedError(): ChromeLaunchError;
+/**
+ * End a launch whose session was stopped.
+ *
+ * @param signal - The launch's abort signal
+ * @throws ChromeLaunchError if the signal is aborted
+ */
+export declare function throwIfLaunchAborted(signal: AbortSignal | undefined): void;
 /**
  * Check that the Chrome answering on 127.0.0.1:<port> is the one just
  * launched, so bdg never drives another session's browser.
@@ -55,9 +71,11 @@ export declare function waitForDevToolsEndpoint(logs: StartupLogs, isRunning: ()
  * that fell back to [::1] is asked once: 127.0.0.1 is held by something else.
  *
  * @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 and its answer
- * @throws ChromeLaunchError: CHROME_DIED_AFTER_LAUNCH if Chrome exits first;
+ *   port (free on 127.0.0.1 and ::1 right before the launch), Chrome's PID,
+ *   longest wait for its announcement and its answer, and a signal that ends
+ *   the waits and a pending request at once (the session was stopped)
+ * @throws ChromeLaunchError: without an issue if `signal` aborts;
+ *   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, or
  *   announced the port but did not answer on it in time
@@ -67,5 +85,6 @@ export declare function verifyLaunchedChrome(options: {
     port: number;
     pid: number;
     timeoutMs?: number;
+    signal?: AbortSignal | undefined;
 }): Promise<void>;
 //# sourceMappingURL=chromeIdentity.d.ts.map

package/dist/connection/chromeIdentity.js

@@ -18,7 +18,7 @@
  * before the launch, and a second listener is how a conflict shows.
  */
 import { createLogger } from '../ui/logging/index.js';
-import { chromeNotAnsweringReason, portTakenByReason } from '../ui/messages/chrome.js';
+import { CHROME_LAUNCH_ABORTED_MESSAGE, chromeNotAnsweringReason, portTakenByReason, } from '../ui/messages/chrome.js';
 import { delay } from '../utils/async.js';
 import { CDP_HTTP_TIMEOUT_MS, fetchBrowserWsUrl, probeDevToolsEndpoint, } from '../utils/http.js';
 import { isProcessAlive } from '../utils/process.js';
@@ -63,17 +63,37 @@ export function parseDevToolsListening(lines) {
  * @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
+ * @param signal - Ends the wait early when aborted
+ * @returns Endpoint, or null if Chrome exited, announced none in time or the
+ *   wait was aborted
  */
-export async function waitForDevToolsEndpoint(logs, isRunning, timeoutMs = ENDPOINT_WAIT_MS) {
+export async function waitForDevToolsEndpoint(logs, isRunning, timeoutMs = ENDPOINT_WAIT_MS, signal) {
     const deadline = Date.now() + timeoutMs;
     for (;;) {
         const endpoint = parseDevToolsListening(readStartupLines(logs));
-        if (endpoint || !isRunning() || Date.now() >= deadline)
+        if (endpoint || !isRunning() || Date.now() >= deadline || signal?.aborted)
             return endpoint;
-        await delay(ENDPOINT_POLL_MS);
+        await delay(ENDPOINT_POLL_MS, signal);
     }
 }
+/**
+ * The error for a launch that was aborted (the session was stopped).
+ *
+ * @returns Launch error
+ */
+export function launchAbortedError() {
+    return new ChromeLaunchError(CHROME_LAUNCH_ABORTED_MESSAGE);
+}
+/**
+ * End a launch whose session was stopped.
+ *
+ * @param signal - The launch's abort signal
+ * @throws ChromeLaunchError if the signal is aborted
+ */
+export function throwIfLaunchAborted(signal) {
+    if (signal?.aborted)
+        throw launchAbortedError();
+}
 /**
  * Check that the Chrome answering on 127.0.0.1:<port> is the one just
  * launched, so bdg never drives another session's browser.
@@ -84,28 +104,32 @@ export async function waitForDevToolsEndpoint(logs, isRunning, timeoutMs = ENDPO
  * that fell back to [::1] is asked once: 127.0.0.1 is held by something else.
  *
  * @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 and its answer
- * @throws ChromeLaunchError: CHROME_DIED_AFTER_LAUNCH if Chrome exits first;
+ *   port (free on 127.0.0.1 and ::1 right before the launch), Chrome's PID,
+ *   longest wait for its announcement and its answer, and a signal that ends
+ *   the waits and a pending request at once (the session was stopped)
+ * @throws ChromeLaunchError: without an issue if `signal` aborts;
+ *   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, or
  *   announced the port but did not answer on it in time
  */
 export async function verifyLaunchedChrome(options) {
-    const { logs, port, pid, timeoutMs = ENDPOINT_WAIT_MS } = options;
+    const { logs, port, pid, timeoutMs = ENDPOINT_WAIT_MS, signal } = options;
     const started = Date.now();
     const isRunning = () => isProcessAlive(pid);
-    const endpoint = await waitForDevToolsEndpoint(logs, isRunning, timeoutMs);
+    const endpoint = await waitForDevToolsEndpoint(logs, isRunning, timeoutMs, signal);
+    throwIfLaunchAborted(signal);
     if (!endpoint && !isRunning())
         throw diedError(port, pid);
     if (!endpoint)
-        return acceptUnannouncedChrome(logs, port);
+        return acceptUnannouncedChrome(logs, port, signal);
     if (endpoint.port !== port) {
         throw portTakenError(port, `Chrome listens on port ${endpoint.port} instead`);
     }
     const onLoopback = endpoint.host === '127.0.0.1';
     const deadline = onLoopback ? started + timeoutMs : Date.now();
-    const answer = await waitForAnswer(port, deadline, isRunning);
+    const answer = await waitForAnswer(port, deadline, isRunning, signal);
+    throwIfLaunchAborted(signal);
     if (answer.kind === 'devtools' && new URL(answer.wsUrl).pathname === endpoint.browserPath) {
         log.debug(`Chrome on port ${port} is the launched one (${endpoint.browserPath})`);
         return;
@@ -119,22 +143,25 @@ export async function verifyLaunchedChrome(options) {
 }
 /**
  * Ask 127.0.0.1:<port> for its DevTools version until something answers,
- * Chrome exits or the deadline passes (at least once). Each request waits at
- * most until the deadline (but at least MIN_ANSWER_WAIT_MS).
+ * Chrome exits, the deadline passes (at least once) or `signal` aborts (which
+ * also ends a pending request). Each request waits at most until the deadline
+ * (but at least MIN_ANSWER_WAIT_MS).
  *
  * @param port - Requested port
  * @param deadline - Time (ms since epoch) to stop asking
  * @param isRunning - Whether Chrome is still running
+ * @param signal - Ends the wait early when aborted
  * @returns The first answer, or the last `unreachable` result
  */
-async function waitForAnswer(port, deadline, isRunning) {
+async function waitForAnswer(port, deadline, isRunning, signal) {
     for (;;) {
         const remaining = Math.max(deadline - Date.now(), MIN_ANSWER_WAIT_MS);
         const timeoutMs = Math.min(CDP_HTTP_TIMEOUT_MS, remaining);
-        const answer = await probeDevToolsEndpoint(port, undefined, { timeoutMs });
-        if (answer.kind !== 'unreachable' || !isRunning() || Date.now() >= deadline)
+        const answer = await probeDevToolsEndpoint(port, undefined, { timeoutMs, signal });
+        const done = answer.kind !== 'unreachable' || !isRunning() || Date.now() >= deadline;
+        if (done || signal?.aborted)
             return answer;
-        await delay(ENDPOINT_POLL_MS);
+        await delay(ENDPOINT_POLL_MS, signal);
     }
 }
 /**
@@ -155,13 +182,17 @@ function answerSource(answer) {
  *
  * @param logs - Chrome's log positions (the stderr log is named in messages)
  * @param port - Requested port
- * @throws ChromeLaunchError: PORT_IN_USE for a second listener;
- *   CHROME_LAUNCH_FAILED if no browser answers
+ * @param signal - Ends the request early when aborted
+ * @throws ChromeLaunchError: without an issue if `signal` aborts;
+ *   PORT_IN_USE for a second listener; CHROME_LAUNCH_FAILED if no browser
+ *   answers
  */
-async function acceptUnannouncedChrome(logs, port) {
+async function acceptUnannouncedChrome(logs, port, signal) {
     const errLog = logs.files[0]?.file ?? 'chrome-err.log';
     const missing = `Chrome did not print "DevTools listening on" to ${errLog}`;
-    if (!(await fetchBrowserWsUrl(port, log))) {
+    const browserWsUrl = await fetchBrowserWsUrl(port, log, { signal });
+    throwIfLaunchAborted(signal);
+    if (!browserWsUrl) {
         throw new ChromeLaunchError(`${missing}, and no browser answers on port ${port}`, {
             issue: {
                 code: 'CHROME_LAUNCH_FAILED',

package/dist/connection/launcher.d.ts

@@ -1,5 +1,6 @@
 import type { LaunchedChrome, Logger } from './types.js';
 import type { Options as ChromeLaunchOptions } from 'chrome-launcher';
+import { ChromeLaunchError } from './errors.js';
 /**
  * Options that control how Chrome is launched for CDP sessions.
  * Extended to support chrome-launcher advanced features.
@@ -29,6 +30,11 @@ export interface LaunchOptions extends Pick<ChromeLaunchOptions, 'logLevel' | 'c
     chromePath?: string;
     /** bdg session directory: recorded as a marker flag on the Chrome command line, and holds the default profile */
     sessionDir?: string | undefined;
+    /**
+     * Ends the launch when aborted (the session was stopped): bdg stops waiting
+     * and kills Chrome as soon as chrome-launcher has spawned it
+     */
+    signal?: AbortSignal | undefined;
 }
 /**
  * Launch Chrome with remote debugging enabled using chrome-launcher.
@@ -42,7 +48,7 @@ export interface LaunchOptions extends Pick<ChromeLaunchOptions, 'logLevel' | 'c
  *
  * @param options - Launch configuration options
  * @returns LaunchedChrome instance with PID and kill method
- * @throws ChromeLaunchError if Chrome fails to launch, process dies immediately, or CDP doesn't become available
+ * @throws ChromeLaunchError if Chrome fails to launch, process dies immediately, CDP doesn't become available, or `options.signal` aborts
  * @throws Error if user data directory cannot be created
  *
  * @remarks
@@ -50,6 +56,32 @@ export interface LaunchOptions extends Pick<ChromeLaunchOptions, 'logLevel' | 'c
  * Uses chrome-launcher for cross-platform Chrome detection and launching.
  */
 export declare function launchChrome(options?: LaunchOptions): Promise<LaunchedChrome>;
+/**
+ * State of the launch when chrome-launcher rejected.
+ */
+interface LaunchFailureContext {
+    /** Debugging port */
+    port: number;
+    /** Chrome's PID (0 if it was not spawned) */
+    pid: number;
+    /** Whether Chrome was still running when chrome-launcher rejected */
+    chromeAlive: boolean;
+    /** How long chrome-launcher waited for the port to open */
+    readyBudgetMs: number;
+}
+/**
+ * The error for a launch chrome-launcher rejected.
+ *
+ * A refused connection while Chrome is still running means Chrome did not
+ * open its port within the readiness budget (a slow start, e.g. the first
+ * one on a cold machine): the port was free right before the launch and
+ * nothing answers on it, so it is not a conflict, and Chrome did not crash.
+ *
+ * @param error - chrome-launcher's rejection
+ * @param context - Port, Chrome's PID and liveness, and the readiness budget
+ * @returns CHROME_PORT_NOT_OPENED for a slow start, else CHROME_LAUNCH_FAILED
+ */
+export declare function launchFailedError(error: unknown, { port, pid, chromeAlive, readyBudgetMs }: LaunchFailureContext): ChromeLaunchError;
 /**
  * Preferences for the launched profile: bdg's defaults (no translate prompt,
  * no password manager or leak check, whose bubbles capture input) for
@@ -65,4 +97,5 @@ export declare function launchChrome(options?: LaunchOptions): Promise<LaunchedC
  * @throws ChromeLaunchError if prefs file cannot be read or parsed, or prefs are not JSON
  */
 export declare function resolveChromePrefs(options: LaunchOptions): Record<string, unknown>;
+export {};
 //# sourceMappingURL=launcher.d.ts.map