browser-pilot 0.0.15 → 0.0.17

package/dist/cli.mjs

@@ -1,12 +1,14 @@
 #!/usr/bin/env bun
+import "./chunk-MIJ7UIKB.mjs";
+import "./chunk-OIHU7OFY.mjs";
 import {
+  BrowserEndpointResolutionError,
   connect,
-  getBrowserWebSocketUrl
-} from "./chunk-WPNW23CE.mjs";
+  resolveBrowserEndpoint
+} from "./chunk-IRLHCVNH.mjs";
 import "./chunk-LCNFBXB5.mjs";
 import {
   DEEP_QUERY_SCRIPT,
-  LiveTraceCollector,
   SENSITIVE_AUTOCOMPLETE_TOKENS,
   TRACE_BINDING_NAME,
   TRACE_SCRIPT,
@@ -16,13 +18,17 @@ import {
   canonicalizeRecordingArtifact,
   createRecordingManifest,
   createTraceId,
+  formatConsoleArg,
   fuzzyMatchElements,
+  globToRegex,
   grantAudioPermissions,
   normalizeTraceEvent,
   pcmToWav,
+  readString,
+  readStringOr,
   redactValueForRecording,
   validateSteps
-} from "./chunk-USYSHCI3.mjs";
+} from "./chunk-MRY3HRFJ.mjs";
 import {
   isRecord
 } from "./chunk-DTVRFXKI.mjs";
@@ -31,6 +37,68 @@ import {
   DAEMON_READY_TIMEOUT_MS
 } from "./chunk-LUGLEMVR.mjs";
 
+// src/cli/command-registry.ts
+var CLI_COMMANDS = [
+  { name: "quickstart", description: "Getting started guide", showInRootHelp: true },
+  { name: "connect", description: "Create or resume a browser session", showInRootHelp: true },
+  { name: "exec", description: "Execute high-level actions", showInRootHelp: true },
+  { name: "eval", description: "Run raw JavaScript as an escape hatch", showInRootHelp: true },
+  { name: "snapshot", description: "Inspect current page with refs", showInRootHelp: true },
+  { name: "text", description: "Extract readable page text", showInRootHelp: true },
+  { name: "page", description: "Compact page overview", showInRootHelp: true },
+  { name: "forms", description: "List form controls", showInRootHelp: true },
+  { name: "targets", description: "List available browser tabs", showInRootHelp: true },
+  { name: "diagnose", description: "Debug selectors and targeting failures", showInRootHelp: true },
+  { name: "review", description: "Structured business state after actions", showInRootHelp: true },
+  { name: "screenshot", description: "Capture a page screenshot", showInRootHelp: true },
+  { name: "run", description: "Run a workflow file", showInRootHelp: true },
+  {
+    name: "record",
+    description: "Record a human workflow and derive replayable output",
+    showInRootHelp: true
+  },
+  { name: "trace", description: "Inspect and analyze behavior over time", showInRootHelp: true },
+  {
+    name: "audio",
+    description: "Set up, validate, and drive voice pipelines",
+    showInRootHelp: true
+  },
+  { name: "env", description: "Session and browser-environment controls", showInRootHelp: true },
+  { name: "daemon", description: "Manage session daemon", showInRootHelp: true },
+  { name: "list", description: "List sessions", showInRootHelp: true },
+  { name: "close", description: "Close session", showInRootHelp: true },
+  { name: "clean", description: "Clean old sessions and artifacts", showInRootHelp: true },
+  { name: "actions", description: "Complete action reference", showInRootHelp: true }
+];
+var ROOT_HELP_COMMANDS = CLI_COMMANDS.filter((command) => command.showInRootHelp);
+var CLI_ROUTE_GROUPS = [
+  {
+    label: "Inspect page state",
+    commands: ["snapshot", "page", "forms", "review", "text", "targets", "diagnose"]
+  },
+  {
+    label: "Act in the browser",
+    commands: ["exec", "run"]
+  },
+  {
+    label: "Capture a human demo",
+    commands: ["record"]
+  },
+  {
+    label: "Analyze behavior over time",
+    commands: ["trace"],
+    note: "(listen is a compatibility alias)"
+  },
+  {
+    label: "Exercise voice/media",
+    commands: ["audio"]
+  },
+  {
+    label: "Change browser conditions",
+    commands: ["env"]
+  }
+];
+
 // src/cli/commands/actions.ts
 var ACTIONS_HELP = `
 bp actions - Complete action reference
@@ -231,7 +299,7 @@ EXAMPLES
   ]'
 
   # Use ref from snapshot
-  bp snapshot --format text  # Note the refs
+  bp snapshot -i  # Note the refs
   bp exec '{"action":"click","selector":"ref:e4"}'
 
   # Scroll and wait
@@ -358,6 +426,268 @@ Content-Type: ${contentType}\r
   parts.push(data);
 }
 
+// src/trace/live.ts
+var LiveTraceCollector = class {
+  cdp;
+  options;
+  handlers = [];
+  wsUrls = /* @__PURE__ */ new Map();
+  httpUrls = /* @__PURE__ */ new Map();
+  events = [];
+  startTime = Date.now();
+  matchRegex;
+  constructor(cdp, options = {}) {
+    this.cdp = cdp;
+    this.options = options;
+    this.matchRegex = options.match ? globToRegex(options.match) : null;
+  }
+  async start() {
+    await this.cdp.send("Runtime.enable");
+    await this.cdp.send("Page.enable");
+    await this.cdp.send("Network.enable");
+    await this.cdp.send("Runtime.addBinding", { name: TRACE_BINDING_NAME });
+    await this.cdp.send("Page.addScriptToEvaluateOnNewDocument", { source: TRACE_SCRIPT });
+    await this.cdp.send("Runtime.evaluate", { expression: TRACE_SCRIPT, awaitPromise: false });
+    if ((this.options.mode ?? "all") !== "http") {
+      this.subscribe("Network.webSocketCreated", (params) => {
+        const requestId = readStringOr(params["requestId"]);
+        const url = readStringOr(params["url"]);
+        if (!this.matchesUrl(url)) {
+          return;
+        }
+        this.wsUrls.set(requestId, url);
+        void this.emit({
+          channel: "ws",
+          event: "ws.connection.created",
+          summary: `WebSocket opened ${url}`,
+          connectionId: requestId,
+          requestId,
+          url,
+          data: { url }
+        });
+      });
+      this.subscribe("Network.webSocketFrameSent", (params) => {
+        const requestId = readStringOr(params["requestId"]);
+        const response = params["response"];
+        const payload = this.formatPayload(response?.payloadData, response?.opcode ?? 1);
+        const url = this.wsUrls.get(requestId);
+        if (this.matchRegex && !this.matchRegex.test(url ?? "") && !this.matchRegex.test(payload)) {
+          return;
+        }
+        void this.emit({
+          channel: "ws",
+          event: "ws.frame.sent",
+          summary: `WebSocket frame sent ${requestId}`,
+          connectionId: requestId,
+          requestId,
+          url,
+          data: {
+            opcode: response?.opcode ?? 1,
+            payload,
+            length: response?.payloadData?.length ?? 0
+          }
+        });
+      });
+      this.subscribe("Network.webSocketFrameReceived", (params) => {
+        const requestId = readStringOr(params["requestId"]);
+        const response = params["response"];
+        const payload = this.formatPayload(response?.payloadData, response?.opcode ?? 1);
+        const url = this.wsUrls.get(requestId);
+        if (this.matchRegex && !this.matchRegex.test(url ?? "") && !this.matchRegex.test(payload)) {
+          return;
+        }
+        void this.emit({
+          channel: "ws",
+          event: "ws.frame.received",
+          summary: `WebSocket frame received ${requestId}`,
+          connectionId: requestId,
+          requestId,
+          url,
+          data: {
+            opcode: response?.opcode ?? 1,
+            payload,
+            length: response?.payloadData?.length ?? 0
+          }
+        });
+      });
+      this.subscribe("Network.webSocketClosed", (params) => {
+        const requestId = readStringOr(params["requestId"]);
+        const url = this.wsUrls.get(requestId);
+        this.wsUrls.delete(requestId);
+        void this.emit({
+          channel: "ws",
+          event: "ws.connection.closed",
+          summary: `WebSocket closed ${requestId}`,
+          severity: "warn",
+          connectionId: requestId,
+          requestId,
+          url,
+          data: { url }
+        });
+      });
+    }
+    if ((this.options.mode ?? "all") !== "ws") {
+      this.subscribe("Network.requestWillBeSent", (params) => {
+        const request = params["request"];
+        const requestId = readStringOr(params["requestId"]);
+        const url = request?.url ?? "";
+        if (!this.matchesUrl(url)) {
+          return;
+        }
+        this.httpUrls.set(requestId, url);
+        void this.emit({
+          channel: "http",
+          event: "http.request.sent",
+          summary: `${request?.method ?? "GET"} ${url}`,
+          requestId,
+          url,
+          data: {
+            method: request?.method ?? "GET",
+            headers: request?.headers ?? {},
+            body: request?.postData ?? null
+          }
+        });
+      });
+      this.subscribe("Network.responseReceived", (params) => {
+        const requestId = readStringOr(params["requestId"]);
+        if (!this.httpUrls.has(requestId)) {
+          return;
+        }
+        const response = params["response"];
+        void this.emit({
+          channel: "http",
+          event: "http.response.received",
+          summary: `${response?.status ?? 0} ${response?.url ?? this.httpUrls.get(requestId) ?? ""}`,
+          requestId,
+          url: response?.url ?? this.httpUrls.get(requestId),
+          data: {
+            status: response?.status ?? 0,
+            headers: response?.headers ?? {},
+            mimeType: response?.mimeType ?? null
+          }
+        });
+      });
+      this.subscribe("Network.loadingFailed", (params) => {
+        const requestId = readStringOr(params["requestId"]);
+        const url = readString(params["blockedReason"]) ?? this.httpUrls.get(requestId) ?? "";
+        void this.emit({
+          channel: "http",
+          event: "http.response.failed",
+          summary: `HTTP request failed ${requestId}`,
+          severity: "error",
+          requestId,
+          url,
+          data: {
+            errorText: params["errorText"] ?? null,
+            blockedReason: params["blockedReason"] ?? null,
+            canceled: params["canceled"] ?? false
+          }
+        });
+      });
+    }
+    this.subscribe("Runtime.consoleAPICalled", (params) => {
+      const type = readStringOr(params["type"], "log");
+      if (type !== "log" && type !== "warn" && type !== "error") {
+        return;
+      }
+      const args = Array.isArray(params["args"]) ? params["args"] : [];
+      const text = args.map(formatConsoleArg).filter(Boolean).join(" ");
+      void this.emit({
+        channel: "console",
+        event: `console.${type}`,
+        severity: type === "error" ? "error" : type === "warn" ? "warn" : "info",
+        summary: text || `console.${type}`,
+        data: { args }
+      });
+    });
+    this.subscribe("Runtime.exceptionThrown", (params) => {
+      const details = params["exceptionDetails"] ?? {};
+      const text = readString(details["text"]) ?? "Runtime exception";
+      void this.emit({
+        channel: "runtime",
+        event: "runtime.exception",
+        severity: "error",
+        summary: text,
+        data: details
+      });
+    });
+    this.subscribe("Runtime.bindingCalled", (params) => {
+      if (params["name"] !== TRACE_BINDING_NAME) {
+        return;
+      }
+      const raw = readStringOr(params["payload"]);
+      try {
+        const payload = JSON.parse(raw);
+        const channel = this.channelForTraceEvent(payload.event);
+        void this.emit({
+          channel,
+          event: payload.event,
+          severity: payload.severity,
+          summary: payload.summary ?? payload.event,
+          ts: payload.ts ? new Date(payload.ts).toISOString() : void 0,
+          data: payload.data ?? {},
+          url: readString(payload.data?.["url"])
+        });
+      } catch {
+      }
+    });
+  }
+  async stop() {
+    for (const { event, handler } of this.handlers) {
+      this.cdp.off(event, handler);
+    }
+    this.handlers.length = 0;
+    return [...this.events];
+  }
+  getEvents() {
+    return [...this.events];
+  }
+  subscribe(event, handler) {
+    this.cdp.on(event, handler);
+    this.handlers.push({ event, handler });
+  }
+  matchesUrl(url) {
+    if (!this.matchRegex) {
+      return true;
+    }
+    return this.matchRegex.test(url);
+  }
+  formatPayload(payloadData, opcode) {
+    const data = payloadData ?? "";
+    const maxPayload = this.options.maxPayload ?? 256;
+    if (opcode === 2) {
+      const byteLength = Math.floor(data.length * 3 / 4);
+      return `[binary: ${byteLength} bytes]`;
+    }
+    if (data.length > maxPayload) {
+      return `${data.slice(0, maxPayload)}... [truncated, ${data.length} total]`;
+    }
+    return data;
+  }
+  channelForTraceEvent(eventName) {
+    if (eventName.startsWith("ws.")) return "ws";
+    if (eventName.startsWith("http.")) return "http";
+    if (eventName.startsWith("console.")) return "console";
+    if (eventName.startsWith("permission.")) return "permission";
+    if (eventName.startsWith("media.")) return "media";
+    if (eventName.startsWith("voice.")) return "voice";
+    if (eventName.startsWith("dom.")) return "dom";
+    if (eventName.startsWith("runtime.")) return "runtime";
+    return "session";
+  }
+  async emit(event) {
+    const normalized = normalizeTraceEvent({
+      traceId: event.traceId ?? createTraceId(event.channel),
+      sessionId: this.options.sessionId,
+      targetId: this.options.targetId,
+      elapsedMs: event.elapsedMs ?? Date.now() - this.startTime,
+      ...event
+    });
+    this.events.push(normalized);
+    await this.options.onEvent?.(normalized);
+  }
+};
+
 // src/trace/store.ts
 import * as fs from "fs";
 import { homedir } from "os";
@@ -385,11 +715,159 @@ function readTraceEvents(path) {
   }).filter((event) => event !== null);
 }
 
-// src/cli/session-logger.ts
-import * as fs2 from "fs";
+// src/cli/browser-endpoint.ts
+async function resolveCLIEndpoint(options = {}) {
+  return resolveBrowserEndpoint({
+    explicitWsUrl: options.explicitWsUrl,
+    channel: options.channel,
+    userDataDir: options.userDataDir,
+    allowLocalDiscovery: true,
+    allowLegacyHostFallback: true
+  });
+}
+function formatCandidateLabel(candidate) {
+  const channelLabel = candidate.channel ? `${candidate.channel}` : "unknown";
+  return `${channelLabel}: ${candidate.userDataDir}`;
+}
+function formatBrowserDiscoveryError(error, options = {}) {
+  const explicitFlag = options.explicitFlag ?? "--browser-url";
+  if (error instanceof BrowserEndpointResolutionError) {
+    if (error.code === "multiple-local-browsers") {
+      const candidates = error.details.candidates ?? [];
+      const foundLines = candidates.length > 0 ? candidates.map((candidate) => `  - ${formatCandidateLabel(candidate)}`).join("\n") : "  - Multiple local Chrome profiles were found";
+      return `Multiple running Chrome profiles have remote debugging enabled.
+${foundLines}
+Pass --channel <stable|beta|dev|canary> or --user-data-dir <path>.`;
+    }
+    const lines = [
+      "Could not auto-discover browser.",
+      "Recommended for Chrome 144+:",
+      "  1. Open Chrome and enable remote debugging in chrome://inspect/#remote-debugging",
+      "  2. Keep Chrome running, then retry",
+      "Other options:",
+      options.explicitHint ?? `  - Pass ${explicitFlag} with a browser WebSocket URL`,
+      "  - Launch Chrome with --remote-debugging-port=9222 and a custom --user-data-dir"
+    ];
+    if (options.reuseSessionHint) {
+      lines.push(`  - Reuse an existing session: ${options.reuseSessionHint}`);
+    }
+    if (options.latestSessionHint) {
+      lines.push(`  - Use latest session: ${options.latestSessionHint}`);
+    }
+    return lines.join("\n");
+  }
+  return error instanceof Error ? error.message : String(error);
+}
+
+// src/cli/session.ts
 import { homedir as homedir2 } from "os";
-import { dirname as dirname2, join as join2, resolve as resolve2 } from "path";
+import { join as join2 } from "path";
 var SESSION_DIR2 = join2(homedir2(), ".browser-pilot", "sessions");
+function getSessionFilePath(id) {
+  return join2(SESSION_DIR2, `${id}.json`);
+}
+async function ensureSessionDir() {
+  const fs9 = await import("fs/promises");
+  await fs9.mkdir(SESSION_DIR2, { recursive: true });
+}
+async function saveSession(session) {
+  await ensureSessionDir();
+  const fs9 = await import("fs/promises");
+  const filePath = join2(SESSION_DIR2, `${session.id}.json`);
+  await fs9.writeFile(filePath, JSON.stringify(session, null, 2));
+}
+async function loadSession(id) {
+  const fs9 = await import("fs/promises");
+  const filePath = join2(SESSION_DIR2, `${id}.json`);
+  try {
+    const content = await fs9.readFile(filePath, "utf-8");
+    return JSON.parse(content);
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      throw new Error(`Session not found: ${id}`);
+    }
+    throw error;
+  }
+}
+async function updateSession(id, updates) {
+  const session = await loadSession(id);
+  const mergedMetadata = updates.metadata !== void 0 ? { ...session.metadata, ...updates.metadata } : session.metadata;
+  const updated = {
+    ...session,
+    ...updates,
+    metadata: mergedMetadata,
+    lastActivity: (/* @__PURE__ */ new Date()).toISOString()
+  };
+  await saveSession(updated);
+  return updated;
+}
+async function deleteSession(id) {
+  const fs9 = await import("fs/promises");
+  const filePath = join2(SESSION_DIR2, `${id}.json`);
+  try {
+    await fs9.unlink(filePath);
+  } catch (error) {
+    if (error.code !== "ENOENT") {
+      throw error;
+    }
+  }
+}
+async function deleteSessionFull(id) {
+  const fs9 = await import("fs/promises");
+  const filePath = join2(SESSION_DIR2, `${id}.json`);
+  try {
+    await fs9.unlink(filePath);
+  } catch (error) {
+    if (error.code !== "ENOENT") {
+      throw error;
+    }
+  }
+  const dirPath = join2(SESSION_DIR2, id);
+  try {
+    await fs9.rm(dirPath, { recursive: true });
+  } catch (error) {
+    if (error.code !== "ENOENT") {
+      throw error;
+    }
+  }
+}
+async function listSessions() {
+  await ensureSessionDir();
+  const fs9 = await import("fs/promises");
+  try {
+    const files = await fs9.readdir(SESSION_DIR2);
+    const sessions = [];
+    for (const file of files) {
+      if (file.endsWith(".json")) {
+        try {
+          const content = await fs9.readFile(join2(SESSION_DIR2, file), "utf-8");
+          sessions.push(JSON.parse(content));
+        } catch {
+        }
+      }
+    }
+    return sessions.sort(
+      (a, b) => new Date(b.lastActivity).getTime() - new Date(a.lastActivity).getTime()
+    );
+  } catch {
+    return [];
+  }
+}
+function generateSessionId() {
+  const timestamp = Date.now().toString(36);
+  const random = Math.random().toString(36).slice(2, 8);
+  return `${timestamp}-${random}`;
+}
+async function getDefaultSession() {
+  const sessions = await listSessions();
+  return sessions[0] ?? null;
+}
+
+// src/cli/session-logger.ts
+import * as fs2 from "fs";
+import { homedir as homedir3 } from "os";
+import { dirname as dirname2, join as join3, resolve as resolve2 } from "path";
+var SESSION_DIR3 = join3(homedir3(), ".browser-pilot", "sessions");
 var SessionLogger = class {
   logPath;
   exportLogPath = null;
@@ -397,8 +875,8 @@ var SessionLogger = class {
   sessionId;
   constructor(sessionId, exportLogPath) {
     this.sessionId = sessionId;
-    const sessionDir = join2(SESSION_DIR2, sessionId);
-    this.logPath = join2(sessionDir, TRACE_FILE_NAME);
+    const sessionDir = join3(SESSION_DIR3, sessionId);
+    this.logPath = join3(sessionDir, TRACE_FILE_NAME);
     if (!fs2.existsSync(sessionDir)) {
       fs2.mkdirSync(sessionDir, { recursive: true });
     }
@@ -635,110 +1113,6 @@ function getSessionLogger(sessionId, exportLogPath) {
   return logger;
 }
 
-// src/cli/session.ts
-import { homedir as homedir3 } from "os";
-import { join as join3 } from "path";
-var SESSION_DIR3 = join3(homedir3(), ".browser-pilot", "sessions");
-function getSessionFilePath(id) {
-  return join3(SESSION_DIR3, `${id}.json`);
-}
-async function ensureSessionDir() {
-  const fs9 = await import("fs/promises");
-  await fs9.mkdir(SESSION_DIR3, { recursive: true });
-}
-async function saveSession(session) {
-  await ensureSessionDir();
-  const fs9 = await import("fs/promises");
-  const filePath = join3(SESSION_DIR3, `${session.id}.json`);
-  await fs9.writeFile(filePath, JSON.stringify(session, null, 2));
-}
-async function loadSession(id) {
-  const fs9 = await import("fs/promises");
-  const filePath = join3(SESSION_DIR3, `${id}.json`);
-  try {
-    const content = await fs9.readFile(filePath, "utf-8");
-    return JSON.parse(content);
-  } catch (error) {
-    if (error.code === "ENOENT") {
-      throw new Error(`Session not found: ${id}`);
-    }
-    throw error;
-  }
-}
-async function updateSession(id, updates) {
-  const session = await loadSession(id);
-  const mergedMetadata = updates.metadata !== void 0 ? { ...session.metadata, ...updates.metadata } : session.metadata;
-  const updated = {
-    ...session,
-    ...updates,
-    metadata: mergedMetadata,
-    lastActivity: (/* @__PURE__ */ new Date()).toISOString()
-  };
-  await saveSession(updated);
-  return updated;
-}
-async function deleteSession(id) {
-  const fs9 = await import("fs/promises");
-  const filePath = join3(SESSION_DIR3, `${id}.json`);
-  try {
-    await fs9.unlink(filePath);
-  } catch (error) {
-    if (error.code !== "ENOENT") {
-      throw error;
-    }
-  }
-}
-async function deleteSessionFull(id) {
-  const fs9 = await import("fs/promises");
-  const filePath = join3(SESSION_DIR3, `${id}.json`);
-  try {
-    await fs9.unlink(filePath);
-  } catch (error) {
-    if (error.code !== "ENOENT") {
-      throw error;
-    }
-  }
-  const dirPath = join3(SESSION_DIR3, id);
-  try {
-    await fs9.rm(dirPath, { recursive: true });
-  } catch (error) {
-    if (error.code !== "ENOENT") {
-      throw error;
-    }
-  }
-}
-async function listSessions() {
-  await ensureSessionDir();
-  const fs9 = await import("fs/promises");
-  try {
-    const files = await fs9.readdir(SESSION_DIR3);
-    const sessions = [];
-    for (const file of files) {
-      if (file.endsWith(".json")) {
-        try {
-          const content = await fs9.readFile(join3(SESSION_DIR3, file), "utf-8");
-          sessions.push(JSON.parse(content));
-        } catch {
-        }
-      }
-    }
-    return sessions.sort(
-      (a, b) => new Date(b.lastActivity).getTime() - new Date(a.lastActivity).getTime()
-    );
-  } catch {
-    return [];
-  }
-}
-function generateSessionId() {
-  const timestamp = Date.now().toString(36);
-  const random = Math.random().toString(36).slice(2, 8);
-  return `${timestamp}-${random}`;
-}
-async function getDefaultSession() {
-  const sessions = await listSessions();
-  return sessions[0] ?? null;
-}
-
 // src/cli/commands/audio.ts
 var AUDIO_HELP = `
 bp audio - Actively exercise voice and audio pipelines
@@ -894,10 +1268,14 @@ async function resolveConnection(sessionId, useLatestSession, trace) {
   }
   let wsUrl;
   try {
-    wsUrl = await getBrowserWebSocketUrl("localhost:9222");
-  } catch {
+    wsUrl = (await resolveCLIEndpoint()).wsUrl;
+  } catch (error) {
     throw new Error(
-      "Could not auto-discover browser.\nEither:\n  1. Start Chrome with: --remote-debugging-port=9222\n  2. Use an existing session: bp audio -s <session-id>\n  3. Use latest session: bp audio -s"
+      formatBrowserDiscoveryError(error, {
+        explicitHint: "  - Create a session first: bp connect --browser-url <ws-url>",
+        reuseSessionHint: "bp audio -s <session-id>",
+        latestSessionHint: "bp audio -s"
+      })
     );
   }
   const browser = await connect({ provider: "generic", wsUrl, debug: trace });
@@ -1171,7 +1549,7 @@ async function audioCommand(args, globalOptions) {
           event: checkJson.ready ? "voice.pipeline.ready" : "voice.pipeline.notReady",
           severity: checkJson.ready ? "info" : "error",
           summary: checkJson.ready ? "Audio pipeline ready" : "Audio pipeline not ready",
-          data: checkJson
+          data: { ...checkJson }
         });
         if (checkJson.agentDetected) {
           logger.logTrace({
@@ -1472,13 +1850,15 @@ bp clean - Remove stale browser sessions
 Usage:
   bp clean [options]
 
-Options:
+Local options:
   --max-age <hours>    Remove sessions older than N hours (default: 24)
   --max-size <size>    Remove oldest sessions until total size < limit (e.g. "100MB", "1GB")
   --dry-run            Show what would be removed without deleting
   --all                Remove all sessions regardless of age
-  -f, --format <fmt>   Output format: json | pretty (default: pretty)
-  --json               Alias for -f json
+
+Global options:
+  --json               Output JSON
+  --pretty             Output readable text (default)
   -h, --help           Show this help
 
 Examples:
@@ -1682,11 +2062,11 @@ bp close - Close a browser session
 Usage:
   bp close [session-id]
 
-Options:
+Global options:
   -s, --session <id>   Session to close (default: most recent)
-  -f, --format <fmt>   Output format: json | pretty (default: pretty)
-  --json               Alias for -f json
-  --trace              Enable debug tracing
+  --json               Output JSON
+  --pretty             Output readable text (default)
+  --debug              Enable CDP transport debugging
   -h, --help           Show this help
 
 Examples:
@@ -1791,16 +2171,30 @@ async function waitForDaemonReady(sessionFilePath, expectedPid, timeoutMs = DAEM
 var CONNECT_HELP = `
 bp connect - Create or resume a browser session
 
+When to use:
+  Create a session before running inspect, exec, record, trace, audio, or env commands.
+
+When not to use:
+  You already have a session and only need to open a page. Use \`bp exec '{"action":"goto","url":"..."}'\`.
+
+Browser and page URL guidance:
+  Use \`--browser-url\` for a DevTools WebSocket endpoint.
+  Use \`--page-url\` to open a page in the attached tab or a new tab.
+  \`--url\` remains for compatibility and is ambiguous when paired with \`--new-tab\`.
+
 Usage:
   bp connect [options]
 
-Options:
+Local options:
   -p, --provider <type>   Provider: generic | browserbase | browserless (default: generic)
-  --url <value>           Browser WebSocket URL, or page URL when used with --new-tab
-  --browser-url <ws-url>  Explicit browser WebSocket URL
-  --page-url <url>        URL to open in the attached page/new tab
+  --browser-url <ws-url>  Explicit browser WebSocket URL (preferred)
+  --page-url <url>        Page URL to open in the attached tab/new tab (preferred)
+  --url <value>           Compatibility shorthand; browser URL, or page URL with --new-tab
+  --channel <name>        Local Chrome channel: stable | beta | dev | canary
+  --user-data-dir <path>  Explicit local Chrome user data dir for auto-discovery
   -n, --name <id>         Custom session name (default: auto-generated)
   -r, --resume <id>       Resume an existing session by ID
+  -s, --session <id>      Alias for --resume
   --new-tab               Create and attach to a fresh tab instead of reusing an existing one
   --target-url <str>      Filter targets to those whose URL contains this string
   --api-key <key>         API key for cloud providers
@@ -1812,30 +2206,69 @@ Options:
   --no-highlights         Disable visual highlights on screenshots
   --no-daemon             Skip daemon creation (direct WebSocket only)
   --daemon-idle <mins>    Daemon idle timeout in minutes (default: 60)
-  -s, --session <id>      Alias for --resume
-  --trace                 Enable debug tracing
+
+Global options:
+  --json                  Output JSON
+  --pretty                Output readable text (default)
+  --debug                 Enable CDP transport debugging
   -h, --help              Show this help
 
 Examples:
-  bp connect                                    # Auto-connect to local Chrome (port 9222)
-  bp connect --record                           # Connect with session-level recording
-  bp connect --provider generic --name dev      # Connect with custom session name
-  bp connect --url ws://localhost:9222/devtools  # Explicit WebSocket URL
-  bp connect --resume dev                       # Resume a previous session
+  bp connect                                     # Auto-connect to local Chrome
+  bp connect --name dev                          # Auto-connect with a custom session name
+  bp connect --resume dev                        # Resume a previous session
+  bp connect --browser-url ws://localhost:9222/devtools/browser/abc123
+  bp connect --channel beta                      # Narrow auto-discovery to Chrome Beta
+  bp connect --user-data-dir ~/tmp/chrome-dev    # Use a specific Chrome profile
   bp connect --target-url localhost:3000         # Attach to tab matching URL
-  bp connect --new-tab --url https://example.com # Create and attach to a fresh tab
-  bp connect --no-daemon                        # Connect without daemon (file-based only)
+  bp connect --record                            # Connect with session-level recording
+  bp connect --new-tab --page-url https://example.com
+  bp connect --no-daemon                         # Connect without daemon (file-based only)
+
+Likely next commands:
+  bp exec -s dev '{"action":"goto","url":"https://example.com"}'
+  bp snapshot -i -s dev
+  bp text -s dev
 `.trimEnd();
+async function resolveInitialPageUrl(page, requestedUrl) {
+  const initialUrl = await page.url();
+  if (!requestedUrl || requestedUrl === "about:blank" || initialUrl !== "about:blank") {
+    return initialUrl;
+  }
+  const deadline = Date.now() + 5e3;
+  while (Date.now() < deadline) {
+    await Bun.sleep(100);
+    const currentUrl = await page.url();
+    if (currentUrl !== "about:blank") {
+      return currentUrl;
+    }
+  }
+  return initialUrl;
+}
 function parseConnectArgs(args) {
   const options = {};
   for (let i = 0; i < args.length; i++) {
     const arg = args[i];
     if (arg === "--provider" || arg === "-p") {
-      options.provider = args[++i];
+      const p = args[++i];
+      if (p !== "browserbase" && p !== "browserless" && p !== "generic") {
+        throw new Error(
+          `Invalid provider: ${p}. Must be one of: browserbase, browserless, generic`
+        );
+      }
+      options.provider = p;
     } else if (arg === "--url") {
       options.url = args[++i];
     } else if (arg === "--browser-url") {
       options.browserUrl = args[++i];
+    } else if (arg === "--channel") {
+      const channel = args[++i];
+      if (channel !== "stable" && channel !== "beta" && channel !== "dev" && channel !== "canary") {
+        throw new Error("--channel must be one of: stable, beta, dev, canary");
+      }
+      options.channel = channel;
+    } else if (arg === "--user-data-dir") {
+      options.userDataDir = args[++i];
     } else if (arg === "--page-url") {
       options.pageUrl = args[++i];
     } else if (arg === "--name" || arg === "-n") {
@@ -1911,6 +2344,9 @@ async function connectCommand(args, globalOptions) {
   const provider = options.provider ?? "generic";
   let wsUrl = options.browserUrl ?? options.url;
   let pageUrl = options.pageUrl;
+  let connectionSource;
+  let resolvedChannel;
+  let resolvedUserDataDir;
   if (options.newTab && options.url && !options.url.startsWith("ws://") && !options.url.startsWith("wss://")) {
     pageUrl = options.url;
     if (!options.browserUrl) {
@@ -1919,17 +2355,31 @@ async function connectCommand(args, globalOptions) {
   }
   if (provider === "generic" && !wsUrl) {
     try {
-      wsUrl = await getBrowserWebSocketUrl("localhost:9222");
-    } catch {
+      const resolved = await resolveCLIEndpoint({
+        explicitWsUrl: wsUrl,
+        channel: options.channel,
+        userDataDir: options.userDataDir
+      });
+      wsUrl = resolved.wsUrl;
+      connectionSource = resolved.source;
+      resolvedChannel = resolved.channel;
+      resolvedUserDataDir = resolved.userDataDir;
+    } catch (error) {
       throw new Error(
-        "Could not auto-discover browser. Specify --url or start Chrome with --remote-debugging-port=9222"
+        formatBrowserDiscoveryError(error, {
+          explicitFlag: "--browser-url"
+        })
       );
     }
+  } else if (wsUrl) {
+    connectionSource = "explicit-ws";
   }
   const connectOptions = {
     provider,
     debug: globalOptions.trace,
     wsUrl,
+    channel: options.channel,
+    userDataDir: options.userDataDir,
     apiKey: options.apiKey,
     projectId: options.projectId
   };
@@ -1938,7 +2388,7 @@ async function connectCommand(args, globalOptions) {
     void 0,
     options.targetUrl ? { targetUrl: options.targetUrl } : void 0
   );
-  const currentUrl = await page.url();
+  const currentUrl = await resolveInitialPageUrl(page, pageUrl);
   const sessionId = options.name ?? generateSessionId();
   let recordSettings;
   if (options.record) {
@@ -1959,9 +2409,13 @@ async function connectCommand(args, globalOptions) {
     currentUrl,
     metadata: {
       ...browser.metadata,
+      ...connectionSource ? { connectionSource } : {},
+      ...resolvedChannel ? { resolvedChannel } : {},
+      ...resolvedUserDataDir ? { resolvedUserDataDir } : {},
       ...recordSettings ? { record: recordSettings } : {}
     }
   };
+  const outputMetadata = session.metadata;
   await saveSession(session);
   await browser.disconnect();
   let daemonResult;
@@ -1989,7 +2443,10 @@ async function connectCommand(args, globalOptions) {
       provider,
       currentUrl,
       recording: !!recordSettings,
-      metadata: browser.metadata,
+      connectionSource,
+      resolvedChannel,
+      resolvedUserDataDir,
+      metadata: outputMetadata,
       daemon: daemonResult
     },
     globalOptions.format
@@ -2013,10 +2470,12 @@ Subcommands:
   logs      Show daemon log output
 
 Options:
-  -s, --session <id>   Target session (default: most recent)
-  -f, --format <fmt>   Output format: json | pretty (default: pretty)
-  --json               Alias for -f json
   -n, --lines <n>      Number of log lines to show (default: 50)
+
+Global options:
+  -s, --session <id>   Target session (default: most recent)
+  --json               Output JSON
+  --pretty             Output readable text (default)
   -h, --help           Show this help
 
 Examples:
@@ -2646,11 +3105,15 @@ Examples:
   bp diagnose "submit"             Find elements matching "submit"
   bp diagnose "ref:e4"             Diagnose by element ref
 
-Options:
-  --json               Output as JSON
+Local options:
   --max <n>            Max candidates for fuzzy match (default: 5)
-  -s, --session <id>   Use specific session
-  --help               Show this help
+
+Global options:
+  -s, --session <id>   Session to use (default: most recent)
+  --json               Output JSON
+  --pretty             Output readable text (default)
+  --debug              Enable CDP transport debugging
+  -h, --help           Show this help
 
 Likely next commands:
   bp exec '[{"action":"click","selector":"<suggested-selector>"}]'
@@ -2784,6 +3247,9 @@ async function diagnoseCommand(args, globalOptions) {
   }
 }
 
+// src/cli/commands/env.ts
+import { dirname as dirname5 } from "path";
+
 // src/cli/env-state.ts
 function normalizeStoredPermission(name) {
   const value = String(name).trim().toLowerCase();
@@ -2821,7 +3287,9 @@ function originFromUrl(url) {
   }
 }
 function buildPermissionOverrideScript(granted) {
-  const normalized = [...new Set(granted.map((value) => normalizeStoredPermission(value)).filter(Boolean))];
+  const normalized = [
+    ...new Set(granted.map((value) => normalizeStoredPermission(value)).filter(Boolean))
+  ];
   return `
 (() => {
   const granted = ${JSON.stringify(normalized)};
@@ -3058,7 +3526,9 @@ function buildNetworkOverrideScript(state) {
 `.trim();
 }
 async function applyPermissionState(cdp, origin, granted) {
-  const protocolPermissions = [...new Set(granted.map((value) => toProtocolPermission(value)).filter(Boolean))];
+  const protocolPermissions = [
+    ...new Set(granted.map((value) => toProtocolPermission(value)).filter(Boolean))
+  ];
   if (protocolPermissions.length > 0) {
     await cdp.send("Browser.grantPermissions", {
       permissions: protocolPermissions,
@@ -3080,222 +3550,7 @@ async function applyNetworkOverride(cdp, state) {
   await cdp.send("Runtime.evaluate", { expression: script, awaitPromise: false });
 }
 
-// src/cli/attach.ts
-async function applySessionEnvironment(page, currentUrl, settings) {
-  if (!settings) {
-    return;
-  }
-  const origin = originFromUrl(currentUrl);
-  if (Array.isArray(settings.permissions)) {
-    await applyPermissionState(page.cdpClient, origin, settings.permissions);
-  }
-  if (settings.geolocation) {
-    await page.setGeolocation(settings.geolocation);
-  }
-  if (settings.visibility) {
-    await applyVisibilityState(page.cdpClient, settings.visibility);
-  }
-  if (settings.network) {
-    await applyNetworkOverride(page.cdpClient, settings.network);
-  }
-}
-async function resolveSession(sessionId) {
-  if (sessionId) {
-    return loadSession(sessionId);
-  }
-  const session = await getDefaultSession();
-  if (!session) {
-    throw new Error('No session found. Run "bp connect" first.');
-  }
-  return session;
-}
-function isDaemonHealthy(session) {
-  if (!session.daemon) return false;
-  const daemonAge = Date.now() - new Date(session.daemon.startedAt).getTime();
-  if (daemonAge > DAEMON_MAX_AGE_MS) {
-    return false;
-  }
-  if (session.daemon.lastHeartbeat) {
-    const heartbeatAge = Date.now() - new Date(session.daemon.lastHeartbeat).getTime();
-    if (heartbeatAge > 9e4) {
-      return false;
-    }
-  }
-  return isDaemonAlive(session.daemon.pid);
-}
-async function cleanupStaleDaemon(session, reason) {
-  console.warn(`[browser-pilot] Daemon unavailable (${reason}), falling back to direct WebSocket`);
-  const sessionFilePath = getSessionFilePath(session.id);
-  await clearDaemonFromSession(sessionFilePath);
-  if (session.daemon?.socketPath) {
-    try {
-      const fsPromises = await import("fs/promises");
-      await fsPromises.unlink(session.daemon.socketPath).catch(() => {
-      });
-    } catch {
-    }
-  }
-}
-async function attachSession(session, options = {}) {
-  if (session.daemon) {
-    if (!isDaemonHealthy(session)) {
-      const reason = !isDaemonAlive(session.daemon.pid) ? "PID not alive" : "daemon expired (>60min)";
-      await cleanupStaleDaemon(session, reason);
-    } else {
-      try {
-        const { createDaemonTransport } = await import("./transport-WHEBAZUP.mjs");
-        const { createCDPClientFromTransport } = await import("./client-JWWZWO6L.mjs");
-        const transport = await createDaemonTransport(session.daemon.socketPath);
-        const cdp = createCDPClientFromTransport(transport, {
-          debug: options.trace
-        });
-        const { Browser: BrowserClass } = await import("./browser-MEWT75IB.mjs");
-        const { Page: PageClass } = await import("./page-XPS6IC6V.mjs");
-        const browser2 = BrowserClass.fromCDP(cdp, session);
-        const page2 = session.daemon.cdpSessionId && session.targetId ? addBatchToPage(
-          await (async () => {
-            cdp.setSessionId(session.daemon?.cdpSessionId);
-            const attachedPage = new PageClass(cdp, session.targetId);
-            await attachedPage.init();
-            return attachedPage;
-          })()
-        ) : addBatchToPage(await browser2.page(void 0, { targetId: session.targetId }));
-        const currentUrl2 = await page2.url();
-        await applySessionEnvironment(page2, currentUrl2, session.metadata?.env);
-        const refCache2 = session.metadata?.refCache;
-        if (refCache2 && refCache2.url === currentUrl2) {
-          page2.importRefMap(refCache2.refMap);
-        }
-        return { session, browser: browser2, page: page2, viaDaemon: true };
-      } catch (err) {
-        const reason = err instanceof Error ? err.message : String(err);
-        await cleanupStaleDaemon(session, reason);
-      }
-    }
-  }
-  let browser;
-  try {
-    browser = await connect({
-      provider: session.provider,
-      wsUrl: session.wsUrl,
-      debug: options.trace
-    });
-  } catch {
-    await deleteSession(session.id);
-    throw new Error(
-      `Session "${session.id}" is no longer valid (browser may have closed).
-Session file has been cleaned up. Run "bp connect" to create a new session.`
-    );
-  }
-  const page = addBatchToPage(await browser.page(void 0, { targetId: session.targetId }));
-  const currentUrl = await page.url();
-  await applySessionEnvironment(page, currentUrl, session.metadata?.env);
-  const refCache = session.metadata?.refCache;
-  if (refCache && refCache.url === currentUrl) {
-    page.importRefMap(refCache.refMap);
-  }
-  return { session, browser, page, viaDaemon: false };
-}
-
-// src/cli/commands/eval.ts
-var EVAL_HELP = `
-bp eval - Evaluate JavaScript in the browser
-
-Convenience wrapper around exec's evaluate action.
-No JSON escaping needed -- just pass a JS expression directly.
-
-Usage:
-  bp eval '<expression>'        Evaluate inline JavaScript
-  bp eval -f <file>             Evaluate JavaScript from a file
-  echo '<expr>' | bp eval       Evaluate from stdin
-
-Options:
-  -f, --file <path>    Read JavaScript from a file
-  --wrap               Wrap the expression in an async IIFE
-  -s, --session <id>   Session to use (default: most recent)
-  -f, --format <fmt>   Output format: json | pretty (default: pretty)
-  --json               Alias for -f json
-  --trace              Enable debug tracing
-  -h, --help           Show this help
-
-Examples:
-  bp eval 'document.title'
-  bp eval 'document.querySelectorAll("a").length'
-  bp eval -f scrape.js
-`.trimEnd();
-function parseEvalArgs(args) {
-  const options = {};
-  let expression;
-  for (let i = 0; i < args.length; i++) {
-    const arg = args[i];
-    if (arg === "-f" || arg === "--file") {
-      options.file = args[++i];
-    } else if (arg === "--wrap") {
-      options.wrap = true;
-    } else if (!expression && !arg.startsWith("-")) {
-      expression = arg;
-    }
-  }
-  return { expression, options };
-}
-function normalizeEvalExpression(expression, wrap = false) {
-  const trimmed = expression.trim();
-  const needsWrap = wrap || trimmed.includes("=>") || /\bawait\b/.test(trimmed);
-  if (!needsWrap) {
-    return trimmed;
-  }
-  if (wrap || /\bawait\b/.test(trimmed)) {
-    return `(async () => (${trimmed}))()`;
-  }
-  return `(() => (${trimmed}))()`;
-}
-async function evalCommand(args, globalOptions) {
-  if (globalOptions.help) {
-    console.log(EVAL_HELP);
-    return;
-  }
-  const { expression: argExpression, options: evalOptions } = parseEvalArgs(args);
-  let expression = argExpression;
-  if (evalOptions.file) {
-    const fs9 = await import("fs/promises");
-    expression = await fs9.readFile(evalOptions.file, "utf-8");
-  }
-  if (!expression && !process.stdin.isTTY) {
-    const chunks = [];
-    for await (const chunk of process.stdin) {
-      chunks.push(chunk);
-    }
-    expression = Buffer.concat(chunks).toString("utf-8").trim();
-  }
-  if (!expression) {
-    throw new Error(
-      "No expression provided.\n\nUsage:\n  bp eval 'document.title'\n  bp eval -f script.js\n  echo 'document.title' | bp eval"
-    );
-  }
-  const session = await resolveSession(globalOptions.session);
-  const { browser, page } = await attachSession(session, { trace: globalOptions.trace });
-  try {
-    const step = {
-      action: "evaluate",
-      value: normalizeEvalExpression(expression, evalOptions.wrap)
-    };
-    const result = await page.batch([step]);
-    const stepResult = result.steps[0];
-    if (!stepResult.success) {
-      throw new Error(stepResult.error ?? "Evaluation failed");
-    }
-    output(
-      globalOptions.format === "json" ? { success: true, result: stepResult.result } : stepResult.result,
-      globalOptions.format
-    );
-    await updateSession(session.id, { currentUrl: await page.url() });
-  } finally {
-    await browser.disconnect();
-  }
-}
-
 // src/cli/commands/env.ts
-import { dirname as dirname5 } from "path";
 var ENV_HELP = `
 bp env - Browser/session environment controls
 
@@ -3453,7 +3708,6 @@ function parseEnvArgs(args) {
       }
       if (options.topCommand === "geolocation") {
         options.geoAction = arg;
-        continue;
       }
     }
   }
@@ -3484,15 +3738,22 @@ async function resolveConnection2(sessionId, useLatestSession = false) {
     if (!defaultSession) {
       throw new Error('No sessions found. Run "bp connect" first or use "-s" for latest session.');
     }
-    const browser2 = await connect({ provider: defaultSession.provider, wsUrl: defaultSession.wsUrl });
+    const browser2 = await connect({
+      provider: defaultSession.provider,
+      wsUrl: defaultSession.wsUrl
+    });
     return { browser: browser2, session: defaultSession };
   }
   let wsUrl;
   try {
-    wsUrl = await getBrowserWebSocketUrl("localhost:9222");
-  } catch {
+    wsUrl = (await resolveCLIEndpoint()).wsUrl;
+  } catch (error) {
     throw new Error(
-      "Could not auto-discover browser.\nEither:\n  1) Start Chrome with: --remote-debugging-port=9222\n  2) Use an existing session: bp env -s <id> ...\n  3) Use latest session: bp env -s"
+      formatBrowserDiscoveryError(error, {
+        explicitHint: "  - Create a session first: bp connect --browser-url <ws-url>",
+        reuseSessionHint: "bp env -s <id> ...",
+        latestSessionHint: "bp env -s"
+      })
     );
   }
   const browser = await connect({ provider: "generic", wsUrl });
@@ -3509,7 +3770,9 @@ async function resolveConnection2(sessionId, useLatestSession = false) {
   };
   await saveSession(session);
   const sessionFile = getSessionFilePath(newSessionId);
-  await import("fs/promises").then((fs9) => fs9.mkdir(dirname5(sessionFile), { recursive: true }));
+  await import("fs/promises").then(
+    (fs9) => fs9.mkdir(dirname5(sessionFile), { recursive: true })
+  );
   return { browser, session };
 }
 function clampRate(value) {
@@ -3537,7 +3800,7 @@ async function getPermissionStates(page) {
       }));
     })()
   `;
-  return await page.evaluate(expr);
+  return page.evaluate(expr);
 }
 async function permissionCommand(action, nameInput, page) {
   const requested = nameInput && nameInput !== "all" ? coercePermissionArg(nameInput) : "all";
@@ -3545,12 +3808,16 @@ async function permissionCommand(action, nameInput, page) {
     const states = await getPermissionStates(page);
     if (requested !== "all") {
       const lower = String(requested).toLowerCase();
-      return states.filter((item) => item.name === lower || item.name === PermissionNames.NAVIGATION[requested]).map((item) => ({ action, name: item.name, state: item.state }));
+      return states.filter(
+        (item) => item.name === lower || item.name === PermissionNames.NAVIGATION[requested]
+      ).map((item) => ({ action, name: item.name, state: item.state }));
     }
     return states.map((item) => ({ action, name: item.name, state: item.state }));
   }
   const permissionNames = requested === "all" ? Object.values(PermissionNames.NAVIGATION).filter((v) => v !== "all") : [PermissionNames.NAVIGATION[requested] ?? String(requested)];
-  const protocolNames = requested === "all" ? ["geolocation", "audioCapture", "videoCapture", "notifications"] : permissionNames.map((item) => PermissionNames.PROTOCOL[item] ?? String(item));
+  const protocolNames = requested === "all" ? ["geolocation", "audioCapture", "videoCapture", "notifications"] : permissionNames.map(
+    (item) => PermissionNames.PROTOCOL[item] ?? String(item)
+  );
   if (action === "grant") {
     const origin2 = await page.evaluate("window.location.origin");
     await page.cdpClient.send("Browser.grantPermissions", {
@@ -3587,7 +3854,8 @@ async function permissionCommand(action, nameInput, page) {
 function formatPermissionOutput(session, data) {
   const lines = [`Session: ${session.id}`, ""];
   for (const row of data) {
-    lines.push(`${row.name}: ${row.state ?? "unknown"} (${row.action})`);
+    const state = typeof row.state === "string" ? row.state : row.state === void 0 || row.state === null ? "unknown" : JSON.stringify(row.state);
+    lines.push(`${row.name}: ${state} (${row.action})`);
   }
   return lines.join("\n");
 }
@@ -3644,7 +3912,9 @@ async function runNetworkCommand(action, options, page, session) {
     offline: false,
     latency
   });
-  console.log(`Session ${session.id}: network throttled | latency=${latency}ms down=${down}B/s up=${up}B/s`);
+  console.log(
+    `Session ${session.id}: network throttled | latency=${latency}ms down=${down}B/s up=${up}B/s`
+  );
 }
 async function runVisibilityCommand(state, page, session) {
   await applyVisibilityState(page.cdpClient, state);
@@ -3664,7 +3934,9 @@ async function runGeolocationCommand(action, options, page, session) {
     longitude: options.lon,
     accuracy: options.accuracy ?? 1
   });
-  console.log(`Session ${session.id}: geolocation set to ${options.lat}, ${options.lon} (accuracy ${options.accuracy ?? 1})`);
+  console.log(
+    `Session ${session.id}: geolocation set to ${options.lat}, ${options.lon} (accuracy ${options.accuracy ?? 1})`
+  );
 }
 async function envCommand(args, globalOptions) {
   const options = parseEnvArgs(args);
@@ -3672,7 +3944,10 @@ async function envCommand(args, globalOptions) {
     console.log(ENV_HELP);
     return;
   }
-  const { browser, session } = await resolveConnection2(globalOptions.session, options.useLatestSession ?? false);
+  const { browser, session } = await resolveConnection2(
+    globalOptions.session,
+    options.useLatestSession ?? false
+  );
   const page = await browser.page(void 0, { targetId: session.targetId });
   const outputAsJson = globalOptions.format === "json";
   const existingEnv = session.metadata?.env ?? {};
@@ -3694,7 +3969,9 @@ async function envCommand(args, globalOptions) {
           const current = new Set(
             (existingEnv.permissions ?? []).map((value) => normalizeStoredPermission(value)).filter(isStoredPermissionName)
           );
-          const requested = options.permissionName === "all" || !options.permissionName ? ["microphone", "camera", "notifications", "geolocation"] : [normalizeStoredPermission(options.permissionName)].filter(isStoredPermissionName);
+          const requested = options.permissionName === "all" || !options.permissionName ? ["microphone", "camera", "notifications", "geolocation"] : [normalizeStoredPermission(options.permissionName)].filter(
+            isStoredPermissionName
+          );
           if (permissionMode === "grant") {
             for (const name of requested) current.add(name);
           } else {
@@ -3711,7 +3988,13 @@ async function envCommand(args, globalOptions) {
         await applyPermissionState(page.cdpClient, originFromUrl(currentUrl), nextPermissions);
       }
       if (outputAsJson) {
-        console.log(JSON.stringify({ session: session.id, action: permissionMode, permissions: result }, null, 2));
+        console.log(
+          JSON.stringify(
+            { session: session.id, action: permissionMode, permissions: result },
+            null,
+            2
+          )
+        );
       } else {
         console.log(formatPermissionOutput(session, result));
       }
@@ -3756,41 +4039,259 @@ async function envCommand(args, globalOptions) {
       }
       return;
     }
-    if (options.topCommand === "visibility") {
-      if (!options.visibility) {
-        throw new Error("visibility command requires: hidden or visible");
-      }
-      await runVisibilityCommand(options.visibility, page, session);
-      await updateSession(session.id, {
-        metadata: {
-          env: {
-            ...existingEnv,
-            visibility: options.visibility
-          }
-        }
-      });
-      return;
+    if (options.topCommand === "visibility") {
+      if (!options.visibility) {
+        throw new Error("visibility command requires: hidden or visible");
+      }
+      await runVisibilityCommand(options.visibility, page, session);
+      await updateSession(session.id, {
+        metadata: {
+          env: {
+            ...existingEnv,
+            visibility: options.visibility
+          }
+        }
+      });
+      return;
+    }
+    if (options.topCommand === "geolocation") {
+      if (!options.geoAction) {
+        throw new Error("geolocation command requires: set or clear");
+      }
+      await runGeolocationCommand(options.geoAction, options, page, session);
+      await updateSession(session.id, {
+        metadata: {
+          env: {
+            ...existingEnv,
+            geolocation: options.geoAction === "clear" ? void 0 : {
+              latitude: options.lat,
+              longitude: options.lon,
+              accuracy: options.accuracy ?? 1
+            }
+          }
+        }
+      });
+      return;
+    }
+    throw new Error("Unknown env command. Run bp env --help for usage.");
+  } finally {
+    await browser.disconnect();
+  }
+}
+
+// src/cli/attach.ts
+async function applySessionEnvironment(page, currentUrl, settings) {
+  if (!settings) {
+    return;
+  }
+  const origin = originFromUrl(currentUrl);
+  if (Array.isArray(settings.permissions)) {
+    await applyPermissionState(page.cdpClient, origin, settings.permissions);
+  }
+  if (settings.geolocation) {
+    await page.setGeolocation(settings.geolocation);
+  }
+  if (settings.visibility) {
+    await applyVisibilityState(page.cdpClient, settings.visibility);
+  }
+  if (settings.network) {
+    await applyNetworkOverride(page.cdpClient, settings.network);
+  }
+}
+async function resolveSession(sessionId) {
+  if (sessionId) {
+    return loadSession(sessionId);
+  }
+  const session = await getDefaultSession();
+  if (!session) {
+    throw new Error('No session found. Run "bp connect" first.');
+  }
+  return session;
+}
+function isDaemonHealthy(session) {
+  if (!session.daemon) return false;
+  const daemonAge = Date.now() - new Date(session.daemon.startedAt).getTime();
+  if (daemonAge > DAEMON_MAX_AGE_MS) {
+    return false;
+  }
+  if (session.daemon.lastHeartbeat) {
+    const heartbeatAge = Date.now() - new Date(session.daemon.lastHeartbeat).getTime();
+    if (heartbeatAge > 9e4) {
+      return false;
+    }
+  }
+  return isDaemonAlive(session.daemon.pid);
+}
+async function cleanupStaleDaemon(session, reason) {
+  console.warn(`[browser-pilot] Daemon unavailable (${reason}), falling back to direct WebSocket`);
+  const sessionFilePath = getSessionFilePath(session.id);
+  await clearDaemonFromSession(sessionFilePath);
+  if (session.daemon?.socketPath) {
+    try {
+      const fsPromises = await import("fs/promises");
+      await fsPromises.unlink(session.daemon.socketPath).catch(() => {
+      });
+    } catch {
+    }
+  }
+}
+async function attachSession(session, options = {}) {
+  if (session.daemon) {
+    if (!isDaemonHealthy(session)) {
+      const reason = !isDaemonAlive(session.daemon.pid) ? "PID not alive" : "daemon expired (>60min)";
+      await cleanupStaleDaemon(session, reason);
+    } else {
+      try {
+        const { createDaemonTransport } = await import("./transport-WHEBAZUP.mjs");
+        const { createCDPClientFromTransport } = await import("./client-JWWZWO6L.mjs");
+        const transport = await createDaemonTransport(session.daemon.socketPath);
+        const cdp = createCDPClientFromTransport(transport, {
+          debug: options.trace
+        });
+        const { Browser: BrowserClass } = await import("./browser-4ZHNAQR5.mjs");
+        const { Page: PageClass } = await import("./page-SD64DY3F.mjs");
+        const browser2 = BrowserClass.fromCDP(cdp, session);
+        const page2 = session.daemon.cdpSessionId && session.targetId ? addBatchToPage(
+          await (async () => {
+            cdp.setSessionId(session.daemon?.cdpSessionId);
+            const attachedPage = new PageClass(cdp, session.targetId);
+            await attachedPage.init();
+            return attachedPage;
+          })()
+        ) : addBatchToPage(await browser2.page(void 0, { targetId: session.targetId }));
+        const currentUrl2 = await page2.url();
+        await applySessionEnvironment(page2, currentUrl2, session.metadata?.env);
+        const refCache2 = session.metadata?.refCache;
+        if (refCache2 && refCache2.url === currentUrl2) {
+          page2.importRefMap(refCache2.refMap);
+        }
+        return { session, browser: browser2, page: page2, viaDaemon: true };
+      } catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        await cleanupStaleDaemon(session, reason);
+      }
+    }
+  }
+  let browser;
+  try {
+    browser = await connect({
+      provider: session.provider,
+      wsUrl: session.wsUrl,
+      debug: options.trace
+    });
+  } catch {
+    await deleteSession(session.id);
+    throw new Error(
+      `Session "${session.id}" is no longer valid (browser may have closed).
+Session file has been cleaned up. Run "bp connect" to create a new session.`
+    );
+  }
+  const page = addBatchToPage(await browser.page(void 0, { targetId: session.targetId }));
+  const currentUrl = await page.url();
+  await applySessionEnvironment(page, currentUrl, session.metadata?.env);
+  const refCache = session.metadata?.refCache;
+  if (refCache && refCache.url === currentUrl) {
+    page.importRefMap(refCache.refMap);
+  }
+  return { session, browser, page, viaDaemon: false };
+}
+
+// src/cli/commands/eval.ts
+var EVAL_HELP = `
+bp eval - Evaluate JavaScript in the browser
+
+Convenience wrapper around exec's evaluate action.
+No JSON escaping needed -- just pass a JS expression directly.
+Use this as an escape hatch after higher-level commands like snapshot, text, review, and exec.
+
+Usage:
+  bp eval '<expression>'        Evaluate inline JavaScript
+  bp eval -f <file>             Evaluate JavaScript from a file
+  echo '<expr>' | bp eval       Evaluate from stdin
+
+Local options:
+  -f, --file <path>     Read JavaScript from a file
+  --wrap                Wrap the expression in an async IIFE
+
+Global options:
+  -s, --session <id>    Session to use (default: most recent)
+  --json                Output JSON
+  --pretty              Output readable text (default)
+  --debug               Enable CDP transport debugging
+  -h, --help            Show this help
+
+Examples:
+  bp eval 'document.title'
+  bp eval 'document.querySelectorAll("a").length'
+  bp eval -f scrape.js
+  bp eval --wrap 'await fetch("/health").then((r) => r.status)'
+`.trimEnd();
+function parseEvalArgs(args) {
+  const options = {};
+  let expression;
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "-f" || arg === "--file") {
+      options.file = args[++i];
+    } else if (arg === "--wrap") {
+      options.wrap = true;
+    } else if (!expression && !arg.startsWith("-")) {
+      expression = arg;
+    }
+  }
+  return { expression, options };
+}
+function normalizeEvalExpression(expression, wrap = false) {
+  const trimmed = expression.trim();
+  const needsWrap = wrap || trimmed.includes("=>") || /\bawait\b/.test(trimmed);
+  if (!needsWrap) {
+    return trimmed;
+  }
+  if (wrap || /\bawait\b/.test(trimmed)) {
+    return `(async () => (${trimmed}))()`;
+  }
+  return `(() => (${trimmed}))()`;
+}
+async function evalCommand(args, globalOptions) {
+  if (globalOptions.help) {
+    console.log(EVAL_HELP);
+    return;
+  }
+  const { expression: argExpression, options: evalOptions } = parseEvalArgs(args);
+  let expression = argExpression;
+  if (evalOptions.file) {
+    const fs9 = await import("fs/promises");
+    expression = await fs9.readFile(evalOptions.file, "utf-8");
+  }
+  if (!expression && !process.stdin.isTTY) {
+    const chunks = [];
+    for await (const chunk of process.stdin) {
+      chunks.push(chunk);
     }
-    if (options.topCommand === "geolocation") {
-      if (!options.geoAction) {
-        throw new Error("geolocation command requires: set or clear");
-      }
-      await runGeolocationCommand(options.geoAction, options, page, session);
-      await updateSession(session.id, {
-        metadata: {
-          env: {
-            ...existingEnv,
-            geolocation: options.geoAction === "clear" ? void 0 : {
-              latitude: options.lat,
-              longitude: options.lon,
-              accuracy: options.accuracy ?? 1
-            }
-          }
-        }
-      });
-      return;
+    expression = Buffer.concat(chunks).toString("utf-8").trim();
+  }
+  if (!expression) {
+    throw new Error(
+      "No expression provided.\n\nUsage:\n  bp eval 'document.title'\n  bp eval -f script.js\n  echo 'document.title' | bp eval"
+    );
+  }
+  const session = await resolveSession(globalOptions.session);
+  const { browser, page } = await attachSession(session, { trace: globalOptions.trace });
+  try {
+    const step = {
+      action: "evaluate",
+      value: normalizeEvalExpression(expression, evalOptions.wrap)
+    };
+    const result = await page.batch([step]);
+    const stepResult = result.steps[0];
+    if (!stepResult.success) {
+      throw new Error(stepResult.error ?? "Evaluation failed");
     }
-    throw new Error("Unknown env command. Run bp env --help for usage.");
+    output(
+      globalOptions.format === "json" ? { success: true, result: stepResult.result } : stepResult.result,
+      globalOptions.format
+    );
+    await updateSession(session.id, { currentUrl: await page.url() });
   } finally {
     await browser.disconnect();
   }
@@ -3819,14 +4320,10 @@ Usage:
   bp exec -f <file>             Execute action(s) from a JSON file
   echo '<json>' | bp exec       Execute action(s) from stdin
 
-Options:
-  -f, --file <path>    Read actions from a JSON file
-  -o, --output <path>  Write command output to a file instead of stdout
-  --dialog <mode>      Handle native dialogs: accept | dismiss
-  -s, --session <id>   Session to use (default: most recent)
-  -f, --format <fmt>   Output format: json | pretty (default: pretty)
-  --json               Alias for -f json
-  --debug              Enable CDP transport debugging (global option)
+Local options:
+  -f, --file <path>     Read actions from a JSON file
+  -o, --output <path>   Write command output to a file instead of stdout
+  --dialog <mode>       Handle native dialogs: accept | dismiss
 
 Recording:
   --record                    Enable screenshot recording
@@ -3836,6 +4333,11 @@ Recording:
   --no-highlights             Disable visual highlights on screenshots
                               Sensitive fields (passwords, OTPs, card inputs) are redacted
 
+Global options:
+  -s, --session <id>   Session to use (default: most recent)
+  --json               Output JSON
+  --pretty             Output readable text (default)
+  --debug              Enable CDP transport debugging
   -h, --help           Show this help
 
 Examples:
@@ -4062,6 +4564,22 @@ Run 'bp actions' for complete action reference.${evalTip}`
           data: stepResult.result
         });
       }
+      if (stepResult.outcomeStatus) {
+        logger.logTrace({
+          channel: "action",
+          event: `action.outcome.${stepResult.outcomeStatus}`,
+          summary: `Outcome: ${stepResult.outcomeStatus}${stepResult.retrySafe === false ? " (unsafe to retry)" : ""}`,
+          data: {
+            outcomeStatus: stepResult.outcomeStatus,
+            retrySafe: stepResult.retrySafe,
+            matchedConditions: stepResult.matchedConditions?.map((mc) => ({
+              kind: mc.condition.kind,
+              matched: mc.matched,
+              detail: mc.detail
+            }))
+          }
+        });
+      }
     }
     if (result.recordingManifest && session.exportLog) {
       mirrorRecordingToExport(result.recordingManifest, session.exportLog);
@@ -4103,7 +4621,10 @@ Run 'bp actions' for complete action reference.${evalTip}`
       selectorUsed: s.selectorUsed,
       error: s.error,
       text: s.text,
-      result: s.result
+      result: s.result,
+      ...s.outcomeStatus !== void 0 ? { outcomeStatus: s.outcomeStatus } : {},
+      ...s.matchedConditions !== void 0 ? { matchedConditions: s.matchedConditions } : {},
+      ...s.retrySafe !== void 0 ? { retrySafe: s.retrySafe } : {}
     }));
     const payload = {
       success: result.success,
@@ -4213,19 +4734,29 @@ function formatInteractiveElementsPretty(elements, limit = elements.length) {
 var FORMS_HELP = `
 bp forms - List form controls on the current page
 
+When to use:
+  You need field names, types, values, or disabled state without the rest of the page.
+
+When not to use:
+  You need clickable refs or a broader page summary. Use \`bp snapshot -i\` or \`bp page\`.
+
 Usage:
   bp forms [options]
 
-Options:
+Global options:
   -s, --session <id>   Session to use (default: most recent)
-  -f, --format <fmt>   json | pretty (default: pretty)
-  --json               Alias for -f json
-  --trace              Enable debug tracing
+  --json               Output JSON
+  --pretty             Output readable text (default)
+  --debug              Enable CDP transport debugging
   -h, --help           Show this help
 
 Examples:
   bp forms
   bp forms --json
+
+Likely next commands:
+  bp exec '[{"action":"fill","selector":"ref:e4","value":"..."}]'
+  bp review --json
 `.trimEnd();
 async function formsCommand(_args, globalOptions) {
   if (globalOptions.help) {
@@ -4262,11 +4793,14 @@ Usage:
   bp list -s <id> --log-path       Print path to session log file (for analysis)
 
 Options:
-  -s, --session <id>    Target session (or uses default session)
   --info                Show session details and log statistics
   --log-tail [n]        Show last n action log entries (default: 20)
   --log-path            Print absolute path to log.jsonl file
-  -f json, --json       Machine-readable JSON output
+
+Global options:
+  -s, --session <id>    Target session (or uses default session)
+  --json                Machine-readable JSON output
+  --pretty              Output readable text (default)
   -h, --help            Show this help
 
 Examples:
@@ -4448,7 +4982,11 @@ When to use:
   You want a quick summary of URL, title, headings, forms, and interactive controls.
 
 When not to use:
-  You need the full accessibility tree or reusable refs for precise automation. Use \`bp snapshot\`.
+  You need the full accessibility tree or the full ref inventory for precise automation. Use \`bp snapshot\`.
+
+Common mistake:
+  Treating \`bp page\` as exhaustive. It is a compact overview; the Actions section caches reusable refs,
+  but use \`bp snapshot -i\` when you need the full actionable surface.
 
 Likely next commands:
   bp snapshot -i
@@ -4458,11 +4996,11 @@ Likely next commands:
 Usage:
   bp page [options]
 
-Options:
+Global options:
   -s, --session <id>   Session to use (default: most recent)
-  -f, --format <fmt>   json | pretty (default: pretty)
-  --json               Alias for -f json
-  --trace              Enable debug tracing
+  --json               Output JSON
+  --pretty             Output readable text (default)
+  --debug              Enable CDP transport debugging
   -h, --help           Show this help
 
 Examples:
@@ -4530,7 +5068,16 @@ async function pageCommand(_args, globalOptions) {
       globalOptions.format === "json" ? summary : formatPageSummary(summary),
       globalOptions.format
     );
-    await updateSession(session.id, { currentUrl: url });
+    await updateSession(session.id, {
+      currentUrl: url,
+      metadata: {
+        refCache: {
+          url,
+          savedAt: (/* @__PURE__ */ new Date()).toISOString(),
+          refMap: page.exportRefMap()
+        }
+      }
+    });
   } finally {
     await browser.disconnect();
   }
@@ -4541,14 +5088,14 @@ var QUICKSTART = `
 browser-pilot CLI - Quick Start Guide
 
 STEP 1: CONNECT TO A BROWSER
-  bp connect --provider generic --name mysite
+  bp connect --name mysite
 
   This creates a session. The CLI remembers it for subsequent commands.
 
 STEP 2: NAVIGATE
-  bp exec '{"action":"goto","url":"https://example.com"}'
+  bp exec -s mysite '{"action":"goto","url":"https://example.com"}'
 
-STEP 3: GET PAGE SNAPSHOT
+STEP 3: CHOOSE THE RIGHT INSPECTION COMMAND
   bp snapshot -i
 
   Shows only interactive elements (buttons, inputs, links) with refs:
@@ -4556,39 +5103,48 @@ STEP 3: GET PAGE SNAPSHOT
     textbox "Email" ref:e3
     link "Forgot password?" ref:e6
 
-  Other formats:
-    bp snapshot --format text    # Full accessibility tree (all elements)
-    bp snapshot --json           # Full snapshot as JSON
+  Other inspection commands:
+    bp page                # Compact overview: URL, title, headings, forms, actions
+    bp text                # Readable page copy or policy text
+    bp review --json       # Structured business state after actions
+    bp diagnose 'submit'   # Debug selector or targeting failures
 
 STEP 4: INTERACT USING REFS
-  bp exec '{"action":"fill","selector":"ref:e3","value":"test@example.com"}'
-  bp exec '{"action":"click","selector":"ref:e2"}'
+  bp exec -s mysite '{"action":"fill","selector":"ref:e3","value":"test@example.com"}'
+  bp exec -s mysite '{"action":"click","selector":"ref:e2"}'
 
 STEP 5: BATCH MULTIPLE ACTIONS
-  bp exec '[
+  bp exec -s mysite '[
     {"action":"fill","selector":"ref:e3","value":"user@test.com"},
     {"action":"click","selector":"ref:e2"},
     {"action":"snapshot"}
   ]'
 
 FOR AI AGENTS
-  Use bp snapshot -i for most workflows - shows only actionable elements.
+  Start with:
+    bp --help
+    bp --version
+
+  Use bp snapshot -i for most workflows - it shows actionable elements.
   Add --json for machine-readable output:
-    bp snapshot -i --json
-    bp exec '{"action":"click","selector":"ref:e3"}' --json
+    bp snapshot -i -s mysite --json
+    bp exec -s mysite '{"action":"click","selector":"ref:e3"}' --json
 
 PAGE DISCOVERY SHORTCUTS
-  bp page              # URL, title, headings, forms, and interactive controls
-  bp forms             # Structured list of form fields only
-  bp targets           # All available browser tabs
-  bp connect --new-tab --url https://example.com
-                      # Start from a fresh tab instead of reusing one
+  bp page                           # URL, title, headings, forms, and interactive controls
+  bp forms                          # Structured list of form fields only
+  bp text --selector '#main'        # Focused readable text extraction
+  bp review --json                  # Structured business state
+  bp targets                        # All available browser tabs
+  bp connect --new-tab --page-url https://example.com
+                                   # Convenience: start from a fresh tab
 
 TIPS
-  \u2022 Refs (e1, e2...) are stable within a page - prefer them over CSS selectors
-  \u2022 After navigation, take a new snapshot to get updated refs
-  \u2022 Use multi-selectors for resilience: ["ref:e3", "#email", "input[type=email]"]
-  \u2022 Add "optional":true to skip elements that may not exist
+  - Refs (e1, e2...) are stable within the current page state
+  - After navigation or major DOM changes, take a new snapshot to refresh refs
+  - Use multi-selectors for resilience: ["ref:e3", "#email", "input[type=email]"]
+  - Add "optional":true to skip elements that may not exist
+  - Use bp eval only as an escape hatch when higher-level commands are insufficient
 
 SELECTOR PRIORITY
   1. ref:e5         From snapshot - most reliable
@@ -5478,20 +6034,24 @@ var Recorder = class {
       awaitPromise: false
     });
     this.bindingHandler = (params) => {
+      const payload = readString(params["payload"]);
+      if (!payload) {
+        return;
+      }
       if (params["name"] === RECORDER_BINDING_NAME) {
-        this.handleBindingCall(params["payload"]);
+        this.handleBindingCall(payload);
       } else if (params["name"] === TRACE_BINDING_NAME) {
-        this.handleTraceBindingCall(params["payload"]);
+        this.handleTraceBindingCall(payload);
       }
     };
     this.cdp.on("Runtime.bindingCalled", this.bindingHandler);
     this.subscribeTrace("Runtime.consoleAPICalled", (params) => {
-      const type = String(params["type"] ?? "log");
+      const type = readStringOr(params["type"], "log");
       if (type !== "log" && type !== "warn" && type !== "error") {
         return;
       }
       const args = Array.isArray(params["args"]) ? params["args"] : [];
-      const text = args.map((entry) => String(entry["value"] ?? entry["description"] ?? "")).filter(Boolean).join(" ");
+      const text = args.map(formatConsoleArg).filter(Boolean).join(" ");
       this.traceEvents.push(
         normalizeTraceEvent({
           traceId: createTraceId("console"),
@@ -5517,7 +6077,7 @@ var Recorder = class {
           channel: "runtime",
           event: "runtime.exception",
           severity: "error",
-          summary: String(details["text"] ?? "Runtime exception"),
+          summary: readString(details["text"]) ?? "Runtime exception",
           data: details,
           url: this.startUrl
         })
@@ -5758,6 +6318,7 @@ var Recorder = class {
       this.subscribeNetwork("Network.webSocketClosed", (params) => {
         const requestId = params["requestId"];
         if (!this.wsUrls.has(requestId)) return;
+        const url = this.wsUrls.get(requestId);
         this.wsUrls.delete(requestId);
         const now = Date.now();
         this.wsEvents.push({
@@ -5775,10 +6336,10 @@ var Recorder = class {
             event: "ws.connection.closed",
             severity: "warn",
             summary: `WebSocket closed ${requestId}`,
-            data: { url: this.wsUrls.get(requestId) ?? null },
+            data: { url: url ?? null },
             connectionId: requestId,
             requestId,
-            url: this.wsUrls.get(requestId)
+            url
           })
         );
       });
@@ -5940,11 +6501,6 @@ var Recorder = class {
     return entries;
   }
 };
-function globToRegex(pattern) {
-  const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&");
-  const withWildcards = escaped.replace(/\*/g, ".*");
-  return new RegExp(`^${withWildcards}$`);
-}
 
 // src/cli/commands/record.ts
 var RECORD_HELP = `
@@ -6074,10 +6630,14 @@ async function resolveConnection3(sessionId, useLatestSession, debug) {
   }
   let wsUrl;
   try {
-    wsUrl = await getBrowserWebSocketUrl("localhost:9222");
-  } catch {
+    wsUrl = (await resolveCLIEndpoint()).wsUrl;
+  } catch (error) {
     throw new Error(
-      "Could not auto-discover browser.\nEither start Chrome with --remote-debugging-port=9222 or pass -s to reuse a session."
+      formatBrowserDiscoveryError(error, {
+        explicitHint: "  - Create a session first: bp connect --browser-url <ws-url>",
+        reuseSessionHint: "bp record -s <session-id>",
+        latestSessionHint: "bp record -s"
+      })
     );
   }
   const browser = await connect({
@@ -6216,7 +6776,9 @@ async function runRecordCapture(args, globalOptions) {
   const canonicalPath = join9(sessionDir, DEFAULT_ARTIFACT);
   const outputPath = resolve5(args.file ?? DEFAULT_ARTIFACT);
   nodeFs2.mkdirSync(screenshotDir, { recursive: true });
-  const existingArtifact = existsSync6(canonicalPath) ? canonicalizeRecordingArtifact(JSON.parse(nodeFs2.readFileSync(canonicalPath, "utf-8"))) : null;
+  const existingArtifact = existsSync6(canonicalPath) ? canonicalizeRecordingArtifact(
+    JSON.parse(nodeFs2.readFileSync(canonicalPath, "utf-8"))
+  ) : null;
   const recordingFrames = existingArtifact ? artifactToFrames(existingArtifact) : [];
   let listenConfig = {
     mode: typeof args.listen === "string" ? args.listen : "all",
@@ -6340,7 +6902,9 @@ async function runRecordCapture(args, globalOptions) {
         console.log(`Use: bp record summary ${outputPath}`);
       }
     } catch (error) {
-      console.error(`Error saving recording: ${error instanceof Error ? error.message : String(error)}`);
+      console.error(
+        `Error saving recording: ${error instanceof Error ? error.message : String(error)}`
+      );
       process.exit(1);
     }
   };
@@ -6457,6 +7021,114 @@ async function recordCommand(args, globalOptions) {
   }
 }
 
+// src/cli/commands/review.ts
+var REVIEW_HELP = `
+bp review - Extract structured business state from the current page
+
+When to use:
+  You want a structured summary of the page: headings, forms, alerts, tables,
+  key-value pairs, and status labels. Useful for verifying business state after
+  an action sequence, especially on detail, checkout, and confirmation pages.
+
+When not to use:
+  You need the full accessibility tree with refs. Use \`bp snapshot\`.
+  You want a compact overview. Use \`bp page\`.
+  You are on a dense catalog or marketing page with lots of nav chrome. Use \`bp text\` or \`bp page\`.
+
+Likely next commands:
+  bp snapshot -i
+  bp exec '[{"action":"click","selector":"ref:e4"}]'
+
+Usage:
+  bp review [options]
+
+Global options:
+  -s, --session <id>   Session to use (default: most recent)
+  --json               Output JSON
+  --pretty             Output readable text (default)
+  --debug              Enable CDP transport debugging
+  -h, --help           Show this help
+
+Examples:
+  bp review
+  bp review --json
+  bp review -s my-session
+`.trimEnd();
+function formatReviewPretty(review) {
+  const lines = [];
+  lines.push(`URL: ${review.url}`);
+  lines.push(`Title: ${review.title}`);
+  lines.push("", "Headings:");
+  if (review.headings.length === 0) {
+    lines.push("  (none)");
+  } else {
+    for (const h of review.headings) {
+      lines.push(`  ${h}`);
+    }
+  }
+  if (review.alerts.length > 0) {
+    lines.push("", "Alerts:");
+    for (const a of review.alerts) {
+      lines.push(`  ${a}`);
+    }
+  }
+  if (review.statusLabels.length > 0) {
+    lines.push("", "Status:");
+    for (const s of review.statusLabels) {
+      lines.push(`  ${s}`);
+    }
+  }
+  if (review.keyValues.length > 0) {
+    lines.push("", "Key-Value Pairs:");
+    for (const kv of review.keyValues) {
+      lines.push(`  ${kv.key}: ${kv.value}`);
+    }
+  }
+  if (review.tables.length > 0) {
+    lines.push("", "Tables:");
+    for (const table of review.tables) {
+      if (table.headers.length > 0) {
+        lines.push(`  | ${table.headers.join(" | ")} |`);
+        lines.push(`  | ${table.headers.map(() => "---").join(" | ")} |`);
+      }
+      for (const row of table.rows) {
+        lines.push(`  | ${row.join(" | ")} |`);
+      }
+      lines.push("");
+    }
+  }
+  lines.push("", "Forms:");
+  if (review.forms.length === 0) {
+    lines.push("  (none)");
+  } else {
+    for (const f of review.forms) {
+      const disabled = f.disabled ? " (disabled)" : "";
+      const label = f.label ?? "(unlabeled)";
+      lines.push(`  ${label} [${f.type}]: ${f.value ?? ""}${disabled}`);
+    }
+  }
+  return lines.join("\n");
+}
+async function reviewCommand(_args, globalOptions) {
+  if (globalOptions.help) {
+    process.stdout.write(`${REVIEW_HELP}
+`);
+    return;
+  }
+  const session = await resolveSession(globalOptions.session);
+  const { browser, page } = await attachSession(session, { trace: globalOptions.trace });
+  try {
+    const review = await page.review();
+    output(
+      globalOptions.format === "json" ? review : formatReviewPretty(review),
+      globalOptions.format
+    );
+    await updateSession(session.id, { currentUrl: review.url });
+  } finally {
+    await browser.disconnect();
+  }
+}
+
 // src/cli/commands/run.ts
 import { readFile } from "fs/promises";
 import { resolve as resolve6 } from "path";
@@ -6599,17 +7271,26 @@ ${result.success ? "Workflow passed" : "Workflow failed"} in ${result.totalDurat
 var SCREENSHOT_HELP = `
 bp screenshot - Take a screenshot of the current page
 
+When to use:
+  You need a visual artifact, regression evidence, or a screenshot to attach elsewhere.
+
+When not to use:
+  You need readable copy or structured business data. Use \`bp text\`, \`bp page\`, or \`bp review\`.
+
 Usage:
   bp screenshot [options]
 
-Options:
+Local options:
   -o, --output <path>    Save screenshot to file (default: print base64 to stdout)
   -f, --format <type>    Image format: png | jpeg | webp (default: png)
   -q, --quality <n>      Image quality 0-100 (jpeg/webp only)
   --full-page            Capture the full scrollable page
+
+Global options:
   -s, --session <id>     Session to use (default: most recent)
-  --json                 Output as JSON (base64 data + metadata)
-  --trace                Enable debug tracing
+  --json                 Output JSON (base64 data + metadata)
+  --pretty               Output readable text for file writes (default)
+  --debug                Enable CDP transport debugging
   -h, --help             Show this help
 
 Examples:
@@ -6955,23 +7636,27 @@ Common mistake:
 Usage:
   bp snapshot [options]
 
-Options:
-  -i, --interactive      Show only interactive elements (buttons, inputs, links)
-  -f, --format <type>    Output format: full | interactive | text (default: text)
-  --role <roles>         Filter snapshot to accessibility roles (for example: radio,checkbox)
-  -o, --output <path>    Write command output to a file instead of stdout
-  -d, --diff <file>      Compare current page against a saved snapshot JSON
-  --inspect              Inject visual ref labels onto the page (auto-removes after 10s)
-  --keep                 Keep visual ref labels visible (use with --inspect)
-  -s, --session <id>     Session to use (default: most recent)
-  -f, --format <fmt>     Output format: json | pretty (default: pretty)
-  --json                 Alias for -f json
-  --debug                Enable CDP transport debugging (global option)
-  -h, --help             Show this help
+Local options:
+  -i, --interactive       Shortcut for --view interactive
+  --view <type>           Snapshot view: full | interactive | text (default: text)
+  -f, --format <type>     Backward-compatible alias for --view
+  --role <roles>          Filter snapshot to accessibility roles (for example: radio,checkbox)
+  -o, --output <path>     Write command output to a file instead of stdout
+  -d, --diff <file>       Compare current page against a saved snapshot JSON
+  --inspect               Inject visual ref labels onto the page (auto-removes after 10s)
+  --keep                  Keep visual ref labels visible (use with --inspect)
+
+Global options:
+  -s, --session <id>      Session to use (default: most recent)
+  --json                  Output JSON; without --view this returns the full snapshot payload
+  --pretty                Output readable text (default)
+  --debug                 Enable CDP transport debugging
+  -h, --help              Show this help
 
 Examples:
   bp snapshot                       # Full accessibility tree as readable text
   bp snapshot -i                    # Interactive elements only; best default for automation
+  bp snapshot --view full           # Full structured snapshot
   bp snapshot --role radio,checkbox # Focus on specific control roles
   bp snapshot --json > page.json    # Save full snapshot to file
   bp snapshot --diff before.json    # Show what changed since before.json
@@ -6988,7 +7673,7 @@ function parseSnapshotArgs(args) {
   };
   for (let i = 0; i < args.length; i++) {
     const arg = args[i];
-    if (arg === "--format" || arg === "-f") {
+    if (arg === "--view" || arg === "--format" || arg === "-f") {
       options.format = args[++i];
       options.formatExplicit = true;
     } else if (arg === "--diff" || arg === "-d") {
@@ -7121,11 +7806,11 @@ bp targets - List page tabs available in the connected browser
 Usage:
   bp targets [options]
 
-Options:
+Global options:
   -s, --session <id>   Session to use (default: most recent)
-  -f, --format <fmt>   json | pretty (default: pretty)
-  --json               Alias for -f json
-  --trace              Enable debug tracing
+  --json               Output JSON
+  --pretty             Output readable text (default)
+  --debug              Enable CDP transport debugging
   -h, --help           Show this help
 
 Examples:
@@ -7190,28 +7875,31 @@ Common mistake:
 Usage:
   bp text [options]
 
-Options:
-  --selector <sel>     Extract text from a specific element (default: entire page)
-  -s, --session <id>   Session to use (default: most recent)
-  -f, --format <fmt>   Output format: json | pretty (default: pretty)
-  --json               Alias for -f json
-  --debug              Enable CDP transport debugging (global option)
-  -h, --help           Show this help
+Local options:
+  --selector <selector>  Extract text from a specific element (default: entire page)
+
+Global options:
+  -s, --session <id>     Session to use (default: most recent)
+  --json                 Output JSON with text, URL, and selector
+  --pretty               Output readable text only (default)
+  --debug                Enable CDP transport debugging
+  -h, --help             Show this help
 
 Examples:
   bp text                          # Extract all text from the page
   bp text --selector '#main'       # Extract text from #main element only
-  bp text --json                   # Output as JSON with URL and selector info
+  bp text -s dev --json            # Output JSON with URL and selector info
 
 Likely next commands:
   bp snapshot -i
+  bp review --json
   bp exec '[{"action":"assertText","expect":"..."}]'
 `.trimEnd();
 function parseTextArgs(args) {
   const options = {};
   for (let i = 0; i < args.length; i++) {
     const arg = args[i];
-    if (arg === "--selector" || arg === "-s") {
+    if (arg === "--selector") {
       options.selector = args[++i];
     } else if (arg === "-h" || arg === "--help") {
       options.help = true;
@@ -7219,6 +7907,9 @@ function parseTextArgs(args) {
   }
   return options;
 }
+function looksLikeSelector(value) {
+  return value.startsWith("#") || value.startsWith(".") || value.startsWith("[") || value.startsWith("/") || value.startsWith("ref:") || value.includes(">");
+}
 async function textCommand(args, globalOptions) {
   const options = parseTextArgs(args);
   if (options.help || globalOptions.help) {
@@ -7227,7 +7918,18 @@ async function textCommand(args, globalOptions) {
   }
   let session;
   if (globalOptions.session) {
-    session = await loadSession(globalOptions.session);
+    try {
+      session = await loadSession(globalOptions.session);
+    } catch (error) {
+      if (!options.selector && looksLikeSelector(globalOptions.session)) {
+        throw new Error(
+          `bp text uses --selector for element targeting. "-s" is reserved for sessions.
+
+Try: bp text --selector ${JSON.stringify(globalOptions.session)}`
+        );
+      }
+      throw error;
+    }
   } else {
     session = await getDefaultSession();
     if (!session) {
@@ -7464,7 +8166,12 @@ function evaluateWatchAssertion(events, assertion, view) {
   };
 }
 async function traceStart(options, globalOptions) {
-  const events = await runLiveTrace(globalOptions.session, options, globalOptions.trace ?? false, "start");
+  const events = await runLiveTrace(
+    globalOptions.session,
+    options,
+    globalOptions.trace ?? false,
+    "start"
+  );
   output(
     {
       success: true,
@@ -7545,7 +8252,10 @@ async function traceMerge(options, globalOptions) {
   };
   fs8.mkdirSync(dirname8(resolve7(options.output)), { recursive: true });
   fs8.writeFileSync(resolve7(options.output), JSON.stringify(payload, null, 2));
-  output({ success: true, output: resolve7(options.output), events: merged.length }, globalOptions.format ?? "pretty");
+  output(
+    { success: true, output: resolve7(options.output), events: merged.length },
+    globalOptions.format ?? "pretty"
+  );
 }
 async function traceCommand(args, globalOptions) {
   const options = parseTraceArgs(args);
@@ -7577,74 +8287,77 @@ async function traceCommand(args, globalOptions) {
   }
 }
 
+// src/cli/version.ts
+import { readFileSync as readFileSync9 } from "fs";
+var cachedCliVersion;
+function getCliVersion() {
+  if (cachedCliVersion) {
+    return cachedCliVersion;
+  }
+  cachedCliVersion = "0.0.17";
+  return cachedCliVersion;
+}
+
 // src/cli/index.ts
-var HELP2 = `
+function buildRootHelp() {
+  const routeLabelWidth = Math.max(...CLI_ROUTE_GROUPS.map((group) => group.label.length)) + 2;
+  const routeLines = CLI_ROUTE_GROUPS.map((group) => {
+    const note = group.note ? `  ${group.note}` : "";
+    return `  ${group.label.padEnd(routeLabelWidth)}${group.commands.join(", ")}${note}`;
+  });
+  const commandLabelWidth = Math.max(...ROOT_HELP_COMMANDS.map((command) => command.name.length)) + 2;
+  const commandLines = ROOT_HELP_COMMANDS.map((command) => {
+    return `  ${command.name.padEnd(commandLabelWidth)}${command.description}`;
+  });
+  return `
 bp - automation-first browser CLI for agents
 
 Route the job first:
-  Inspect page state              snapshot, page, forms, text, targets, diagnose
-  Act in the browser              exec, run
-  Capture a human demo            record
-  Analyze behavior over time      trace   (listen is a compatibility alias)
-  Exercise voice/media            audio
-  Change browser conditions       env
+${routeLines.join("\n")}
 
 Usage:
   bp <command> [options]
 
 Commands:
-  quickstart  Getting started guide
-  connect     Create a browser session
-  exec        Execute high-level actions
-  snapshot    Inspect current page with refs
-  record      Record a human workflow and derive replayable output
-  trace       Inspect and analyze behavior over time (listen alias for live stream)
-  audio       Set up/validate/inject/capture voice pipelines
-  env         Session and browser-environment controls
-  run         Run a workflow file
-  page        Compact page overview
-  forms       List form controls
-  targets     List available browser tabs
-  daemon      Manage session daemon
-  list        List sessions
-  close       Close session
-  clean       Clean old sessions and artifacts
-  actions     Complete action reference
+${commandLines.join("\n")}
 
 Golden paths:
-  1. Automate a page
-     bp connect --provider generic --name dev
+  1. Connect, open a page, inspect it, then act
+     bp connect --name dev
+     bp exec -s dev '{"action":"goto","url":"https://example.com"}'
      bp snapshot -i -s dev
      bp exec -s dev '[{"action":"click","selector":"ref:e4"}]'
 
-  2. Capture a manual workflow and derive automation
+  2. Read content or verify business state
+     bp text -s dev --selector main
+     bp review -s dev --json
+
+  3. Capture a manual workflow and derive automation
      bp record -s demo --profile automation
      bp record summary demo/recording.json
      bp record derive demo/recording.json -o workflow.json
      bp run workflow.json
 
-  3. Debug a realtime or voice session
+  4. Debug a realtime or voice session
      bp trace start -s dev
      bp trace summary -s dev --view ws
      bp audio check -s dev
      bp trace summary -s dev --view voice
 
-  4. Exercise failure modes
-     bp env network offline -s dev --duration 10000
-     bp trace watch -s dev --view ws --assert profile:reconnect --timeout 15000
-
 Options:
   -s, --session <id>    Session ID
   -f, --format <fmt>    json | pretty (default: pretty)
   --json                Alias for -f json
+  --pretty              Alias for -f pretty
   --debug               Enable debug logs for CDP transport
   --trace               Legacy alias for --debug
-  --dialog <mode>       Handle dialogs: accept | dismiss
   -h, --help            Show help
+  --version             Print CLI version
 
 Notes:
   Start with "record summary" or "trace summary" before opening raw artifacts.
-`;
+`.trim();
+}
 function parseGlobalOptions(args) {
   const options = {
     format: "pretty"
@@ -7720,14 +8433,28 @@ function prettyPrint(obj, lines, indent = 0) {
 }
 async function main() {
   const args = process.argv.slice(2);
-  if (args.length === 0) {
-    console.log(HELP2);
+  if (args.length === 0 || args.length === 1 && (args[0] === "--help" || args[0] === "-h" || args[0] === "help")) {
+    console.log(buildRootHelp());
+    process.exit(0);
+  }
+  if (args.length === 1 && (args[0] === "--version" || args[0] === "version")) {
+    process.stdout.write(`${getCliVersion()}
+`);
     process.exit(0);
   }
-  const command = args[0];
-  const { options, remaining } = parseGlobalOptions(args.slice(1));
+  let command = args[0];
+  let commandArgs = args.slice(1);
+  if (command === "help") {
+    if (commandArgs.length === 0) {
+      console.log(buildRootHelp());
+      process.exit(0);
+    }
+    command = commandArgs[0];
+    commandArgs = [...commandArgs.slice(1), "--help"];
+  }
+  const { options, remaining } = parseGlobalOptions(commandArgs);
   if (options.help && !command) {
-    console.log(HELP2);
+    console.log(buildRootHelp());
     process.exit(0);
   }
   try {
@@ -7783,6 +8510,9 @@ async function main() {
       case "record":
         await recordCommand(remaining, options);
         break;
+      case "review":
+        await reviewCommand(remaining, options);
+        break;
       case "trace":
         await traceCommand(remaining, options);
         break;
@@ -7801,11 +8531,12 @@ async function main() {
       case "help":
       case "--help":
       case "-h":
-        console.log(HELP2);
+        console.log(buildRootHelp());
         break;
       default:
         console.error(`Unknown command: ${command}`);
-        console.log(HELP2);
+        console.error('Run "bp --help" to see the available command tree.');
+        console.log(buildRootHelp());
         process.exit(1);
     }
   } catch (error) {