browser-debugger-cli 0.13.0 → 0.15.0

package/dist/connection/chromeIdentity.js

@@ -18,8 +18,9 @@
  * 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 { delay } from '../utils/async.js';
-import { fetchBrowserWsUrl } from '../utils/http.js';
+import { CDP_HTTP_TIMEOUT_MS, fetchBrowserWsUrl, probeDevToolsEndpoint, } from '../utils/http.js';
 import { isProcessAlive } from '../utils/process.js';
 import { ChromeLaunchError } from './errors.js';
 import { acceptsConnections } from './portReservation.js';
@@ -29,6 +30,8 @@ const LISTENING_PATTERN = /^DevTools listening on (ws:\/\/\S+)/;
 /** How long to wait for Chrome to announce its endpoint after the port answered */
 const ENDPOINT_WAIT_MS = 10000;
 const ENDPOINT_POLL_MS = 50;
+/** Shortest wait for one answer, also when the deadline has passed */
+const MIN_ANSWER_WAIT_MS = 1000;
 const log = createLogger('chrome');
 /**
  * Find the endpoint Chrome announced in its output (the last announcement).
@@ -75,32 +78,75 @@ export async function waitForDevToolsEndpoint(logs, isRunning, timeoutMs = ENDPO
  * Check that the Chrome answering on 127.0.0.1:<port> is the one just
  * launched, so bdg never drives another session's browser.
  *
+ * A Chrome that announced 127.0.0.1:<port> but does not answer yet (a slow
+ * start, its `/json/version` request timing out) is asked again until the
+ * deadline; only an answer from something else is a port conflict. A Chrome
+ * 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
+ *   longest wait for its announcement and its answer
  * @throws ChromeLaunchError: 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
+ *   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 } = options;
+    const { logs, port, pid, timeoutMs = ENDPOINT_WAIT_MS } = options;
+    const started = Date.now();
     const isRunning = () => isProcessAlive(pid);
     const endpoint = await waitForDevToolsEndpoint(logs, isRunning, timeoutMs);
-    if (!endpoint && !isRunning()) {
-        throw new ChromeLaunchError(`Chrome died immediately after launch (PID: ${pid})`, {
-            issue: { code: 'CHROME_DIED_AFTER_LAUNCH', context: { port, pid } },
-        });
-    }
+    if (!endpoint && !isRunning())
+        throw diedError(port, pid);
     if (!endpoint)
         return acceptUnannouncedChrome(logs, port);
     if (endpoint.port !== port) {
         throw portTakenError(port, `Chrome listens on port ${endpoint.port} instead`);
     }
-    const answering = await fetchBrowserWsUrl(port, log);
-    if (!answering || new URL(answering).pathname !== endpoint.browserPath) {
-        throw portTakenError(port, `another process answers on 127.0.0.1 (Chrome listens on ${endpoint.host})`);
+    const onLoopback = endpoint.host === '127.0.0.1';
+    const deadline = onLoopback ? started + timeoutMs : Date.now();
+    const answer = await waitForAnswer(port, deadline, isRunning);
+    if (answer.kind === 'devtools' && new URL(answer.wsUrl).pathname === endpoint.browserPath) {
+        log.debug(`Chrome on port ${port} is the launched one (${endpoint.browserPath})`);
+        return;
+    }
+    if (answer.kind === 'unreachable' && !isRunning())
+        throw diedError(port, pid);
+    if (answer.kind === 'unreachable' && onLoopback) {
+        throw slowStartError(port, Date.now() - started);
+    }
+    throw portTakenError(port, portTakenByReason(answerSource(answer), endpoint.host));
+}
+/**
+ * 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).
+ *
+ * @param port - Requested port
+ * @param deadline - Time (ms since epoch) to stop asking
+ * @param isRunning - Whether Chrome is still running
+ * @returns The first answer, or the last `unreachable` result
+ */
+async function waitForAnswer(port, deadline, isRunning) {
+    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)
+            return answer;
+        await delay(ENDPOINT_POLL_MS);
     }
-    log.debug(`Chrome on port ${port} is the launched one (${endpoint.browserPath})`);
+}
+/**
+ * What answered on 127.0.0.1:<port> instead of the launched Chrome.
+ *
+ * @param answer - The answer
+ * @returns A browser, another process, or nothing
+ */
+function answerSource(answer) {
+    if (answer.kind === 'devtools')
+        return 'browser';
+    return answer.kind === 'not-devtools' ? 'process' : 'nothing';
 }
 /**
  * Accept a Chrome that did not announce its endpoint, if a browser answers on
@@ -128,6 +174,32 @@ async function acceptUnannouncedChrome(logs, port) {
     }
     log.info(`Warning: ${missing}; using the browser on 127.0.0.1:${port}, which was free before the launch`);
 }
+/**
+ * The error for a Chrome that exited during the launch checks.
+ *
+ * @param port - Requested port
+ * @param pid - Chrome's PID
+ * @returns Launch error with the CHROME_DIED_AFTER_LAUNCH issue
+ */
+function diedError(port, pid) {
+    return new ChromeLaunchError(`Chrome died immediately after launch (PID: ${pid})`, {
+        issue: { code: 'CHROME_DIED_AFTER_LAUNCH', context: { port, pid } },
+    });
+}
+/**
+ * The error for a Chrome that announced the port but did not answer on it in
+ * time.
+ *
+ * @param port - Requested port
+ * @param waitedMs - How long bdg waited
+ * @returns Launch error with the CHROME_LAUNCH_FAILED issue
+ */
+function slowStartError(port, waitedMs) {
+    const reason = chromeNotAnsweringReason(port, waitedMs);
+    return new ChromeLaunchError(reason, {
+        issue: { code: 'CHROME_LAUNCH_FAILED', context: { port, reason } },
+    });
+}
 /**
  * The error for a port another process answers on.
  *

package/dist/connection/launcher/flagsBuilder.d.ts

@@ -56,5 +56,51 @@ export declare function needsNoSandbox(): boolean;
  * @returns True if running in Docker, false otherwise
  */
 export declare function isDocker(): boolean;
+/**
+ * Remove `HEADLESS` from this process's environment.
+ *
+ * chrome-launcher adds a bare `--headless` whenever the launching process has
+ * a non-empty `HEADLESS` variable (even `0` or `false`), whatever its
+ * `envVars` option says, which would make `--no-headless` launch headless.
+ * The daemon calls this before it launches Chrome.
+ *
+ * @param env - Environment to clean (defaults to `process.env`)
+ */
+export declare function dropLauncherHeadlessEnv(env?: NodeJS.ProcessEnv): void;
+/**
+ * Build Chrome flags array from launch options.
+ *
+ * Uses chrome-launcher default flags as base (unless ignoreDefaultFlags is true)
+ * and layers bdg-specific overrides on top. Headless mode uses the new headless
+ * implementation for better compatibility.
+ *
+ * When running in Docker, automatically adds GPU-disabling flags to work around
+ * graphics limitations in containerized environments.
+ *
+ * Custom flags are passed via the chromeFlags option. The BDG_CHROME_FLAGS env var
+ * is parsed by the CLI and merged into chromeFlags before reaching this function.
+ * Feature lists from all sources end up in one `--disable-features` (and one
+ * `--enable-features`) flag, and each flag appears once.
+ *
+ * @param options - Launch options containing flag preferences
+ * @returns Array of Chrome command-line flags
+ *
+ * @example
+ * ```typescript
+ * // Standard flags
+ * const flags = buildChromeFlags({ port: 9222 });
+ *
+ * // Headless with custom flags
+ * const flags = buildChromeFlags({
+ *   port: 9222,
+ *   headless: true,
+ *   chromeFlags: ['--window-size=1920,1080']
+ * });
+ *
+ * // Docker environment (auto-detects)
+ * const flags = buildChromeFlags({ port: 9222 });
+ * // Includes --disable-gpu, --no-sandbox if in Docker
+ * ```
+ */
 export declare function buildChromeFlags(options: FlagsBuilderOptions): string[];
 //# sourceMappingURL=flagsBuilder.d.ts.map

package/dist/connection/launcher/flagsBuilder.js

@@ -68,6 +68,103 @@ export function isDocker() {
         return false;
     }
 }
+const DISABLE_FEATURES = '--disable-features=';
+const ENABLE_FEATURES = '--enable-features=';
+/**
+ * Flags that bdg merges into one: Chrome reads only the last occurrence of
+ * these comma-separated feature lists, and chrome-launcher's defaults, bdg and
+ * users all pass them. `--disable-blink-features`/`--enable-blink-features`
+ * are not merged (neither bdg nor the defaults pass them), nor is `--js-flags`
+ * (space-separated V8 flags, not a feature list).
+ */
+const FEATURE_LIST_FLAGS = [DISABLE_FEATURES, ENABLE_FEATURES];
+/**
+ * Bare name of a feature-list entry, without a `<Trial` or `:params` suffix.
+ *
+ * @param entry - Entry such as `Foo<Trial` or `Foo:param/1`
+ * @returns Feature name
+ */
+function featureName(entry) {
+    return entry.split(/[<:]/)[0] ?? entry;
+}
+/**
+ * Remove disabled features that are also enabled.
+ *
+ * Chrome lets `--disable-features` win over `--enable-features`, so without
+ * this a user's `--enable-features=MediaRouter` could not re-enable a feature
+ * chrome-launcher disables by default.
+ *
+ * @param features - Merged values per feature-list flag (changed in place)
+ */
+function dropReEnabledFeatures(features) {
+    const enabled = new Set([...(features.get(ENABLE_FEATURES) ?? [])].map(featureName));
+    const disabled = features.get(DISABLE_FEATURES);
+    disabled?.forEach((entry) => {
+        if (enabled.has(featureName(entry)))
+            disabled.delete(entry);
+    });
+}
+/**
+ * Merge every `--disable-features=` (and `--enable-features=`) flag into one
+ * and drop repeated flags.
+ *
+ * Chrome applies only the last occurrence of a feature-list flag, so bdg's or
+ * the user's list would otherwise switch chrome-launcher's defaults back on.
+ * The merged flag keeps the first one's position; its values keep their order
+ * without repeats, and an enabled feature is never also disabled. Only
+ * entries starting with `-` are deduplicated, so positional arguments such as
+ * URLs are passed as given.
+ *
+ * @param flags - Chrome flags in launch order
+ * @returns Flags with at most one flag per feature list and no repeated flags
+ */
+function mergeFeatureFlags(flags) {
+    const features = new Map();
+    const merged = [];
+    for (const flag of flags) {
+        const prefix = FEATURE_LIST_FLAGS.find((p) => flag.startsWith(p));
+        if (prefix) {
+            if (!features.has(prefix))
+                merged.push(prefix);
+            const values = flag.slice(prefix.length).split(',').filter(Boolean);
+            features.set(prefix, new Set([...(features.get(prefix) ?? []), ...values]));
+        }
+        else if (!flag.startsWith('-') || !merged.includes(flag)) {
+            merged.push(flag);
+        }
+    }
+    dropReEnabledFeatures(features);
+    return merged.flatMap((flag) => {
+        const values = features.get(flag);
+        if (!values)
+            return [flag];
+        return values.size > 0 ? [flag + [...values].join(',')] : [];
+    });
+}
+/**
+ * Remove `HEADLESS` from this process's environment.
+ *
+ * chrome-launcher adds a bare `--headless` whenever the launching process has
+ * a non-empty `HEADLESS` variable (even `0` or `false`), whatever its
+ * `envVars` option says, which would make `--no-headless` launch headless.
+ * The daemon calls this before it launches Chrome.
+ *
+ * @param env - Environment to clean (defaults to `process.env`)
+ */
+export function dropLauncherHeadlessEnv(env = process.env) {
+    delete env['HEADLESS'];
+}
+/**
+ * chrome-launcher's default flags (plus its Linux sandbox flag). bdg passes
+ * them itself and tells chrome-launcher to skip its own copy, so each flag
+ * appears once; chrome-launcher adds `--remote-debugging-port`.
+ *
+ * @returns Default flags
+ */
+function defaultFlags() {
+    const flags = chromeLauncher.Launcher.defaultFlags();
+    return process.platform === 'linux' ? [...flags, '--disable-setuid-sandbox'] : flags;
+}
 /**
  * Build Chrome flags array from launch options.
  *
@@ -80,6 +177,8 @@ export function isDocker() {
  *
  * Custom flags are passed via the chromeFlags option. The BDG_CHROME_FLAGS env var
  * is parsed by the CLI and merged into chromeFlags before reaching this function.
+ * Feature lists from all sources end up in one `--disable-features` (and one
+ * `--enable-features`) flag, and each flag appears once.
  *
  * @param options - Launch options containing flag preferences
  * @returns Array of Chrome command-line flags
@@ -101,17 +200,6 @@ export function isDocker() {
  * // Includes --disable-gpu, --no-sandbox if in Docker
  * ```
  */
-/**
- * chrome-launcher's default flags (plus its Linux sandbox flag). bdg passes
- * them itself and tells chrome-launcher to skip its own copy, so each flag
- * appears once; chrome-launcher adds `--remote-debugging-port`.
- *
- * @returns Default flags
- */
-function defaultFlags() {
-    const flags = chromeLauncher.Launcher.defaultFlags();
-    return process.platform === 'linux' ? [...flags, '--disable-setuid-sandbox'] : flags;
-}
 export function buildChromeFlags(options) {
     const baseFlags = options.ignoreDefaultFlags ? [] : defaultFlags();
     const bdgFlags = [
@@ -120,18 +208,14 @@ export function buildChromeFlags(options) {
     ];
     const dockerFlags = isDocker() ? DOCKER_CHROME_FLAGS : [];
     const sandboxFlags = needsNoSandbox() ? ['--no-sandbox'] : [];
-    // Custom flags from CLI option (env var BDG_CHROME_FLAGS is parsed by CLI and passed here)
     const customFlags = options.chromeFlags ?? [];
-    if (options.headless) {
-        return [
-            HEADLESS_FLAG,
-            ...baseFlags,
-            ...bdgFlags,
-            ...dockerFlags,
-            ...sandboxFlags,
-            ...customFlags,
-        ];
-    }
-    return [...baseFlags, ...bdgFlags, ...dockerFlags, ...sandboxFlags, ...customFlags];
+    return mergeFeatureFlags([
+        ...(options.headless ? [HEADLESS_FLAG] : []),
+        ...baseFlags,
+        ...bdgFlags,
+        ...dockerFlags,
+        ...sandboxFlags,
+        ...customFlags,
+    ]);
 }
 //# sourceMappingURL=flagsBuilder.js.map

package/dist/connection/launcher.d.ts

@@ -4,7 +4,7 @@ import type { Options as ChromeLaunchOptions } from 'chrome-launcher';
  * Options that control how Chrome is launched for CDP sessions.
  * Extended to support chrome-launcher advanced features.
  */
-export interface LaunchOptions extends Pick<ChromeLaunchOptions, 'logLevel' | 'connectionPollInterval' | 'maxConnectionRetries' | 'portStrictMode' | 'envVars' | 'handleSIGINT' | 'ignoreDefaultFlags' | 'chromeFlags' | 'chromePath'> {
+export interface LaunchOptions extends Pick<ChromeLaunchOptions, 'logLevel' | 'connectionPollInterval' | 'maxConnectionRetries' | 'portStrictMode' | 'envVars' | 'ignoreDefaultFlags' | 'chromeFlags' | 'chromePath'> {
     /** Remote debugging port (defaults to 9222 when omitted) */
     port?: number;
     /**

package/dist/connection/launcher.js

@@ -2,7 +2,7 @@ import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
 import * as chromeLauncher from 'chrome-launcher';
-import { BDG_CHROME_PREFS, DEFAULT_CDP_PORT, CHROME_PROFILE_DIR, DEFAULT_CHROME_LOG_LEVEL, DEFAULT_CHROME_HANDLE_SIGINT, } from '../constants.js';
+import { BDG_CHROME_PREFS, DEFAULT_CDP_PORT, CHROME_PROFILE_DIR, DEFAULT_CHROME_LOG_LEVEL, } from '../constants.js';
 import { makeDirectory } from '../utils/directories.js';
 import { getErrorMessage } from '../utils/errors.js';
 import { filterDefined } from '../utils/objects.js';
@@ -224,7 +224,6 @@ function buildChromeOptions(options) {
     const chromePathOverride = resolveChromeBinary(options);
     return {
         logLevel: options.logLevel ?? DEFAULT_CHROME_LOG_LEVEL,
-        handleSIGINT: options.handleSIGINT ?? DEFAULT_CHROME_HANDLE_SIGINT,
         ignoreDefaultFlags: true,
         chromeFlags: buildChromeFlags(options),
         userDataDir,

package/dist/constants.d.ts

@@ -12,10 +12,6 @@ export declare const DEFAULT_CDP_PORT = 9222;
  * Default Chrome launcher log level for quiet operation
  */
 export declare const DEFAULT_CHROME_LOG_LEVEL = "silent";
-/**
- * Default SIGINT handling - bdg handles signals, not chrome-launcher
- */
-export declare const DEFAULT_CHROME_HANDLE_SIGINT = false;
 /**
  * Persistent Chrome profile directory path (relative to user home)
  */
@@ -58,7 +54,8 @@ export declare const DOCKER_CHROME_FLAGS: string[];
  */
 export declare const BDG_CHROME_PREFS: Record<string, unknown>;
 /**
- * Maximum network requests to collect before dropping new requests
+ * Finished network requests kept: past this the oldest are dropped, so the
+ * newest are kept (requests in flight are never dropped)
  * Prevents memory issues in long-running sessions with high network activity
  */
 export declare const MAX_NETWORK_REQUESTS = 10000;
@@ -88,6 +85,24 @@ export declare const OBJECT_EXPANSION_FAILURE_THRESHOLD = 5;
  * Can be overridden with --max-body-size flag
  */
 export declare const MAX_RESPONSE_SIZE: number;
+/**
+ * Total size of the response bodies a session keeps (100MB)
+ * Past this the oldest bodies are replaced by a placeholder; their requests stay
+ */
+export declare const MAX_TOTAL_BODY_BYTES: number;
+/**
+ * Characters of one value `dom get --raw` and `dom eval` print (human output,
+ * and eval string results and outer HTML in JSON)
+ */
+export declare const MAX_VALUE_LENGTH = 20000;
+/**
+ * Characters of a console message text in human output (`console`, `peek`)
+ */
+export declare const MAX_CONSOLE_TEXT_LENGTH = 200;
+/**
+ * Characters of a console message text in JSON output (`console`, `peek`)
+ */
+export declare const MAX_CONSOLE_JSON_TEXT_LENGTH = 10000;
 /**
  * Total Chrome network buffer size (50MB)
  * Limits total memory used by Chrome for preserving network payloads
@@ -103,6 +118,17 @@ export declare const CHROME_NETWORK_BUFFER_PER_RESOURCE: number;
  * Limits size of POST body data included in requestWillBeSent notification
  */
 export declare const CHROME_POST_DATA_LIMIT: number;
+/** Matches `dom query` and `dom a11y query` list with `--json` and no `--limit` */
+export declare const QUERY_JSON_LIST_LIMIT = 100;
+/** Elements of an array result `dom eval --json` lists (the rest are counted as omitted) */
+export declare const EVAL_JSON_ARRAY_LIMIT = 100;
+/** Matches `dom layout` measures per command (the rest are counted as omitted) */
+export declare const LAYOUT_ELEMENT_LIMIT = 100;
+/**
+ * Requests listed in an action's result (a click that loads a page triggers
+ * its whole load); notable ones are kept before assets
+ */
+export declare const MAX_TRIGGERED_REQUESTS = 50;
 /**
  * Default page readiness timeout (2 seconds)
  * Maximum time to wait for page to be ready before proceeding

package/dist/constants.js

@@ -15,10 +15,6 @@ export const DEFAULT_CDP_PORT = 9222;
  * Default Chrome launcher log level for quiet operation
  */
 export const DEFAULT_CHROME_LOG_LEVEL = 'silent';
-/**
- * Default SIGINT handling - bdg handles signals, not chrome-launcher
- */
-export const DEFAULT_CHROME_HANDLE_SIGINT = false;
 /**
  * Persistent Chrome profile directory path (relative to user home)
  */
@@ -87,7 +83,8 @@ export const BDG_CHROME_PREFS = {
 // DATA COLLECTION LIMITS
 // ============================================================================
 /**
- * Maximum network requests to collect before dropping new requests
+ * Finished network requests kept: past this the oldest are dropped, so the
+ * newest are kept (requests in flight are never dropped)
  * Prevents memory issues in long-running sessions with high network activity
  */
 export const MAX_NETWORK_REQUESTS = 10000;
@@ -120,6 +117,27 @@ export const OBJECT_EXPANSION_FAILURE_THRESHOLD = 5;
  * Can be overridden with --max-body-size flag
  */
 export const MAX_RESPONSE_SIZE = 5 * 1024 * 1024; // 5MB
+/**
+ * Total size of the response bodies a session keeps (100MB)
+ * Past this the oldest bodies are replaced by a placeholder; their requests stay
+ */
+export const MAX_TOTAL_BODY_BYTES = 100 * 1024 * 1024;
+// ============================================================================
+// OUTPUT VALUE LIMITS (lifted by --full)
+// ============================================================================
+/**
+ * Characters of one value `dom get --raw` and `dom eval` print (human output,
+ * and eval string results and outer HTML in JSON)
+ */
+export const MAX_VALUE_LENGTH = 20_000;
+/**
+ * Characters of a console message text in human output (`console`, `peek`)
+ */
+export const MAX_CONSOLE_TEXT_LENGTH = 200;
+/**
+ * Characters of a console message text in JSON output (`console`, `peek`)
+ */
+export const MAX_CONSOLE_JSON_TEXT_LENGTH = 10_000;
 // ============================================================================
 // CHROME CDP BUFFER LIMITS
 // ============================================================================
@@ -139,6 +157,20 @@ export const CHROME_NETWORK_BUFFER_PER_RESOURCE = 10 * 1024 * 1024; // 10MB
  */
 export const CHROME_POST_DATA_LIMIT = 1 * 1024 * 1024; // 1MB
 // ============================================================================
+// JSON LIST LIMITS
+// ============================================================================
+/** Matches `dom query` and `dom a11y query` list with `--json` and no `--limit` */
+export const QUERY_JSON_LIST_LIMIT = 100;
+/** Elements of an array result `dom eval --json` lists (the rest are counted as omitted) */
+export const EVAL_JSON_ARRAY_LIMIT = 100;
+/** Matches `dom layout` measures per command (the rest are counted as omitted) */
+export const LAYOUT_ELEMENT_LIMIT = 100;
+/**
+ * Requests listed in an action's result (a click that loads a page triggers
+ * its whole load); notable ones are kept before assets
+ */
+export const MAX_TRIGGERED_REQUESTS = 50;
+// ============================================================================
 // TIMEOUTS & INTERVALS
 // ============================================================================
 /**

package/dist/daemon/SessionController.js

@@ -245,6 +245,8 @@ export class SessionController {
                             network: data.totalNetwork,
                             console: data.totalConsole,
                             ...(data.droppedConsole && { consoleDropped: data.droppedConsole }),
+                            ...(data.droppedNetwork && { networkDropped: data.droppedNetwork }),
+                            ...(data.evictedNetworkBodies && { networkBodiesEvicted: data.evictedNetworkBodies }),
                         },
                         currentNavigationId: data.currentNavigationId,
                         ...(data.pageCrashedAt !== undefined && { pageCrashedAt: data.pageCrashedAt }),

package/dist/daemon/launcher.d.ts

@@ -16,6 +16,8 @@ export interface SpawnedDaemon {
  * Ensure a daemon is running, spawning one if needed.
  *
  * @returns The daemon it spawned, or undefined when one was already running
+ * @throws SessionDirError if the session directory is unusable or untrusted
+ *   (checked first, so a socket planted there is never taken for a daemon)
  * @throws DaemonStartupError if the daemon script is missing or the daemon
  *   does not accept connections in time
  */
@@ -24,9 +26,21 @@ export declare function launchDaemon(): Promise<SpawnedDaemon | undefined>;
  * Check that the session directory can hold the daemon's files before
  * spawning it (otherwise the daemon dies and only its log says why).
  *
- * @throws SessionDirError (103) for a file or a path that cannot hold a
- *   directory (a pseudo-filesystem like `/proc`), (81) for a too-long path
- *   like a named session's, (82) when not writable
+ * @throws SessionDirError (103) for a file, a path that cannot hold a
+ *   directory (a pseudo-filesystem like `/proc`) or an untrusted directory
+ *   (see {@link secureSessionDir}, which also tightens the user's own 0755
+ *   directories to 0700), (81) for a too-long path like a named session's,
+ *   (82) when not writable
  */
 export declare function assertUsableSessionDir(): void;
+/**
+ * Open the daemon log for the daemon's output, creating it 0600. A symlink in
+ * its place is refused, not followed: it would append the log to the file it
+ * points to.
+ *
+ * @param logPath - Daemon log path
+ * @returns File descriptor
+ * @throws SessionDirError (103) when it cannot be opened (`ELOOP` for a symlink)
+ */
+export declare function openDaemonLog(logPath: string): number;
 //# sourceMappingURL=launcher.d.ts.map

package/dist/daemon/launcher.js

@@ -10,10 +10,10 @@ import { spawn } from 'child_process';
 import fs from 'fs';
 import { join } from 'path';
 import { DaemonStartupError, SessionDirError } from './errors.js';
-import { sessionDirIsFileError, sessionDirNotWritableError, socketPathTooLongError, } from '../errors/messages.js';
+import { daemonLogNotOpenedError, sessionDirIsFileError, sessionDirNotWritableError, socketPathTooLongError, untrustedSessionDirError, } from '../errors/messages.js';
 import { killSessionChromes, readLiveDaemonPid } from '../session/cleanup/staleSession.js';
 import { isDaemonAlive, isDaemonSocketGone } from '../session/daemonSocket.js';
-import { MAX_DAEMON_SOCKET_PATH_BYTES, ensureSessionDir, getSessionDir, getSessionFilePath, } from '../session/paths.js';
+import { MAX_DAEMON_SOCKET_PATH_BYTES, ensureSessionDir, getSessionDir, getSessionFilePath, secureSessionDir, } from '../session/paths.js';
 import { createLogger } from '../ui/logging/index.js';
 import { delay } from '../utils/async.js';
 import { directoryProblem } from '../utils/directories.js';
@@ -28,10 +28,13 @@ const DAEMON_READY_POLL_MS = 20;
  * Ensure a daemon is running, spawning one if needed.
  *
  * @returns The daemon it spawned, or undefined when one was already running
+ * @throws SessionDirError if the session directory is unusable or untrusted
+ *   (checked first, so a socket planted there is never taken for a daemon)
  * @throws DaemonStartupError if the daemon script is missing or the daemon
  *   does not accept connections in time
  */
 export async function launchDaemon() {
+    assertUsableSessionDir();
     if (await isDaemonAlive()) {
         log.debug('Daemon already running');
         return undefined;
@@ -39,11 +42,10 @@ export async function launchDaemon() {
     if (!fs.existsSync(DAEMON_SCRIPT_PATH)) {
         throw new DaemonStartupError(`Daemon script not found at ${DAEMON_SCRIPT_PATH}. Did you run 'npm run build'?`, 'DAEMON_SCRIPT_NOT_FOUND');
     }
-    assertUsableSessionDir();
     await stopUnreachableDaemon();
     const logPath = join(getSessionDir(), 'daemon.log');
     rotateLog(logPath);
-    const logFd = fs.openSync(logPath, 'a');
+    const logFd = openDaemonLog(logPath);
     log.debug(`Starting daemon: ${DAEMON_SCRIPT_PATH}`);
     const daemon = spawn(process.execPath, [DAEMON_SCRIPT_PATH], {
         detached: true,
@@ -97,9 +99,11 @@ async function stopUnreachableDaemon() {
  * Check that the session directory can hold the daemon's files before
  * spawning it (otherwise the daemon dies and only its log says why).
  *
- * @throws SessionDirError (103) for a file or a path that cannot hold a
- *   directory (a pseudo-filesystem like `/proc`), (81) for a too-long path
- *   like a named session's, (82) when not writable
+ * @throws SessionDirError (103) for a file, a path that cannot hold a
+ *   directory (a pseudo-filesystem like `/proc`) or an untrusted directory
+ *   (see {@link secureSessionDir}, which also tightens the user's own 0755
+ *   directories to 0700), (81) for a too-long path like a named session's,
+ *   (82) when not writable
  */
 export function assertUsableSessionDir() {
     const dir = getSessionDir();
@@ -116,6 +120,9 @@ export function assertUsableSessionDir() {
     if (problem) {
         fail(sessionDirNotWritableError(dir, problem.reason), problem.denied ? EXIT_CODES.PERMISSION_DENIED : EXIT_CODES.SESSION_FILE_ERROR);
     }
+    const untrusted = secureSessionDir(dir);
+    if (untrusted)
+        fail(untrustedSessionDirError(untrusted));
     try {
         ensureSessionDir();
         fs.accessSync(dir, fs.constants.W_OK);
@@ -126,6 +133,29 @@ export function assertUsableSessionDir() {
         fail(sessionDirNotWritableError(dir, code ?? getErrorMessage(error)), denied ? EXIT_CODES.PERMISSION_DENIED : EXIT_CODES.SESSION_FILE_ERROR);
     }
 }
+/** Flags opening the daemon log for appending, refusing (not following) a symlink */
+const DAEMON_LOG_FLAGS = fs.constants.O_WRONLY |
+    fs.constants.O_APPEND |
+    fs.constants.O_CREAT |
+    (fs.constants.O_NOFOLLOW ?? 0);
+/**
+ * Open the daemon log for the daemon's output, creating it 0600. A symlink in
+ * its place is refused, not followed: it would append the log to the file it
+ * points to.
+ *
+ * @param logPath - Daemon log path
+ * @returns File descriptor
+ * @throws SessionDirError (103) when it cannot be opened (`ELOOP` for a symlink)
+ */
+export function openDaemonLog(logPath) {
+    try {
+        return fs.openSync(logPath, DAEMON_LOG_FLAGS, 0o600);
+    }
+    catch (error) {
+        const err = daemonLogNotOpenedError(logPath, error.code ?? getErrorMessage(error));
+        throw new SessionDirError(err.message, err.suggestion);
+    }
+}
 /** Size above which the daemon log is rotated when a daemon starts */
 const MAX_LOG_BYTES = 5 * 1024 * 1024;
 /**

package/dist/daemon/session/Session.d.ts

@@ -83,7 +83,8 @@ export declare class Session {
      * Execute a registered command against this session. After a renderer
      * crash only {@link RUN_ON_CRASHED_PAGE} commands run (`bdg cdp` only for
      * {@link CRASH_SAFE_CDP} methods); others fail with exit 107 instead of
-     * waiting for a page that cannot answer.
+     * waiting for a page that cannot answer. Commands that may change the page
+     * drop `dom inspect`'s kept matched rules ({@link withMatchedStylesReset}).
      *
      * @param name - Command name
      * @param params - Command parameters