browser-debugger-cli 0.12.0 → 0.14.0

package/dist/commands/shared/daemonErrorHandler.js

@@ -3,8 +3,8 @@
  */
 import { sessionUnavailableSuggestion } from '../../errors/messages.js';
 import { genericError } from '../../errors/messages.js';
-import { OutputBuilder } from '../../ui/OutputBuilder.js';
-import { connectionLostRetryMessage, connectionLostStopHintMessage, } from '../../ui/messages/preview.js';
+import { OutputBuilder, stringifyEnvelope } from '../../ui/OutputBuilder.js';
+import { connectionLostRetryMessage, connectionLostStopHintMessage, followedSessionEndedMessage, } from '../../ui/messages/preview.js';
 import { EXIT_CODES } from '../../utils/exitCodes.js';
 /** Follow-mode state: whether a session ever answered, and whether its loss was reported */
 const followState = { connected: false, lossReported: false };
@@ -20,8 +20,11 @@ export function noteFollowConnected() {
  * Handle daemon connection errors with consistent formatting and behavior.
  *
  * Outside follow mode the command exits. In follow mode, a session that never
- * answered exits too (there is nothing to follow, exit 83); a session that
- * goes away is reported once and retried until a new one starts.
+ * answered exits too (there is nothing to follow, exit 83), and so does one
+ * that ends while followed (no session any more, exit 83), so a follower
+ * running in the background finds out. Other failures (a busy page, a
+ * timeout) are retried: reported once in text, and on every failed refresh
+ * in JSON, one object per line.
  *
  * @param error - Error message to display
  * @param options - Error handling options
@@ -29,22 +32,30 @@ export function noteFollowConnected() {
  */
 export function handleDaemonConnectionError(error, options) {
     const { json = false, follow = false, retryIntervalMs = 1000, exitCode = EXIT_CODES.RESOURCE_NOT_FOUND, } = options;
-    const exits = !follow || !followState.connected;
-    if (exits || !followState.lossReported) {
+    const sessionGone = exitCode === EXIT_CODES.RESOURCE_NOT_FOUND;
+    const exits = !follow || !followState.connected || sessionGone;
+    const message = follow && followState.connected && sessionGone ? followedSessionEndedMessage() : error;
+    if (exits || json || !followState.lossReported) {
         if (json) {
             const suggestion = exits ? sessionUnavailableSuggestion(exitCode) : undefined;
-            console.log(JSON.stringify(OutputBuilder.buildJsonError(error, { exitCode, ...(suggestion && { suggestion }) }), null, 2));
+            const envelope = OutputBuilder.buildJsonError(message, {
+                exitCode,
+                ...(suggestion && { suggestion }),
+            });
+            console.log(follow ? JSON.stringify(envelope) : stringifyEnvelope(envelope));
         }
         else {
-            console.error(genericError(error));
+            console.error(genericError(message));
         }
     }
     if (exits)
         return { shouldExit: true, exitCode };
     if (!followState.lossReported) {
         const retryMessage = retryIntervalMs >= 1000 ? `${retryIntervalMs / 1000}s` : `${retryIntervalMs}ms`;
-        console.error(connectionLostRetryMessage(new Date().toISOString(), retryMessage));
-        console.error(connectionLostStopHintMessage());
+        if (!json) {
+            console.error(connectionLostRetryMessage(new Date().toISOString(), retryMessage));
+            console.error(connectionLostStopHintMessage());
+        }
         followState.lossReported = true;
     }
     return { shouldExit: false };

package/dist/commands/shared/dataFetcher.d.ts

@@ -3,6 +3,7 @@
  */
 import type { PeekSection } from '../../ipc/protocol/commands.js';
 import type { BdgOutput, ConsoleMessage, NetworkRequest } from '../../types.js';
+import type { NetworkEvictionCounts } from '../../ui/messages/networkMessages.js';
 export type FetchSuccess<T> = {
     success: true;
     data: T;
@@ -47,18 +48,27 @@ export declare function fetchPreviewData(query?: PreviewQuery): Promise<FetchRes
  * Fetch all captured network requests from daemon.
  *
  * @param withHeaders - Include request/response headers (needed by header filters)
- * @returns Requests or a fetch error
+ * @returns Requests, when the page crashed (while it is not loaded again)
+ *   and what the session let go at its capture limits, or a fetch error
  */
-export declare function fetchNetworkRequests(withHeaders?: boolean): Promise<FetchResult<NetworkRequest[]>>;
+export declare function fetchNetworkRequests(withHeaders?: boolean): Promise<FetchResult<{
+    requests: NetworkRequest[];
+    pageCrashedAt: number | undefined;
+    evictions: NetworkEvictionCounts;
+}>>;
 /**
  * Fetch all console messages from daemon.
  *
- * @returns Messages (with their session-wide index) and the navigation id of
- *   the page currently loaded
+ * @returns Messages (with their session-wide index), the navigation id of
+ *   the page currently loaded, how many of the oldest messages the session
+ *   dropped at its limit and when the page crashed (while it is not loaded
+ *   again)
  */
 export declare function fetchConsoleMessages(): Promise<FetchResult<{
     messages: ConsoleMessage[];
     currentNavigationId: number | undefined;
+    dropped: number;
+    pageCrashedAt: number | undefined;
 }>>;
 interface ErrorResult {
     success: false;

package/dist/commands/shared/dataFetcher.js

@@ -90,19 +90,33 @@ export async function fetchPreviewData(query = {}) {
  * Fetch all captured network requests from daemon.
  *
  * @param withHeaders - Include request/response headers (needed by header filters)
- * @returns Requests or a fetch error
+ * @returns Requests, when the page crashed (while it is not loaded again)
+ *   and what the session let go at its capture limits, or a fetch error
  */
 export async function fetchNetworkRequests(withHeaders = false) {
     const result = await fetchPreviewData({ lastN: 0, only: 'network', withHeaders });
     if (!result.success)
         return result;
-    return { success: true, data: result.data.network };
+    const { totals, pageCrashedAt } = result.data.output;
+    return {
+        success: true,
+        data: {
+            requests: result.data.network,
+            pageCrashedAt,
+            evictions: {
+                requestsDropped: totals?.networkDropped ?? 0,
+                bodiesEvicted: totals?.networkBodiesEvicted ?? 0,
+            },
+        },
+    };
 }
 /**
  * Fetch all console messages from daemon.
  *
- * @returns Messages (with their session-wide index) and the navigation id of
- *   the page currently loaded
+ * @returns Messages (with their session-wide index), the navigation id of
+ *   the page currently loaded, how many of the oldest messages the session
+ *   dropped at its limit and when the page crashed (while it is not loaded
+ *   again)
  */
 export async function fetchConsoleMessages() {
     const result = await fetchPreviewData({ lastN: 0, only: 'console' });
@@ -113,6 +127,8 @@ export async function fetchConsoleMessages() {
         data: {
             messages: result.data.console,
             currentNavigationId: result.data.output.currentNavigationId,
+            dropped: result.data.output.totals?.consoleDropped ?? 0,
+            pageCrashedAt: result.data.output.pageCrashedAt,
         },
     };
 }

package/dist/commands/shared/followMode.d.ts

@@ -23,6 +23,14 @@ export declare function followFetchFailure(failure: {
     json?: boolean | undefined;
     retryIntervalMs: number;
 }): FollowPoll;
+/**
+ * Report each page crash of a stream once: a page loaded again that crashes
+ * again is a new crash.
+ *
+ * @returns Function taking the crash time a refresh fetched, returning it
+ *   when that crash was not reported yet
+ */
+export declare function newPageCrashes(): (crashedAt: number | undefined) => number | undefined;
 /**
  * Options for configuring follow mode behavior.
  */
@@ -42,7 +50,7 @@ export interface FollowModeOptions {
  * - Initial display of start message
  * - First refresh call (awaited)
  * - Periodic interval-based refresh
- * - SIGINT handler for graceful shutdown
+ * - SIGINT/SIGTERM handlers that stop with 130/143, as shells expect
  * - Stopping with the exit code a refresh returns (e.g. the session is gone)
  *
  * @param refreshFn - Async function to call on each refresh cycle

package/dist/commands/shared/followMode.js

@@ -27,6 +27,22 @@ export function followFetchFailure(failure, options) {
         ? { exitCode: result.exitCode ?? EXIT_CODES.RESOURCE_NOT_FOUND }
         : undefined;
 }
+/**
+ * Report each page crash of a stream once: a page loaded again that crashes
+ * again is a new crash.
+ *
+ * @returns Function taking the crash time a refresh fetched, returning it
+ *   when that crash was not reported yet
+ */
+export function newPageCrashes() {
+    let reported;
+    return (crashedAt) => {
+        if (crashedAt === undefined || crashedAt === reported)
+            return undefined;
+        reported = crashedAt;
+        return crashedAt;
+    };
+}
 /**
  * Sets up follow mode with periodic refresh and graceful shutdown.
  *
@@ -35,7 +51,7 @@ export function followFetchFailure(failure, options) {
  * - Initial display of start message
  * - First refresh call (awaited)
  * - Periodic interval-based refresh
- * - SIGINT handler for graceful shutdown
+ * - SIGINT/SIGTERM handlers that stop with 130/143, as shells expect
  * - Stopping with the exit code a refresh returns (e.g. the session is gone)
  *
  * @param refreshFn - Async function to call on each refresh cycle
@@ -71,10 +87,12 @@ export async function setupFollowMode(refreshFn, options) {
             console.error(genericError(getErrorMessage(error)));
         });
     }, intervalMs);
-    process.on('SIGINT', () => {
+    const stop = (exitCode) => {
         clearInterval(intervalId);
         console.error(stopMessage());
-        process.exit(EXIT_CODES.SUCCESS);
-    });
+        process.exit(exitCode);
+    };
+    process.on('SIGINT', () => stop(EXIT_CODES.INTERRUPTED));
+    process.on('SIGTERM', () => stop(EXIT_CODES.TERMINATED));
 }
 //# sourceMappingURL=followMode.js.map

package/dist/commands/shared/handleValidationError.js

@@ -1,6 +1,6 @@
 import { CommandError } from '../../errors/index.js';
 import { genericError } from '../../errors/messages.js';
-import { OutputBuilder } from '../../ui/OutputBuilder.js';
+import { OutputBuilder, stringifyEnvelope } from '../../ui/OutputBuilder.js';
 import { escapeControlChars } from '../../ui/formatting.js';
 import { EXIT_CODES } from '../../utils/exitCodes.js';
 /**
@@ -24,7 +24,7 @@ export function handleValidationError(error, json) {
             if (error.metadata.suggestion) {
                 errorOptions.suggestion = error.metadata.suggestion;
             }
-            console.log(JSON.stringify(OutputBuilder.buildJsonError(error.message, errorOptions), null, 2));
+            console.log(stringifyEnvelope(OutputBuilder.buildJsonError(error.message, errorOptions)));
         }
         else {
             console.error(genericError(error.message));
@@ -38,7 +38,7 @@ export function handleValidationError(error, json) {
         const envelope = OutputBuilder.buildJsonError(message, {
             exitCode: EXIT_CODES.INVALID_ARGUMENTS,
         });
-        console.log(JSON.stringify(envelope, null, 2));
+        console.log(stringifyEnvelope(envelope));
     }
     else {
         console.error(genericError(message));

package/dist/commands/shared/optionTypes.d.ts

@@ -142,10 +142,13 @@ export type DetailsCommandOptions = BaseOptions & {
     id: string;
 };
 /** Options for DOM query command */
-export type DomQueryCommandOptions = BaseOptions;
+export type DomQueryCommandOptions = BaseOptions & {
+    /** Matches listed (0 = all); default 50, or 100 with --json */
+    limit?: number;
+};
 /** Options for DOM get command */
 export type DomGetCommandOptions = BaseOptions & RawOptions & SelectionOptions & {
-    /** All of the element's text instead of its first 500 characters (semantic output) */
+    /** All of the element's text (semantic output) or HTML (`--raw`), instead of its start */
     full?: boolean;
     /** Which match of the selector (0-based); `--nth` is its alias */
     index?: number;
@@ -156,6 +159,8 @@ export type DomScreenshotCommandOptions = BaseOptions & ScreenshotOptions;
 export interface DomEvalCommandOptions extends BaseOptions {
     /** Iframe to evaluate in: index, name/id attribute, or part of the name, id or URL */
     frame?: string;
+    /** The whole value instead of its first 20000 characters */
+    full?: boolean;
 }
 /** Options for DOM frames command */
 export type DomFramesCommandOptions = BaseOptions;
@@ -273,7 +278,12 @@ export interface WaitCommandOptions extends BaseOptions {
     timeout: number;
 }
 /** Options for A11y tree command */
-export type A11yTreeCommandOptions = BaseOptions;
+export interface A11yTreeCommandOptions extends BaseOptions {
+    /** Nodes to list (0 = all); default 50, also with --json */
+    limit?: number;
+    /** Levels below the root to list (0 = root only) */
+    depth?: number;
+}
 /** Options for A11y query command */
 export interface A11yQueryCommandOptions extends BaseOptions {
     /** Matches to list (0 = all) */
@@ -351,6 +361,8 @@ export interface ConsoleCommandOptions extends BaseOptions {
     history?: boolean;
     /** Filter by message level (error, warning, info, debug) */
     level?: ConsoleLevel;
+    /** Message texts whole instead of cut */
+    full?: boolean;
 }
 /**
  * Options for preview display.
@@ -377,6 +389,8 @@ export interface PeekCommandOptions extends BaseOptions, PreviewDisplayOptions {
     type?: string;
     /** Refresh interval of --follow in ms (string from CLI, default: 1000) */
     interval?: string;
+    /** Console message texts whole instead of cut */
+    full?: boolean;
 }
 /**
  * Options for tail command.

package/dist/commands/shared/outputFile.js

@@ -7,6 +7,7 @@ import * as path from 'path';
 import { CommandError } from '../../errors/index.js';
 import { emptyOutputPathError, outputFileError } from '../../errors/messages.js';
 import { AtomicFileWriter } from '../../utils/atomicFile.js';
+import { makeDirectory } from '../../utils/directories.js';
 import { EXIT_CODES } from '../../utils/exitCodes.js';
 /** What went wrong with a path, by error code */
 const PATH_PROBLEMS = {
@@ -19,6 +20,10 @@ const PATH_PROBLEMS = {
     ENAMETOOLONG: { reason: 'the name is too long', exitCode: EXIT_CODES.INVALID_ARGUMENTS },
     ENOENT: { reason: 'the directory cannot be created', exitCode: EXIT_CODES.INVALID_ARGUMENTS },
     ENOSPC: { reason: 'no space left on the device', exitCode: EXIT_CODES.SESSION_FILE_ERROR },
+    EPSEUDOFS: {
+        reason: 'it is on a pseudo-filesystem (/proc, /sys)',
+        exitCode: EXIT_CODES.INVALID_ARGUMENTS,
+    },
 };
 /**
  * A file-system error as a user-facing error about the given path.
@@ -64,7 +69,7 @@ export async function writeOutputFile(filePath, data, extension) {
     assertFilePath(filePath, extension);
     const absolutePath = path.resolve(filePath);
     try {
-        fs.mkdirSync(path.dirname(absolutePath), { recursive: true });
+        makeDirectory(path.dirname(absolutePath));
         if (typeof data === 'string')
             await AtomicFileWriter.writeAsync(absolutePath, data);
         else

package/dist/commands/shared/startHelpers.js

@@ -14,7 +14,7 @@ import { IPCErrorCode, } from '../../ipc/index.js';
 import { IPCTimeoutError } from '../../ipc/transport/index.js';
 import { isConnectionError } from '../../ipc/utils/errors.js';
 import { getSessionName } from '../../session/paths.js';
-import { OutputBuilder, buildSuccessResponse } from '../../ui/OutputBuilder.js';
+import { OutputBuilder, buildSuccessResponse, stringifyEnvelope } from '../../ui/OutputBuilder.js';
 import { escapeControlChars, joinLines } from '../../ui/formatting.js';
 import { createLogger } from '../../ui/logging/index.js';
 import { daemonStillExitingHint, daemonStillExitingSuggestion, startNotices, } from '../../ui/messages/session.js';
@@ -318,7 +318,7 @@ function reportStartOutcome(outcome, options) {
                 exitCode: outcome.exitCode,
                 ...outcome.details,
             });
-            console.log(JSON.stringify(envelope, null, 2));
+            console.log(stringifyEnvelope(envelope));
         }
         else {
             console.error(escapeControlChars(outcome.human));
@@ -340,7 +340,7 @@ function reportStartOutcome(outcome, options) {
             daemonPid: data.daemonPid,
             ...(autoStopAt && { autoStopAt: autoStopAt.toISOString() }),
         };
-        console.log(JSON.stringify(buildSuccessResponse(result), null, 2));
+        console.log(stringifyEnvelope(buildSuccessResponse(result)));
     }
     else {
         const page = {

package/dist/commands/start.d.ts

@@ -84,15 +84,17 @@ export declare function parseViewport(value: string): ViewportSize;
  */
 export declare function parseColorScheme(value: string): ColorScheme;
 /**
- * Reject a subcommand typed without its group (`bdg query x` for
- * `bdg dom query x`) before Commander reads it as a start URL with extra
- * arguments.
+ * Reject a mistyped command before Commander reads it as a start URL with
+ * extra arguments (`too many arguments`): a subcommand typed without its
+ * group (`bdg query x` for `bdg dom query x`), or a word close to a command
+ * followed by more words (`bdg netwrk list`). A single word is left to the
+ * start command, which checks it the same way.
  *
  * @param program - Root command with all commands registered
  * @param argv - Process arguments
- * @throws CommandError (81) naming the full command
+ * @throws CommandError (81) naming the command meant
  */
-export declare function assertNotGroupSubcommand(program: Command, argv: string[]): void;
+export declare function assertNotMistypedCommand(program: Command, argv: string[]): void;
 /**
  * Register the start command
  *

package/dist/commands/start.js

@@ -9,19 +9,12 @@ import { PORT_OPTION_DESCRIPTION } from '../constants.js';
 import { CommandError } from '../errors/index.js';
 import { chromeWsUrlConflictError, externalChromeUnreachableError, invalidChromeFlagError, notDevToolsEndpointError, invalidColorSchemeError, invalidUserDataDirError, invalidViewportError, missingStartUrlError, unknownCommandError, } from '../errors/messages.js';
 import { startCommandHelpMessage } from '../ui/messages/commands.js';
+import { directoryProblem } from '../utils/directories.js';
+import { hasDisplay } from '../utils/display.js';
 import { EXIT_CODES } from '../utils/exitCodes.js';
 import { probeDevToolsEndpoint } from '../utils/http.js';
 import { findSimilar } from '../utils/suggestions.js';
 import { devToolsHttpEndpoint, validateChromeWsUrl, validateUrl } from '../utils/url.js';
-/**
- * Check if a display server (X11 or Wayland) is available.
- * Used to determine default headless mode.
- */
-function hasDisplay() {
-    const display = process.env['DISPLAY'];
-    const wayland = process.env['WAYLAND_DISPLAY'];
-    return (display !== undefined && display !== '') || (wayland !== undefined && wayland !== '');
-}
 /**
  * Expand a leading `~/` in a path to the user's home directory.
  * Chrome itself does not expand `~`, so bdg normalizes it for users.
@@ -74,7 +67,7 @@ export function applyCollectorOptions(command) {
         .option('-a, --all', 'Include all data: no tracking/analytics filtering, and capture every response body (incl. binary)', false)
         .option('-m, --max-body-size <megabytes>', 'Maximum response body size in MB', '5')
         .addOption(new Option('--compact', 'No effect; kept for compatibility').hideHelp())
-        .option('--headless', 'Run Chrome without a window (default unless DISPLAY or WAYLAND_DISPLAY is set)', defaultHeadless)
+        .option('--headless', 'Run Chrome without a window (default without a display: Linux without DISPLAY or WAYLAND_DISPLAY, macOS over SSH or in CI)', defaultHeadless)
         .option('--no-headless', 'Show browser window')
         .option('--chrome-ws-url <url>', 'Connect to an existing Chrome: its DevTools port (9222, host:port, http://host:port), or a WebSocket URL: browser (ws://host:port/devtools/browser/<id>, uses the first tab) or page (.../devtools/page/<id>)')
         .option('-q, --quiet', 'Quiet mode - minimal output for AI agents', false)
@@ -180,6 +173,8 @@ function buildSessionOptions(options) {
 }
 /** Telemetry collected by every session. */
 const SESSION_TELEMETRY = ['dom', 'network', 'console'];
+/** A word that cannot be a URL: no dot, colon or slash */
+const BARE_WORD = /^[a-z][a-z0-9_-]*$/i;
 /** Flags users type as commands (`bdg version`). */
 const FLAG_WORDS = { version: '--version', help: '--help' };
 /**
@@ -194,29 +189,59 @@ const FLAG_WORDS = { version: '--version', help: '--help' };
  * @throws CommandError (81) for a bare word other than `localhost`
  */
 function assertNotCommandTypo(arg, commandNames) {
-    if (!/^[a-z][a-z0-9_-]*$/i.test(arg) || arg.toLowerCase() === 'localhost')
+    if (!BARE_WORD.test(arg) || arg.toLowerCase() === 'localhost')
         return;
     const flag = FLAG_WORDS[arg.toLowerCase()];
     const err = unknownCommandError(arg, flag ? [flag] : findSimilar(arg, commandNames));
     throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.INVALID_ARGUMENTS);
 }
 /**
- * Reject a subcommand typed without its group (`bdg query x` for
- * `bdg dom query x`) before Commander reads it as a start URL with extra
- * arguments.
+ * The words of the command line that are not options or option values of
+ * the root command (`bdg --session a netwrk list` gives `netwrk`, `list`).
+ *
+ * @param program - Root command
+ * @param args - Arguments after the executable and script
+ * @returns Positional words, in order
+ */
+function positionalWords(program, args) {
+    const words = [];
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i] ?? '';
+        if (!arg.startsWith('-')) {
+            words.push(arg);
+            continue;
+        }
+        const option = program.options.find((o) => o.long === arg || o.short === arg);
+        if (option && (option.required || option.optional))
+            i++;
+    }
+    return words;
+}
+/**
+ * Reject a mistyped command before Commander reads it as a start URL with
+ * extra arguments (`too many arguments`): a subcommand typed without its
+ * group (`bdg query x` for `bdg dom query x`), or a word close to a command
+ * followed by more words (`bdg netwrk list`). A single word is left to the
+ * start command, which checks it the same way.
  *
  * @param program - Root command with all commands registered
  * @param argv - Process arguments
- * @throws CommandError (81) naming the full command
+ * @throws CommandError (81) naming the command meant
  */
-export function assertNotGroupSubcommand(program, argv) {
-    const [first] = argv.slice(2).filter((arg) => !arg.startsWith('-'));
-    if (first === undefined || program.commands.some((command) => command.name() === first))
+export function assertNotMistypedCommand(program, argv) {
+    const [first, ...rest] = positionalWords(program, argv.slice(2));
+    const commandNames = program.commands.map((command) => command.name());
+    if (first === undefined || commandNames.includes(first))
         return;
     const group = program.commands.find((command) => command.commands.some((sub) => sub.name() === first));
-    if (!group)
+    const similar = group
+        ? [`${group.name()} ${first}`]
+        : rest.length > 0 && BARE_WORD.test(first)
+            ? findSimilar(first, commandNames)
+            : [];
+    if (similar.length === 0)
         return;
-    const err = unknownCommandError(first, [`${group.name()} ${first}`]);
+    const err = unknownCommandError(first, similar);
     throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.INVALID_ARGUMENTS);
 }
 /**
@@ -247,7 +272,10 @@ function validateStartInput(url, options, program) {
             ...(process.env['BDG_CHROME_FLAGS']?.split(' ') ?? []),
             ...(options.chromeFlags?.split(' ') ?? []),
         ]);
-    return { url, sessionOptions: buildSessionOptions(options) };
+    const sessionOptions = buildSessionOptions(options);
+    if (sessionOptions.userDataDir !== undefined)
+        assertUsableProfile(sessionOptions.userDataDir);
+    return { url, sessionOptions };
 }
 /**
  * Register the start command
@@ -346,6 +374,22 @@ function assertUserDataDir(value) {
     const err = invalidUserDataDirError(value, reason);
     throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.INVALID_ARGUMENTS);
 }
+/**
+ * Check that Chrome can create and write its profile directory (given with
+ * `-u` or in `--chrome-flags`), before a daemon is spawned: a profile under
+ * `/proc` spun the daemon at full CPU and wedged the session.
+ *
+ * @param dir - Profile directory, `~/` expanded
+ * @throws CommandError (81) for a path that cannot hold a directory, (82)
+ *   when its nearest existing directory is not writable
+ */
+function assertUsableProfile(dir) {
+    const problem = directoryProblem(dir);
+    if (!problem)
+        return;
+    const err = invalidUserDataDirError(dir, problem.reason);
+    throw new CommandError(err.message, { suggestion: err.suggestion }, problem.denied ? EXIT_CODES.PERMISSION_DENIED : EXIT_CODES.INVALID_ARGUMENTS);
+}
 /**
  * Options given that only apply to a Chrome bdg launches. `--headless` has a
  * default, so it counts only when given on the command line.

package/dist/commands/stop.d.ts

@@ -1,4 +1,15 @@
 import type { Command } from 'commander';
+/**
+ * Wait until the stopped session's daemon has exited: it removes the
+ * session's files on the way out, and a command run right after (`bdg
+ * sessions`, a new start) would otherwise still see the session. The wait is
+ * bounded, as after a failed start.
+ *
+ * @param pid - Daemon PID read before the stop, or null when unknown
+ * @param waitMs - Milliseconds to wait at most
+ * @returns Warning when the daemon still runs after the wait
+ */
+export declare function waitForDaemonExit(pid: number | null, waitMs?: number): Promise<string | undefined>;
 /**
  * Register stop command
  *

package/dist/commands/stop.js

@@ -3,13 +3,33 @@ import { jsonOption } from './shared/commonOptions.js';
 import { stopSession } from '../ipc/client.js';
 import { IPCErrorCode } from '../ipc/index.js';
 import { IPCTimeoutError } from '../ipc/transport/index.js';
+import { readLiveDaemonPid } from '../session/cleanup/staleSession.js';
 import { joinLines } from '../ui/formatting.js';
 import { chromeClosedMessage, orphanedDaemonsCleanedMessage, warningMessage, } from '../ui/messages/commands.js';
-import { sessionStopped, STOP_MESSAGES, stopFailedError } from '../ui/messages/session.js';
+import { daemonStillExitingHint, daemonStillExitingSuggestion, sessionStopped, STOP_MESSAGES, stopFailedError, } from '../ui/messages/session.js';
 import { noActiveSessionMessage, sessionCommand, startSessionSuggestion, } from '../ui/messages/sessionCommand.js';
+import { waitUntil } from '../utils/async.js';
 import { getExitCodeForIPCError, isDaemonNotRunningError } from '../utils/errorMapping.js';
 import { getErrorMessage } from '../utils/errors.js';
 import { EXIT_CODES } from '../utils/exitCodes.js';
+import { isProcessAlive } from '../utils/process.js';
+/** How long `bdg stop` waits for the session's daemon to exit */
+const DAEMON_EXIT_WAIT_MS = 3000;
+/**
+ * Wait until the stopped session's daemon has exited: it removes the
+ * session's files on the way out, and a command run right after (`bdg
+ * sessions`, a new start) would otherwise still see the session. The wait is
+ * bounded, as after a failed start.
+ *
+ * @param pid - Daemon PID read before the stop, or null when unknown
+ * @param waitMs - Milliseconds to wait at most
+ * @returns Warning when the daemon still runs after the wait
+ */
+export async function waitForDaemonExit(pid, waitMs = DAEMON_EXIT_WAIT_MS) {
+    if (pid === null || (await waitUntil(() => !isProcessAlive(pid), waitMs)))
+        return undefined;
+    return `${daemonStillExitingHint(pid, waitMs)}; ${daemonStillExitingSuggestion()}`;
+}
 /**
  * Format stop result for human-readable output.
  *
@@ -36,8 +56,10 @@ export function registerStopCommand(program) {
         .action(async (options) => {
         await runCommand(async () => {
             try {
+                const daemonPid = readLiveDaemonPid();
                 const response = await stopSession();
                 if (response.status === 'ok') {
+                    const warning = await waitForDaemonExit(daemonPid);
                     return {
                         success: true,
                         data: {
@@ -48,6 +70,7 @@ export function registerStopCommand(program) {
                             },
                             orphanedDaemonsCount: 0,
                             message: response.message ?? STOP_MESSAGES.SUCCESS,
+                            ...(warning && { warnings: [warning] }),
                         },
                     };
                 }

package/dist/commands.js

@@ -1,12 +1,12 @@
 import { registerCdpCommand } from './commands/cdp.js';
 import { registerCleanupCommand } from './commands/cleanup.js';
 import { registerConsoleCommand } from './commands/console.js';
+import { registerCssCommands } from './commands/css.js';
 import { registerDetailsCommand } from './commands/details.js';
 import { registerFormInteractionCommands } from './commands/dom/formInteraction.js';
 import { registerDomCommands } from './commands/dom/index.js';
 import { registerInstallSkillCommand } from './commands/installSkill.js';
 import { registerNetworkCommands } from './commands/network/index.js';
-import { registerCssCommands } from './commands/css.js';
 import { registerPageCommands } from './commands/page.js';
 import { registerPeekCommand } from './commands/peek.js';
 import { registerSessionsCommand } from './commands/sessions.js';

package/dist/connection/cdp.d.ts

@@ -181,6 +181,13 @@ export declare class CDPConnection implements CDPEventSource {
      * @returns Calculated delay in milliseconds (base delay * 2^attempt, capped at maxDelay)
      */
     private calculateBackoffDelay;
+    /**
+     * Fail every command still waiting for an answer, e.g. after the page's
+     * renderer crashed: commands it was running are never answered.
+     *
+     * @param error - Error the waiting commands fail with
+     */
+    rejectPending(error: Error): void;
     /**
      * Clear all pending command promises with the given error.
      *

package/dist/connection/cdp.js

@@ -390,6 +390,15 @@ export class CDPConnection {
     calculateBackoffDelay(attempt, maxDelay) {
         return Math.min(this.config.baseRetryDelay * Math.pow(2, attempt), maxDelay);
     }
+    /**
+     * Fail every command still waiting for an answer, e.g. after the page's
+     * renderer crashed: commands it was running are never answered.
+     *
+     * @param error - Error the waiting commands fail with
+     */
+    rejectPending(error) {
+        this.clearPendingMessages(error);
+    }
     /**
      * Clear all pending command promises with the given error.
      *