@btraut/browser-bridge 0.13.1 → 0.14.0

package/dist/index.js

@@ -38,14 +38,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";
@@ -102,22 +99,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;
@@ -134,60 +115,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) {
@@ -201,35 +128,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
   };
 };
@@ -246,32 +156,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,
@@ -318,17 +202,6 @@ var readRuntimeMetadata = ({
     return null;
   }
 };
-var writeRuntimeMetadata = (metadata, {
-  cwd,
-  gitRoot,
-  metadataPath
-} = {}) => {
-  const path9 = resolveRuntimeMetadataPath({ cwd, gitRoot, metadataPath });
-  (0, import_node_fs.mkdirSync)((0, import_node_path.dirname)(path9), { recursive: true });
-  (0, import_node_fs.writeFileSync)(path9, `${JSON.stringify(metadata, null, 2)}
-`, "utf8");
-  return path9;
-};
 var resolveCoreRuntime = (options = {}) => {
   const env = options.env ?? process.env;
   const resolvedCwd = resolveCwd(options.cwd);
@@ -339,45 +212,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,
@@ -385,11 +231,7 @@ var resolveCoreRuntime = (options = {}) => {
     portSource,
     metadataPath,
     metadata,
-    gitRoot,
-    worktreeId: resolveWorktreeId({ cwd: resolvedCwd, gitRoot }),
-    deterministicPort,
-    isolatedMode,
-    isolatedModeSource
+    gitRoot
   };
 };
 
@@ -808,7 +650,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(
@@ -1002,9 +844,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(),
@@ -1025,12 +865,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({
@@ -1105,7 +946,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)
@@ -1274,6 +1115,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()
 });
@@ -1468,6 +1311,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();
@@ -1504,6 +1348,49 @@ var resolveTimeoutMs2 = (timeoutMs) => {
 };
 var normalizePath = (path9) => path9.startsWith("/") ? path9 : `/${path9}`;
 var durationMs = (startedAt) => Number((Number(process.hrtime.bigint() - startedAt) / 1e6).toFixed(3));
+var MAX_RESPONSE_PREVIEW_LENGTH = 200;
+var normalizeResponsePreview = (raw) => {
+  const normalized = raw.replace(/\s+/g, " ").trim();
+  if (normalized.length <= MAX_RESPONSE_PREVIEW_LENGTH) {
+    return normalized;
+  }
+  return `${normalized.slice(0, MAX_RESPONSE_PREVIEW_LENGTH)}...`;
+};
+var getHeaderValue = (headers, name) => {
+  if (!headers || typeof headers.get !== "function") {
+    return void 0;
+  }
+  const value = headers.get(name);
+  return typeof value === "string" && value.trim().length > 0 ? value : void 0;
+};
+var buildInvalidCoreResponseError = (options) => {
+  const details = {
+    base_url: options.baseUrl,
+    path: options.path,
+    status: options.status,
+    reason: options.kind === "empty" ? "core_empty_response" : "core_invalid_json_response",
+    next_step: "Verify Browser Bridge core is reachable on the expected host and port, then retry."
+  };
+  if (options.contentType) {
+    details.content_type = options.contentType;
+  }
+  if (options.responseText && options.responseText.trim().length > 0) {
+    details.response_preview = normalizeResponsePreview(options.responseText);
+  }
+  const message = options.kind === "empty" ? "Core returned an empty response." : options.contentType?.toLowerCase().includes("text/html") ? "Core returned HTML instead of JSON." : "Core returned an invalid JSON response.";
+  return new CoreClientError({
+    code: "UNAVAILABLE",
+    message,
+    retryable: true,
+    retry: {
+      retryable: true,
+      reason: options.kind === "empty" ? "core_empty_response" : "core_invalid_json_response",
+      retry_after_ms: 250,
+      max_attempts: 1
+    },
+    details
+  });
+};
 var createCoreClient = (options = {}) => {
   const logger = options.logger ?? createJsonlLogger({
     stream: "cli",
@@ -1617,6 +1504,7 @@ startCoreServer({ ${startOptions.join(
         });
         throw error;
       }
+      const contentType = getHeaderValue(response.headers, "content-type");
       const raw = await response.text();
       if (!raw) {
         logger.warn("cli.core.request.empty_response", {
@@ -1624,9 +1512,16 @@ startCoreServer({ ${startOptions.join(
           path: requestPath,
           base_url: readiness.baseUrl,
           status: response.status,
+          content_type: contentType,
           duration_ms: durationMs(startedAt)
         });
-        throw new Error(`Empty response from Core (${response.status}).`);
+        throw buildInvalidCoreResponseError({
+          kind: "empty",
+          status: response.status,
+          baseUrl: readiness.baseUrl,
+          path: requestPath,
+          contentType
+        });
       }
       try {
         const parsed = JSON.parse(raw);
@@ -1639,16 +1534,24 @@ startCoreServer({ ${startOptions.join(
         });
         return parsed;
       } catch (error) {
-        const message = error instanceof Error ? error.message : "Unknown JSON parse error";
         logger.error("cli.core.request.invalid_json", {
           method,
           path: requestPath,
           base_url: readiness.baseUrl,
           status: response.status,
+          content_type: contentType,
+          response_preview: normalizeResponsePreview(raw),
           duration_ms: durationMs(startedAt),
           error
         });
-        throw new Error(`Failed to parse Core response: ${message}`);
+        throw buildInvalidCoreResponseError({
+          kind: "invalid_json",
+          status: response.status,
+          baseUrl: readiness.baseUrl,
+          path: requestPath,
+          contentType,
+          responseText: raw
+        });
       }
     } finally {
       clearTimeout(timeout);
@@ -1665,9 +1568,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: "cli",
@@ -1962,35 +1863,8 @@ var registerDiagnosticsCommands = (program2) => {
   });
 };
 
-// packages/cli/src/open-path.ts
-var import_node_child_process2 = require("node:child_process");
-var openPath = async (target) => {
-  const platform = process.platform;
-  if (platform === "darwin") {
-    const child2 = (0, import_node_child_process2.spawn)("open", [target], { detached: true, stdio: "ignore" });
-    child2.unref();
-    return;
-  }
-  if (platform === "win32") {
-    const child2 = (0, import_node_child_process2.spawn)("cmd", ["/c", "start", "", target], {
-      detached: true,
-      stdio: "ignore"
-    });
-    child2.unref();
-    return;
-  }
-  const child = (0, import_node_child_process2.spawn)("xdg-open", [target], {
-    detached: true,
-    stdio: "ignore"
-  });
-  child.unref();
-};
-
 // packages/cli/src/commands/dev.ts
 var ENV_EXTENSION_ID = "BROWSER_BRIDGE_EXTENSION_ID";
-var ACTIVATION_FLAG_PARAM = "bb_activate";
-var ACTIVATION_PORT_PARAM = "corePort";
-var ACTIVATION_WORKTREE_PARAM = "worktreeId";
 var normalizeToken = (value) => {
   if (typeof value !== "string") {
     return void 0;
@@ -2007,45 +1881,71 @@ var resolveActivationExtensionId = (options) => {
   if (envId) {
     return { extensionId: envId, source: "env" };
   }
-  const metadataId = normalizeToken(options.metadataExtensionId);
-  if (metadataId) {
-    return { extensionId: metadataId, source: "metadata" };
-  }
   return null;
 };
-var buildActivationOptionsUrl = (options) => {
-  const search = new URLSearchParams();
-  search.set(ACTIVATION_FLAG_PARAM, "1");
-  search.set(ACTIVATION_PORT_PARAM, String(options.corePort));
-  if (options.worktreeId) {
-    search.set(ACTIVATION_WORKTREE_PARAM, options.worktreeId);
-  }
-  return `chrome-extension://${options.extensionId}/options.html?${search.toString()}`;
-};
-var buildPersistedRuntimeMetadata = (runtime, extensionId) => ({
-  ...runtime.metadata ?? {},
-  host: runtime.host,
-  port: runtime.port,
-  git_root: runtime.gitRoot ?? runtime.metadata?.git_root,
-  worktree_id: runtime.worktreeId ?? runtime.metadata?.worktree_id,
-  extension_id: extensionId,
-  isolated_mode: true,
-  updated_at: (/* @__PURE__ */ new Date()).toISOString()
-});
-var resolveRuntimeForCommand = (options, overrides = {}) => {
+var resolveRuntimeForCommand = (options) => {
   const runtimeOptions = {
     host: options.host,
     port: options.port,
     strictEnvPort: true
   };
-  if (overrides.isolatedMode !== void 0) {
-    runtimeOptions.isolatedMode = overrides.isolatedMode;
-  }
   return resolveCoreRuntime(runtimeOptions);
 };
+var hasPassingCheck = (report, name) => report?.checks?.some((check) => check.name === name && check.ok) ?? false;
+var getReportedExtensionId = (report) => normalizeToken(report?.runtime?.extension?.extension_id);
+var inspectCapabilityReady = (report, expectedExtensionId) => {
+  const reportedExtensionId = getReportedExtensionId(report);
+  const extensionIdMatch = !expectedExtensionId || !reportedExtensionId || reportedExtensionId === expectedExtensionId;
+  return extensionIdMatch && hasPassingCheck(report, "inspect.capability");
+};
+var readDiagnosticReport = async (runtime) => {
+  const client = createCoreClient({
+    host: runtime.host,
+    port: runtime.port,
+    ensureDaemon: true
+  });
+  const envelope2 = await client.post(
+    "/diagnostics/doctor",
+    {}
+  );
+  return envelope2.ok ? envelope2.result : void 0;
+};
+var buildInspectCapabilityError = (runtime, report, expectedExtension) => {
+  const observedExtensionId = getReportedExtensionId(report);
+  if (expectedExtension && observedExtensionId && observedExtensionId !== expectedExtension.extensionId) {
+    return new CliError({
+      code: "FAILED_PRECONDITION",
+      message: "Inspect capability is available, but the connected extension does not match the requested extension id.",
+      retryable: false,
+      details: {
+        host: runtime.host,
+        port: runtime.port,
+        expectedExtensionId: expectedExtension.extensionId,
+        expectedExtensionIdSource: expectedExtension.source,
+        observedExtensionId,
+        next_step: "Clear the stale extension-id override or reload the intended Browser Bridge extension, then retry."
+      }
+    });
+  }
+  return new CliError({
+    code: "FAILED_PRECONDITION",
+    message: "Inspect capability is unavailable in a build where it should already be enabled.",
+    retryable: true,
+    details: {
+      host: runtime.host,
+      port: runtime.port,
+      expectedExtensionId: expectedExtension?.extensionId,
+      expectedExtensionIdSource: expectedExtension?.source,
+      observedConnected: report?.extension?.connected ?? false,
+      observedExtensionId,
+      observedInspectCapability: hasPassingCheck(report, "inspect.capability"),
+      next_step: "Restart the Browser Bridge core daemon, then reload or update the Browser Bridge extension and retry."
+    }
+  });
+};
 var registerDevCommands = (program2) => {
   const dev = program2.command("dev").description("Development commands");
-  dev.command("info").description("Print resolved runtime details for the current worktree").action(async (_options, command) => {
+  dev.command("info").description("Print resolved runtime details for the current environment").action(async (_options, command) => {
     await runLocal(command, async (globalOptions) => {
       const runtime = resolveRuntimeForCommand(globalOptions);
       const logDir = resolveLogDirectory({ gitRoot: runtime.gitRoot });
@@ -2056,8 +1956,6 @@ var registerDevCommands = (program2) => {
           hostSource: runtime.hostSource,
           port: runtime.port,
           portSource: runtime.portSource,
-          deterministicPort: runtime.deterministicPort,
-          worktreeId: runtime.worktreeId,
           metadataPath: runtime.metadataPath,
           logDir,
           metadataSnapshot: runtime.metadata
@@ -2065,51 +1963,40 @@ var registerDevCommands = (program2) => {
       };
     });
   });
-  dev.command("activate").description(
-    "Enable isolated worktree routing and open extension options for activation"
-  ).option(
+  dev.command("enable-inspect").description("Compatibility helper that verifies inspect capability").option(
     "--extension-id <id>",
-    "Chrome extension id to activate for isolated worktree routing"
+    "Chrome extension id to verify against while checking inspect capability"
   ).action(async (options, command) => {
     await runLocal(command, async (globalOptions) => {
-      const runtime = resolveRuntimeForCommand(globalOptions, {
-        isolatedMode: true
-      });
-      const extension = resolveActivationExtensionId({
+      const runtime = resolveRuntimeForCommand(globalOptions);
+      let resolvedExtension = resolveActivationExtensionId({
         optionExtensionId: options.extensionId,
-        envExtensionId: process.env[ENV_EXTENSION_ID],
-        metadataExtensionId: runtime.metadata?.extension_id
+        envExtensionId: process.env[ENV_EXTENSION_ID]
       });
-      if (!extension) {
-        throw new CliError({
-          code: "INVALID_ARGUMENT",
-          message: "Missing extension id. Provide --extension-id <id>, set BROWSER_BRIDGE_EXTENSION_ID, or persist extension_id in metadata by running dev activate with --extension-id once (only needed for isolated worktree routing).",
-          retryable: false,
-          details: {
-            metadataPath: runtime.metadataPath
-          }
-        });
+      const report = await readDiagnosticReport(runtime);
+      if (!resolvedExtension) {
+        const reportedExtensionId = getReportedExtensionId(report);
+        if (reportedExtensionId) {
+          resolvedExtension = {
+            extensionId: reportedExtensionId,
+            source: "connected"
+          };
+        }
+      }
+      if (!inspectCapabilityReady(report, resolvedExtension?.extensionId)) {
+        throw buildInspectCapabilityError(runtime, report, resolvedExtension);
       }
-      const metadataPath = writeRuntimeMetadata(
-        buildPersistedRuntimeMetadata(runtime, extension.extensionId),
-        { metadataPath: runtime.metadataPath }
-      );
-      const activationUrl = buildActivationOptionsUrl({
-        extensionId: extension.extensionId,
-        corePort: runtime.port,
-        worktreeId: runtime.worktreeId
-      });
-      await openPath(activationUrl);
       return {
         ok: true,
         result: {
-          extensionId: extension.extensionId,
-          extensionIdSource: extension.source,
           host: runtime.host,
           port: runtime.port,
-          isolatedMode: true,
-          metadataPath,
-          activationUrl
+          inspectAlwaysEnabled: true,
+          checkedWithDiagnostics: true,
+          ...resolvedExtension ? {
+            extensionId: resolvedExtension.extensionId,
+            extensionIdSource: resolvedExtension.source
+          } : {}
         }
       };
     });
@@ -2198,7 +2085,7 @@ var registerDriveCommands = (program2) => {
   drive.command("navigate").description("Navigate to a URL").option(
     "--session-id <id>",
     "Session identifier (auto-created when omitted)"
-  ).requiredOption("--url <url>", "URL to navigate to").option("--tab-id <id>", "Tab identifier (defaults to agent window/tab)").option("--wait <mode>", "Wait mode (none, domcontentloaded)").action(async (options, command) => {
+  ).requiredOption("--url <url>", "URL to navigate to").option("--tab-id <id>", "Tab identifier (defaults to agent window/tab)").option("--wait <mode>", "Wait mode (none, domcontentloaded, networkidle)").action(async (options, command) => {
     await runCommand(command, (client) => {
       const payload = parseInput(DriveNavigateInputSchema, {
         ...options.sessionId ? { session_id: options.sessionId } : {},
@@ -2476,9 +2363,23 @@ var registerDriveCommands = (program2) => {
 };
 
 // packages/cli/src/commands/inspect.ts
+var parseNumber4 = (value) => {
+  if (value === void 0 || value === null || value === "") {
+    return void 0;
+  }
+  const parsed = Number(value);
+  return Number.isFinite(parsed) ? parsed : Number.NaN;
+};
+var buildTargetHint = (options) => {
+  const tabId = parseNumber4(options.tabId);
+  if (tabId === void 0) {
+    return void 0;
+  }
+  return { tab_id: tabId };
+};
 var registerInspectCommands = (program2) => {
   const inspect = program2.command("inspect").description("Inspect commands");
-  inspect.command("dom-snapshot").description("Fetch a DOM snapshot").requiredOption("--session-id <id>", "Session identifier").option("--format <format>", "Snapshot format (ax, html)").option("--consistency <mode>", "Consistency mode (best_effort, quiesce)").option("-i, --interactive", "Only include interactive elements").option("-c, --compact", "Remove empty/decorative nodes").option("--max-nodes <n>", "Limit AX snapshot to at most n nodes").option("-s, --selector <selector>", "Limit snapshot to selector").action(async (options, command) => {
+  inspect.command("dom-snapshot").description("Fetch a DOM snapshot").requiredOption("--session-id <id>", "Session identifier").option("--format <format>", "Snapshot format (ax, html)").option("--consistency <mode>", "Consistency mode (best_effort, quiesce)").option("-i, --interactive", "Only include interactive elements").option("-c, --compact", "Remove empty/decorative nodes").option("--max-nodes <n>", "Limit AX snapshot to at most n nodes").option("-s, --selector <selector>", "Limit snapshot to selector").option("--tab-id <id>", "Explicit tab identifier").action(async (options, command) => {
     await runCommand(command, (client) => {
       const payload = parseInput(InspectDomSnapshotInputSchema, {
         session_id: options.sessionId,
@@ -2487,7 +2388,8 @@ var registerInspectCommands = (program2) => {
         interactive: options.interactive,
         compact: options.compact,
         max_nodes: options.maxNodes,
-        selector: options.selector
+        selector: options.selector,
+        target: buildTargetHint(options)
       });
       return client.post("/inspect/dom_snapshot", payload);
     });
@@ -2500,7 +2402,7 @@ var registerInspectCommands = (program2) => {
       return client.post("/inspect/dom_diff", payload);
     });
   });
-  inspect.command("find").description("Find elements and return refs").requiredOption("--session-id <id>", "Session identifier").argument("<kind>", "Find kind (role, text, label)").argument("<value>", "Role name or text to match").option("--name <name>", "Accessible name to match (role only)").action(async (kind, value, options, command) => {
+  inspect.command("find").description("Find elements and return refs").requiredOption("--session-id <id>", "Session identifier").argument("<kind>", "Find kind (role, text, label)").argument("<value>", "Role name or text to match").option("--name <name>", "Accessible name to match (role only)").option("--tab-id <id>", "Explicit tab identifier").action(async (kind, value, options, command) => {
     await runCommand(command, (client) => {
       const normalizedKind = String(kind ?? "").toLowerCase();
       let payload;
@@ -2509,19 +2411,22 @@ var registerInspectCommands = (program2) => {
           session_id: options.sessionId,
           kind: "role",
           role: value,
-          name: options.name
+          name: options.name,
+          target: buildTargetHint(options)
         };
       } else if (normalizedKind === "text") {
         payload = {
           session_id: options.sessionId,
           kind: "text",
-          text: value
+          text: value,
+          target: buildTargetHint(options)
         };
       } else if (normalizedKind === "label") {
         payload = {
           session_id: options.sessionId,
           kind: "label",
-          label: value
+          label: value,
+          target: buildTargetHint(options)
         };
       } else {
         throw new CliError({
@@ -2535,53 +2440,59 @@ var registerInspectCommands = (program2) => {
       return client.post("/inspect/find", parsed);
     });
   });
-  inspect.command("extract-content").description("Extract main content from the page").requiredOption("--session-id <id>", "Session identifier").option("--format <format>", "Output format (markdown, text, article_json)").option("--include-metadata", "Include article metadata").option("--no-include-metadata", "Exclude article metadata").action(async (options, command) => {
+  inspect.command("extract-content").description("Extract main content from the page").requiredOption("--session-id <id>", "Session identifier").option("--format <format>", "Output format (markdown, text, article_json)").option("--include-metadata", "Include article metadata").option("--no-include-metadata", "Exclude article metadata").option("--tab-id <id>", "Explicit tab identifier").action(async (options, command) => {
     await runCommand(command, (client) => {
       const payload = parseInput(InspectExtractContentInputSchema, {
         session_id: options.sessionId,
         format: options.format,
-        include_metadata: options.includeMetadata
+        include_metadata: options.includeMetadata,
+        target: buildTargetHint(options)
       });
       return client.post("/inspect/extract_content", payload);
     });
   });
-  inspect.command("page-state").description("Capture form, storage, and cookie state").requiredOption("--session-id <id>", "Session identifier").action(async (options, command) => {
+  inspect.command("page-state").description("Capture form, storage, and cookie state").requiredOption("--session-id <id>", "Session identifier").option("--tab-id <id>", "Explicit tab identifier").action(async (options, command) => {
     await runCommand(command, (client) => {
       const payload = parseInput(InspectPageStateInputSchema, {
-        session_id: options.sessionId
+        session_id: options.sessionId,
+        target: buildTargetHint(options)
       });
       return client.post("/inspect/page_state", payload);
     });
   });
-  inspect.command("console-list").description("Fetch console entries").requiredOption("--session-id <id>", "Session identifier").action(async (options, command) => {
+  inspect.command("console-list").description("Fetch console entries").requiredOption("--session-id <id>", "Session identifier").option("--tab-id <id>", "Explicit tab identifier").action(async (options, command) => {
     await runCommand(command, (client) => {
       const payload = parseInput(InspectConsoleListInputSchema, {
-        session_id: options.sessionId
+        session_id: options.sessionId,
+        target: buildTargetHint(options)
       });
       return client.post("/inspect/console_list", payload);
     });
   });
-  inspect.command("network-har").description("Fetch network HAR").requiredOption("--session-id <id>", "Session identifier").action(async (options, command) => {
+  inspect.command("network-har").description("Fetch network HAR").requiredOption("--session-id <id>", "Session identifier").option("--tab-id <id>", "Explicit tab identifier").action(async (options, command) => {
     await runCommand(command, (client) => {
       const payload = parseInput(InspectNetworkHarInputSchema, {
-        session_id: options.sessionId
+        session_id: options.sessionId,
+        target: buildTargetHint(options)
       });
       return client.post("/inspect/network_har", payload);
     });
   });
-  inspect.command("evaluate").description("Evaluate a JavaScript expression").requiredOption("--session-id <id>", "Session identifier").option("--expression <expr>", "Expression to evaluate").action(async (options, command) => {
+  inspect.command("evaluate").description("Evaluate a JavaScript expression").requiredOption("--session-id <id>", "Session identifier").option("--expression <expr>", "Expression to evaluate").option("--tab-id <id>", "Explicit tab identifier").action(async (options, command) => {
     await runCommand(command, (client) => {
       const payload = parseInput(InspectEvaluateInputSchema, {
         session_id: options.sessionId,
-        expression: options.expression
+        expression: options.expression,
+        target: buildTargetHint(options)
       });
       return client.post("/inspect/evaluate", payload);
     });
   });
-  inspect.command("performance-metrics").description("Fetch performance metrics").requiredOption("--session-id <id>", "Session identifier").action(async (options, command) => {
+  inspect.command("performance-metrics").description("Fetch performance metrics").requiredOption("--session-id <id>", "Session identifier").option("--tab-id <id>", "Explicit tab identifier").action(async (options, command) => {
     await runCommand(command, (client) => {
       const payload = parseInput(InspectPerformanceMetricsInputSchema, {
-        session_id: options.sessionId
+        session_id: options.sessionId,
+        target: buildTargetHint(options)
       });
       return client.post("/inspect/performance_metrics", payload);
     });
@@ -2589,7 +2500,7 @@ var registerInspectCommands = (program2) => {
 };
 
 // packages/mcp-adapter/src/core-client.ts
-var import_node_child_process3 = require("node:child_process");
+var import_node_child_process2 = require("node:child_process");
 var import_node_path4 = require("node:path");
 var DEFAULT_TIMEOUT_MS3 = 3e4;
 var normalizePath2 = (path9) => path9.startsWith("/") ? path9 : `/${path9}`;
@@ -2618,7 +2529,7 @@ var createCoreClient2 = (options = {}) => {
   }).child({ scope: "core-client" });
   const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS3;
   const fetchImpl = options.fetchImpl ?? fetch;
-  const spawnImpl = options.spawnImpl ?? import_node_child_process3.spawn;
+  const spawnImpl = options.spawnImpl ?? import_node_child_process2.spawn;
   const ensureDaemon = options.ensureDaemon ?? false;
   const componentVersion = options.componentVersion ?? process.env.BROWSER_BRIDGE_VERSION ?? process.env.npm_package_version;
   const readiness = createCoreReadinessController({
@@ -2750,9 +2661,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",
@@ -2798,6 +2707,70 @@ var toInternalErrorEnvelope = (error) => ({
 });
 var envelope = (schema) => successEnvelopeSchema(schema);
 var isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+var readSessionId = (args) => {
+  if (!isRecord(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" && isRecord(details) && details.reason === "session_not_found";
+};
+var addSessionRecoveryHint = (envelopeResult) => {
+  if (envelopeResult.ok) {
+    return envelopeResult;
+  }
+  return {
+    ok: false,
+    error: {
+      ...envelopeResult.error,
+      details: {
+        ...isRecord(envelopeResult.error.details) ? envelopeResult.error.details : {},
+        recover_action: "session.create"
+      }
+    }
+  };
+};
+var addSessionMigrationNotice = (envelopeResult, staleSessionId, replacementSessionId) => {
+  if (envelopeResult.ok) {
+    if (!isRecord(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: {
+        ...isRecord(envelopeResult.error.details) ? envelopeResult.error.details : {},
+        stale_session_id: staleSessionId,
+        replacement_session_id: replacementSessionId,
+        recover_action: "session.recover"
+      }
+    }
+  };
+};
 var addDeprecatedAliasWarning2 = (envelopeResult, deprecationAlias) => {
   if (!deprecationAlias || !envelopeResult.ok || typeof envelopeResult.result !== "object" || !envelopeResult.result) {
     return envelopeResult;
@@ -3208,10 +3181,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 = readSessionId(transformedArgs);
+      let envelopeResult = await client.post(corePath, transformedArgs);
+      if (staleSessionId && supportsSessionMigration(corePath) && isSessionNotFoundEnvelope(envelopeResult) && isRecord(transformedArgs)) {
+        const createdSession = await client.post("/session/create", {});
+        if (createdSession.ok && isRecord(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(
         addDeprecatedAliasWarning2(envelopeResult, deprecationAlias)
       );
@@ -3357,7 +3346,7 @@ var DEFAULT_HTTP_PATH = "/mcp";
 var ENV_MCP_EAGER = "BROWSER_BRIDGE_MCP_EAGER";
 var ENV_LEGACY_MCP_EAGER = "BROWSER_VISION_MCP_EAGER";
 var durationMs4 = (startedAt) => Number((Number(process.hrtime.bigint() - startedAt) / 1e6).toFixed(3));
-var parseBoolean2 = (value) => {
+var parseBoolean = (value) => {
   if (value === void 0) {
     return void 0;
   }
@@ -3374,7 +3363,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) => ({
@@ -3561,7 +3550,7 @@ var readJsonBody = async (req, maxBytes = 5 * 1024 * 1024) => {
   }
   return JSON.parse(raw);
 };
-var getHeaderValue = (value) => {
+var getHeaderValue2 = (value) => {
   if (typeof value === "string") {
     return value;
   }
@@ -3627,7 +3616,7 @@ var startMcpHttpServer = async (options = {}) => {
         });
         return;
       }
-      const sessionId = getHeaderValue(req.headers["mcp-session-id"]);
+      const sessionId = getHeaderValue2(req.headers["mcp-session-id"]);
       requestLogger.debug("mcp.http.request.session", {
         session_id: sessionId ?? null
       });
@@ -3786,7 +3775,7 @@ var checkboxPrompt = async (options) => {
 };
 
 // packages/cli/src/installer/mcp-install.ts
-var import_node_child_process4 = require("node:child_process");
+var import_node_child_process3 = require("node:child_process");
 
 // packages/cli/src/installer/cursor-mcp.ts
 var import_promises2 = __toESM(require("node:fs/promises"));
@@ -3857,7 +3846,7 @@ var installCursorMcp = async (settingsPath) => {
 // packages/cli/src/installer/mcp-install.ts
 var runQuiet = async (cmd, args) => {
   await new Promise((resolve4, reject) => {
-    const child = (0, import_node_child_process4.spawn)(cmd, args, { stdio: ["ignore", "pipe", "pipe"] });
+    const child = (0, import_node_child_process3.spawn)(cmd, args, { stdio: ["ignore", "pipe", "pipe"] });
     let stderr = "";
     child.stderr?.on("data", (chunk) => {
       stderr += String(chunk);
@@ -4026,11 +4015,6 @@ var import_express2 = __toESM(require("express"));
 // packages/core/src/routes/session.ts
 var import_express = require("express");
 
-// packages/core/src/inspect/service.ts
-var import_readability = require("@mozilla/readability");
-var import_jsdom = require("jsdom");
-var import_turndown = __toESM(require("turndown"));
-
 // packages/core/src/artifacts.ts
 var import_promises3 = require("node:fs/promises");
 var import_node_os2 = __toESM(require("node:os"));
@@ -4063,6 +4047,11 @@ var DriveMutex = class {
 };
 var driveMutex = new DriveMutex();
 
+// 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"));
+
 // packages/core/src/page-state-script.ts
 var PAGE_STATE_SCRIPT = [
   "(() => {",
@@ -4172,6 +4161,32 @@ var PROCESS_STARTED_AT = new Date(
   Date.now() - Math.floor(process.uptime() * 1e3)
 ).toISOString();
 
+// packages/cli/src/open-path.ts
+var import_node_child_process4 = require("node:child_process");
+var shouldOpenInChrome = (target) => /^chrome(?:-extension)?:\/\//.test(target);
+var openPath = async (target) => {
+  const platform = process.platform;
+  if (platform === "darwin") {
+    const args = shouldOpenInChrome(target) ? ["-a", "Google Chrome", target] : [target];
+    const child2 = (0, import_node_child_process4.spawn)("open", args, { detached: true, stdio: "ignore" });
+    child2.unref();
+    return;
+  }
+  if (platform === "win32") {
+    const child2 = (0, import_node_child_process4.spawn)("cmd", ["/c", "start", "", target], {
+      detached: true,
+      stdio: "ignore"
+    });
+    child2.unref();
+    return;
+  }
+  const child = (0, import_node_child_process4.spawn)("xdg-open", [target], {
+    detached: true,
+    stdio: "ignore"
+  });
+  child.unref();
+};
+
 // packages/cli/src/commands/open-artifacts.ts
 var registerOpenArtifactsCommand = (program2) => {
   program2.command("open-artifacts").description("Open the artifact folder for a session").requiredOption("--session-id <id>", "Session identifier").action(async (options, command) => {
@@ -4331,7 +4346,7 @@ var resolveSkillSourceDir = async () => {
   } catch {
   }
   const repoRoot = import_node_path8.default.resolve(rootDir, "..", "..");
-  const docsSkill = import_node_path8.default.join(repoRoot, "docs", "skills", "browser-bridge");
+  const docsSkill = import_node_path8.default.join(repoRoot, "skills", "browser-bridge");
   try {
     await import_promises4.default.stat(docsSkill);
     return docsSkill;