browser-debugger-cli 0.8.0 → 0.10.0

package/dist/runtime/page/navigation.d.ts

@@ -3,6 +3,7 @@
  */
 import type { CDPConnection } from '../../connection/cdp.js';
 import type { PageAction, PageNavigationResult } from '../../ipc/protocol/commands.js';
+import type { PendingRequest } from '../../telemetry/network.js';
 import type { CDPSender } from '../../telemetry/objectExpander.js';
 /**
  * Navigate the session's page and wait until it has loaded.
@@ -11,17 +12,21 @@ import type { CDPSender } from '../../telemetry/objectExpander.js';
  * navigation may still be waiting for the server). Otherwise the server gets
  * {@link PAGE_READY_TIMEOUT_MS} to answer, then the new document is waited on
  * to settle; its HTTP status is reported, with a warning for 4xx/5xx, for a
- * URL that is a download, or a page still loading.
+ * URL that is a download, or a server that has not answered. A document
+ * that has not finished loading by then is reported as `loading`, with the
+ * requests it waits on.
  *
  * @param cdp - CDP connection
  * @param action - Navigate to a URL, reload, or go back/forward in history
- * @param options - `url` for navigate, `wait: false` to return without waiting
+ * @param options - `url` for navigate, `wait: false` to return without waiting,
+ *   `pendingRequests`: the session's requests still running
  * @returns Where the page is now
  * @throws CommandError (80) for an unreachable URL, (81) without a history entry
  */
 export declare function navigatePage(cdp: CDPConnection, action: PageAction, options?: {
     url?: string;
     wait?: boolean;
+    pendingRequests?: () => Iterable<PendingRequest>;
 }): Promise<PageNavigationResult>;
 /**
  * The URL of a navigation still waiting for the server, if any: the page
@@ -31,4 +36,43 @@ export declare function navigatePage(cdp: CDPConnection, action: PageAction, opt
  * @returns The pending URL, or undefined when the page is not navigating
  */
 export declare function pendingNavigationUrl(cdp: CDPSender): Promise<string | undefined>;
+/** HTTP response of a document loaded in the main frame */
+interface DocumentResponse {
+    status: number;
+    url: string;
+}
+/** Documents the main frame loaded during a navigation */
+export interface DocumentResponses {
+    /** The navigation's own document (after HTTP redirects) */
+    first: DocumentResponse;
+    /** The last document loaded after it (a script or meta refresh moved on), if any */
+    later?: DocumentResponse;
+}
+/**
+ * Add the HTTP status of the navigation's own document, with a warning for an
+ * error status or for a later document that answered differently (a 404 page
+ * whose script loads the app, as single-page apps on static hosts do).
+ *
+ * @param result - Navigation result
+ * @param documents - The main frame's document responses, if one arrived
+ * @returns Result with status
+ */
+export declare function withStatus(result: PageNavigationResult, documents: DocumentResponses | undefined): PageNavigationResult;
+/**
+ * Watch for the responses of the main frame's documents. Only documents
+ * requested after the watch began count (a response to a request from
+ * before belongs to an earlier navigation). The navigation's own document
+ * is the one of its loader when the browser named it, else the first; the
+ * documents after it were loaded by the page itself.
+ *
+ * @param cdp - CDP connection
+ * @param mainFrameId - Main frame id
+ * @returns The responses seen so far (given the navigation's loader, if known),
+ *   and a function to stop listening
+ */
+export declare function documentResponse(cdp: Pick<CDPConnection, 'on'>, mainFrameId: string): {
+    response: (loaderId?: string) => DocumentResponses | undefined;
+    stop: () => void;
+};
+export {};
 //# sourceMappingURL=navigation.d.ts.map

package/dist/runtime/page/navigation.js

@@ -5,8 +5,9 @@ import { waitForPageReady } from '../../connection/pageReadiness.js';
 import { UNREACHABLE_ERRORS } from '../../daemon/session/cdpSetup.js';
 import { CommandError } from '../../errors/index.js';
 import { navigationFailedError, noHistoryEntryError } from '../../errors/messages.js';
+import { readPageLoadingState } from './loadingState.js';
 import { createLogger } from '../../ui/logging/index.js';
-import { httpErrorWarning, notAPageWarning, stillLoadingWarning } from '../../ui/messages/commands.js';
+import { documentStatusWarning, notAPageWarning, stillLoadingWarning, } from '../../ui/messages/commands.js';
 import { delay } from '../../utils/async.js';
 import { getErrorMessage } from '../../utils/errors.js';
 import { EXIT_CODES } from '../../utils/exitCodes.js';
@@ -21,11 +22,14 @@ const PAGE_READY_TIMEOUT_MS = 15_000;
  * navigation may still be waiting for the server). Otherwise the server gets
  * {@link PAGE_READY_TIMEOUT_MS} to answer, then the new document is waited on
  * to settle; its HTTP status is reported, with a warning for 4xx/5xx, for a
- * URL that is a download, or a page still loading.
+ * URL that is a download, or a server that has not answered. A document
+ * that has not finished loading by then is reported as `loading`, with the
+ * requests it waits on.
  *
  * @param cdp - CDP connection
  * @param action - Navigate to a URL, reload, or go back/forward in history
- * @param options - `url` for navigate, `wait: false` to return without waiting
+ * @param options - `url` for navigate, `wait: false` to return without waiting,
+ *   `pendingRequests`: the session's requests still running
  * @returns Where the page is now
  * @throws CommandError (80) for an unreachable URL, (81) without a history entry
  */
@@ -37,15 +41,17 @@ export async function navigatePage(cdp, action, options = {}) {
     const navigated = nextNavigation(cdp, mainFrameId);
     const document = documentResponse(cdp, mainFrameId);
     const deadline = Date.now() + PAGE_READY_TIMEOUT_MS;
+    let loaderId;
     try {
         const sent = startAction(cdp, action, url);
         sent.catch(() => undefined);
         const started = await Promise.race([sent, delay(PAGE_READY_TIMEOUT_MS)]);
         if (started === undefined)
             return await stillLoading(cdp, action);
-        if (started === 'not-a-page') {
+        if (started.notAPage) {
             return { action, ...(await currentLocation(cdp)), warning: notAPageWarning() };
         }
+        loaderId = started.loaderId;
         const how = await Promise.race([navigated.done, delay(Math.max(0, deadline - Date.now()))]);
         if (how === 'loaded') {
             await waitForPageReady(cdp, { maxWaitMs: Math.max(0, deadline - Date.now()) });
@@ -55,7 +61,9 @@ export async function navigatePage(cdp, action, options = {}) {
         navigated.stop();
         document.stop();
     }
-    return withStatus({ action, ...(await currentLocation(cdp)) }, document.response());
+    const result = withStatus({ action, ...(await currentLocation(cdp)) }, document.response(loaderId));
+    const loading = await readPageLoadingState(cdp, options.pendingRequests?.() ?? []);
+    return loading ? { ...result, loading } : result;
 }
 /** How long `--no-wait` waits for an action to be refused (no history entry, unreachable URL) */
 const NO_WAIT_GRACE_MS = 1_000;
@@ -74,7 +82,7 @@ async function startWithoutWaiting(cdp, action, url) {
     sent.catch((error) => log.debug(`Navigation not started: ${getErrorMessage(error)}`));
     const started = await Promise.race([sent, delay(NO_WAIT_GRACE_MS)]);
     const result = { action, url: url ?? (await pageTarget(cdp)).url, title: '' };
-    return started === 'not-a-page' ? { ...result, warning: notAPageWarning() } : result;
+    return started?.notAPage ? { ...result, warning: notAPageWarning() } : result;
 }
 /**
  * Send the command of an action.
@@ -82,7 +90,7 @@ async function startWithoutWaiting(cdp, action, url) {
  * @param cdp - CDP connection
  * @param action - What to do
  * @param url - Normalized URL for navigate
- * @returns 'not-a-page' when the URL loaded no document (a download), else 'started'
+ * @returns Whether a document is loading, and its loader when known
  * @throws CommandError (80) when the URL cannot be reached, (81) without a history entry
  */
 async function startAction(cdp, action, url) {
@@ -92,7 +100,7 @@ async function startAction(cdp, action, url) {
         await cdp.send('Page.reload', {});
     else
         await goThroughHistory(cdp, action === 'back' ? -1 : 1);
-    return 'started';
+    return { notAPage: false };
 }
 /**
  * The page target as the browser sees it. Unlike the page's own state, this
@@ -151,38 +159,64 @@ async function stillLoading(cdp, action) {
     };
 }
 /**
- * Add the document's HTTP status (and a warning for an error status).
+ * Add the HTTP status of the navigation's own document, with a warning for an
+ * error status or for a later document that answered differently (a 404 page
+ * whose script loads the app, as single-page apps on static hosts do).
  *
  * @param result - Navigation result
- * @param response - The main document's response, if one arrived
+ * @param documents - The main frame's document responses, if one arrived
  * @returns Result with status
  */
-function withStatus(result, response) {
-    if (!response)
+export function withStatus(result, documents) {
+    if (!documents)
         return result;
-    const url = result.url.startsWith('chrome-error://') ? response.url : result.url;
-    return {
-        ...result,
-        url,
-        status: response.status,
-        ...(response.status >= 400 && { warning: httpErrorWarning(response.status) }),
-    };
+    const { first, later } = documents;
+    const url = result.url.startsWith('chrome-error://') ? first.url : result.url;
+    const warning = documentStatusWarning(first.status, later);
+    return { ...result, url, status: first.status, ...(warning && { warning }) };
 }
 /**
- * Watch for the response of the main frame's next document.
+ * Watch for the responses of the main frame's documents. Only documents
+ * requested after the watch began count (a response to a request from
+ * before belongs to an earlier navigation). The navigation's own document
+ * is the one of its loader when the browser named it, else the first; the
+ * documents after it were loaded by the page itself.
  *
  * @param cdp - CDP connection
  * @param mainFrameId - Main frame id
- * @returns The response seen so far, and a function to stop listening
+ * @returns The responses seen so far (given the navigation's loader, if known),
+ *   and a function to stop listening
  */
-function documentResponse(cdp, mainFrameId) {
-    let seen;
-    const stop = cdp.on('Network.responseReceived', (params) => {
-        if (params.type === 'Document' && params.frameId === mainFrameId) {
-            seen = { status: params.response.status, url: params.response.url };
-        }
+export function documentResponse(cdp, mainFrameId) {
+    const requested = new Set();
+    const responses = [];
+    const isMainDocument = (params) => params.type === 'Document' && params.frameId === mainFrameId;
+    const stopRequests = cdp.on('Network.requestWillBeSent', (params) => {
+        if (isMainDocument(params))
+            requested.add(params.requestId);
     });
-    return { response: () => seen, stop };
+    const stopResponses = cdp.on('Network.responseReceived', (params) => {
+        if (!isMainDocument(params) || !requested.has(params.requestId))
+            return;
+        const { status, url } = params.response;
+        responses.push({ status, url, ...(params.loaderId && { loaderId: params.loaderId }) });
+    });
+    const response = (loaderId) => {
+        const index = loaderId ? responses.findIndex((r) => r.loaderId === loaderId) : 0;
+        const own = responses[index];
+        if (index < 0 || !own)
+            return undefined;
+        const last = responses.length - 1 > index ? responses[responses.length - 1] : undefined;
+        const first = { status: own.status, url: own.url };
+        return last ? { first, later: { status: last.status, url: last.url } } : { first };
+    };
+    return {
+        response,
+        stop: () => {
+            stopRequests();
+            stopResponses();
+        },
+    };
 }
 /**
  * Resolve once the page has loaded a new document, moved within its
@@ -216,15 +250,17 @@ function nextNavigation(cdp, mainFrameId) {
  *
  * @param cdp - CDP connection
  * @param url - Normalized URL
- * @returns 'not-a-page' when no document was loaded (a download), else 'started'
+ * @returns Whether a document is loading (not for a download), and its loader
  * @throws CommandError (80) when the URL cannot be reached
  */
 async function navigateTo(cdp, url) {
     const navigation = (await cdp.send('Page.navigate', { url }));
-    if (navigation.errorText === 'net::ERR_ABORTED' && !navigation.loaderId)
-        return 'not-a-page';
-    if (!navigation.errorText || !UNREACHABLE_ERRORS.test(navigation.errorText))
-        return 'started';
+    if (navigation.errorText === 'net::ERR_ABORTED' && !navigation.loaderId) {
+        return { notAPage: true };
+    }
+    if (!navigation.errorText || !UNREACHABLE_ERRORS.test(navigation.errorText)) {
+        return { notAPage: false, ...(navigation.loaderId && { loaderId: navigation.loaderId }) };
+    }
     const err = navigationFailedError(url, navigation.errorText);
     throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.INVALID_URL);
 }

package/dist/session/QueryCacheManager.d.ts

@@ -18,11 +18,21 @@
  * }
  * ```
  */
-import type { DomQueryResult } from '../types.js';
+import type { DomQueryResult, IndexSource } from '../types.js';
 /**
  * Selector recorded for `dom form` results (fields carry their own selectors).
  */
 export declare const FORM_DISCOVERY_CACHE_SELECTOR = "form:auto-discovered";
+/** Prefix of the selector recorded for `dom a11y query` results (followed by the pattern) */
+export declare const A11Y_CACHE_SELECTOR_PREFIX = "a11y ";
+/**
+ * The list an index refers to, from the selector recorded with the cache.
+ *
+ * @param index - The index the user gave
+ * @param cacheSelector - Selector recorded with the cached results
+ * @returns The command whose results are cached, and its query
+ */
+export declare function indexSourceOf(index: number, cacheSelector: string): IndexSource;
 /**
  * Result of reading the cache.
  */

package/dist/session/QueryCacheManager.js

@@ -23,6 +23,7 @@ import { readFile, rm, writeFile } from 'fs/promises';
 import { join } from 'path';
 import { getSessionDir } from './paths.js';
 import { createLogger } from '../ui/logging/index.js';
+import { sessionCommand } from '../ui/messages/sessionCommand.js';
 import { getErrorMessage } from '../utils/errors.js';
 const log = createLogger('session');
 /**
@@ -34,6 +35,27 @@ const CACHE_VERSION = 2;
  * Selector recorded for `dom form` results (fields carry their own selectors).
  */
 export const FORM_DISCOVERY_CACHE_SELECTOR = 'form:auto-discovered';
+/** Prefix of the selector recorded for `dom a11y query` results (followed by the pattern) */
+export const A11Y_CACHE_SELECTOR_PREFIX = 'a11y ';
+/**
+ * The list an index refers to, from the selector recorded with the cache.
+ *
+ * @param index - The index the user gave
+ * @param cacheSelector - Selector recorded with the cached results
+ * @returns The command whose results are cached, and its query
+ */
+export function indexSourceOf(index, cacheSelector) {
+    if (cacheSelector === FORM_DISCOVERY_CACHE_SELECTOR)
+        return { index, command: 'dom form' };
+    if (cacheSelector.startsWith(A11Y_CACHE_SELECTOR_PREFIX)) {
+        return {
+            index,
+            command: 'dom a11y query',
+            query: cacheSelector.slice(A11Y_CACHE_SELECTOR_PREFIX.length),
+        };
+    }
+    return { index, command: 'dom query', query: cacheSelector };
+}
 /**
  * Singleton manager for the on-disk query cache.
  */
@@ -89,7 +111,7 @@ export class QueryCacheManager {
                 valid: false,
                 cache: null,
                 error: 'No cached query results found',
-                suggestion: 'Run "bdg dom query <selector>" first to generate indexed results',
+                suggestion: `Run "${sessionCommand('bdg dom query <selector>')}" first to generate indexed results`,
             };
         }
         const { version, ...cache } = raw;
@@ -99,8 +121,8 @@ export class QueryCacheManager {
                 cache: null,
                 error: 'Cached query results are from an older bdg version',
                 suggestion: cache.selector === FORM_DISCOVERY_CACHE_SELECTOR
-                    ? 'Re-run "bdg dom form" to refresh cached results'
-                    : `Re-run "bdg dom query ${cache.selector}" to refresh cached results`,
+                    ? `Re-run "${sessionCommand('bdg dom form')}" to refresh cached results`
+                    : `Re-run "${sessionCommand(`bdg dom query ${cache.selector}`)}" to refresh cached results`,
             };
         }
         return { valid: true, cache };

package/dist/session/chromeOwners.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Which other bdg session uses a Chrome, so `--chrome-ws-url` never takes over
+ * a tab another session drives, nor a Chrome another session launched (and
+ * closes when it stops).
+ *
+ * Sessions are found in this base directory and, through the machine-wide
+ * port registry, in other base directories whose sessions claimed a port.
+ */
+/**
+ * A running session and the Chrome tab it drives.
+ */
+export interface ChromeOwner {
+    /** Session name, or null for a default session */
+    name: string | null;
+    /** Session directory */
+    dir: string;
+    /** Base directory of the session (its `BDG_SESSION_DIR`) */
+    baseDir: string;
+    /** Target (tab) the session drives */
+    targetId: string;
+    /** Whether the session launched that Chrome (it closes Chrome when it stops) */
+    launched: boolean;
+}
+/**
+ * Another running session that a new session attaching to a Chrome would
+ * collide with: one that launched that Chrome, or one driving the tab the
+ * new session would use.
+ *
+ * @param chromeTargetIds - Ids of every target of the Chrome being attached to
+ * @param targetId - Tab the new session would drive
+ * @returns The conflicting session, or null
+ */
+export declare function findConflictingOwner(chromeTargetIds: readonly string[], targetId: string): Promise<ChromeOwner | null>;
+//# sourceMappingURL=chromeOwners.d.ts.map

package/dist/session/chromeOwners.js

@@ -0,0 +1,51 @@
+/**
+ * Which other bdg session uses a Chrome, so `--chrome-ws-url` never takes over
+ * a tab another session drives, nor a Chrome another session launched (and
+ * closes when it stops).
+ *
+ * Sessions are found in this base directory and, through the machine-wide
+ * port registry, in other base directories whose sessions claimed a port.
+ */
+import * as fs from 'fs';
+import { probeDaemonSocket } from './daemonSocket.js';
+import { sessionFilePathIn, sessionOfDir } from './paths.js';
+import { otherSessionDirs } from './portClaims.js';
+import { createLogger, logDebugError } from '../ui/logging/index.js';
+const log = createLogger('session');
+/**
+ * The tab a running session drives, from its metadata.
+ *
+ * @param dir - Session directory
+ * @returns Owner info, or null without a running session or metadata
+ */
+async function readOwner(dir) {
+    if ((await probeDaemonSocket(sessionFilePathIn(dir, 'DAEMON_SOCKET'))) !== 'alive')
+        return null;
+    try {
+        const meta = JSON.parse(fs.readFileSync(sessionFilePathIn(dir, 'METADATA'), 'utf8'));
+        if (typeof meta.targetId !== 'string')
+            return null;
+        const launched = typeof meta.chromePid === 'number' && meta.chromePid > 0;
+        return { ...sessionOfDir(dir), dir, targetId: meta.targetId, launched };
+    }
+    catch (error) {
+        logDebugError(log, `read the metadata in ${dir}`, error);
+        return null;
+    }
+}
+/**
+ * Another running session that a new session attaching to a Chrome would
+ * collide with: one that launched that Chrome, or one driving the tab the
+ * new session would use.
+ *
+ * @param chromeTargetIds - Ids of every target of the Chrome being attached to
+ * @param targetId - Tab the new session would drive
+ * @returns The conflicting session, or null
+ */
+export async function findConflictingOwner(chromeTargetIds, targetId) {
+    const owners = await Promise.all(otherSessionDirs().map(readOwner));
+    return (owners.find((owner) => owner !== null &&
+        chromeTargetIds.includes(owner.targetId) &&
+        (owner.launched || owner.targetId === targetId)) ?? null);
+}
+//# sourceMappingURL=chromeOwners.js.map

package/dist/session/cleanup/staleSession.d.ts

@@ -26,6 +26,15 @@ export declare function removeStaleDaemonFiles(): Promise<boolean>;
  * @returns Chrome PID, or null
  */
 export declare function findOrphanedChrome(): number | null;
+/**
+ * Whether a process is the Chrome bdg launched for a session directory: its
+ * command line carries the directory's marker flag.
+ *
+ * @param pid - Process ID
+ * @param sessionDir - Session directory
+ * @returns True for that session's Chrome
+ */
+export declare function isSessionChrome(pid: number, sessionDir: string): boolean;
 /**
  * Kill the Chrome recorded in chrome.pid, if it is still the Chrome bdg launched
  * for this session directory (verified by its marker flag).
@@ -43,7 +52,8 @@ export declare function reapOrphanedChrome(): Promise<boolean>;
 /**
  * Read the PID of a live bdg daemon from daemon.pid.
  *
+ * @param dir - Session directory (defaults to the selected session's)
  * @returns Daemon PID if the process is alive and is a bdg daemon, else null
  */
-export declare function readLiveDaemonPid(): number | null;
+export declare function readLiveDaemonPid(dir?: string): number | null;
 //# sourceMappingURL=staleSession.d.ts.map

package/dist/session/cleanup/staleSession.js

@@ -10,8 +10,8 @@ import { chromeSessionMarkerFlag } from '../../connection/launcher/flagsBuilder.
 import { QueryCacheManager } from '../QueryCacheManager.js';
 import { clearChromePid, readChromePid } from '../chrome.js';
 import { probeDaemonSocket } from '../daemonSocket.js';
-import { getSessionDir, getSessionFilePath } from '../paths.js';
-import { readDaemonPid } from '../pid.js';
+import { getSessionDir, getSessionFilePath, sessionFilePathIn } from '../paths.js';
+import { readPidFromFile } from '../pid.js';
 import { createLogger, logDebugError } from '../../ui/logging/index.js';
 import { delay } from '../../utils/async.js';
 import { safeRemoveFile } from '../../utils/file.js';
@@ -66,13 +66,23 @@ export function findOrphanedChrome() {
     const chromePid = readChromePid();
     if (!chromePid)
         return null;
-    if (hasArgument(getProcessCommand(chromePid), chromeSessionMarkerFlag(getSessionDir()))) {
+    if (isSessionChrome(chromePid, getSessionDir()))
         return chromePid;
-    }
     log.debug(`PID ${chromePid} is no longer a bdg Chrome; dropping chrome.pid`);
     clearChromePid();
     return null;
 }
+/**
+ * Whether a process is the Chrome bdg launched for a session directory: its
+ * command line carries the directory's marker flag.
+ *
+ * @param pid - Process ID
+ * @param sessionDir - Session directory
+ * @returns True for that session's Chrome
+ */
+export function isSessionChrome(pid, sessionDir) {
+    return hasArgument(getProcessCommand(pid), chromeSessionMarkerFlag(sessionDir));
+}
 /**
  * Kill the Chrome recorded in chrome.pid, if it is still the Chrome bdg launched
  * for this session directory (verified by its marker flag).
@@ -113,10 +123,11 @@ export async function reapOrphanedChrome() {
 /**
  * Read the PID of a live bdg daemon from daemon.pid.
  *
+ * @param dir - Session directory (defaults to the selected session's)
  * @returns Daemon PID if the process is alive and is a bdg daemon, else null
  */
-export function readLiveDaemonPid() {
-    const pid = readDaemonPid();
+export function readLiveDaemonPid(dir = getSessionDir()) {
+    const pid = readPidFromFile(sessionFilePathIn(dir, 'DAEMON_PID'));
     if (!pid || !isProcessAlive(pid))
         return null;
     return hasArgument(getProcessCommand(pid), DAEMON_SCRIPT_PATH) ? pid : null;

package/dist/session/cleanup/userCommands.js

@@ -5,7 +5,7 @@ import * as fs from 'fs';
 import { killOrphanedChrome, readLiveDaemonPid, removeStaleDaemonFiles, } from './staleSession.js';
 import { isDaemonAlive } from '../daemonSocket.js';
 import { clearLastSessionEnd } from '../lastSession.js';
-import { getSessionFilePath } from '../paths.js';
+import { SESSION_STATE_FILES, getSessionFilePath } from '../paths.js';
 import { createLogger } from '../../ui/logging/index.js';
 import { getErrorMessage } from '../../utils/errors.js';
 const log = createLogger('cleanup');
@@ -39,15 +39,13 @@ export async function performSessionCleanup(options) {
         warnings,
     };
 }
-/** Files a session leaves behind (stale ones are what cleanup removes) */
-const SESSION_FILE_TYPES = ['DAEMON_PID', 'DAEMON_SOCKET', 'CHROME_PID', 'METADATA'];
 /**
  * How many session files exist.
  *
  * @returns Number of existing session files
  */
 function countSessionFiles() {
-    return SESSION_FILE_TYPES.filter((type) => fs.existsSync(getSessionFilePath(type))).length;
+    return SESSION_STATE_FILES.filter((type) => fs.existsSync(getSessionFilePath(type))).length;
 }
 /**
  * SIGKILL a live bdg daemon and wait briefly for its socket to go away.

package/dist/session/metadata.d.ts

@@ -4,7 +4,7 @@
  * Handles reading/writing session metadata (Chrome PID, CDP port, target info, etc).
  * WHY: Metadata persistence enables `bdg status` and other commands to inspect active sessions.
  */
-import type { TelemetryType } from '../types.js';
+import type { ColorScheme, TelemetryType, ViewportSize } from '../types.js';
 /**
  * Session metadata stored in ~/.bdg/session.meta.json
  */
@@ -18,6 +18,10 @@ export interface SessionMetadata {
     activeTelemetry?: TelemetryType[] | undefined;
     /** When `--timeout` stops the session (epoch ms) */
     autoStopAt?: number | undefined;
+    /** Viewport the page is emulated at (`--viewport`) */
+    viewport?: ViewportSize | undefined;
+    /** `prefers-color-scheme` the page is emulated with (`--color-scheme`) */
+    colorScheme?: ColorScheme | undefined;
 }
 /**
  * Options for reading session metadata.

package/dist/session/metadata.js

@@ -6,6 +6,7 @@
  */
 import * as fs from 'fs';
 import { createLogger } from '../ui/logging/index.js';
+import { sessionCommand } from '../ui/messages/sessionCommand.js';
 import { AtomicFileWriter } from '../utils/atomicFile.js';
 import { getErrorMessage } from '../utils/errors.js';
 import { getSessionFilePath, ensureSessionDir } from './paths.js';
@@ -20,7 +21,7 @@ const log = createLogger('session');
 function handleCorruptedMetadata(metaPath, error, options) {
     if (options?.warnOnCorruption) {
         log.info(`Session metadata corrupted (cannot read details): ${getErrorMessage(error)}`);
-        log.info('Troubleshooting: Run "bdg cleanup" to remove corrupted files');
+        log.info(`Troubleshooting: Run "${sessionCommand('bdg cleanup')}" to remove corrupted files`);
     }
     if (options?.selfHealOnCorruption) {
         try {