@browserbridge/bbx 1.8.0 → 1.9.0

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

@@ -0,0 +1,195 @@
+// @ts-check
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { getBridgeDir, getBridgeTransport } from '../../native-host/src/config.js';
+import { atomicWriteFile } from './atomic-write.js';
+
+/** @typedef {import('./types.js').AutoUpdatePolicy} AutoUpdatePolicy */
+/** @typedef {import('./types.js').BridgeClientOptions} BridgeClientOptions */
+/** @typedef {import('./types.js').BrowserBridgeConfig} BrowserBridgeConfig */
+
+export const AUTO_UPDATE_ENV = 'BBX_AUTO_UPDATE';
+export const CONFIG_FILENAME = 'config.json';
+const AUTO_UPDATE_POLICIES = new Set(['off', 'compatible']);
+
+/**
+ * @param {NodeJS.ProcessEnv} [env=process.env]
+ * @returns {string}
+ */
+export function getBridgeConfigPath(env = process.env) {
+  return path.join(getBridgeDir(env), CONFIG_FILENAME);
+}
+
+/**
+ * @param {unknown} value
+ * @returns {AutoUpdatePolicy}
+ */
+export function parseAutoUpdatePolicy(value) {
+  if (typeof value !== 'string' || !AUTO_UPDATE_POLICIES.has(value)) {
+    throw new Error('Auto-update policy must be "off" or "compatible".');
+  }
+  return /** @type {AutoUpdatePolicy} */ (value);
+}
+
+/**
+ * @param {NodeJS.ProcessEnv} [env=process.env]
+ * @returns {Promise<BrowserBridgeConfig>}
+ */
+export async function readBridgeConfig(env = process.env) {
+  const configPath = getBridgeConfigPath(env);
+  let raw;
+  try {
+    raw = await fs.promises.readFile(configPath, 'utf8');
+  } catch (error) {
+    if (isMissingFileError(error)) {
+      return { autoUpdate: 'off' };
+    }
+    throw error;
+  }
+
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (error) {
+    throw new Error(
+      `Cannot read ${configPath}: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw new Error(`Cannot read ${configPath}: expected a JSON object.`);
+  }
+
+  const config = /** @type {Record<string, unknown>} */ (parsed);
+  return {
+    ...config,
+    autoUpdate: config.autoUpdate === undefined ? 'off' : parseAutoUpdatePolicy(config.autoUpdate),
+  };
+}
+
+/**
+ * @param {AutoUpdatePolicy} policy
+ * @param {NodeJS.ProcessEnv} [env=process.env]
+ * @returns {Promise<string>}
+ */
+export async function setAutoUpdatePolicy(policy, env = process.env) {
+  const normalized = parseAutoUpdatePolicy(policy);
+  const configPath = getBridgeConfigPath(env);
+  const config = await readBridgeConfig(env);
+  await atomicWriteFile(
+    configPath,
+    `${JSON.stringify({ ...config, autoUpdate: normalized }, null, 2)}\n`,
+    { encoding: 'utf8', mode: 0o600 }
+  );
+  return configPath;
+}
+
+/**
+ * Environment configuration overrides the persisted preference for unattended
+ * and containerized clients.
+ *
+ * @param {NodeJS.ProcessEnv} [env=process.env]
+ * @returns {Promise<AutoUpdatePolicy>}
+ */
+export async function getAutoUpdatePolicy(env = process.env) {
+  if (env[AUTO_UPDATE_ENV] !== undefined) {
+    return parseAutoUpdatePolicy(env[AUTO_UPDATE_ENV]);
+  }
+  return (await readBridgeConfig(env)).autoUpdate;
+}
+
+/**
+ * @param {BridgeClientOptions} [options={}]
+ * @param {NodeJS.ProcessEnv} [env=process.env]
+ * @param {string[]} [argv=process.argv]
+ * @returns {Promise<BridgeClientOptions>}
+ */
+export async function applyConfiguredAutoUpdate(
+  options = {},
+  env = process.env,
+  argv = process.argv
+) {
+  if (options.updateNpmOnCompatibleVersion !== undefined) {
+    return options;
+  }
+  if (env[AUTO_UPDATE_ENV] === undefined && !isBrowserBridgeProcess(argv)) {
+    return options;
+  }
+  if (env.npm_command === 'exec' || (await getAutoUpdatePolicy(env)) !== 'compatible') {
+    return options;
+  }
+  const transport = options.socketPath ? null : (options.transport ?? getBridgeTransport(env));
+  if (transport?.type === 'tcp' && !isLoopbackHost(transport.host)) {
+    return options;
+  }
+  return {
+    ...options,
+    checkProtocolOnConnect: true,
+    updateNpmOnCompatibleVersion: true,
+    exitProcessOnNpmUpdate: isMcpProcess(argv),
+  };
+}
+
+/**
+ * @param {string} host
+ * @returns {boolean}
+ */
+function isLoopbackHost(host) {
+  const normalized = host
+    .trim()
+    .toLowerCase()
+    .replace(/^\[|\]$/gu, '');
+  if (normalized === 'localhost' || normalized === '::1' || normalized === '0:0:0:0:0:0:0:1') {
+    return true;
+  }
+  const match = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/u.exec(normalized);
+  return Boolean(
+    match && match.slice(1).every((part) => Number(part) <= 255) && match[1] === '127'
+  );
+}
+
+/**
+ * @param {string[]} [argv=process.argv]
+ * @returns {boolean}
+ */
+export function isMcpProcess(argv = process.argv) {
+  const entry = (argv[1] || '').replaceAll('\\', '/');
+  const entryName = entry.slice(entry.lastIndexOf('/') + 1).toLowerCase();
+  return (
+    (argv[2] === 'mcp' && argv[3] === 'serve') ||
+    (entry.includes('/mcp-server/') && entry.endsWith('/bin.js')) ||
+    entryName === 'bbx-mcp' ||
+    entryName === 'bbx-mcp.cmd'
+  );
+}
+
+/**
+ * Persisted CLI preferences apply to the shipped executables, not arbitrary
+ * programmatic BridgeClient consumers that happen to share the same user home.
+ *
+ * @param {string[]} [argv=process.argv]
+ * @returns {boolean}
+ */
+export function isBrowserBridgeProcess(argv = process.argv) {
+  if (isMcpProcess(argv)) return true;
+  const entry = (argv[1] || '').replaceAll('\\', '/');
+  const entryName = entry.slice(entry.lastIndexOf('/') + 1).toLowerCase();
+  return (
+    (entry.includes('/agent-client/') && entry.endsWith('/cli.js')) ||
+    entryName === 'bbx' ||
+    entryName === 'bbx.cmd'
+  );
+}
+
+/**
+ * @param {unknown} error
+ * @returns {boolean}
+ */
+function isMissingFileError(error) {
+  return Boolean(
+    error &&
+    typeof error === 'object' &&
+    /** @type {{ code?: unknown }} */ (error).code === 'ENOENT'
+  );
+}

package/packages/agent-client/src/npm-self-update.js

@@ -0,0 +1,305 @@
+// @ts-check
+
+import { execFile } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import fs from 'node:fs';
+import net from 'node:net';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const PACKAGE_NAME = '@browserbridge/bbx';
+const PACKAGE_ROOT = path.dirname(fileURLToPath(new URL('../../../package.json', import.meta.url)));
+const DEFAULT_COMMAND_TIMEOUT_MS = 120_000;
+const DEFAULT_LOCK_TIMEOUT_MS = 120_000;
+const UPDATE_LOCK_PORT_START = 49_152;
+const UPDATE_LOCK_PORT_COUNT = 16_384;
+const UPDATE_LOCK_PORT_ATTEMPTS = 32;
+
+/** @typedef {import('./types.js').NpmUpdateResult} NpmUpdateResult */
+
+export class NpmPackageUpdatedError extends Error {
+  /**
+   * @param {string} version
+   */
+  constructor(version) {
+    super(`Browser Bridge updated to ${version}; restarting to load the new version.`);
+    this.name = 'NpmPackageUpdatedError';
+    this.code = 'BBX_NPM_UPDATED';
+    this.version = version;
+  }
+}
+
+/**
+ * @param {string} value
+ * @returns {[number, number, number] | null}
+ */
+export function parseStableVersion(value) {
+  const match = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/u.exec(value);
+  return match ? [Number(match[1]), Number(match[2]), Number(match[3])] : null;
+}
+
+/**
+ * @param {string} left
+ * @param {string} right
+ * @returns {number}
+ */
+export function comparePackageVersions(left, right) {
+  const leftParts = parseStableVersion(left);
+  const rightParts = parseStableVersion(right);
+  if (!leftParts || !rightParts) {
+    throw new Error(`Cannot compare invalid stable versions "${left}" and "${right}".`);
+  }
+  for (let index = 0; index < leftParts.length; index += 1) {
+    const delta = leftParts[index] - rightParts[index];
+    if (delta !== 0) return delta > 0 ? 1 : -1;
+  }
+  return 0;
+}
+
+/**
+ * @param {string} version
+ * @returns {string | null}
+ */
+export function derivePackageProtocolVersion(version) {
+  const parsed = parseStableVersion(version);
+  return parsed ? `${parsed[0]}.${parsed[1]}` : null;
+}
+
+/**
+ * @param {unknown[]} versions
+ * @param {readonly string[]} supportedProtocols
+ * @param {string} currentVersion
+ * @returns {string | null}
+ */
+export function selectCompatibleNpmVersion(versions, supportedProtocols, currentVersion) {
+  if (!parseStableVersion(currentVersion)) return null;
+  const supported = new Set(supportedProtocols.filter((version) => /^\d+\.\d+$/u.test(version)));
+  let selected = null;
+  for (const value of versions) {
+    if (typeof value !== 'string' || !parseStableVersion(value)) continue;
+    const protocolVersion = derivePackageProtocolVersion(value);
+    if (!protocolVersion || !supported.has(protocolVersion)) continue;
+    if (comparePackageVersions(value, currentVersion) <= 0) continue;
+    if (selected === null || comparePackageVersions(value, selected) > 0) selected = value;
+  }
+  return selected;
+}
+
+/**
+ * @param {string} packageRoot
+ * @returns {Promise<string | null>}
+ */
+async function readPackageVersion(packageRoot) {
+  try {
+    const parsed = JSON.parse(
+      await fs.promises.readFile(path.join(packageRoot, 'package.json'), 'utf8')
+    );
+    return parsed && typeof parsed.version === 'string' ? parsed.version : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * @param {string[]} args
+ * @param {{ env?: NodeJS.ProcessEnv, timeoutMs?: number }} [options={}]
+ * @returns {Promise<string>}
+ */
+export async function runNpmCommand(args, options = {}) {
+  const env = options.env ?? process.env;
+  const npmExecPath = env.npm_execpath;
+  const useNode = Boolean(npmExecPath && /\.(?:c?js|mjs)$/u.test(npmExecPath));
+  const command = useNode
+    ? process.execPath
+    : npmExecPath || (process.platform === 'win32' ? 'npm.cmd' : 'npm');
+  const commandArgs = useNode && npmExecPath ? [npmExecPath, ...args] : args;
+
+  return new Promise((resolve, reject) => {
+    execFile(
+      command,
+      commandArgs,
+      {
+        env,
+        encoding: 'utf8',
+        timeout: options.timeoutMs ?? DEFAULT_COMMAND_TIMEOUT_MS,
+        maxBuffer: 4 * 1024 * 1024,
+        windowsHide: true,
+      },
+      (error, stdout, stderr) => {
+        if (!error) {
+          resolve(stdout);
+          return;
+        }
+        const detail = stderr.trim();
+        reject(
+          new Error(
+            `npm ${args.join(' ')} failed${detail ? `: ${detail.slice(0, 1000)}` : `: ${error.message}`}`
+          )
+        );
+      }
+    );
+  });
+}
+
+/**
+ * Bind an exclusive loopback port derived from the global npm package path.
+ * The OS releases the lock if the updater crashes, avoiding persistent stale
+ * lock files while preserving cross-process serialization.
+ *
+ * @param {string} lockKey
+ * @param {number} [offset=0]
+ * @returns {number}
+ */
+export function getNpmUpdateLockPort(lockKey, offset = 0) {
+  const digest = createHash('sha256').update(lockKey).digest();
+  return (
+    UPDATE_LOCK_PORT_START +
+    ((digest.readUInt32BE(0) + Math.max(0, Math.trunc(offset))) % UPDATE_LOCK_PORT_COUNT)
+  );
+}
+
+/**
+ * @param {number} port
+ * @returns {Promise<string | null>}
+ */
+async function readNpmUpdateLockIdentity(port) {
+  return new Promise((resolve) => {
+    const socket = net.createConnection({ host: '127.0.0.1', port });
+    let settled = false;
+    let value = '';
+    /** @param {string | null} result */
+    const finish = (result) => {
+      if (settled) return;
+      settled = true;
+      socket.destroy();
+      resolve(result);
+    };
+    socket.setEncoding('utf8');
+    socket.setTimeout(250, () => finish(null));
+    socket.on('data', (chunk) => {
+      value += chunk;
+      if (value.length > 256 || value.includes('\n')) finish(value.trim());
+    });
+    socket.on('end', () => finish(value.trim() || null));
+    socket.on('error', () => finish(null));
+  });
+}
+
+/**
+ * @param {string} lockKey
+ * @param {number} [timeoutMs=DEFAULT_LOCK_TIMEOUT_MS]
+ * @returns {Promise<() => Promise<void>>}
+ */
+export async function acquireNpmUpdateLock(lockKey, timeoutMs = DEFAULT_LOCK_TIMEOUT_MS) {
+  const startedAt = Date.now();
+  const identity = `bbx-npm-update:${createHash('sha256').update(lockKey).digest('hex')}`;
+  while (true) {
+    let activeUpdaterFound = false;
+    for (let offset = 0; offset < UPDATE_LOCK_PORT_ATTEMPTS; offset += 1) {
+      const port = getNpmUpdateLockPort(lockKey, offset);
+      const server = net.createServer((socket) => socket.end(`${identity}\n`));
+      const acquired = await new Promise((resolve, reject) => {
+        server.once('error', (error) => {
+          if (/** @type {NodeJS.ErrnoException} */ (error).code === 'EADDRINUSE') {
+            resolve(false);
+            return;
+          }
+          reject(error);
+        });
+        server.listen({ host: '127.0.0.1', port, exclusive: true }, () => resolve(true));
+      });
+      if (acquired) {
+        return async () => {
+          await new Promise((resolve) => server.close(resolve));
+        };
+      }
+      if ((await readNpmUpdateLockIdentity(port)) === identity) {
+        activeUpdaterFound = true;
+        break;
+      }
+    }
+    if (Date.now() - startedAt >= timeoutMs) {
+      throw new Error(
+        activeUpdaterFound
+          ? 'Timed out waiting for another Browser Bridge npm update to finish.'
+          : 'Could not reserve a local Browser Bridge npm update lock.'
+      );
+    }
+    await new Promise((resolve) => setTimeout(resolve, 250));
+  }
+}
+
+/**
+ * @param {{
+ *   extensionVersion: string,
+ *   supportedVersions: readonly string[],
+ *   env?: NodeJS.ProcessEnv,
+ *   packageRoot?: string,
+ *   lockPath?: string,
+ *   runNpmFn?: typeof runNpmCommand,
+ * }} options
+ * @returns {Promise<NpmUpdateResult>}
+ */
+export async function updateCompatibleNpmPackage(options) {
+  const env = options.env ?? process.env;
+  const packageRoot = options.packageRoot ?? PACKAGE_ROOT;
+  const runNpmFn = options.runNpmFn ?? runNpmCommand;
+  const extensionProtocol = derivePackageProtocolVersion(options.extensionVersion);
+  if (!extensionProtocol || !options.supportedVersions.includes(extensionProtocol)) {
+    return { updated: false, reason: 'invalid_extension_version' };
+  }
+
+  const globalRoot = (await runNpmFn(['root', '--global'], { env })).trim();
+  const expectedRoot = path.join(globalRoot, '@browserbridge', 'bbx');
+  const [realPackageRoot, realExpectedRoot, expectedStat] = await Promise.all([
+    fs.promises.realpath(packageRoot).catch(() => ''),
+    fs.promises.realpath(expectedRoot).catch(() => ''),
+    fs.promises.lstat(expectedRoot).catch(() => null),
+  ]);
+  if (!realPackageRoot || realPackageRoot !== realExpectedRoot || expectedStat?.isSymbolicLink()) {
+    return { updated: false, reason: 'not_global_install' };
+  }
+
+  const lockKey = options.lockPath ?? realExpectedRoot;
+  const releaseLock = await acquireNpmUpdateLock(lockKey);
+  try {
+    const currentVersion = await readPackageVersion(packageRoot);
+    if (!currentVersion || !parseStableVersion(currentVersion)) {
+      return { updated: false, reason: 'invalid_installed_version' };
+    }
+    if (comparePackageVersions(options.extensionVersion, currentVersion) <= 0) {
+      return { updated: false, reason: 'extension_not_newer', previousVersion: currentVersion };
+    }
+
+    const versionsRaw = await runNpmFn(['view', PACKAGE_NAME, 'versions', '--json'], { env });
+    const parsedVersions = JSON.parse(versionsRaw);
+    const versions = Array.isArray(parsedVersions) ? parsedVersions : [parsedVersions];
+    const targetVersion = selectCompatibleNpmVersion(
+      versions,
+      options.supportedVersions,
+      currentVersion
+    );
+    if (!targetVersion) {
+      return { updated: false, reason: 'no_compatible_update', previousVersion: currentVersion };
+    }
+
+    await runNpmFn(
+      ['install', '--global', '--no-audit', '--no-fund', '--', `${PACKAGE_NAME}@${targetVersion}`],
+      { env }
+    );
+    const installedVersion = await readPackageVersion(packageRoot);
+    if (installedVersion !== targetVersion) {
+      throw new Error(
+        `npm reported success, but Browser Bridge ${targetVersion} was not installed at ${packageRoot}.`
+      );
+    }
+    return {
+      updated: true,
+      reason: 'updated',
+      previousVersion: currentVersion,
+      version: targetVersion,
+    };
+  } finally {
+    await releaseLock();
+  }
+}

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

@@ -7,6 +7,7 @@ import { createTcpBridgeTransport, getBridgeDir } from '../../native-host/src/co
 import { normalizeBridgeAuthToken } from '../../native-host/src/auth-token.js';
 import { atomicWriteFile } from './atomic-write.js';
 import { BridgeClient } from './client.js';
+import { applyConfiguredAutoUpdate } from './config.js';
 
 const REMOTES_FILENAME = 'remotes.json';
 const LOCAL_DESTINATION_ID = 'local';
@@ -287,12 +288,12 @@ function validateAuthToken(token) {
 
 /**
  * @param {string | null | undefined} destinationId
- * @param {{ defaultTimeoutMs?: number, checkProtocolOnConnect?: boolean }} [options={}]
+ * @param {import('./types.js').BridgeClientOptions} [options={}]
  * @returns {Promise<BridgeClient>}
  */
 export async function createBridgeClientForDestination(destinationId, options = {}) {
   if (!destinationId || destinationId === LOCAL_DESTINATION_ID) {
-    return new BridgeClient(options);
+    return new BridgeClient(await applyConfiguredAutoUpdate(options));
   }
   const config = await readRemoteConfig();
   const remote = config.remotes.find((entry) => entry.id === destinationId);
@@ -304,5 +305,6 @@ export async function createBridgeClientForDestination(destinationId, options =
     transport: createTcpBridgeTransport(remote.port, remote.host),
     authToken: remote.token,
     restartDaemonOnVersionMismatch: false,
+    updateNpmOnCompatibleVersion: false,
   });
 }

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

@@ -28,9 +28,14 @@ import {
   getBridgeOperationTimeoutMs,
   getProtocolVersion,
   MAX_CLIENT_REQUEST_TIMEOUT_MS,
+  normalizeRecoveryTelemetrySummary,
+  RECOVERY_EVENT_KINDS,
+  sanitizeIncidentalPath,
+  sanitizeIncidentalText,
 } from '../../protocol/src/index.js';
 import { methodNeedsTab } from './cli-helpers.js';
 import { BridgeClient } from './client.js';
+import { applyConfiguredAutoUpdate } from './config.js';
 import { readRemoteConfig } from './remotes.js';
 import { collectSetupStatus } from './setup-status.js';
 
@@ -101,7 +106,7 @@ export async function ensureClientConnected(client) {
  * @param {BridgeClient} client
  * @param {BridgeMethod} method
  * @param {Record<string, unknown>} [params={}]
- * @param {{ tabId?: number | null, source?: BridgeRequestSource, tokenBudget?: number | null }} [options]
+ * @param {{ tabId?: number | null, source?: BridgeRequestSource, tokenBudget?: number | null, automaticRetry?: 'mcp_second_attempt' }} [options]
  * @returns {Promise<BridgeResponse>}
  */
 export async function requestBridge(client, method, params = {}, options = {}) {
@@ -122,7 +127,7 @@ export async function requestBridge(client, method, params = {}, options = {}) {
     method,
     params,
     tabId: methodNeedsTab(method) ? (options.tabId ?? null) : null,
-    meta: withRequestMeta(options.source, options.tokenBudget),
+    meta: withRequestMeta(options.source, options.tokenBudget, options.automaticRetry),
     ...(timeoutMs === undefined ? {} : { timeoutMs }),
   });
 }
@@ -164,9 +169,10 @@ export async function resolveRef(client, refOrSelector, tabId = null, source) {
 /**
  * @param {BridgeRequestSource | undefined} source
  * @param {number | null | undefined} tokenBudget
+ * @param {'mcp_second_attempt' | undefined} automaticRetry
  * @returns {BridgeMeta}
  */
-function withRequestMeta(source, tokenBudget) {
+function withRequestMeta(source, tokenBudget, automaticRetry) {
   /** @type {BridgeMeta} */
   const meta = {};
   if (source) {
@@ -175,6 +181,9 @@ function withRequestMeta(source, tokenBudget) {
   if (typeof tokenBudget === 'number' && Number.isFinite(tokenBudget)) {
     meta.token_budget = tokenBudget;
   }
+  if (automaticRetry === 'mcp_second_attempt') {
+    meta.automatic_retry = { attempt: 2, reason: 'retryable_error' };
+  }
   return meta;
 }
 
@@ -185,7 +194,7 @@ function withRequestMeta(source, tokenBudget) {
  * @returns {Promise<T>}
  */
 export async function withBridgeClient(callback, options) {
-  const client = new BridgeClient(options);
+  const client = new BridgeClient(await applyConfiguredAutoUpdate(options));
   await ensureClientConnected(client);
   try {
     return await callback(client);
@@ -661,6 +670,30 @@ function summarizeMetrics(value) {
     requestsProcessed: boundedCount(metrics.requestsProcessed),
     requestsFailed: boundedCount(metrics.requestsFailed),
     avgResponseTimeMs: boundedCount(metrics.avgResponseTimeMs),
+    recovery: normalizeRecoveryTelemetrySummary(metrics.recovery, 'daemon'),
+  };
+}
+
+/**
+ * @param {Record<string, unknown> | null} health
+ * @param {import('./types.js').DoctorDaemonMetrics | null} metrics
+ * @returns {import('./types.js').DoctorRecoveryDiagnostics}
+ */
+function summarizeRecovery(health, metrics) {
+  const recovery = asRecord(health?.recovery);
+  const daemon = metrics?.recovery ?? normalizeRecoveryTelemetrySummary(recovery?.daemon, 'daemon');
+  const routedExtension = normalizeRecoveryTelemetrySummary(
+    recovery?.routedExtension,
+    'routedExtension'
+  );
+  return {
+    daemon,
+    routedExtension,
+    activeLoops: RECOVERY_EVENT_KINDS.filter(
+      (kind) =>
+        daemon?.events[kind].activeLoop === true ||
+        routedExtension?.events[kind].activeLoop === true
+    ),
   };
 }
 
@@ -947,6 +980,7 @@ export async function getDoctorReport(options = {}) {
     },
     protocol: summarizeProtocol(null, false),
     debugger: summarizeDebugger(null),
+    recovery: summarizeRecovery(null, null),
     metrics: null,
     recentEvents: [],
     recentCauses: [],
@@ -1105,6 +1139,10 @@ export async function getDoctorReport(options = {}) {
     ),
   ];
   report.debugger = summarizeDebugger(report.healthAvailable ? resolvedHealth : null);
+  report.recovery = summarizeRecovery(
+    report.healthAvailable ? resolvedHealth : null,
+    report.metrics
+  );
   if (report.debugger.recentReason && !report.recentCauses.includes(report.debugger.recentReason)) {
     report.recentCauses.push(report.debugger.recentReason);
   }
@@ -1243,5 +1281,59 @@ export async function getDoctorReport(options = {}) {
     );
   }
 
-  return report;
+  for (const loop of report.recovery.activeLoops) {
+    const issue = `${loop}_loop`;
+    if (!report.issues.includes(issue)) report.issues.push(issue);
+    if (loop === 'stale_ref_recovery') {
+      report.nextSteps.push(
+        'Stale-reference recovery is repeatedly failing. Re-query the target for a fresh elementRef and retry once without reusing old refs.'
+      );
+    } else if (
+      loop === 'debugger_reattach' &&
+      report.debugger.state !== 'conflict' &&
+      !report.recentCauses.includes('debugger_conflict')
+    ) {
+      report.nextSteps.push(
+        'Debugger reattachment is repeatedly failing. Keep the tab open, close competing debuggers, and retry one debugger-backed operation.'
+      );
+    } else if (loop === 'content_script_reinjection') {
+      report.nextSteps.push(
+        'Content-script reinjection is repeatedly failing. Reload the Browser Bridge extension and target page, then enable the window again.'
+      );
+    } else if (loop === 'native_host_reconnect' && !authenticationFailed) {
+      report.nextSteps.push(
+        'Native-host reconnects are repeatedly failing. Run `bbx restart`; for remote TCP proxy use, verify the endpoint and rotate stale credentials with `bbx proxy enable --rotate-token`.'
+      );
+    } else if (loop === 'automatic_mcp_retry') {
+      report.nextSteps.push(
+        'Automatic MCP retries are repeatedly failing. Stop the retry loop, resolve the reported bridge readiness issue, then retry the original read once.'
+      );
+    } else if (loop === 'request_outcome') {
+      report.nextSteps.push(
+        'Browser requests are repeatedly failing. Inspect the first typed bridge error, narrow the request or target as directed, and retry once after correcting that specific failure.'
+      );
+    }
+  }
+
+  return {
+    ...report,
+    manifestPath: sanitizeDoctorPath(report.manifestPath),
+    daemonLogPath: sanitizeDoctorPath(report.daemonLogPath),
+    unwritableBridgePaths: report.unwritableBridgePaths.map(sanitizeDoctorPath),
+    nativeHostManifestIssues: report.nativeHostManifestIssues.map((issue) => ({
+      ...issue,
+      manifestPath: sanitizeDoctorPath(issue.manifestPath),
+      message: sanitizeIncidentalText(issue.message),
+    })),
+    browserManifests: report.browserManifests.map((browser) => ({
+      ...browser,
+      manifestPath: sanitizeDoctorPath(browser.manifestPath),
+    })),
+    nextSteps: report.nextSteps.map((step) => sanitizeIncidentalText(step)),
+  };
+}
+
+/** @param {string} value */
+function sanitizeDoctorPath(value) {
+  return value ? sanitizeIncidentalPath(value) : '';
 }