@btraut/browser-bridge 0.13.2 → 0.14.0

package/dist/api.js

@@ -51,14 +51,11 @@ var import_node_path2 = require("node:path");
 var import_node_fs = require("node:fs");
 var import_node_path = require("node:path");
 var DEFAULT_HOST = "127.0.0.1";
-var LEGACY_DEFAULT_PORT = 3210;
-var DETERMINISTIC_PORT_WINDOW = 2e3;
+var DEFAULT_PORT = 3210;
 var ENV_CORE_HOST = "BROWSER_BRIDGE_CORE_HOST";
 var ENV_VISION_HOST = "BROWSER_VISION_CORE_HOST";
 var ENV_CORE_PORT = "BROWSER_BRIDGE_CORE_PORT";
 var ENV_VISION_PORT = "BROWSER_VISION_CORE_PORT";
-var ENV_ISOLATED_MODE = "BROWSER_BRIDGE_ISOLATED_MODE";
-var ENV_VISION_ISOLATED_MODE = "BROWSER_VISION_ISOLATED_MODE";
 var ENV_BRIDGE_CWD = "BROWSER_BRIDGE_CWD";
 var ENV_PROCESS_PWD = "PWD";
 var ENV_PROCESS_INIT_CWD = "INIT_CWD";
@@ -115,22 +112,6 @@ var normalizeHost = (value) => {
   const trimmed = value.trim();
   return trimmed.length > 0 ? trimmed : void 0;
 };
-var parseBoolean = (value) => {
-  if (typeof value === "boolean") {
-    return value;
-  }
-  if (typeof value !== "string") {
-    return void 0;
-  }
-  const normalized = value.trim().toLowerCase();
-  if (normalized === "1" || normalized === "true" || normalized === "yes" || normalized === "on") {
-    return true;
-  }
-  if (normalized === "0" || normalized === "false" || normalized === "no" || normalized === "off") {
-    return false;
-  }
-  return void 0;
-};
 var parsePort = (value, label, invalidPolicy) => {
   if (value === void 0 || value === null) {
     return void 0;
@@ -147,60 +128,6 @@ var parsePort = (value, label, invalidPolicy) => {
   }
   return void 0;
 };
-var hashString = (value) => {
-  let hash = 2166136261;
-  for (let index = 0; index < value.length; index += 1) {
-    hash ^= value.charCodeAt(index);
-    hash = Math.imul(hash, 16777619);
-  }
-  return hash >>> 0;
-};
-var normalizePathForHash = (value) => value.replace(/\\/g, "/").toLowerCase();
-var sanitizeToken = (value) => value.trim().replace(/[^a-zA-Z0-9._-]+/g, "-").replace(/^-+|-+$/g, "");
-var fallbackWorktreeId = (gitRoot) => {
-  const hash = hashString(normalizePathForHash(gitRoot)).toString(16).padStart(8, "0");
-  return `wt-${hash}`;
-};
-var extractWorktreeIdFromGitDir = (gitDir) => {
-  const normalized = gitDir.replace(/\\/g, "/");
-  const marker = "/.git/worktrees/";
-  const markerIndex = normalized.lastIndexOf(marker);
-  if (markerIndex < 0) {
-    return null;
-  }
-  const remainder = normalized.slice(markerIndex + marker.length);
-  const rawId = remainder.split("/")[0];
-  if (!rawId) {
-    return null;
-  }
-  const sanitized = sanitizeToken(rawId);
-  return sanitized.length > 0 ? sanitized : null;
-};
-var readWorktreeGitDir = (gitRoot) => {
-  const gitPath = (0, import_node_path.join)(gitRoot, ".git");
-  try {
-    const stats = (0, import_node_fs.statSync)(gitPath);
-    if (stats.isDirectory()) {
-      return gitPath;
-    }
-    if (!stats.isFile()) {
-      return null;
-    }
-  } catch {
-    return null;
-  }
-  try {
-    const raw = (0, import_node_fs.readFileSync)(gitPath, "utf8");
-    const match = raw.match(/^gitdir:\s*(.+)$/m);
-    if (!match?.[1]) {
-      return null;
-    }
-    const candidate = match[1].trim();
-    return (0, import_node_path.isAbsolute)(candidate) ? candidate : (0, import_node_path.resolve)(gitRoot, candidate);
-  } catch {
-    return null;
-  }
-};
 var resolveEnvHost = (env) => {
   const bridgeHost = normalizeHost(env[ENV_CORE_HOST]);
   if (bridgeHost) {
@@ -214,35 +141,18 @@ var resolveEnvPortRaw = (env) => {
   }
   return env[ENV_VISION_PORT];
 };
-var resolveEnvIsolatedMode = (env) => {
-  const bridge = parseBoolean(env[ENV_ISOLATED_MODE]);
-  if (bridge !== void 0) {
-    return bridge;
-  }
-  return parseBoolean(env[ENV_VISION_ISOLATED_MODE]);
-};
 var sanitizeMetadata = (raw) => {
   if (!raw || typeof raw !== "object") {
     return null;
   }
   const candidate = raw;
-  const host = normalizeHost(candidate.host);
-  const port = parsePort(candidate.port, "port", "ignore");
-  const gitRoot = normalizeHost(candidate.git_root);
-  const worktreeId = normalizeHost(candidate.worktree_id);
   const extensionId = normalizeHost(candidate.extension_id);
-  const isolatedMode = parseBoolean(candidate.isolated_mode);
   const updatedAt = normalizeHost(candidate.updated_at);
-  if (!host && port === void 0 && !gitRoot && !worktreeId && !extensionId && isolatedMode === void 0 && !updatedAt) {
+  if (!extensionId && !updatedAt) {
     return null;
   }
   return {
-    host,
-    port,
-    git_root: gitRoot,
-    worktree_id: worktreeId,
     extension_id: extensionId,
-    isolated_mode: isolatedMode,
     updated_at: updatedAt
   };
 };
@@ -259,32 +169,6 @@ var findGitRoot = (cwd) => {
     current = parent;
   }
 };
-var resolveWorktreeId = ({
-  cwd,
-  gitRoot
-} = {}) => {
-  const resolvedGitRoot = gitRoot ?? findGitRoot(resolveCwd(cwd));
-  if (!resolvedGitRoot) {
-    return null;
-  }
-  const gitDir = readWorktreeGitDir(resolvedGitRoot);
-  const parsedId = gitDir ? extractWorktreeIdFromGitDir(gitDir) : null;
-  if (parsedId) {
-    return parsedId;
-  }
-  return fallbackWorktreeId(resolvedGitRoot);
-};
-var resolveDeterministicCorePort = ({
-  cwd,
-  gitRoot
-} = {}) => {
-  const resolvedGitRoot = gitRoot ?? findGitRoot(resolveCwd(cwd));
-  if (!resolvedGitRoot) {
-    return LEGACY_DEFAULT_PORT;
-  }
-  const seed = normalizePathForHash(resolvedGitRoot);
-  return LEGACY_DEFAULT_PORT + hashString(seed) % DETERMINISTIC_PORT_WINDOW;
-};
 var resolveRuntimeMetadataPath = ({
   cwd,
   gitRoot,
@@ -342,26 +226,6 @@ var writeRuntimeMetadata = (metadata, {
 `, "utf8");
   return path3;
 };
-var createBoundedPortProbeSequence = (startPort, maxAttempts = 20, maxPort = 65535) => {
-  const normalizedStart = parsePort(startPort, "startPort", "throw");
-  if (normalizedStart === void 0) {
-    throw new Error(`Invalid startPort: ${String(startPort)}`);
-  }
-  const attempts = Math.max(1, Math.floor(maxAttempts));
-  const ceiling = Math.min(65535, Math.max(1, Math.floor(maxPort)));
-  if (normalizedStart > ceiling) {
-    throw new Error(`startPort ${normalizedStart} exceeds maxPort ${ceiling}.`);
-  }
-  const sequence = [];
-  for (let offset = 0; offset < attempts; offset += 1) {
-    const port = normalizedStart + offset;
-    if (port > ceiling) {
-      break;
-    }
-    sequence.push(port);
-  }
-  return sequence;
-};
 var resolveCoreRuntime = (options = {}) => {
   const env = options.env ?? process.env;
   const resolvedCwd = resolveCwd(options.cwd);
@@ -372,45 +236,18 @@ var resolveCoreRuntime = (options = {}) => {
     metadataPath: options.metadataPath
   });
   const metadata = options.metadata === void 0 ? readRuntimeMetadata({ metadataPath }) : sanitizeMetadata(options.metadata);
-  const deterministicPort = resolveDeterministicCorePort({
-    cwd: resolvedCwd,
-    gitRoot
-  });
   const optionHost = normalizeHost(options.host);
   const envHost = resolveEnvHost(env);
-  const metadataHost = normalizeHost(metadata?.host);
-  const host = optionHost ?? envHost ?? metadataHost ?? DEFAULT_HOST;
-  const hostSource = optionHost ? "option" : envHost ? "env" : metadataHost ? "metadata" : "default";
+  const host = optionHost ?? envHost ?? DEFAULT_HOST;
+  const hostSource = optionHost ? "option" : envHost ? "env" : "default";
   const optionPort = parsePort(options.port, "port", "throw");
   const envPort = parsePort(
     resolveEnvPortRaw(env),
     "port",
     options.strictEnvPort ? "throw" : "ignore"
   );
-  const metadataPort = parsePort(metadata?.port, "port", "ignore");
-  const optionIsolatedMode = options.isolatedMode;
-  const envIsolatedMode = resolveEnvIsolatedMode(env);
-  const metadataIsolatedMode = metadata?.isolated_mode;
-  const isolatedMode = optionIsolatedMode ?? envIsolatedMode ?? metadataIsolatedMode ?? false;
-  const isolatedModeSource = optionIsolatedMode !== void 0 ? "option" : envIsolatedMode !== void 0 ? "env" : metadataIsolatedMode !== void 0 ? "metadata" : "default";
-  let port;
-  let portSource;
-  if (optionPort !== void 0) {
-    port = optionPort;
-    portSource = "option";
-  } else if (envPort !== void 0) {
-    port = envPort;
-    portSource = "env";
-  } else if (metadataPort !== void 0 && isolatedMode) {
-    port = metadataPort;
-    portSource = "metadata";
-  } else if (isolatedMode) {
-    port = deterministicPort;
-    portSource = "deterministic";
-  } else {
-    port = LEGACY_DEFAULT_PORT;
-    portSource = "default";
-  }
+  const port = optionPort ?? envPort ?? DEFAULT_PORT;
+  const portSource = optionPort !== void 0 ? "option" : envPort !== void 0 ? "env" : "default";
   return {
     host,
     port,
@@ -418,11 +255,7 @@ var resolveCoreRuntime = (options = {}) => {
     portSource,
     metadataPath,
     metadata,
-    gitRoot,
-    worktreeId: resolveWorktreeId({ cwd: resolvedCwd, gitRoot }),
-    deterministicPort,
-    isolatedMode,
-    isolatedModeSource
+    gitRoot
   };
 };
 
@@ -841,7 +674,7 @@ var createCoreReadinessController = (options = {}) => {
     }
     if (portOccupied) {
       throw new Error(
-        `Core daemon failed to start on ${runtime.host}:${runtime.port}. A process is already listening on this port but did not pass Browser Bridge health checks. Retry with --no-daemon to reuse it, or enable isolated mode (BROWSER_BRIDGE_ISOLATED_MODE=1) for per-worktree ports.`
+        `Core daemon failed to start on ${runtime.host}:${runtime.port}. A process is already listening on this port but did not pass Browser Bridge health checks. Retry with --no-daemon to reuse the existing process or stop whatever is already bound to that port.`
       );
     }
     throw new Error(
@@ -1169,9 +1002,7 @@ var DiagnosticsRuntimeEndpointSchema = import_zod3.z.object({
   port: import_zod3.z.number().finite().optional(),
   base_url: import_zod3.z.string().optional(),
   host_source: import_zod3.z.string().optional(),
-  port_source: import_zod3.z.string().optional(),
-  metadata_path: import_zod3.z.string().optional(),
-  isolated_mode: import_zod3.z.boolean().optional()
+  port_source: import_zod3.z.string().optional()
 });
 var DiagnosticsRuntimeProcessSchema = import_zod3.z.object({
   component: import_zod3.z.enum(["cli", "mcp", "core"]).optional(),
@@ -1192,12 +1023,13 @@ var DiagnosticsRuntimeContextSchema = import_zod3.z.object({
     process: DiagnosticsRuntimeProcessSchema.optional()
   }).optional(),
   extension: import_zod3.z.object({
+    extension_id: import_zod3.z.string().optional(),
     version: import_zod3.z.string().optional(),
     protocol_version: import_zod3.z.string().optional(),
     capability_negotiated: import_zod3.z.boolean().optional(),
     capabilities: import_zod3.z.record(import_zod3.z.string(), import_zod3.z.boolean()).optional(),
     endpoint: DiagnosticsRuntimeEndpointSchema.optional(),
-    port_source: import_zod3.z.enum(["default", "storage"]).optional()
+    port_source: import_zod3.z.enum(["default"]).optional()
   }).optional()
 });
 var DiagnosticReportSchema = import_zod3.z.object({
@@ -1272,7 +1104,7 @@ var DriveNavigateInputSchema = import_zod3.z.object({
   session_id: import_zod3.z.string().min(1).optional(),
   url: import_zod3.z.string().min(1),
   tab_id: import_zod3.z.number().finite().optional(),
-  wait: import_zod3.z.enum(["none", "domcontentloaded"]).default("domcontentloaded")
+  wait: import_zod3.z.enum(["none", "domcontentloaded", "networkidle"]).default("domcontentloaded")
 });
 var DriveNavigateOutputSchema = OpResultSchema.extend({
   session_id: import_zod3.z.string().min(1)
@@ -1441,6 +1273,8 @@ var InspectConsistencySchema = import_zod3.z.enum(["best_effort", "quiesce"]);
 var TargetHintSchema = import_zod3.z.object({
   url: import_zod3.z.string().min(1).optional(),
   title: import_zod3.z.string().min(1).optional(),
+  tab_id: import_zod3.z.number().finite().optional(),
+  tabId: import_zod3.z.number().finite().optional(),
   last_active_at: import_zod3.z.string().optional(),
   lastActiveAt: import_zod3.z.string().optional()
 });
@@ -1635,6 +1469,7 @@ var HealthCheckOutputSchema = import_zod3.z.object({
   }).passthrough(),
   extension: import_zod3.z.object({
     connected: import_zod3.z.boolean(),
+    extension_id: import_zod3.z.string().optional(),
     last_seen_at: import_zod3.z.string().min(1).optional()
   }).passthrough()
 }).passthrough();
@@ -1744,7 +1579,8 @@ var SessionRegistry = class {
       state: "INIT" /* INIT */,
       createdAt: now,
       updatedAt: now,
-      lastAccessedAt: now
+      lastAccessedAt: now,
+      selectedTabId: void 0
     };
     this.sessions.set(id, session);
     return session;
@@ -1843,6 +1679,18 @@ var SessionRegistry = class {
     session.updatedAt = /* @__PURE__ */ new Date();
     return session;
   }
+  setSelectedTab(sessionId, tabId) {
+    const session = this.require(sessionId);
+    session.selectedTabId = tabId;
+    session.updatedAt = /* @__PURE__ */ new Date();
+    return session;
+  }
+  clearSelectedTab(sessionId) {
+    const session = this.require(sessionId);
+    session.selectedTabId = void 0;
+    session.updatedAt = /* @__PURE__ */ new Date();
+    return session;
+  }
 };
 
 // packages/core/src/routes/shared.ts
@@ -1883,13 +1731,14 @@ var deriveHintFromTabs = (tabs) => {
   if (!Array.isArray(tabs) || tabs.length === 0) {
     return void 0;
   }
+  const candidatePool = tabs.some((tab) => tab.active === true) ? tabs.filter((tab) => tab.active === true) : tabs;
   let best;
   let bestTime = -Infinity;
-  for (const tab of tabs) {
+  for (const tab of candidatePool) {
     const raw = tab.last_active_at;
     const time = raw ? Date.parse(raw) : NaN;
     const score = Number.isFinite(time) ? time : -Infinity;
-    if (!best || score > bestTime) {
+    if (!best || score > bestTime || score === bestTime && tab.tab_id < best.tab_id) {
       best = tab;
       bestTime = score;
     }
@@ -1965,7 +1814,8 @@ var createSessionRouter = (registry, options = {}) => {
       return sendResult(res, {
         session_id: session.id,
         state: session.state,
-        updated_at: session.updatedAt.toISOString()
+        updated_at: session.updatedAt.toISOString(),
+        ...typeof session.selectedTabId === "number" ? { selected_tab_id: session.selectedTabId } : {}
       });
     } catch (error) {
       if (error instanceof SessionError) {
@@ -2103,9 +1953,6 @@ var InspectError = class extends Error {
 var import_crypto3 = require("crypto");
 var import_promises3 = require("node:fs/promises");
 var import_node_path4 = __toESM(require("node:path"));
-var import_readability = require("@mozilla/readability");
-var import_jsdom = require("jsdom");
-var import_turndown = __toESM(require("turndown"));
 
 // packages/core/src/artifacts.ts
 var import_promises2 = require("node:fs/promises");
@@ -2172,6 +2019,7 @@ var ExtensionBridge = class {
     return {
       connected: this.connected,
       lastSeenAt: this.lastSeenAt,
+      extensionId: this.extensionId,
       version: this.version,
       protocolVersion: this.protocolVersion,
       protocolMismatch: this.protocolMismatch,
@@ -2352,6 +2200,7 @@ var ExtensionBridge = class {
     this.stopHeartbeat();
     this.connected = false;
     this.socket = null;
+    this.extensionId = void 0;
     this.version = void 0;
     this.protocolVersion = void 0;
     this.protocolMismatch = void 0;
@@ -2414,6 +2263,11 @@ var ExtensionBridge = class {
         this.tabs = tabs;
       }
       if (message.action === "drive.hello") {
+        if (typeof params?.extension_id === "string") {
+          this.extensionId = params.extension_id;
+        } else {
+          this.extensionId = void 0;
+        }
         if (typeof params?.version === "string") {
           this.version = params.version;
         }
@@ -2436,7 +2290,7 @@ var ExtensionBridge = class {
         if (typeof params?.core_port === "number" && Number.isFinite(params.core_port)) {
           this.corePort = params.core_port;
         }
-        if (params?.core_port_source === "default" || params?.core_port_source === "storage") {
+        if (params?.core_port_source === "default") {
           this.corePortSource = params.core_port_source;
         }
         const capabilities = params?.capabilities;
@@ -2524,7 +2378,26 @@ var toDriveError = (error) => ({
 
 // packages/core/src/drive.ts
 var LOOPBACK_NAVIGATION_PREFLIGHT_TIMEOUT_MS = 1200;
+var POST_CLICK_SETTLE_MS = 75;
+var TRANSIENT_LOCATOR_RETRY_DELAY_MS = 150;
 var LOOPBACK_HOSTS = /* @__PURE__ */ new Set(["localhost", "127.0.0.1", "::1"]);
+var ACTIONS_WITH_OPTIONAL_TAB_ID = /* @__PURE__ */ new Set([
+  "drive.navigate",
+  "drive.go_back",
+  "drive.go_forward",
+  "drive.click",
+  "drive.hover",
+  "drive.select",
+  "drive.type",
+  "drive.fill_form",
+  "drive.drag",
+  "drive.handle_dialog",
+  "drive.key",
+  "drive.key_press",
+  "drive.scroll",
+  "drive.screenshot",
+  "drive.wait_for"
+]);
 var isLikelyUnreachableLoopbackError = (message) => {
   const normalized = message.toLowerCase();
   return normalized.includes("connection refused") || normalized.includes("econnrefused") || normalized.includes("err_connection_refused") || normalized.includes("enotfound") || normalized.includes("err_name_not_resolved") || normalized.includes("eai_again") || normalized.includes("ehostunreach") || normalized.includes("enetunreach");
@@ -2621,10 +2494,26 @@ var DriveController = class {
     this.lastError = void 0;
     this.lastErrorAt = void 0;
   }
+  async sleep(ms) {
+    await new Promise((resolve3) => setTimeout(resolve3, ms));
+  }
+  isTransientLocatorError(action, error) {
+    if (action !== "drive.click") {
+      return false;
+    }
+    if (error.code.toUpperCase() !== "NOT_FOUND") {
+      return false;
+    }
+    const reason = error.details?.reason;
+    const legacyCode = error.details?.legacy_code;
+    const resource = error.details?.resource;
+    return reason === "locator_not_found" || legacyCode === "LOCATOR_NOT_FOUND" || resource === "locator";
+  }
   async execute(sessionId, action, params, timeoutMs) {
     return await driveMutex.runExclusive(async () => {
+      let selectedTabId;
       try {
-        this.registry.require(sessionId);
+        selectedTabId = this.registry.require(sessionId).selectedTabId;
       } catch (error) {
         if (error instanceof SessionError) {
           const errorInfo2 = {
@@ -2668,7 +2557,12 @@ var DriveController = class {
         return { ok: false, error: errorInfo };
       }
       this.ensureDriveReady(sessionId);
-      const preflightError = await preflightLoopbackNavigation(action, params);
+      const prepared = this.prepareRequestParams(action, params, selectedTabId);
+      const requestParams = prepared.params;
+      const preflightError = await preflightLoopbackNavigation(
+        action,
+        requestParams
+      );
       if (preflightError) {
         this.recordError(preflightError);
         return {
@@ -2681,10 +2575,19 @@ var DriveController = class {
         try {
           const response = await this.bridge.request(
             action,
-            params,
+            requestParams,
             timeoutMs
           );
           if (response.status === "ok") {
+            if (action === "drive.click") {
+              await this.sleep(POST_CLICK_SETTLE_MS);
+            }
+            this.applySessionTargetOnSuccess(
+              sessionId,
+              action,
+              requestParams,
+              response.result
+            );
             this.clearLastError();
             return {
               ok: true,
@@ -2701,6 +2604,11 @@ var DriveController = class {
               max_attempts: 1
             }
           };
+          if (attempt === 0 && this.isTransientLocatorError(action, errorInfo)) {
+            attempt += 1;
+            await this.sleep(TRANSIENT_LOCATOR_RETRY_DELAY_MS);
+            continue;
+          }
           if (shouldRetryDriveOp({
             attempt,
             retryable: errorInfo.retryable,
@@ -2709,6 +2617,9 @@ var DriveController = class {
             attempt += 1;
             continue;
           }
+          if (prepared.injectedSessionTabId && this.isMissingTabError(errorInfo)) {
+            this.clearSessionTarget(sessionId);
+          }
           this.recordError(errorInfo);
           return { ok: false, error: errorInfo };
         } catch (error) {
@@ -2725,6 +2636,9 @@ var DriveController = class {
               attempt += 1;
               continue;
             }
+            if (prepared.injectedSessionTabId && this.isMissingTabError(errorInfo2)) {
+              this.clearSessionTarget(sessionId);
+            }
             this.recordError(errorInfo2);
             return { ok: false, error: errorInfo2 };
           }
@@ -2742,6 +2656,74 @@ var DriveController = class {
       }
     });
   }
+  readTabId(params) {
+    const value = params?.tab_id;
+    return typeof value === "number" && Number.isFinite(value) ? value : void 0;
+  }
+  readTabIdFromResult(result) {
+    if (!result || typeof result !== "object" || Array.isArray(result)) {
+      return void 0;
+    }
+    const value = result.tab_id;
+    return typeof value === "number" && Number.isFinite(value) ? value : void 0;
+  }
+  prepareRequestParams(action, params, selectedTabId) {
+    if (!ACTIONS_WITH_OPTIONAL_TAB_ID.has(action)) {
+      return { params, injectedSessionTabId: false };
+    }
+    if (!selectedTabId || selectedTabId <= 0) {
+      return { params, injectedSessionTabId: false };
+    }
+    const explicitTabId = this.readTabId(params);
+    if (explicitTabId !== void 0) {
+      return { params, injectedSessionTabId: false };
+    }
+    return {
+      params: { ...params ?? {}, tab_id: selectedTabId },
+      injectedSessionTabId: true
+    };
+  }
+  applySessionTargetOnSuccess(sessionId, action, params, result) {
+    const tabId = this.readTabIdFromResult(result) ?? this.readTabId(params);
+    if (tabId === void 0) {
+      return;
+    }
+    try {
+      if (action === "drive.tab_close") {
+        const session = this.registry.require(sessionId);
+        if (session.selectedTabId === tabId) {
+          this.registry.clearSelectedTab(sessionId);
+        }
+        return;
+      }
+      if (action === "drive.tab_activate" || ACTIONS_WITH_OPTIONAL_TAB_ID.has(action)) {
+        this.registry.setSelectedTab(sessionId, tabId);
+      }
+    } catch (error) {
+      console.debug(
+        `Drive target update ignored for session ${sessionId}.`,
+        error
+      );
+    }
+  }
+  isMissingTabError(error) {
+    const code = error.code.toUpperCase();
+    if (code === "TAB_NOT_FOUND") {
+      return true;
+    }
+    const resource = error.details?.resource;
+    return code === "NOT_FOUND" && (resource === void 0 || resource === "tab");
+  }
+  clearSessionTarget(sessionId) {
+    try {
+      this.registry.clearSelectedTab(sessionId);
+    } catch (error) {
+      console.debug(
+        `Drive target clear ignored for session ${sessionId}.`,
+        error
+      );
+    }
+  }
   ensureDriveReady(sessionId) {
     try {
       const session = this.registry.require(sessionId);
@@ -2781,6 +2763,10 @@ var INTERACTIVE_AX_ROLES = /* @__PURE__ */ new Set([
   "textbox",
   "combobox",
   "listbox",
+  "menu",
+  "menuitem",
+  "menuitemcheckbox",
+  "menuitemradio",
   "checkbox",
   "radio",
   "switch",
@@ -3238,6 +3224,136 @@ var toConsoleEntry = (event) => {
   }
 };
 
+// packages/core/src/inspect/extract-content-policy.ts
+var import_readability = require("@mozilla/readability");
+var import_jsdom = require("jsdom");
+var import_turndown = __toESM(require("turndown"));
+var normalizeExtractedText = (value) => value.replace(/\s+/g, " ").trim();
+var collapseRepeatedMarkdownBlocks = (markdown) => {
+  const blocks = markdown.split(/\n{2,}/).map((block) => block.trim()).filter((block) => block.length > 0);
+  for (let sequenceLength = Math.floor(blocks.length / 2); sequenceLength >= 1; sequenceLength -= 1) {
+    for (let start = 0; start + sequenceLength * 2 <= blocks.length; start += 1) {
+      const first = blocks.slice(start, start + sequenceLength).map((block) => normalizeExtractedText(block)).join("\n");
+      const second = blocks.slice(start + sequenceLength, start + sequenceLength * 2).map((block) => normalizeExtractedText(block)).join("\n");
+      if (first.length === 0 || first !== second) {
+        continue;
+      }
+      blocks.splice(start + sequenceLength, sequenceLength);
+      sequenceLength = Math.min(
+        sequenceLength + 1,
+        Math.floor(blocks.length / 2)
+      );
+      start = Math.max(start - 1, -1);
+    }
+  }
+  return blocks.join("\n\n").trim();
+};
+var extractSemanticMainCandidate = (document) => {
+  const candidates = Array.from(
+    document.querySelectorAll('main, [role="main"], article')
+  );
+  let best = candidates[0] ?? null;
+  let bestLength = 0;
+  for (const candidate of candidates) {
+    const text = normalizeExtractedText(candidate.textContent ?? "");
+    if (text.length <= bestLength) {
+      continue;
+    }
+    best = candidate;
+    bestLength = text.length;
+  }
+  if (!best || bestLength === 0) {
+    return null;
+  }
+  return {
+    html: best.innerHTML,
+    text: normalizeExtractedText(best.textContent ?? ""),
+    tagName: best.tagName.toLowerCase()
+  };
+};
+var shouldPreferSemanticMainCandidate = (options) => {
+  const articleLength = normalizeExtractedText(options.articleText).length;
+  const mainLength = normalizeExtractedText(options.mainText).length;
+  if (mainLength === 0) {
+    return false;
+  }
+  if (articleLength === 0) {
+    return true;
+  }
+  if (options.mainTagName === "article") {
+    return false;
+  }
+  return articleLength < 160 && mainLength > articleLength + 20;
+};
+var parseExtractContentSource = (options) => {
+  let article = null;
+  let semanticMainCandidate = null;
+  try {
+    const dom = new import_jsdom.JSDOM(options.html, { url: options.url });
+    const reader = new import_readability.Readability(dom.window.document);
+    article = reader.parse();
+    semanticMainCandidate = extractSemanticMainCandidate(dom.window.document);
+  } catch {
+    throw new InspectError(
+      "EVALUATION_FAILED",
+      "Failed to parse page content.",
+      {
+        retryable: false
+      }
+    );
+  }
+  if (!article) {
+    throw new InspectError(
+      "NOT_SUPPORTED",
+      "Readability could not extract content.",
+      {
+        retryable: false
+      }
+    );
+  }
+  return {
+    article,
+    semanticMainCandidate
+  };
+};
+var renderExtractContent = (options) => {
+  let content = "";
+  if (options.format === "article_json") {
+    content = JSON.stringify(options.article, null, 2);
+  } else if (options.format === "text") {
+    const articleText = options.article.textContent ?? "";
+    if (options.semanticMainCandidate && shouldPreferSemanticMainCandidate({
+      articleText,
+      mainText: options.semanticMainCandidate.text,
+      mainTagName: options.semanticMainCandidate.tagName
+    })) {
+      content = options.semanticMainCandidate.text;
+    } else {
+      content = articleText;
+    }
+  } else {
+    const turndown = new import_turndown.default();
+    const articleText = options.article.textContent ?? "";
+    const sourceHtml = options.semanticMainCandidate && shouldPreferSemanticMainCandidate({
+      articleText,
+      mainText: options.semanticMainCandidate.text,
+      mainTagName: options.semanticMainCandidate.tagName
+    }) ? options.semanticMainCandidate.html : options.article.content ?? "";
+    content = collapseRepeatedMarkdownBlocks(turndown.turndown(sourceHtml));
+  }
+  const includeMetadata = options.includeMetadata ?? true;
+  return {
+    content,
+    ...includeMetadata ? {
+      title: options.article.title ?? void 0,
+      byline: options.article.byline ?? void 0,
+      excerpt: options.article.excerpt ?? void 0,
+      siteName: options.article.siteName ?? void 0
+    } : {},
+    ...options.warnings && options.warnings.length > 0 ? { warnings: options.warnings } : {}
+  };
+};
+
 // packages/core/src/inspect/har.ts
 var buildHar = (events, title) => {
   const requests = /* @__PURE__ */ new Map();
@@ -3539,11 +3655,19 @@ var SnapshotHistory = class {
 
 // packages/core/src/inspect/snapshot-refs.ts
 var SNAPSHOT_REF_ATTRIBUTE = "data-bv-ref";
+var SNAPSHOT_REF_REGISTRY_ID = "__bb_snapshot_ref_registry__";
 var MAX_REF_ASSIGNMENTS = 500;
 var MAX_REF_WARNINGS = 5;
 var isInspectError = (error) => Boolean(
   error && typeof error === "object" && "name" in error && error.name === "InspectError" && "message" in error && typeof error.message === "string"
 );
+var isExpectedSnapshotRefMiss = (error) => {
+  if (!isInspectError(error)) {
+    return false;
+  }
+  const message = error.message.toLowerCase();
+  return message.includes("could not find node") || message.includes("no node with given id") || message.includes("does not belong to the document");
+};
 var assignRefsToAxSnapshot = (snapshot) => {
   const nodes = getAxNodes(snapshot);
   const refs = /* @__PURE__ */ new Map();
@@ -3562,31 +3686,61 @@ var assignRefsToAxSnapshot = (snapshot) => {
     const ref = `@e${index}`;
     index += 1;
     node.ref = ref;
-    refs.set(backendId, ref);
+    refs.set(backendId, {
+      ref,
+      ...getAxRole(node) ? { role: getAxRole(node) } : {},
+      ...getAxName(node) ? { name: getAxName(node) } : {},
+      ...extractUrl(node) ? { url: extractUrl(node) } : {}
+    });
   }
   return refs;
 };
-var clearSnapshotRefs = async (tabId, debuggerCommand) => {
-  await debuggerCommand(tabId, "Runtime.evaluate", {
-    expression: `document.querySelectorAll('[${SNAPSHOT_REF_ATTRIBUTE}]').forEach((el) => el.removeAttribute('${SNAPSHOT_REF_ATTRIBUTE}'))`,
-    returnByValue: true,
-    awaitPromise: true
-  });
+var extractUrl = (node) => {
+  if (!Array.isArray(node.properties)) {
+    return void 0;
+  }
+  for (const prop of node.properties) {
+    if (!prop || typeof prop !== "object") {
+      continue;
+    }
+    const name = prop.name;
+    if (name !== "url") {
+      continue;
+    }
+    const value = prop.value?.value;
+    if (typeof value === "string" && value.length > 0) {
+      return value;
+    }
+  }
+  return void 0;
 };
-var applySnapshotRefs = async (tabId, refs, debuggerCommand) => {
-  const warnings = [];
-  await debuggerCommand(tabId, "DOM.enable", {});
-  await debuggerCommand(tabId, "Runtime.enable", {});
+var clearSnapshotRefArtifacts = async (tabId, debuggerCommand) => {
   try {
-    await clearSnapshotRefs(tabId, debuggerCommand);
+    await debuggerCommand(tabId, "Runtime.evaluate", {
+      expression: `(() => {
+        document.querySelectorAll('[${SNAPSHOT_REF_ATTRIBUTE}]').forEach((el) => el.removeAttribute('${SNAPSHOT_REF_ATTRIBUTE}'));
+        document.getElementById('${SNAPSHOT_REF_REGISTRY_ID}')?.remove();
+      })()`,
+      returnByValue: true,
+      awaitPromise: true
+    });
+    return { warnings: [] };
   } catch {
-    warnings.push("Failed to clear prior snapshot refs.");
+    return { warnings: ["Failed to clear prior snapshot refs."] };
   }
+};
+var applySnapshotRefAttributes = async (tabId, refs, debuggerCommand) => {
+  const warnings = [];
+  const appliedRefs = /* @__PURE__ */ new Set();
+  const appliedBindings = [];
+  await debuggerCommand(tabId, "DOM.enable", {});
+  await debuggerCommand(tabId, "Runtime.enable", {});
   if (refs.size === 0) {
-    return warnings;
+    return { warnings, appliedRefs, appliedBindings };
   }
   let applied = 0;
-  for (const [backendNodeId, ref] of refs) {
+  for (const [backendNodeId, binding] of refs) {
+    const ref = binding.ref;
     if (applied >= MAX_REF_ASSIGNMENTS) {
       warnings.push(
         `Snapshot refs truncated at ${MAX_REF_ASSIGNMENTS} elements.`
@@ -3599,9 +3753,6 @@ var applySnapshotRefs = async (tabId, refs, debuggerCommand) => {
       });
       const node = described.node;
       if (!node || node.nodeType !== 1 || typeof node.nodeId !== "number") {
-        if (warnings.length < MAX_REF_WARNINGS) {
-          warnings.push(`Ref ${ref} could not be applied to a DOM element.`);
-        }
         continue;
       }
       await debuggerCommand(tabId, "DOM.setAttributeValue", {
@@ -3610,13 +3761,52 @@ var applySnapshotRefs = async (tabId, refs, debuggerCommand) => {
         value: ref
       });
       applied += 1;
-    } catch {
+      appliedRefs.add(ref);
+      appliedBindings.push(binding);
+    } catch (error) {
+      if (isExpectedSnapshotRefMiss(error)) {
+        continue;
+      }
       if (warnings.length < MAX_REF_WARNINGS) {
         warnings.push(`Ref ${ref} could not be applied.`);
       }
     }
   }
-  return warnings;
+  return { warnings, appliedRefs, appliedBindings };
+};
+var persistSnapshotRefRegistry = async (tabId, bindings, debuggerCommand) => {
+  try {
+    const registry = JSON.stringify(bindings);
+    await debuggerCommand(tabId, "Runtime.evaluate", {
+      expression: `(() => {
+        const id = ${JSON.stringify(SNAPSHOT_REF_REGISTRY_ID)};
+        let el = document.getElementById(id);
+        if (!el) {
+          el = document.createElement('script');
+          el.id = id;
+          el.type = 'application/json';
+          document.documentElement.appendChild(el);
+        }
+        el.textContent = ${JSON.stringify(registry)};
+      })()`,
+      returnByValue: true,
+      awaitPromise: true
+    });
+    return { warnings: [] };
+  } catch {
+    return { warnings: ["Snapshot ref registry could not be applied."] };
+  }
+};
+var pruneUnappliedRefsFromSnapshot = (snapshot, appliedRefs) => {
+  for (const node of getAxNodes(snapshot)) {
+    if (!node || typeof node !== "object") {
+      continue;
+    }
+    const ref = node.ref;
+    if (typeof ref === "string" && !appliedRefs.has(ref)) {
+      delete node.ref;
+    }
+  }
 };
 var resolveNodeIdForSelector = async (tabId, selector, debuggerCommand) => {
   await debuggerCommand(tabId, "DOM.enable", {});
@@ -3645,107 +3835,6 @@ var resolveNodeIdForSelector = async (tabId, selector, debuggerCommand) => {
   }
 };
 
-// packages/core/src/page-state-script.ts
-var PAGE_STATE_SCRIPT = [
-  "(() => {",
-  "  const escape = (value) => {",
-  "    if (typeof CSS !== 'undefined' && typeof CSS.escape === 'function') {",
-  "      return CSS.escape(value);",
-  "    }",
-  `    return String(value).replace(/["'\\\\]/g, '\\\\$&');`,
-  "  };",
-  "  const truncate = (value, max) => {",
-  "    const text = String(value ?? '');",
-  "    return text.length > max ? text.slice(0, max) : text;",
-  "  };",
-  "  const selectorFor = (element) => {",
-  "    if (element.id) {",
-  "      return `#${escape(element.id)}`;",
-  "    }",
-  "    const name = element.getAttribute('name');",
-  "    if (name) {",
-  '      return `${element.tagName.toLowerCase()}[name="${escape(name)}"]`;',
-  "    }",
-  "    const parts = [];",
-  "    let node = element;",
-  "    while (node && node.nodeType === 1 && parts.length < 4) {",
-  "      let part = node.tagName.toLowerCase();",
-  "      const parent = node.parentElement;",
-  "      if (parent) {",
-  "        const siblings = Array.from(parent.children).filter(",
-  "          (child) => child.tagName === node.tagName",
-  "        );",
-  "        if (siblings.length > 1) {",
-  "          part += `:nth-of-type(${siblings.indexOf(node) + 1})`;",
-  "        }",
-  "      }",
-  "      parts.unshift(part);",
-  "      node = parent;",
-  "    }",
-  "    return parts.join('>');",
-  "  };",
-  "  const readStorage = (storage, limit) => {",
-  "    try {",
-  "      return Object.keys(storage)",
-  "        .slice(0, limit)",
-  "        .map((key) => ({",
-  "          key,",
-  "          value: truncate(storage.getItem(key), 500),",
-  "        }));",
-  "    } catch {",
-  "      return [];",
-  "    }",
-  "  };",
-  "  const forms = Array.from(document.querySelectorAll('form')).map((form) => {",
-  "    const fields = Array.from(form.elements)",
-  "      .filter((element) => element && element.tagName)",
-  "      .map((element) => {",
-  "        const tag = element.tagName.toLowerCase();",
-  "        const type = 'type' in element && element.type ? element.type : tag;",
-  "        const name = element.name || element.getAttribute('name') || element.id || '';",
-  "        let value = '';",
-  "        let options;",
-  "        if (tag === 'select') {",
-  "          const select = element;",
-  "          value = select.value ?? '';",
-  "          options = Array.from(select.options).map((option) => option.text);",
-  "        } else if (tag === 'input' && element.type === 'password') {",
-  "          value = '[redacted]';",
-  "        } else if (tag === 'input' || tag === 'textarea') {",
-  "          value = element.value ?? '';",
-  "        } else if (element.isContentEditable) {",
-  "          value = element.textContent ?? '';",
-  "        } else if ('value' in element) {",
-  "          value = element.value ?? '';",
-  "        }",
-  "        return {",
-  "          name,",
-  "          type,",
-  "          value: truncate(value, 500),",
-  "          ...(options ? { options } : {}),",
-  "        };",
-  "      });",
-  "    return {",
-  "      selector: selectorFor(form),",
-  "      action: form.getAttribute('action') || undefined,",
-  "      method: form.getAttribute('method') || undefined,",
-  "      fields,",
-  "    };",
-  "  });",
-  "  const localStorage = readStorage(window.localStorage, 100);",
-  "  const sessionStorage = readStorage(window.sessionStorage, 100);",
-  "  const cookies = (document.cookie ? document.cookie.split(';') : [])",
-  "    .map((entry) => entry.trim())",
-  "    .filter((entry) => entry.length > 0)",
-  "    .slice(0, 50)",
-  "    .map((entry) => {",
-  "      const [key, ...rest] = entry.split('=');",
-  "      return { key, value: truncate(rest.join('='), 500) };",
-  "    });",
-  "  return { forms, localStorage, sessionStorage, cookies };",
-  "})()"
-].join("\n");
-
 // packages/core/src/target-matching.ts
 var normalizeText = (value) => (value ?? "").trim().toLowerCase();
 var normalizeUrl = (value) => {
@@ -3851,6 +3940,199 @@ var pickBestTarget = (candidates, hint, now = Date.now()) => {
   return ranked.length > 0 ? ranked[0] : null;
 };
 
+// packages/core/src/inspect/target-selection.ts
+var readTargetHintInput = (target) => {
+  if (!target) {
+    return void 0;
+  }
+  const url = typeof target.url === "string" ? target.url : void 0;
+  const title = typeof target.title === "string" ? target.title : void 0;
+  const tabIdRaw = target.tab_id ?? target.tabId;
+  const tabId = typeof tabIdRaw === "number" ? tabIdRaw : void 0;
+  const lastActiveAtRaw = target.last_active_at ?? target.lastActiveAt;
+  const lastActiveAt = typeof lastActiveAtRaw === "string" ? lastActiveAtRaw : void 0;
+  if (!url && !title && tabId === void 0 && !lastActiveAt) {
+    return void 0;
+  }
+  return { url, title, tabId, lastActiveAt };
+};
+var readSessionTargetHint = (registry, sessionId) => {
+  if (typeof sessionId !== "string") {
+    return void 0;
+  }
+  const selectedTabId = registry.get(sessionId)?.selectedTabId;
+  return typeof selectedTabId === "number" && Number.isFinite(selectedTabId) ? { tabId: selectedTabId } : void 0;
+};
+var resolveInspectTargetHint = (options) => {
+  const explicit = readTargetHintInput(options.target);
+  if (explicit) {
+    return explicit;
+  }
+  const sessionHint = readSessionTargetHint(
+    options.registry,
+    options.sessionId
+  );
+  if (sessionHint) {
+    return sessionHint;
+  }
+  const tabs = options.extensionBridge?.getStatus().tabs ?? [];
+  return deriveHintFromTabs(tabs);
+};
+var selectInspectTab = (options) => {
+  if (!options.extensionBridge || !options.extensionBridge.isConnected()) {
+    throw new InspectError(
+      "EXTENSION_DISCONNECTED",
+      "Extension is not connected.",
+      {
+        retryable: true
+      }
+    );
+  }
+  const tabs = options.extensionBridge.getStatus().tabs ?? [];
+  if (!Array.isArray(tabs) || tabs.length === 0) {
+    throw new InspectError("TAB_NOT_FOUND", "No tabs available to inspect.");
+  }
+  const effectiveHint = options.targetHint ?? readSessionTargetHint(options.registry, options.sessionId);
+  if (typeof effectiveHint?.tabId === "number" && Number.isFinite(effectiveHint.tabId)) {
+    const tab2 = tabs.find((entry) => entry.tab_id === effectiveHint.tabId);
+    if (!tab2) {
+      throw new InspectError(
+        "TAB_NOT_FOUND",
+        `No matching tab found for tab_id ${effectiveHint.tabId}.`,
+        { details: { tab_id: effectiveHint.tabId } }
+      );
+    }
+    return { tabId: effectiveHint.tabId, tab: tab2 };
+  }
+  const candidates = tabs.map((tab2) => ({
+    id: String(tab2.tab_id),
+    url: tab2.url ?? "",
+    title: tab2.title,
+    lastSeenAt: tab2.last_active_at ? Date.parse(tab2.last_active_at) : void 0
+  }));
+  const ranked = pickBestTarget(candidates, effectiveHint);
+  if (!ranked) {
+    throw new InspectError("TAB_NOT_FOUND", "No matching tab found.");
+  }
+  const tabId = Number(ranked.candidate.id);
+  if (!Number.isFinite(tabId)) {
+    throw new InspectError("TAB_NOT_FOUND", "Resolved tab id is invalid.");
+  }
+  const tab = tabs.find((entry) => entry.tab_id === tabId) ?? tabs[0];
+  const warnings = [];
+  if (!effectiveHint) {
+    warnings.push("No target hint provided; using the most recent tab.");
+  } else if (ranked.score < 20) {
+    warnings.push("Weak target match; using best available tab.");
+  }
+  return {
+    tabId,
+    tab,
+    warnings: warnings.length > 0 ? warnings : void 0
+  };
+};
+
+// packages/core/src/page-state-script.ts
+var PAGE_STATE_SCRIPT = [
+  "(() => {",
+  "  const escape = (value) => {",
+  "    if (typeof CSS !== 'undefined' && typeof CSS.escape === 'function') {",
+  "      return CSS.escape(value);",
+  "    }",
+  `    return String(value).replace(/["'\\\\]/g, '\\\\$&');`,
+  "  };",
+  "  const truncate = (value, max) => {",
+  "    const text = String(value ?? '');",
+  "    return text.length > max ? text.slice(0, max) : text;",
+  "  };",
+  "  const selectorFor = (element) => {",
+  "    if (element.id) {",
+  "      return `#${escape(element.id)}`;",
+  "    }",
+  "    const name = element.getAttribute('name');",
+  "    if (name) {",
+  '      return `${element.tagName.toLowerCase()}[name="${escape(name)}"]`;',
+  "    }",
+  "    const parts = [];",
+  "    let node = element;",
+  "    while (node && node.nodeType === 1 && parts.length < 4) {",
+  "      let part = node.tagName.toLowerCase();",
+  "      const parent = node.parentElement;",
+  "      if (parent) {",
+  "        const siblings = Array.from(parent.children).filter(",
+  "          (child) => child.tagName === node.tagName",
+  "        );",
+  "        if (siblings.length > 1) {",
+  "          part += `:nth-of-type(${siblings.indexOf(node) + 1})`;",
+  "        }",
+  "      }",
+  "      parts.unshift(part);",
+  "      node = parent;",
+  "    }",
+  "    return parts.join('>');",
+  "  };",
+  "  const readStorage = (storage, limit) => {",
+  "    try {",
+  "      return Object.keys(storage)",
+  "        .slice(0, limit)",
+  "        .map((key) => ({",
+  "          key,",
+  "          value: truncate(storage.getItem(key), 500),",
+  "        }));",
+  "    } catch {",
+  "      return [];",
+  "    }",
+  "  };",
+  "  const forms = Array.from(document.querySelectorAll('form')).map((form) => {",
+  "    const fields = Array.from(form.elements)",
+  "      .filter((element) => element && element.tagName)",
+  "      .map((element) => {",
+  "        const tag = element.tagName.toLowerCase();",
+  "        const type = 'type' in element && element.type ? element.type : tag;",
+  "        const name = element.name || element.getAttribute('name') || element.id || '';",
+  "        let value = '';",
+  "        let options;",
+  "        if (tag === 'select') {",
+  "          const select = element;",
+  "          value = select.value ?? '';",
+  "          options = Array.from(select.options).map((option) => option.text);",
+  "        } else if (tag === 'input' && element.type === 'password') {",
+  "          value = '[redacted]';",
+  "        } else if (tag === 'input' || tag === 'textarea') {",
+  "          value = element.value ?? '';",
+  "        } else if (element.isContentEditable) {",
+  "          value = element.textContent ?? '';",
+  "        } else if ('value' in element) {",
+  "          value = element.value ?? '';",
+  "        }",
+  "        return {",
+  "          name,",
+  "          type,",
+  "          value: truncate(value, 500),",
+  "          ...(options ? { options } : {}),",
+  "        };",
+  "      });",
+  "    return {",
+  "      selector: selectorFor(form),",
+  "      action: form.getAttribute('action') || undefined,",
+  "      method: form.getAttribute('method') || undefined,",
+  "      fields,",
+  "    };",
+  "  });",
+  "  const localStorage = readStorage(window.localStorage, 100);",
+  "  const sessionStorage = readStorage(window.sessionStorage, 100);",
+  "  const cookies = (document.cookie ? document.cookie.split(';') : [])",
+  "    .map((entry) => entry.trim())",
+  "    .filter((entry) => entry.length > 0)",
+  "    .slice(0, 50)",
+  "    .map((entry) => {",
+  "      const [key, ...rest] = entry.split('=');",
+  "      return { key, value: truncate(rest.join('='), 500) };",
+  "    });",
+  "  return { forms, localStorage, sessionStorage, cookies };",
+  "})()"
+].join("\n");
+
 // packages/core/src/inspect/service.ts
 var DEFAULT_MAX_SNAPSHOTS_PER_SESSION = 20;
 var DEFAULT_MAX_SNAPSHOT_HISTORY = 100;
@@ -3895,7 +4177,7 @@ var InspectService = class {
   async reconnect(sessionId) {
     try {
       this.requireSession(sessionId);
-      const selection = await this.resolveTab();
+      const selection = await this.resolveTab(sessionId);
       const debuggerBridge = this.ensureDebugger();
       const result = await debuggerBridge.attach(selection.tabId);
       if (result.ok) {
@@ -3914,7 +4196,7 @@ var InspectService = class {
   }
   async domSnapshot(input) {
     this.requireSession(input.sessionId);
-    const selection = await this.resolveTab(input.targetHint);
+    const selection = await this.resolveTab(input.sessionId, input.targetHint);
     const debuggerCommand = this.debuggerCommand.bind(this);
     const work = async () => {
       if (input.format === "html") {
@@ -3964,20 +4246,11 @@ var InspectService = class {
           );
           selectorWarnings.push(...resolved.warnings ?? []);
           if (!resolved.nodeId) {
-            let refWarnings2 = [];
-            try {
-              refWarnings2 = await applySnapshotRefs(
-                selection.tabId,
-                /* @__PURE__ */ new Map(),
-                debuggerCommand
-              );
-            } catch {
-              refWarnings2 = ["Failed to clear prior snapshot refs."];
-            }
+            const refWarnings = (await clearSnapshotRefArtifacts(selection.tabId, debuggerCommand)).warnings;
             const warnings2 = [
               ...selection.warnings ?? [],
               ...selectorWarnings,
-              ...refWarnings2
+              ...refWarnings
             ];
             return {
               format: "ax",
@@ -4014,16 +4287,28 @@ var InspectService = class {
           }
         }
         const refMap = assignRefsToAxSnapshot(snapshot);
-        const refWarnings = await applySnapshotRefs(
+        const clearResult = await clearSnapshotRefArtifacts(
+          selection.tabId,
+          debuggerCommand
+        );
+        const refResult = await applySnapshotRefAttributes(
           selection.tabId,
           refMap,
           debuggerCommand
         );
+        const persistResult = refMap.size === 0 ? { warnings: [] } : await persistSnapshotRefRegistry(
+          selection.tabId,
+          refResult.appliedBindings,
+          debuggerCommand
+        );
+        pruneUnappliedRefsFromSnapshot(snapshot, refResult.appliedRefs);
         const warnings = [
           ...selection.warnings ?? [],
           ...selectorWarnings,
           ...truncationWarnings,
-          ...refWarnings ?? []
+          ...clearResult.warnings,
+          ...refResult.warnings,
+          ...persistResult.warnings
         ];
         return {
           format: "ax",
@@ -4149,7 +4434,7 @@ var InspectService = class {
   }
   async consoleList(input) {
     this.requireSession(input.sessionId);
-    const selection = await this.resolveTab(input.targetHint);
+    const selection = await this.resolveTab(input.sessionId, input.targetHint);
     await this.enableConsole(selection.tabId);
     const events = this.ensureDebugger().getConsoleEvents(selection.tabId);
     const entries = events.map((event) => toConsoleEntry(event)).filter((entry) => entry !== null);
@@ -4162,7 +4447,7 @@ var InspectService = class {
   }
   async networkHar(input) {
     this.requireSession(input.sessionId);
-    const selection = await this.resolveTab(input.targetHint);
+    const selection = await this.resolveTab(input.sessionId, input.targetHint);
     await this.enableNetwork(selection.tabId);
     const events = this.ensureDebugger().getNetworkEvents(selection.tabId);
     const har = buildHar(events, selection.tab.title);
@@ -4189,7 +4474,7 @@ var InspectService = class {
   }
   async evaluate(input) {
     this.requireSession(input.sessionId);
-    const selection = await this.resolveTab(input.targetHint);
+    const selection = await this.resolveTab(input.sessionId, input.targetHint);
     const expression = input.expression ?? "undefined";
     await this.debuggerCommand(selection.tabId, "Runtime.enable", {});
     const result = await this.debuggerCommand(
@@ -4218,7 +4503,7 @@ var InspectService = class {
   }
   async extractContent(input) {
     this.requireSession(input.sessionId);
-    const selection = await this.resolveTab(input.targetHint);
+    const selection = await this.resolveTab(input.sessionId, input.targetHint);
     const debuggerCommand = this.debuggerCommand.bind(this);
     const html = await captureHtml(selection.tabId, {
       debuggerCommand,
@@ -4233,56 +4518,30 @@ var InspectService = class {
       }
     });
     const url = selection.tab.url ?? "about:blank";
-    let article = null;
     try {
-      const dom = new import_jsdom.JSDOM(html, { url });
-      const reader = new import_readability.Readability(dom.window.document);
-      article = reader.parse();
-    } catch {
-      const err = new InspectError(
-        "EVALUATION_FAILED",
-        "Failed to parse page content.",
-        { retryable: false }
-      );
-      this.recordError(err);
-      throw err;
-    }
-    if (!article) {
-      const err = new InspectError(
-        "NOT_SUPPORTED",
-        "Readability could not extract content.",
-        { retryable: false }
-      );
-      this.recordError(err);
-      throw err;
-    }
-    let content = "";
-    if (input.format === "article_json") {
-      content = JSON.stringify(article, null, 2);
-    } else if (input.format === "text") {
-      content = article.textContent ?? "";
-    } else {
-      const turndown = new import_turndown.default();
-      content = turndown.turndown(article.content ?? "");
+      const { article, semanticMainCandidate } = parseExtractContentSource({
+        html,
+        url
+      });
+      const output = renderExtractContent({
+        format: input.format,
+        article,
+        semanticMainCandidate,
+        includeMetadata: input.includeMetadata,
+        warnings: selection.warnings
+      });
+      this.markInspectConnected(input.sessionId);
+      return output;
+    } catch (error) {
+      if (error instanceof InspectError) {
+        this.recordError(error);
+      }
+      throw error;
     }
-    const warnings = selection.warnings ?? [];
-    const includeMetadata = input.includeMetadata ?? true;
-    const output = {
-      content,
-      ...includeMetadata ? {
-        title: article.title ?? void 0,
-        byline: article.byline ?? void 0,
-        excerpt: article.excerpt ?? void 0,
-        siteName: article.siteName ?? void 0
-      } : {},
-      ...warnings.length > 0 ? { warnings } : {}
-    };
-    this.markInspectConnected(input.sessionId);
-    return output;
   }
   async pageState(input) {
     this.requireSession(input.sessionId);
-    const selection = await this.resolveTab(input.targetHint);
+    const selection = await this.resolveTab(input.sessionId, input.targetHint);
     await this.debuggerCommand(selection.tabId, "Runtime.enable", {});
     const expression = PAGE_STATE_SCRIPT;
     const result = await this.debuggerCommand(
@@ -4321,7 +4580,7 @@ var InspectService = class {
   }
   async performanceMetrics(input) {
     this.requireSession(input.sessionId);
-    const selection = await this.resolveTab(input.targetHint);
+    const selection = await this.resolveTab(input.sessionId, input.targetHint);
     await this.debuggerCommand(selection.tabId, "Performance.enable", {});
     const result = await this.debuggerCommand(
       selection.tabId,
@@ -4338,9 +4597,13 @@ var InspectService = class {
   }
   async screenshot(input) {
     this.requireSession(input.sessionId);
-    const selection = await this.resolveTab(input.targetHint);
+    const selection = await this.resolveTab(input.sessionId, input.targetHint);
     const format = input.format ?? "png";
-    const writeArtifact = async (data2) => {
+    const createScreenshotError = (code, message, retryable = false, details) => new InspectError(code, message, {
+      retryable,
+      ...details ? { details } : {}
+    });
+    const writeArtifact = async (data) => {
       try {
         const rootDir = await ensureArtifactRootDir(input.sessionId);
         const artifactId = (0, import_crypto3.randomUUID)();
@@ -4349,7 +4612,7 @@ var InspectService = class {
           rootDir,
           `screenshot-${artifactId}.${extension}`
         );
-        await (0, import_promises3.writeFile)(filePath, Buffer.from(data2, "base64"));
+        await (0, import_promises3.writeFile)(filePath, Buffer.from(data, "base64"));
         const mime = format === "jpeg" ? "image/jpeg" : `image/${format}`;
         const output = {
           artifact_id: artifactId,
@@ -4367,143 +4630,138 @@ var InspectService = class {
         throw error;
       }
     };
-    if (input.selector) {
+    const captureViaExtension = async (mode, failureMessage) => {
       if (!this.extensionBridge?.request) {
-        const error = new InspectError(
+        throw createScreenshotError(
           "NOT_SUPPORTED",
-          "Element screenshots require an extension that supports drive.screenshot."
+          "Screenshots require an extension that supports drive.screenshot."
         );
-        this.recordError(error);
-        throw error;
       }
       const response = await this.extensionBridge.request(
         "drive.screenshot",
         {
           tab_id: selection.tabId,
-          mode: "element",
-          selector: input.selector,
+          mode,
+          ...input.selector ? { selector: input.selector } : {},
           format,
           ...typeof input.quality === "number" ? { quality: input.quality } : {}
         },
         12e4
       );
       if (response.status === "error") {
-        const error = new InspectError(
+        const error = createScreenshotError(
           response.error?.code ?? "INSPECT_UNAVAILABLE",
-          response.error?.message ?? "Failed to capture element screenshot.",
-          {
-            retryable: response.error?.retryable ?? false,
-            ...response.error?.details ? { details: response.error.details } : {}
-          }
+          response.error?.message ?? failureMessage,
+          response.error?.retryable ?? false,
+          response.error?.details
+        );
+        this.recordError(error);
+        throw error;
+      }
+      const result = response.result;
+      if (!result?.data_base64 || typeof result.data_base64 !== "string") {
+        const error = createScreenshotError(
+          "INSPECT_UNAVAILABLE",
+          failureMessage
         );
         this.recordError(error);
         throw error;
       }
-      const result2 = response.result;
-      if (!result2?.data_base64 || typeof result2.data_base64 !== "string") {
+      return await writeArtifact(result.data_base64);
+    };
+    const shouldFallbackFromExtensionScreenshot = (error) => [
+      "NOT_SUPPORTED",
+      "NOT_IMPLEMENTED",
+      "INSPECT_UNAVAILABLE",
+      "PERMISSION_REQUIRED",
+      "RATE_LIMITED"
+    ].includes(error.code);
+    const shouldPreserveExtensionScreenshotError = (fallbackError) => [
+      "INSPECT_UNAVAILABLE",
+      "ATTACH_DENIED",
+      "NOT_SUPPORTED",
+      "NOT_IMPLEMENTED"
+    ].includes(fallbackError.code);
+    const captureViaDebugger = async () => {
+      await this.debuggerCommand(selection.tabId, "Page.enable", {});
+      let captureParams = {
+        format,
+        fromSurface: true
+      };
+      if (format !== "png" && typeof input.quality === "number") {
+        captureParams = { ...captureParams, quality: input.quality };
+      }
+      if (input.target === "full") {
+        const layout = await this.debuggerCommand(
+          selection.tabId,
+          "Page.getLayoutMetrics",
+          {}
+        );
+        const contentSize = layout?.contentSize;
+        if (contentSize) {
+          captureParams = {
+            ...captureParams,
+            clip: {
+              x: 0,
+              y: 0,
+              width: contentSize.width,
+              height: contentSize.height,
+              scale: 1
+            }
+          };
+        } else {
+          captureParams = { ...captureParams, captureBeyondViewport: true };
+        }
+      }
+      const result = await this.debuggerCommand(
+        selection.tabId,
+        "Page.captureScreenshot",
+        captureParams
+      );
+      const data = result.data;
+      if (!data) {
         const error = new InspectError(
           "INSPECT_UNAVAILABLE",
-          "Failed to capture element screenshot."
+          "Failed to capture screenshot.",
+          { retryable: false }
         );
         this.recordError(error);
         throw error;
       }
-      return await writeArtifact(result2.data_base64);
+      return await writeArtifact(data);
+    };
+    if (input.selector) {
+      return await captureViaExtension(
+        "element",
+        "Failed to capture element screenshot."
+      );
     }
-    if (input.target === "full" && this.extensionBridge?.request) {
+    let extensionScreenshotError;
+    if (this.extensionBridge?.request) {
       try {
-        const response = await this.extensionBridge.request(
-          "drive.screenshot",
-          {
-            tab_id: selection.tabId,
-            mode: "full_page",
-            format,
-            ...typeof input.quality === "number" ? { quality: input.quality } : {}
-          },
-          12e4
+        return await captureViaExtension(
+          input.target === "full" ? "full_page" : "viewport",
+          input.target === "full" ? "Failed to capture full page screenshot." : "Failed to capture viewport screenshot."
         );
-        if (response.status === "error") {
-          const error = new InspectError(
-            response.error?.code ?? "INSPECT_UNAVAILABLE",
-            response.error?.message ?? "Failed to capture full page screenshot.",
-            {
-              retryable: response.error?.retryable ?? false,
-              ...response.error?.details ? { details: response.error.details } : {}
-            }
-          );
-          this.recordError(error);
+      } catch (error) {
+        if (!(error instanceof InspectError)) {
           throw error;
         }
-        const result2 = response.result;
-        if (!result2?.data_base64 || typeof result2.data_base64 !== "string") {
-          const error = new InspectError(
-            "INSPECT_UNAVAILABLE",
-            "Failed to capture full page screenshot."
-          );
-          this.recordError(error);
+        if (!shouldFallbackFromExtensionScreenshot(error)) {
           throw error;
         }
-        return await writeArtifact(result2.data_base64);
-      } catch (error) {
-        if (error instanceof InspectError) {
-          const code = String(error.code);
-          if (!error.retryable && ![
-            "NOT_SUPPORTED",
-            "NOT_IMPLEMENTED",
-            "INSPECT_UNAVAILABLE",
-            "RATE_LIMITED"
-          ].includes(code)) {
-            throw error;
-          }
-        }
+        extensionScreenshotError = error;
       }
     }
-    await this.debuggerCommand(selection.tabId, "Page.enable", {});
-    let captureParams = {
-      format,
-      fromSurface: true
-    };
-    if (format !== "png" && typeof input.quality === "number") {
-      captureParams = { ...captureParams, quality: input.quality };
-    }
-    if (input.target === "full") {
-      const layout = await this.debuggerCommand(
-        selection.tabId,
-        "Page.getLayoutMetrics",
-        {}
-      );
-      const contentSize = layout?.contentSize;
-      if (contentSize) {
-        captureParams = {
-          ...captureParams,
-          clip: {
-            x: 0,
-            y: 0,
-            width: contentSize.width,
-            height: contentSize.height,
-            scale: 1
-          }
-        };
-      } else {
-        captureParams = { ...captureParams, captureBeyondViewport: true };
+    try {
+      return await captureViaDebugger();
+    } catch (error) {
+      if (extensionScreenshotError && error instanceof InspectError && shouldPreserveExtensionScreenshotError(error)) {
+        this.recordError(extensionScreenshotError);
+        throw extensionScreenshotError;
       }
-    }
-    const result = await this.debuggerCommand(
-      selection.tabId,
-      "Page.captureScreenshot",
-      captureParams
-    );
-    const data = result.data;
-    if (!data) {
-      const error = new InspectError(
-        "INSPECT_UNAVAILABLE",
-        "Failed to capture screenshot.",
-        { retryable: false }
-      );
-      this.recordError(error);
       throw error;
     }
-    return await writeArtifact(data);
   }
   ensureDebugger() {
     if (!this.debugger) {
@@ -4513,58 +4771,20 @@ var InspectService = class {
     }
     return this.debugger;
   }
-  async resolveTab(hint) {
-    if (!this.extensionBridge || !this.extensionBridge.isConnected()) {
-      const error = new InspectError(
-        "EXTENSION_DISCONNECTED",
-        "Extension is not connected.",
-        { retryable: true }
-      );
-      this.recordError(error);
-      throw error;
-    }
-    const tabs = this.extensionBridge.getStatus().tabs ?? [];
-    if (!Array.isArray(tabs) || tabs.length === 0) {
-      const error = new InspectError(
-        "TAB_NOT_FOUND",
-        "No tabs available to inspect."
-      );
-      this.recordError(error);
-      throw error;
-    }
-    const candidates = tabs.map((tab2) => ({
-      id: String(tab2.tab_id),
-      url: tab2.url ?? "",
-      title: tab2.title,
-      lastSeenAt: tab2.last_active_at ? Date.parse(tab2.last_active_at) : void 0
-    }));
-    const ranked = pickBestTarget(candidates, hint);
-    if (!ranked) {
-      const error = new InspectError("TAB_NOT_FOUND", "No matching tab found.");
-      this.recordError(error);
-      throw error;
-    }
-    const tabId = Number(ranked.candidate.id);
-    if (!Number.isFinite(tabId)) {
-      const error = new InspectError(
-        "TAB_NOT_FOUND",
-        "Resolved tab id is invalid."
-      );
-      this.recordError(error);
+  async resolveTab(sessionId, hint) {
+    try {
+      return selectInspectTab({
+        sessionId,
+        targetHint: hint,
+        registry: this.registry,
+        extensionBridge: this.extensionBridge
+      });
+    } catch (error) {
+      if (error instanceof InspectError) {
+        this.recordError(error);
+      }
       throw error;
     }
-    const tab = tabs.find((entry) => entry.tab_id === tabId) ?? tabs[0];
-    const warnings = [];
-    if (!hint) {
-      warnings.push("No target hint provided; using the most recent tab.");
-    } else if (ranked.score < 20) {
-      warnings.push("Weak target match; using best available tab.");
-    }
-    return {
-      tabId,
-      tab,
-      warnings: warnings.length > 0 ? warnings : void 0
-    };
   }
   async enableConsole(tabId) {
     await this.debuggerCommand(tabId, "Runtime.enable", {});
@@ -4667,7 +4887,11 @@ var sendArtifactsError = (res, code, message, details, retryable = false) => {
   });
 };
 var registerArtifactsRoutes = (router, options = {}) => {
-  const inspect = options.inspectService ?? (options.registry ? createInspectService({ registry: options.registry }) : void 0);
+  const inspect = options.inspectService ?? (options.registry ? createInspectService({
+    registry: options.registry,
+    extensionBridge: options.extensionBridge,
+    debuggerBridge: options.debuggerBridge
+  }) : void 0);
   router.post("/artifacts/screenshot", async (req, res) => {
     if (!isRecord2(req.body)) {
       sendArtifactsError(
@@ -4761,6 +4985,7 @@ var readCapability = (capabilities, name) => {
   const candidate = capabilities[name];
   return typeof candidate === "boolean" ? candidate : void 0;
 };
+var hasCapturePermissionErrorReason = (details) => typeof details?.reason === "string" && details.reason === "capture_visible_tab_permission_required";
 var hasEndpoint = (endpoint) => Boolean(
   endpoint && typeof endpoint.host === "string" && endpoint.host.length > 0 && typeof endpoint.port === "number" && Number.isFinite(endpoint.port)
 );
@@ -4773,9 +4998,7 @@ var toRuntimeEndpoint = (endpoint) => {
     port: endpoint.port,
     base_url: endpoint.baseUrl,
     host_source: endpoint.hostSource,
-    port_source: endpoint.portSource,
-    metadata_path: endpoint.metadataPath,
-    isolated_mode: endpoint.isolatedMode
+    port_source: endpoint.portSource
   };
 };
 var toRuntimeProcess = (process2) => {
@@ -4839,23 +5062,6 @@ var buildDiagnosticReport = (sessionId, context = {}) => {
       }
     });
   }
-  if (callerEndpoint?.metadataPath && coreEndpoint?.metadataPath) {
-    const matches = callerEndpoint.metadataPath === coreEndpoint.metadataPath;
-    checks.push({
-      name: "runtime.caller.metadata_path_match",
-      ok: matches,
-      message: matches ? "Caller metadata path matches the active core runtime metadata path." : "Caller metadata path differs from core runtime metadata path (shared core across worktrees).",
-      details: {
-        caller_metadata_path: callerEndpoint.metadataPath,
-        core_metadata_path: coreEndpoint.metadataPath
-      }
-    });
-    if (!matches) {
-      warnings.push(
-        "CLI is talking to a core process started from a different worktree metadata path. If daemon auto-start fails, retry with --no-daemon or enable isolated mode."
-      );
-    }
-  }
   if (extensionConnected && hasEndpoint(coreEndpoint) && hasEndpoint(extensionEndpoint)) {
     const matches = coreEndpoint.host === extensionEndpoint.host && coreEndpoint.port === extensionEndpoint.port;
     checks.push({
@@ -4903,7 +5109,7 @@ var buildDiagnosticReport = (sessionId, context = {}) => {
     checks.push({
       name: "inspect.capability",
       ok: capabilityNegotiated && inspectEnabled,
-      message: capabilityNegotiated && inspectEnabled ? "Inspect debugger capability is enabled." : capabilityNegotiated ? "Inspect debugger capability is disabled in extension options." : "Inspect capability is unknown until extension capability negotiation completes.",
+      message: capabilityNegotiated && inspectEnabled ? "Inspect capability is available." : capabilityNegotiated ? "Inspect capability is unavailable from the connected extension/runtime." : "Inspect capability is unknown until extension capability negotiation completes.",
       details: {
         required_capabilities: ["debugger.attach", "debugger.command"],
         debugger_attach: inspectAttachCapability,
@@ -4912,7 +5118,7 @@ var buildDiagnosticReport = (sessionId, context = {}) => {
     });
     if (capabilityNegotiated && !inspectEnabled) {
       warnings.push(
-        "Inspect commands require debugger capability. Enable debugger-based inspect in extension options to use inspect.* routes."
+        "Inspect commands are unavailable from the connected extension/runtime. Reload or update the extension, then verify inspect.capability before using inspect.* routes."
       );
     }
   }
@@ -4945,9 +5151,15 @@ var buildDiagnosticReport = (sessionId, context = {}) => {
         code: context.driveLastError.code,
         retryable: context.driveLastError.retryable,
         at: context.driveLastError.at,
+        ...context.driveLastError.details ?? {},
         ...ageMs !== void 0 ? { age_ms: ageMs } : {}
       }
     });
+    if (hasCapturePermissionErrorReason(context.driveLastError.details)) {
+      warnings.push(
+        "Screenshot capture permission is missing. Reload the Browser Bridge extension in chrome://extensions and retry screenshot capture."
+      );
+    }
   }
   if (context.inspectLastError) {
     const ageMs = getErrorAgeMs(context.inspectLastError.at);
@@ -4965,9 +5177,15 @@ var buildDiagnosticReport = (sessionId, context = {}) => {
         code: context.inspectLastError.code,
         retryable: context.inspectLastError.retryable,
         at: context.inspectLastError.at,
+        ...context.inspectLastError.details ?? {},
         ...ageMs !== void 0 ? { age_ms: ageMs } : {}
       }
     });
+    if (hasCapturePermissionErrorReason(context.inspectLastError.details)) {
+      warnings.push(
+        "Screenshot capture permission is missing. Reload the Browser Bridge extension in chrome://extensions and retry screenshot capture."
+      );
+    }
   }
   if (context.recoveryAttempt) {
     checks.push({
@@ -5001,6 +5219,7 @@ var buildDiagnosticReport = (sessionId, context = {}) => {
     } : void 0,
     extension: {
       connected: extensionConnected,
+      extension_id: context.extension?.extensionId,
       version: context.extension?.version,
       last_seen_at: context.extension?.lastSeenAt
     },
@@ -5037,6 +5256,7 @@ var buildDiagnosticReport = (sessionId, context = {}) => {
         process: toRuntimeProcess(context.runtime.core.process)
       } : void 0,
       extension: context.runtime.extension ? {
+        extension_id: context.runtime.extension.extensionId,
         version: context.runtime.extension.version,
         protocol_version: context.runtime.extension.protocolVersion,
         capability_negotiated: context.runtime.extension.capabilityNegotiated,
@@ -5084,12 +5304,78 @@ var registerDiagnosticsRoutes = (router, options = {}) => {
       sessions: { active: sessionsActive },
       extension: {
         connected: extensionStatus?.connected ?? false,
+        ...extensionStatus?.extensionId ? { extension_id: extensionStatus.extensionId } : {},
         ...extensionStatus?.lastSeenAt ? { last_seen_at: extensionStatus.lastSeenAt } : {}
       }
     });
   };
   router.post("/health/check", handleHealthCheck);
   router.post("/health_check", handleHealthCheck);
+  router.post("/diagnostics/enable_inspect", async (req, res) => {
+    const body = req.body ?? {};
+    if (!isRecord2(body)) {
+      sendError(res, 400, {
+        code: "INVALID_ARGUMENT",
+        message: "Request body must be an object.",
+        retryable: false
+      });
+      return;
+    }
+    const extensionIdRaw = body.extension_id;
+    if (extensionIdRaw !== void 0 && typeof extensionIdRaw !== "string") {
+      sendError(res, 400, {
+        code: "INVALID_ARGUMENT",
+        message: "extension_id must be a string when provided.",
+        retryable: false,
+        details: { field: "extension_id" }
+      });
+      return;
+    }
+    if (!options.extensionBridge) {
+      sendError(res, 503, {
+        code: "EXTENSION_DISCONNECTED",
+        message: "Extension bridge is unavailable.",
+        retryable: true
+      });
+      return;
+    }
+    try {
+      const envelope2 = await options.extensionBridge.request("drive.set_debugger_capability", {
+        enabled: true,
+        ...extensionIdRaw ? { extension_id: extensionIdRaw } : {}
+      });
+      if (envelope2.status === "error") {
+        const error = envelope2.error ?? {
+          code: "INTERNAL",
+          message: "Extension request failed.",
+          retryable: false
+        };
+        sendError(res, 409, {
+          code: error.code,
+          message: error.message,
+          retryable: error.retryable,
+          details: error.details
+        });
+        return;
+      }
+      sendResult(res, envelope2.result ?? { ok: true, enabled: true });
+    } catch (error) {
+      if (error instanceof ExtensionBridgeError) {
+        sendError(res, 409, {
+          code: error.code,
+          message: error.message,
+          retryable: error.retryable,
+          details: error.details
+        });
+        return;
+      }
+      sendError(res, 500, {
+        code: "INTERNAL",
+        message: "Unexpected inspect enablement error.",
+        retryable: false
+      });
+    }
+  });
   router.post("/diagnostics/doctor", (req, res) => {
     const body = req.body ?? {};
     if (!isRecord2(body)) {
@@ -5121,9 +5407,7 @@ var registerDiagnosticsRoutes = (router, options = {}) => {
             port: parsedDoctorInput.data.caller.endpoint.port,
             baseUrl: parsedDoctorInput.data.caller.endpoint.base_url,
             hostSource: parsedDoctorInput.data.caller.endpoint.host_source,
-            portSource: parsedDoctorInput.data.caller.endpoint.port_source,
-            metadataPath: parsedDoctorInput.data.caller.endpoint.metadata_path,
-            isolatedMode: parsedDoctorInput.data.caller.endpoint.isolated_mode
+            portSource: parsedDoctorInput.data.caller.endpoint.port_source
           } : void 0,
           process: parsedDoctorInput.data.caller.process ? {
             component: parsedDoctorInput.data.caller.process.component,
@@ -5140,9 +5424,7 @@ var registerDiagnosticsRoutes = (router, options = {}) => {
             port: options.coreRuntime.port,
             baseUrl: `http://${options.coreRuntime.host}:${options.coreRuntime.port}`,
             hostSource: options.coreRuntime.hostSource,
-            portSource: options.coreRuntime.portSource,
-            metadataPath: options.coreRuntime.metadataPath,
-            isolatedMode: options.coreRuntime.isolatedMode
+            portSource: options.coreRuntime.portSource
           } : void 0,
           process: {
             component: "core",
@@ -5185,11 +5467,13 @@ var registerDiagnosticsRoutes = (router, options = {}) => {
         const status = options.extensionBridge.getStatus();
         context.extension = {
           connected: status.connected,
+          extensionId: status.extensionId,
           version: status.version,
           lastSeenAt: status.lastSeenAt
         };
         if (status.connected) {
           context.runtime.extension = {
+            extensionId: status.extensionId,
             version: status.version,
             protocolVersion: status.protocolVersion,
             capabilityNegotiated: status.capabilityNegotiated,
@@ -5226,7 +5510,8 @@ var registerDiagnosticsRoutes = (router, options = {}) => {
             code: lastError.error.code,
             message: lastError.error.message,
             retryable: lastError.error.retryable,
-            at: lastError.at
+            at: lastError.at,
+            details: lastError.error.details
           };
         }
       }
@@ -5237,7 +5522,8 @@ var registerDiagnosticsRoutes = (router, options = {}) => {
             code: lastError.error.code,
             message: lastError.error.message,
             retryable: lastError.error.retryable,
-            at: lastError.at
+            at: lastError.at,
+            details: lastError.error.details
           };
         }
       }
@@ -5267,6 +5553,11 @@ var registerDiagnosticsRoutes = (router, options = {}) => {
 };
 
 // packages/core/src/routes/drive.ts
+var SUPPORTED_NAVIGATE_WAIT_MODES = [
+  "none",
+  "domcontentloaded",
+  "networkidle"
+];
 var parseBody = (schema, body) => {
   const result = schema.safeParse(body);
   if (result.success) {
@@ -5283,6 +5574,24 @@ var parseBody = (schema, body) => {
 };
 var makeNavigateHandler = (schema, drive, registry) => {
   return (req, res) => {
+    if (isRecord2(req.body) && req.body.wait !== void 0) {
+      const waitMode = req.body.wait;
+      if (typeof waitMode !== "string" || !SUPPORTED_NAVIGATE_WAIT_MODES.includes(
+        waitMode
+      )) {
+        sendError(res, errorStatus("INVALID_ARGUMENT"), {
+          code: "INVALID_ARGUMENT",
+          message: `Unsupported wait mode: ${String(waitMode)}.`,
+          retryable: false,
+          details: {
+            field: "wait",
+            supported_wait_modes: SUPPORTED_NAVIGATE_WAIT_MODES,
+            mapped_wait_mode: "domcontentloaded"
+          }
+        });
+        return;
+      }
+    }
     const parsed = parseBody(schema, req.body ?? {});
     if (parsed.error) {
       sendError(res, errorStatus("INVALID_ARGUMENT"), {
@@ -5539,27 +5848,6 @@ var parseBody2 = (schema, body) => {
     }
   };
 };
-var readTargetHint = (target) => {
-  if (!target) {
-    return void 0;
-  }
-  const url = typeof target.url === "string" ? target.url : void 0;
-  const title = typeof target.title === "string" ? target.title : void 0;
-  const lastActiveAtRaw = target.last_active_at ?? target.lastActiveAt;
-  const lastActiveAt = typeof lastActiveAtRaw === "string" ? lastActiveAtRaw : void 0;
-  if (!url && !title && !lastActiveAt) {
-    return void 0;
-  }
-  return { url, title, lastActiveAt };
-};
-var resolveTargetHint = (target, options) => {
-  const explicit = readTargetHint(target);
-  if (explicit) {
-    return explicit;
-  }
-  const tabs = options.extensionBridge?.getStatus().tabs ?? [];
-  return deriveHintFromTabs(tabs);
-};
 var makeHandler2 = (schema, handler) => async (req, res) => {
   const parsed = parseBody2(schema, req.body ?? {});
   if (parsed.error) {
@@ -5605,7 +5893,12 @@ var registerInspectRoutes = (router, options) => {
         compact: body.compact,
         maxNodes: body.max_nodes,
         selector: body.selector,
-        targetHint: resolveTargetHint(body.target, options)
+        targetHint: resolveInspectTargetHint({
+          sessionId: body.session_id,
+          target: body.target,
+          registry: options.registry,
+          extensionBridge: options.extensionBridge
+        })
       });
     })
   );
@@ -5618,7 +5911,12 @@ var registerInspectRoutes = (router, options) => {
   router.post(
     "/inspect/find",
     makeHandler2(InspectFindInputSchema, async (body) => {
-      const targetHint = resolveTargetHint(body.target, options);
+      const targetHint = resolveInspectTargetHint({
+        sessionId: body.session_id,
+        target: body.target,
+        registry: options.registry,
+        extensionBridge: options.extensionBridge
+      });
       if (body.kind === "role") {
         return await inspect.find({
           sessionId: body.session_id,
@@ -5651,7 +5949,12 @@ var registerInspectRoutes = (router, options) => {
         sessionId: body.session_id,
         format: body.format,
         includeMetadata: body.include_metadata,
-        targetHint: resolveTargetHint(body.target, options)
+        targetHint: resolveInspectTargetHint({
+          sessionId: body.session_id,
+          target: body.target,
+          registry: options.registry,
+          extensionBridge: options.extensionBridge
+        })
       });
     })
   );
@@ -5660,7 +5963,12 @@ var registerInspectRoutes = (router, options) => {
     makeHandler2(InspectPageStateInputSchema, async (body) => {
       return await inspect.pageState({
         sessionId: body.session_id,
-        targetHint: resolveTargetHint(body.target, options)
+        targetHint: resolveInspectTargetHint({
+          sessionId: body.session_id,
+          target: body.target,
+          registry: options.registry,
+          extensionBridge: options.extensionBridge
+        })
       });
     })
   );
@@ -5669,7 +5977,12 @@ var registerInspectRoutes = (router, options) => {
     makeHandler2(InspectConsoleListInputSchema, async (body) => {
       return await inspect.consoleList({
         sessionId: body.session_id,
-        targetHint: resolveTargetHint(body.target, options)
+        targetHint: resolveInspectTargetHint({
+          sessionId: body.session_id,
+          target: body.target,
+          registry: options.registry,
+          extensionBridge: options.extensionBridge
+        })
       });
     })
   );
@@ -5678,7 +5991,12 @@ var registerInspectRoutes = (router, options) => {
     makeHandler2(InspectNetworkHarInputSchema, async (body) => {
       return await inspect.networkHar({
         sessionId: body.session_id,
-        targetHint: resolveTargetHint(body.target, options)
+        targetHint: resolveInspectTargetHint({
+          sessionId: body.session_id,
+          target: body.target,
+          registry: options.registry,
+          extensionBridge: options.extensionBridge
+        })
       });
     })
   );
@@ -5688,7 +6006,12 @@ var registerInspectRoutes = (router, options) => {
       return await inspect.evaluate({
         sessionId: body.session_id,
         expression: body.expression,
-        targetHint: resolveTargetHint(body.target, options)
+        targetHint: resolveInspectTargetHint({
+          sessionId: body.session_id,
+          target: body.target,
+          registry: options.registry,
+          extensionBridge: options.extensionBridge
+        })
       });
     })
   );
@@ -5697,7 +6020,12 @@ var registerInspectRoutes = (router, options) => {
     makeHandler2(InspectPerformanceMetricsInputSchema, async (body) => {
       return await inspect.performanceMetrics({
         sessionId: body.session_id,
-        targetHint: resolveTargetHint(body.target, options)
+        targetHint: resolveInspectTargetHint({
+          sessionId: body.session_id,
+          target: body.target,
+          registry: options.registry,
+          extensionBridge: options.extensionBridge
+        })
       });
     })
   );
@@ -6126,6 +6454,7 @@ var createCoreServer = (options = {}) => {
   registerArtifactsRoutes(app, {
     registry,
     extensionBridge,
+    debuggerBridge,
     inspectService: inspect
   });
   registerDiagnosticsRoutes(app, {
@@ -6148,27 +6477,12 @@ var createCoreServer = (options = {}) => {
     recoveryTracker
   };
 };
-var CORE_PORT_PROBE_ATTEMPTS = 20;
-var buildRuntimeMetadataForPersist = (runtime, resolvedPort) => ({
+var buildRuntimeMetadataForPersist = (runtime) => ({
   ...runtime.metadata ?? {},
-  host: runtime.host,
-  port: resolvedPort,
-  git_root: runtime.gitRoot ?? runtime.metadata?.git_root,
-  worktree_id: runtime.worktreeId ?? runtime.metadata?.worktree_id,
+  extension_id: runtime.metadata?.extension_id,
   updated_at: (/* @__PURE__ */ new Date()).toISOString()
 });
-var resolveProbePortsForRuntime = (runtime) => {
-  if (!runtime.isolatedMode) {
-    return [runtime.port];
-  }
-  if (runtime.portSource === "metadata" || runtime.portSource === "deterministic") {
-    return createBoundedPortProbeSequence(
-      runtime.port,
-      CORE_PORT_PROBE_ATTEMPTS
-    );
-  }
-  return [runtime.port];
-};
+var resolveProbePortsForRuntime = (runtime) => [runtime.port];
 var resolveSessionTtlMs = () => {
   const env = process.env.BROWSER_BRIDGE_SESSION_TTL_MS || process.env.BROWSER_VISION_SESSION_TTL_MS;
   if (env) {
@@ -6249,11 +6563,7 @@ var startCoreServer = async (options = {}) => {
     host: runtime.host,
     port: runtime.port,
     host_source: runtime.hostSource,
-    port_source: runtime.portSource,
-    metadata_path: runtime.metadataPath,
-    git_root: runtime.gitRoot,
-    worktree_id: runtime.worktreeId,
-    deterministic_port: runtime.deterministicPort
+    port_source: runtime.portSource
   });
   const { app, registry, extensionBridge } = createCoreServer({
     registry: options.registry,
@@ -6283,10 +6593,9 @@ var startCoreServer = async (options = {}) => {
         duration_ms: Number(startupDurationMs.toFixed(3))
       });
       try {
-        writeRuntimeMetadata(
-          buildRuntimeMetadataForPersist(runtime, resolvedPort),
-          { metadataPath: runtime.metadataPath }
-        );
+        writeRuntimeMetadata(buildRuntimeMetadataForPersist(runtime), {
+          metadataPath: runtime.metadataPath
+        });
         logger.info("core.runtime_metadata.persisted", {
           metadata_path: runtime.metadataPath,
           host: runtime.host,
@@ -6495,9 +6804,7 @@ startCoreServer({ ${startOptions.join(
           port: readiness.runtime.port,
           base_url: readiness.baseUrl,
           host_source: readiness.runtime.hostSource,
-          port_source: readiness.runtime.portSource,
-          metadata_path: readiness.runtime.metadataPath,
-          isolated_mode: readiness.runtime.isolatedMode
+          port_source: readiness.runtime.portSource
         },
         process: {
           component: "mcp",
@@ -6543,6 +6850,70 @@ var toInternalErrorEnvelope = (error) => ({
 });
 var envelope = (schema) => successEnvelopeSchema(schema);
 var isRecord3 = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+var readSessionId2 = (args) => {
+  if (!isRecord3(args)) {
+    return void 0;
+  }
+  const sessionId = args.session_id;
+  return typeof sessionId === "string" && sessionId.length > 0 ? sessionId : void 0;
+};
+var supportsSessionMigration = (corePath) => corePath.startsWith("/drive/") || corePath.startsWith("/inspect/") || corePath.startsWith("/artifacts/") || corePath === "/diagnostics/doctor";
+var isSessionNotFoundEnvelope = (envelopeResult) => {
+  if (envelopeResult.ok) {
+    return false;
+  }
+  const details = envelopeResult.error.details;
+  return envelopeResult.error.code === "NOT_FOUND" && isRecord3(details) && details.reason === "session_not_found";
+};
+var addSessionRecoveryHint = (envelopeResult) => {
+  if (envelopeResult.ok) {
+    return envelopeResult;
+  }
+  return {
+    ok: false,
+    error: {
+      ...envelopeResult.error,
+      details: {
+        ...isRecord3(envelopeResult.error.details) ? envelopeResult.error.details : {},
+        recover_action: "session.create"
+      }
+    }
+  };
+};
+var addSessionMigrationNotice = (envelopeResult, staleSessionId, replacementSessionId) => {
+  if (envelopeResult.ok) {
+    if (!isRecord3(envelopeResult.result)) {
+      return envelopeResult;
+    }
+    const warning = `Session ${staleSessionId} became stale after runtime switch; retried with ${replacementSessionId}.`;
+    const existingWarnings = Array.isArray(envelopeResult.result.warnings) ? envelopeResult.result.warnings.filter(
+      (item) => typeof item === "string"
+    ) : [];
+    return {
+      ok: true,
+      result: {
+        ...envelopeResult.result,
+        warnings: existingWarnings.includes(warning) ? existingWarnings : [...existingWarnings, warning],
+        session_migration: {
+          stale_session_id: staleSessionId,
+          replacement_session_id: replacementSessionId
+        }
+      }
+    };
+  }
+  return {
+    ok: false,
+    error: {
+      ...envelopeResult.error,
+      details: {
+        ...isRecord3(envelopeResult.error.details) ? envelopeResult.error.details : {},
+        stale_session_id: staleSessionId,
+        replacement_session_id: replacementSessionId,
+        recover_action: "session.recover"
+      }
+    }
+  };
+};
 var addDeprecatedAliasWarning = (envelopeResult, deprecationAlias) => {
   if (!deprecationAlias || !envelopeResult.ok || typeof envelopeResult.result !== "object" || !envelopeResult.result) {
     return envelopeResult;
@@ -6953,10 +7324,26 @@ var createToolHandler = (clientProvider, corePath, deprecationAlias, transformIn
     void _extra;
     try {
       const client = typeof clientProvider === "function" ? await clientProvider() : clientProvider;
-      const envelopeResult = await client.post(
-        corePath,
-        transformInput ? transformInput(args) : args
-      );
+      const transformedArgs = transformInput ? transformInput(args) : args;
+      const staleSessionId = readSessionId2(transformedArgs);
+      let envelopeResult = await client.post(corePath, transformedArgs);
+      if (staleSessionId && supportsSessionMigration(corePath) && isSessionNotFoundEnvelope(envelopeResult) && isRecord3(transformedArgs)) {
+        const createdSession = await client.post("/session/create", {});
+        if (createdSession.ok && isRecord3(createdSession.result) && typeof createdSession.result.session_id === "string" && createdSession.result.session_id.length > 0) {
+          const replacementSessionId = createdSession.result.session_id;
+          const retryArgs = {
+            ...transformedArgs,
+            session_id: replacementSessionId
+          };
+          envelopeResult = addSessionMigrationNotice(
+            await client.post(corePath, retryArgs),
+            staleSessionId,
+            replacementSessionId
+          );
+        } else {
+          envelopeResult = addSessionRecoveryHint(envelopeResult);
+        }
+      }
       return toToolResult(
         addDeprecatedAliasWarning(envelopeResult, deprecationAlias)
       );
@@ -7097,7 +7484,7 @@ var DEFAULT_SERVER_NAME = "browser-bridge";
 var DEFAULT_SERVER_VERSION = "0.0.0";
 var ENV_MCP_EAGER = "BROWSER_BRIDGE_MCP_EAGER";
 var ENV_LEGACY_MCP_EAGER = "BROWSER_VISION_MCP_EAGER";
-var parseBoolean2 = (value) => {
+var parseBoolean = (value) => {
   if (value === void 0) {
     return void 0;
   }
@@ -7114,7 +7501,7 @@ var resolveEagerMode = (explicit) => {
   if (typeof explicit === "boolean") {
     return explicit;
   }
-  const envValue = parseBoolean2(process.env[ENV_MCP_EAGER]) ?? parseBoolean2(process.env[ENV_LEGACY_MCP_EAGER]);
+  const envValue = parseBoolean(process.env[ENV_MCP_EAGER]) ?? parseBoolean(process.env[ENV_LEGACY_MCP_EAGER]);
   return envValue ?? false;
 };
 var toCoreClientOptions = (options, logger) => ({