browser-debugger-cli 0.7.2 → 0.9.0

package/dist/commands/start.js

@@ -1,10 +1,18 @@
+import fs from 'node:fs';
 import os from 'node:os';
-import { startSessionViaDaemon } from '../commands/shared/startHelpers.js';
-import { positiveIntRule } from '../commands/shared/validation.js';
+import { Option } from 'commander';
+import { jsonOption } from './shared/commonOptions.js';
+import { handleValidationError } from './shared/handleValidationError.js';
+import { startSessionViaDaemon } from './shared/startHelpers.js';
+import { positiveIntRule } from './shared/validation.js';
 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 { genericError } from '../ui/messages/errors.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.
@@ -14,27 +22,102 @@ function hasDisplay() {
     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.
+ */
+export function expandHome(value) {
+    return value.startsWith('~/') ? value.replace(/^~/, os.homedir()) : value;
+}
+/**
+ * Extract `--user-data-dir` from a flags array.
+ *
+ * Supports both `--user-data-dir=<path>` and `--user-data-dir <path>` forms.
+ * When found, returns the path (with `~/` expanded) and the remaining flags
+ * with every matching entry removed, so callers can avoid passing the same
+ * switch to Chrome twice.
+ */
+export function extractUserDataDirFromFlags(flags) {
+    const rest = [];
+    let userDataDir;
+    for (let i = 0; i < flags.length; i++) {
+        const flag = flags[i];
+        if (flag.startsWith('--user-data-dir=')) {
+            userDataDir = flag.slice('--user-data-dir='.length);
+            continue;
+        }
+        if (flag === '--user-data-dir' && i + 1 < flags.length) {
+            userDataDir = flags[i + 1];
+            i++;
+            continue;
+        }
+        rest.push(flag);
+    }
+    return {
+        userDataDir: userDataDir ? expandHome(userDataDir) : undefined,
+        rest,
+    };
+}
 /**
  * Apply shared telemetry options to a command
  *
  * @param command - Commander.js Command instance to apply options to
  * @returns The modified Command instance with all telemetry options applied
  */
-function applyCollectorOptions(command) {
+export function applyCollectorOptions(command) {
     // Default to headless if no display available
     const defaultHeadless = !hasDisplay();
     return command
         .option('-p, --port <number>', PORT_OPTION_DESCRIPTION)
-        .option('-t, --timeout <seconds>', 'Auto-stop after timeout in seconds (unlimited if not specified)')
+        .option('-t, --timeout <seconds>', 'Stop the session this many seconds after the page has loaded (unlimited if not specified)')
         .option('-u, --user-data-dir <path>', 'Chrome user data directory (defaults to session dir)')
-        .option('-a, --all', 'Include all data (disable filtering of tracking/analytics)', false)
+        .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')
-        .option('--compact', 'Use compact JSON format (no indentation) for output files', false)
-        .option('--headless', 'Run in headless mode (auto if no display)', defaultHeadless)
+        .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('--no-headless', 'Show browser window')
-        .option('--chrome-ws-url <url>', 'Connect to existing Chrome via WebSocket URL (e.g., ws://localhost:9222/devtools/page/...)')
+        .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)
-        .option('--chrome-flags <flags>', 'Custom Chrome flags (space-separated, e.g., --chrome-flags="--ignore-certificate-errors --disable-web-security")');
+        .addOption(jsonOption())
+        .option('--chrome-flags <flags>', 'Custom Chrome flags (space-separated, e.g., --chrome-flags="--ignore-certificate-errors --disable-web-security")')
+        .option('--viewport <WxH>', 'Viewport size in CSS px for the whole session, e.g. 1280x800 (default: 1920x1080 window)')
+        .option('--color-scheme <scheme>', 'Emulate prefers-color-scheme for the session: light or dark (default: the system setting)');
+}
+/** Largest viewport side accepted by `--viewport` (CSS px) */
+const MAX_VIEWPORT_SIDE = 10000;
+/** Values of `--color-scheme` */
+const COLOR_SCHEMES = ['light', 'dark'];
+/**
+ * Parse a `--viewport` value: width and height in CSS px joined by `x`
+ * (`1280x800`; `X`, `×` and `,` work too).
+ *
+ * @param value - Option value
+ * @returns Viewport size
+ * @throws CommandError (81) for anything else, or a side outside 1-10000
+ */
+export function parseViewport(value) {
+    const match = /^\s*(\d+)\s*[xX×,]\s*(\d+)\s*$/.exec(value);
+    const width = Number(match?.[1]);
+    const height = Number(match?.[2]);
+    const valid = (side) => side >= 1 && side <= MAX_VIEWPORT_SIDE;
+    if (match && valid(width) && valid(height))
+        return { width, height };
+    const err = invalidViewportError(value, MAX_VIEWPORT_SIDE);
+    throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.INVALID_ARGUMENTS);
+}
+/**
+ * Parse a `--color-scheme` value (case-insensitive).
+ *
+ * @param value - Option value
+ * @returns The scheme
+ * @throws CommandError (81) for another value, suggesting the closest one
+ */
+export function parseColorScheme(value) {
+    const scheme = COLOR_SCHEMES.find((candidate) => candidate === value.trim().toLowerCase());
+    if (scheme)
+        return scheme;
+    const err = invalidColorSchemeError(value, findSimilar(value, [...COLOR_SCHEMES]), COLOR_SCHEMES);
+    throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.INVALID_ARGUMENTS);
 }
 /**
  * Transform CLI options into session options
@@ -43,45 +126,111 @@ function applyCollectorOptions(command) {
  * @returns Session options object with parsed and normalized values
  */
 function buildSessionOptions(options) {
-    const maxBodySizeRule = positiveIntRule({ min: 1, max: 100, required: false });
-    const timeoutRule = positiveIntRule({ min: 1, max: 3600, required: false });
-    const maxBodySizeMB = options.maxBodySize
-        ? maxBodySizeRule.validate(options.maxBodySize)
-        : undefined;
-    const timeout = options.timeout ? timeoutRule.validate(options.timeout) : undefined;
-    let userDataDir = options.userDataDir;
-    if (userDataDir?.startsWith('~/')) {
-        userDataDir = userDataDir.replace(/^~/, os.homedir());
-    }
+    const maxBodySizeRule = positiveIntRule({
+        name: '--max-body-size',
+        min: 1,
+        max: 100,
+        required: false,
+    });
+    const timeoutRule = positiveIntRule({ name: '--timeout', min: 1, max: 3600, required: false });
+    const portRule = positiveIntRule({ name: '--port', min: 1024, max: 65535, required: false });
+    const maxBodySizeMB = options.maxBodySize !== undefined ? maxBodySizeRule.validate(options.maxBodySize) : undefined;
+    const timeout = options.timeout !== undefined ? timeoutRule.validate(options.timeout) : undefined;
     // Merge env var flags with CLI flags (CLI flags come after, taking precedence)
     const envFlags = process.env['BDG_CHROME_FLAGS']?.split(' ').filter(Boolean) ?? [];
     const cliFlags = options.chromeFlags?.split(' ').filter(Boolean) ?? [];
-    const combinedFlags = [...envFlags, ...cliFlags];
+    const { userDataDir: flagUserDataDir, rest: combinedFlags } = extractUserDataDirFromFlags([
+        ...envFlags,
+        ...cliFlags,
+    ]);
+    // Precedence: -u / --user-data-dir > --chrome-flags / BDG_CHROME_FLAGS > default
+    const userDataDir = options.userDataDir ? expandHome(options.userDataDir) : flagUserDataDir;
     const chromeFlags = combinedFlags.length > 0 ? combinedFlags : undefined;
     return {
-        port: parseInt(options.port, 10),
+        port: options.port !== undefined ? portRule.validate(options.port) : undefined,
         timeout,
         userDataDir,
         includeAll: options.all ?? false,
         maxBodySize: maxBodySizeMB !== undefined ? maxBodySizeMB * 1024 * 1024 : undefined,
-        compact: options.compact ?? false,
         headless: options.headless ?? !hasDisplay(),
         chromeWsUrl: options.chromeWsUrl,
         quiet: options.quiet ?? false,
+        json: options.json ?? false,
         chromeFlags,
+        viewport: options.viewport !== undefined ? parseViewport(options.viewport) : undefined,
+        colorScheme: options.colorScheme !== undefined ? parseColorScheme(options.colorScheme) : undefined,
     };
 }
+/** Telemetry collected by every session. */
+const SESSION_TELEMETRY = ['dom', 'network', 'console'];
+/** Flags users type as commands (`bdg version`). */
+const FLAG_WORDS = { version: '--version', help: '--help' };
+/**
+ * Reject a bare word that is most likely a mistyped command.
+ *
+ * Without a dot, colon or slash an argument cannot be a public URL; treating
+ * it as one would start Chrome on `http://<word>/`. A dotless host still
+ * works as a full URL (`bdg http://intranet/`).
+ *
+ * @param arg - The URL argument
+ * @param commandNames - Registered top-level command names
+ * @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')
+        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.
+ *
+ * @param program - Root command with all commands registered
+ * @param argv - Process arguments
+ * @throws CommandError (81) naming the full command
+ */
+export function assertNotGroupSubcommand(program, argv) {
+    const [first] = argv.slice(2).filter((arg) => !arg.startsWith('-'));
+    if (first === undefined || program.commands.some((command) => command.name() === first))
+        return;
+    const group = program.commands.find((command) => command.commands.some((sub) => sub.name() === first));
+    if (!group)
+        return;
+    const err = unknownCommandError(first, [`${group.name()} ${first}`]);
+    throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.INVALID_ARGUMENTS);
+}
 /**
- * Common action handler for telemetry commands
+ * Validate the URL and all start options before anything is spawned.
  *
- * @param url - Target URL to collect telemetry from
+ * @param url - Target URL
  * @param options - Parsed command-line options from Commander
- * @returns Promise that resolves when session completes or is stopped
+ * @param program - Root command (registered command names for typo detection,
+ *   and which options came from the command line)
+ * @returns The URL and normalized session options
+ * @throws CommandError on any invalid input
  */
-async function collectorAction(url, options) {
-    const sessionOptions = buildSessionOptions(options);
-    const telemetry = ['dom', 'network', 'console'];
-    await startSessionViaDaemon(url, sessionOptions, telemetry);
+function validateStartInput(url, options, program) {
+    if (url === undefined) {
+        const err = missingStartUrlError();
+        throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.INVALID_ARGUMENTS);
+    }
+    assertNotCommandTypo(url, program.commands.map((command) => command.name()));
+    assertValidUrl(url);
+    if (options.chromeWsUrl !== undefined) {
+        assertValidChromeWsUrl(options.chromeWsUrl);
+        assertNoLaunchOptions(options, program);
+    }
+    if (options.userDataDir !== undefined)
+        assertUserDataDir(options.userDataDir);
+    if (options.chromeWsUrl === undefined)
+        assertChromeFlags([
+            ...(process.env['BDG_CHROME_FLAGS']?.split(' ') ?? []),
+            ...(options.chromeFlags?.split(' ') ?? []),
+        ]);
+    return { url, sessionOptions: buildSessionOptions(options) };
 }
 /**
  * Register the start command
@@ -91,20 +240,159 @@ async function collectorAction(url, options) {
  */
 export function registerStartCommands(program) {
     applyCollectorOptions(program.argument('[url]', 'Target URL (example.com or localhost:3000)')).action(async (url, options) => {
-        if (!url) {
+        if (url === undefined && !hasUserOptions(program)) {
             console.error(startCommandHelpMessage());
             process.exit(0);
         }
-        const { validateUrl } = await import('../utils/url.js');
-        const validation = validateUrl(url);
-        if (!validation.valid) {
-            console.error(genericError(validation.error ?? 'Invalid URL'));
-            if (validation.suggestion) {
-                console.error(`Suggestion: ${validation.suggestion}`);
-            }
-            process.exit(EXIT_CODES.INVALID_URL);
+        let validated;
+        try {
+            validated = validateStartInput(url, options, program);
+            validated.sessionOptions.chromeWsUrl = await resolveChromeWsUrl(validated.sessionOptions.chromeWsUrl);
         }
-        await collectorAction(url, options);
+        catch (error) {
+            handleValidationError(error, options.json ?? false);
+        }
+        await startSessionViaDaemon(validated.url, validated.sessionOptions, SESSION_TELEMETRY);
+    });
+}
+/**
+ * Turn a `--chrome-ws-url` that names the HTTP DevTools endpoint (a port,
+ * `host:port`, or `http://host:port`) into the browser's WebSocket URL from
+ * its `/json/version`, so users need not look it up themselves.
+ *
+ * @param value - Option value (WebSocket URLs are returned unchanged)
+ * @returns WebSocket URL, or undefined without the option
+ * @throws CommandError (101) when the endpoint does not answer or is not DevTools
+ */
+async function resolveChromeWsUrl(value) {
+    const endpoint = value === undefined ? null : devToolsHttpEndpoint(value);
+    if (endpoint === null)
+        return value;
+    const { hostname, port, protocol } = new URL(endpoint);
+    const secure = protocol === 'https:';
+    const defaultPort = secure ? 443 : 80;
+    const probe = await probeDevToolsEndpoint(Number(port) || defaultPort, undefined, {
+        host: hostname,
+        secure,
     });
+    if (probe.kind === 'devtools')
+        return atEndpoint(probe.wsUrl, endpoint);
+    const err = probe.kind === 'not-devtools'
+        ? notDevToolsEndpointError(endpoint)
+        : externalChromeUnreachableError(endpoint, false);
+    throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.CDP_CONNECTION_FAILURE);
+}
+/**
+ * Point a WebSocket URL Chrome reported at the endpoint the user gave: Chrome
+ * reports its own host and port, which differ behind a proxy or forwarded
+ * port, and only ws:// (an https endpoint is a TLS proxy, so wss://).
+ *
+ * @param wsUrl - URL from `/json/version`
+ * @param endpoint - Endpoint origin the user gave
+ * @returns The URL with the endpoint's host, port and matching scheme
+ */
+function atEndpoint(wsUrl, endpoint) {
+    const resolved = new URL(wsUrl);
+    const target = new URL(endpoint);
+    resolved.protocol = target.protocol === 'https:' ? 'wss:' : 'ws:';
+    resolved.host = target.host;
+    return resolved.toString();
+}
+/**
+ * Whether any start option was given on the command line (`bdg --port 9333`
+ * without a URL is an error, a bare `bdg` shows help).
+ *
+ * @param program - Root command
+ * @returns True if an option came from the command line
+ */
+function hasUserOptions(program) {
+    return program.options.some((option) => program.getOptionValueSource(option.attributeName()) === 'cli');
+}
+/**
+ * Reject a `-u` value that is an option (`-u --json` swallowed the next flag)
+ * or an existing file.
+ *
+ * @param value - Value of `--user-data-dir`
+ * @throws CommandError (81) when it cannot be a profile directory
+ */
+function assertUserDataDir(value) {
+    const resolved = expandHome(value);
+    let reason;
+    if (!value.trim())
+        reason = 'the path is empty';
+    else if (value.startsWith('-'))
+        reason = 'it looks like an option; -u needs a directory path';
+    else if (fs.existsSync(resolved) && !fs.statSync(resolved).isDirectory())
+        reason = 'it is a file';
+    if (reason === undefined)
+        return;
+    const err = invalidUserDataDirError(value, reason);
+    throw new CommandError(err.message, { suggestion: err.suggestion }, 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.
+ *
+ * @param options - Parsed options
+ * @param program - Command the options were parsed by
+ * @returns The conflicting flags, e.g. ["--port", "--headless"]
+ */
+export function launchOptionConflicts(options, program) {
+    const headlessGiven = program.getOptionValueSource('headless') === 'cli';
+    return [
+        ...(options.port !== undefined ? ['--port'] : []),
+        ...(options.userDataDir !== undefined ? ['--user-data-dir'] : []),
+        ...(headlessGiven ? [options.headless ? '--headless' : '--no-headless'] : []),
+    ];
+}
+/**
+ * Reject options that only apply to a Chrome bdg launches.
+ *
+ * @param options - Parsed options (with `--chrome-ws-url`)
+ * @param program - Command the options were parsed by
+ * @throws CommandError (81) for `--port`, `-u` or `--[no-]headless`
+ */
+function assertNoLaunchOptions(options, program) {
+    const conflicts = launchOptionConflicts(options, program);
+    if (conflicts.length === 0)
+        return;
+    const err = chromeWsUrlConflictError(conflicts);
+    throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.INVALID_ARGUMENTS);
+}
+/** bdg's own options, which a `--chrome-flags` value must not be */
+const BDG_OPTION_WORDS = new Set([
+    '--json',
+    '-j',
+    '--port',
+    '-p',
+    '--no-headless',
+    '-q',
+    '--quiet',
+]);
+/**
+ * Reject Chrome flags bdg sets itself, and a `--chrome-flags` value that is
+ * one of bdg's options (`--chrome-flags --json` swallowed `--json`).
+ *
+ * @param flags - Flags from BDG_CHROME_FLAGS and --chrome-flags
+ * @throws CommandError (81) for a conflicting or swallowed flag
+ */
+function assertChromeFlags(flags) {
+    const flag = flags.find((value) => /^--remote-debugging-(port|pipe)\b/.test(value) || BDG_OPTION_WORDS.has(value));
+    if (flag === undefined)
+        return;
+    const err = invalidChromeFlagError(flag);
+    throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.INVALID_ARGUMENTS);
+}
+function assertValidUrl(url) {
+    const result = validateUrl(url);
+    if (result.valid)
+        return;
+    throw new CommandError(result.error, result.suggestion ? { suggestion: result.suggestion } : {}, EXIT_CODES.INVALID_URL);
+}
+function assertValidChromeWsUrl(url) {
+    const result = validateChromeWsUrl(url);
+    if (result.valid)
+        return;
+    throw new CommandError(result.error, result.suggestion ? { suggestion: result.suggestion } : {}, EXIT_CODES.INVALID_URL);
 }
 //# sourceMappingURL=start.js.map

package/dist/commands/status.js

@@ -1,11 +1,55 @@
-import { runCommand } from '../commands/shared/CommandRunner.js';
+import { runCommand } from './shared/CommandRunner.js';
+import { isDaemonConnectionError } from '../errors/index.js';
+import { invalidResponseError, sessionNotRespondingError } from '../errors/messages.js';
 import { getStatus } from '../ipc/client.js';
-import { cleanupStaleDaemonPid } from '../session/cleanup.js';
-import { isDaemonConnectionError } from '../ui/errors/index.js';
+import { IPCTimeoutError } from '../ipc/transport/IPCError.js';
+import { describeRunningChrome } from '../session/chrome.js';
+import { findOrphanedChrome, removeStaleDaemonFiles } from '../session/cleanup/staleSession.js';
+import { readLastSessionEnd } from '../session/lastSession.js';
+import { getSessionName } from '../session/paths.js';
 import { formatSessionStatus, formatStatusAsJson, formatNoSessionMessage, } from '../ui/formatters/status.js';
-import { invalidResponseError, daemonNotRunningError } from '../ui/messages/errors.js';
+import { sessionCommand } from '../ui/messages/sessionCommand.js';
 import { getErrorMessage } from '../utils/errors.js';
 import { EXIT_CODES } from '../utils/exitCodes.js';
+/**
+ * Status without a running session: a start in progress, or a Chrome left
+ * running by an earlier session.
+ *
+ * @param starting - Start in progress, as reported by the daemon
+ * @param ending - Whether the daemon is shutting the session down
+ * @returns Status data (inactive)
+ */
+function inactiveStatus(starting, ending) {
+    if (starting)
+        return { active: false, starting };
+    if (ending)
+        return { active: false, ending: true };
+    const orphanedChromePid = findOrphanedChrome();
+    const lastSession = readLastSessionEnd();
+    return {
+        active: false,
+        ...(orphanedChromePid !== null && { orphanedChromePid }),
+        ...(lastSession && { lastSession }),
+    };
+}
+/**
+ * Add the selected session's name (named sessions only).
+ *
+ * @param data - Status data
+ * @returns Status data with `session` for a named session
+ */
+function withSessionName(data) {
+    const session = getSessionName();
+    return session === null ? data : { session, ...data };
+}
+/**
+ * Force-clean the selected session and start it again.
+ *
+ * @returns Command line
+ */
+function resetCommand() {
+    return `${sessionCommand('bdg cleanup --force')} && ${sessionCommand('bdg <url>')}`;
+}
 /**
  * Register status command
  *
@@ -17,7 +61,7 @@ export function registerStatusCommand(program) {
         .command('status')
         .description('Show active session status and collection statistics')
         .option('-j, --json', 'Output as JSON', false)
-        .option('-v, --verbose', 'Show detailed Chrome diagnostics', false)
+        .option('-v, --verbose', "Also show the session's Chrome executable, mode and profile", false)
         .action(async (options) => {
         let latestMetadata;
         let latestSessionPid;
@@ -32,7 +76,7 @@ export function registerStatusCommand(program) {
                         error: `Daemon error: ${response.error ?? 'Unknown error'}`,
                         exitCode: EXIT_CODES.SOFTWARE_ERROR,
                         errorContext: {
-                            suggestion: 'Try: bdg cleanup --force && bdg <url>',
+                            suggestion: `Try: ${resetCommand()}`,
                         },
                     };
                 }
@@ -43,7 +87,7 @@ export function registerStatusCommand(program) {
                         error: invalidResponseError('missing data'),
                         exitCode: EXIT_CODES.SOFTWARE_ERROR,
                         errorContext: {
-                            suggestion: 'This is unexpected. Try: bdg cleanup --force && bdg <url>',
+                            suggestion: `This is unexpected. Try: ${resetCommand()}`,
                         },
                     };
                 }
@@ -52,14 +96,14 @@ export function registerStatusCommand(program) {
                 if (!data.sessionPid || !data.sessionMetadata) {
                     latestMetadata = undefined;
                     latestSessionPid = undefined;
-                    const jsonOutput = formatStatusAsJson(null, null);
+                    const jsonOutput = inactiveStatus(data.starting, data.ending);
                     if (data.activity) {
                         jsonOutput.activity = data.activity;
                     }
                     if (data.pageState) {
                         jsonOutput.pageState = data.pageState;
                     }
-                    return { success: true, data: jsonOutput };
+                    return { success: true, data: withSessionName(jsonOutput) };
                 }
                 const metadata = {
                     bdgPid: data.sessionMetadata.bdgPid,
@@ -69,45 +113,60 @@ export function registerStatusCommand(program) {
                     targetId: data.sessionMetadata.targetId,
                     webSocketDebuggerUrl: data.sessionMetadata.webSocketDebuggerUrl,
                     activeTelemetry: data.sessionMetadata.activeTelemetry,
+                    autoStopAt: data.sessionMetadata.autoStopAt,
+                    viewport: data.sessionMetadata.viewport,
+                    colorScheme: data.sessionMetadata.colorScheme,
                 };
                 latestMetadata = metadata;
                 latestSessionPid = data.sessionPid;
                 const jsonOutput = formatStatusAsJson(metadata, data.sessionPid);
+                const chrome = options.verbose && metadata.chromePid
+                    ? describeRunningChrome(metadata.chromePid)
+                    : null;
+                if (chrome)
+                    jsonOutput.chrome = chrome;
                 if (data.activity) {
                     jsonOutput.activity = data.activity;
                 }
                 if (data.pageState) {
                     jsonOutput.pageState = data.pageState;
                 }
-                return { success: true, data: jsonOutput };
+                return { success: true, data: withSessionName(jsonOutput) };
             }
             catch (error) {
                 const errorMessage = getErrorMessage(error);
-                if (isDaemonConnectionError(error)) {
-                    const cleaned = cleanupStaleDaemonPid();
+                if (error instanceof IPCTimeoutError) {
+                    const err = sessionNotRespondingError(error.timeoutMs / 1000);
                     return {
                         success: false,
-                        error: daemonNotRunningError({ staleCleanedUp: cleaned }),
-                        exitCode: EXIT_CODES.RESOURCE_NOT_FOUND,
+                        error: err.message,
+                        exitCode: EXIT_CODES.CDP_TIMEOUT,
+                        errorContext: { suggestion: err.suggestion },
                     };
                 }
+                if (isDaemonConnectionError(error)) {
+                    await removeStaleDaemonFiles();
+                    latestMetadata = undefined;
+                    latestSessionPid = undefined;
+                    return { success: true, data: withSessionName(inactiveStatus()) };
+                }
                 return {
                     success: false,
                     error: `Error checking status: ${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`,
                     },
                 };
             }
         }, options, (data) => {
             if (!data.active) {
-                return formatNoSessionMessage();
+                return formatNoSessionMessage(data);
             }
             if (!latestMetadata || latestSessionPid === undefined) {
                 return formatNoSessionMessage();
             }
-            return formatSessionStatus(latestMetadata, latestSessionPid, latestActivity, latestPageState, options.verbose ?? false);
+            return formatSessionStatus(latestMetadata, latestSessionPid, latestActivity, latestPageState, options.verbose ?? false, data.session);
         });
     });
 }