@browserbridge/bbx 1.7.0 → 1.7.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@browserbridge/bbx",
-  "version": "1.7.0",
+  "version": "1.7.2",
   "private": false,
   "keywords": [
     "agent-tools",

package/packages/agent-client/src/cli.js

@@ -20,6 +20,7 @@ import { restartBridgeDaemon } from '../../native-host/src/daemon-process.js';
 import { uninstallNativeManifest } from '../../native-host/src/install-manifest.js';
 import {
   createRuntimeContext,
+  getProtocolVersion,
   METHODS,
   summarizeBatchErrorItem,
   summarizeBatchResponseItem,
@@ -628,7 +629,7 @@ async function main() {
               evidence: null,
               durationMs: 0,
               approxTokens: 0,
-              meta: { protocol_version: '1.0' },
+              meta: { protocol_version: getProtocolVersion() },
               error: {
                 code: 'INVALID_REQUEST',
                 message: 'Each batch call needs a method.',
@@ -645,7 +646,7 @@ async function main() {
               evidence: null,
               durationMs: 0,
               approxTokens: 0,
-              meta: { protocol_version: '1.0' },
+              meta: { protocol_version: getProtocolVersion() },
               error: {
                 code: 'INVALID_REQUEST',
                 message: `Unknown bridge method "${call.method}".`,

package/packages/agent-client/src/client.js

@@ -1,14 +1,16 @@
 // @ts-check
 
 import { EventEmitter, once } from 'node:events';
+import fs from 'node:fs';
 import net from 'node:net';
 import { randomUUID } from 'node:crypto';
 
 import {
   createRequest,
   DEFAULT_CLIENT_REQUEST_TIMEOUT_MS,
-  PROTOCOL_VERSION,
+  getProtocolVersion,
   parseJsonLines,
+  setProtocolPackageVersion,
 } from '../../protocol/src/index.js';
 import {
   createSocketBridgeTransport,
@@ -26,6 +28,21 @@ import { restartBridgeDaemon } from '../../native-host/src/daemon-process.js';
 /** @typedef {import('./types.js').PendingRequest} PendingRequest */
 /** @typedef {import('./types.js').ProtocolHealthResult} ProtocolHealthResult */
 
+setProtocolPackageVersion(loadPackageVersion());
+
+/**
+ * @returns {string | null}
+ */
+function loadPackageVersion() {
+  try {
+    const raw = fs.readFileSync(new URL('../../../package.json', import.meta.url), 'utf8');
+    const parsed = JSON.parse(raw);
+    return parsed && typeof parsed.version === 'string' ? parsed.version : null;
+  } catch {
+    return null;
+  }
+}
+
 /**
  * @param {string} left
  * @param {string} right
@@ -57,6 +74,18 @@ function createTimeoutError(method, timeoutMs) {
   return error;
 }
 
+/**
+ * npm exec often runs a checkout-local CLI against an already-connected global
+ * daemon. In that mode, protocol drift should warn instead of replacing the
+ * user's working daemon and temporarily disconnecting the extension.
+ *
+ * @param {NodeJS.ProcessEnv} [env=process.env]
+ * @returns {boolean}
+ */
+function shouldAutoRestartDaemonOnVersionMismatch(env = process.env) {
+  return env.npm_command !== 'exec';
+}
+
 /**
  * @param {net.Socket} socket
  * @param {string} line
@@ -83,7 +112,7 @@ export class BridgeClient extends EventEmitter {
     clientId = `agent_${randomUUID()}`,
     defaultTimeoutMs = DEFAULT_CLIENT_REQUEST_TIMEOUT_MS,
     autoReconnect = false,
-    restartDaemonOnVersionMismatch = true,
+    restartDaemonOnVersionMismatch = shouldAutoRestartDaemonOnVersionMismatch(),
     restartDaemonFn = restartBridgeDaemon,
     authToken = undefined,
   } = {}) {
@@ -390,9 +419,16 @@ export class BridgeClient extends EventEmitter {
           ? healthResult.supported_versions
           : [];
     const latestRemote = remoteVersions[0];
+    if (
+      healthResult?.extensionConnected === true &&
+      Array.isArray(healthResult.supported_versions) &&
+      !healthResult.supported_versions.includes(getProtocolVersion())
+    ) {
+      return false;
+    }
     return (
       typeof latestRemote === 'string' &&
-      compareProtocolVersions(latestRemote, PROTOCOL_VERSION) < 0
+      compareProtocolVersions(latestRemote, getProtocolVersion()) < 0
     );
   }
 
@@ -436,20 +472,21 @@ export class BridgeClient extends EventEmitter {
     if (remoteVersions.length === 0) {
       return {
         compatible: true,
-        localVersion: PROTOCOL_VERSION,
+        localVersion: getProtocolVersion(),
         remoteVersions,
       };
     }
-    const compatible = remoteVersions.includes(PROTOCOL_VERSION);
+    const localVersion = getProtocolVersion();
+    const compatible = remoteVersions.includes(localVersion);
     return {
       compatible,
-      localVersion: PROTOCOL_VERSION,
+      localVersion,
       remoteVersions,
       ...(!compatible && {
         warning:
           typeof healthResult?.migration_hint === 'string' && healthResult.migration_hint
             ? healthResult.migration_hint
-            : `Protocol mismatch: client speaks ${PROTOCOL_VERSION} but remote supports [${remoteVersions.join(', ')}]. Update the ${remoteVersions[0] > PROTOCOL_VERSION ? 'client (npm)' : 'extension'} to match.`,
+            : `Protocol mismatch: client speaks ${localVersion} but remote supports [${remoteVersions.join(', ')}]. Update the ${remoteVersions[0] > localVersion ? 'client (npm)' : 'extension'} to match.`,
       }),
     };
   }

package/packages/agent-client/src/mcp-config.js

@@ -3,7 +3,6 @@
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
-import { fileURLToPath } from 'node:url';
 
 /** @typedef {import('./types.js').McpClientName} McpClientName */
 
@@ -40,8 +39,8 @@ export function isMcpClientName(value) {
 }
 
 const BROWSER_BRIDGE_SERVER_NAME = 'browser-bridge';
-const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../..');
-const mcpServerBinPath = path.join(packageRoot, 'packages', 'mcp-server', 'src', 'bin.js');
+const MCP_COMMAND = 'bbx';
+const MCP_ARGS = Object.freeze(['mcp', 'serve']);
 
 /**
  * @returns {string}
@@ -95,15 +94,15 @@ export function getMcpConfigShape(clientName) {
  */
 function createBaseServerConfig(clientName) {
   const serverConfig = {
-    command: process.execPath,
-    args: [mcpServerBinPath],
+    command: MCP_COMMAND,
+    args: [...MCP_ARGS],
     env: {},
   };
 
   if (clientName === 'opencode') {
     return {
       type: 'local',
-      command: [process.execPath, mcpServerBinPath],
+      command: [MCP_COMMAND, ...MCP_ARGS],
     };
   }
   return serverConfig;
@@ -135,8 +134,8 @@ export function buildMcpConfig(clientName) {
     return {
       mcp_servers: {
         [BROWSER_BRIDGE_SERVER_NAME]: {
-          command: process.execPath,
-          args: [mcpServerBinPath],
+          command: MCP_COMMAND,
+          args: [...MCP_ARGS],
         },
       },
     };
@@ -267,8 +266,8 @@ export async function getMcpConfigPaths(clientName, options) {
 function formatCodexServerBlock() {
   return [
     `[mcp_servers."${BROWSER_BRIDGE_SERVER_NAME}"]`,
-    `command = ${JSON.stringify(process.execPath)}`,
-    `args = ${JSON.stringify([mcpServerBinPath])}`,
+    `command = ${JSON.stringify(MCP_COMMAND)}`,
+    `args = ${JSON.stringify(MCP_ARGS)}`,
     '',
   ].join('\n');
 }

package/packages/agent-client/src/runtime.js

@@ -1,13 +1,22 @@
 // @ts-check
 
 import fs from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
 
 import {
   APP_NAME,
+  getBridgeDir,
+  getDaemonLogPath,
+  getDaemonPidPath,
   getManifestInstallDir,
+  getSocketPath,
   SUPPORTED_BROWSERS,
 } from '../../native-host/src/config.js';
+import {
+  readDaemonStartHistory,
+  summarizeDaemonRestarts,
+} from '../../native-host/src/daemon-process.js';
 import { resolveDefaultExtensionId } from '../../native-host/src/install-manifest.js';
 import { methodNeedsTab } from './cli-helpers.js';
 import { BridgeClient } from './client.js';
@@ -18,6 +27,7 @@ import { BridgeClient } from './client.js';
 /** @typedef {import('./types.js').BridgeResponse} BridgeResponse */
 /** @typedef {import('../../native-host/src/config.js').SupportedBrowser} SupportedBrowser */
 /** @typedef {import('./types.js').BrowserManifestStatus} BrowserManifestStatus */
+/** @typedef {import('./types.js').NativeHostManifestIssue} NativeHostManifestIssue */
 /** @typedef {import('./types.js').DoctorReport} DoctorReport */
 /** @typedef {import('./types.js').DoctorReportOptions} DoctorReportOptions */
 
@@ -156,6 +166,195 @@ export async function checkBrowserManifests() {
   );
 }
 
+/**
+ * @param {string} line
+ * @param {number} startIndex
+ * @returns {{ value: string, nextIndex: number } | null}
+ */
+function readShellSingleQuotedToken(line, startIndex) {
+  let index = startIndex;
+  while (line[index] === ' ') {
+    index += 1;
+  }
+  if (line[index] !== "'") {
+    return null;
+  }
+  index += 1;
+
+  let value = '';
+  while (index < line.length) {
+    const endIndex = line.indexOf("'", index);
+    if (endIndex === -1) {
+      return null;
+    }
+    value += line.slice(index, endIndex);
+    index = endIndex + 1;
+    if (line.startsWith("\\''", index)) {
+      value += "'";
+      index += 3;
+      continue;
+    }
+    return { value, nextIndex: index };
+  }
+
+  return null;
+}
+
+/**
+ * @param {string} launcher
+ * @returns {{ nodePath: string, hostPath: string } | null}
+ */
+function parseNativeHostLauncherTargets(launcher) {
+  const windowsMatch = /"([^"\r\n]+)"\s+"([^"\r\n]+)"\s+%\*/u.exec(launcher);
+  if (windowsMatch?.[1] && windowsMatch[2]) {
+    return {
+      nodePath: windowsMatch[1],
+      hostPath: windowsMatch[2],
+    };
+  }
+
+  const execLine = launcher
+    .split(/\r?\n/u)
+    .map((line) => line.trim())
+    .find((line) => line.startsWith('exec '));
+  if (!execLine) {
+    return null;
+  }
+  const nodeToken = readShellSingleQuotedToken(execLine, 'exec '.length);
+  if (!nodeToken) {
+    return null;
+  }
+  const hostToken = readShellSingleQuotedToken(execLine, nodeToken.nextIndex);
+  if (!hostToken) {
+    return null;
+  }
+  return {
+    nodePath: nodeToken.value,
+    hostPath: hostToken.value,
+  };
+}
+
+/**
+ * Validate installed native messaging manifests and the launcher they point to.
+ * This catches stale sudo/global Node installs where the manifest exists but
+ * Chrome launches a missing or non-executable script/Node binary.
+ *
+ * @param {BrowserManifestStatus[]} browserManifests
+ * @returns {Promise<NativeHostManifestIssue[]>}
+ */
+export async function checkNativeHostManifestHealth(browserManifests) {
+  /** @type {NativeHostManifestIssue[]} */
+  const issues = [];
+  const executableAccessMode = os.platform() === 'win32' ? fs.constants.F_OK : fs.constants.X_OK;
+  for (const entry of browserManifests) {
+    if (!entry.installed) {
+      continue;
+    }
+
+    /** @type {Record<string, unknown>} */
+    let manifest;
+    try {
+      const rawManifest = await fs.promises.readFile(entry.manifestPath, 'utf8');
+      const parsed = JSON.parse(rawManifest);
+      manifest = parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : {};
+    } catch (error) {
+      issues.push({
+        browser: entry.browser,
+        manifestPath: entry.manifestPath,
+        message: `Native host manifest is not readable JSON: ${error instanceof Error ? error.message : String(error)}`,
+      });
+      continue;
+    }
+
+    const launcherPath = typeof manifest.path === 'string' ? manifest.path : '';
+    if (!launcherPath) {
+      issues.push({
+        browser: entry.browser,
+        manifestPath: entry.manifestPath,
+        message: 'Native host manifest does not specify a launcher path.',
+      });
+      continue;
+    }
+
+    let launcherRaw = '';
+    try {
+      await fs.promises.access(launcherPath, executableAccessMode);
+      launcherRaw = await fs.promises.readFile(launcherPath, 'utf8');
+    } catch (error) {
+      issues.push({
+        browser: entry.browser,
+        manifestPath: entry.manifestPath,
+        message: `Native host launcher is not executable or readable at ${launcherPath}: ${error instanceof Error ? error.message : String(error)}`,
+      });
+      continue;
+    }
+
+    const launcherTargets = parseNativeHostLauncherTargets(launcherRaw);
+    if (!launcherTargets) {
+      issues.push({
+        browser: entry.browser,
+        manifestPath: entry.manifestPath,
+        message: `Native host launcher has an unrecognized format at ${launcherPath}. Run \`bbx install --browser ${entry.browser}\` to regenerate it.`,
+      });
+      continue;
+    }
+
+    try {
+      await fs.promises.access(launcherTargets.nodePath, executableAccessMode);
+    } catch (error) {
+      issues.push({
+        browser: entry.browser,
+        manifestPath: entry.manifestPath,
+        message: `Node executable referenced by the native host launcher is not usable at ${launcherTargets.nodePath}: ${error instanceof Error ? error.message : String(error)}`,
+      });
+    }
+
+    try {
+      await fs.promises.access(launcherTargets.hostPath, fs.constants.F_OK);
+    } catch (error) {
+      issues.push({
+        browser: entry.browser,
+        manifestPath: entry.manifestPath,
+        message: `Native host script referenced by the launcher is missing at ${launcherTargets.hostPath}: ${error instanceof Error ? error.message : String(error)}`,
+      });
+    }
+  }
+  return issues;
+}
+
+/**
+ * Check the bridge home dir and the daemon files inside it for writability.
+ * Root-owned files (typically left behind by a sudo install or a sudo `bbx`
+ * run) make the daemon crash-loop, so doctor must call them out explicitly.
+ *
+ * @returns {Promise<string[]>} paths that exist but are not writable
+ */
+export async function checkUnwritableBridgePaths() {
+  // The root-owned-files scenario comes from sudo installs, which do not exist
+  // on Windows — and fs.access(W_OK) there only reflects the read-only file
+  // attribute, so it would produce false positives.
+  if (os.platform() === 'win32') {
+    return [];
+  }
+
+  const candidates = [getBridgeDir(), getDaemonPidPath(), getDaemonLogPath()];
+  candidates.push(getSocketPath());
+
+  /** @type {string[]} */
+  const unwritable = [];
+  for (const candidate of candidates) {
+    try {
+      await fs.promises.access(candidate, fs.constants.W_OK);
+    } catch (error) {
+      const code = error && typeof error === 'object' && 'code' in error ? error.code : undefined;
+      if (code !== 'ENOENT') {
+        unwritable.push(candidate);
+      }
+    }
+  }
+  return unwritable;
+}
+
 /**
  * @param {DoctorReportOptions} [options={}]
  * @returns {Promise<DoctorReport>}
@@ -166,6 +365,15 @@ export async function getDoctorReport(options = {}) {
   const defaultExtensionId = options.defaultExtensionIdInfo || resolveDefaultExtensionId();
 
   const browserManifests = await (options.checkBrowserManifests || checkBrowserManifests)();
+  const nativeHostManifestIssues = await (
+    options.checkNativeHostManifestHealth || checkNativeHostManifestHealth
+  )(browserManifests);
+  const daemonRestarts = summarizeDaemonRestarts(
+    await (options.readDaemonStartHistory || readDaemonStartHistory)()
+  );
+  const unwritableBridgePaths = await (
+    options.checkUnwritableBridgePaths || checkUnwritableBridgePaths
+  )();
   const manifestInstalled = Boolean(manifest) || browserManifests.some((b) => b.installed);
   const chromiumSandboxedManifestInstalled = browserManifests.some(
     (entry) =>
@@ -188,6 +396,10 @@ export async function getDoctorReport(options = {}) {
     routeTabId: null,
     routeReady: false,
     routeReason: 'access_disabled',
+    daemonRestarts,
+    daemonLogPath: getDaemonLogPath(),
+    unwritableBridgePaths,
+    nativeHostManifestIssues,
     issues: [],
     nextSteps: [],
     browserManifests,
@@ -223,6 +435,24 @@ export async function getDoctorReport(options = {}) {
     report.extensionConnected = false;
   }
 
+  if (unwritableBridgePaths.length > 0) {
+    report.issues.push('bridge_files_not_writable');
+    report.nextSteps.push(
+      `These Browser Bridge files are not writable by the current user (usually caused by installing or running bbx with sudo): ${unwritableBridgePaths.join(', ')}. Fix ownership with: sudo chown -R "$USER" "${getBridgeDir()}"`
+    );
+  }
+  if (nativeHostManifestIssues.length > 0) {
+    report.issues.push('native_host_manifest_invalid');
+    report.nextSteps.push(
+      `The native host manifest or launcher is broken: ${nativeHostManifestIssues.map((issue) => issue.message).join(' ')} Reinstall the native host with \`bbx install --browser <browser>\` or \`bbx install --all\`.`
+    );
+  }
+  if (daemonRestarts.restartLoop) {
+    report.issues.push('daemon_restart_loop');
+    report.nextSteps.push(
+      `The bridge daemon started ${daemonRestarts.startsInWindow} times in the last ${Math.round(daemonRestarts.windowMs / 1000)}s, which means it keeps crashing shortly after startup. Check the daemon log for the underlying error: ${report.daemonLogPath}`
+    );
+  }
   if (!report.manifestInstalled) {
     report.issues.push('native_host_manifest_missing');
     report.nextSteps.push(

package/packages/agent-client/src/types.ts

@@ -98,6 +98,18 @@ export interface BrowserManifestStatus {
   installed: boolean;
 }
 
+export interface DaemonRestartSummary {
+  startsInWindow: number;
+  windowMs: number;
+  restartLoop: boolean;
+}
+
+export interface NativeHostManifestIssue {
+  browser: string;
+  manifestPath: string;
+  message: string;
+}
+
 export interface DoctorReport {
   manifestInstalled: boolean;
   manifestPath: string;
@@ -111,6 +123,10 @@ export interface DoctorReport {
   routeTabId: number | null;
   routeReady: boolean;
   routeReason: string;
+  daemonRestarts: DaemonRestartSummary;
+  daemonLogPath: string;
+  unwritableBridgePaths: string[];
+  nativeHostManifestIssues: NativeHostManifestIssue[];
   issues: string[];
   nextSteps: string[];
   browserManifests: BrowserManifestStatus[];
@@ -124,6 +140,11 @@ export interface DoctorReportOptions {
   bridgeClientRunner?: <T>(
     callback: (client: { request: BridgeClientRequest }) => Promise<T>
   ) => Promise<T>;
+  readDaemonStartHistory?: () => Promise<number[]>;
+  checkUnwritableBridgePaths?: () => Promise<string[]>;
+  checkNativeHostManifestHealth?: (
+    browserManifests: BrowserManifestStatus[]
+  ) => Promise<NativeHostManifestIssue[]>;
 }
 
 export type BridgeClientRequest = (options: {

package/packages/native-host/bin/bridge-daemon.js

@@ -7,7 +7,11 @@ import {
   getBridgeTransport,
 } from '../src/config.js';
 import { DaemonLogger } from '../src/daemon-logger.js';
-import { clearDaemonPidFile, writeDaemonPidFile } from '../src/daemon-process.js';
+import {
+  clearDaemonPidFile,
+  recordDaemonStart,
+  writeDaemonPidFile,
+} from '../src/daemon-process.js';
 
 applyWindowsTcpTransportDefaults();
 const transport = getBridgeTransport();
@@ -25,7 +29,6 @@ function isExistingDaemonError(error) {
 
 try {
   await daemon.start();
-  await writeDaemonPidFile(process.pid);
 } catch (error) {
   if (isExistingDaemonError(error)) {
     process.stdout.write(`${error.message}\n`);
@@ -35,6 +38,18 @@ try {
   process.exit(1);
 }
 
+await recordDaemonStart();
+
+try {
+  await writeDaemonPidFile(process.pid);
+} catch (error) {
+  // A stale root-owned pid file (e.g. after a sudo install) must not take down
+  // a daemon that is already listening; `bbx` falls back to lsof for the pid.
+  process.stderr.write(
+    `Could not write daemon pid file: ${error instanceof Error ? error.message : String(error)}\n`
+  );
+}
+
 process.stdout.write(`Browser Bridge daemon listening on ${formatBridgeTransport(transport)}\n`);
 
 let shuttingDown = false;

package/packages/native-host/bin/postinstall.js

@@ -16,6 +16,18 @@ import { installNativeManifest } from '../src/install-manifest.js';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const repoRoot = path.resolve(__dirname, '../../..');
 
+/**
+ * npm exec may run package lifecycle hooks while resolving the local bin. Keep
+ * transient `npm exec -- bbx ...` invocations from rewriting host setup or
+ * replacing a working daemon.
+ *
+ * @param {NodeJS.ProcessEnv} [env=process.env]
+ * @returns {boolean}
+ */
+function shouldSkipPostinstall(env = process.env) {
+  return env.npm_command === 'exec';
+}
+
 /**
  * @param {{
  *   installNativeManifestFn?: typeof installNativeManifest,
@@ -23,6 +35,7 @@ const repoRoot = path.resolve(__dirname, '../../..');
  *   stdout?: Pick<NodeJS.WriteStream, 'write'>,
  *   stderr?: Pick<NodeJS.WriteStream, 'write'>,
  *   exit?: (code?: number) => void,
+ *   env?: NodeJS.ProcessEnv,
  * }} [deps]
  * @returns {Promise<void>}
  */
@@ -32,7 +45,12 @@ export async function runPostinstall({
   stdout = process.stdout,
   stderr = process.stderr,
   exit = (code) => process.exit(code),
+  env = process.env,
 } = {}) {
+  if (shouldSkipPostinstall(env)) {
+    return;
+  }
+
   try {
     await installNativeManifestFn({ repoRoot, preserveCustomExtensionId: true });
     stdout.write('Browser Bridge: native host installed. Run `bbx doctor` to verify.\n');

package/packages/native-host/src/config.js

@@ -292,6 +292,29 @@ export function getDaemonPidPath(env = process.env) {
   return path.join(getBridgeDir(env), 'daemon.pid');
 }
 
+/**
+ * Persistent daemon log. The daemon is normally spawned detached with its
+ * stdio redirected here so startup failures stay diagnosable after the
+ * process is gone.
+ *
+ * @param {NodeJS.ProcessEnv} [env=process.env]
+ * @returns {string}
+ */
+export function getDaemonLogPath(env = process.env) {
+  return path.join(getBridgeDir(env), 'daemon.log');
+}
+
+/**
+ * Rolling history of daemon start timestamps, used to detect a daemon that
+ * keeps restarting within a short window (crash loop).
+ *
+ * @param {NodeJS.ProcessEnv} [env=process.env]
+ * @returns {string}
+ */
+export function getDaemonStartHistoryPath(env = process.env) {
+  return path.join(getBridgeDir(env), 'daemon-starts.json');
+}
+
 /**
  * @returns {string}
  */

package/packages/native-host/src/daemon-process.js

@@ -12,7 +12,9 @@ import {
   createSocketBridgeTransport,
   formatBridgeTransport,
   getBridgeTransport,
+  getDaemonLogPath,
   getDaemonPidPath,
+  getDaemonStartHistoryPath,
 } from './config.js';
 
 /** @typedef {import('./config.js').BridgeTransport} BridgeTransport */
@@ -22,6 +24,15 @@ const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const daemonEntryPath = path.resolve(__dirname, '../bin/bridge-daemon.js');
 const DEFAULT_DAEMON_RESTART_TIMEOUT_MS = 5_000;
 const DEFAULT_DAEMON_POLL_INTERVAL_MS = 100;
+const DAEMON_LOG_MAX_BYTES = 1024 * 1024;
+const DAEMON_START_HISTORY_MAX_ENTRIES = 20;
+
+/**
+ * A daemon that starts this many times within the window is considered to be
+ * crash-looping rather than restarting normally.
+ */
+export const DAEMON_RESTART_LOOP_THRESHOLD = 3;
+export const DAEMON_RESTART_LOOP_WINDOW_MS = 60_000;
 
 /**
  * @typedef {{
@@ -56,18 +67,114 @@ const DEFAULT_DAEMON_POLL_INTERVAL_MS = 100;
  * }} RestartBridgeDaemonOptions
  */
 
+/**
+ * Open the persistent daemon log for appending, rotating it once when it grows
+ * past the size cap. Returns null when the log cannot be opened (for example a
+ * root-owned bridge dir after a sudo install) so callers can fall back to
+ * discarding output instead of failing the spawn.
+ *
+ * @param {string} [logPath=getDaemonLogPath()]
+ * @returns {number | null}
+ */
+export function openDaemonLogFd(logPath = getDaemonLogPath()) {
+  try {
+    fs.mkdirSync(path.dirname(logPath), { recursive: true });
+    try {
+      if (fs.statSync(logPath).size > DAEMON_LOG_MAX_BYTES) {
+        fs.rmSync(`${logPath}.1`, { force: true });
+        fs.renameSync(logPath, `${logPath}.1`);
+      }
+    } catch {
+      // Rotation is best-effort: on Windows the rename fails while another
+      // daemon holds the log open. Keep appending to the current file.
+    }
+    return fs.openSync(logPath, 'a');
+  } catch {
+    return null;
+  }
+}
+
 /**
  * @returns {import('node:child_process').ChildProcess}
  */
 export function spawnBridgeDaemonProcess() {
+  const logFd = openDaemonLogFd();
   const child = spawn(process.execPath, [daemonEntryPath], {
     detached: true,
-    stdio: 'ignore',
+    stdio: logFd === null ? 'ignore' : ['ignore', logFd, logFd],
   });
   child.unref();
+  if (logFd !== null) {
+    fs.closeSync(logFd);
+  }
   return child;
 }
 
+/**
+ * Read the rolling daemon start history (epoch ms timestamps, oldest first).
+ * Missing or malformed files read as an empty history.
+ *
+ * @param {string} [historyPath=getDaemonStartHistoryPath()]
+ * @returns {Promise<number[]>}
+ */
+export async function readDaemonStartHistory(historyPath = getDaemonStartHistoryPath()) {
+  try {
+    const parsed = JSON.parse(await fs.promises.readFile(historyPath, 'utf8'));
+    if (!Array.isArray(parsed)) {
+      return [];
+    }
+    return parsed.filter(
+      (value) => typeof value === 'number' && Number.isFinite(value) && value > 0
+    );
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Append a daemon start timestamp to the rolling history. Best-effort: any
+ * filesystem failure is swallowed so an unwritable bridge dir never prevents
+ * the daemon from starting.
+ *
+ * @param {{ at?: number, historyPath?: string }} [options={}]
+ * @returns {Promise<number[]>} the updated history (empty when persisting failed)
+ */
+export async function recordDaemonStart(options = {}) {
+  const { at = Date.now(), historyPath = getDaemonStartHistoryPath() } = options;
+  try {
+    const history = [...(await readDaemonStartHistory(historyPath)), at].slice(
+      -DAEMON_START_HISTORY_MAX_ENTRIES
+    );
+    await fs.promises.mkdir(path.dirname(historyPath), { recursive: true });
+    await fs.promises.writeFile(historyPath, `${JSON.stringify(history)}\n`, 'utf8');
+    return history;
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Summarize the daemon start history over the recent window so callers can
+ * tell a crash-looping daemon apart from a normal restart.
+ *
+ * @param {number[]} history
+ * @param {{ now?: number, windowMs?: number, threshold?: number }} [options={}]
+ * @returns {{ startsInWindow: number, windowMs: number, restartLoop: boolean }}
+ */
+export function summarizeDaemonRestarts(history, options = {}) {
+  const {
+    now = Date.now(),
+    windowMs = DAEMON_RESTART_LOOP_WINDOW_MS,
+    threshold = DAEMON_RESTART_LOOP_THRESHOLD,
+  } = options;
+  const startsInWindow = history.filter((at) => at <= now && now - at <= windowMs).length;
+  return {
+    startsInWindow,
+    windowMs,
+    restartLoop: startsInWindow >= threshold,
+  };
+}
+
 /**
  * @param {number} [pid=process.pid]
  * @param {string} [pidPath=getDaemonPidPath()]
@@ -141,7 +248,8 @@ export async function stopBridgeDaemon(options = {}) {
   const resolvedSocketPath =
     resolvedTransport.type === 'socket' ? resolvedTransport.socketPath : '';
 
-  let previousPid = await readPidFn(pidPath);
+  const pidFromFile = await readPidFn(pidPath);
+  let previousPid = pidFromFile;
   let previouslyRunning = previousPid !== null;
 
   if (previousPid === null && (await safePingDaemon(resolvedTransport, pingDaemonFn))) {
@@ -158,7 +266,7 @@ export async function stopBridgeDaemon(options = {}) {
       }
     }
 
-    const stopped = await waitForDaemonReachability({
+    let stopped = await waitForDaemonReachability({
       transport: resolvedTransport,
       reachable: false,
       timeoutMs,
@@ -166,12 +274,38 @@ export async function stopBridgeDaemon(options = {}) {
       pingDaemonFn,
       sleepFn,
     });
+    if (!stopped) {
+      // The pid file can be stale (e.g. a root-owned leftover from a sudo
+      // install that the daemon could not overwrite) while a daemon with a
+      // different pid owns the socket. Target the socket owner before giving up.
+      const socketOwnerPid = await findPidByTransportFn(resolvedTransport);
+      if (socketOwnerPid !== null && socketOwnerPid !== previousPid) {
+        try {
+          killFn(socketOwnerPid, 'SIGTERM');
+        } catch (error) {
+          if (!isMissingProcessError(error)) {
+            throw error;
+          }
+        }
+        stopped = await waitForDaemonReachability({
+          transport: resolvedTransport,
+          reachable: false,
+          timeoutMs,
+          pollIntervalMs,
+          pingDaemonFn,
+          sleepFn,
+        });
+        if (stopped) {
+          previousPid = socketOwnerPid;
+        }
+      }
+    }
     if (!stopped) {
       throw new Error(`Timed out waiting for Browser Bridge daemon (pid ${previousPid}) to stop.`);
     }
   }
 
-  await clearDaemonPidFile({ pid: previousPid, pidPath, rmFn });
+  await clearDaemonPidFile({ pid: pidFromFile ?? previousPid, pidPath, rmFn });
 
   const removedStaleSocket = await removeStaleSocket(resolvedTransport, rmFn, pingDaemonFn);
   return {

package/packages/native-host/src/daemon.js

@@ -24,9 +24,10 @@ import {
   DEFAULT_DAEMON_PENDING_TIMEOUT_MS,
   DEFAULT_LOG_TAIL_LIMIT,
   ERROR_CODES,
+  getProtocolVersion,
+  getSupportedProtocolVersions,
   parseJsonLines,
-  PROTOCOL_VERSION,
-  SUPPORTED_VERSIONS,
+  setProtocolPackageVersion,
   validateBridgeRequest,
 } from '../../protocol/src/index.js';
 import {
@@ -45,6 +46,7 @@ import { normalizeDaemonLogger } from './daemon-logger.js';
 import { writeJsonLine } from './framing.js';
 
 const DAEMON_VERSION = loadDaemonVersion();
+setProtocolPackageVersion(DAEMON_VERSION);
 
 /** @typedef {import('../../protocol/src/types.js').BridgeRequest} BridgeRequest */
 /** @typedef {import('../../protocol/src/types.js').SetupInstallParams} SetupInstallParams */
@@ -89,14 +91,15 @@ function compareProtocolVersions(left, right) {
  * @returns {{ supported_versions: readonly string[], deprecated_since?: string, migration_hint?: string }}
  */
 function getVersionNegotiationPayload(requestedVersion) {
-  const latestSupported = SUPPORTED_VERSIONS[0];
-  if (!requestedVersion || !latestSupported || SUPPORTED_VERSIONS.includes(requestedVersion)) {
-    return { supported_versions: SUPPORTED_VERSIONS };
+  const supportedVersions = getSupportedProtocolVersions();
+  const latestSupported = supportedVersions[0];
+  if (!requestedVersion || !latestSupported || supportedVersions.includes(requestedVersion)) {
+    return { supported_versions: supportedVersions };
   }
 
   const localIsNewer = compareProtocolVersions(latestSupported, requestedVersion) > 0;
   return {
-    supported_versions: SUPPORTED_VERSIONS,
+    supported_versions: supportedVersions,
     ...(localIsNewer ? { deprecated_since: latestSupported } : {}),
     migration_hint: localIsNewer
       ? `Browser Bridge daemon is newer than the client protocol ${requestedVersion}. Restart or update the Browser Bridge CLI/npm package to ${latestSupported} or later.`
@@ -640,7 +643,7 @@ export class BridgeDaemon {
           transport: formatBridgeTransport(this.transport),
           proxy: this.getProxyStatusPayload(),
           connectedExtensions: [],
-          daemon_supported_versions: SUPPORTED_VERSIONS,
+          daemon_supported_versions: getSupportedProtocolVersions(),
           ...getVersionNegotiationPayload(request.meta?.protocol_version),
         });
         await writeJsonLine(socket, { type: 'agent.response', response });
@@ -948,7 +951,7 @@ export class BridgeDaemon {
                 ...getVersionNegotiationPayload(pending.protocolVersion),
                 .../** @type {Record<string, unknown>} */ (responseMessage.result),
                 daemonVersion: DAEMON_VERSION,
-                daemon_supported_versions: SUPPORTED_VERSIONS,
+                daemon_supported_versions: getSupportedProtocolVersions(),
                 proxy: this.getProxyStatusPayload(),
               },
               {
@@ -1161,7 +1164,7 @@ export async function pingExistingDaemon(transport) {
             method: 'health.ping',
             tab_id: null,
             params: {},
-            meta: { protocol_version: PROTOCOL_VERSION, token_budget: null },
+            meta: { protocol_version: getProtocolVersion(), token_budget: null },
           },
         })}\n`
       );

package/packages/native-host/src/native-host.js

@@ -125,7 +125,7 @@ export async function runNativeHost({
     socket = await connectWithBootstrap(resolvedTransport);
   } catch (error) {
     await writeNativeMessageQueued({
-      type: 'agent.response',
+      type: 'host.bridge_response',
       response: createFailure(
         'native_bootstrap',
         ERROR_CODES.NATIVE_HOST_UNAVAILABLE,

package/packages/protocol/src/protocol.js

@@ -82,10 +82,59 @@ import { BRIDGE_METHODS, METHOD_SET, createBridgeMethodGroups } from './registry
 /** @typedef {import('./types.js').WaitForLoadStateParams} WaitForLoadStateParams */
 /** @typedef {import('./types.js').WaitForParams} WaitForParams */
 
-export const PROTOCOL_VERSION = '1.0';
+/** @type {string | null} */
+let protocolPackageVersion = null;
+
+/**
+ * @param {string | null | undefined} packageVersion
+ * @returns {string}
+ */
+export function deriveProtocolVersion(packageVersion) {
+  const match = typeof packageVersion === 'string' ? /^(\d+)\.(\d+)/.exec(packageVersion) : null;
+  return match ? `${match[1]}.${match[2]}` : '0.0';
+}
+
+/**
+ * @returns {string | null}
+ */
+function getRuntimePackageVersion() {
+  const chromeRuntime = /** @type {{ runtime?: { getManifest?: () => { version?: unknown } } }} */ (
+    globalThis.chrome ?? {}
+  ).runtime;
+  const manifestVersion = chromeRuntime?.getManifest?.().version;
+  if (typeof manifestVersion === 'string') {
+    return manifestVersion;
+  }
+
+  const npmPackageVersion = globalThis.process?.env?.npm_package_version;
+  return typeof npmPackageVersion === 'string' ? npmPackageVersion : null;
+}
+
+/**
+ * @param {string | null | undefined} packageVersion
+ * @returns {void}
+ */
+export function setProtocolPackageVersion(packageVersion) {
+  protocolPackageVersion = typeof packageVersion === 'string' ? packageVersion : null;
+}
+
+/**
+ * @returns {string}
+ */
+export function getProtocolVersion() {
+  return deriveProtocolVersion(protocolPackageVersion ?? getRuntimePackageVersion());
+}
+
+/** Snapshot retained for older callers; new code should call getProtocolVersion(). */
+export const PROTOCOL_VERSION = getProtocolVersion();
 
 /** Versions this build can speak. Newest first. */
-export const SUPPORTED_VERSIONS = Object.freeze(['1.0']);
+export function getSupportedProtocolVersions() {
+  return Object.freeze([getProtocolVersion()]);
+}
+
+/** Snapshot retained for older callers; new code should call getSupportedProtocolVersions(). */
+export const SUPPORTED_VERSIONS = getSupportedProtocolVersions();
 
 /**
  * Clamp a numeric value between min and max, falling back to a default.
@@ -122,7 +171,7 @@ export function createRequest({ id, method, tabId = null, params = {}, meta = {}
     tab_id: tabId,
     params,
     meta: {
-      protocol_version: PROTOCOL_VERSION,
+      protocol_version: getProtocolVersion(),
       ...meta,
     },
   });
@@ -141,7 +190,7 @@ export function createSuccess(id, result, meta = {}) {
     result,
     error: null,
     meta: {
-      protocol_version: PROTOCOL_VERSION,
+      protocol_version: getProtocolVersion(),
       ...meta,
     },
   };
@@ -168,7 +217,7 @@ export function createFailure(id, code, message, details = null, meta = {}) {
       ...(recovery && { recovery }),
     },
     meta: {
-      protocol_version: PROTOCOL_VERSION,
+      protocol_version: getProtocolVersion(),
       ...meta,
     },
   };
@@ -238,7 +287,7 @@ export function validateBridgeRequest(request) {
     meta: {
       ...meta,
       protocol_version:
-        typeof meta.protocol_version === 'string' ? meta.protocol_version : PROTOCOL_VERSION,
+        typeof meta.protocol_version === 'string' ? meta.protocol_version : getProtocolVersion(),
       token_budget: typeof meta.token_budget === 'number' ? meta.token_budget : null,
       source: meta.source === 'cli' || meta.source === 'mcp' ? meta.source : undefined,
     },
@@ -842,7 +891,7 @@ export function createRuntimeContext() {
   const methodGroups = createBridgeMethodGroups();
 
   return {
-    v: PROTOCOL_VERSION,
+    v: getProtocolVersion(),
     budgets: {
       quick: {
         n: BUDGET_PRESETS.quick.maxNodes,

package/packages/protocol/src/summary.js

@@ -1,6 +1,11 @@
 // @ts-check
 
-import { estimateSerializedPayloadCost, getCostClass, serializeJsonPayload } from './index.js';
+import {
+  estimateSerializedPayloadCost,
+  getCostClass,
+  getProtocolVersion,
+  serializeJsonPayload,
+} from './index.js';
 
 /** @typedef {import('./types.js').BridgeResponse} BridgeResponse */
 /** @typedef {import('./types.js').BridgeMethod} SummaryMethod */
@@ -692,7 +697,7 @@ export function summarizeBatchErrorItem({ method, tabId, error, durationMs }) {
       message,
       details: null,
     },
-    meta: { protocol_version: '1.0' },
+    meta: { protocol_version: getProtocolVersion() },
   });
   const summary = annotateBridgeSummary(summarizeBridgeResponse(response, method), response);
   return {

package/skills/browser-bridge/references/protocol.md

@@ -348,7 +348,7 @@ bbx call screenshot.capture_full_page '{}'
   "tab_id": 123,
   "method": "dom.query",
   "params": {},
-  "meta": { "protocol_version": "1.0", "token_budget": 1200 }
+  "meta": { "protocol_version": "<package major.minor>", "token_budget": 1200 }
 }
 ```