browser-pilot-cli 0.3.0 → 0.5.0

package/dist/cli.js

@@ -1,12 +1,12 @@
 #!/usr/bin/env node
 
 // src/cli.ts
-import { Command } from "commander";
-import { writeFileSync as writeFileSync2, readFileSync as readFileSync4, existsSync as existsSync4 } from "fs";
-import { resolve as resolvePath } from "path";
+import { Command, CommanderError } from "commander";
+import { writeFileSync as writeFileSync2, readFileSync as readFileSync4, existsSync as existsSync4, mkdirSync as mkdirSync2 } from "fs";
+import { basename as basename2, isAbsolute as isAbsolute3, resolve as resolvePath } from "path";
 
 // src/version.ts
-var BROWSER_PILOT_VERSION = "0.3.0";
+var BROWSER_PILOT_VERSION = "0.5.0";
 
 // src/protocol/errors.ts
 var ERROR_CODES = [
@@ -28,6 +28,7 @@ var ERROR_CODES = [
   "action_not_verified",
   "command_cancelled",
   "command_expired",
+  "wait_timeout",
   "unknown_outcome",
   "artifact_not_found",
   "artifact_expired",
@@ -73,23 +74,6 @@ function invalidArgument(message, field, rpcCode = -32602) {
     rpcCode
   });
 }
-function asBrowserPilotError(error) {
-  if (error instanceof BrowserPilotError) return error;
-  if (error instanceof Error && typeof error.code === "string" && ERROR_CODES.includes(error.code)) {
-    const stable = error;
-    return new BrowserPilotError(stable.code, error.message, {
-      retryable: stable.retryable,
-      context: stable.context,
-      remediation: stable.remediation,
-      rpcCode: stable.rpcCode,
-      cause: error
-    });
-  }
-  return new BrowserPilotError("internal_error", "Internal Browser Pilot error", {
-    retryable: false,
-    cause: error
-  });
-}
 function browserPilotErrorFromJsonRpc(error) {
   const data = error.data;
   if (!data || typeof data !== "object" || Array.isArray(data)) {
@@ -110,154 +94,445 @@ function browserPilotErrorFromJsonRpc(error) {
   });
 }
 
-// src/session.ts
-import { spawn } from "child_process";
-
-// src/client.ts
-import http from "http";
-import { existsSync as existsSync2, readFileSync as readFileSync2 } from "fs";
-
-// src/broker-locator.ts
-import { createHash as createHash2, randomUUID } from "crypto";
-import {
-  chmodSync,
-  closeSync,
-  existsSync,
-  lstatSync,
-  mkdirSync,
-  openSync,
-  readFileSync,
-  renameSync,
-  realpathSync,
-  statSync,
-  unlinkSync,
-  writeFileSync,
-  writeSync
-} from "fs";
-import { basename, dirname, isAbsolute as isAbsolute2, join as join2 } from "path";
-
-// src/paths.ts
+// src/chrome.ts
 import { createHash } from "crypto";
-import { homedir, platform, tmpdir, userInfo } from "os";
-import { isAbsolute, join, win32 } from "path";
-var MAX_PORTABLE_UNIX_SOCKET_BYTES = 96;
-function identityDigest(value) {
-  return createHash("sha256").update(value).digest("hex").slice(0, 16);
-}
-function resolveBrowserPilotPaths(options = {}) {
-  const os = options.platform ?? platform();
-  const home = options.homeDir ?? homedir();
-  const env = options.env ?? process.env;
-  if (os === "win32") {
-    const localAppData = env.LOCALAPPDATA ?? win32.join(home, "AppData", "Local");
-    const stateDir2 = env.BROWSER_PILOT_HOME ?? win32.join(localAppData, "Browser Pilot");
-    if (!win32.isAbsolute(stateDir2)) throw new Error("BROWSER_PILOT_HOME must be absolute");
-    const username = options.username ?? (() => {
-      try {
-        return userInfo().username;
-      } catch {
-        return home;
-      }
-    })();
-    const identity = identityDigest(
-      `${username.toLowerCase()}\0${home.toLowerCase()}\0${stateDir2.toLowerCase()}`
-    );
+import { execFileSync } from "child_process";
+import { existsSync, lstatSync, readFileSync } from "fs";
+import { connect as connectTcp } from "net";
+import { delimiter, join } from "path";
+import { homedir, platform } from "os";
+import WebSocket from "ws";
+function readChromeInfo(browser, dataDir) {
+  const portFile = join(dataDir, "DevToolsActivePort");
+  if (!existsSync(portFile)) return null;
+  try {
+    const lines = readFileSync(portFile, "utf-8").trim().split(/\r?\n/);
+    if (lines.length < 2) return null;
+    const port = Number.parseInt(lines[0], 10);
+    const wsPath = lines[1];
+    if (!Number.isSafeInteger(port) || port < 1 || port > 65535 || !wsPath.startsWith("/")) return null;
     return {
-      stateDir: stateDir2,
-      runtimeDir: stateDir2,
-      endpoint: `\\\\.\\pipe\\browser-pilot-${identity}`,
-      transport: "windows_pipe",
-      locatorFile: win32.join(stateDir2, "broker-locator.json"),
-      pidFile: win32.join(stateDir2, "daemon.pid"),
-      startupLockFile: win32.join(stateDir2, "startup.lock"),
-      versionHistoryFile: win32.join(stateDir2, "broker-versions.json"),
-      artifactDir: win32.join(stateDir2, "artifacts"),
-      downloadDir: win32.join(stateDir2, "downloads")
+      port,
+      wsPath,
+      wsUrl: `ws://127.0.0.1:${port}${wsPath}`,
+      browser,
+      dataDir
     };
+  } catch {
+    return null;
   }
-  const stateDir = env.BROWSER_PILOT_HOME ?? join(home, ".browser-pilot");
-  if (!isAbsolute(stateDir)) throw new Error("BROWSER_PILOT_HOME must be absolute");
-  const defaultEndpoint = join(stateDir, "daemon.sock");
-  const uid = options.uid ?? process.getuid?.() ?? 0;
-  const useShortRuntimePath = Buffer.byteLength(defaultEndpoint) > MAX_PORTABLE_UNIX_SOCKET_BYTES;
-  let runtimeDir = useShortRuntimePath ? join(options.tempDir ?? tmpdir(), `browser-pilot-${uid}-${identityDigest(stateDir)}`) : stateDir;
-  let endpoint = join(runtimeDir, "daemon.sock");
-  if (Buffer.byteLength(endpoint) > MAX_PORTABLE_UNIX_SOCKET_BYTES) {
-    runtimeDir = join("/tmp", `browser-pilot-${uid}-${identityDigest(stateDir)}`);
-    endpoint = join(runtimeDir, "daemon.sock");
-  }
-  if (Buffer.byteLength(endpoint) > MAX_PORTABLE_UNIX_SOCKET_BYTES) {
-    throw new Error("Browser Pilot cannot resolve a portable Unix socket path");
-  }
-  if (!isAbsolute(endpoint)) throw new Error("Browser Pilot endpoint must be absolute");
-  return {
-    stateDir,
-    runtimeDir,
-    endpoint,
-    transport: "unix_socket",
-    locatorFile: join(stateDir, "broker-locator.json"),
-    pidFile: join(stateDir, "daemon.pid"),
-    startupLockFile: join(stateDir, "startup.lock"),
-    versionHistoryFile: join(stateDir, "broker-versions.json"),
-    artifactDir: join(stateDir, "artifacts"),
-    downloadDir: join(stateDir, "downloads")
-  };
 }
-var BROWSER_PILOT_PATHS = resolveBrowserPilotPaths();
-var STATE_DIR = BROWSER_PILOT_PATHS.stateDir;
-var RUNTIME_DIR = BROWSER_PILOT_PATHS.runtimeDir;
-var SOCKET_PATH = BROWSER_PILOT_PATHS.endpoint;
-var BROKER_TRANSPORT = BROWSER_PILOT_PATHS.transport;
-var LOCATOR_FILE = BROWSER_PILOT_PATHS.locatorFile;
-var PID_FILE = BROWSER_PILOT_PATHS.pidFile;
-var STARTUP_LOCK_FILE = BROWSER_PILOT_PATHS.startupLockFile;
-var ARTIFACT_DIR = BROWSER_PILOT_PATHS.artifactDir;
-var DOWNLOAD_DIR = BROWSER_PILOT_PATHS.downloadDir;
-
-// src/broker-locator.ts
-var PRIVATE_DIRECTORY_MODE = 448;
-var PRIVATE_FILE_MODE = 384;
-var MAX_METADATA_BYTES = 16 * 1024;
-function currentUid() {
-  return process.getuid?.();
+function executablePaths(env) {
+  return (env.PATH ?? "").split(delimiter).filter(Boolean);
 }
-function validateOwnedPath(path, expectDirectory) {
-  const stats = lstatSync(path);
-  if (stats.isSymbolicLink()) throw new Error(`Browser Pilot path must not be a symbolic link: ${path}`);
-  if (expectDirectory ? !stats.isDirectory() : !stats.isFile()) {
-    throw new Error(`Browser Pilot path has an unexpected type: ${path}`);
+function linuxInstallPaths(env, names) {
+  return executablePaths(env).flatMap((directory) => names.map((name) => join(directory, name)));
+}
+function supportedBrowserProfiles(options = {}) {
+  const home = options.homeDir ?? homedir();
+  const os = options.platform ?? platform();
+  const env = options.env ?? process.env;
+  if (os === "darwin") {
+    const base = join(home, "Library", "Application Support");
+    const applications = ["/Applications", join(home, "Applications")];
+    const appPaths = (name) => applications.map((directory) => join(directory, name));
+    return [
+      {
+        key: "chrome-stable",
+        product: "Chrome",
+        channel: "stable",
+        dataDir: join(base, "Google", "Chrome"),
+        installPaths: appPaths("Google Chrome.app"),
+        executableNames: ["Google Chrome"]
+      },
+      {
+        key: "chrome-beta",
+        product: "Chrome",
+        channel: "beta",
+        dataDir: join(base, "Google", "Chrome Beta"),
+        installPaths: appPaths("Google Chrome Beta.app"),
+        executableNames: ["Google Chrome Beta"]
+      },
+      {
+        key: "chrome-canary",
+        product: "Chrome",
+        channel: "canary",
+        dataDir: join(base, "Google", "Chrome Canary"),
+        installPaths: appPaths("Google Chrome Canary.app"),
+        executableNames: ["Google Chrome Canary"]
+      },
+      {
+        key: "brave-stable",
+        product: "Brave",
+        channel: "stable",
+        dataDir: join(base, "BraveSoftware", "Brave-Browser"),
+        installPaths: appPaths("Brave Browser.app"),
+        executableNames: ["Brave Browser"]
+      },
+      {
+        key: "edge-stable",
+        product: "Edge",
+        channel: "stable",
+        dataDir: join(base, "Microsoft Edge"),
+        installPaths: appPaths("Microsoft Edge.app"),
+        executableNames: ["Microsoft Edge"]
+      },
+      {
+        key: "chromium-stable",
+        product: "Chromium",
+        channel: "stable",
+        dataDir: join(base, "Chromium"),
+        installPaths: appPaths("Chromium.app"),
+        executableNames: ["Chromium"]
+      }
+    ];
   }
-  const uid = currentUid();
-  if (uid !== void 0 && stats.uid !== uid) {
-    throw new Error(`Browser Pilot path is not owned by the current user: ${path}`);
+  if (os === "linux") {
+    return [
+      {
+        key: "chrome-stable",
+        product: "Chrome",
+        channel: "stable",
+        dataDir: join(home, ".config", "google-chrome"),
+        installPaths: linuxInstallPaths(env, ["google-chrome", "google-chrome-stable"]),
+        executableNames: ["google-chrome", "google-chrome-stable"]
+      },
+      {
+        key: "chrome-beta",
+        product: "Chrome",
+        channel: "beta",
+        dataDir: join(home, ".config", "google-chrome-beta"),
+        installPaths: linuxInstallPaths(env, ["google-chrome-beta"]),
+        executableNames: ["google-chrome-beta"]
+      },
+      {
+        key: "chromium-stable",
+        product: "Chromium",
+        channel: "stable",
+        dataDir: join(home, ".config", "chromium"),
+        installPaths: linuxInstallPaths(env, ["chromium", "chromium-browser"]),
+        executableNames: ["chromium", "chromium-browser"]
+      },
+      {
+        key: "brave-stable",
+        product: "Brave",
+        channel: "stable",
+        dataDir: join(home, ".config", "BraveSoftware", "Brave-Browser"),
+        installPaths: linuxInstallPaths(env, ["brave-browser", "brave-browser-stable"]),
+        executableNames: ["brave-browser", "brave-browser-stable"]
+      },
+      {
+        key: "edge-stable",
+        product: "Edge",
+        channel: "stable",
+        dataDir: join(home, ".config", "microsoft-edge"),
+        installPaths: linuxInstallPaths(env, ["microsoft-edge", "microsoft-edge-stable"]),
+        executableNames: ["microsoft-edge", "microsoft-edge-stable"]
+      }
+    ];
   }
-  if (!expectDirectory && process.platform !== "win32" && (stats.mode & 63) !== 0) {
-    throw new Error(`Browser Pilot metadata is accessible by another OS user: ${path}`);
+  if (os === "win32") {
+    const local = env.LOCALAPPDATA ?? join(home, "AppData", "Local");
+    const programFiles = [env.PROGRAMFILES, env["PROGRAMFILES(X86)"]].filter((value) => Boolean(value));
+    return [
+      {
+        key: "chrome-stable",
+        product: "Chrome",
+        channel: "stable",
+        dataDir: join(local, "Google", "Chrome", "User Data"),
+        installPaths: [join(local, "Google", "Chrome", "Application", "chrome.exe"), ...programFiles.map((path) => join(path, "Google", "Chrome", "Application", "chrome.exe"))],
+        executableNames: ["chrome.exe"]
+      },
+      {
+        key: "brave-stable",
+        product: "Brave",
+        channel: "stable",
+        dataDir: join(local, "BraveSoftware", "Brave-Browser", "User Data"),
+        installPaths: [join(local, "BraveSoftware", "Brave-Browser", "Application", "brave.exe"), ...programFiles.map((path) => join(path, "BraveSoftware", "Brave-Browser", "Application", "brave.exe"))],
+        executableNames: ["brave.exe"]
+      },
+      {
+        key: "edge-stable",
+        product: "Edge",
+        channel: "stable",
+        dataDir: join(local, "Microsoft", "Edge", "User Data"),
+        installPaths: [join(local, "Microsoft", "Edge", "Application", "msedge.exe"), ...programFiles.map((path) => join(path, "Microsoft", "Edge", "Application", "msedge.exe"))],
+        executableNames: ["msedge.exe"]
+      }
+    ];
   }
+  return [];
 }
-function ensurePrivateDirectorySync(path) {
-  if (!existsSync(path)) mkdirSync(path, { recursive: true, mode: PRIVATE_DIRECTORY_MODE });
-  validateOwnedPath(path, true);
-  if (process.platform !== "win32") chmodSync(path, PRIVATE_DIRECTORY_MODE);
-}
-function ensureBrokerDirectoriesSync(paths = BROWSER_PILOT_PATHS) {
-  ensurePrivateDirectorySync(paths.stateDir);
-  if (paths.runtimeDir !== paths.stateDir) ensurePrivateDirectorySync(paths.runtimeDir);
-}
-function parseJsonFile(path) {
-  validateOwnedPath(path, false);
-  const stats = statSync(path);
-  if (stats.size < 2 || stats.size > MAX_METADATA_BYTES) throw new Error("Broker metadata has an invalid size");
-  return JSON.parse(readFileSync(path, "utf8"));
+function stableBrowserId(definition, os) {
+  const digest = createHash("sha256").update(`${os}\0${definition.key}\0${definition.dataDir}`).digest("base64url").slice(0, 20);
+  return `browser:${definition.key}:${digest}`;
 }
-function isSafePid(value) {
-  return Number.isSafeInteger(value) && Number(value) > 0;
+function pathExistsWithoutFollowingSymlink(path) {
+  try {
+    lstatSync(path);
+    return true;
+  } catch {
+    return false;
+  }
 }
-function isSafeTimestamp(value) {
-  return typeof value === "number" && Number.isSafeInteger(value) && value > 0;
+function installed(definition) {
+  return pathExistsWithoutFollowingSymlink(definition.dataDir) || definition.installPaths.some(pathExistsWithoutFollowingSymlink);
 }
-function validExecutable(value) {
-  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+function readRunningCommands(os) {
+  try {
+    if (os === "win32") {
+      return execFileSync("tasklist.exe", ["/FO", "CSV", "/NH"], {
+        encoding: "utf8",
+        timeout: 2e3,
+        windowsHide: true
+      }).split(/\r?\n/).filter(Boolean);
+    }
+    return execFileSync("ps", ["-axo", "command="], {
+      encoding: "utf8",
+      timeout: 2e3
+    }).split(/\r?\n/).filter(Boolean);
+  } catch {
+    return null;
+  }
+}
+function browserProcessState(definition, commands) {
+  for (const lockName of ["SingletonLock", "SingletonSocket", "lockfile"]) {
+    if (pathExistsWithoutFollowingSymlink(join(definition.dataDir, lockName))) return "running";
+  }
+  if (commands === null) return "unknown";
+  const names = definition.executableNames.map((name) => name.toLowerCase());
+  return commands.some((command) => {
+    const normalized = command.toLowerCase();
+    return names.some((name) => {
+      const macExecutable = `/${name}.app/contents/macos/${name}`;
+      if (normalized.includes(macExecutable)) return true;
+      const escaped = name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+      return new RegExp(`(^|[/\\\\"'])${escaped}(?=$|[\\s"',])`, "i").test(normalized);
+    });
+  }) ? "running" : "not_running";
+}
+function remediation(state, endpointAvailable = false) {
+  switch (state) {
+    case "not_running":
+      return {
+        code: "start_browser",
+        message: "Start this browser profile, then enable remote debugging from chrome://inspect/#remote-debugging.",
+        actionRequired: true
+      };
+    case "remote_debugging_disabled":
+      return {
+        code: "enable_remote_debugging",
+        message: "Open chrome://inspect/#remote-debugging in this browser and turn on remote debugging.",
+        actionRequired: true
+      };
+    case "authorization_required":
+      return {
+        code: "authorize_remote_debugging",
+        message: "Approve the browser's remote debugging authorization prompt.",
+        actionRequired: true
+      };
+    case "disconnected":
+      if (endpointAvailable) {
+        return {
+          code: "connect_browser",
+          message: "Run an explicit browser connect operation to request remote debugging authorization.",
+          actionRequired: true
+        };
+      }
+      return {
+        code: "restart_remote_debugging",
+        message: "The recorded remote debugging endpoint is stale. Restart this browser profile and enable remote debugging again.",
+        actionRequired: true
+      };
+    case "ready":
+      return void 0;
+  }
+}
+async function discoverBrowserCandidates(options = {}) {
+  const os = options.platform ?? platform();
+  const definitions = options.profiles ?? supportedBrowserProfiles(options);
+  const runningCommands = options.runningCommands === void 0 ? readRunningCommands(os) : options.runningCommands;
+  const results = [];
+  for (const definition of definitions) {
+    if (!installed(definition)) continue;
+    const endpoint = readChromeInfo(definition.product, definition.dataDir);
+    let processState = browserProcessState(definition, runningCommands);
+    let remoteDebuggingState = "disabled";
+    let authorizationState = "not_applicable";
+    let state;
+    if (!endpoint) {
+      state = processState === "running" ? "remote_debugging_disabled" : "not_running";
+    } else if (processState === "not_running") {
+      remoteDebuggingState = "stale";
+      authorizationState = "unknown";
+      state = "disconnected";
+    } else {
+      processState = "running";
+      remoteDebuggingState = "enabled";
+      authorizationState = "unknown";
+      state = "disconnected";
+    }
+    const candidate = {
+      id: stableBrowserId(definition, os),
+      product: definition.product,
+      channel: definition.channel,
+      userDataRoot: definition.dataDir,
+      processState,
+      remoteDebuggingState,
+      authorizationState,
+      state,
+      ...remediation(state, endpoint !== null && remoteDebuggingState === "enabled") ? { remediation: remediation(state, endpoint !== null && remoteDebuggingState === "enabled") } : {}
+    };
+    results.push({ candidate, dataDir: definition.dataDir, ...endpoint ? { endpoint } : {} });
+  }
+  return results;
+}
+
+// src/client.ts
+import http from "http";
+import { existsSync as existsSync3, readFileSync as readFileSync3 } from "fs";
+
+// src/broker-locator.ts
+import { createHash as createHash3, randomUUID } from "crypto";
+import {
+  chmodSync,
+  closeSync,
+  existsSync as existsSync2,
+  lstatSync as lstatSync2,
+  mkdirSync,
+  openSync,
+  readFileSync as readFileSync2,
+  renameSync,
+  realpathSync,
+  statSync,
+  unlinkSync,
+  writeFileSync,
+  writeSync
+} from "fs";
+import { basename, dirname, isAbsolute as isAbsolute2, join as join3 } from "path";
+
+// src/paths.ts
+import { createHash as createHash2 } from "crypto";
+import { homedir as homedir2, platform as platform2, tmpdir, userInfo } from "os";
+import { isAbsolute, join as join2, win32 } from "path";
+var MAX_PORTABLE_UNIX_SOCKET_BYTES = 96;
+function identityDigest(value) {
+  return createHash2("sha256").update(value).digest("hex").slice(0, 16);
+}
+function resolveBrowserPilotPaths(options = {}) {
+  const os = options.platform ?? platform2();
+  const home = options.homeDir ?? homedir2();
+  const env = options.env ?? process.env;
+  if (os === "win32") {
+    const localAppData = env.LOCALAPPDATA ?? win32.join(home, "AppData", "Local");
+    const stateDir2 = env.BROWSER_PILOT_HOME ?? win32.join(localAppData, "Browser Pilot");
+    if (!win32.isAbsolute(stateDir2)) throw new Error("BROWSER_PILOT_HOME must be absolute");
+    const username = options.username ?? (() => {
+      try {
+        return userInfo().username;
+      } catch {
+        return home;
+      }
+    })();
+    const identity = identityDigest(
+      `${username.toLowerCase()}\0${home.toLowerCase()}\0${stateDir2.toLowerCase()}`
+    );
+    return {
+      stateDir: stateDir2,
+      runtimeDir: stateDir2,
+      endpoint: `\\\\.\\pipe\\browser-pilot-${identity}`,
+      transport: "windows_pipe",
+      locatorFile: win32.join(stateDir2, "broker-locator.json"),
+      pidFile: win32.join(stateDir2, "daemon.pid"),
+      startupLockFile: win32.join(stateDir2, "startup.lock"),
+      versionHistoryFile: win32.join(stateDir2, "broker-versions.json"),
+      artifactDir: win32.join(stateDir2, "artifacts"),
+      downloadDir: win32.join(stateDir2, "downloads")
+    };
+  }
+  const stateDir = env.BROWSER_PILOT_HOME ?? join2(home, ".browser-pilot");
+  if (!isAbsolute(stateDir)) throw new Error("BROWSER_PILOT_HOME must be absolute");
+  const defaultEndpoint = join2(stateDir, "daemon.sock");
+  const uid = options.uid ?? process.getuid?.() ?? 0;
+  const useShortRuntimePath = Buffer.byteLength(defaultEndpoint) > MAX_PORTABLE_UNIX_SOCKET_BYTES;
+  let runtimeDir = useShortRuntimePath ? join2(options.tempDir ?? tmpdir(), `browser-pilot-${uid}-${identityDigest(stateDir)}`) : stateDir;
+  let endpoint = join2(runtimeDir, "daemon.sock");
+  if (Buffer.byteLength(endpoint) > MAX_PORTABLE_UNIX_SOCKET_BYTES) {
+    runtimeDir = join2("/tmp", `browser-pilot-${uid}-${identityDigest(stateDir)}`);
+    endpoint = join2(runtimeDir, "daemon.sock");
+  }
+  if (Buffer.byteLength(endpoint) > MAX_PORTABLE_UNIX_SOCKET_BYTES) {
+    throw new Error("Browser Pilot cannot resolve a portable Unix socket path");
+  }
+  if (!isAbsolute(endpoint)) throw new Error("Browser Pilot endpoint must be absolute");
+  return {
+    stateDir,
+    runtimeDir,
+    endpoint,
+    transport: "unix_socket",
+    locatorFile: join2(stateDir, "broker-locator.json"),
+    pidFile: join2(stateDir, "daemon.pid"),
+    startupLockFile: join2(stateDir, "startup.lock"),
+    versionHistoryFile: join2(stateDir, "broker-versions.json"),
+    artifactDir: join2(stateDir, "artifacts"),
+    downloadDir: join2(stateDir, "downloads")
+  };
+}
+var BROWSER_PILOT_PATHS = resolveBrowserPilotPaths();
+var STATE_DIR = BROWSER_PILOT_PATHS.stateDir;
+var RUNTIME_DIR = BROWSER_PILOT_PATHS.runtimeDir;
+var SOCKET_PATH = BROWSER_PILOT_PATHS.endpoint;
+var BROKER_TRANSPORT = BROWSER_PILOT_PATHS.transport;
+var LOCATOR_FILE = BROWSER_PILOT_PATHS.locatorFile;
+var PID_FILE = BROWSER_PILOT_PATHS.pidFile;
+var STARTUP_LOCK_FILE = BROWSER_PILOT_PATHS.startupLockFile;
+var ARTIFACT_DIR = BROWSER_PILOT_PATHS.artifactDir;
+var DOWNLOAD_DIR = BROWSER_PILOT_PATHS.downloadDir;
+
+// src/broker-locator.ts
+var PRIVATE_DIRECTORY_MODE = 448;
+var PRIVATE_FILE_MODE = 384;
+var MAX_METADATA_BYTES = 16 * 1024;
+function currentUid() {
+  return process.getuid?.();
+}
+function validateOwnedPath(path, expectDirectory) {
+  const stats = lstatSync2(path);
+  if (stats.isSymbolicLink()) throw new Error(`Browser Pilot path must not be a symbolic link: ${path}`);
+  if (expectDirectory ? !stats.isDirectory() : !stats.isFile()) {
+    throw new Error(`Browser Pilot path has an unexpected type: ${path}`);
+  }
+  const uid = currentUid();
+  if (uid !== void 0 && stats.uid !== uid) {
+    throw new Error(`Browser Pilot path is not owned by the current user: ${path}`);
+  }
+  if (!expectDirectory && process.platform !== "win32" && (stats.mode & 63) !== 0) {
+    throw new Error(`Browser Pilot metadata is accessible by another OS user: ${path}`);
+  }
+}
+function ensurePrivateDirectorySync(path) {
+  if (!existsSync2(path)) mkdirSync(path, { recursive: true, mode: PRIVATE_DIRECTORY_MODE });
+  validateOwnedPath(path, true);
+  if (process.platform !== "win32") chmodSync(path, PRIVATE_DIRECTORY_MODE);
+}
+function ensureBrokerDirectoriesSync(paths = BROWSER_PILOT_PATHS) {
+  ensurePrivateDirectorySync(paths.stateDir);
+  if (paths.runtimeDir !== paths.stateDir) ensurePrivateDirectorySync(paths.runtimeDir);
+}
+function parseJsonFile(path) {
+  validateOwnedPath(path, false);
+  const stats = statSync(path);
+  if (stats.size < 2 || stats.size > MAX_METADATA_BYTES) throw new Error("Broker metadata has an invalid size");
+  return JSON.parse(readFileSync2(path, "utf8"));
+}
+function isSafePid(value) {
+  return Number.isSafeInteger(value) && Number(value) > 0;
+}
+function isSafeTimestamp(value) {
+  return typeof value === "number" && Number.isSafeInteger(value) && value > 0;
+}
+function validExecutable(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
   const record = value;
   return typeof record.version === "string" && record.version.length > 0 && record.version.length <= 128 && typeof record.path === "string" && record.path.length > 0 && record.path.length <= 4096 && isAbsolute2(record.path) && typeof record.identity === "string" && /^executable:[a-f0-9]{64}$/.test(record.identity);
 }
@@ -283,14 +558,14 @@ function validLocator(value, paths) {
 function createExecutableMetadataSync(version, path) {
   if (!version || version.length > 128) throw new Error("Invalid Browser Pilot executable version");
   const resolvedPath = realpathSync(path);
-  const digest = createHash2("sha256").update(`${resolvedPath}\0${version}\0`);
+  const digest = createHash3("sha256").update(`${resolvedPath}\0${version}\0`);
   for (const artifactPath of [
     resolvedPath,
-    join2(dirname(resolvedPath), "daemon.js"),
-    join2(dirname(resolvedPath), "managed-target-janitor.js")
+    join3(dirname(resolvedPath), "daemon.js"),
+    join3(dirname(resolvedPath), "managed-target-janitor.js")
   ]) {
-    if (!existsSync(artifactPath)) continue;
-    digest.update(basename(artifactPath)).update("\0").update(readFileSync(artifactPath)).update("\0");
+    if (!existsSync2(artifactPath)) continue;
+    digest.update(basename(artifactPath)).update("\0").update(readFileSync2(artifactPath)).update("\0");
   }
   return {
     version,
@@ -299,7 +574,7 @@ function createExecutableMetadataSync(version, path) {
   };
 }
 function readBrokerLocatorSync(paths = BROWSER_PILOT_PATHS) {
-  if (!existsSync(paths.locatorFile)) return void 0;
+  if (!existsSync2(paths.locatorFile)) return void 0;
   try {
     const value = parseJsonFile(paths.locatorFile);
     return validLocator(value, paths) ? value : void 0;
@@ -310,7 +585,7 @@ function readBrokerLocatorSync(paths = BROWSER_PILOT_PATHS) {
 function readBrokerPidSync(paths = BROWSER_PILOT_PATHS) {
   const locator = readBrokerLocatorSync(paths);
   if (locator) return locator.pid;
-  if (!existsSync(paths.pidFile)) return void 0;
+  if (!existsSync2(paths.pidFile)) return void 0;
   try {
     const value = parseJsonFile(paths.pidFile);
     if (isSafePid(value)) return value;
@@ -321,7 +596,7 @@ function readBrokerPidSync(paths = BROWSER_PILOT_PATHS) {
   } catch {
     try {
       validateOwnedPath(paths.pidFile, false);
-      const pid = Number.parseInt(readFileSync(paths.pidFile, "utf8").trim(), 10);
+      const pid = Number.parseInt(readFileSync2(paths.pidFile, "utf8").trim(), 10);
       return isSafePid(pid) ? pid : void 0;
     } catch {
     }
@@ -329,7 +604,7 @@ function readBrokerPidSync(paths = BROWSER_PILOT_PATHS) {
   return void 0;
 }
 function readBrokerStartingSync(paths = BROWSER_PILOT_PATHS) {
-  if (!existsSync(paths.pidFile) || existsSync(paths.locatorFile)) return void 0;
+  if (!existsSync2(paths.pidFile) || existsSync2(paths.locatorFile)) return void 0;
   try {
     const value = parseJsonFile(paths.pidFile);
     if (!value || typeof value !== "object" || Array.isArray(value)) return void 0;
@@ -350,7 +625,7 @@ function processIsAlive(pid) {
   }
 }
 function readStartupLock(path) {
-  if (!existsSync(path)) return void 0;
+  if (!existsSync2(path)) return void 0;
   try {
     const value = parseJsonFile(path);
     if (!value || typeof value !== "object" || Array.isArray(value)) return void 0;
@@ -426,7 +701,7 @@ async function acquireBrokerStartupLock(options = {}) {
       stale = !alive(owner.pid);
     } else {
       try {
-        stale = now() - lstatSync(paths.startupLockFile).mtimeMs > staleAfterMs;
+        stale = now() - lstatSync2(paths.startupLockFile).mtimeMs > staleAfterMs;
       } catch {
         stale = true;
       }
@@ -453,14 +728,60 @@ function removeStaleBrokerFilesSync(paths = BROWSER_PILOT_PATHS) {
   }
 }
 
+// src/services/broker-request-timeout.ts
+var MIN_BROKER_REQUEST_TIMEOUT_MS = 6e4;
+var BROKER_REQUEST_TIMEOUT_MARGIN_MS = 5e3;
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function brokerRequestTimeoutMs(method, params) {
+  if (method !== "tools/call" || !isRecord(params)) return MIN_BROKER_REQUEST_TIMEOUT_MS;
+  const deadlineMs = params.deadlineMs;
+  if (!Number.isSafeInteger(deadlineMs) || Number(deadlineMs) < 1) {
+    return MIN_BROKER_REQUEST_TIMEOUT_MS;
+  }
+  return Math.max(
+    MIN_BROKER_REQUEST_TIMEOUT_MS,
+    Number(deadlineMs) + BROKER_REQUEST_TIMEOUT_MARGIN_MS
+  );
+}
+function brokerRequestTimeoutError(method, params) {
+  if (method !== "tools/call" || !isRecord(params)) {
+    return new BrowserPilotError(
+      "browser_disconnected",
+      "Timed out waiting for the Browser Pilot Broker",
+      { retryable: true }
+    );
+  }
+  const commandId = typeof params.commandId === "string" ? params.commandId : void 0;
+  const toolName = typeof params.name === "string" ? params.name : void 0;
+  return new BrowserPilotError(
+    "unknown_outcome",
+    "Timed out waiting for the Browser Pilot command result",
+    {
+      retryable: true,
+      context: {
+        ...commandId ? { commandId } : {},
+        ...toolName ? { method: toolName } : {}
+      },
+      remediation: {
+        code: "inspect_command_before_retry",
+        message: commandId ? `Run bp command ${commandId} and inspect browser state before retrying.` : "Inspect recent commands and browser state before retrying.",
+        actionRequired: true
+      }
+    }
+  );
+}
+
 // src/client.ts
 var BROKER_SHUTDOWN_TIMEOUT_MS = 15e3;
+var BROKER_RPC_VERSION = 2;
 function isDaemonRunning() {
   const locator = readBrokerLocatorSync();
   if (locator) return processIsAlive(locator.pid);
-  if (!existsSync2(BROWSER_PILOT_PATHS.pidFile)) return false;
+  if (!existsSync3(BROWSER_PILOT_PATHS.pidFile)) return false;
   try {
-    const raw = readFileSync2(BROWSER_PILOT_PATHS.pidFile, "utf-8").trim();
+    const raw = readFileSync3(BROWSER_PILOT_PATHS.pidFile, "utf-8").trim();
     const parsed = raw.startsWith("{") ? JSON.parse(raw) : Number.parseInt(raw, 10);
     const pid = typeof parsed === "number" ? parsed : parsed && typeof parsed === "object" && !Array.isArray(parsed) ? Number(parsed.pid) : Number.NaN;
     return processIsAlive(pid);
@@ -473,7 +794,7 @@ var DaemonClient = class {
   constructor() {
     this.endpoint = readBrokerLocatorSync()?.endpoint ?? BROWSER_PILOT_PATHS.endpoint;
   }
-  request(path, body, signal) {
+  request(path, body, signal, timeoutMs = MIN_BROKER_REQUEST_TIMEOUT_MS) {
     return new Promise((resolve, reject) => {
       const req = http.request(
         {
@@ -481,7 +802,7 @@ var DaemonClient = class {
           path,
           method: body !== void 0 ? "POST" : "GET",
           headers: body !== void 0 ? { "Content-Type": "application/json" } : {},
-          timeout: 6e4,
+          timeout: timeoutMs,
           signal
         },
         (res) => {
@@ -507,7 +828,13 @@ var DaemonClient = class {
       });
       req.on("timeout", () => {
         req.destroy();
-        reject(new Error("Daemon request timeout"));
+        reject(
+          path === "/broker/rpc" && body && typeof body.method === "string" ? brokerRequestTimeoutError(body.method, body.params) : new BrowserPilotError(
+            "browser_disconnected",
+            "Timed out waiting for the Browser Pilot Broker",
+            { retryable: true }
+          )
+        );
       });
       if (body !== void 0) req.write(JSON.stringify(body));
       req.end();
@@ -553,22 +880,12 @@ var DaemonClient = class {
       }
     );
   }
-  async brokerCall(bridgeSessionId, method, params) {
+  async brokerCall(clientSessionId, method, params) {
     return this.request("/broker/rpc", {
-      bridgeSessionId,
+      clientSessionId,
       method,
       ...params !== void 0 ? { params } : {}
-    });
-  }
-  async brokerDisconnect(bridgeSessionId) {
-    await this.request("/broker/disconnect", { bridgeSessionId });
-  }
-  async brokerNextNotification(bridgeSessionId, waitMs, signal) {
-    const result = await this.request("/broker/events/next", {
-      bridgeSessionId,
-      waitMs
-    }, signal);
-    return result.notification;
+    }, void 0, brokerRequestTimeoutMs(method, params));
   }
   async discoveredTargets() {
     const res = await this.request("/discovered");
@@ -598,648 +915,42 @@ var DaemonClient = class {
   }
   async netRequests(opts) {
     const p = new URLSearchParams();
-    if (opts?.limit) p.set("limit", String(opts.limit));
-    if (opts?.url) p.set("url", opts.url);
-    if (opts?.method) p.set("method", opts.method);
-    if (opts?.status) p.set("status", opts.status);
-    if (opts?.type) p.set("type", opts.type);
-    if (opts?.after) p.set("after", String(opts.after));
-    const qs = p.toString();
-    return this.request(`/net/requests${qs ? "?" + qs : ""}`);
-  }
-  async netRequestDetail(id) {
-    return this.request(`/net/request/${id}`);
-  }
-  async netBody(id) {
-    return this.request(`/net/body/${id}`);
-  }
-  async netClear() {
-    await this.request("/net/clear", {});
-  }
-  async netAddRule(rule) {
-    return this.request("/net/rules", rule);
-  }
-  async netRules() {
-    return this.request("/net/rules");
-  }
-  async netRemoveRule(id) {
-    await this.request("/net/rules/remove", id !== void 0 ? { id } : { all: true });
-  }
-  close() {
-  }
-};
-
-// src/chrome.ts
-import { createHash as createHash3 } from "crypto";
-import { execFileSync } from "child_process";
-import { existsSync as existsSync3, lstatSync as lstatSync2, readFileSync as readFileSync3 } from "fs";
-import { connect as connectTcp } from "net";
-import { delimiter, join as join3 } from "path";
-import { homedir as homedir2, platform as platform2 } from "os";
-import WebSocket from "ws";
-function readChromeInfo(browser, dataDir) {
-  const portFile = join3(dataDir, "DevToolsActivePort");
-  if (!existsSync3(portFile)) return null;
-  try {
-    const lines = readFileSync3(portFile, "utf-8").trim().split(/\r?\n/);
-    if (lines.length < 2) return null;
-    const port = Number.parseInt(lines[0], 10);
-    const wsPath = lines[1];
-    if (!Number.isSafeInteger(port) || port < 1 || port > 65535 || !wsPath.startsWith("/")) return null;
-    return {
-      port,
-      wsPath,
-      wsUrl: `ws://127.0.0.1:${port}${wsPath}`,
-      browser,
-      dataDir
-    };
-  } catch {
-    return null;
-  }
-}
-function executablePaths(env) {
-  return (env.PATH ?? "").split(delimiter).filter(Boolean);
-}
-function linuxInstallPaths(env, names) {
-  return executablePaths(env).flatMap((directory) => names.map((name) => join3(directory, name)));
-}
-function supportedBrowserProfiles(options = {}) {
-  const home = options.homeDir ?? homedir2();
-  const os = options.platform ?? platform2();
-  const env = options.env ?? process.env;
-  if (os === "darwin") {
-    const base = join3(home, "Library", "Application Support");
-    const applications = ["/Applications", join3(home, "Applications")];
-    const appPaths = (name) => applications.map((directory) => join3(directory, name));
-    return [
-      {
-        key: "chrome-stable",
-        product: "Chrome",
-        channel: "stable",
-        dataDir: join3(base, "Google", "Chrome"),
-        installPaths: appPaths("Google Chrome.app"),
-        executableNames: ["Google Chrome"]
-      },
-      {
-        key: "chrome-beta",
-        product: "Chrome",
-        channel: "beta",
-        dataDir: join3(base, "Google", "Chrome Beta"),
-        installPaths: appPaths("Google Chrome Beta.app"),
-        executableNames: ["Google Chrome Beta"]
-      },
-      {
-        key: "chrome-canary",
-        product: "Chrome",
-        channel: "canary",
-        dataDir: join3(base, "Google", "Chrome Canary"),
-        installPaths: appPaths("Google Chrome Canary.app"),
-        executableNames: ["Google Chrome Canary"]
-      },
-      {
-        key: "brave-stable",
-        product: "Brave",
-        channel: "stable",
-        dataDir: join3(base, "BraveSoftware", "Brave-Browser"),
-        installPaths: appPaths("Brave Browser.app"),
-        executableNames: ["Brave Browser"]
-      },
-      {
-        key: "edge-stable",
-        product: "Edge",
-        channel: "stable",
-        dataDir: join3(base, "Microsoft Edge"),
-        installPaths: appPaths("Microsoft Edge.app"),
-        executableNames: ["Microsoft Edge"]
-      },
-      {
-        key: "chromium-stable",
-        product: "Chromium",
-        channel: "stable",
-        dataDir: join3(base, "Chromium"),
-        installPaths: appPaths("Chromium.app"),
-        executableNames: ["Chromium"]
-      }
-    ];
-  }
-  if (os === "linux") {
-    return [
-      {
-        key: "chrome-stable",
-        product: "Chrome",
-        channel: "stable",
-        dataDir: join3(home, ".config", "google-chrome"),
-        installPaths: linuxInstallPaths(env, ["google-chrome", "google-chrome-stable"]),
-        executableNames: ["google-chrome", "google-chrome-stable"]
-      },
-      {
-        key: "chrome-beta",
-        product: "Chrome",
-        channel: "beta",
-        dataDir: join3(home, ".config", "google-chrome-beta"),
-        installPaths: linuxInstallPaths(env, ["google-chrome-beta"]),
-        executableNames: ["google-chrome-beta"]
-      },
-      {
-        key: "chromium-stable",
-        product: "Chromium",
-        channel: "stable",
-        dataDir: join3(home, ".config", "chromium"),
-        installPaths: linuxInstallPaths(env, ["chromium", "chromium-browser"]),
-        executableNames: ["chromium", "chromium-browser"]
-      },
-      {
-        key: "brave-stable",
-        product: "Brave",
-        channel: "stable",
-        dataDir: join3(home, ".config", "BraveSoftware", "Brave-Browser"),
-        installPaths: linuxInstallPaths(env, ["brave-browser", "brave-browser-stable"]),
-        executableNames: ["brave-browser", "brave-browser-stable"]
-      },
-      {
-        key: "edge-stable",
-        product: "Edge",
-        channel: "stable",
-        dataDir: join3(home, ".config", "microsoft-edge"),
-        installPaths: linuxInstallPaths(env, ["microsoft-edge", "microsoft-edge-stable"]),
-        executableNames: ["microsoft-edge", "microsoft-edge-stable"]
-      }
-    ];
-  }
-  if (os === "win32") {
-    const local = env.LOCALAPPDATA ?? join3(home, "AppData", "Local");
-    const programFiles = [env.PROGRAMFILES, env["PROGRAMFILES(X86)"]].filter((value) => Boolean(value));
-    return [
-      {
-        key: "chrome-stable",
-        product: "Chrome",
-        channel: "stable",
-        dataDir: join3(local, "Google", "Chrome", "User Data"),
-        installPaths: [join3(local, "Google", "Chrome", "Application", "chrome.exe"), ...programFiles.map((path) => join3(path, "Google", "Chrome", "Application", "chrome.exe"))],
-        executableNames: ["chrome.exe"]
-      },
-      {
-        key: "brave-stable",
-        product: "Brave",
-        channel: "stable",
-        dataDir: join3(local, "BraveSoftware", "Brave-Browser", "User Data"),
-        installPaths: [join3(local, "BraveSoftware", "Brave-Browser", "Application", "brave.exe"), ...programFiles.map((path) => join3(path, "BraveSoftware", "Brave-Browser", "Application", "brave.exe"))],
-        executableNames: ["brave.exe"]
-      },
-      {
-        key: "edge-stable",
-        product: "Edge",
-        channel: "stable",
-        dataDir: join3(local, "Microsoft", "Edge", "User Data"),
-        installPaths: [join3(local, "Microsoft", "Edge", "Application", "msedge.exe"), ...programFiles.map((path) => join3(path, "Microsoft", "Edge", "Application", "msedge.exe"))],
-        executableNames: ["msedge.exe"]
-      }
-    ];
-  }
-  return [];
-}
-function stableBrowserId(definition, os) {
-  const digest = createHash3("sha256").update(`${os}\0${definition.key}\0${definition.dataDir}`).digest("base64url").slice(0, 20);
-  return `browser:${definition.key}:${digest}`;
-}
-function pathExistsWithoutFollowingSymlink(path) {
-  try {
-    lstatSync2(path);
-    return true;
-  } catch {
-    return false;
-  }
-}
-function installed(definition) {
-  return pathExistsWithoutFollowingSymlink(definition.dataDir) || definition.installPaths.some(pathExistsWithoutFollowingSymlink);
-}
-function readRunningCommands(os) {
-  try {
-    if (os === "win32") {
-      return execFileSync("tasklist.exe", ["/FO", "CSV", "/NH"], {
-        encoding: "utf8",
-        timeout: 2e3,
-        windowsHide: true
-      }).split(/\r?\n/).filter(Boolean);
-    }
-    return execFileSync("ps", ["-axo", "command="], {
-      encoding: "utf8",
-      timeout: 2e3
-    }).split(/\r?\n/).filter(Boolean);
-  } catch {
-    return null;
-  }
-}
-function browserProcessState(definition, commands) {
-  for (const lockName of ["SingletonLock", "SingletonSocket", "lockfile"]) {
-    if (pathExistsWithoutFollowingSymlink(join3(definition.dataDir, lockName))) return "running";
-  }
-  if (commands === null) return "unknown";
-  const names = definition.executableNames.map((name) => name.toLowerCase());
-  return commands.some((command) => {
-    const normalized = command.toLowerCase();
-    return names.some((name) => {
-      const macExecutable = `/${name}.app/contents/macos/${name}`;
-      if (normalized.includes(macExecutable)) return true;
-      const escaped = name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-      return new RegExp(`(^|[/\\\\"'])${escaped}(?=$|[\\s"',])`, "i").test(normalized);
-    });
-  }) ? "running" : "not_running";
-}
-function remediation(state, endpointAvailable = false) {
-  switch (state) {
-    case "not_running":
-      return {
-        code: "start_browser",
-        message: "Start this browser profile, then enable remote debugging from chrome://inspect/#remote-debugging.",
-        actionRequired: true
-      };
-    case "remote_debugging_disabled":
-      return {
-        code: "enable_remote_debugging",
-        message: "Open chrome://inspect/#remote-debugging in this browser and turn on remote debugging.",
-        actionRequired: true
-      };
-    case "authorization_required":
-      return {
-        code: "authorize_remote_debugging",
-        message: "Approve the browser's remote debugging authorization prompt.",
-        actionRequired: true
-      };
-    case "disconnected":
-      if (endpointAvailable) {
-        return {
-          code: "connect_browser",
-          message: "Run an explicit browser connect operation to request remote debugging authorization.",
-          actionRequired: true
-        };
-      }
-      return {
-        code: "restart_remote_debugging",
-        message: "The recorded remote debugging endpoint is stale. Restart this browser profile and enable remote debugging again.",
-        actionRequired: true
-      };
-    case "ready":
-      return void 0;
-  }
-}
-async function discoverBrowserCandidates(options = {}) {
-  const os = options.platform ?? platform2();
-  const definitions = options.profiles ?? supportedBrowserProfiles(options);
-  const runningCommands = options.runningCommands === void 0 ? readRunningCommands(os) : options.runningCommands;
-  const results = [];
-  for (const definition of definitions) {
-    if (!installed(definition)) continue;
-    const endpoint = readChromeInfo(definition.product, definition.dataDir);
-    let processState = browserProcessState(definition, runningCommands);
-    let remoteDebuggingState = "disabled";
-    let authorizationState = "not_applicable";
-    let state;
-    if (!endpoint) {
-      state = processState === "running" ? "remote_debugging_disabled" : "not_running";
-    } else if (processState === "not_running") {
-      remoteDebuggingState = "stale";
-      authorizationState = "unknown";
-      state = "disconnected";
-    } else {
-      processState = "running";
-      remoteDebuggingState = "enabled";
-      authorizationState = "unknown";
-      state = "disconnected";
-    }
-    const candidate = {
-      id: stableBrowserId(definition, os),
-      product: definition.product,
-      channel: definition.channel,
-      profile: definition.dataDir,
-      processState,
-      remoteDebuggingState,
-      authorizationState,
-      state,
-      ...remediation(state, endpoint !== null && remoteDebuggingState === "enabled") ? { remediation: remediation(state, endpoint !== null && remoteDebuggingState === "enabled") } : {}
-    };
-    results.push({ candidate, dataDir: definition.dataDir, ...endpoint ? { endpoint } : {} });
-  }
-  return results;
-}
-
-// src/page-scripts.ts
-var CLICK_TARGET_STATE_FUNCTION = `function() {
-  const target = this;
-  if (!target || target.nodeType !== 1 || !target.isConnected) {
-    return {connected:false, kind:'other', focused:false};
-  }
-  const composedParent = node => {
-    if (node && node.parentElement) return node.parentElement;
-    const root = node && typeof node.getRootNode === 'function' ? node.getRootNode() : null;
-    return root && root.host ? root.host : null;
-  };
-  const composedContains = (container, node) => {
-    for (let current = node; current; current = composedParent(current)) {
-      if (current === container) return true;
-    }
-    return false;
-  };
-  const isShadowHostOf = (node, possibleHost) => {
-    let root = node && typeof node.getRootNode === 'function' ? node.getRootNode() : null;
-    while (root && root.host) {
-      if (root.host === possibleHost) return true;
-      root = typeof root.host.getRootNode === 'function' ? root.host.getRootNode() : null;
-    }
-    return false;
-  };
-  const token = (value, mixed) => {
-    const normalized = String(value || '').trim().toLowerCase();
-    if (normalized === 'true') return true;
-    if (normalized === 'false') return false;
-    return mixed && normalized === 'mixed' ? 'mixed' : undefined;
-  };
-  const tag = String(target.tagName || '').toLowerCase();
-  const role = String(target.getAttribute && target.getAttribute('role') || '').trim().toLowerCase();
-  const inputType = tag === 'input' ? String(target.type || '').toLowerCase() : '';
-  let kind = 'other';
-  if (inputType === 'checkbox' || role === 'checkbox' || role === 'menuitemcheckbox') kind = 'checkbox';
-  else if (inputType === 'radio' || role === 'radio' || role === 'menuitemradio') kind = 'radio';
-  else if (role === 'switch') kind = 'switch';
-  else if (tag === 'option' || role === 'option') kind = 'option';
-  else if (tag === 'select' || role === 'listbox' || role === 'combobox') kind = 'select';
-  else if (
-    tag === 'button' || tag === 'a' || tag === 'input' || tag === 'textarea' ||
-    role === 'button' || role === 'link' || role === 'tab' || role === 'menuitem'
-  ) kind = 'control';
-
-  const state = {connected:true, kind, focused:false};
-  if ((kind === 'checkbox' || kind === 'radio') && tag === 'input') {
-    state.checked = !!target.checked;
-  } else if (kind === 'checkbox' || kind === 'radio' || kind === 'switch') {
-    const checked = token(target.getAttribute('aria-checked'), true);
-    if (checked !== undefined) state.checked = checked;
-  }
-  if (kind === 'option' && tag === 'option') state.selected = !!target.selected;
-  else {
-    const selected = token(target.getAttribute('aria-selected'), false);
-    if (selected !== undefined) state.selected = selected === true;
-  }
-  const pressed = token(target.getAttribute('aria-pressed'), true);
-  if (pressed !== undefined) state.pressed = pressed;
-  const expanded = token(target.getAttribute('aria-expanded'), false);
-  if (expanded !== undefined) state.expanded = expanded === true;
-
-  let active = document.activeElement;
-  for (let depth = 0; depth < 32 && active && active.shadowRoot && active.shadowRoot.activeElement; depth += 1) {
-    active = active.shadowRoot.activeElement;
-  }
-  state.focused = active === target || composedContains(target, active) || isShadowHostOf(target, active);
-  return state;
-}`;
-var GET_POINTER_TARGET_STATE = `function() {
-  const blocked = (reason, obstruction) => ({
-    status: 'blocked',
-    reason,
-    ...(obstruction ? {obstruction} : {}),
-  });
-  const composedParent = node => {
-    if (node && node.parentElement) return node.parentElement;
-    const root = node && typeof node.getRootNode === 'function' ? node.getRootNode() : null;
-    return root && root.host ? root.host : null;
-  };
-  const composedContains = (container, node) => {
-    for (let current = node; current; current = composedParent(current)) {
-      if (current === container) return true;
-    }
-    return false;
-  };
-  const isShadowHostOf = (node, possibleHost) => {
-    let root = node && typeof node.getRootNode === 'function' ? node.getRootNode() : null;
-    while (root && root.host) {
-      if (root.host === possibleHost) return true;
-      root = typeof root.host.getRootNode === 'function' ? root.host.getRootNode() : null;
-    }
-    return false;
-  };
-  const describes = node => {
-    if (!node || typeof node.tagName !== 'string') return undefined;
-    const tagName = node.tagName.toLowerCase().slice(0, 40);
-    const rawRole = typeof node.getAttribute === 'function' ? node.getAttribute('role') : null;
-    const role = typeof rawRole === 'string' ? rawRole.trim().slice(0, 40) : '';
-    return role ? {tagName, role} : {tagName};
-  };
-
-  const target = this;
-  if (!target || target.nodeType !== 1 || !target.isConnected) return blocked('detached');
-  target.scrollIntoView({block:'center', inline:'center', behavior:'instant'});
-  if (!target.isConnected) return blocked('detached');
-
-  const style = getComputedStyle(target);
-  if (style.display === 'none' || style.visibility === 'hidden' || style.visibility === 'collapse') {
-    return blocked('no_layout');
+    if (opts?.limit) p.set("limit", String(opts.limit));
+    if (opts?.url) p.set("url", opts.url);
+    if (opts?.method) p.set("method", opts.method);
+    if (opts?.status) p.set("status", opts.status);
+    if (opts?.type) p.set("type", opts.type);
+    if (opts?.after) p.set("after", String(opts.after));
+    const qs = p.toString();
+    return this.request(`/net/requests${qs ? "?" + qs : ""}`);
   }
-
-  for (let current = target; current; current = composedParent(current)) {
-    const ariaDisabled = typeof current.getAttribute === 'function'
-      ? current.getAttribute('aria-disabled') : null;
-    const nativeDisabled = typeof current.matches === 'function' && current.matches(':disabled');
-    if (nativeDisabled || current.inert === true || String(ariaDisabled).trim().toLowerCase() === 'true') {
-      return blocked('disabled');
-    }
+  async netRequestDetail(id) {
+    return this.request(`/net/request/${id}`);
   }
-
-  const viewportWidth = Math.max(0, window.innerWidth || document.documentElement.clientWidth || 0);
-  const viewportHeight = Math.max(0, window.innerHeight || document.documentElement.clientHeight || 0);
-  const rectList = target.getClientRects();
-  const rects = [];
-  for (let index = 0; index < Math.min(rectList.length, 64); index += 1) {
-    const rect = rectList[index];
-    if (
-      Number.isFinite(rect.left) && Number.isFinite(rect.top) &&
-      Number.isFinite(rect.right) && Number.isFinite(rect.bottom) &&
-      rect.width > 0 && rect.height > 0
-    ) rects.push(rect);
-  }
-  if (rects.length === 0) return blocked('no_layout');
-
-  const visibleRects = rects.map(rect => ({
-    left: Math.max(0, rect.left),
-    top: Math.max(0, rect.top),
-    right: Math.min(viewportWidth, rect.right),
-    bottom: Math.min(viewportHeight, rect.bottom),
-  })).filter(rect => rect.right > rect.left && rect.bottom > rect.top)
-    .sort((a, b) => ((b.right - b.left) * (b.bottom - b.top)) - ((a.right - a.left) * (a.bottom - a.top)))
-    .slice(0, 4);
-  if (visibleRects.length === 0) return blocked('outside_viewport');
-
-  const labels = [];
-  if (target.labels && typeof target.labels.length === 'number') {
-    for (let index = 0; index < Math.min(target.labels.length, 32); index += 1) {
-      labels.push(target.labels[index]);
-    }
+  async netBody(id) {
+    return this.request(`/net/body/${id}`);
   }
-  for (let current = target; current; current = composedParent(current)) {
-    if (String(current.tagName).toLowerCase() === 'label') labels.push(current);
+  async netClear() {
+    await this.request("/net/clear", {});
   }
-  const accepts = hit => {
-    if (!hit) return false;
-    if (hit === target || composedContains(target, hit) || isShadowHostOf(target, hit)) return true;
-    return labels.some(label => (
-      hit === label || composedContains(label, hit) || isShadowHostOf(label, hit)
-    ));
-  };
-
-  let firstObstruction;
-  for (const rect of visibleRects) {
-    const width = rect.right - rect.left;
-    const height = rect.bottom - rect.top;
-    const points = [
-      [rect.left + width * 0.5, rect.top + height * 0.5],
-      [rect.left + width * 0.25, rect.top + height * 0.25],
-      [rect.left + width * 0.75, rect.top + height * 0.25],
-      [rect.left + width * 0.25, rect.top + height * 0.75],
-      [rect.left + width * 0.75, rect.top + height * 0.75],
-    ];
-    for (const [x, y] of points) {
-      const hit = document.elementsFromPoint(x, y)[0];
-      if (accepts(hit)) {
-        const readClickTargetState = ${CLICK_TARGET_STATE_FUNCTION};
-        return {status:'ready', x, y, targetState:readClickTargetState.call(target)};
-      }
-      if (!firstObstruction && hit) firstObstruction = describes(hit);
-    }
+  async netAddRule(rule) {
+    return this.request("/net/rules", rule);
   }
-  return blocked('obscured', firstObstruction);
-}`;
-var EDITABLE_STATE_FUNCTION = `function(target) {
-  const unsupported = (reason, inputType) => ({
-    kind:'unsupported', value:'', sensitive:false, editable:false,
-    ...(inputType ? {inputType} : {}), reason,
-  });
-  if (!target || target.nodeType !== 1 || !target.isConnected) return unsupported('detached');
-
-  const composedParent = node => {
-    if (node && node.parentElement) return node.parentElement;
-    const root = node && typeof node.getRootNode === 'function' ? node.getRootNode() : null;
-    return root && root.host ? root.host : null;
-  };
-  const hasComposedState = (node, property, attribute) => {
-    for (let current = node; current; current = composedParent(current)) {
-      if (current[property] === true || current.hasAttribute?.(attribute)) return true;
-    }
-    return false;
-  };
-  const ariaTrue = (node, name) => String(node.getAttribute?.(name) || '').trim().toLowerCase() === 'true';
-  const blockedReason = node => {
-    if (hasComposedState(node, 'inert', 'inert')) return 'inert';
-    for (let current = node; current; current = composedParent(current)) {
-      if (current.matches?.(':disabled') || current.disabled === true || ariaTrue(current, 'aria-disabled')) {
-        return 'disabled';
-      }
-    }
-    for (let current = node; current; current = composedParent(current)) {
-      if (current.readOnly === true || ariaTrue(current, 'aria-readonly')) return 'readonly';
-    }
-    return null;
-  };
-  const contenteditableRoot = node => {
-    let root = node;
-    while (root.parentElement && root.parentElement.isContentEditable) root = root.parentElement;
-    return root;
-  };
-
-  if (target instanceof HTMLInputElement) {
-    const inputType = String(target.type || 'text').toLowerCase();
-    const rangeTextTypes = new Set(['text', 'search', 'tel', 'url', 'password']);
-    const selectTextTypes = new Set(['email', 'number']);
-    const valueTypes = new Set(['date', 'time', 'datetime-local', 'month', 'week', 'color', 'range']);
-    const editMode = rangeTextTypes.has(inputType) || selectTextTypes.has(inputType)
-      ? 'text' : valueTypes.has(inputType) ? 'value' : null;
-    if (!editMode) return unsupported('unsupported_input_type', inputType);
-    const reason = blockedReason(target);
-    return {
-      kind:'input', value:String(target.value ?? ''), sensitive:inputType === 'password',
-      editable:!reason, inputType, editMode,
-      ...(editMode === 'text' ? {selectionMode:selectTextTypes.has(inputType) ? 'select' : 'range'} : {}),
-      ...(reason ? {reason} : {}),
-    };
+  async netRules() {
+    return this.request("/net/rules");
   }
-  if (target instanceof HTMLTextAreaElement) {
-    const reason = blockedReason(target);
-    return {
-      kind:'input', value:String(target.value ?? ''), sensitive:false,
-      editable:!reason, inputType:'textarea', editMode:'text', selectionMode:'range',
-      ...(reason ? {reason} : {}),
-    };
+  async netRemoveRule(id) {
+    await this.request("/net/rules/remove", id !== void 0 ? { id } : { all: true });
   }
-  if (target.isContentEditable) {
-    const root = contenteditableRoot(target);
-    const reason = blockedReason(root);
-    return {
-      kind:'contenteditable', value:String(root.innerText ?? root.textContent ?? ''), sensitive:false,
-      editable:!reason, inputType:'contenteditable', editMode:'text', selectionMode:'range',
-      ...(reason ? {reason} : {}),
-    };
+  close() {
   }
-  return unsupported('unsupported_element');
-}`;
-var PREPARE_EDITABLE_TARGET = `function(clear) {
-  const readState = ${EDITABLE_STATE_FUNCTION};
-  const state = readState(this);
-  if (!state.editable) return state;
+};
 
-  if (state.kind === 'input') {
-    this.focus();
-    const focusedState = readState(this);
-    if (!focusedState.editable) return focusedState;
-    if (focusedState.editMode === 'text') {
-      if (focusedState.selectionMode === 'range') {
-        const end = String(this.value ?? '').length;
-        this.setSelectionRange(clear ? 0 : end, end, 'none');
-      } else if (clear) {
-        this.select();
-      }
-    }
-    return focusedState;
-  }
+// src/compatibility-broker-client.ts
+import { createHash as createHash4, randomUUID as randomUUID2 } from "crypto";
 
-  let root = this;
-  while (root.parentElement && root.parentElement.isContentEditable) root = root.parentElement;
-  root.focus();
-  const focusedState = readState(root);
-  if (!focusedState.editable) return focusedState;
-  const range = document.createRange();
-  range.selectNodeContents(root);
-  if (!clear) range.collapse(false);
-  const selection = window.getSelection();
-  if (!selection) return {...focusedState, editable:false, reason:'selection_unavailable'};
-  selection.removeAllRanges();
-  selection.addRange(range);
-  return focusedState;
-}`;
-var SET_VALUE_CONTROL = `function(value) {
-  const readState = ${EDITABLE_STATE_FUNCTION};
-  const state = readState(this);
-  if (!state.editable || state.kind !== 'input' || state.editMode !== 'value') return;
-  this.focus();
-  const beforeInput = new InputEvent('beforeinput', {
-    bubbles:true, composed:true, cancelable:true, inputType:'insertReplacementText', data:value,
-  });
-  if (!this.dispatchEvent(beforeInput)) return;
-  const setter = Object.getOwnPropertyDescriptor(HTMLInputElement.prototype, 'value')?.set;
-  if (setter) setter.call(this, value); else this.value = value;
-  this.dispatchEvent(new InputEvent('input', {
-    bubbles:true, composed:true, inputType:'insertReplacementText', data:value,
-  }));
-}`;
-var READ_EDITABLE_STATE = `function() {
-  const readState = ${EDITABLE_STATE_FUNCTION};
-  return readState(this);
-}`;
-var READ_ACTIVE_EDITABLE_STATE = `(() => {
-  const readState = ${EDITABLE_STATE_FUNCTION};
-  let active = document.activeElement;
-  while (active && active.shadowRoot && active.shadowRoot.activeElement) {
-    active = active.shadowRoot.activeElement;
-  }
-  return readState(active);
-})()`;
+// src/session.ts
+import { spawn } from "child_process";
 
 // src/runtime-layout.ts
 import { fileURLToPath } from "url";
@@ -1370,1847 +1081,77 @@ async function connectDaemon(browserFilter) {
         remediation: {
           code: "restart_unresponsive_broker",
           message: "Stop the unresponsive Browser Pilot Broker explicitly, then retry. Live processes are never replaced automatically.",
-          actionRequired: true
-        }
-      });
-    }
-    removeStaleBrokerFilesSync();
-    const candidates = await discoverBrowserCandidates();
-    const filter = browserFilter?.toLowerCase();
-    const matches = candidates.filter(({ candidate }) => !filter || [candidate.id, candidate.product, candidate.channel].some((value) => value?.toLowerCase().includes(filter)));
-    if (browserFilter && matches.length === 0) {
-      throw new BrowserPilotError(
-        "browser_not_found",
-        "No installed supported browser matches the requested selection.",
-        {
-          remediation: {
-            code: "select_supported_browser",
-            message: "Run browser discovery and select one of the returned browser IDs or product names.",
-            actionRequired: true
-          }
-        }
-      );
-    }
-    const selected = matches.find((browser) => browser.endpoint !== void 0) ?? matches[0] ?? null;
-    return await startDaemon(selected);
-  } finally {
-    startupLock.release();
-  }
-}
-
-// src/bridge/daemon-bridge-backend.ts
-var DaemonBridgeBackend = class {
-  constructor(browserFilter) {
-    this.browserFilter = browserFilter;
-  }
-  client;
-  async call(bridgeSessionId, method, params) {
-    const client = await this.getClient();
-    return client.brokerCall(bridgeSessionId, method, params);
-  }
-  async disconnect(bridgeSessionId) {
-    if (!this.client) return;
-    await this.client.brokerDisconnect(bridgeSessionId);
-  }
-  async *notifications(bridgeSessionId, signal) {
-    const client = await this.getClient();
-    while (!signal.aborted) {
-      try {
-        const notification = await client.brokerNextNotification(bridgeSessionId, 25e3, signal);
-        if (notification) yield notification;
-      } catch (error) {
-        if (signal.aborted) return;
-        throw error;
-      }
-    }
-  }
-  async getClient() {
-    if (!this.client) this.client = await connectDaemon(this.browserFilter);
-    const health = await this.client.healthInfo();
-    if (health.brokerProtocol !== 1) {
-      throw new BrowserPilotError("protocol_incompatible", "Running Browser Pilot daemon is from an older executable", {
-        remediation: {
-          code: "use_compatible_executable_or_isolate",
-          message: "Use a compatible Browser Pilot executable, or set BROWSER_PILOT_HOME for a deliberately isolated Broker.",
-          actionRequired: true
-        }
-      });
-    }
-    return this.client;
-  }
-};
-
-// src/bridge/stdio-bridge.ts
-import { once } from "events";
-import { randomUUID as randomUUID5 } from "crypto";
-
-// src/protocol/model.ts
-var CAPABILITIES = [
-  "browser.discovery",
-  "browser.control",
-  "workspace.manage",
-  "observation.read",
-  "action.input",
-  "artifact.read",
-  "event.read",
-  "network.observe",
-  "network.modify",
-  "auth.manage",
-  "cookies.read",
-  "developer.eval"
-];
-var OBSERVATION_TRUNCATION_REASONS = [
-  "element_limit",
-  "text_limit",
-  "depth_limit",
-  "byte_limit"
-];
-var OBSERVATION_V1_LIMITS = {
-  defaultElements: 50,
-  maxElements: 1e4,
-  maxTitleCharacters: 4096,
-  maxUrlCharacters: 16384,
-  maxElementNameCharacters: 4096,
-  maxElementValueCharacters: 65536,
-  maxTextCharacters: 1e6,
-  maxTreeDepth: 128,
-  maxSerializedBytes: 2 * 1024 * 1024,
-  ttlMs: 5 * 6e4,
-  maxStoredObservations: 2048
-};
-var SENSITIVITIES = [
-  "public",
-  "browser_data",
-  "credential",
-  "user_file"
-];
-
-// src/protocol/validation.ts
-var MAX_ID_LENGTH = 256;
-var MIN_NEGOTIATED_TRANSPORT_BYTES = 64 * 1024;
-var MAX_DECLARED_TRANSPORT_BYTES = 1024 * 1024 * 1024;
-function isRecord(value) {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-function assertOnlyKeys(record, allowed, field = "params") {
-  const allowedSet = new Set(allowed);
-  const unknown = Object.keys(record).filter((key) => !allowedSet.has(key));
-  if (unknown.length > 0) {
-    throw invalidArgument(`Unknown ${field} field: ${unknown[0]}`, `${field}.${unknown[0]}`, field === "message" ? -32600 : -32602);
-  }
-}
-function isJsonValue(value) {
-  if (value === null || ["string", "number", "boolean"].includes(typeof value)) {
-    return typeof value !== "number" || Number.isFinite(value);
-  }
-  if (Array.isArray(value)) return value.every(isJsonValue);
-  if (isRecord(value)) return Object.values(value).every(isJsonValue);
-  return false;
-}
-function requireString(record, key, options = {}) {
-  const value = record[key];
-  const maxLength = options.maxLength ?? MAX_ID_LENGTH;
-  if (typeof value !== "string" || value.length === 0 || value.length > maxLength) {
-    throw invalidArgument(`${key} must be a non-empty string no longer than ${maxLength} characters`, key);
-  }
-  if (options.pattern && !options.pattern.test(value)) {
-    throw invalidArgument(`${key} has an invalid format`, key);
-  }
-  return value;
-}
-function parseId(value, allowNull) {
-  if (allowNull && value === null) return null;
-  if (typeof value === "string" && value.length > 0 && value.length <= MAX_ID_LENGTH) return value;
-  if (typeof value === "number" && Number.isSafeInteger(value)) return value;
-  throw invalidArgument("JSON-RPC id must be a non-empty string or safe integer", "id", -32600);
-}
-function parseParams(value) {
-  if (value === void 0) return void 0;
-  if (!Array.isArray(value) && !isRecord(value) || !isJsonValue(value)) {
-    throw invalidArgument("JSON-RPC params must be a JSON object or array", "params", -32600);
-  }
-  return value;
-}
-function parseErrorObject(value) {
-  if (!isRecord(value)) throw invalidArgument("JSON-RPC error must be an object", "error", -32600);
-  if (!Number.isSafeInteger(value.code)) throw invalidArgument("JSON-RPC error.code must be an integer", "error.code", -32600);
-  const message = requireString(value, "message", { maxLength: 4096 });
-  if (value.data !== void 0 && !isJsonValue(value.data)) {
-    throw invalidArgument("JSON-RPC error.data must be valid JSON", "error.data", -32600);
-  }
-  return { code: value.code, message, ...value.data !== void 0 ? { data: value.data } : {} };
-}
-function parseJsonRpcMessage(line, maxMessageBytes = 1024 * 1024) {
-  if (Buffer.byteLength(line, "utf8") > maxMessageBytes) {
-    throw new BrowserPilotError("result_too_large", `Protocol message exceeds ${maxMessageBytes} bytes`, {
-      context: { maxMessageBytes },
-      rpcCode: -32600
-    });
-  }
-  if (line.trim().length === 0) throw invalidArgument("Protocol message is empty", void 0, -32700);
-  let parsed;
-  try {
-    parsed = JSON.parse(line);
-  } catch (cause) {
-    throw new BrowserPilotError("invalid_argument", "Invalid JSON", { rpcCode: -32700, cause });
-  }
-  if (!isRecord(parsed) || parsed.jsonrpc !== "2.0") {
-    throw invalidArgument("Message must be a JSON-RPC 2.0 object", "jsonrpc", -32600);
-  }
-  if (typeof parsed.method === "string") {
-    assertOnlyKeys(parsed, ["jsonrpc", "id", "method", "params"], "message");
-    const method = requireString(parsed, "method", { maxLength: 256 });
-    const params = parseParams(parsed.params);
-    if (parsed.id === void 0) {
-      return { jsonrpc: "2.0", method, ...params !== void 0 ? { params } : {} };
-    }
-    return {
-      jsonrpc: "2.0",
-      id: parseId(parsed.id, false),
-      method,
-      ...params !== void 0 ? { params } : {}
-    };
-  }
-  if (parsed.id === void 0) {
-    throw invalidArgument("JSON-RPC response must include id", "id", -32600);
-  }
-  const id = parseId(parsed.id, true);
-  const hasResult = Object.hasOwn(parsed, "result");
-  const hasError = Object.hasOwn(parsed, "error");
-  if (hasResult === hasError) {
-    throw invalidArgument("JSON-RPC response must contain exactly one of result or error", void 0, -32600);
-  }
-  if (hasResult) {
-    assertOnlyKeys(parsed, ["jsonrpc", "id", "result"], "message");
-    if (!isJsonValue(parsed.result)) throw invalidArgument("JSON-RPC result must be valid JSON", "result", -32600);
-    return { jsonrpc: "2.0", id, result: parsed.result };
-  }
-  assertOnlyKeys(parsed, ["jsonrpc", "id", "error"], "message");
-  return { jsonrpc: "2.0", id, error: parseErrorObject(parsed.error) };
-}
-
-// src/services/broker-runtime.ts
-import { randomUUID as randomUUID4 } from "crypto";
-
-// src/protocol/schema.ts
-function isRecord2(value) {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-function assertSchemaDefinition(schema, path = "$schema") {
-  const sensitivity = schema["x-browser-pilot-sensitivity"];
-  if (sensitivity) {
-    if (sensitivity.length === 0 || new Set(sensitivity).size !== sensitivity.length) {
-      throw new Error(`${path}.x-browser-pilot-sensitivity must be non-empty and unique`);
-    }
-    for (const value of sensitivity) {
-      if (!SENSITIVITIES.includes(value)) {
-        throw new Error(`${path}.x-browser-pilot-sensitivity contains unknown value ${value}`);
-      }
-    }
-  }
-  if (schema.type === "object") {
-    const properties = schema.properties ?? {};
-    for (const required of schema.required ?? []) {
-      if (!Object.hasOwn(properties, required)) {
-        throw new Error(`${path}.required references unknown property ${required}`);
-      }
-    }
-    for (const [name, property] of Object.entries(properties)) {
-      assertSchemaDefinition(property, `${path}.properties.${name}`);
-    }
-    if (isRecord2(schema.additionalProperties)) {
-      assertSchemaDefinition(schema.additionalProperties, `${path}.additionalProperties`);
-    }
-  }
-  if (schema.type === "array" && schema.items) {
-    assertSchemaDefinition(schema.items, `${path}.items`);
-  }
-  for (const [index, alternative] of (schema.oneOf ?? []).entries()) {
-    assertSchemaDefinition(alternative, `${path}.oneOf[${index}]`);
-  }
-  if (schema.pattern) new RegExp(schema.pattern, "u");
-}
-var stringSchema = (options = {}) => ({ type: "string", ...options });
-var booleanSchema = (options = {}) => ({ type: "boolean", ...options });
-var integerSchema = (options = {}) => ({ type: "integer", ...options });
-var numberSchema = (options = {}) => ({ type: "number", ...options });
-var arraySchema = (items, options = {}) => ({
-  type: "array",
-  items,
-  ...options
-});
-var objectSchema = (properties, required = [], options = {}) => ({
-  type: "object",
-  properties,
-  required,
-  additionalProperties: false,
-  ...options
-});
-
-// src/protocol/tools.ts
-var emptyInput = objectSchema({});
-function sensitive(schema, ...sensitivity) {
-  return { ...schema, "x-browser-pilot-sensitivity": sensitivity };
-}
-var boundedText = sensitive(
-  stringSchema({ minLength: 1, maxLength: 1e6 }),
-  "browser_data",
-  "credential"
-);
-var boundedSelector = sensitive(stringSchema({ minLength: 1, maxLength: 4096 }), "browser_data");
-var boundedUrl = sensitive(stringSchema({ minLength: 1, maxLength: 16384 }), "browser_data");
-var opaqueIdSchema = stringSchema({ minLength: 3, maxLength: 128, pattern: "^[A-Za-z0-9][A-Za-z0-9._:-]+$" });
-var headerSchema = objectSchema({
-  name: sensitive(stringSchema({ minLength: 1, maxLength: 256 }), "browser_data"),
-  value: sensitive(stringSchema({ maxLength: 8192 }), "browser_data", "credential")
-}, ["name", "value"]);
-var networkRuleSchema = objectSchema({
-  ruleId: opaqueIdSchema,
-  type: stringSchema({ enum: ["block", "mock", "headers"] }),
-  pattern: boundedUrl,
-  status: integerSchema({ minimum: 100, maximum: 999 }),
-  headers: arraySchema(headerSchema, { maxItems: 256 }),
-  bodySize: integerSchema({ minimum: 0 })
-}, ["ruleId", "type", "pattern"]);
-var networkRequestDetailSchema = objectSchema({
-  requestId: opaqueIdSchema,
-  sequence: integerSchema({ minimum: 1 }),
-  method: stringSchema({ maxLength: 32 }),
-  url: boundedUrl,
-  type: stringSchema({ maxLength: 128 }),
-  requestHeaders: arraySchema(headerSchema, { maxItems: 256 }),
-  postData: sensitive(stringSchema({ maxLength: 65536 }), "browser_data", "credential"),
-  postDataTruncated: booleanSchema(),
-  status: integerSchema({ minimum: 100, maximum: 999 }),
-  statusText: sensitive(stringSchema({ maxLength: 4096 }), "browser_data"),
-  responseHeaders: arraySchema(headerSchema, { maxItems: 256 }),
-  mimeType: stringSchema({ maxLength: 256 }),
-  size: integerSchema({ minimum: 0 }),
-  durationMs: numberSchema({ minimum: 0 }),
-  error: sensitive(stringSchema({ maxLength: 4096 }), "browser_data"),
-  bodyAvailable: booleanSchema()
-}, [
-  "requestId",
-  "sequence",
-  "method",
-  "url",
-  "type",
-  "requestHeaders",
-  "postDataTruncated",
-  "bodyAvailable"
-]);
-var elementSchema = objectSchema({
-  ref: integerSchema({ minimum: 1 }),
-  role: stringSchema({ minLength: 1, maxLength: 128 }),
-  name: sensitive(stringSchema({ maxLength: OBSERVATION_V1_LIMITS.maxElementNameCharacters }), "browser_data"),
-  value: sensitive(stringSchema({ maxLength: OBSERVATION_V1_LIMITS.maxElementValueCharacters }), "browser_data", "credential"),
-  checked: booleanSchema()
-}, ["ref", "role", "name"]);
-var inputEvidenceSchema = objectSchema({
-  action: stringSchema({ enum: ["type", "keyboard"] }),
-  status: stringSchema({ enum: ["verified", "mismatch", "unavailable"] }),
-  kind: stringSchema({ enum: ["input", "contenteditable", "unsupported"] }),
-  sensitive: booleanSchema(),
-  beforeLength: integerSchema({ minimum: 0 }),
-  expectedLength: integerSchema({ minimum: 0 }),
-  afterLength: integerSchema({ minimum: 0 }),
-  reason: stringSchema({ enum: ["active_element_not_readable", "value_mismatch"] })
-}, ["action", "status", "kind", "sensitive"]);
-var clickEvidenceSchema = objectSchema({
-  action: stringSchema({ const: "click" }),
-  status: stringSchema({ enum: ["verified", "mismatch", "unavailable"] }),
-  kind: stringSchema({ enum: [
-    "checkbox",
-    "radio",
-    "switch",
-    "option",
-    "select",
-    "control",
-    "other",
-    "coordinates"
-  ] }),
-  effects: arraySchema(stringSchema({ enum: [
-    "checked_changed",
-    "selected_changed",
-    "pressed_changed",
-    "expanded_changed",
-    "focus_changed",
-    "navigation",
-    "document_changed",
-    "dialog_opened",
-    "popup_opened"
-  ] }), { maxItems: 9, uniqueItems: true }),
-  checked: { oneOf: [booleanSchema(), stringSchema({ const: "mixed" })] },
-  selected: booleanSchema(),
-  pressed: { oneOf: [booleanSchema(), stringSchema({ const: "mixed" })] },
-  expanded: booleanSchema(),
-  focused: booleanSchema(),
-  reason: stringSchema({ enum: [
-    "coordinate_target",
-    "target_unavailable",
-    "expected_state_unchanged",
-    "no_observable_effect"
-  ] })
-}, ["action", "status", "kind", "effects"]);
-var pressEvidenceSchema = objectSchema({
-  action: stringSchema({ const: "press" }),
-  status: stringSchema({ enum: ["verified", "unavailable"] }),
-  kind: stringSchema({ enum: [
-    "input",
-    "contenteditable",
-    "checkbox",
-    "radio",
-    "select",
-    "control",
-    "other"
-  ] }),
-  effects: arraySchema(stringSchema({ enum: [
-    "value_changed",
-    "checked_changed",
-    "selected_changed",
-    "pressed_changed",
-    "expanded_changed",
-    "focus_changed",
-    "navigation",
-    "document_changed",
-    "dialog_opened",
-    "popup_opened"
-  ] }), { maxItems: 10, uniqueItems: true }),
-  sensitive: booleanSchema(),
-  reason: stringSchema({ enum: ["target_unavailable", "no_observable_effect"] })
-}, ["action", "status", "kind", "effects", "sensitive"]);
-var uploadEvidenceSchema = objectSchema({
-  action: stringSchema({ const: "upload" }),
-  status: stringSchema({ enum: ["verified", "mismatch", "unavailable"] }),
-  expectedFileCount: integerSchema({ const: 1 }),
-  fileCount: integerSchema({ minimum: 0 }),
-  nameMatched: booleanSchema(),
-  reason: stringSchema({ enum: [
-    "target_unavailable",
-    "file_count_mismatch",
-    "file_name_mismatch"
-  ] })
-}, ["action", "status", "expectedFileCount"]);
-var scrollEvidenceSchema = objectSchema({
-  action: stringSchema({ const: "scroll" }),
-  status: stringSchema({ enum: ["verified", "mismatch"] }),
-  mode: stringSchema({ enum: ["relative", "position", "text"] }),
-  target: stringSchema({ enum: ["page", "element", "text"] }),
-  moved: booleanSchema(),
-  deltaX: numberSchema(),
-  deltaY: numberSchema(),
-  beforeX: numberSchema({ minimum: 0 }),
-  beforeY: numberSchema({ minimum: 0 }),
-  afterX: numberSchema({ minimum: 0 }),
-  afterY: numberSchema({ minimum: 0 }),
-  matchedText: sensitive(stringSchema({ maxLength: 4096 }), "browser_data"),
-  reason: stringSchema({ enum: ["at_boundary", "text_not_found", "text_not_revealed"] })
-}, [
-  "action",
-  "status",
-  "mode",
-  "target",
-  "moved",
-  "deltaX",
-  "deltaY",
-  "beforeX",
-  "beforeY",
-  "afterX",
-  "afterY"
-]);
-var dropdownOptionSchema = objectSchema({
-  index: integerSchema({ minimum: 1, maximum: 500 }),
-  label: sensitive(stringSchema({ maxLength: 4096 }), "browser_data"),
-  value: sensitive(stringSchema({ maxLength: 4096 }), "browser_data"),
-  selected: booleanSchema(),
-  disabled: booleanSchema()
-}, ["index", "label", "value", "selected", "disabled"]);
-var selectEvidenceSchema = objectSchema({
-  action: stringSchema({ const: "select" }),
-  status: stringSchema({ enum: ["verified", "mismatch", "unavailable"] }),
-  kind: stringSchema({ enum: ["native", "aria"] }),
-  selected: arraySchema(dropdownOptionSchema, { maxItems: 500 }),
-  reason: stringSchema({ enum: ["option_not_found", "selection_mismatch", "selection_not_exposed"] })
-}, ["action", "status", "kind", "selected"]);
-var artifactSchema = objectSchema({
-  id: opaqueIdSchema,
-  workspaceId: opaqueIdSchema,
-  kind: stringSchema({ enum: ["screenshot", "screenshot_preview", "pdf", "download", "upload_input"] }),
-  mimeType: stringSchema({ minLength: 1, maxLength: 256 }),
-  byteSize: integerSchema({ minimum: 0 }),
-  fileName: stringSchema({ minLength: 1, maxLength: 4096 }),
-  width: integerSchema({ minimum: 1 }),
-  height: integerSchema({ minimum: 1 }),
-  sensitivity: stringSchema({ enum: ["public", "browser_data", "credential", "user_file"] }),
-  createdAt: integerSchema({ minimum: 0 }),
-  expiresAt: integerSchema({ minimum: 0 }),
-  retained: booleanSchema(),
-  previewOf: opaqueIdSchema
-}, ["id", "workspaceId", "kind", "mimeType", "byteSize", "sensitivity", "createdAt", "expiresAt", "retained"]);
-var hintRefsSchema = arraySchema(integerSchema({ minimum: 1 }), {
-  maxItems: 32,
-  uniqueItems: true
-});
-var agentHintSchema = {
-  oneOf: [
-    objectSchema({
-      code: stringSchema({ const: "autocomplete" }),
-      source: stringSchema({ const: "observation" }),
-      confidence: stringSchema({ enum: ["strong", "possible"] }),
-      recommendedAction: stringSchema({ const: "observe_then_select" }),
-      refs: hintRefsSchema
-    }, ["code", "source", "confidence", "recommendedAction", "refs"]),
-    objectSchema({
-      code: stringSchema({ const: "modal_overlay" }),
-      source: stringSchema({ const: "observation" }),
-      confidence: stringSchema({ enum: ["strong", "possible"] }),
-      recommendedAction: stringSchema({ const: "resolve_overlay_first" }),
-      blocking: booleanSchema(),
-      refs: hintRefsSchema
-    }, ["code", "source", "confidence", "recommendedAction", "blocking", "refs"]),
-    objectSchema({
-      code: stringSchema({ const: "filter_controls" }),
-      source: stringSchema({ const: "observation" }),
-      confidence: stringSchema({ const: "strong" }),
-      recommendedAction: stringSchema({ const: "review_refinement_controls" }),
-      refs: hintRefsSchema
-    }, ["code", "source", "confidence", "recommendedAction", "refs"]),
-    objectSchema({
-      code: stringSchema({ const: "access_blocked" }),
-      source: stringSchema({ const: "network" }),
-      confidence: stringSchema({ const: "strong" }),
-      recommendedAction: stringSchema({ const: "avoid_same_navigation_retry" }),
-      status: integerSchema({ enum: [403, 429] })
-    }, ["code", "source", "confidence", "recommendedAction", "status"]),
-    objectSchema({
-      code: stringSchema({ const: "authentication_surface" }),
-      source: stringSchema({ const: "observation" }),
-      confidence: stringSchema({ const: "strong" }),
-      recommendedAction: stringSchema({ const: "inspect_authentication_state" }),
-      state: stringSchema({ enum: ["present", "entered", "left"] })
-    }, ["code", "source", "confidence", "recommendedAction", "state"]),
-    objectSchema({
-      code: stringSchema({ const: "download" }),
-      source: stringSchema({ const: "download" }),
-      confidence: stringSchema({ const: "strong" }),
-      recommendedAction: stringSchema({ const: "wait_for_download" }),
-      state: stringSchema({ const: "started" })
-    }, ["code", "source", "confidence", "recommendedAction", "state"]),
-    objectSchema({
-      code: stringSchema({ const: "download" }),
-      source: stringSchema({ const: "download" }),
-      confidence: stringSchema({ const: "strong" }),
-      recommendedAction: stringSchema({ const: "inspect_download_artifact" }),
-      state: stringSchema({ const: "completed" }),
-      artifactId: opaqueIdSchema
-    }, ["code", "source", "confidence", "recommendedAction", "state", "artifactId"]),
-    objectSchema({
-      code: stringSchema({ const: "download" }),
-      source: stringSchema({ const: "download" }),
-      confidence: stringSchema({ const: "strong" }),
-      recommendedAction: stringSchema({ const: "inspect_download_failure" }),
-      state: stringSchema({ enum: ["failed", "cancelled"] }),
-      reason: stringSchema({ minLength: 1, maxLength: 128 })
-    }, ["code", "source", "confidence", "recommendedAction", "state", "reason"]),
-    objectSchema({
-      code: stringSchema({ const: "repeated_action" }),
-      source: stringSchema({ const: "watchdog" }),
-      confidence: stringSchema({ const: "strong" }),
-      recommendedAction: stringSchema({ const: "change_strategy" }),
-      streak: integerSchema({ minimum: 1, maximum: 1e6 }),
-      reason: stringSchema({ minLength: 1, maxLength: 128 })
-    }, ["code", "source", "confidence", "recommendedAction", "streak", "reason"])
-  ]
-};
-function resultSchema(context, properties = {}, required = []) {
-  const contextProperties = {};
-  const contextRequired = [];
-  if (context === "workspace" || context === "target") {
-    contextProperties.workspaceId = opaqueIdSchema;
-    contextProperties.leaseId = opaqueIdSchema;
-    contextRequired.push("workspaceId", "leaseId");
-  }
-  if (context === "target") {
-    contextProperties.targetId = opaqueIdSchema;
-    contextProperties.profileContextId = opaqueIdSchema;
-    contextProperties.url = boundedUrl;
-    contextRequired.push("targetId", "url");
-  }
-  return objectSchema({ ...contextProperties, ...properties }, [...contextRequired, ...required]);
-}
-var observationOutput = resultSchema("target", {
-  observationId: opaqueIdSchema,
-  title: sensitive(stringSchema({ maxLength: OBSERVATION_V1_LIMITS.maxTitleCharacters }), "browser_data"),
-  page: objectSchema({
-    viewportWidth: integerSchema({ minimum: 0 }),
-    viewportHeight: integerSchema({ minimum: 0 }),
-    documentWidth: integerSchema({ minimum: 0 }),
-    documentHeight: integerSchema({ minimum: 0 }),
-    scrollX: integerSchema({ minimum: 0 }),
-    scrollY: integerSchema({ minimum: 0 }),
-    pixelsAbove: integerSchema({ minimum: 0 }),
-    pixelsBelow: integerSchema({ minimum: 0 }),
-    pixelsLeft: integerSchema({ minimum: 0 }),
-    pixelsRight: integerSchema({ minimum: 0 }),
-    scrollPercentX: numberSchema({ minimum: 0, maximum: 100 }),
-    scrollPercentY: numberSchema({ minimum: 0, maximum: 100 })
-  }, [
-    "viewportWidth",
-    "viewportHeight",
-    "documentWidth",
-    "documentHeight",
-    "scrollX",
-    "scrollY",
-    "pixelsAbove",
-    "pixelsBelow",
-    "pixelsLeft",
-    "pixelsRight",
-    "scrollPercentX",
-    "scrollPercentY"
-  ]),
-  elements: arraySchema(elementSchema, { maxItems: OBSERVATION_V1_LIMITS.maxElements }),
-  truncated: booleanSchema(),
-  truncationReasons: arraySchema(stringSchema({
-    enum: [...OBSERVATION_TRUNCATION_REASONS]
-  }), { uniqueItems: true }),
-  hints: arraySchema(agentHintSchema, { maxItems: 16 }),
-  evidence: { oneOf: [
-    inputEvidenceSchema,
-    clickEvidenceSchema,
-    pressEvidenceSchema,
-    uploadEvidenceSchema,
-    scrollEvidenceSchema,
-    selectEvidenceSchema
-  ] }
-}, ["observationId", "title", "elements", "truncated", "truncationReasons"]);
-var artifactOutput = resultSchema("target", {
-  artifact: artifactSchema,
-  preview: artifactSchema,
-  annotationCount: integerSchema({ minimum: 0, maximum: 200 })
-}, ["artifact"]);
-var elementAddressSchema = {
-  oneOf: [
-    objectSchema({
-      observationId: opaqueIdSchema,
-      ref: integerSchema({ minimum: 1 })
-    }, ["observationId", "ref"]),
-    objectSchema({ selector: boundedSelector }, ["selector"])
-  ]
-};
-var dropdownChoiceSchema = {
-  oneOf: [
-    objectSchema({ by: stringSchema({ const: "index" }), index: integerSchema({ minimum: 1, maximum: 500 }) }, ["by", "index"]),
-    objectSchema({
-      by: stringSchema({ const: "label" }),
-      label: sensitive(stringSchema({ minLength: 1, maxLength: 4096 }), "browser_data"),
-      exact: booleanSchema()
-    }, ["by", "label"]),
-    objectSchema({
-      by: stringSchema({ const: "value" }),
-      value: sensitive(stringSchema({ minLength: 1, maxLength: 4096 }), "browser_data"),
-      exact: booleanSchema()
-    }, ["by", "value"])
-  ]
-};
-var profileRepresentativeTabSchema = objectSchema({
-  targetId: opaqueIdSchema,
-  title: sensitive(stringSchema({ maxLength: 4096 }), "browser_data"),
-  url: boundedUrl
-}, ["targetId", "title", "url"]);
-var profileContextSchema = objectSchema({
-  profileContextId: opaqueIdSchema,
-  label: stringSchema({ minLength: 1, maxLength: 128 }),
-  displayName: sensitive(stringSchema({ minLength: 1, maxLength: 4096 }), "browser_data"),
-  tabCount: integerSchema({ minimum: 0 }),
-  eligibleTabCount: integerSchema({ minimum: 0 }),
-  selected: booleanSchema(),
-  representativeTabs: arraySchema(profileRepresentativeTabSchema, { maxItems: 3 })
-}, [
-  "profileContextId",
-  "label",
-  "tabCount",
-  "eligibleTabCount",
-  "selected",
-  "representativeTabs"
-]);
-function tool(definition) {
-  return definition;
-}
-var TOOL_DEFINITIONS = [
-  tool({
-    name: "browser.discover",
-    title: "Discover browsers",
-    description: "List supported local browsers and structured setup or authorization state.",
-    context: "connection",
-    inputSchema: objectSchema({ browser: stringSchema({ minLength: 1, maxLength: 128 }) }),
-    outputSchema: resultSchema("connection", {
-      browsers: arraySchema(objectSchema({
-        id: opaqueIdSchema,
-        product: stringSchema({ minLength: 1, maxLength: 128 }),
-        channel: stringSchema({ maxLength: 128 }),
-        profile: sensitive(stringSchema({ maxLength: 4096 }), "browser_data"),
-        processState: stringSchema({ enum: ["running", "not_running", "unknown"] }),
-        remoteDebuggingState: stringSchema({ enum: ["enabled", "disabled", "stale"] }),
-        authorizationState: stringSchema({ enum: ["authorized", "required", "not_applicable", "unknown"] }),
-        state: stringSchema({ enum: ["ready", "not_running", "remote_debugging_disabled", "authorization_required", "disconnected"] }),
-        remediation: objectSchema({
-          code: stringSchema({ minLength: 1, maxLength: 128 }),
-          message: stringSchema({ minLength: 1, maxLength: 4096 }),
-          actionRequired: booleanSchema()
-        }, ["code", "message", "actionRequired"])
-      }, [
-        "id",
-        "product",
-        "processState",
-        "remoteDebuggingState",
-        "authorizationState",
-        "state"
-      ]))
-    }, ["browsers"]),
-    requiredCapabilities: ["browser.discovery"],
-    mutating: false,
-    idempotency: "read_only",
-    cancellation: "not_applicable",
-    sensitivity: { input: [], output: ["browser_data"] },
-    artifactKinds: []
-  }),
-  tool({
-    name: "browser.connect",
-    title: "Connect browser",
-    description: "Connect a Workspace to a selected authorized browser instance.",
-    context: "workspace",
-    inputSchema: objectSchema({ browserId: opaqueIdSchema }, ["browserId"]),
-    outputSchema: resultSchema("workspace", {
-      browserInstanceId: opaqueIdSchema,
-      connectionGeneration: integerSchema({ minimum: 1 }),
-      state: stringSchema({ const: "connected" })
-    }, ["browserInstanceId", "connectionGeneration", "state"]),
-    requiredCapabilities: ["browser.control"],
-    mutating: true,
-    idempotency: "idempotent",
-    cancellation: "before_dispatch",
-    sensitivity: { input: [], output: ["browser_data"] },
-    artifactKinds: []
-  }),
-  tool({
-    name: "browser.profiles.list",
-    title: "List browser Profiles",
-    description: "Passively list live Profile contexts and bounded representative tabs.",
-    context: "workspace",
-    inputSchema: emptyInput,
-    outputSchema: resultSchema("workspace", {
-      profiles: arraySchema(profileContextSchema, { maxItems: 128 })
-    }, ["profiles"]),
-    requiredCapabilities: ["browser.control"],
-    mutating: false,
-    idempotency: "read_only",
-    cancellation: "not_applicable",
-    sensitivity: { input: [], output: ["browser_data"] },
-    artifactKinds: []
-  }),
-  tool({
-    name: "browser.profiles.select",
-    title: "Select browser Profile",
-    description: "Select one current Profile context for new managed targets in this Workspace.",
-    context: "workspace",
-    inputSchema: objectSchema({ profileContextId: opaqueIdSchema }, ["profileContextId"]),
-    outputSchema: resultSchema("workspace", {
-      profileContextId: opaqueIdSchema,
-      label: stringSchema({ minLength: 1, maxLength: 128 }),
-      displayName: sensitive(stringSchema({ minLength: 1, maxLength: 4096 }), "browser_data")
-    }, ["profileContextId", "label"]),
-    requiredCapabilities: ["browser.control"],
-    mutating: true,
-    idempotency: "idempotent",
-    cancellation: "before_dispatch",
-    sensitivity: { input: [], output: ["browser_data"] },
-    artifactKinds: []
-  }),
-  tool({
-    name: "browser.open",
-    title: "Open URL",
-    description: "Navigate an authorized controlled target or create a new target in the ManagedTabSet.",
-    context: "workspace",
-    inputSchema: objectSchema({
-      url: boundedUrl,
-      targetId: opaqueIdSchema,
-      newTarget: booleanSchema(),
-      profileContextId: opaqueIdSchema,
-      observationLimit: integerSchema({ minimum: 1, maximum: OBSERVATION_V1_LIMITS.maxElements })
-    }, ["url"]),
-    outputSchema: observationOutput,
-    requiredCapabilities: ["browser.control", "observation.read"],
-    mutating: true,
-    idempotency: "non_idempotent",
-    cancellation: "best_effort",
-    sensitivity: { input: ["browser_data"], output: ["browser_data", "credential"] },
-    artifactKinds: []
-  }),
-  tool({
-    name: "browser.observe",
-    title: "Observe page",
-    description: "Create an immutable bounded Observation with numbered refs.",
-    context: "target",
-    inputSchema: objectSchema({
-      limit: integerSchema({ minimum: 1, maximum: OBSERVATION_V1_LIMITS.maxElements })
-    }),
-    outputSchema: observationOutput,
-    requiredCapabilities: ["observation.read"],
-    mutating: false,
-    idempotency: "read_only",
-    cancellation: "best_effort",
-    sensitivity: { input: [], output: ["browser_data", "credential"] },
-    artifactKinds: []
-  }),
-  tool({
-    name: "browser.observation.latest",
-    title: "Get latest Observation",
-    description: "Return the latest live Observation descriptor for a controlled target.",
-    context: "target",
-    inputSchema: emptyInput,
-    outputSchema: resultSchema("target", {
-      observationId: opaqueIdSchema,
-      createdAt: integerSchema({ minimum: 0 }),
-      expiresAt: integerSchema({ minimum: 0 }),
-      elementCount: integerSchema({ minimum: 0, maximum: OBSERVATION_V1_LIMITS.maxElements })
-    }, ["observationId", "createdAt", "expiresAt", "elementCount"]),
-    requiredCapabilities: ["observation.read"],
-    mutating: false,
-    idempotency: "read_only",
-    cancellation: "not_applicable",
-    sensitivity: { input: [], output: ["browser_data"] },
-    artifactKinds: []
-  }),
-  tool({
-    name: "browser.locate",
-    title: "Locate element",
-    description: "Return viewport coordinates for a CSS selector in the selected frame.",
-    context: "target",
-    inputSchema: objectSchema({ selector: boundedSelector }, ["selector"]),
-    outputSchema: resultSchema("target", {
-      x: numberSchema(),
-      y: numberSchema(),
-      top: numberSchema(),
-      left: numberSchema(),
-      width: numberSchema({ minimum: 0 }),
-      height: numberSchema({ minimum: 0 })
-    }, ["x", "y", "top", "left", "width", "height"]),
-    requiredCapabilities: ["observation.read"],
-    mutating: false,
-    idempotency: "read_only",
-    cancellation: "best_effort",
-    sensitivity: { input: ["browser_data"], output: ["browser_data"] },
-    artifactKinds: []
-  }),
-  tool({
-    name: "browser.read",
-    title: "Read page text",
-    description: "Read bounded text from the page or a selector.",
-    context: "target",
-    inputSchema: objectSchema({
-      selector: boundedSelector,
-      limit: integerSchema({ minimum: 1, maximum: 1e6 })
-    }),
-    outputSchema: resultSchema("target", {
-      title: sensitive(stringSchema({ maxLength: 4096 }), "browser_data"),
-      text: sensitive(stringSchema({ maxLength: 1e6 }), "browser_data"),
-      length: integerSchema({ minimum: 0 }),
-      truncated: booleanSchema()
-    }, ["title", "text", "length", "truncated"]),
-    requiredCapabilities: ["observation.read"],
-    mutating: false,
-    idempotency: "read_only",
-    cancellation: "best_effort",
-    sensitivity: { input: ["browser_data"], output: ["browser_data"] },
-    artifactKinds: []
-  }),
-  tool({
-    name: "browser.search",
-    title: "Search page text",
-    description: "Find bounded visible text matches without returning the entire page.",
-    context: "target",
-    inputSchema: objectSchema({
-      query: sensitive(stringSchema({ minLength: 1, maxLength: 4096 }), "browser_data"),
-      selector: boundedSelector,
-      caseSensitive: booleanSchema(),
-      wholeWord: booleanSchema(),
-      limit: integerSchema({ minimum: 1, maximum: 200 })
-    }, ["query"]),
-    outputSchema: resultSchema("target", {
-      title: sensitive(stringSchema({ maxLength: 4096 }), "browser_data"),
-      totalMatches: integerSchema({ minimum: 0 }),
-      matches: arraySchema(objectSchema({
-        index: integerSchema({ minimum: 1 }),
-        text: sensitive(stringSchema({ maxLength: 4096 }), "browser_data"),
-        context: sensitive(stringSchema({ maxLength: 500 }), "browser_data"),
-        tagName: stringSchema({ maxLength: 64 }),
-        visible: booleanSchema(),
-        x: numberSchema(),
-        y: numberSchema(),
-        width: numberSchema({ minimum: 0 }),
-        height: numberSchema({ minimum: 0 })
-      }, ["index", "text", "context", "tagName", "visible", "x", "y", "width", "height"]), { maxItems: 200 }),
-      truncated: booleanSchema()
-    }, ["title", "totalMatches", "matches", "truncated"]),
-    requiredCapabilities: ["observation.read"],
-    mutating: false,
-    idempotency: "read_only",
-    cancellation: "best_effort",
-    sensitivity: { input: ["browser_data"], output: ["browser_data"] },
-    artifactKinds: []
-  }),
-  tool({
-    name: "browser.elements.find",
-    title: "Find DOM elements",
-    description: "Run a bounded CSS query and return safe element metadata without exposing DOM handles.",
-    context: "target",
-    inputSchema: objectSchema({
-      selector: boundedSelector,
-      limit: integerSchema({ minimum: 1, maximum: 200 }),
-      attributeNames: arraySchema(
-        sensitive(stringSchema({ minLength: 1, maxLength: 128, pattern: "^[A-Za-z_:][A-Za-z0-9_.:-]*$" }), "browser_data"),
-        { maxItems: 20, uniqueItems: true }
-      ),
-      pierceShadow: booleanSchema()
-    }, ["selector"]),
-    outputSchema: resultSchema("target", {
-      title: sensitive(stringSchema({ maxLength: 4096 }), "browser_data"),
-      totalMatches: integerSchema({ minimum: 0 }),
-      elements: arraySchema(objectSchema({
-        index: integerSchema({ minimum: 1 }),
-        tagName: stringSchema({ maxLength: 64 }),
-        role: stringSchema({ maxLength: 128 }),
-        name: sensitive(stringSchema({ maxLength: 4096 }), "browser_data"),
-        text: sensitive(stringSchema({ maxLength: 500 }), "browser_data"),
-        visible: booleanSchema(),
-        enabled: booleanSchema(),
-        x: numberSchema(),
-        y: numberSchema(),
-        width: numberSchema({ minimum: 0 }),
-        height: numberSchema({ minimum: 0 }),
-        attributes: arraySchema(objectSchema({
-          name: sensitive(stringSchema({ maxLength: 128 }), "browser_data"),
-          value: sensitive(stringSchema({ maxLength: 2048 }), "browser_data", "credential")
-        }, ["name", "value"]), { maxItems: 20 })
-      }, [
-        "index",
-        "tagName",
-        "role",
-        "name",
-        "text",
-        "visible",
-        "enabled",
-        "x",
-        "y",
-        "width",
-        "height",
-        "attributes"
-      ]), { maxItems: 200 }),
-      truncated: booleanSchema()
-    }, ["title", "totalMatches", "elements", "truncated"]),
-    requiredCapabilities: ["observation.read"],
-    mutating: false,
-    idempotency: "read_only",
-    cancellation: "best_effort",
-    sensitivity: { input: ["browser_data"], output: ["browser_data", "credential"] },
-    artifactKinds: []
-  }),
-  tool({
-    name: "browser.scroll",
-    title: "Scroll page or element",
-    description: "Scroll the page, a ref, a CSS-selected container, or visible text and return a fresh Observation.",
-    context: "target",
-    inputSchema: objectSchema({
-      target: elementAddressSchema,
-      direction: stringSchema({ enum: ["up", "down", "left", "right"] }),
-      amount: numberSchema({ minimum: 0.01, maximum: 1e5 }),
-      unit: stringSchema({ enum: ["pixels", "viewport"] }),
-      position: stringSchema({ enum: ["start", "end"] }),
-      text: sensitive(stringSchema({ minLength: 1, maxLength: 4096 }), "browser_data"),
-      exact: booleanSchema(),
-      observationLimit: integerSchema({ minimum: 1, maximum: OBSERVATION_V1_LIMITS.maxElements })
-    }),
-    outputSchema: observationOutput,
-    requiredCapabilities: ["action.input", "observation.read"],
-    mutating: true,
-    idempotency: "non_idempotent",
-    cancellation: "best_effort",
-    sensitivity: { input: ["browser_data"], output: ["browser_data", "credential"] },
-    artifactKinds: []
-  }),
-  tool({
-    name: "browser.dropdown.options",
-    title: "List dropdown options",
-    description: "Enumerate bounded native or currently exposed ARIA dropdown options.",
-    context: "target",
-    inputSchema: objectSchema({ target: elementAddressSchema }, ["target"]),
-    outputSchema: resultSchema("target", {
-      kind: stringSchema({ enum: ["native", "aria"] }),
-      expanded: booleanSchema(),
-      multiple: booleanSchema(),
-      requiresOpen: booleanSchema(),
-      options: arraySchema(dropdownOptionSchema, { maxItems: 500 }),
-      truncated: booleanSchema()
-    }, ["kind", "expanded", "multiple", "requiresOpen", "options", "truncated"]),
-    requiredCapabilities: ["observation.read"],
-    mutating: false,
-    idempotency: "read_only",
-    cancellation: "best_effort",
-    sensitivity: { input: ["browser_data"], output: ["browser_data"] },
-    artifactKinds: []
-  }),
-  tool({
-    name: "browser.dropdown.select",
-    title: "Select dropdown option",
-    description: "Select and verify a native or ARIA dropdown option, opening custom controls when needed.",
-    context: "target",
-    inputSchema: objectSchema({
-      target: elementAddressSchema,
-      choice: dropdownChoiceSchema,
-      observationLimit: integerSchema({ minimum: 1, maximum: OBSERVATION_V1_LIMITS.maxElements })
-    }, ["target", "choice"]),
-    outputSchema: observationOutput,
-    requiredCapabilities: ["action.input", "observation.read"],
-    mutating: true,
-    idempotency: "non_idempotent",
-    cancellation: "best_effort",
-    sensitivity: { input: ["browser_data"], output: ["browser_data", "credential"] },
-    artifactKinds: []
-  }),
-  tool({
-    name: "browser.click",
-    title: "Click element",
-    description: "Click an Observation ref or viewport coordinates after interactability checks.",
-    context: "target",
-    inputSchema: objectSchema({
-      target: {
-        oneOf: [
-          objectSchema({ observationId: opaqueIdSchema, ref: integerSchema({ minimum: 1 }) }, ["observationId", "ref"]),
-          objectSchema({ x: numberSchema(), y: numberSchema() }, ["x", "y"])
-        ]
-      },
-      button: stringSchema({ enum: ["left", "right"] }),
-      clickCount: integerSchema({ minimum: 1, maximum: 2 }),
-      observationLimit: integerSchema({ minimum: 1, maximum: OBSERVATION_V1_LIMITS.maxElements })
-    }, ["target"]),
-    outputSchema: observationOutput,
-    requiredCapabilities: ["action.input", "observation.read"],
-    mutating: true,
-    idempotency: "non_idempotent",
-    cancellation: "best_effort",
-    sensitivity: { input: ["browser_data"], output: ["browser_data", "credential"] },
-    artifactKinds: []
-  }),
-  tool({
-    name: "browser.type",
-    title: "Type into element",
-    description: "Enter text into an Observation ref and read back the effective value.",
-    context: "target",
-    inputSchema: objectSchema({
-      observationId: opaqueIdSchema,
-      ref: integerSchema({ minimum: 1 }),
-      text: boundedText,
-      clear: booleanSchema(),
-      submit: booleanSchema(),
-      verification: stringSchema({ enum: ["report", "require_exact"] }),
-      observationLimit: integerSchema({ minimum: 1, maximum: OBSERVATION_V1_LIMITS.maxElements })
-    }, ["observationId", "ref", "text"]),
-    outputSchema: observationOutput,
-    requiredCapabilities: ["action.input", "observation.read"],
-    mutating: true,
-    idempotency: "non_idempotent",
-    cancellation: "best_effort",
-    sensitivity: { input: ["browser_data", "credential"], output: ["browser_data", "credential"] },
-    artifactKinds: []
-  }),
-  tool({
-    name: "browser.keyboard",
-    title: "Type with keyboard",
-    description: "Dispatch keyboard input to the currently focused page control.",
-    context: "target",
-    inputSchema: objectSchema({
-      text: boundedText,
-      clear: booleanSchema(),
-      submit: booleanSchema(),
-      delayMs: integerSchema({ minimum: 0, maximum: 6e4 }),
-      focusSelector: boundedSelector,
-      verification: stringSchema({ enum: ["report", "require_exact"] }),
-      observationLimit: integerSchema({ minimum: 1, maximum: OBSERVATION_V1_LIMITS.maxElements })
-    }, ["text"]),
-    outputSchema: observationOutput,
-    requiredCapabilities: ["action.input", "observation.read"],
-    mutating: true,
-    idempotency: "non_idempotent",
-    cancellation: "best_effort",
-    sensitivity: { input: ["browser_data", "credential"], output: ["browser_data", "credential"] },
-    artifactKinds: []
-  }),
-  tool({
-    name: "browser.press",
-    title: "Press key",
-    description: "Dispatch a key or key combination and report bounded observable effects.",
-    context: "target",
-    inputSchema: objectSchema({
-      key: stringSchema({ minLength: 1, maxLength: 128 }),
-      observationLimit: integerSchema({ minimum: 1, maximum: OBSERVATION_V1_LIMITS.maxElements })
-    }, ["key"]),
-    outputSchema: observationOutput,
-    requiredCapabilities: ["action.input", "observation.read"],
-    mutating: true,
-    idempotency: "non_idempotent",
-    cancellation: "best_effort",
-    sensitivity: { input: ["browser_data"], output: ["browser_data", "credential"] },
-    artifactKinds: []
-  }),
-  tool({
-    name: "browser.capture",
-    title: "Capture screenshot",
-    description: "Capture the viewport, full page, or a selected element as protected Artifacts.",
-    context: "target",
-    inputSchema: objectSchema({
-      fullPage: booleanSchema(),
-      selector: boundedSelector,
-      includeOriginal: booleanSchema(),
-      annotations: objectSchema({
-        observationId: opaqueIdSchema,
-        refs: arraySchema(integerSchema({ minimum: 1 }), { maxItems: 200, uniqueItems: true })
-      }, ["observationId"])
-    }),
-    outputSchema: artifactOutput,
-    requiredCapabilities: ["artifact.read"],
-    mutating: false,
-    idempotency: "idempotent",
-    cancellation: "best_effort",
-    sensitivity: { input: ["browser_data"], output: ["browser_data"] },
-    artifactKinds: ["screenshot", "screenshot_preview"]
-  }),
-  tool({
-    name: "browser.pdf",
-    title: "Capture PDF",
-    description: "Print the controlled target to a protected PDF Artifact.",
-    context: "target",
-    inputSchema: objectSchema({ landscape: booleanSchema() }),
-    outputSchema: artifactOutput,
-    requiredCapabilities: ["artifact.read"],
-    mutating: false,
-    idempotency: "idempotent",
-    cancellation: "best_effort",
-    sensitivity: { input: [], output: ["browser_data"] },
-    artifactKinds: ["pdf"]
-  }),
-  tool({
-    name: "browser.upload",
-    title: "Upload file",
-    description: "Assign a client-authorized local file and verify the browser selection.",
-    context: "target",
-    inputSchema: {
-      oneOf: [
-        objectSchema({
-          artifactId: sensitive(opaqueIdSchema, "user_file"),
-          observationId: opaqueIdSchema,
-          ref: integerSchema({ minimum: 1 }),
-          observationLimit: integerSchema({ minimum: 1, maximum: OBSERVATION_V1_LIMITS.maxElements })
-        }, ["artifactId", "observationId", "ref"]),
-        objectSchema({
-          artifactId: sensitive(opaqueIdSchema, "user_file"),
-          inputIndex: integerSchema({ minimum: 1 }),
-          observationLimit: integerSchema({ minimum: 1, maximum: OBSERVATION_V1_LIMITS.maxElements })
-        }, ["artifactId", "inputIndex"]),
-        objectSchema({
-          artifactId: sensitive(opaqueIdSchema, "user_file"),
-          observationLimit: integerSchema({ minimum: 1, maximum: OBSERVATION_V1_LIMITS.maxElements })
-        }, ["artifactId"])
-      ]
-    },
-    outputSchema: observationOutput,
-    requiredCapabilities: ["action.input", "artifact.read", "observation.read"],
-    mutating: true,
-    idempotency: "non_idempotent",
-    cancellation: "best_effort",
-    sensitivity: { input: ["user_file"], output: ["browser_data", "credential"] },
-    artifactKinds: []
-  }),
-  tool({
-    name: "browser.tabs.list",
-    title: "List browser tabs",
-    description: "List ManagedTabSet targets and all eligible user tabs in the connected browser.",
-    context: "workspace",
-    inputSchema: objectSchema({
-      scope: stringSchema({ enum: ["all", "managed_only", "user_tabs"] })
-    }),
-    outputSchema: resultSchema("workspace", {
-      targets: arraySchema(objectSchema({
-        targetId: opaqueIdSchema,
-        profileContextId: opaqueIdSchema,
-        title: sensitive(stringSchema({ maxLength: 4096 }), "browser_data"),
-        url: boundedUrl,
-        active: booleanSchema(),
-        origin: stringSchema({ enum: ["managed", "managed_popup", "user_tab"] }),
-        managedTabSetId: opaqueIdSchema,
-        controlState: stringSchema({ enum: ["available", "controlled", "busy"] })
-      }, ["targetId", "title", "url", "active", "origin", "controlState"]))
-    }, ["targets"]),
-    requiredCapabilities: ["browser.control"],
-    mutating: false,
-    idempotency: "read_only",
-    cancellation: "not_applicable",
-    sensitivity: { input: [], output: ["browser_data"] },
-    artifactKinds: []
-  }),
-  tool({
-    name: "browser.tabs.switch",
-    title: "Switch tab",
-    description: "Set a managed or user tab as the active controlled target for the current Lease.",
-    context: "workspace",
-    inputSchema: objectSchema({ targetId: opaqueIdSchema }, ["targetId"]),
-    outputSchema: resultSchema("target"),
-    requiredCapabilities: ["browser.control"],
-    mutating: true,
-    idempotency: "idempotent",
-    cancellation: "before_dispatch",
-    sensitivity: { input: ["browser_data"], output: ["browser_data"] },
-    artifactKinds: []
-  }),
-  tool({
-    name: "browser.tabs.close",
-    title: "Close tab",
-    description: "Close one explicitly addressed managed or user tab.",
-    context: "target",
-    inputSchema: emptyInput,
-    outputSchema: resultSchema("workspace", { closedTargetId: opaqueIdSchema }, ["closedTargetId"]),
-    requiredCapabilities: ["browser.control"],
-    mutating: true,
-    idempotency: "idempotent",
-    cancellation: "before_dispatch",
-    sensitivity: { input: [], output: ["browser_data"] },
-    artifactKinds: []
-  }),
-  tool({
-    name: "browser.tabs.release",
-    title: "Release tab control",
-    description: "Relinquish this Lease control of one tab without closing it.",
-    context: "target",
-    inputSchema: emptyInput,
-    outputSchema: resultSchema("target", { released: booleanSchema() }, ["released"]),
-    requiredCapabilities: ["browser.control"],
-    mutating: true,
-    idempotency: "idempotent",
-    cancellation: "before_dispatch",
-    sensitivity: { input: [], output: ["browser_data"] },
-    artifactKinds: []
-  }),
-  tool({
-    name: "browser.frames.list",
-    title: "List frames",
-    description: "List frames and CDP sessions belonging to the controlled target.",
-    context: "target",
-    inputSchema: emptyInput,
-    outputSchema: resultSchema("target", {
-      frames: arraySchema(objectSchema({
-        frameId: opaqueIdSchema,
-        parentFrameId: opaqueIdSchema,
-        url: boundedUrl,
-        name: sensitive(stringSchema({ maxLength: 4096 }), "browser_data")
-      }, ["frameId", "url", "name"]))
-    }, ["frames"]),
-    requiredCapabilities: ["observation.read"],
-    mutating: false,
-    idempotency: "read_only",
-    cancellation: "not_applicable",
-    sensitivity: { input: [], output: ["browser_data"] },
-    artifactKinds: []
-  }),
-  tool({
-    name: "browser.frames.switch",
-    title: "Switch frame",
-    description: "Set the active frame for the current Lease after target-access validation.",
-    context: "target",
-    inputSchema: {
-      oneOf: [
-        objectSchema({ frameId: opaqueIdSchema }, ["frameId"]),
-        objectSchema({ top: booleanSchema({ const: true }) }, ["top"])
-      ]
-    },
-    outputSchema: resultSchema("target", { frameId: opaqueIdSchema }, ["frameId"]),
-    requiredCapabilities: ["browser.control"],
-    mutating: true,
-    idempotency: "idempotent",
-    cancellation: "before_dispatch",
-    sensitivity: { input: ["browser_data"], output: ["browser_data"] },
-    artifactKinds: []
-  }),
-  tool({
-    name: "browser.dialogs.list",
-    title: "List dialogs",
-    description: "List pending dialogs for controlled targets without auto-accepting them.",
-    context: "workspace",
-    inputSchema: emptyInput,
-    outputSchema: resultSchema("workspace", {
-      dialogs: arraySchema(objectSchema({
-        dialogId: opaqueIdSchema,
-        targetId: opaqueIdSchema,
-        type: stringSchema({ enum: ["alert", "confirm", "prompt", "beforeunload"] }),
-        message: sensitive(stringSchema({ maxLength: 65536 }), "browser_data")
-      }, ["dialogId", "targetId", "type", "message"]))
-    }, ["dialogs"]),
-    requiredCapabilities: ["event.read"],
-    mutating: false,
-    idempotency: "read_only",
-    cancellation: "not_applicable",
-    sensitivity: { input: [], output: ["browser_data"] },
-    artifactKinds: []
-  }),
-  tool({
-    name: "browser.dialogs.respond",
-    title: "Respond to dialog",
-    description: "Explicitly accept or dismiss a pending dialog on a controlled target.",
-    context: "target",
-    inputSchema: objectSchema({
-      dialogId: opaqueIdSchema,
-      action: stringSchema({ enum: ["accept", "dismiss"] }),
-      promptText: sensitive(stringSchema({ maxLength: 65536 }), "browser_data", "credential")
-    }, ["dialogId", "action"]),
-    outputSchema: resultSchema("target", { dialogId: opaqueIdSchema, action: stringSchema({ enum: ["accept", "dismiss"] }) }, ["dialogId", "action"]),
-    requiredCapabilities: ["action.input"],
-    mutating: true,
-    idempotency: "idempotent",
-    cancellation: "before_dispatch",
-    sensitivity: { input: ["browser_data", "credential"], output: ["browser_data"] },
-    artifactKinds: []
-  }),
-  tool({
-    name: "browser.auth.set",
-    title: "Set HTTP auth",
-    description: "Set Workspace-scoped HTTP authentication credentials.",
-    context: "workspace",
-    inputSchema: objectSchema({
-      username: sensitive(stringSchema({ minLength: 1, maxLength: 4096 }), "credential"),
-      password: sensitive(stringSchema({ maxLength: 65536 }), "credential")
-    }, ["username", "password"]),
-    outputSchema: resultSchema("workspace", { configured: booleanSchema({ const: true }) }, ["configured"]),
-    requiredCapabilities: ["auth.manage"],
-    mutating: true,
-    idempotency: "idempotent",
-    cancellation: "before_dispatch",
-    sensitivity: { input: ["credential"], output: [] },
-    artifactKinds: []
-  }),
-  tool({
-    name: "browser.auth.clear",
-    title: "Clear HTTP auth",
-    description: "Remove Workspace-scoped HTTP authentication credentials.",
-    context: "workspace",
-    inputSchema: emptyInput,
-    outputSchema: resultSchema("workspace", { configured: booleanSchema({ const: false }) }, ["configured"]),
-    requiredCapabilities: ["auth.manage"],
-    mutating: true,
-    idempotency: "idempotent",
-    cancellation: "before_dispatch",
-    sensitivity: { input: [], output: [] },
-    artifactKinds: []
-  }),
-  tool({
-    name: "browser.cookies.list",
-    title: "List cookies",
-    description: "List cookies available to a controlled target with sensitivity metadata.",
-    context: "target",
-    inputSchema: objectSchema({
-      domain: sensitive(stringSchema({ minLength: 1, maxLength: 2048 }), "browser_data")
-    }),
-    outputSchema: resultSchema("target", {
-      cookies: arraySchema(objectSchema({
-        name: sensitive(stringSchema({ maxLength: 4096 }), "browser_data"),
-        value: sensitive(stringSchema({ maxLength: 1e6 }), "credential"),
-        domain: sensitive(stringSchema({ maxLength: 2048 }), "browser_data"),
-        path: sensitive(stringSchema({ maxLength: 4096 }), "browser_data"),
-        httpOnly: booleanSchema(),
-        secure: booleanSchema(),
-        expires: numberSchema()
-      }, ["name", "value", "domain", "path", "httpOnly", "secure", "expires"]))
-    }, ["cookies"]),
-    requiredCapabilities: ["cookies.read"],
-    mutating: false,
-    idempotency: "read_only",
-    cancellation: "best_effort",
-    sensitivity: { input: ["browser_data"], output: ["browser_data", "credential"] },
-    artifactKinds: []
-  }),
-  tool({
-    name: "browser.network.requests",
-    title: "List network requests",
-    description: "List bounded Workspace-scoped network request metadata.",
-    context: "workspace",
-    inputSchema: objectSchema({
-      limit: integerSchema({ minimum: 1, maximum: 1e3 }),
-      after: integerSchema({ minimum: 0 }),
-      url: sensitive(stringSchema({ maxLength: 16384 }), "browser_data"),
-      method: stringSchema({ maxLength: 32 }),
-      status: stringSchema({ maxLength: 16 }),
-      type: arraySchema(stringSchema({ minLength: 1, maxLength: 128 }), { uniqueItems: true })
-    }),
-    outputSchema: resultSchema("workspace", {
-      requests: arraySchema(objectSchema({
-        requestId: opaqueIdSchema,
-        sequence: integerSchema({ minimum: 1 }),
-        method: stringSchema({ maxLength: 32 }),
-        url: boundedUrl,
-        status: integerSchema({ minimum: 100, maximum: 999 }),
-        type: stringSchema({ maxLength: 128 }),
-        size: integerSchema({ minimum: 0 }),
-        durationMs: numberSchema({ minimum: 0 }),
-        error: sensitive(stringSchema({ maxLength: 4096 }), "browser_data")
-      }, ["requestId", "sequence", "method", "url", "type"])),
-      nextCursor: integerSchema({ minimum: 0 }),
-      truncated: booleanSchema()
-    }, ["requests", "nextCursor", "truncated"]),
-    requiredCapabilities: ["network.observe"],
-    mutating: false,
-    idempotency: "read_only",
-    cancellation: "best_effort",
-    sensitivity: { input: ["browser_data"], output: ["browser_data"] },
-    artifactKinds: []
-  }),
-  tool({
-    name: "browser.network.request",
-    title: "Read network request",
-    description: "Read bounded details for one Workspace-scoped request.",
-    context: "workspace",
-    inputSchema: objectSchema({ requestId: opaqueIdSchema, includeBody: booleanSchema() }, ["requestId"]),
-    outputSchema: resultSchema("workspace", {
-      request: networkRequestDetailSchema,
-      body: sensitive(stringSchema({ maxLength: 1e6 }), "browser_data", "credential"),
-      bodyEncoding: stringSchema({ enum: ["utf8", "base64"] }),
-      mimeType: stringSchema({ maxLength: 256 }),
-      bodyTruncated: booleanSchema()
-    }, ["request", "bodyTruncated"]),
-    requiredCapabilities: ["network.observe"],
-    mutating: false,
-    idempotency: "read_only",
-    cancellation: "best_effort",
-    sensitivity: { input: ["browser_data"], output: ["browser_data", "credential"] },
-    artifactKinds: []
-  }),
-  tool({
-    name: "browser.network.clear",
-    title: "Clear network journal",
-    description: "Clear captured request metadata for the current Workspace.",
-    context: "workspace",
-    inputSchema: emptyInput,
-    outputSchema: resultSchema("workspace", { cleared: booleanSchema({ const: true }) }, ["cleared"]),
-    requiredCapabilities: ["network.observe"],
-    mutating: true,
-    idempotency: "idempotent",
-    cancellation: "before_dispatch",
-    sensitivity: { input: [], output: [] },
-    artifactKinds: []
-  }),
-  tool({
-    name: "browser.network.rules.list",
-    title: "List network rules",
-    description: "List interception rules owned by the current Workspace.",
-    context: "workspace",
-    inputSchema: emptyInput,
-    outputSchema: resultSchema("workspace", {
-      rules: arraySchema(networkRuleSchema)
-    }, ["rules"]),
-    requiredCapabilities: ["network.observe"],
-    mutating: false,
-    idempotency: "read_only",
-    cancellation: "not_applicable",
-    sensitivity: { input: [], output: ["browser_data", "credential"] },
-    artifactKinds: []
-  }),
-  tool({
-    name: "browser.network.rules.add",
-    title: "Add network rule",
-    description: "Add a Workspace-scoped block, mock, or header rule.",
-    context: "workspace",
-    inputSchema: {
-      oneOf: [
-        objectSchema({ type: stringSchema({ const: "block" }), pattern: boundedUrl }, ["type", "pattern"]),
-        objectSchema({
-          type: stringSchema({ const: "mock" }),
-          pattern: boundedUrl,
-          status: integerSchema({ minimum: 100, maximum: 999 }),
-          headers: arraySchema(headerSchema, { maxItems: 256 }),
-          body: sensitive(stringSchema({ maxLength: 1e6 }), "browser_data", "credential")
-        }, ["type", "pattern"]),
-        objectSchema({
-          type: stringSchema({ const: "headers" }),
-          pattern: boundedUrl,
-          headers: arraySchema(headerSchema, { minItems: 1, maxItems: 256 })
-        }, ["type", "pattern", "headers"])
-      ]
-    },
-    outputSchema: resultSchema("workspace", { ruleId: opaqueIdSchema }, ["ruleId"]),
-    requiredCapabilities: ["network.modify"],
-    mutating: true,
-    idempotency: "non_idempotent",
-    cancellation: "before_dispatch",
-    sensitivity: { input: ["browser_data", "credential"], output: ["browser_data"] },
-    artifactKinds: []
-  }),
-  tool({
-    name: "browser.network.rules.remove",
-    title: "Remove network rule",
-    description: "Remove one owned interception rule or all rules in the Workspace.",
-    context: "workspace",
-    inputSchema: {
-      oneOf: [
-        objectSchema({ ruleId: opaqueIdSchema }, ["ruleId"]),
-        objectSchema({ all: booleanSchema({ const: true }) }, ["all"])
-      ]
-    },
-    outputSchema: resultSchema("workspace", { removed: integerSchema({ minimum: 0 }) }, ["removed"]),
-    requiredCapabilities: ["network.modify"],
-    mutating: true,
-    idempotency: "idempotent",
-    cancellation: "before_dispatch",
-    sensitivity: { input: ["browser_data"], output: [] },
-    artifactKinds: []
-  }),
-  tool({
-    name: "browser.eval",
-    title: "Evaluate JavaScript",
-    description: "Evaluate JavaScript in a controlled target when the Agent host exposes developer capability.",
-    context: "target",
-    inputSchema: objectSchema({ expression: boundedText, awaitPromise: booleanSchema() }, ["expression"]),
-    outputSchema: resultSchema("target", {
-      value: sensitive({}, "browser_data", "credential"),
-      truncated: booleanSchema()
-    }, ["value", "truncated"]),
-    requiredCapabilities: ["developer.eval"],
-    mutating: true,
-    idempotency: "non_idempotent",
-    cancellation: "best_effort",
-    sensitivity: { input: ["browser_data", "credential"], output: ["browser_data", "credential"] },
-    artifactKinds: []
-  })
-];
-var toolsByName = new Map(TOOL_DEFINITIONS.map((definition) => [definition.name, definition]));
-function schemaSensitivities(schema, result = /* @__PURE__ */ new Set()) {
-  for (const value of schema["x-browser-pilot-sensitivity"] ?? []) result.add(value);
-  for (const property of Object.values(schema.properties ?? {})) schemaSensitivities(property, result);
-  for (const alternative of schema.oneOf ?? []) schemaSensitivities(alternative, result);
-  if (schema.items) schemaSensitivities(schema.items, result);
-  if (schema.additionalProperties && typeof schema.additionalProperties === "object") {
-    schemaSensitivities(schema.additionalProperties, result);
-  }
-  return result;
-}
-function assertToolManifest(definitions = TOOL_DEFINITIONS) {
-  const names = /* @__PURE__ */ new Set();
-  const knownCapabilities = new Set(CAPABILITIES);
-  for (const definition of definitions) {
-    if (!/^[a-z][a-z0-9]*(?:[._][a-z][a-z0-9]*)+$/.test(definition.name)) {
-      throw new Error(`Invalid tool name: ${definition.name}`);
-    }
-    if (names.has(definition.name)) throw new Error(`Duplicate tool name: ${definition.name}`);
-    names.add(definition.name);
-    for (const capability of definition.requiredCapabilities) {
-      if (!knownCapabilities.has(capability)) {
-        throw new Error(`Tool ${definition.name} references unknown capability ${capability}`);
-      }
-    }
-    if (!definition.mutating && definition.idempotency === "non_idempotent") {
-      throw new Error(`Read-only tool ${definition.name} cannot be non-idempotent`);
-    }
-    if (definition.mutating && definition.cancellation === "not_applicable") {
-      throw new Error(`Mutating tool ${definition.name} must declare cancellation semantics`);
-    }
-    for (const direction of ["input", "output"]) {
-      const sensitivity = definition.sensitivity[direction];
-      if (new Set(sensitivity).size !== sensitivity.length) {
-        throw new Error(`Tool ${definition.name} has duplicate ${direction} sensitivity`);
-      }
-      for (const value of sensitivity) {
-        if (!SENSITIVITIES.includes(value)) {
-          throw new Error(`Tool ${definition.name} references unknown sensitivity ${value}`);
-        }
-      }
-      for (const value of schemaSensitivities(
-        direction === "input" ? definition.inputSchema : definition.outputSchema
-      )) {
-        if (!SENSITIVITIES.includes(value)) {
-          throw new Error(
-            `Tool ${definition.name} ${direction} schema contains unknown sensitivity ${value}`
-          );
-        }
-        if (!sensitivity.includes(value)) {
-          throw new Error(
-            `Tool ${definition.name} ${direction} schema marks ${value} without declaring it`
-          );
-        }
-      }
-    }
-    assertSchemaDefinition(definition.inputSchema, `${definition.name}.inputSchema`);
-    assertSchemaDefinition(definition.outputSchema, `${definition.name}.outputSchema`);
-  }
-}
-assertToolManifest();
-
-// src/services/command-runtime.ts
-import { randomUUID as randomUUID2 } from "crypto";
-
-// src/services/event-journal.ts
-import { randomUUID as randomUUID3 } from "crypto";
-
-// src/services/broker-runtime.ts
-var DEFAULT_PROTOCOL_LIMITS = {
-  maxMessageBytes: 1024 * 1024,
-  maxResultBytes: 4 * 1024 * 1024,
-  maxArtifactBytes: 100 * 1024 * 1024,
-  eventJournalSize: 1e3
-};
-
-// src/bridge/stdio-bridge.ts
-function isIncomingCall(message) {
-  return "method" in message;
-}
-function isOutOfBandControl(message) {
-  if (message.method === "commands/get" || message.method === "commands/cancel") return true;
-  if (message.method !== "tools/call" || !message.params || typeof message.params !== "object") return false;
-  if (Array.isArray(message.params)) return false;
-  const name = message.params.name;
-  return name === "browser.dialogs.list" || name === "browser.dialogs.respond";
-}
-function errorResponse(id, error) {
-  const stable = asBrowserPilotError(error);
-  return { jsonrpc: "2.0", id, error: stable.toJsonRpcError() };
-}
-async function writeLine(output, value, maxResultBytes) {
-  let serialized = JSON.stringify(value);
-  if (Buffer.byteLength(serialized, "utf8") > maxResultBytes) {
-    if (!("id" in value)) return;
-    serialized = JSON.stringify(errorResponse(value.id, new BrowserPilotError(
-      "result_too_large",
-      `Protocol result exceeds ${maxResultBytes} bytes`,
-      { context: { maxResultBytes } }
-    )));
-  }
-  if (output.destroyed || !output.writable) throw new Error("Protocol output is closed");
-  if (!output.write(`${serialized}
-`)) await once(output, "drain");
-}
-function negotiatedTransportLimits(value, ceilings) {
-  if (!value || typeof value !== "object" || Array.isArray(value)) return void 0;
-  const limits = value.limits;
-  if (!limits || typeof limits !== "object" || Array.isArray(limits)) return void 0;
-  if (!Number.isSafeInteger(limits.maxMessageBytes) || !Number.isSafeInteger(limits.maxResultBytes) || limits.maxMessageBytes <= 0 || limits.maxResultBytes <= 0) return void 0;
-  return {
-    maxMessageBytes: Math.min(limits.maxMessageBytes, ceilings.maxMessageBytes),
-    maxResultBytes: Math.min(limits.maxResultBytes, ceilings.maxResultBytes)
-  };
-}
-function decodeLine(bytes) {
-  try {
-    return new TextDecoder("utf-8", { fatal: true }).decode(bytes);
-  } catch (cause) {
-    throw new BrowserPilotError("invalid_argument", "Protocol message is not valid UTF-8", {
-      rpcCode: -32700,
-      cause
-    });
-  }
-}
-async function runStdioBridge(options) {
-  const bridgeSessionId = options.bridgeSessionId ?? `bridge:${randomUUID5()}`;
-  const ceilings = {
-    maxMessageBytes: options.maxMessageBytes ?? DEFAULT_PROTOCOL_LIMITS.maxMessageBytes,
-    maxResultBytes: options.maxResultBytes ?? DEFAULT_PROTOCOL_LIMITS.maxResultBytes
-  };
-  let maxMessageBytes = ceilings.maxMessageBytes;
-  let maxResultBytes = ceilings.maxResultBytes;
-  const maxPendingCalls = options.maxPendingCalls ?? 256;
-  const maxOutOfBandCalls = options.maxOutOfBandCalls ?? 16;
-  if (!Number.isSafeInteger(maxPendingCalls) || maxPendingCalls <= 0 || !Number.isSafeInteger(maxOutOfBandCalls) || maxOutOfBandCalls <= 0) throw new Error("Bridge in-flight call limits must be positive integers");
-  let pending = Buffer.alloc(0);
-  let reason = "eof";
-  let exitCode = 0;
-  let stopped = false;
-  let framingFailed = false;
-  let outputTail = Promise.resolve();
-  let normalTail = Promise.resolve();
-  let initialization;
-  let notificationController;
-  let notificationTask;
-  const inFlight = /* @__PURE__ */ new Set();
-  let pendingCalls = 0;
-  let outOfBandCalls = 0;
-  const queueWrite = (value) => {
-    const write = outputTail.then(() => writeLine(options.output, value, maxResultBytes));
-    outputTail = write.catch(() => {
-    });
-    return write;
-  };
-  const failFraming = async (error) => {
-    exitCode = 1;
-    reason = "protocol_error";
-    stopped = true;
-    framingFailed = true;
-    await queueWrite(errorResponse(null, error));
-  };
-  const track = (task, outOfBand) => {
-    inFlight.add(task);
-    if (outOfBand) outOfBandCalls += 1;
-    else pendingCalls += 1;
-    const finished = () => {
-      inFlight.delete(task);
-      if (outOfBand) outOfBandCalls -= 1;
-      else pendingCalls -= 1;
-    };
-    void task.then(finished, finished);
-  };
-  const startNotifications = () => {
-    if (notificationTask || !options.backend.notifications) return;
-    notificationController = new AbortController();
-    notificationTask = (async () => {
-      for await (const notification of options.backend.notifications(
-        bridgeSessionId,
-        notificationController.signal
-      )) {
-        if (notificationController.signal.aborted || stopped) break;
-        await queueWrite(notification);
-      }
-    })().catch(() => {
-      if (notificationController?.signal.aborted) return;
-      stopped = true;
-      reason = "output_closed";
-      exitCode = 1;
-      options.input.destroy();
-    });
-  };
-  const processLine = async (rawLine) => {
-    const line = rawLine.at(-1) === 13 ? rawLine.subarray(0, -1) : rawLine;
-    let message;
-    try {
-      message = parseJsonRpcMessage(decodeLine(line), maxMessageBytes);
-    } catch (error) {
-      await failFraming(error);
-      return;
-    }
-    if (!isIncomingCall(message)) {
-      await failFraming(invalidArgument("Bridge accepts JSON-RPC requests and notifications only", void 0, -32600));
-      return;
-    }
-    const requestId = "id" in message ? message.id : void 0;
-    const outOfBand = isOutOfBandControl(message);
-    const saturated = outOfBand ? outOfBandCalls >= maxOutOfBandCalls : pendingCalls >= maxPendingCalls;
-    if (saturated) {
-      if (requestId !== void 0) {
-        await queueWrite(errorResponse(requestId, new BrowserPilotError(
-          "result_too_large",
-          `Bridge ${outOfBand ? "control" : "request"} queue is full`,
-          {
-            retryable: true,
-            context: {
-              limit: outOfBand ? maxOutOfBandCalls : maxPendingCalls,
-              queue: outOfBand ? "control" : "request"
-            }
-          }
-        )));
-      }
-      return;
-    }
-    const dispatch = async () => {
-      try {
-        const result = await options.backend.call(bridgeSessionId, message.method, message.params);
-        if (requestId !== void 0 && reason !== "protocol_error") {
-          await queueWrite({ jsonrpc: "2.0", id: requestId, result });
-        }
-        if (message.method === "initialize" && reason !== "protocol_error") {
-          const negotiated = negotiatedTransportLimits(result, ceilings);
-          if (negotiated) {
-            maxMessageBytes = negotiated.maxMessageBytes;
-            maxResultBytes = negotiated.maxResultBytes;
-          }
-          startNotifications();
-        }
-      } catch (error) {
-        if (requestId !== void 0 && reason !== "protocol_error") {
-          try {
-            await queueWrite(errorResponse(requestId, error));
-          } catch {
-            stopped = true;
-            reason = "output_closed";
-            exitCode = 1;
-          }
-        }
-      }
-    };
-    const task = outOfBand ? (initialization ?? Promise.resolve()).then(dispatch) : normalTail.then(dispatch);
-    if (!outOfBand) normalTail = task.catch(() => {
-    });
-    if (message.method === "initialize") initialization = task.catch(() => {
-    });
-    track(task, outOfBand);
-    if (message.method === "shutdown") {
-      stopped = true;
-      reason = "shutdown";
+          actionRequired: true
+        }
+      });
     }
-  };
-  try {
-    for await (const value of options.input) {
-      const chunk = Buffer.isBuffer(value) ? value : Buffer.from(value);
-      let offset = 0;
-      while (!stopped && offset < chunk.length) {
-        const newline = chunk.indexOf(10, offset);
-        if (newline === -1) {
-          const remaining = chunk.subarray(offset);
-          if (pending.length + remaining.length > maxMessageBytes) {
-            await failFraming(new BrowserPilotError(
-              "result_too_large",
-              `Protocol message exceeds ${maxMessageBytes} bytes`,
-              { context: { maxMessageBytes }, rpcCode: -32600 }
-            ));
-            break;
+    removeStaleBrokerFilesSync();
+    const candidates = await discoverBrowserCandidates();
+    const filter = browserFilter?.toLowerCase();
+    const matches = candidates.filter(({ candidate }) => !filter || [candidate.id, candidate.product, candidate.channel].some((value) => value?.toLowerCase().includes(filter)));
+    if (browserFilter && matches.length === 0) {
+      throw new BrowserPilotError(
+        "browser_not_found",
+        "No installed supported browser matches the requested selection.",
+        {
+          remediation: {
+            code: "select_supported_browser",
+            message: "Run browser discovery and select one of the returned browser IDs or product names.",
+            actionRequired: true
           }
-          pending = pending.length === 0 ? Buffer.from(remaining) : Buffer.concat([pending, remaining]);
-          offset = chunk.length;
-          continue;
         }
-        const part = chunk.subarray(offset, newline);
-        if (pending.length + part.length > maxMessageBytes) {
-          await failFraming(new BrowserPilotError(
-            "result_too_large",
-            `Protocol message exceeds ${maxMessageBytes} bytes`,
-            { context: { maxMessageBytes }, rpcCode: -32600 }
-          ));
-          break;
-        }
-        const line = pending.length === 0 ? part : Buffer.concat([pending, part]);
-        pending = Buffer.alloc(0);
-        offset = newline + 1;
-        await processLine(line);
-        if (initialization) await initialization;
-      }
-      if (stopped) break;
-    }
-    if (!stopped && pending.length > 0) await processLine(pending);
-    notificationController?.abort();
-    await notificationTask;
-    if (!framingFailed) await Promise.allSettled([...inFlight]);
-    await outputTail;
-  } catch {
-    if (!stopped) {
-      reason = "output_closed";
-      exitCode = 1;
+      );
     }
+    const selected = matches.find((browser) => browser.endpoint !== void 0) ?? matches[0] ?? null;
+    return await startDaemon(selected);
   } finally {
-    notificationController?.abort();
-    await notificationTask;
-    try {
-      await options.backend.disconnect(bridgeSessionId);
-    } catch {
-    }
+    startupLock.release();
   }
-  return { exitCode, reason };
 }
 
+// src/protocol/model.ts
+var CAPABILITIES = [
+  "browser.discovery",
+  "browser.control",
+  "workspace.manage",
+  "observation.read",
+  "action.input",
+  "artifact.read",
+  "event.read",
+  "network.observe",
+  "network.modify",
+  "auth.manage",
+  "cookies.read",
+  "developer.eval"
+];
+var OBSERVATION_V1_LIMITS = {
+  defaultElements: 50,
+  maxElements: 1e4,
+  maxTitleCharacters: 4096,
+  maxUrlCharacters: 16384,
+  maxElementNameCharacters: 4096,
+  maxElementValueCharacters: 65536,
+  maxTextCharacters: 1e6,
+  maxTreeDepth: 128,
+  maxSerializedBytes: 2 * 1024 * 1024,
+  ttlMs: 5 * 6e4,
+  maxStoredObservations: 2048
+};
+
 // src/compatibility-broker-client.ts
-import { randomUUID as randomUUID6 } from "crypto";
-var BRIDGE_SESSION_ID = "bridge:browser-pilot-cli";
 var CLIENT_KEY = "browser-pilot-cli";
 var LEASE_TTL_MS = 5 * 6e4;
+function compatibilityIdentity(clientKey, executableVersion) {
+  const principalDigest = createHash4("sha256").update(clientKey).digest("base64url").slice(0, 24);
+  const sessionDigest = createHash4("sha256").update(clientKey).update("\0").update(executableVersion).digest("base64url").slice(0, 24);
+  return {
+    clientSessionId: `client:browser-pilot-cli:${sessionDigest}`,
+    instanceId: `local:browser-pilot-cli:${principalDigest}`
+  };
+}
+function isSelected(target) {
+  return target.selected ?? target.active === true;
+}
 function asRecord(value, label) {
   if (!value || typeof value !== "object" || Array.isArray(value)) {
     throw new BrowserPilotError("internal_error", `${label} returned an invalid result`);
@@ -3226,55 +1167,93 @@ function commandResult(value, method) {
   return asRecord(outcome.result, `${method} result`);
 }
 var CompatibilityBrokerClient = class _CompatibilityBrokerClient {
-  constructor(transport, initialized, workspace, lease) {
+  constructor(transport, clientSessionId, initialized, workspace, lease, invocation) {
     this.transport = transport;
+    this.clientSessionId = clientSessionId;
     this.initialized = initialized;
     this.workspace = workspace;
     this.lease = lease;
+    this.invocation = invocation;
   }
   commandSequence = 0;
-  static async create(transport, executableVersion) {
-    const initialized = asRecord(await transport.brokerCall(BRIDGE_SESSION_ID, "initialize", {
+  static async create(transport, executableVersion, clientKey = CLIENT_KEY, invocation = {}) {
+    const identity = compatibilityIdentity(clientKey, executableVersion);
+    const initialized = asRecord(await transport.brokerCall(identity.clientSessionId, "initialize", {
       client: {
         id: "org.browser-pilot.cli",
         name: "Browser Pilot CLI",
         version: executableVersion,
-        instanceId: "local:one-shot"
+        instanceId: identity.instanceId
       },
-      protocol: { min: { major: 1, minor: 1 }, max: { major: 1, minor: 2 } },
-      requestedCapabilities: [...CAPABILITIES],
-      launchMode: "one-shot"
+      protocol: { min: { major: 1, minor: 1 }, max: { major: 1, minor: 3 } },
+      requestedCapabilities: [...CAPABILITIES]
     }), "initialize");
-    if (initialized.executableVersion !== executableVersion) {
-      throw new BrowserPilotError("protocol_incompatible", "Running Browser Pilot daemon is from another executable version", {
-        remediation: {
-          code: "use_matching_executable_or_isolate",
-          message: "Use the matching Browser Pilot installation, or set BROWSER_PILOT_HOME for a deliberately isolated Broker.",
-          actionRequired: true
-        }
-      });
-    }
-    const created = asRecord(await transport.brokerCall(BRIDGE_SESSION_ID, "workspaces/create", {
-      clientKey: CLIENT_KEY
+    const created = asRecord(await transport.brokerCall(identity.clientSessionId, "workspaces/create", {
+      clientKey
     }), "workspaces/create");
-    const leased = asRecord(await transport.brokerCall(BRIDGE_SESSION_ID, "leases/create", {
+    const leased = asRecord(await transport.brokerCall(identity.clientSessionId, "leases/create", {
       workspaceId: created.workspace.id,
-      clientKey: CLIENT_KEY,
+      clientKey,
       ttlMs: LEASE_TTL_MS
     }), "leases/create");
-    return new _CompatibilityBrokerClient(transport, initialized, created.workspace, leased.lease);
+    return new _CompatibilityBrokerClient(
+      transport,
+      identity.clientSessionId,
+      initialized,
+      created.workspace,
+      leased.lease,
+      invocation
+    );
   }
   async callTool(name, args = {}, targetId) {
     this.commandSequence += 1;
-    return commandResult(await this.transport.brokerCall(BRIDGE_SESSION_ID, "tools/call", {
+    if (this.invocation.signal?.aborted) {
+      throw new BrowserPilotError("command_cancelled", "Command was cancelled before dispatch");
+    }
+    const commandId = this.commandId(this.commandSequence);
+    const request = this.transport.brokerCall(this.clientSessionId, "tools/call", {
       name,
       arguments: args,
       workspaceId: this.workspace.id,
       leaseId: this.lease.id,
       ...targetId ? { targetId } : {},
-      commandId: `command:cli-${process.pid}-${this.commandSequence}-${randomUUID6()}`,
-      deadlineMs: 6e4
-    }), name);
+      commandId,
+      ...this.invocation.requestId ? { idempotencyKey: `cli-request:${this.invocation.requestId}:${this.commandSequence}` } : {},
+      deadlineMs: this.invocation.deadlineMs ?? 6e4
+    });
+    const cancel = () => {
+      void this.transport.brokerCall(this.clientSessionId, "commands/cancel", {
+        commandId,
+        workspaceId: this.workspace.id
+      }).catch(() => {
+      });
+    };
+    this.invocation.signal?.addEventListener("abort", cancel, { once: true });
+    try {
+      return commandResult(await request, name);
+    } finally {
+      this.invocation.signal?.removeEventListener("abort", cancel);
+    }
+  }
+  async listCommands(limit = 20, statuses) {
+    const result = asRecord(await this.transport.brokerCall(this.clientSessionId, "commands/list", {
+      workspaceId: this.workspace.id,
+      limit,
+      ...statuses ? { statuses: [...statuses] } : {}
+    }), "commands/list");
+    return result.commands;
+  }
+  async getCommand(commandId) {
+    return asRecord(await this.transport.brokerCall(this.clientSessionId, "commands/get", {
+      workspaceId: this.workspace.id,
+      commandId
+    }), "commands/get");
+  }
+  async cancelCommand(commandId) {
+    return asRecord(await this.transport.brokerCall(this.clientSessionId, "commands/cancel", {
+      workspaceId: this.workspace.id,
+      commandId
+    }), "commands/cancel");
   }
   async connectBrowser(browserId) {
     const selected = browserId ? this.initialized.browsers.find((candidate) => candidate.id === browserId) : this.initialized.browsers.find((candidate) => candidate.state === "ready") ?? this.initialized.browsers[0];
@@ -3304,6 +1283,16 @@ var CompatibilityBrokerClient = class _CompatibilityBrokerClient {
     }
     return result.profiles;
   }
+  async identifyProfiles(profileContextId, refresh = false) {
+    const result = await this.callTool("browser.profiles.identify", {
+      ...profileContextId ? { profileContextId } : {},
+      ...refresh ? { refresh: true } : {}
+    });
+    if (!Array.isArray(result.profiles)) {
+      throw new BrowserPilotError("internal_error", "browser.profiles.identify returned invalid Profiles");
+    }
+    return result.profiles;
+  }
   async selectProfile(profileContextId) {
     const result = await this.callTool("browser.profiles.select", { profileContextId });
     const profiles = await this.listProfiles();
@@ -3317,11 +1306,11 @@ var CompatibilityBrokerClient = class _CompatibilityBrokerClient {
   }
   async ensureTarget() {
     const targets = await this.listTabs("all");
-    const selected = targets.find((target) => target.active) ?? targets.find((target) => target.origin !== "user_tab");
+    const selected = targets.find(isSelected) ?? targets.find((target) => target.origin !== "user_tab");
     if (selected) {
-      if (!selected.active) {
+      if (!isSelected(selected)) {
         await this.callTool("browser.tabs.switch", { targetId: selected.targetId });
-        selected.active = true;
+        selected.selected = true;
       }
       return selected;
     }
@@ -3329,11 +1318,11 @@ var CompatibilityBrokerClient = class _CompatibilityBrokerClient {
   }
   async ensureManagedTarget() {
     const targets = await this.listTabs("managed_only");
-    const selected = targets.find((target) => target.active) ?? targets[0];
+    const selected = targets.find(isSelected) ?? targets[0];
     if (selected) {
-      if (!selected.active) {
+      if (!isSelected(selected)) {
         await this.callTool("browser.tabs.switch", { targetId: selected.targetId });
-        selected.active = true;
+        selected.selected = true;
       }
       return selected;
     }
@@ -3350,7 +1339,7 @@ var CompatibilityBrokerClient = class _CompatibilityBrokerClient {
       profileContextId: opened.profileContextId,
       title: String(opened.title ?? ""),
       url: String(opened.url),
-      active: true,
+      selected: true,
       origin: "managed",
       controlState: "controlled"
     };
@@ -3363,7 +1352,7 @@ var CompatibilityBrokerClient = class _CompatibilityBrokerClient {
     return result.observationId;
   }
   async importArtifact(path, mimeType) {
-    const result = asRecord(await this.transport.brokerCall(BRIDGE_SESSION_ID, "artifacts/import", {
+    const result = asRecord(await this.transport.brokerCall(this.clientSessionId, "artifacts/import", {
       workspaceId: this.workspace.id,
       leaseId: this.lease.id,
       path,
@@ -3371,8 +1360,19 @@ var CompatibilityBrokerClient = class _CompatibilityBrokerClient {
     }), "artifacts/import");
     return asRecord(result.artifact, "imported Artifact");
   }
+  async listArtifacts(kinds) {
+    const result = asRecord(await this.transport.brokerCall(this.clientSessionId, "artifacts/list", {
+      workspaceId: this.workspace.id,
+      leaseId: this.lease.id,
+      ...kinds ? { kinds: [...kinds] } : {}
+    }), "artifacts/list");
+    if (!Array.isArray(result.artifacts)) {
+      throw new BrowserPilotError("internal_error", "artifacts/list returned invalid Artifacts");
+    }
+    return result.artifacts;
+  }
   async exportArtifact(artifactId, path) {
-    await this.transport.brokerCall(BRIDGE_SESSION_ID, "artifacts/export", {
+    await this.transport.brokerCall(this.clientSessionId, "artifacts/export", {
       workspaceId: this.workspace.id,
       leaseId: this.lease.id,
       artifactId,
@@ -3381,113 +1381,88 @@ var CompatibilityBrokerClient = class _CompatibilityBrokerClient {
     });
   }
   async releaseArtifact(artifactId) {
-    await this.transport.brokerCall(BRIDGE_SESSION_ID, "artifacts/release", {
+    await this.transport.brokerCall(this.clientSessionId, "artifacts/release", {
       workspaceId: this.workspace.id,
       leaseId: this.lease.id,
       artifactId
     });
   }
   async releaseWorkspace() {
-    await this.transport.brokerCall(BRIDGE_SESSION_ID, "workspaces/release", {
+    await this.transport.brokerCall(this.clientSessionId, "workspaces/release", {
       workspaceId: this.workspace.id
     });
   }
+  commandId(sequence) {
+    if (!this.invocation.requestId) {
+      return `command:cli-${process.pid}-${sequence}-${randomUUID2()}`;
+    }
+    const digest = createHash4("sha256").update(this.workspace.clientKey ?? CLIENT_KEY).update("\0").update(this.invocation.requestId).update("\0").update(String(sequence)).digest("base64url").slice(0, 32);
+    return `command:cli-${digest}-${sequence}`;
+  }
 };
 async function validateDaemon(client) {
   const health = await client.healthInfo();
   if (!health.ok) throw new BrowserPilotError("browser_disconnected", "Browser Pilot daemon is unavailable");
-  if (health.brokerProtocol !== 1) {
-    throw new BrowserPilotError("protocol_incompatible", "Running Browser Pilot daemon is from an older executable", {
-      remediation: {
-        code: "use_compatible_executable_or_isolate",
-        message: "Use a compatible Browser Pilot executable, or set BROWSER_PILOT_HOME for a deliberately isolated Broker.",
-        actionRequired: true
-      }
-    });
-  }
-}
-async function validateCompatibilityDaemon(client, executableVersion) {
-  await validateDaemon(client);
-  const health = await client.healthInfo();
-  const requester = createExecutableMetadataSync(
-    executableVersion,
-    publicExecutablePath(import.meta.url)
-  );
-  if (health.executableVersion !== void 0 && health.executableVersion !== requester.version || health.executableIdentity !== void 0 && health.executableIdentity !== requester.identity) {
-    throw new BrowserPilotError("protocol_incompatible", "Running Browser Pilot daemon is from another executable installation", {
+  if (health.brokerProtocol !== BROKER_RPC_VERSION) {
+    throw new BrowserPilotError("protocol_incompatible", "Running Browser Pilot Broker uses an incompatible private transport", {
       context: {
-        brokerExecutableVersion: health.executableVersion,
-        requesterExecutableVersion: requester.version
+        brokerRpcVersion: health.brokerProtocol,
+        requiredBrokerRpcVersion: BROKER_RPC_VERSION,
+        serviceVersion: health.serviceVersion,
+        executableVersion: health.executableVersion
       },
       remediation: {
-        code: "use_matching_executable_or_isolate",
-        message: "Use the matching Browser Pilot installation, or set BROWSER_PILOT_HOME for a deliberately isolated Broker.",
+        code: "stop_incompatible_broker_or_isolate",
+        message: "Stop the running Broker with the Browser Pilot executable that started it, or set BROWSER_PILOT_HOME for a deliberately isolated Broker.",
         actionRequired: true
       }
     });
   }
 }
-async function connectCompatibility(executableVersion, browserFilter) {
+async function connectCompatibility(executableVersion, browserFilter, clientKey = CLIENT_KEY, invocation = {}) {
   const daemon = await connectDaemon(browserFilter);
-  await validateCompatibilityDaemon(daemon, executableVersion);
-  return CompatibilityBrokerClient.create(daemon, executableVersion);
+  await validateDaemon(daemon);
+  return CompatibilityBrokerClient.create(daemon, executableVersion, clientKey, invocation);
 }
-async function resumeCompatibility(executableVersion) {
+async function resumeCompatibility(executableVersion, clientKey = CLIENT_KEY, invocation = {}) {
   if (!isDaemonRunning()) return null;
   const daemon = new DaemonClient();
   try {
-    await validateCompatibilityDaemon(daemon, executableVersion);
-    return await CompatibilityBrokerClient.create(daemon, executableVersion);
+    await validateDaemon(daemon);
+    return await CompatibilityBrokerClient.create(daemon, executableVersion, clientKey, invocation);
   } catch (error) {
     if (error instanceof BrowserPilotError && error.code === "protocol_incompatible") throw error;
     return null;
   }
 }
-async function withCompatibilityTarget(executableVersion, operation) {
-  const client = await resumeCompatibility(executableVersion);
+async function withCompatibilityTarget(executableVersion, operation, clientKey = CLIENT_KEY, invocation = {}) {
+  const client = await resumeCompatibility(executableVersion, clientKey, invocation);
   if (!client) throw new Error("Not connected");
   const target = await client.ensureTarget();
   return operation(client, target);
 }
-async function shutdownCompatibility(executableVersion) {
+async function shutdownCompatibility(executableVersion, clientKey = CLIENT_KEY) {
   if (!isDaemonRunning()) return;
   const daemon = new DaemonClient();
   await validateDaemon(daemon);
-  const health = await daemon.healthInfo();
-  if (!health.ok || !health.brokerProcessIdentity || !health.executableVersion || !health.executableIdentity) {
-    throw new BrowserPilotError("protocol_incompatible", "Running Browser Pilot Broker does not support protected shutdown", {
-      remediation: {
-        code: "use_matching_executable_or_isolate",
-        message: "Use the Browser Pilot installation that started the Broker, or set BROWSER_PILOT_HOME for a deliberately isolated Broker.",
-        actionRequired: true
-      }
-    });
-  }
-  const requester = createExecutableMetadataSync(
-    executableVersion,
-    publicExecutablePath(import.meta.url)
-  );
-  if (requester.version !== health.executableVersion || requester.identity !== health.executableIdentity) {
-    throw new BrowserPilotError("protocol_incompatible", "This Browser Pilot installation does not own the running Broker", {
-      context: {
-        brokerExecutableVersion: health.executableVersion,
-        requesterExecutableVersion: requester.version
-      },
-      remediation: {
-        code: "use_matching_executable_or_isolate",
-        message: "Use the matching Browser Pilot installation, or set BROWSER_PILOT_HOME for a deliberately isolated Broker.",
-        actionRequired: true
-      }
-    });
-  }
   try {
-    const client = await CompatibilityBrokerClient.create(daemon, executableVersion);
+    const client = await CompatibilityBrokerClient.create(daemon, executableVersion, clientKey);
     await client.releaseWorkspace();
   } catch (error) {
     if (!(error instanceof BrowserPilotError) || error.code !== "browser_not_found") throw error;
   }
+  const afterRelease = await daemon.healthInfo();
+  if ((afterRelease.clients?.activeLeases ?? 0) > 0) {
+    return;
+  }
+  if (!afterRelease.ok || !afterRelease.brokerProcessIdentity || !afterRelease.executableVersion || !afterRelease.executableIdentity) return;
+  const requester = createExecutableMetadataSync(
+    executableVersion,
+    publicExecutablePath(import.meta.url)
+  );
+  if (requester.version !== afterRelease.executableVersion || requester.identity !== afterRelease.executableIdentity) return;
   await daemon.shutdown({
-    brokerProcessIdentity: health.brokerProcessIdentity,
+    brokerProcessIdentity: afterRelease.brokerProcessIdentity,
     executableVersion: requester.version,
     executableIdentity: requester.identity
   });
@@ -3495,7 +1470,8 @@ async function shutdownCompatibility(executableVersion) {
 
 // src/cli.ts
 var program = new Command();
-program.name("bp").description("Control your browser from the command line").version(BROWSER_PILOT_VERSION).option("--human", "force human-readable output (default when TTY)").addHelpText("after", `
+program.exitOverride();
+program.name("bp").description("Control your browser from the command line").version(BROWSER_PILOT_VERSION).option("--human", "force human-readable output (default when TTY)").option("--client-key <key>", "stable namespace for Agent browser state").option("--request-id <id>", "stable host request ID for safe retry recovery").option("--timeout <ms>", "browser command deadline in milliseconds", "60000").addHelpText("after", `
 Workflow:
   bp connect                          # one-time setup (click Allow in Chrome)
   bp profiles                         # list live Chrome Profile contexts
@@ -3525,7 +1501,7 @@ Output:
   JSON by default when piped (for LLM/script use).
   Human-readable when run in a terminal (TTY). Force with --human.
   Actions return: {"ok":true, "title":"...", "url":"...", "elements":[...]}
-  Errors return:  {"ok":false, "error":"...", "hint":"..."}
+  Errors return:  {"ok":false, "error":"...", "code":"...", "retryable":false}
 
 Canvas editors (Google Docs, Sheets, Figma):
   bp keyboard "text" --click ".editor"               # click to focus, then type
@@ -3550,24 +1526,43 @@ Eval (escape hatch for operations without a dedicated command):
   bp eval "JSON.stringify(localStorage)"              # read storage
   echo 'complex js here' | bp eval                   # stdin for complex JS
 `);
+var cliAbortController = new AbortController();
+var receivedSignal;
+for (const signal of ["SIGINT", "SIGTERM"]) {
+  process.once(signal, () => {
+    receivedSignal = signal;
+    cliAbortController.abort();
+    const fallback = setTimeout(() => process.exit(signal === "SIGINT" ? 130 : 143), 2e3);
+    fallback.unref();
+  });
+}
 function useJson() {
-  if (program.opts().human) return false;
+  if (process.argv.slice(2).includes("--human") || program.opts().human) return false;
   return !process.stdout.isTTY;
 }
+program.configureOutput({
+  writeErr: (value) => {
+    if (!useJson()) process.stderr.write(value);
+  }
+});
 function emit(data, human) {
   if (useJson()) console.log(JSON.stringify(data));
   else if (human) console.log(human);
 }
 function fail(error, hint, details) {
+  const stable = details ?? new BrowserPilotError("internal_error", error);
   if (useJson()) console.log(JSON.stringify({
     ok: false,
     error,
+    code: stable.code,
+    retryable: stable.retryable,
     ...hint ? { hint } : {},
-    ...details ? details.toData() : {}
+    ...stable.context ? { context: stable.context } : {},
+    ...stable.remediation ? { remediation: stable.remediation } : {}
   }));
   else console.error(`\u2717 ${error}${hint ? `
   hint: ${hint}` : ""}`);
-  process.exit(1);
+  process.exit(receivedSignal === "SIGINT" ? 130 : receivedSignal === "SIGTERM" ? 143 : 1);
 }
 function observationElements(result) {
   return Array.isArray(result.elements) ? result.elements : [];
@@ -3617,13 +1612,17 @@ function emitObservation(result) {
 function action(fn) {
   return (...args) => fn(...args).catch((err) => {
     const msg = err instanceof Error ? err.message : String(err);
-    if (err instanceof BrowserPilotError && err.code === "stale_ref") {
-      fail(msg, "Run 'bp snapshot' to refresh element refs.", err);
+    const stable = err instanceof BrowserPilotError ? err : new BrowserPilotError("internal_error", msg, { cause: err });
+    if (stable.code === "stale_ref") {
+      fail(msg, "Run 'bp snapshot' to refresh element refs.", stable);
+    }
+    if (stable.code === "browser_disconnected") {
+      fail(msg, "Run 'bp connect' first.", stable);
     }
-    if (msg.includes("not found") && msg.includes("Ref")) fail(msg, "Run 'bp snapshot' to refresh element refs.", err instanceof BrowserPilotError ? err : void 0);
-    if (msg.includes("Not connected")) fail(msg, "Run 'bp connect' first.", err instanceof BrowserPilotError ? err : void 0);
-    if (msg.includes("Page load timeout")) fail(msg, "Page may still be loading. Retry the command after a moment.", err instanceof BrowserPilotError ? err : void 0);
-    fail(msg, void 0, err instanceof BrowserPilotError ? err : void 0);
+    if (stable.code === "unknown_outcome") {
+      fail(msg, "Inspect the current tab state before deciding whether to retry.", stable);
+    }
+    fail(msg, void 0, stable);
   });
 }
 function normalizeUrl(url) {
@@ -3631,18 +1630,127 @@ function normalizeUrl(url) {
   return `https://${url}`;
 }
 function parseLimit(raw) {
-  const n = parseInt(raw, 10);
-  if (isNaN(n) || n < 1) throw new Error("--limit must be a positive number");
+  const n = Number(raw);
+  if (!/^\d+$/.test(raw) || !Number.isSafeInteger(n) || n < 1) {
+    throw invalidArgument("--limit must be a positive integer", "limit");
+  }
   return n;
 }
 function parseRef(raw) {
   const ref = Number(raw);
-  if (!Number.isSafeInteger(ref) || ref < 1) {
-    throw new Error("Ref must be a positive integer");
+  if (!/^\d+$/.test(raw) || !Number.isSafeInteger(ref) || ref < 1) {
+    throw invalidArgument("Ref must be a positive integer", "ref");
   }
   return ref;
 }
-function requireString2(value, label) {
+function parseCoordinates(raw) {
+  const parts = raw.split(",");
+  if (parts.length !== 2 || parts.some((part) => part.trim() === "")) {
+    throw invalidArgument("--xy must be x,y (e.g. --xy 400,300)", "xy");
+  }
+  const [x, y] = parts.map((part) => Number(part.trim()));
+  if (!Number.isFinite(x) || !Number.isFinite(y)) {
+    throw invalidArgument("--xy must be x,y (e.g. --xy 400,300)", "xy");
+  }
+  return { x, y };
+}
+function cliClientKey() {
+  const value = program.opts().clientKey ?? process.env.BROWSER_PILOT_CLIENT_KEY;
+  if (value === void 0) return "browser-pilot-cli";
+  if (typeof value !== "string" || !/^[A-Za-z0-9][A-Za-z0-9._:-]{2,127}$/.test(value)) {
+    throw new BrowserPilotError(
+      "invalid_argument",
+      "Client key must be 3-128 characters using letters, digits, dot, underscore, colon, or hyphen",
+      { context: { field: "clientKey" } }
+    );
+  }
+  return value;
+}
+function cliInvocationOptions() {
+  const requestId = program.opts().requestId ?? process.env.BROWSER_PILOT_REQUEST_ID;
+  if (requestId !== void 0 && (typeof requestId !== "string" || !/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(requestId))) {
+    throw invalidArgument(
+      "Request ID must be 1-128 characters using letters, digits, dot, underscore, colon, or hyphen",
+      "requestId"
+    );
+  }
+  const rawTimeout = String(program.opts().timeout ?? "60000");
+  const deadlineMs = Number(rawTimeout);
+  if (!/^\d+$/.test(rawTimeout) || !Number.isSafeInteger(deadlineMs) || deadlineMs < 1 || deadlineMs > 3e5) {
+    throw invalidArgument("--timeout must be an integer from 1 through 300000", "timeout");
+  }
+  return {
+    ...requestId ? { requestId } : {},
+    deadlineMs,
+    signal: cliAbortController.signal
+  };
+}
+function cliCommand(command) {
+  return {
+    id: command.id,
+    method: command.method,
+    mutating: command.mutating,
+    status: command.status,
+    acceptedAt: command.acceptedAt,
+    deadlineAt: command.deadlineAt,
+    ...command.targetId ? { targetId: command.targetId } : {},
+    ...command.dispatchedAt !== void 0 ? { dispatchedAt: command.dispatchedAt } : {},
+    ...command.completedAt !== void 0 ? { completedAt: command.completedAt } : {},
+    ...command.cancellationRequested ? { cancellationRequested: true } : {}
+  };
+}
+function cliCommandOutcome(outcome) {
+  return {
+    command: cliCommand(outcome.command),
+    ...outcome.result !== void 0 ? { result: outcome.result } : {},
+    ...outcome.error !== void 0 ? { error: outcome.error } : {}
+  };
+}
+function outputPath(filename) {
+  if (isAbsolute3(filename)) return resolvePath(filename);
+  const configured = process.env.BROWSER_PILOT_OUTPUT_DIR;
+  if (configured !== void 0) {
+    if (!isAbsolute3(configured)) {
+      throw invalidArgument("BROWSER_PILOT_OUTPUT_DIR must be an absolute path", "outputDir");
+    }
+    mkdirSync2(configured, { recursive: true, mode: 448 });
+    return resolvePath(configured, filename);
+  }
+  return resolvePath(filename);
+}
+function artifactFileResult(artifact, file) {
+  return {
+    file,
+    mimeType: artifact.mimeType,
+    sizeBytes: artifact.byteSize,
+    ...artifact.width !== void 0 ? { width: artifact.width } : {},
+    ...artifact.height !== void 0 ? { height: artifact.height } : {}
+  };
+}
+function delay2(ms) {
+  if (cliAbortController.signal.aborted) {
+    return Promise.reject(new BrowserPilotError("command_cancelled", "Wait was cancelled"));
+  }
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(done, ms);
+    function done() {
+      cliAbortController.signal.removeEventListener("abort", cancelled);
+      resolve();
+    }
+    function cancelled() {
+      clearTimeout(timer);
+      cliAbortController.signal.removeEventListener("abort", cancelled);
+      reject(new BrowserPilotError("command_cancelled", "Wait was cancelled"));
+    }
+    cliAbortController.signal.addEventListener("abort", cancelled, { once: true });
+  });
+}
+function matchesUrl(url, pattern) {
+  if (!pattern.includes("*")) return url.includes(pattern);
+  const source = pattern.split("*").map((part) => part.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join(".*");
+  return new RegExp(`^${source}$`).test(url);
+}
+function requireString(value, label) {
   if (typeof value !== "string") throw new BrowserPilotError("internal_error", `${label} is missing`);
   return value;
 }
@@ -3659,12 +1767,21 @@ async function cliElementAddress(client, target, raw) {
       ref: parseRef(raw)
     };
   }
-  if (!raw.trim()) throw new Error("Element target must not be empty");
+  if (!raw.trim()) throw invalidArgument("Element target must not be empty", "target");
   return { selector: raw };
 }
 async function requireCompatibility() {
-  const client = await resumeCompatibility(BROWSER_PILOT_VERSION);
-  if (!client) throw new Error("Not connected");
+  const client = await resumeCompatibility(BROWSER_PILOT_VERSION, cliClientKey(), cliInvocationOptions());
+  if (!client) {
+    throw new BrowserPilotError("browser_disconnected", "Browser Pilot is not connected", {
+      retryable: true,
+      remediation: {
+        code: "connect_browser",
+        message: "Run 'bp connect', complete Chrome authorization if prompted, then retry.",
+        actionRequired: true
+      }
+    });
+  }
   return client;
 }
 async function resolveCliProfile(client, selector) {
@@ -3673,11 +1790,11 @@ async function resolveCliProfile(client, selector) {
   if (exactId) return exactId;
   if (/^\d+$/.test(selector)) {
     const index = Number(selector);
-    if (Number.isSafeInteger(index) && profiles[index]) return profiles[index];
-    throw invalidCliProfile(`Profile index out of range (0-${Math.max(0, profiles.length - 1)})`, selector);
+    if (Number.isSafeInteger(index) && index >= 1 && profiles[index - 1]) return profiles[index - 1];
+    throw invalidCliProfile(`Profile index out of range (1-${profiles.length})`, selector);
   }
   const normalized = selector.trim().toLocaleLowerCase();
-  const matches = profiles.filter((profile) => profile.label.toLocaleLowerCase() === normalized || profile.displayName?.toLocaleLowerCase() === normalized);
+  const matches = profiles.filter((profile) => profile.label.toLocaleLowerCase() === normalized || profile.displayName?.toLocaleLowerCase() === normalized || profile.profileName?.toLocaleLowerCase() === normalized || profile.accountName?.toLocaleLowerCase() === normalized || profile.accountEmail?.toLocaleLowerCase() === normalized);
   if (matches.length === 1) return matches[0];
   if (matches.length > 1) {
     throw invalidCliProfile("Profile selector is ambiguous; use its index or Profile context ID", selector);
@@ -3691,10 +1808,16 @@ function invalidCliProfile(message, selector) {
 }
 function cliProfile(profile, index) {
   return {
-    index,
+    index: index + 1,
     profileContextId: profile.profileContextId,
     label: profile.label,
     ...profile.displayName ? { displayName: profile.displayName } : {},
+    ...profile.identityStatus ? { identityStatus: profile.identityStatus } : {},
+    ...profile.profileName ? { profileName: profile.profileName } : {},
+    ...profile.accountName ? { accountName: profile.accountName } : {},
+    ...profile.accountEmail ? { accountEmail: profile.accountEmail } : {},
+    ...profile.profileDirectory ? { profileDirectory: profile.profileDirectory } : {},
+    ...profile.identityErrorCode ? { identityErrorCode: profile.identityErrorCode } : {},
     tabCount: profile.tabCount,
     eligibleTabCount: profile.eligibleTabCount,
     selected: profile.selected,
@@ -3702,7 +1825,7 @@ function cliProfile(profile, index) {
   };
 }
 function withCliTarget(operation) {
-  return withCompatibilityTarget(BROWSER_PILOT_VERSION, operation);
+  return withCompatibilityTarget(BROWSER_PILOT_VERSION, operation, cliClientKey(), cliInvocationOptions());
 }
 function readStdin() {
   if (process.stdin.isTTY) return Promise.resolve("");
@@ -3714,9 +1837,212 @@ function readStdin() {
     process.stdin.on("end", () => resolve(d.trim()));
   });
 }
+program.command("status").description("Show current Broker, browser, Agent namespace, and recovery state").action(action(async () => {
+  const brokerRunning = isDaemonRunning();
+  const client = await resumeCompatibility(BROWSER_PILOT_VERSION, cliClientKey(), cliInvocationOptions());
+  if (!client) {
+    const browsers = (await discoverBrowserCandidates()).map((discovered) => discovered.candidate);
+    emit({
+      ok: true,
+      service: { state: brokerRunning ? "unavailable" : "stopped", version: BROWSER_PILOT_VERSION },
+      browser: { state: "disconnected" },
+      browsers,
+      session: { state: "unavailable" },
+      recovery: {
+        required: true,
+        code: "browser_disconnected",
+        action: "bp connect"
+      }
+    }, brokerRunning ? "Browser Pilot Broker is running, but the browser session is unavailable." : "Browser Pilot is not connected. Run bp connect.");
+    return;
+  }
+  const [activeCommands, uncertainCommands] = await Promise.all([
+    client.listCommands(20, ["accepted", "dispatched"]),
+    client.listCommands(20, ["unknown_outcome"])
+  ]);
+  let tabs = [];
+  let profiles = [];
+  let browserStateError;
+  try {
+    [tabs, profiles] = await Promise.all([client.listTabs("all"), client.listProfiles()]);
+  } catch (error) {
+    browserStateError = error instanceof BrowserPilotError ? error : new BrowserPilotError("internal_error", error instanceof Error ? error.message : String(error));
+  }
+  const selectedTarget = tabs.find((tab) => tab.selected ?? tab.active === true);
+  const selectedProfile = profiles.find((profile) => profile.selected);
+  const browser = client.initialized.browsers.find((candidate) => candidate.state === "ready") ?? client.initialized.browsers[0];
+  const recovery = browserStateError ? {
+    required: true,
+    code: browserStateError.code,
+    action: browserStateError.remediation?.message ?? "Inspect the browser connection before continuing."
+  } : uncertainCommands.length > 0 ? {
+    required: true,
+    code: "unknown_outcome",
+    action: "Inspect the current tab and the uncertain command before retrying."
+  } : { required: false };
+  emit({
+    ok: true,
+    service: {
+      state: "running",
+      version: client.initialized.serviceVersion
+    },
+    browser: browser ? { id: browser.id, product: browser.product, state: browser.state } : { state: "disconnected" },
+    session: {
+      state: client.lease.state,
+      expiresAt: client.lease.expiresAt,
+      profile: selectedProfile ? cliProfile(selectedProfile, profiles.indexOf(selectedProfile)) : null,
+      target: selectedTarget ? {
+        index: tabs.indexOf(selectedTarget) + 1,
+        title: selectedTarget.title,
+        url: selectedTarget.url,
+        origin: selectedTarget.origin,
+        profileContextId: selectedTarget.profileContextId
+      } : null
+    },
+    commands: {
+      active: activeCommands.map(cliCommand),
+      uncertain: uncertainCommands.map(cliCommand)
+    },
+    recovery
+  }, `Browser Pilot: ${browser?.state ?? "disconnected"}; ${tabs.length} tab(s); ${activeCommands.length} active command(s)`);
+}));
+program.command("commands").description("List recent commands for this Agent namespace").option("-l, --limit <n>", "maximum commands to return", "20").option("--status <statuses>", "comma-separated Command statuses").action(action(async (opts) => {
+  const limit = parseLimit(opts.limit);
+  if (limit > 100) throw invalidArgument("--limit must not exceed 100", "limit");
+  const statuses = opts.status === void 0 ? void 0 : String(opts.status).split(",").map((status) => status.trim()).filter(Boolean);
+  const validStatuses = /* @__PURE__ */ new Set([
+    "accepted",
+    "dispatched",
+    "completed",
+    "unknown_outcome",
+    "cancelled",
+    "expired"
+  ]);
+  if (statuses && (statuses.length === 0 || statuses.some((status) => !validStatuses.has(status)))) {
+    throw invalidArgument("--status contains an invalid Command status", "status");
+  }
+  const commands = await (await requireCompatibility()).listCommands(limit, statuses);
+  if (useJson()) {
+    console.log(JSON.stringify({ ok: true, commands: commands.map(cliCommand) }));
+  } else if (commands.length === 0) {
+    console.log("No recent commands.");
+  } else {
+    for (const command of commands) {
+      console.log(`${command.id}  ${command.status.padEnd(15)} ${command.method}`);
+    }
+  }
+}));
+program.command("command <commandId>").description("Inspect one recent command and its outcome").action(action(async (commandId) => {
+  const outcome = await (await requireCompatibility()).getCommand(commandId);
+  const result = cliCommandOutcome(outcome);
+  if (useJson()) console.log(JSON.stringify({ ok: true, ...result }));
+  else console.log(`${outcome.command.id}: ${outcome.command.status} (${outcome.command.method})`);
+}));
+program.command("cancel <commandId>").description("Request cancellation of a running command").action(action(async (commandId) => {
+  const outcome = await (await requireCompatibility()).cancelCommand(commandId);
+  const result = cliCommandOutcome(outcome);
+  if (useJson()) console.log(JSON.stringify({ ok: true, ...result }));
+  else console.log(`${outcome.command.id}: ${outcome.command.status}`);
+}));
+program.command("wait").description("Wait for a browser-visible condition").option("--url <pattern>", "wait for the selected tab URL to contain a value or match a * glob").option("--text <text>", "wait for visible page text").option("--selector <selector>", "wait for a CSS selector").option("--dialog", "wait for a pending JavaScript dialog").option("--download", "wait for a completed unexported download").option("--popup", "wait for a managed popup tab").option("--interval <ms>", "poll interval in milliseconds", "250").action(action(async (opts) => {
+  const conditions = [
+    opts.url !== void 0,
+    opts.text !== void 0,
+    opts.selector !== void 0,
+    opts.dialog === true,
+    opts.download === true,
+    opts.popup === true
+  ].filter(Boolean).length;
+  if (conditions !== 1) {
+    throw invalidArgument(
+      "Choose exactly one of --url, --text, --selector, --dialog, --download, or --popup",
+      "condition"
+    );
+  }
+  const intervalMs = Number(opts.interval);
+  if (!/^\d+$/.test(String(opts.interval)) || !Number.isSafeInteger(intervalMs) || intervalMs < 100 || intervalMs > 5e3) {
+    throw invalidArgument("--interval must be an integer from 100 through 5000", "interval");
+  }
+  const waitTimeoutMs = cliInvocationOptions().deadlineMs ?? 6e4;
+  const startedAt = Date.now();
+  const deadlineAt = startedAt + waitTimeoutMs;
+  const client = await requireCompatibility();
+  const needsTarget = opts.url !== void 0 || opts.text !== void 0 || opts.selector !== void 0;
+  const target = needsTarget ? await client.ensureTarget() : void 0;
+  const condition = opts.url !== void 0 ? "url" : opts.text !== void 0 ? "text" : opts.selector !== void 0 ? "selector" : opts.dialog ? "dialog" : opts.download ? "download" : "popup";
+  while (Date.now() <= deadlineAt) {
+    let matched;
+    if (opts.url !== void 0) {
+      const tabs = await client.listTabs("all");
+      const current = tabs.find((tab) => tab.targetId === target.targetId);
+      if (current && matchesUrl(current.url, String(opts.url))) {
+        matched = {
+          title: current.title,
+          url: current.url,
+          origin: current.origin,
+          profileContextId: current.profileContextId
+        };
+      }
+    } else if (opts.text !== void 0) {
+      const result = await client.callTool("browser.search", {
+        query: String(opts.text),
+        limit: 1
+      }, target.targetId);
+      const matches = Array.isArray(result.matches) ? result.matches : [];
+      if (matches.length > 0) matched = { title: result.title, url: result.url, match: matches[0] };
+    } else if (opts.selector !== void 0) {
+      const result = await client.callTool("browser.elements.find", {
+        selector: String(opts.selector),
+        limit: 1
+      }, target.targetId);
+      const elements = Array.isArray(result.elements) ? result.elements : [];
+      if (elements.length > 0) matched = { url: result.url, element: elements[0] };
+    } else if (opts.dialog) {
+      const result = await client.callTool("browser.dialogs.list");
+      const dialogs = Array.isArray(result.dialogs) ? result.dialogs : [];
+      if (dialogs.length > 0) matched = dialogs[0];
+    } else if (opts.download) {
+      const downloads = await client.listArtifacts(["download"]);
+      if (downloads.length > 0) matched = {
+        index: 1,
+        id: downloads[0].id,
+        fileName: downloads[0].fileName ?? null,
+        mimeType: downloads[0].mimeType,
+        sizeBytes: downloads[0].byteSize,
+        createdAt: downloads[0].createdAt,
+        expiresAt: downloads[0].expiresAt
+      };
+    } else {
+      const tabs = await client.listTabs("all");
+      const popup = tabs.find((tab) => tab.origin === "managed_popup");
+      if (popup) {
+        matched = {
+          title: popup.title,
+          url: popup.url,
+          origin: popup.origin,
+          profileContextId: popup.profileContextId
+        };
+      }
+    }
+    if (matched !== void 0) {
+      emit({
+        ok: true,
+        condition,
+        elapsedMs: Date.now() - startedAt,
+        matched
+      }, `Condition satisfied: ${condition}`);
+      return;
+    }
+    await delay2(Math.min(intervalMs, Math.max(0, deadlineAt - Date.now())));
+  }
+  throw new BrowserPilotError("wait_timeout", `Timed out waiting for ${condition}`, {
+    retryable: true,
+    context: { condition, timeoutMs: waitTimeoutMs }
+  });
+}));
 program.command("browsers").description("List supported local browsers and their setup state").option("-b, --browser <name>", "filter by browser ID, product, or channel").action(action(async (opts) => {
   const filter = typeof opts.browser === "string" ? opts.browser.toLowerCase() : void 0;
-  const client = await resumeCompatibility(BROWSER_PILOT_VERSION);
+  const client = await resumeCompatibility(BROWSER_PILOT_VERSION, cliClientKey(), cliInvocationOptions());
   const browsers = client ? await client.listBrowsers(filter) : (await discoverBrowserCandidates()).map((discovered) => discovered.candidate).filter((candidate) => !filter || [candidate.id, candidate.product, candidate.channel].some((value) => value?.toLowerCase().includes(filter)));
   if (useJson()) {
     console.log(JSON.stringify({ ok: true, browsers }));
@@ -3743,7 +2069,7 @@ program.command("connect").description("Connect to Chrome and prepare unambiguou
     console.log(`If prompted, click "Allow" in Chrome's authorization dialog.
 `);
   }
-  const client = await connectCompatibility(BROWSER_PILOT_VERSION, opts.browser);
+  const client = await connectCompatibility(BROWSER_PILOT_VERSION, opts.browser, cliClientKey(), cliInvocationOptions());
   await client.connectBrowser();
   const profiles = await client.listProfiles();
   if (profiles.length <= 1) await client.ensureManagedTarget();
@@ -3753,7 +2079,7 @@ program.command("connect").description("Connect to Chrome and prepare unambiguou
     emit(
       { ok: true, browser, profileSelectionRequired: true, profiles: listed },
       `\u2713 Connected to ${browser}
-Multiple Chrome Profiles are open. Run 'bp profiles', then 'bp profile <index>'.`
+Multiple Chrome Profiles are open. Run 'bp profiles --identify', then 'bp profile <index>'.`
     );
     return;
   }
@@ -3765,31 +2091,14 @@ Multiple Chrome Profiles are open. Run 'bp profiles', then 'bp profile <index>'.
 Ready! Try: bp open https://example.com`
   );
 }));
-program.command("bridge").description("Run the Agent-neutral JSON-RPC bridge").option("--stdio", "use newline-delimited JSON-RPC over stdin/stdout").option("-b, --browser <name>", "prefer a browser ID, product, or channel when starting the Broker").action((opts) => {
-  if (!opts.stdio) {
-    process.stderr.write("bridge currently requires --stdio\n");
-    process.exitCode = 2;
-    return;
-  }
-  void runStdioBridge({
-    input: process.stdin,
-    output: process.stdout,
-    backend: new DaemonBridgeBackend(opts.browser)
-  }).then((result) => {
-    process.exitCode = result.exitCode;
-  }).catch((error) => {
-    const message = error instanceof Error ? error.message : String(error);
-    process.stderr.write(`Bridge error: ${message}
-`);
-    process.exitCode = 1;
-  });
-});
 program.command("disconnect").description("Release CLI browser state and stop an otherwise unused daemon").action(action(async () => {
-  await shutdownCompatibility(BROWSER_PILOT_VERSION);
+  await shutdownCompatibility(BROWSER_PILOT_VERSION, cliClientKey());
   emit({ ok: true }, "\u2713 Disconnected");
 }));
-program.command("profiles").description("List live Chrome Profile contexts").action(action(async () => {
-  const profiles = (await (await requireCompatibility()).listProfiles()).map(cliProfile);
+program.command("profiles").description("List live Chrome Profile contexts").option("--identify", "explicitly identify Profiles using temporary visible Chrome pages").option("--refresh", "repeat Profile identification instead of using cached results").action(action(async (opts) => {
+  const client = await requireCompatibility();
+  const identified = opts.identify || opts.refresh ? await client.identifyProfiles(void 0, opts.refresh === true) : await client.listProfiles();
+  const profiles = identified.map(cliProfile);
   if (useJson()) {
     console.log(JSON.stringify({ ok: true, profiles }));
     return;
@@ -3799,8 +2108,10 @@ program.command("profiles").description("List live Chrome Profile contexts").act
     return;
   }
   for (const profile of profiles) {
-    const name = profile.displayName ? ` (${profile.displayName})` : "";
-    console.log(`${profile.selected ? "*" : " "} ${profile.index}  ${profile.label}${name}  ${profile.tabCount} tab(s)`);
+    const name = profile.profileName ?? profile.displayName;
+    const account = profile.accountEmail ?? profile.accountName;
+    const identity = name ? `  ${name}${account ? ` (${account})` : ""}  [${profile.label}]` : `  ${profile.label}${profile.identityStatus === "unavailable" ? " (identity unavailable)" : ""}`;
+    console.log(`${profile.selected ? "*" : " "} ${profile.index}${identity}  ${profile.tabCount} tab(s)`);
   }
 }));
 program.command("profile <selector>").description("Select a Chrome Profile context for new managed tabs").action(action(async (selector) => {
@@ -3812,15 +2123,21 @@ program.command("profile <selector>").description("Select a Chrome Profile conte
       ok: true,
       profileContextId: selected.profileContextId,
       label: selected.label,
-      ...selected.displayName ? { displayName: selected.displayName } : {}
+      ...selected.displayName ? { displayName: selected.displayName } : {},
+      ...selected.identityStatus ? { identityStatus: selected.identityStatus } : {},
+      ...selected.profileName ? { profileName: selected.profileName } : {},
+      ...selected.accountName ? { accountName: selected.accountName } : {},
+      ...selected.accountEmail ? { accountEmail: selected.accountEmail } : {},
+      ...selected.profileDirectory ? { profileDirectory: selected.profileDirectory } : {},
+      ...selected.identityErrorCode ? { identityErrorCode: selected.identityErrorCode } : {}
     },
-    `\u2713 Selected ${selected.displayName ?? selected.label}`
+    `\u2713 Selected ${selected.profileName ?? selected.displayName ?? selected.label}`
   );
 }));
-program.command("open <url>").description("Navigate to URL and return page snapshot").option("-n, --new", "open in new tab").option("--profile <selector>", "Profile index, ID, label, or verified display name (requires --new)").option("-l, --limit <n>", "max elements in snapshot", "50").addHelpText("after", "\nExamples:\n  bp open https://github.com\n  bp open github.com --new\n  bp open https://example.com --new --profile 1\n  bp open https://example.com --limit 20").action(action(async (url, opts) => {
+program.command("open <url>").description("Navigate to URL and return page snapshot").option("-n, --new", "open in new tab").option("--profile <selector>", "Profile index, ID, label, verified name, or email (requires --new)").option("-l, --limit <n>", "max elements in snapshot", "50").addHelpText("after", "\nExamples:\n  bp open https://github.com\n  bp open github.com --new\n  bp open https://example.com --new --profile 1\n  bp open https://example.com --limit 20").action(action(async (url, opts) => {
   url = normalizeUrl(url);
   const limit = parseLimit(opts.limit);
-  if (opts.profile && !opts.new) throw new Error("--profile requires --new");
+  if (opts.profile && !opts.new) throw invalidArgument("--profile requires --new", "profile");
   if (opts.new) {
     const client = await requireCompatibility();
     const profile = opts.profile ? await resolveCliProfile(client, String(opts.profile)) : void 0;
@@ -3854,20 +2171,22 @@ Examples:
   bp click --xy 400,300 --double   # double-click at coordinates
   bp click --xy 400,300 --right    # right-click (context menu)
   bp click 3 --right          # right-click element [3]`).action(action(async (ref, opts) => {
-  if (opts.double && opts.right) throw new Error("--double and --right are mutually exclusive");
-  if (!ref && !opts.xy) throw new Error("Provide a ref number or --xy coordinates");
+  if (opts.double && opts.right) {
+    throw invalidArgument("--double and --right are mutually exclusive", "button");
+  }
+  if (!ref && !opts.xy) throw invalidArgument("Provide a ref number or --xy coordinates", "target");
+  if (ref && opts.xy) throw invalidArgument("Provide either a ref number or --xy, not both", "target");
   const limit = parseLimit(opts.limit);
+  const coordinates = opts.xy ? parseCoordinates(opts.xy) : void 0;
+  const parsedRef = ref ? parseRef(ref) : void 0;
   await withCliTarget(async (client, controlledTarget) => {
     let target;
-    if (opts.xy) {
-      const [xStr, yStr] = opts.xy.split(",");
-      const x = parseFloat(xStr), y = parseFloat(yStr);
-      if (isNaN(x) || isNaN(y)) throw new Error("--xy must be x,y (e.g. --xy 400,300)");
-      target = { x, y };
+    if (coordinates) {
+      target = coordinates;
     } else {
       target = {
         observationId: await client.latestObservation(controlledTarget.targetId),
-        ref: parseRef(ref)
+        ref: parsedRef
       };
     }
     const result = await client.callTool("browser.click", {
@@ -3906,10 +2225,11 @@ Examples:
 }));
 program.command("type <ref> <text>").description("Type text into element and return page snapshot").option("-c, --clear", "clear field before typing").option("-s, --submit", "press Enter after typing").option("-l, --limit <n>", "max elements in snapshot", "50").addHelpText("after", '\nExamples:\n  bp type 2 "hello world"\n  bp type 5 "query" --submit\n  bp type 3 "new value" --clear').action(action(async (ref, text, opts) => {
   const limit = parseLimit(opts.limit);
+  const parsedRef = parseRef(ref);
   await withCliTarget(async (client, target) => {
     const result = await client.callTool("browser.type", {
       observationId: await client.latestObservation(target.targetId),
-      ref: parseRef(ref),
+      ref: parsedRef,
       text,
       ...opts.clear ? { clear: true } : {},
       ...opts.submit ? { submit: true } : {},
@@ -3932,17 +2252,19 @@ Examples:
   bp keyboard "Hello Docs!" --click ".kix-appview-editor"
   bp keyboard "slow typing" --delay 50`).action(action(async (text, opts) => {
   const limit = parseLimit(opts.limit);
-  let delay2 = 0;
+  let delay3 = 0;
   if (opts.delay) {
-    delay2 = parseInt(opts.delay, 10);
-    if (isNaN(delay2) || delay2 < 0) throw new Error("--delay must be a non-negative number");
+    delay3 = Number(opts.delay);
+    if (!/^\d+$/.test(opts.delay) || !Number.isSafeInteger(delay3) || delay3 < 0) {
+      throw invalidArgument("--delay must be a non-negative integer", "delay");
+    }
   }
   await withCliTarget(async (client, target) => {
     const result = await client.callTool("browser.keyboard", {
       text,
       ...opts.clear ? { clear: true } : {},
       ...opts.submit ? { submit: true } : {},
-      delayMs: delay2,
+      delayMs: delay3,
       ...opts.click ? { focusSelector: opts.click } : {},
       observationLimit: limit
     }, target.targetId);
@@ -3982,7 +2304,9 @@ Examples:
   echo 'complex js' | bp eval`).action(action(async (expression) => {
   if (!expression) {
     expression = await readStdin();
-    if (!expression) throw new Error("No expression. Pass as argument or pipe via stdin.");
+    if (!expression) {
+      throw invalidArgument("No expression. Pass as argument or pipe via stdin.", "expression");
+    }
   }
   await withCliTarget(async (client, target) => {
     const result = await client.callTool("browser.eval", {
@@ -4014,8 +2338,10 @@ When to use which command:
   bp snapshot   \u2192 list interactive elements (buttons, links, inputs)
   bp read       \u2192 page text content (search results, articles)
   bp eval       \u2192 custom extraction (structured data, attributes)`).action(action(async (selector, opts) => {
-  const limit = parseInt(opts.limit, 10);
-  if (isNaN(limit) || limit < 1) throw new Error("--limit must be a positive integer");
+  const limit = Number(opts.limit);
+  if (!/^\d+$/.test(opts.limit) || !Number.isSafeInteger(limit) || limit < 1) {
+    throw invalidArgument("--limit must be a positive integer", "limit");
+  }
   await withCliTarget(async (client, target) => {
     let data;
     try {
@@ -4096,15 +2422,25 @@ Examples:
   bp scroll down --selector ".results"
   bp scroll --ref 8 --to end
   bp scroll --to-text "Payment details"`).action(action(async (direction, opts) => {
-  if (opts.selector && opts.ref) throw new Error("--selector and --ref are mutually exclusive");
+  if (opts.selector && opts.ref) {
+    throw invalidArgument("--selector and --ref are mutually exclusive", "target");
+  }
   const modes = [direction !== void 0, opts.to !== void 0, opts.toText !== void 0].filter(Boolean).length;
-  if (modes > 1) throw new Error("Use only one of direction, --to, or --to-text");
+  if (modes > 1) throw invalidArgument("Use only one of direction, --to, or --to-text", "mode");
   const validDirections = /* @__PURE__ */ new Set(["up", "down", "left", "right"]);
-  if (direction !== void 0 && !validDirections.has(direction)) throw new Error("direction must be up, down, left, or right");
-  if (opts.to !== void 0 && !["start", "end"].includes(opts.to)) throw new Error("--to must be start or end");
-  if (!["pixels", "viewport"].includes(opts.unit)) throw new Error("--unit must be pixels or viewport");
+  if (direction !== void 0 && !validDirections.has(direction)) {
+    throw invalidArgument("direction must be up, down, left, or right", "direction");
+  }
+  if (opts.to !== void 0 && !["start", "end"].includes(opts.to)) {
+    throw invalidArgument("--to must be start or end", "to");
+  }
+  if (!["pixels", "viewport"].includes(opts.unit)) {
+    throw invalidArgument("--unit must be pixels or viewport", "unit");
+  }
   const amount = opts.amount === void 0 ? void 0 : Number(opts.amount);
-  if (amount !== void 0 && (!Number.isFinite(amount) || amount <= 0)) throw new Error("--amount must be a positive number");
+  if (amount !== void 0 && (!Number.isFinite(amount) || amount <= 0)) {
+    throw invalidArgument("--amount must be a positive number", "amount");
+  }
   const limit = parseLimit(opts.limit);
   await withCliTarget(async (client, target) => {
     const rawTarget = opts.selector ?? opts.ref;
@@ -4141,7 +2477,9 @@ program.command("dropdown <target>").description("List native or ARIA dropdown o
   });
 }));
 program.command("select <target> <option>").description("Select and verify a dropdown option").option("--by <mode>", "match by label, value, or index", "label").option("--contains", "use case-insensitive substring matching").option("-l, --limit <n>", "max elements in returned snapshot", "50").addHelpText("after", '\nExamples:\n  bp select 4 "United States"\n  bp select 4 us --by value\n  bp select 4 3 --by index').action(action(async (rawTarget, rawOption, opts) => {
-  if (!["label", "value", "index"].includes(opts.by)) throw new Error("--by must be label, value, or index");
+  if (!["label", "value", "index"].includes(opts.by)) {
+    throw invalidArgument("--by must be label, value, or index", "by");
+  }
   const choice = opts.by === "index" ? { by: "index", index: parseRef(rawOption) } : { by: opts.by, [opts.by]: rawOption, exact: opts.contains !== true };
   const limit = parseLimit(opts.limit);
   await withCliTarget(async (client, target) => {
@@ -4155,9 +2493,11 @@ program.command("select <target> <option>").description("Select and verify a dro
 }));
 program.command("upload <filepath>").description('Upload file (auto-finds <input type="file"> on the page)').option("--nth <n>", "which file input to use if multiple exist", "1").addHelpText("after", "\nAuto-detects file inputs on the page. No ref needed.\n\nExamples:\n  bp upload ./photo.jpg\n  bp upload /tmp/resume.pdf\n  bp upload ./doc.pdf --nth 2    # if multiple file inputs").action(action(async (filepath, opts) => {
   const absPath = resolvePath(filepath);
-  if (!existsSync4(absPath)) throw new Error(`File not found: ${absPath}`);
-  const inputIndex = parseInt(opts.nth, 10);
-  if (isNaN(inputIndex) || inputIndex < 1) throw new Error("--nth must be a positive integer");
+  if (!existsSync4(absPath)) throw invalidArgument(`File not found: ${absPath}`, "filepath");
+  const inputIndex = Number(opts.nth);
+  if (!/^\d+$/.test(opts.nth) || !Number.isSafeInteger(inputIndex) || inputIndex < 1) {
+    throw invalidArgument("--nth must be a positive integer", "nth");
+  }
   await withCliTarget(async (client, target) => {
     const artifact = await client.importArtifact(absPath);
     try {
@@ -4173,9 +2513,46 @@ program.command("upload <filepath>").description('Upload file (auto-finds <input
     }
   });
 }));
+program.command("downloads").description("List completed downloads available to this Agent namespace").action(action(async () => {
+  const artifacts = await (await requireCompatibility()).listArtifacts(["download"]);
+  const downloads = artifacts.map((artifact, index) => ({
+    index: index + 1,
+    id: artifact.id,
+    fileName: artifact.fileName,
+    mimeType: artifact.mimeType,
+    sizeBytes: artifact.byteSize,
+    createdAt: artifact.createdAt,
+    expiresAt: artifact.expiresAt
+  }));
+  if (useJson()) {
+    console.log(JSON.stringify({ ok: true, downloads }));
+  } else if (downloads.length === 0) {
+    console.log("No completed downloads.");
+  } else {
+    for (const download of downloads) {
+      console.log(`${download.index}  ${download.fileName ?? download.id}  ${download.sizeBytes} bytes`);
+    }
+  }
+}));
+program.command("download <selector> [filename]").description("Export one completed download to a local file").action(action(async (selector, filename) => {
+  const client = await requireCompatibility();
+  const artifacts = await client.listArtifacts(["download"]);
+  const artifact = /^\d+$/.test(selector) ? artifacts[Number(selector) - 1] : artifacts.find((candidate) => candidate.id === selector);
+  if (!artifact) {
+    throw new BrowserPilotError("artifact_not_found", "Download was not found for this Agent namespace", {
+      context: { field: "selector" }
+    });
+  }
+  const fallbackName = artifact.fileName ? basename2(artifact.fileName) : `download-${artifact.createdAt}`;
+  const file = outputPath(filename ?? fallbackName);
+  await client.exportArtifact(artifact.id, file);
+  await client.releaseArtifact(artifact.id).catch(() => {
+  });
+  emit({ ok: true, ...artifactFileResult(artifact, file) }, `\u2713 Download saved to ${file}`);
+}));
 program.command("screenshot [filename]").description("Capture screenshot").option("-f, --full", "capture full page").option("--selector <sel>", "capture specific element").option("--annotate [refs]", "draw Observation ref boxes; optionally comma-separated refs").addHelpText("after", '\nExamples:\n  bp screenshot\n  bp screenshot page.png\n  bp screenshot --full\n  bp screenshot --selector ".chart"\n  bp screenshot page.png --annotate\n  bp screenshot page.png --annotate 1,3,8').action(action(async (filename, opts) => {
   if (opts.annotate !== void 0 && (opts.full || opts.selector)) {
-    throw new Error("--annotate cannot be combined with --full or --selector");
+    throw invalidArgument("--annotate cannot be combined with --full or --selector", "annotate");
   }
   await withCliTarget(async (client, target) => {
     let annotations;
@@ -4194,9 +2571,9 @@ program.command("screenshot [filename]").description("Capture screenshot").optio
     }, target.targetId);
     const artifact = artifactFrom(result);
     const file = filename ?? `screenshot-${(/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-").slice(0, -5)}.png`;
-    const outputPath = resolvePath(file);
+    const destination = outputPath(file);
     try {
-      await client.exportArtifact(artifact.id, outputPath);
+      await client.exportArtifact(artifact.id, destination);
     } finally {
       await client.releaseArtifact(artifact.id).catch(() => {
       });
@@ -4208,9 +2585,9 @@ program.command("screenshot [filename]").description("Capture screenshot").optio
     }
     emit({
       ok: true,
-      file: outputPath,
+      ...artifactFileResult(artifact, destination),
       ...typeof result.annotationCount === "number" ? { annotationCount: result.annotationCount } : {}
-    }, `\u2713 Screenshot saved to ${outputPath}`);
+    }, `\u2713 Screenshot saved to ${destination}`);
   });
 }));
 program.command("pdf [filename]").description("Save page as PDF").option("--landscape", "landscape orientation").addHelpText("after", "\nExamples:\n  bp pdf\n  bp pdf report.pdf\n  bp pdf report.pdf --landscape").action(action(async (filename, opts) => {
@@ -4220,14 +2597,14 @@ program.command("pdf [filename]").description("Save page as PDF").option("--land
     }, target.targetId);
     const artifact = artifactFrom(result);
     const file = filename ?? `page-${(/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-").slice(0, -5)}.pdf`;
-    const outputPath = resolvePath(file);
+    const destination = outputPath(file);
     try {
-      await client.exportArtifact(artifact.id, outputPath);
+      await client.exportArtifact(artifact.id, destination);
     } finally {
       await client.releaseArtifact(artifact.id).catch(() => {
       });
     }
-    emit({ ok: true, file: outputPath }, `\u2713 PDF saved to ${outputPath}`);
+    emit({ ok: true, ...artifactFileResult(artifact, destination) }, `\u2713 PDF saved to ${destination}`);
   });
 }));
 program.command("cookies [domain]").description("View cookies (CDP-only, includes HttpOnly)").addHelpText("after", "\nExamples:\n  bp cookies\n  bp cookies github.com").action(action(async (domain) => {
@@ -4263,12 +2640,15 @@ program.command("frame [target]").description("List frames, or switch to a frame
         }
       }
     } else {
-      const idx = parseInt(target, 10);
+      const idx = Number(target);
       if (!Number.isSafeInteger(idx) || idx < 0 || idx >= frames.length) {
-        throw new Error(`Frame index out of range (0-${Math.max(0, frames.length - 1)})`);
+        throw invalidArgument(
+          `Frame index out of range (0-${Math.max(0, frames.length - 1)})`,
+          "target"
+        );
       }
       const frame = frames[idx];
-      await client.callTool("browser.frames.switch", idx === 0 ? { top: true } : { frameId: requireString2(frame.frameId, "frameId") }, controlledTarget.targetId);
+      await client.callTool("browser.frames.switch", idx === 0 ? { top: true } : { frameId: requireString(frame.frameId, "frameId") }, controlledTarget.targetId);
       emit(
         { ok: true, frame: idx, url: frame.url },
         `\u2713 Switched to frame ${idx}: ${frame.url}`
@@ -4283,7 +2663,7 @@ program.command("auth [username] [password]").description("Set or clear HTTP Bas
     emit({ ok: true }, "\u2713 Auth credentials cleared");
     return;
   }
-  if (!password) throw new Error("Usage: bp auth <username> <password>");
+  if (!password) throw invalidArgument("Usage: bp auth <username> <password>", "password");
   await client.callTool("browser.auth.set", { username, password });
   emit({ ok: true }, "\u2713 Auth credentials set (scoped to HTTP 401 challenges)");
 }));
@@ -4302,7 +2682,7 @@ program.command("dialogs").description("List pending JavaScript dialogs").action
 }));
 program.command("dialog <dialogId>").description("Accept or dismiss a pending JavaScript dialog").option("--accept", "accept the dialog").option("--dismiss", "dismiss the dialog").option("--prompt <text>", "text to submit to a prompt dialog").action(action(async (dialogId, opts) => {
   if (Boolean(opts.accept) === Boolean(opts.dismiss)) {
-    throw new Error("Choose exactly one of --accept or --dismiss");
+    throw invalidArgument("Choose exactly one of --accept or --dismiss", "action");
   }
   const client = await requireCompatibility();
   const listed = await client.callTool("browser.dialogs.list");
@@ -4316,7 +2696,7 @@ program.command("dialog <dialogId>").description("Accept or dismiss a pending Ja
     dialogId,
     action: opts.accept ? "accept" : "dismiss",
     ...opts.prompt !== void 0 ? { promptText: opts.prompt } : {}
-  }, requireString2(dialog.targetId, "dialog targetId"));
+  }, requireString(dialog.targetId, "dialog targetId"));
   emit(
     { ok: true, dialogId: result.dialogId, action: result.action },
     `\u2713 ${result.action === "accept" ? "Accepted" : "Dismissed"} dialog ${result.dialogId}`
@@ -4324,9 +2704,10 @@ program.command("dialog <dialogId>").description("Accept or dismiss a pending Ja
 }));
 program.command("tabs").description("List all controllable browser tabs").action(action(async () => {
   const targets = await (await requireCompatibility()).listTabs("all");
-  const tabs = targets.map(({ targetId: _targetId, managedTabSetId: _managedTabSetId, controlState, ...tab }, index) => ({
-    index,
+  const tabs = targets.map(({ targetId: _targetId, managedTabSetId: _managedTabSetId, controlState, active, selected, ...tab }, index) => ({
+    index: index + 1,
     ...tab,
+    selected: selected ?? active === true,
     controlState
   }));
   if (useJson()) {
@@ -4334,20 +2715,20 @@ program.command("tabs").description("List all controllable browser tabs").action
   } else if (tabs.length === 0) {
     console.log("No controllable tabs open.");
   } else {
-    for (const t of tabs) console.log(`${t.active ? "*" : " "} ${t.index}  ${t.url}  ${t.title}`);
+    for (const t of tabs) console.log(`${t.selected ? "*" : " "} ${t.index}  ${t.url}  ${t.title}`);
   }
 }));
-program.command("tab <index>").description("Switch to tab by index").action(action(async (indexStr) => {
+program.command("tab <index>").description("Select a tab by one-based index").action(action(async (indexStr) => {
   const client = await requireCompatibility();
-  const index = parseInt(indexStr, 10);
+  const index = Number(indexStr);
   const targets = await client.listTabs("all");
-  if (!Number.isSafeInteger(index) || index < 0 || index >= targets.length) {
-    throw new Error(`Tab index out of range (0-${Math.max(0, targets.length - 1)})`);
+  if (!Number.isSafeInteger(index) || index < 1 || index > targets.length) {
+    throw invalidArgument(`Tab index out of range (1-${targets.length})`, "index");
   }
-  await client.callTool("browser.tabs.switch", { targetId: targets[index].targetId });
-  emit({ ok: true, index }, `\u2713 Switched to tab ${index}`);
+  await client.callTool("browser.tabs.switch", { targetId: targets[index - 1].targetId });
+  emit({ ok: true, index }, `\u2713 Selected tab ${index}`);
 }));
-program.command("close").description("Close current browser tab").option("-a, --all", "close all tabs in the current Pilot window").action(action(async (opts) => {
+program.command("close").description("Close current browser tab").option("-a, --all", "close all managed tabs in this Agent Workspace").action(action(async (opts) => {
   const client = await requireCompatibility();
   if (opts.all) {
     const managed = await client.listTabs("managed_only");
@@ -4377,7 +2758,7 @@ program.command("close").description("Close current browser tab").option("-a, --
     await client.callTool("browser.tabs.close", {}, target.targetId);
     const remainingTabs = await client.listTabs("all");
     if (remainingTabs.length > 0) {
-      if (!remainingTabs.some((tab) => tab.active)) {
+      if (!remainingTabs.some((tab) => tab.selected ?? tab.active === true)) {
         const fallback = remainingTabs.find((tab) => tab.origin !== "user_tab");
         if (fallback) await client.callTool("browser.tabs.switch", { targetId: fallback.targetId });
       }
@@ -4404,7 +2785,7 @@ function cliNetworkRequest(request) {
 }
 async function findNetworkRequest(client, sequence) {
   if (!Number.isSafeInteger(sequence) || sequence < 1) {
-    throw new Error("Request ID must be a positive integer");
+    throw invalidArgument("Request ID must be a positive integer", "id");
   }
   const listed = await client.callTool("browser.network.requests", {
     after: sequence - 1,
@@ -4428,14 +2809,18 @@ Examples:
   bp net rules                        # list active rules
   bp net remove --all                 # clear rules`).action(action(async (opts) => {
   const client = await requireCompatibility();
-  const limit = opts.limit ? parseInt(opts.limit, 10) : 20;
+  const limit = parseLimit(opts.limit ?? "20");
+  const after = opts.after === void 0 ? void 0 : Number(opts.after);
+  if (after !== void 0 && (!/^\d+$/.test(opts.after) || !Number.isSafeInteger(after))) {
+    throw invalidArgument("--after must be a non-negative integer", "after");
+  }
   const result = await client.callTool("browser.network.requests", {
     limit,
     ...opts.url ? { url: opts.url } : {},
     ...opts.method ? { method: opts.method } : {},
     ...opts.status ? { status: opts.status } : {},
     ...opts.type ? { type: String(opts.type).split(",").map((value) => value.trim()).filter(Boolean) } : {},
-    ...opts.after ? { after: parseInt(opts.after, 10) } : {}
+    ...after !== void 0 ? { after } : {}
   });
   const requests = networkRequests(result).map(cliNetworkRequest);
   if (useJson()) {
@@ -4459,20 +2844,31 @@ Examples:
 }));
 netCmd.command("show <id>").description("Show full request/response details").option("--save <file>", "save response body to file").action(action(async (idStr, opts) => {
   const client = await requireCompatibility();
-  const id = parseInt(idStr, 10);
+  const id = Number(idStr);
   const summary = await findNetworkRequest(client, id);
   const result = await client.callTool("browser.network.request", {
-    requestId: requireString2(summary.requestId, "requestId"),
+    requestId: requireString(summary.requestId, "requestId"),
     includeBody: true
   });
   const request = result.request && typeof result.request === "object" && !Array.isArray(result.request) ? result.request : {};
   const responseBody = typeof result.body === "string" ? result.body : void 0;
   if (opts.save) {
-    if (responseBody === void 0) throw new Error(`Response body for request #${id} is unavailable`);
-    const outputPath = resolvePath(opts.save);
+    if (responseBody === void 0) {
+      throw new BrowserPilotError(
+        "action_not_verified",
+        `Response body for request #${id} is unavailable`,
+        { context: { sequence: id } }
+      );
+    }
+    const destination = outputPath(opts.save);
     const bytes = result.bodyEncoding === "base64" ? Buffer.from(responseBody, "base64") : Buffer.from(responseBody, "utf8");
-    writeFileSync2(outputPath, bytes);
-    emit({ ok: true, file: outputPath }, `Saved to ${outputPath}`);
+    writeFileSync2(destination, bytes, { mode: 384 });
+    emit({
+      ok: true,
+      file: destination,
+      mimeType: typeof request.mimeType === "string" ? request.mimeType : "application/octet-stream",
+      sizeBytes: bytes.byteLength
+    }, `Saved to ${destination}`);
     return;
   }
   const detail = { id: request.sequence, ...request, responseBody };
@@ -4497,15 +2893,18 @@ netCmd.command("block <pattern>").description("Block requests matching URL patte
   const rule = { id: result.ruleId, type: "block", pattern };
   emit({ ok: true, rule }, `Rule #${rule.id}: blocking "${pattern}"`);
 }));
-netCmd.command("mock <pattern>").description("Mock responses for matching URLs").option("--body <json>", "response body").option("--file <path>", "read body from file").option("--status <code>", "HTTP status", "200").action(action(async (pattern, opts) => {
+netCmd.command("mock <pattern>").description("Mock responses for matching URLs").option("--body <text>", "response body text").option("--file <path>", "read body from file").option("--status <code>", "HTTP status", "200").action(action(async (pattern, opts) => {
   const client = await requireCompatibility();
   let body = opts.body || "";
   if (opts.file) {
     const filePath = resolvePath(opts.file);
-    if (!existsSync4(filePath)) throw new Error(`File not found: ${filePath}`);
+    if (!existsSync4(filePath)) throw invalidArgument(`File not found: ${filePath}`, "file");
     body = readFileSync4(filePath, "utf-8");
   }
-  const status = parseInt(opts.status, 10);
+  const status = Number(opts.status);
+  if (!/^\d+$/.test(opts.status) || !Number.isSafeInteger(status) || status < 100 || status > 599) {
+    throw invalidArgument("--status must be an HTTP status from 100 through 599", "status");
+  }
   const result = await client.callTool("browser.network.rules.add", {
     type: "mock",
     pattern,
@@ -4552,10 +2951,32 @@ netCmd.command("remove [ruleId]").description("Remove interception rule(s)").opt
   } else if (ruleId) {
     await client.callTool("browser.network.rules.remove", { ruleId });
     emit({ ok: true }, `Rule #${ruleId} removed`);
-  } else throw new Error("Specify a rule ID or use --all");
+  } else throw invalidArgument("Specify a rule ID or use --all", "ruleId");
 }));
 netCmd.command("clear").description("Clear captured request log").action(action(async () => {
   await (await requireCompatibility()).callTool("browser.network.clear");
   emit({ ok: true }, "Request log cleared");
 }));
-program.parse();
+async function main() {
+  try {
+    await program.parseAsync();
+  } catch (error) {
+    if (error instanceof CommanderError) {
+      if (error.exitCode === 0) {
+        process.exitCode = 0;
+      } else if (useJson()) {
+        const message = error.message.replace(/^error:\s*/i, "");
+        const stable = new BrowserPilotError("invalid_argument", message, {
+          context: { parserCode: error.code }
+        });
+        fail(message, void 0, stable);
+      } else {
+        process.exitCode = error.exitCode;
+      }
+    } else {
+      const message = error instanceof Error ? error.message : String(error);
+      fail(message, void 0, error instanceof BrowserPilotError ? error : void 0);
+    }
+  }
+}
+void main();