browser-pilot 0.0.14 → 0.0.16

package/dist/cli.mjs

@@ -1,18 +1,32 @@
 #!/usr/bin/env bun
+import {
+  BrowserEndpointResolutionError,
+  connect,
+  resolveBrowserEndpoint
+} from "./chunk-TJ5B56NV.mjs";
+import "./chunk-LCNFBXB5.mjs";
 import {
   DEEP_QUERY_SCRIPT,
+  LiveTraceCollector,
   SENSITIVE_AUTOCOMPLETE_TOKENS,
+  TRACE_BINDING_NAME,
+  TRACE_SCRIPT,
   addBatchToPage,
-  connect,
+  buildTraceSummaries,
+  buildTraceSummary,
+  canonicalizeRecordingArtifact,
+  createRecordingManifest,
+  createTraceId,
   fuzzyMatchElements,
-  getBrowserWebSocketUrl,
+  grantAudioPermissions,
+  normalizeTraceEvent,
   pcmToWav,
   redactValueForRecording,
   validateSteps
-} from "./chunk-7NDR6V7S.mjs";
+} from "./chunk-6GBYX7C2.mjs";
 import {
   isRecord
-} from "./chunk-SPSZZH22.mjs";
+} from "./chunk-DTVRFXKI.mjs";
 import {
   DAEMON_MAX_AGE_MS,
   DAEMON_READY_TIMEOUT_MS
@@ -345,28 +359,99 @@ Content-Type: ${contentType}\r
   parts.push(data);
 }
 
-// src/cli/session.ts
+// src/trace/store.ts
+import * as fs from "fs";
 import { homedir } from "os";
-import { join } from "path";
+import { dirname, join, resolve } from "path";
+var TRACE_FILE_NAME = "trace.jsonl";
 var SESSION_DIR = join(homedir(), ".browser-pilot", "sessions");
+function getSessionTracePath(sessionId) {
+  return join(SESSION_DIR, sessionId, TRACE_FILE_NAME);
+}
+function readTraceEvents(path) {
+  const resolved = resolve(path);
+  if (!fs.existsSync(resolved)) {
+    return [];
+  }
+  const content = fs.readFileSync(resolved, "utf-8").trim();
+  if (!content) {
+    return [];
+  }
+  return content.split("\n").map((line) => {
+    try {
+      return JSON.parse(line);
+    } catch {
+      return null;
+    }
+  }).filter((event) => event !== null);
+}
+
+// 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 { join as join2 } from "path";
+var SESSION_DIR2 = join2(homedir2(), ".browser-pilot", "sessions");
 function getSessionFilePath(id) {
-  return join(SESSION_DIR, `${id}.json`);
+  return join2(SESSION_DIR2, `${id}.json`);
 }
 async function ensureSessionDir() {
-  const fs7 = await import("fs/promises");
-  await fs7.mkdir(SESSION_DIR, { recursive: true });
+  const fs9 = await import("fs/promises");
+  await fs9.mkdir(SESSION_DIR2, { recursive: true });
 }
 async function saveSession(session) {
   await ensureSessionDir();
-  const fs7 = await import("fs/promises");
-  const filePath = join(SESSION_DIR, `${session.id}.json`);
-  await fs7.writeFile(filePath, JSON.stringify(session, null, 2));
+  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 fs7 = await import("fs/promises");
-  const filePath = join(SESSION_DIR, `${id}.json`);
+  const fs9 = await import("fs/promises");
+  const filePath = join2(SESSION_DIR2, `${id}.json`);
   try {
-    const content = await fs7.readFile(filePath, "utf-8");
+    const content = await fs9.readFile(filePath, "utf-8");
     return JSON.parse(content);
   } catch (error) {
     if (error.code === "ENOENT") {
@@ -388,10 +473,10 @@ async function updateSession(id, updates) {
   return updated;
 }
 async function deleteSession(id) {
-  const fs7 = await import("fs/promises");
-  const filePath = join(SESSION_DIR, `${id}.json`);
+  const fs9 = await import("fs/promises");
+  const filePath = join2(SESSION_DIR2, `${id}.json`);
   try {
-    await fs7.unlink(filePath);
+    await fs9.unlink(filePath);
   } catch (error) {
     if (error.code !== "ENOENT") {
       throw error;
@@ -399,18 +484,18 @@ async function deleteSession(id) {
   }
 }
 async function deleteSessionFull(id) {
-  const fs7 = await import("fs/promises");
-  const filePath = join(SESSION_DIR, `${id}.json`);
+  const fs9 = await import("fs/promises");
+  const filePath = join2(SESSION_DIR2, `${id}.json`);
   try {
-    await fs7.unlink(filePath);
+    await fs9.unlink(filePath);
   } catch (error) {
     if (error.code !== "ENOENT") {
       throw error;
     }
   }
-  const dirPath = join(SESSION_DIR, id);
+  const dirPath = join2(SESSION_DIR2, id);
   try {
-    await fs7.rm(dirPath, { recursive: true });
+    await fs9.rm(dirPath, { recursive: true });
   } catch (error) {
     if (error.code !== "ENOENT") {
       throw error;
@@ -419,14 +504,14 @@ async function deleteSessionFull(id) {
 }
 async function listSessions() {
   await ensureSessionDir();
-  const fs7 = await import("fs/promises");
+  const fs9 = await import("fs/promises");
   try {
-    const files = await fs7.readdir(SESSION_DIR);
+    const files = await fs9.readdir(SESSION_DIR2);
     const sessions = [];
     for (const file of files) {
       if (file.endsWith(".json")) {
         try {
-          const content = await fs7.readFile(join(SESSION_DIR, file), "utf-8");
+          const content = await fs9.readFile(join2(SESSION_DIR2, file), "utf-8");
           sessions.push(JSON.parse(content));
         } catch {
         }
@@ -449,9 +534,271 @@ async function getDefaultSession() {
   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;
+  seq = 0;
+  sessionId;
+  constructor(sessionId, exportLogPath) {
+    this.sessionId = sessionId;
+    const sessionDir = join3(SESSION_DIR3, sessionId);
+    this.logPath = join3(sessionDir, TRACE_FILE_NAME);
+    if (!fs2.existsSync(sessionDir)) {
+      fs2.mkdirSync(sessionDir, { recursive: true });
+    }
+    if (exportLogPath) {
+      this.exportLogPath = resolve2(exportLogPath);
+      const exportDir = dirname2(this.exportLogPath);
+      if (!fs2.existsSync(exportDir)) {
+        fs2.mkdirSync(exportDir, { recursive: true });
+      }
+    }
+    if (fs2.existsSync(this.logPath)) {
+      this.seq = this.countEntries();
+    }
+  }
+  /**
+   * Log a raw compatibility entry through the canonical trace substrate.
+   */
+  log(entry) {
+    const fullEntry = {
+      seq: ++this.seq,
+      ts: (/* @__PURE__ */ new Date()).toISOString(),
+      ...entry
+    };
+    this.logTrace(this.compatibilityEntryToTrace(fullEntry));
+  }
+  logTrace(event) {
+    const normalized = normalizeTraceEvent({
+      traceId: event.traceId ?? createTraceId(event.channel),
+      sessionId: this.sessionId,
+      ...event
+    });
+    const line = `${JSON.stringify(normalized)}
+`;
+    fs2.appendFileSync(this.logPath, line, "utf-8");
+    if (this.exportLogPath) {
+      try {
+        fs2.appendFileSync(this.exportLogPath, line, "utf-8");
+      } catch (err) {
+        console.warn(`[browser-pilot] Failed to write to export log: ${err}`);
+      }
+    }
+  }
+  /**
+   * Get the export log path (if configured)
+   */
+  getExportLogPath() {
+    return this.exportLogPath;
+  }
+  /**
+   * Log a command execution
+   */
+  logCommand(cmd, args, result, durationMs, screenshotFile) {
+    this.log({
+      type: "command",
+      cmd,
+      args,
+      status: result.success ? "success" : "failed",
+      durationMs,
+      error: result.error,
+      hints: result.hints,
+      screenshotFile
+    });
+  }
+  /**
+   * Log an error
+   */
+  logError(error, context) {
+    this.log({
+      type: "error",
+      error: error.message,
+      args: context
+    });
+  }
+  /**
+   * Get the log file path
+   */
+  getLogPath() {
+    return this.logPath;
+  }
+  /**
+   * Get log statistics
+   */
+  getLogStats() {
+    if (!fs2.existsSync(this.logPath)) {
+      return { entries: 0, size: 0 };
+    }
+    const stat = fs2.statSync(this.logPath);
+    const entries = this.countEntries();
+    let first;
+    let last;
+    if (entries > 0) {
+      const lines = fs2.readFileSync(this.logPath, "utf-8").trim().split("\n");
+      const firstEntry = this.parseLine(lines[0]);
+      const lastEntry = this.parseLine(lines[lines.length - 1]);
+      first = firstEntry?.ts;
+      last = lastEntry?.ts;
+    }
+    return {
+      entries,
+      size: stat.size,
+      first,
+      last
+    };
+  }
+  /**
+   * Get the last n log entries
+   */
+  tailLog(n) {
+    if (!fs2.existsSync(this.logPath)) {
+      return [];
+    }
+    const content = fs2.readFileSync(this.logPath, "utf-8").trim();
+    if (!content) {
+      return [];
+    }
+    const lines = content.split("\n");
+    const startIndex = Math.max(0, lines.length - n);
+    const result = [];
+    for (let i = startIndex; i < lines.length; i++) {
+      const entry = this.parseLine(lines[i]);
+      if (entry) {
+        result.push(entry);
+      }
+    }
+    return result;
+  }
+  /**
+   * Count entries in the log file
+   */
+  countEntries() {
+    if (!fs2.existsSync(this.logPath)) {
+      return 0;
+    }
+    const content = fs2.readFileSync(this.logPath, "utf-8").trim();
+    if (!content) {
+      return 0;
+    }
+    return content.split("\n").length;
+  }
+  /**
+   * Parse a single log line
+   */
+  parseLine(line) {
+    if (!line) {
+      return null;
+    }
+    try {
+      const event = JSON.parse(line);
+      return this.traceToCompatibilityEntry(event);
+    } catch {
+      return null;
+    }
+  }
+  compatibilityEntryToTrace(entry) {
+    if (entry.type === "command") {
+      return normalizeTraceEvent({
+        traceId: `cmd-${entry.seq}`,
+        sessionId: this.sessionId,
+        ts: entry.ts,
+        channel: "action",
+        event: entry.status === "failed" ? "action.failed" : "action.succeeded",
+        severity: entry.status === "failed" ? "error" : "info",
+        summary: `${entry.cmd ?? "command"}${entry.selectorUsed ? ` ${entry.selectorUsed}` : ""}`,
+        data: {
+          cmd: entry.cmd ?? null,
+          args: entry.args ?? {},
+          durationMs: entry.durationMs ?? null,
+          error: entry.error ?? null,
+          hints: entry.hints ?? [],
+          screenshotFile: entry.screenshotFile ?? null,
+          legacy: entry
+        },
+        selectorUsed: entry.selectorUsed,
+        url: entry.urlAfter ?? entry.urlBefore
+      });
+    }
+    if (entry.type === "error") {
+      return normalizeTraceEvent({
+        traceId: `err-${entry.seq}`,
+        sessionId: this.sessionId,
+        ts: entry.ts,
+        channel: "runtime",
+        event: "runtime.exception",
+        severity: "error",
+        summary: entry.error ?? "Session error",
+        data: {
+          args: entry.args ?? {},
+          legacy: entry
+        }
+      });
+    }
+    return normalizeTraceEvent({
+      traceId: `evt-${entry.seq}`,
+      sessionId: this.sessionId,
+      ts: entry.ts,
+      channel: "session",
+      event: entry.cmd ?? "session.event",
+      severity: entry.status === "failed" ? "error" : "info",
+      summary: entry.cmd ?? "Session event",
+      data: {
+        args: entry.args ?? {},
+        status: entry.status ?? null,
+        legacy: entry
+      },
+      url: entry.urlAfter ?? entry.urlBefore
+    });
+  }
+  traceToCompatibilityEntry(event) {
+    const legacy = event.data["legacy"];
+    if (legacy && typeof legacy === "object") {
+      return legacy;
+    }
+    return {
+      seq: this.seq,
+      ts: event.ts,
+      type: event.severity === "error" ? "error" : event.channel === "action" ? "command" : "event",
+      cmd: event.event,
+      args: event.data,
+      status: event.event === "action.failed" ? "failed" : event.event === "action.succeeded" ? "success" : void 0,
+      selectorUsed: event.selectorUsed,
+      urlAfter: event.url,
+      error: event.severity === "error" ? event.summary : void 0
+    };
+  }
+};
+var loggerCache = /* @__PURE__ */ new Map();
+function getSessionLogger(sessionId, exportLogPath) {
+  const cacheKey = exportLogPath ? `${sessionId}:${exportLogPath}` : sessionId;
+  let logger = loggerCache.get(cacheKey);
+  if (!logger) {
+    logger = new SessionLogger(sessionId, exportLogPath);
+    loggerCache.set(cacheKey, logger);
+  }
+  return logger;
+}
+
 // src/cli/commands/audio.ts
 var AUDIO_HELP = `
-bp audio - Test voice/audio AI agents in the browser
+bp audio - Actively exercise voice and audio pipelines
+
+When to use:
+  You need to inject microphone input, capture spoken output, or quickly validate a voice stack.
+
+When not to use:
+  You are investigating cross-cutting failure causes over time. Use \`bp trace summary --view voice\` after capture.
+
+Default flow:
+  setup -> goto or activate the app -> check -> roundtrip or capture -> trace summary
+
+Common mistake:
+  Injecting overrides after the app already created its audio pipeline.
 
 Feed audio as microphone input, capture the agent's spoken response,
 and optionally transcribe it. Designed for AI apps that respond with
@@ -461,11 +808,11 @@ Usage:
   bp audio <subcommand> [options]
 
 Subcommands:
+  setup       Inject audio hooks into the session
+  check       Validate the current audio pipeline
   roundtrip   Play input + capture response (full voice round-trip)
   play        Feed audio file into the page's fake microphone
   capture     Capture audio output from the page
-  setup       Set up audio I/O on the session (auto-runs if needed)
-  check       Validate audio pipeline and report status
 
 Common Options:
   -s, --session [id]     Session to use (omit: auto-connect, -s: latest, -s <id>: specific)
@@ -494,51 +841,32 @@ Roundtrip Options:
   --timeout <ms>         Max total round-trip time (default: 120000)
   --send-selector <sel>  Click this selector after input finishes (push-to-talk)
 
-Voice Agent Testing (typical workflow):
-  # 1. Connect to browser
-  bp connect --provider generic --name my-test
-
-  # 2. Navigate to voice agent
-  bp exec -s my-test '{"action":"goto","url":"https://my-voice-app.com"}'
-
-  # 3. Validate audio pipeline
-  bp audio check -s my-test
-
-  # 4. Run voice roundtrip with transcription
-  bp audio roundtrip -s my-test -i prompt.wav --transcribe -o response.wav
-
-Setup Order (CRITICAL):
-  Audio overrides must be injected BEFORE the voice agent initializes.
-  If the agent auto-starts on page load:
-    1. bp audio setup -s my-test
-    2. bp exec -s my-test '{"action":"goto","url":"..."}'   (reload)
-    3. sleep 3
-    4. bp audio check -s my-test                            (expect READY)
-  If capture returns empty, reload the page so the agent re-initializes
-  after overrides are in place.
-
-Diagnosing Issues:
-  bp audio check -s SESSION          Validate the full audio pipeline
-  bp audio check -s SESSION --json   Machine-readable pipeline status
-
-  0 AudioContexts    = agent not initialized (wait or reload)
-  NOT READY           = overrides missing (run setup, then reload)
-  latencyMs: -1      = agent didn't respond (check bp audio check)
-  Garbage transcript = sample rate issue (use --verbose)
-
-Quick Validation:
-  1. bp audio check     -> shows "READY" with agent AudioContext detected
-  2. bp audio roundtrip  -> shows non-zero latencyMs and response duration
-  3. If latencyMs is -1, agent didn't respond -- check audio check output
+Typical workflows:
+  Click-to-start app:
+    bp audio setup -s vt
+    bp exec -s vt '{"action":"goto","url":"https://my-voice-app.com"}'
+    bp snapshot -i -s vt
+    bp exec -s vt '{"action":"click","selector":"ref:e4"}'
+    bp audio check -s vt
+    bp audio roundtrip -s vt -i prompt.wav --transcribe -o response.wav
+
+  Auto-start app:
+    bp audio setup -s vt
+    bp exec -s vt '{"action":"goto","url":"https://my-voice-app.com"}'
+    bp audio check -s vt
+    bp audio roundtrip -s vt -i prompt.wav --transcribe
+
+Likely next commands:
+  bp trace summary -s vt --view voice
+  bp record -s vt --profile voice
+  bp env permissions grant -s vt microphone
 
 Tips:
-  - Default --silence-timeout is 1500ms. Agents rarely pause >1.5s mid-reply,
-    so this works well. Increase only if your agent has long thinking pauses.
-  - Use --pre-delay if the page needs time after audio injection.
-  - --send-selector for push-to-talk UIs (click after speaking).
-  - --transcribe adds ~1-2s (Whisper is fast). Safe in hot loop.
-  - Use --verbose to see per-chunk RMS and silence detection.
-  - Use --json for structured output in CI/scripting.
+  - \`bp audio check\` is the first diagnostic command.
+  - If you see 0 AudioContexts, the app has not initialized yet.
+  - If you see NOT READY, run \`bp audio setup\` and reload or re-open the app flow.
+  - Use \`--send-selector\` for push-to-talk UIs.
+  - Use \`bp trace summary --view voice\` when the question is causal, not just operational.
 
 Environment:
   OPENAI_API_KEY    Required for --transcribe. Validated immediately on use.
@@ -611,10 +939,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 });
@@ -633,13 +965,13 @@ async function resolveConnection(sessionId, useLatestSession, trace) {
   return { browser, session, isNewSession: true };
 }
 async function readInputFile(filePath) {
-  const fs7 = await import("fs/promises");
-  const buffer = await fs7.readFile(filePath);
+  const fs9 = await import("fs/promises");
+  const buffer = await fs9.readFile(filePath);
   return new Uint8Array(buffer);
 }
 async function getFileSize(filePath) {
-  const fs7 = await import("fs/promises");
-  const stat = await fs7.stat(filePath);
+  const fs9 = await import("fs/promises");
+  const stat = await fs9.stat(filePath);
   return stat.size;
 }
 function formatMs(ms) {
@@ -654,8 +986,8 @@ function basename(filePath) {
   return filePath.split("/").pop()?.split("\\").pop() ?? filePath;
 }
 async function writeWavFile(filePath, data) {
-  const fs7 = await import("fs/promises");
-  await fs7.writeFile(filePath, new Uint8Array(data));
+  const fs9 = await import("fs/promises");
+  await fs9.writeFile(filePath, new Uint8Array(data));
 }
 var CHECK_DIAGNOSTICS_EXPRESSION = `
 (function() {
@@ -854,6 +1186,7 @@ async function audioCommand(args, globalOptions) {
     options.useLatestSession ?? false,
     globalOptions.trace ?? false
   );
+  const logger = getSessionLogger(session.id, session.exportLog);
   if (isNewSession) {
     console.log(`Created new session: ${session.id}`);
   }
@@ -863,6 +1196,12 @@ async function audioCommand(args, globalOptions) {
       case "setup": {
         await page.setupAudio();
         const msg = "Audio I/O set up (microphone override + output capture ready)";
+        logger.logTrace({
+          channel: "voice",
+          event: "voice.pipeline.ready",
+          summary: msg,
+          data: { subcommand: "setup" }
+        });
         output(
           globalOptions.format === "json" ? { success: true, message: msg } : msg,
           globalOptions.format
@@ -875,8 +1214,24 @@ async function audioCommand(args, globalOptions) {
         const parsedDiag = JSON.parse(rawDiag);
         if (!isRecord(parsedDiag)) throw new Error("Invalid audio diagnostics payload");
         const diag = parsedDiag;
+        const checkJson = buildCheckJson(diag);
+        logger.logTrace({
+          channel: "voice",
+          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
+        });
+        if (checkJson.agentDetected) {
+          logger.logTrace({
+            channel: "media",
+            event: "media.track.started",
+            summary: "Audio track detected during audio check",
+            data: { kind: "audio", sampleRate: checkJson.agentSampleRate }
+          });
+        }
         if (globalOptions.format === "json") {
-          output(buildCheckJson(diag), "json");
+          output(checkJson, "json");
         } else {
           console.log(formatCheckPretty(diag));
         }
@@ -889,8 +1244,20 @@ async function audioCommand(args, globalOptions) {
         const audioData = await readInputFile(options.input);
         console.log(`Playing ${options.input} (${audioData.length} bytes)...`);
         const start = Date.now();
+        logger.logTrace({
+          channel: "voice",
+          event: "voice.capture.started",
+          summary: "Audio playback started",
+          data: { file: options.input }
+        });
         await page.audioInput.play(audioData, { waitForEnd: !options.noWait });
         const durationMs = Date.now() - start;
+        logger.logTrace({
+          channel: "voice",
+          event: "voice.capture.stopped",
+          summary: "Audio playback finished",
+          data: { file: options.input, durationMs }
+        });
         const result = { success: true, file: options.input, durationMs };
         output(
           globalOptions.format === "json" ? result : `Playback complete (${durationMs}ms)`,
@@ -908,6 +1275,12 @@ async function audioCommand(args, globalOptions) {
           });
         }
         let capture;
+        logger.logTrace({
+          channel: "media",
+          event: "media.playback.started",
+          summary: "Audio capture started",
+          data: { subcommand: "capture" }
+        });
         if (options.duration && options.duration > 0) {
           await page.audioOutput.start();
           await sleep(options.duration);
@@ -919,6 +1292,15 @@ async function audioCommand(args, globalOptions) {
             maxDuration: options.maxDuration ?? 3e5
           });
         }
+        logger.logTrace({
+          channel: "media",
+          event: "media.playback.stopped",
+          summary: "Audio capture stopped",
+          data: {
+            durationMs: Math.round(capture.durationMs),
+            samples: capture.left.length
+          }
+        });
         if (options.out) {
           const wav = pcmToWav({
             left: capture.left,
@@ -987,6 +1369,12 @@ async function audioCommand(args, globalOptions) {
           preDelay: options.preDelay,
           sendSelector: options.sendSelector
         });
+        logger.logTrace({
+          channel: "voice",
+          event: "voice.capture.started",
+          summary: "Voice roundtrip started",
+          data: { file: options.input }
+        });
         let savedFile;
         if (options.out) {
           if (result.audio.left.length === 0) {
@@ -1007,6 +1395,17 @@ async function audioCommand(args, globalOptions) {
           transcript = tr.text;
         }
         const hasResponse = result.latencyMs !== -1 && result.audio.left.length > 0;
+        logger.logTrace({
+          channel: hasResponse ? "voice" : "media",
+          event: hasResponse ? "voice.capture.detectedAudio" : "voice.pipeline.notReady",
+          severity: hasResponse ? "info" : "error",
+          summary: hasResponse ? "Voice response captured" : "Voice response missing",
+          data: {
+            latencyMs: result.latencyMs,
+            durationMs: Math.round(result.audio.durationMs),
+            samples: result.audio.left.length
+          }
+        });
         if (globalOptions.format === "json") {
           const jsonResult = {
             success: true,
@@ -1061,17 +1460,17 @@ Available: setup, play, capture, roundtrip, check`
   }
 }
 function sleep(ms) {
-  return new Promise((resolve5) => setTimeout(resolve5, ms));
+  return new Promise((resolve8) => setTimeout(resolve8, ms));
 }
 
 // src/cli/commands/clean.ts
-import * as fs2 from "fs";
-import { homedir as homedir2 } from "os";
-import { join as join3 } from "path";
+import * as fs4 from "fs";
+import { homedir as homedir4 } from "os";
+import { join as join5 } from "path";
 
 // src/daemon/lifecycle.ts
-import * as fs from "fs";
-import { dirname, join as join2 } from "path";
+import * as fs3 from "fs";
+import { dirname as dirname3, join as join4 } from "path";
 function parseSessionRecord(raw) {
   const parsed = JSON.parse(raw);
   return isRecord(parsed) ? parsed : null;
@@ -1115,7 +1514,7 @@ async function clearDaemonFromSession(sessionFilePath) {
 }
 
 // src/cli/commands/clean.ts
-var SESSION_DIR2 = join3(homedir2(), ".browser-pilot", "sessions");
+var SESSION_DIR4 = join5(homedir4(), ".browser-pilot", "sessions");
 var CLEAN_HELP = `
 bp clean - Remove stale browser sessions
 
@@ -1161,12 +1560,12 @@ function formatBytes2(bytes) {
 }
 function getSessionSize(sessionId) {
   let total = 0;
-  const jsonPath = join3(SESSION_DIR2, `${sessionId}.json`);
+  const jsonPath = join5(SESSION_DIR4, `${sessionId}.json`);
   try {
-    total += fs2.statSync(jsonPath).size;
+    total += fs4.statSync(jsonPath).size;
   } catch {
   }
-  const dirPath = join3(SESSION_DIR2, sessionId);
+  const dirPath = join5(SESSION_DIR4, sessionId);
   try {
     total += getDirSize(dirPath);
   } catch {
@@ -1176,14 +1575,14 @@ function getSessionSize(sessionId) {
 function getDirSize(dirPath) {
   let total = 0;
   try {
-    const entries = fs2.readdirSync(dirPath, { withFileTypes: true });
+    const entries = fs4.readdirSync(dirPath, { withFileTypes: true });
     for (const entry of entries) {
-      const fullPath = join3(dirPath, entry.name);
+      const fullPath = join5(dirPath, entry.name);
       if (entry.isDirectory()) {
         total += getDirSize(fullPath);
       } else if (entry.isFile()) {
         try {
-          total += fs2.statSync(fullPath).size;
+          total += fs4.statSync(fullPath).size;
         } catch {
         }
       }
@@ -1398,12 +1797,12 @@ async function closeCommand(args, globalOptions) {
 
 // src/cli/daemon-spawn.ts
 import { spawn } from "child_process";
-import * as fs3 from "fs";
-import { dirname as dirname2, join as join4, resolve } from "path";
+import * as fs5 from "fs";
+import { dirname as dirname4, join as join6, resolve as resolve3 } from "path";
 import { fileURLToPath } from "url";
 function spawnDaemon(sessionId, idleTimeoutMs) {
-  const thisDir = dirname2(fileURLToPath(import.meta.url));
-  const daemonScript = resolve(join4(thisDir, "..", "daemon", "index.ts"));
+  const thisDir = dirname4(fileURLToPath(import.meta.url));
+  const daemonScript = resolve3(join6(thisDir, "..", "daemon", "index.ts"));
   const args = [daemonScript, sessionId];
   if (idleTimeoutMs) {
     args.push("--idle-timeout", String(idleTimeoutMs));
@@ -1423,7 +1822,7 @@ async function waitForDaemonReady(sessionFilePath, expectedPid, timeoutMs = DAEM
   const pollInterval = 100;
   while (Date.now() < deadline) {
     try {
-      const raw = fs3.readFileSync(sessionFilePath, "utf-8");
+      const raw = fs5.readFileSync(sessionFilePath, "utf-8");
       const parsed = JSON.parse(raw);
       if (!isRecord(parsed)) continue;
       const daemon = isRecord(parsed["daemon"]) ? parsed["daemon"] : null;
@@ -1448,6 +1847,8 @@ 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
+  --channel <name>        Local Chrome channel: stable | beta | dev | canary
+  --user-data-dir <path>  Explicit local Chrome user data dir for auto-discovery
   --page-url <url>        URL to open in the attached page/new tab
   -n, --name <id>         Custom session name (default: auto-generated)
   -r, --resume <id>       Resume an existing session by ID
@@ -1467,10 +1868,12 @@ Options:
   -h, --help              Show this help
 
 Examples:
-  bp connect                                    # Auto-connect to local Chrome (port 9222)
+  bp connect                                    # Auto-connect to local Chrome
+  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 --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 --name dev                         # Auto-connect with a custom session name
+  bp connect --url ws://localhost:9222/devtools/browser/abc123  # Explicit WebSocket URL
   bp connect --resume dev                       # Resume a previous session
   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
@@ -1486,6 +1889,14 @@ function parseConnectArgs(args) {
       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") {
@@ -1561,6 +1972,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) {
@@ -1569,17 +1983,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
   };
@@ -1609,9 +2037,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;
@@ -1639,7 +2071,10 @@ async function connectCommand(args, globalOptions) {
       provider,
       currentUrl,
       recording: !!recordSettings,
-      metadata: browser.metadata,
+      connectionSource,
+      resolvedChannel,
+      resolvedUserDataDir,
+      metadata: outputMetadata,
       daemon: daemonResult
     },
     globalOptions.format
@@ -1647,10 +2082,10 @@ async function connectCommand(args, globalOptions) {
 }
 
 // src/cli/commands/daemon.ts
-import * as fs4 from "fs";
-import { homedir as homedir3 } from "os";
-import { join as join5 } from "path";
-var SESSION_DIR3 = join5(homedir3(), ".browser-pilot", "sessions");
+import * as fs6 from "fs";
+import { homedir as homedir5 } from "os";
+import { join as join7 } from "path";
+var SESSION_DIR5 = join7(homedir5(), ".browser-pilot", "sessions");
 var DAEMON_HELP = `
 bp daemon - Manage daemon processes for browser sessions
 
@@ -1766,12 +2201,12 @@ async function daemonCommand(args, globalOptions) {
     }
     case "logs": {
       const session = await getSession(globalOptions);
-      const logPath = join5(SESSION_DIR3, session.id, "daemon.log");
-      if (!fs4.existsSync(logPath)) {
+      const logPath = join7(SESSION_DIR5, session.id, "daemon.log");
+      if (!fs6.existsSync(logPath)) {
         output({ sessionId: session.id, message: "No daemon log found" }, globalOptions.format);
         return;
       }
-      const content = fs4.readFileSync(logPath, "utf-8");
+      const content = fs6.readFileSync(logPath, "utf-8");
       const lines = content.trim().split("\n");
       const n = daemonOptions.lines ?? 50;
       const tail = lines.slice(-n);
@@ -2278,6 +2713,15 @@ async function diagnoseElement(page, selector, options = {}) {
 var DIAGNOSE_HELP = `
 bp diagnose - Debug element selection and find alternatives
 
+When to use:
+  A selector or ref failed and you need to understand why.
+
+When not to use:
+  You have not inspected the page yet. Start with \`bp snapshot -i\`.
+
+Common mistake:
+  Jumping to raw JavaScript before checking browser-pilot's selector diagnostics and suggested alternatives.
+
 Usage:
   bp diagnose <selector>           Diagnose specific selector
   bp diagnose "<fuzzy query>"      Fuzzy search for elements
@@ -2288,19 +2732,14 @@ Examples:
   bp diagnose "ref:e4"             Diagnose by element ref
 
 Options:
-  --json              Output as JSON
-  --max <n>           Max candidates for fuzzy match (default: 5)
-  -s, --session <id>  Use specific session
-  --help              Show this help
-
-Output (exact match):
-  - Visibility: display, opacity, in viewport
-  - Interactivity: disabled, covered by overlay
-  - Alternative selectors
-
-Output (fuzzy match):
-  - Top N candidates ranked by similarity
-  - Role, name, visibility for each
+  --json               Output as JSON
+  --max <n>            Max candidates for fuzzy match (default: 5)
+  -s, --session <id>   Use specific session
+  --help               Show this help
+
+Likely next commands:
+  bp exec '[{"action":"click","selector":"<suggested-selector>"}]'
+  bp snapshot -i
 `;
 function parseDiagnoseArgs(args) {
   const options = {};
@@ -2430,367 +2869,1069 @@ async function diagnoseCommand(args, globalOptions) {
   }
 }
 
-// src/cli/attach.ts
-async function resolveSession(sessionId) {
-  if (sessionId) {
-    return loadSession(sessionId);
+// 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();
+  if (value === "microphone" || value === "audio" || value === "audiocapture" || value === "audio-capture") {
+    return "microphone";
   }
-  const session = await getDefaultSession();
-  if (!session) {
-    throw new Error('No session found. Run "bp connect" first.');
+  if (value === "camera" || value === "videocapture" || value === "video-capture") {
+    return "camera";
   }
-  return session;
+  if (value === "notifications") {
+    return "notifications";
+  }
+  if (value === "geolocation") {
+    return "geolocation";
+  }
+  return null;
 }
-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;
+function toProtocolPermission(name) {
+  const normalized = normalizeStoredPermission(name);
+  if (normalized === "microphone") return "audioCapture";
+  if (normalized === "camera") return "videoCapture";
+  if (normalized === "notifications") return "notifications";
+  if (normalized === "geolocation") return "geolocation";
+  return null;
+}
+function originFromUrl(url) {
+  try {
+    const parsed = new URL(url ?? "");
+    if (parsed.protocol === "http:" || parsed.protocol === "https:") {
+      return parsed.origin;
     }
+    return void 0;
+  } catch {
+    return void 0;
   }
-  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(() => {
+function buildPermissionOverrideScript(granted) {
+  const normalized = [
+    ...new Set(granted.map((value) => normalizeStoredPermission(value)).filter(Boolean))
+  ];
+  return `
+(() => {
+  const granted = ${JSON.stringify(normalized)};
+  globalThis.__bpGrantedPermissions = granted;
+
+  if (!navigator.permissions || !navigator.permissions.query) {
+    return;
+  }
+
+  if (!globalThis.__bpPermissionOverrideInstalled) {
+    globalThis.__bpPermissionOverrideInstalled = true;
+    const originalQuery = navigator.permissions.query.bind(navigator.permissions);
+    navigator.permissions.query = function(desc) {
+      const rawName = desc && desc.name ? String(desc.name) : '';
+      const normalizedName =
+        rawName === 'audio-capture' || rawName === 'audioCapture'
+          ? 'microphone'
+          : rawName === 'video-capture' || rawName === 'videoCapture'
+            ? 'camera'
+            : rawName;
+      if (Array.isArray(globalThis.__bpGrantedPermissions) && globalThis.__bpGrantedPermissions.includes(normalizedName)) {
+        return Promise.resolve({
+          state: 'granted',
+          onchange: null,
+          addEventListener() {},
+          removeEventListener() {},
+          dispatchEvent() { return true; },
+        });
+      }
+      return originalQuery(desc);
+    };
+  }
+})();
+`.trim();
+}
+function buildVisibilityOverrideScript(state) {
+  return `
+(() => {
+  const nextState = ${JSON.stringify(state)};
+
+  if (!globalThis.__bpApplyVisibilityState) {
+    globalThis.__bpApplyVisibilityState = function(value) {
+      Object.defineProperty(document, 'visibilityState', {
+        configurable: true,
+        get() { return value; },
       });
-    } catch {
-    }
+      Object.defineProperty(document, 'hidden', {
+        configurable: true,
+        get() { return value === 'hidden'; },
+      });
+      document.dispatchEvent(new Event('visibilitychange'));
+    };
   }
+
+  globalThis.__bpForcedVisibilityState = nextState;
+  globalThis.__bpApplyVisibilityState(nextState);
+})();
+`.trim();
 }
-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-3AFV2IAF.mjs");
-        const transport = await createDaemonTransport(session.daemon.socketPath);
-        const cdp = createCDPClientFromTransport(transport, {
-          debug: options.trace
+function buildNetworkOverrideScript(state) {
+  const normalized = {
+    offline: Boolean(state?.offline),
+    latency: Math.max(0, Math.round(state?.latency ?? 0))
+  };
+  return `
+(() => {
+  const config = ${JSON.stringify(normalized)};
+  globalThis.__bpNetworkOverrideState = config;
+  globalThis.__bpTrackedWebSockets = globalThis.__bpTrackedWebSockets || new Set();
+
+  if (!globalThis.__bpNetworkOverrideInstalled) {
+    globalThis.__bpNetworkOverrideInstalled = true;
+
+    const originalFetch = globalThis.fetch ? globalThis.fetch.bind(globalThis) : null;
+    if (originalFetch) {
+      globalThis.fetch = function(...args) {
+        const current = globalThis.__bpNetworkOverrideState || { offline: false, latency: 0 };
+        if (current.offline) {
+          return Promise.reject(new TypeError('Failed to fetch'));
+        }
+        return new Promise((resolve, reject) => {
+          setTimeout(() => {
+            originalFetch(...args).then(resolve, reject);
+          }, current.latency || 0);
         });
-        const { Browser: BrowserClass } = await import("./browser-LZTEHUDI.mjs");
-        const browser2 = BrowserClass.fromCDP(cdp, session);
-        const page2 = addBatchToPage(await browser2.page(void 0, { targetId: session.targetId }));
-        const currentUrl2 = await page2.url();
-        const refCache2 = session.metadata?.refCache;
-        if (refCache2 && refCache2.url === currentUrl2) {
-          page2.importRefMap(refCache2.refMap);
+      };
+    }
+
+    if (globalThis.XMLHttpRequest && !globalThis.__bpNetworkXhrPatched) {
+      globalThis.__bpNetworkXhrPatched = true;
+      const originalSend = XMLHttpRequest.prototype.send;
+      XMLHttpRequest.prototype.send = function(body) {
+        const current = globalThis.__bpNetworkOverrideState || { offline: false, latency: 0 };
+        if (current.offline) {
+          setTimeout(() => {
+            this.dispatchEvent(new ProgressEvent('error'));
+            if (typeof this.onerror === 'function') {
+              this.onerror(new ProgressEvent('error'));
+            }
+          }, 0);
+          return;
         }
-        return { session, browser: browser2, page: page2, viaDaemon: true };
-      } catch (err) {
-        const reason = err instanceof Error ? err.message : String(err);
-        await cleanupStaleDaemon(session, reason);
+        const invoke = () => originalSend.call(this, body);
+        if (current.latency > 0) {
+          setTimeout(invoke, current.latency);
+        } else {
+          invoke();
+        }
+      };
+    }
+
+    if (globalThis.WebSocket && !globalThis.__bpNetworkWebSocketPatched) {
+      globalThis.__bpNetworkWebSocketPatched = true;
+      const NativeWebSocket = globalThis.WebSocket;
+      const notifyOfflineSocket = (socket, code = 1012, reason = 'offline') => {
+        if (!socket || socket.__bpOfflineNotified) {
+          return;
+        }
+        try {
+          socket.__bpOfflineNotified = true;
+        } catch {}
+        try {
+          socket.readyState = 3;
+        } catch {}
+        const errorEvent = new Event('error');
+        const closeEvent =
+          typeof CloseEvent === 'function'
+            ? new CloseEvent('close', { code, reason, wasClean: false })
+            : new Event('close');
+        try {
+          socket.dispatchEvent(errorEvent);
+        } catch {}
+        try {
+          if (typeof socket.onerror === 'function') {
+            socket.onerror(errorEvent);
+          }
+        } catch {}
+        try {
+          socket.dispatchEvent(closeEvent);
+        } catch {}
+        try {
+          if (typeof socket.onclose === 'function') {
+            socket.onclose(closeEvent);
+          }
+        } catch {}
+      };
+      const createOfflineSocket = (url) => {
+        const target = new EventTarget();
+        const socket = {
+          url: String(url),
+          readyState: 0,
+          bufferedAmount: 0,
+          extensions: '',
+          protocol: '',
+          binaryType: 'blob',
+          onopen: null,
+          onerror: null,
+          onclose: null,
+          onmessage: null,
+          addEventListener: target.addEventListener.bind(target),
+          removeEventListener: target.removeEventListener.bind(target),
+          dispatchEvent: target.dispatchEvent.bind(target),
+          send() {
+            throw new DOMException('WebSocket is offline', 'InvalidStateError');
+          },
+          close(code = 1012, reason = 'offline') {
+            socket.readyState = 3;
+            notifyOfflineSocket(socket, code, reason);
+          },
+        };
+        setTimeout(() => {
+          notifyOfflineSocket(socket, 1012, 'offline');
+        }, 0);
+        return socket;
+      };
+      const WrappedWebSocket = function(url, protocols) {
+        const current = globalThis.__bpNetworkOverrideState || { offline: false };
+        if (current.offline) {
+          return createOfflineSocket(url);
+        }
+        const socket =
+          arguments.length > 1 ? new NativeWebSocket(url, protocols) : new NativeWebSocket(url);
+        globalThis.__bpTrackedWebSockets.add(socket);
+        const nativeClose = socket.close.bind(socket);
+        socket.close = function(code = 1000, reason = '') {
+          const current = globalThis.__bpNetworkOverrideState || { offline: false };
+          if (current.offline) {
+            notifyOfflineSocket(socket, code || 1012, reason || 'offline');
+          }
+          return nativeClose(code, reason);
+        };
+        const failOffline = () => {
+          const current = globalThis.__bpNetworkOverrideState || { offline: false };
+          if (current.offline) {
+            try {
+              socket.close(1012, 'offline');
+            } catch {}
+          }
+        };
+        socket.addEventListener('open', failOffline);
+        socket.addEventListener('close', () => {
+          try {
+            globalThis.__bpTrackedWebSockets.delete(socket);
+          } catch {}
+        });
+        setTimeout(failOffline, 25);
+        return socket;
+      };
+      WrappedWebSocket.prototype = NativeWebSocket.prototype;
+      Object.setPrototypeOf(WrappedWebSocket, NativeWebSocket);
+      globalThis.WebSocket = WrappedWebSocket;
+    }
+  }
+
+  if (globalThis.__bpTrackedWebSockets) {
+    for (const socket of globalThis.__bpTrackedWebSockets) {
+      if (socket && socket.readyState === 1 && config.offline) {
+        try {
+          socket.close(1012, 'offline');
+        } catch {}
       }
     }
   }
-  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.`
-    );
+
+  if (globalThis.navigator && typeof globalThis.navigator === 'object') {
+    try {
+      Object.defineProperty(globalThis.navigator, 'onLine', {
+        configurable: true,
+        get() { return !config.offline; },
+      });
+    } catch {}
   }
-  const page = addBatchToPage(await browser.page(void 0, { targetId: session.targetId }));
-  const currentUrl = await page.url();
-  const refCache = session.metadata?.refCache;
-  if (refCache && refCache.url === currentUrl) {
-    page.importRefMap(refCache.refMap);
+})();
+`.trim();
+}
+async function applyPermissionState(cdp, origin, granted) {
+  const protocolPermissions = [
+    ...new Set(granted.map((value) => toProtocolPermission(value)).filter(Boolean))
+  ];
+  if (protocolPermissions.length > 0) {
+    await cdp.send("Browser.grantPermissions", {
+      permissions: protocolPermissions,
+      origin: origin ?? ""
+    });
   }
-  return { session, browser, page, viaDaemon: false };
+  const script = buildPermissionOverrideScript(granted);
+  await cdp.send("Page.addScriptToEvaluateOnNewDocument", { source: script });
+  await cdp.send("Runtime.evaluate", { expression: script, awaitPromise: false });
+}
+async function applyVisibilityState(cdp, state) {
+  const script = buildVisibilityOverrideScript(state);
+  await cdp.send("Page.addScriptToEvaluateOnNewDocument", { source: script });
+  await cdp.send("Runtime.evaluate", { expression: script, awaitPromise: false });
+}
+async function applyNetworkOverride(cdp, state) {
+  const script = buildNetworkOverrideScript(state);
+  await cdp.send("Page.addScriptToEvaluateOnNewDocument", { source: script });
+  await cdp.send("Runtime.evaluate", { expression: script, awaitPromise: false });
 }
 
-// src/cli/commands/eval.ts
-var EVAL_HELP = `
-bp eval - Evaluate JavaScript in the browser
+// src/cli/commands/env.ts
+var ENV_HELP = `
+bp env - Browser/session environment controls
 
-Convenience wrapper around exec's evaluate action.
-No JSON escaping needed -- just pass a JS expression directly.
+When to use:
+  You need deterministic permission, network, visibility, or geolocation changes without dropping to raw CDP or eval.
+
+When not to use:
+  You are inspecting or automating DOM interactions. Use \`bp snapshot\`, \`bp exec\`, \`bp record\`, or \`bp trace\`.
+
+Default flow:
+  change environment -> run exec or audio flow -> inspect with trace summary or watch
+
+Common mistake:
+  Treating \`env\` as a generic utilities bucket. It is only for browser and session state controls.
+
+Use this namespace when you need deterministic controls over browser permissions,
+network, visibility, or geolocation during investigation and automation.
 
 Usage:
-  bp eval '<expression>'        Evaluate inline JavaScript
-  bp eval -f <file>             Evaluate JavaScript from a file
-  echo '<expr>' | bp eval       Evaluate from stdin
+  bp env permissions <action> [permission] [options]
+  bp env network <action> [options]
+  bp env visibility <state> [options]
+  bp env geolocation <action> [options]
 
-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
+Subcommands:
+  permissions  grant, revoke, reset, get
+  network      offline, online, throttle
+  visibility   hidden, visible
+  geolocation  set, clear
+
+Common options:
+  -s, --session <id>     Session to use (omit: auto-connect, -s: latest, -s <id>: specific)
+  -h, --help             Show help
 
 Examples:
-  bp eval 'document.title'
-  bp eval 'document.querySelectorAll("a").length'
-  bp eval -f scrape.js
-`.trimEnd();
-function parseEvalArgs(args) {
+  # Browser permissions
+  bp env permissions get -s my-session microphone
+  bp env permissions grant -s my-session microphone
+  bp env permissions reset -s my-session
+
+  # Network control
+  bp env network offline -s my-session
+  bp env network online -s my-session
+  bp env network throttle -s my-session --latency 200 --down 128kbps --up 64kbps
+
+  # Visibility
+  bp env visibility hidden -s my-session
+  bp env visibility visible -s my-session
+
+  # Geolocation
+  bp env geolocation set -s my-session --lat 37.7749 --lon -122.4194
+  bp env geolocation clear -s my-session
+
+Likely next commands:
+  bp trace watch -s my-session --view ws --assert profile:reconnect
+  bp exec -s my-session '[{"action":"assertPermission","name":"microphone","state":"granted"}]'
+  bp trace summary -s my-session --view permissions
+`;
+var PermissionNames;
+((PermissionNames2) => {
+  PermissionNames2.NAVIGATION = {
+    microphone: "microphone",
+    camera: "camera",
+    notifications: "notifications",
+    geolocation: "geolocation",
+    audio: "audio",
+    audioCapture: "audio-capture",
+    all: "all"
+  };
+  PermissionNames2.PROTOCOL = {
+    microphone: "audioCapture",
+    camera: "videoCapture",
+    notifications: "notifications",
+    geolocation: "geolocation",
+    audio: "audioCapture",
+    audioCapture: "audioCapture",
+    all: "all"
+  };
+})(PermissionNames || (PermissionNames = {}));
+function parseEnvArgs(args) {
   const options = {};
-  let expression;
-  for (let i = 0; i < args.length; i++) {
+  let i = 0;
+  for (; 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;
+    if (!options.topCommand && (arg === "permissions" || arg === "network" || arg === "visibility" || arg === "geolocation")) {
+      options.topCommand = arg;
+      continue;
+    }
+    if (arg === "-h" || arg === "--help") {
+      options.help = true;
+      continue;
+    }
+    if (arg === "-s" || arg === "--session") {
+      const next = args[i + 1];
+      if (next && !next.startsWith("-")) {
+      }
+      const after = args[i + 1];
+      if (!after || after.startsWith("-")) {
+        options.useLatestSession = true;
+      }
+      continue;
+    }
+    if (arg === "--lat") {
+      options.lat = Number.parseFloat(args[++i] ?? "0");
+      continue;
+    }
+    if (arg === "--lon") {
+      options.lon = Number.parseFloat(args[++i] ?? "0");
+      continue;
+    }
+    if (arg === "--accuracy" || arg === "--acc") {
+      options.accuracy = Number.parseFloat(args[++i] ?? "1");
+      continue;
+    }
+    if (arg === "--duration") {
+      const value = Number.parseInt(args[++i] ?? "0", 10);
+      if (Number.isFinite(value) && value > 0) options.duration = value;
+      continue;
+    }
+    if (arg === "--latency") {
+      const value = Number.parseInt(args[++i] ?? "0", 10);
+      if (Number.isFinite(value) && value >= 0) options.latency = value;
+      continue;
+    }
+    if (arg === "--down") {
+      options.down = args[++i];
+      continue;
+    }
+    if (arg === "--up") {
+      options.up = args[++i];
+      continue;
+    }
+    if (!arg.startsWith("-") && options.topCommand) {
+      if (options.topCommand === "permissions") {
+        if (!options.permissionMode) {
+          options.permissionMode = arg;
+          continue;
+        }
+        if (!options.permissionName && options.permissionMode !== "get" && options.permissionMode !== "reset") {
+          options.permissionName = arg;
+          continue;
+        }
+        if (!options.permissionName && options.permissionMode === "get") {
+          options.permissionName = arg;
+          continue;
+        }
+      }
+      if (options.topCommand === "network") {
+        options.networkAction = arg;
+        continue;
+      }
+      if (options.topCommand === "visibility") {
+        options.visibility = arg;
+        continue;
+      }
+      if (options.topCommand === "geolocation") {
+        options.geoAction = 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}))()`;
+  return options;
 }
-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 fs7 = await import("fs/promises");
-    expression = await fs7.readFile(evalOptions.file, "utf-8");
+function coercePermissionArg(value) {
+  return value;
+}
+function toBytesPerSecond(raw) {
+  if (!raw) return void 0;
+  const text = raw.trim().toLowerCase();
+  const match = text.match(/^([0-9]*\.?[0-9]+)\s*(kbps|mbps|k|m)?$/);
+  if (!match || !match[1]) return void 0;
+  const value = Number.parseFloat(match[1]);
+  if (!Number.isFinite(value) || value <= 0) return void 0;
+  const unit = match[2] ?? "kbps";
+  if (unit === "mbps" || unit === "m") return Math.round(value * 1e6 / 8);
+  return Math.round(value * 1e3 / 8);
+}
+async function resolveConnection2(sessionId, useLatestSession = false) {
+  if (sessionId) {
+    const session2 = await loadSession(sessionId);
+    const browser2 = await connect({ provider: session2.provider, wsUrl: session2.wsUrl });
+    return { browser: browser2, session: session2 };
   }
-  if (!expression && !process.stdin.isTTY) {
-    const chunks = [];
-    for await (const chunk of process.stdin) {
-      chunks.push(chunk);
+  if (useLatestSession) {
+    const defaultSession = await getDefaultSession();
+    if (!defaultSession) {
+      throw new Error('No sessions found. Run "bp connect" first or use "-s" for latest session.');
     }
-    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 browser2 = await connect({
+      provider: defaultSession.provider,
+      wsUrl: defaultSession.wsUrl
+    });
+    return { browser: browser2, session: defaultSession };
   }
-  const session = await resolveSession(globalOptions.session);
-  const { browser, page } = await attachSession(session, { trace: globalOptions.trace });
+  let wsUrl;
   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
+    wsUrl = (await resolveCLIEndpoint()).wsUrl;
+  } catch (error) {
+    throw new Error(
+      formatBrowserDiscoveryError(error, {
+        explicitHint: "  - Create a session first: bp connect --browser-url <ws-url>",
+        reuseSessionHint: "bp env -s <id> ...",
+        latestSessionHint: "bp env -s"
+      })
     );
-    await updateSession(session.id, { currentUrl: await page.url() });
-  } finally {
-    await browser.disconnect();
   }
-}
-
-// src/cli/commands/exec.ts
-import * as nodeFs from "fs";
-import { basename as basename2, dirname as dirname4, join as join7, resolve as resolve3 } from "path";
-
-// src/cli/session-logger.ts
-import * as fs5 from "fs";
-import { homedir as homedir4 } from "os";
-import { dirname as dirname3, join as join6, resolve as resolve2 } from "path";
-var SESSION_DIR4 = join6(homedir4(), ".browser-pilot", "sessions");
-var SessionLogger = class {
-  logPath;
-  exportLogPath = null;
-  seq = 0;
-  constructor(sessionId, exportLogPath) {
-    const sessionDir = join6(SESSION_DIR4, sessionId);
-    this.logPath = join6(sessionDir, "log.jsonl");
-    if (!fs5.existsSync(sessionDir)) {
-      fs5.mkdirSync(sessionDir, { recursive: true });
-    }
-    if (exportLogPath) {
-      this.exportLogPath = resolve2(exportLogPath);
-      const exportDir = dirname3(this.exportLogPath);
-      if (!fs5.existsSync(exportDir)) {
-        fs5.mkdirSync(exportDir, { recursive: true });
-      }
-    }
-    if (fs5.existsSync(this.logPath)) {
-      this.seq = this.countEntries();
+  const browser = await connect({ provider: "generic", wsUrl });
+  const page = await browser.page();
+  const currentUrl = await page.url();
+  const newSessionId = generateSessionId();
+  const session = {
+    id: newSessionId,
+    provider: "generic",
+    wsUrl: browser.wsUrl,
+    createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+    lastActivity: (/* @__PURE__ */ new Date()).toISOString(),
+    currentUrl
+  };
+  await saveSession(session);
+  const sessionFile = getSessionFilePath(newSessionId);
+  await import("fs/promises").then(
+    (fs9) => fs9.mkdir(dirname5(sessionFile), { recursive: true })
+  );
+  return { browser, session };
+}
+function clampRate(value) {
+  if (value === void 0) return void 0;
+  if (!Number.isFinite(value) || value < 0) return void 0;
+  return Math.round(value);
+}
+function isStoredPermissionName(value) {
+  return value !== null;
+}
+async function getPermissionStates(page) {
+  const expr = `
+    (() => {
+      const names = ['geolocation', 'microphone', 'audio-capture', 'camera', 'notifications', 'clipboard-read', 'clipboard-write'];
+      return Promise.all(names.map(async (name) => {
+        if (!navigator.permissions || !navigator.permissions.query) {
+          return { name, state: 'unsupported' };
+        }
+        try {
+          const result = await navigator.permissions.query({ name });
+          return { name, state: result.state };
+        } catch {
+          return { name, state: 'unsupported' };
+        }
+      }));
+    })()
+  `;
+  return page.evaluate(expr);
+}
+async function permissionCommand(action, nameInput, page) {
+  const requested = nameInput && nameInput !== "all" ? coercePermissionArg(nameInput) : "all";
+  if (action === "get") {
+    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.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)
+  );
+  if (action === "grant") {
+    const origin2 = await page.evaluate("window.location.origin");
+    await page.cdpClient.send("Browser.grantPermissions", {
+      permissions: protocolNames.filter((value) => value !== "all" && value !== "audio"),
+      origin: origin2
+    });
+    if (permissionNames.includes("microphone")) {
+      await grantAudioPermissions(page.cdpClient, origin2);
     }
+    const result = await getPermissionStates(page);
+    return result.map((item) => ({ action, name: item.name, state: item.state }));
   }
-  /**
-   * Log a raw entry (writes to both core and export logs)
-   */
-  log(entry) {
-    const fullEntry = {
-      seq: ++this.seq,
-      ts: (/* @__PURE__ */ new Date()).toISOString(),
-      ...entry
-    };
-    const line = `${JSON.stringify(fullEntry)}
-`;
-    fs5.appendFileSync(this.logPath, line, "utf-8");
-    if (this.exportLogPath) {
+  const origin = await page.evaluate("window.location.origin");
+  if (action === "revoke" || action === "reset") {
+    for (const permission of protocolNames) {
+      if (permission === "all") continue;
       try {
-        fs5.appendFileSync(this.exportLogPath, line, "utf-8");
-      } catch (err) {
-        console.warn(`[browser-pilot] Failed to write to export log: ${err}`);
+        await page.cdpClient.send("Browser.resetPermissions", {
+          permissions: [permission],
+          origin
+        });
+      } catch {
+        await page.cdpClient.send("Browser.revokePermissions", {
+          permissions: [permission],
+          origin
+        });
       }
     }
+    const result = await getPermissionStates(page);
+    return result.map((item) => ({ action, name: item.name, state: item.state }));
   }
-  /**
-   * Get the export log path (if configured)
-   */
-  getExportLogPath() {
-    return this.exportLogPath;
+  throw new Error(`Unsupported permission action: ${action}`);
+}
+function formatPermissionOutput(session, data) {
+  const lines = [`Session: ${session.id}`, ""];
+  for (const row of data) {
+    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})`);
   }
-  /**
-   * Log a command execution
-   */
-  logCommand(cmd, args, result, durationMs, screenshotFile) {
-    this.log({
-      type: "command",
-      cmd,
-      args,
-      status: result.success ? "success" : "failed",
-      durationMs,
-      error: result.error,
-      hints: result.hints,
-      screenshotFile
+  return lines.join("\n");
+}
+async function runNetworkCommand(action, options, page, session) {
+  await page.cdpClient.send("Network.enable");
+  const applyNetworkState = async (offline, latency2, downloadThroughput, uploadThroughput, connectionType) => {
+    const state = {
+      offline,
+      latency: latency2,
+      downloadThroughput,
+      uploadThroughput,
+      connectionType
+    };
+    try {
+      await page.cdpClient.send("Network.emulateNetworkConditionsByRule", {
+        offline,
+        matchedNetworkConditions: [
+          {
+            urlPattern: "",
+            latency: latency2,
+            downloadThroughput,
+            uploadThroughput
+          }
+        ]
+      });
+      await page.cdpClient.send("Network.overrideNetworkState", state);
+    } catch {
+      await page.cdpClient.send("Network.emulateNetworkConditions", state);
+    }
+  };
+  if (action === "offline") {
+    await applyNetworkState(true, options.latency ?? 0, 0, 0, "none");
+    await applyNetworkOverride(page.cdpClient, {
+      offline: true,
+      latency: options.latency ?? 0
     });
+    console.log(`Session ${session.id}: network set to offline`);
+    return;
   }
-  /**
-   * Log an error
-   */
-  logError(error, context) {
-    this.log({
-      type: "error",
-      error: error.message,
-      args: context
+  if (action === "online") {
+    await applyNetworkState(false, 0, -1, -1, "wifi");
+    await applyNetworkOverride(page.cdpClient, {
+      offline: false,
+      latency: 0
     });
+    console.log(`Session ${session.id}: network set to online`);
+    return;
   }
-  /**
-   * Get the log file path
-   */
-  getLogPath() {
-    return this.logPath;
+  const latency = clampRate(options.latency) ?? 0;
+  const down = clampRate(toBytesPerSecond(options.down)) ?? 1e6;
+  const up = clampRate(toBytesPerSecond(options.up)) ?? 5e5;
+  await applyNetworkState(false, latency, down, up, "wifi");
+  await applyNetworkOverride(page.cdpClient, {
+    offline: false,
+    latency
+  });
+  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);
+  console.log(`Session ${session.id}: visibility set to ${state}`);
+}
+async function runGeolocationCommand(action, options, page, session) {
+  if (action === "clear") {
+    await page.clearGeolocation();
+    console.log(`Session ${session.id}: geolocation override cleared`);
+    return;
   }
-  /**
-   * Get log statistics
-   */
-  getLogStats() {
-    if (!fs5.existsSync(this.logPath)) {
-      return { entries: 0, size: 0 };
-    }
-    const stat = fs5.statSync(this.logPath);
-    const entries = this.countEntries();
-    let first;
-    let last;
-    if (entries > 0) {
-      const lines = fs5.readFileSync(this.logPath, "utf-8").trim().split("\n");
-      const firstEntry = this.parseLine(lines[0]);
-      const lastEntry = this.parseLine(lines[lines.length - 1]);
-      first = firstEntry?.ts;
-      last = lastEntry?.ts;
-    }
-    return {
-      entries,
-      size: stat.size,
-      first,
-      last
-    };
+  if (options.lat === void 0 || options.lon === void 0) {
+    throw new Error("geolocation set requires --lat and --lon");
   }
-  /**
-   * Get the last n log entries
-   */
-  tailLog(n) {
-    if (!fs5.existsSync(this.logPath)) {
-      return [];
-    }
-    const content = fs5.readFileSync(this.logPath, "utf-8").trim();
-    if (!content) {
-      return [];
+  await page.setGeolocation({
+    latitude: options.lat,
+    longitude: 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);
+  if (options.help || globalOptions.help || !options.topCommand) {
+    console.log(ENV_HELP);
+    return;
+  }
+  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 ?? {};
+  try {
+    if (options.topCommand === "permissions") {
+      const permissionMode = options.permissionMode ?? "get";
+      if (permissionMode === "get" && !options.permissionName) {
+        const result2 = await permissionCommand(permissionMode, "all", page);
+        if (outputAsJson) {
+          console.log(JSON.stringify({ session: session.id, permissions: result2 }, null, 2));
+        } else {
+          console.log(formatPermissionOutput(session, result2));
+        }
+        return;
+      }
+      const result = await permissionCommand(permissionMode, options.permissionName, page);
+      if (permissionMode !== "get") {
+        const nextPermissions = permissionMode === "reset" ? [] : (() => {
+          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
+          );
+          if (permissionMode === "grant") {
+            for (const name of requested) current.add(name);
+          } else {
+            for (const name of requested) current.delete(name);
+          }
+          return [...current];
+        })();
+        const nextEnv = {
+          ...existingEnv,
+          permissions: nextPermissions
+        };
+        await updateSession(session.id, { metadata: { env: nextEnv } });
+        const currentUrl = await page.evaluate("window.location.href");
+        await applyPermissionState(page.cdpClient, originFromUrl(currentUrl), nextPermissions);
+      }
+      if (outputAsJson) {
+        console.log(
+          JSON.stringify(
+            { session: session.id, action: permissionMode, permissions: result },
+            null,
+            2
+          )
+        );
+      } else {
+        console.log(formatPermissionOutput(session, result));
+      }
+      return;
     }
-    const lines = content.split("\n");
-    const startIndex = Math.max(0, lines.length - n);
-    const result = [];
-    for (let i = startIndex; i < lines.length; i++) {
-      const entry = this.parseLine(lines[i]);
-      if (entry) {
-        result.push(entry);
+    if (options.topCommand === "network") {
+      const action = options.networkAction;
+      if (!action) {
+        throw new Error("network command requires action: offline, online, or throttle");
+      }
+      await runNetworkCommand(action, options, page, session);
+      await updateSession(session.id, {
+        metadata: {
+          env: {
+            ...existingEnv,
+            network: action === "online" ? {
+              offline: false,
+              latency: 0
+            } : {
+              offline: action === "offline",
+              latency: action === "throttle" ? options.latency ?? 0 : options.latency ?? 0
+            }
+          }
+        }
+      });
+      if (options.duration && options.duration > 0) {
+        await new Promise((resolve8) => setTimeout(resolve8, options.duration));
+        if (action === "offline" || action === "throttle") {
+          await runNetworkCommand("online", {}, page, session);
+          await updateSession(session.id, {
+            metadata: {
+              env: {
+                ...existingEnv,
+                network: {
+                  offline: false,
+                  latency: 0
+                }
+              }
+            }
+          });
+        }
       }
+      return;
     }
-    return result;
-  }
-  /**
-   * Count entries in the log file
-   */
-  countEntries() {
-    if (!fs5.existsSync(this.logPath)) {
-      return 0;
+    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;
     }
-    const content = fs5.readFileSync(this.logPath, "utf-8").trim();
-    if (!content) {
-      return 0;
+    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;
     }
-    return content.split("\n").length;
+    throw new Error("Unknown env command. Run bp env --help for usage.");
+  } finally {
+    await browser.disconnect();
   }
-  /**
-   * Parse a single log line
-   */
-  parseLine(line) {
-    if (!line) {
-      return null;
+}
+
+// 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 {
-      return JSON.parse(line);
+      const fsPromises = await import("fs/promises");
+      await fsPromises.unlink(session.daemon.socketPath).catch(() => {
+      });
     } catch {
-      return null;
     }
   }
-};
-var loggerCache = /* @__PURE__ */ new Map();
-function getSessionLogger(sessionId, exportLogPath) {
-  const cacheKey = exportLogPath ? `${sessionId}:${exportLogPath}` : sessionId;
-  let logger = loggerCache.get(cacheKey);
-  if (!logger) {
-    logger = new SessionLogger(sessionId, exportLogPath);
-    loggerCache.set(cacheKey, logger);
+}
+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-ZCR6AA4D.mjs");
+        const { Page: PageClass } = await import("./page-IUUTJ3SW.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();
   }
-  return logger;
 }
 
 // src/cli/commands/exec.ts
+import * as nodeFs from "fs";
+import { basename as basename2, dirname as dirname6, join as join8, resolve as resolve4 } from "path";
 var EXEC_HELP = `
-bp exec - Execute browser actions on current session
+bp exec - Act on a page with high-level browser steps
+
+When to use:
+  You know what you want to do in the browser and want to click, fill, wait, or assert in one batch.
+
+When not to use:
+  A human is demonstrating the workflow from scratch. Use \`bp record\`.
+
+Default flow:
+  snapshot -> exec -> snapshot or trace summary
+
+Common mistake:
+  Guessing brittle selectors instead of taking \`bp snapshot -i\` and using refs.
 
 Usage:
   bp exec '<json>'              Execute action(s) from inline JSON
@@ -2804,7 +3945,7 @@ Options:
   -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
+  --debug              Enable CDP transport debugging (global option)
 
 Recording:
   --record                    Enable screenshot recording
@@ -2818,12 +3959,16 @@ Recording:
 
 Examples:
   bp exec '{"action":"goto","url":"https://example.com"}'
+  bp exec '[{"action":"click","selector":"ref:e4"},{"action":"assertText","expect":"Saved"}]'
+  bp exec '[{"action":"waitForWsMessage","match":"*realtime*","where":{"type":"ready"}}]'
   bp exec --record '[{"action":"fill","selector":"#email","value":"me@test.com"},{"action":"submit","selector":"form"}]'
   bp exec --dialog accept '{"action":"click","selector":"#delete-btn"}'
   bp exec -f login-steps.json
 
-Run 'bp actions' for the complete action reference.
-Run 'bp quickstart' for getting started guide.
+Likely next commands:
+  bp snapshot -i
+  bp diagnose "<selector>"
+  bp trace summary -s <session> --view console
 `.trimEnd();
 function parseExecArgs(args) {
   const options = {};
@@ -2884,24 +4029,24 @@ async function captureFinalUrl(page, steps, fallback) {
   if (!mightNavigate) {
     return currentUrl;
   }
-  await new Promise((resolve5) => setTimeout(resolve5, 200));
+  await new Promise((resolve8) => setTimeout(resolve8, 200));
   return getCurrentUrlSafe(page, currentUrl);
 }
 function mirrorRecordingToExport(recordingManifest, exportLogPath) {
   try {
-    const sourceDir = dirname4(recordingManifest);
-    const exportDir = dirname4(exportLogPath);
+    const sourceDir = dirname6(recordingManifest);
+    const exportDir = dirname6(exportLogPath);
     const manifestName = basename2(recordingManifest);
-    const exportManifestPath = join7(exportDir, manifestName);
+    const exportManifestPath = join8(exportDir, manifestName);
     nodeFs.copyFileSync(recordingManifest, exportManifestPath);
-    const sourceScreenshotsDir = join7(sourceDir, "screenshots");
-    const exportScreenshotsDir = join7(exportDir, "screenshots");
+    const sourceScreenshotsDir = join8(sourceDir, "screenshots");
+    const exportScreenshotsDir = join8(exportDir, "screenshots");
     if (nodeFs.existsSync(sourceScreenshotsDir)) {
       nodeFs.rmSync(exportScreenshotsDir, { force: true, recursive: true });
       nodeFs.mkdirSync(exportScreenshotsDir, { recursive: true });
       const files = nodeFs.readdirSync(sourceScreenshotsDir);
       for (const file of files) {
-        nodeFs.copyFileSync(join7(sourceScreenshotsDir, file), join7(exportScreenshotsDir, file));
+        nodeFs.copyFileSync(join8(sourceScreenshotsDir, file), join8(exportScreenshotsDir, file));
       }
     }
   } catch (err) {
@@ -2915,8 +4060,8 @@ async function execCommand(args, globalOptions) {
   }
   let { actionsJson, options: execOptions } = parseExecArgs(args);
   if (execOptions.file) {
-    const fs7 = await import("fs/promises");
-    actionsJson = await fs7.readFile(execOptions.file, "utf-8");
+    const fs9 = await import("fs/promises");
+    actionsJson = await fs9.readFile(execOptions.file, "utf-8");
   }
   if (!actionsJson && !process.stdin.isTTY) {
     const chunks = [];
@@ -2965,10 +4110,10 @@ Run 'bp actions' for complete action reference.${evalTip}`
       highlights: execOptions.noHighlights ? false : sessionRecord?.highlights ?? true
     };
     if (execOptions.recordDir) {
-      recordOptions.outputDir = resolve3(execOptions.recordDir);
+      recordOptions.outputDir = resolve4(execOptions.recordDir);
     } else {
-      const { homedir: homedir6 } = await import("os");
-      recordOptions.outputDir = join7(homedir6(), ".browser-pilot", "sessions", session.id);
+      const { homedir: homedir7 } = await import("os");
+      recordOptions.outputDir = join8(homedir7(), ".browser-pilot", "sessions", session.id);
     }
   }
   const { browser, page } = await attachSession(session, { trace: globalOptions.trace });
@@ -3004,6 +4149,38 @@ Run 'bp actions' for complete action reference.${evalTip}`
         stepResult.durationMs,
         stepResult.screenshotPath ? basename2(stepResult.screenshotPath) : void 0
       );
+      if (stepResult.success && stepResult.action === "waitForWsMessage" && stepResult.result) {
+        logger.logTrace({
+          channel: "ws",
+          event: "ws.frame.received",
+          summary: "waitForWsMessage matched",
+          data: stepResult.result
+        });
+      }
+      if (stepResult.success && stepResult.action === "assertTextChanged" && stepResult.text) {
+        logger.logTrace({
+          channel: "dom",
+          event: "dom.text.changed",
+          summary: "Text changed",
+          data: { text: stepResult.text }
+        });
+      }
+      if (stepResult.success && stepResult.action === "assertPermission" && stepResult.result) {
+        logger.logTrace({
+          channel: "permission",
+          event: "permission.state",
+          summary: "Permission assertion passed",
+          data: stepResult.result
+        });
+      }
+      if (stepResult.success && stepResult.action === "assertMediaTrackLive" && stepResult.result) {
+        logger.logTrace({
+          channel: "media",
+          event: "media.track.started",
+          summary: "Live media track detected",
+          data: stepResult.result
+        });
+      }
     }
     if (result.recordingManifest && session.exportLog) {
       mirrorRecordingToExport(result.recordingManifest, session.exportLog);
@@ -3056,8 +4233,8 @@ Run 'bp actions' for complete action reference.${evalTip}`
       ...result.recordingManifest ? { recordingManifest: result.recordingManifest } : {}
     };
     if (execOptions.outputFile) {
-      const fs7 = await import("fs/promises");
-      await fs7.writeFile(execOptions.outputFile, renderOutput(payload, globalOptions.format));
+      const fs9 = await import("fs/promises");
+      await fs9.writeFile(execOptions.outputFile, renderOutput(payload, globalOptions.format));
       process.stderr.write(`Wrote output to ${execOptions.outputFile}
 `);
     } else {
@@ -3067,7 +4244,7 @@ Run 'bp actions' for complete action reference.${evalTip}`
       const frameCount = result.steps.filter((s) => s.screenshotPath).length;
       process.stderr.write(
         `
-Recording: ${frameCount} screenshots saved to ${dirname4(result.recordingManifest)}
+Recording: ${frameCount} screenshots saved to ${dirname6(result.recordingManifest)}
 `
       );
     }
@@ -3242,501 +4419,161 @@ function parseListArgs(args) {
     }
   }
   return options;
-}
-function formatLogEntry(entry) {
-  const time = new Date(entry.ts).toLocaleTimeString();
-  const status = entry.status === "failed" ? "\u2717" : entry.status === "success" ? "\u2713" : "\u25CB";
-  if (entry.type === "command") {
-    const dur = entry.durationMs ? `(${entry.durationMs}ms)` : "";
-    return `${time} ${status} ${entry.cmd} ${dur}`;
-  }
-  if (entry.type === "error") {
-    return `${time} \u2717 ERROR: ${entry.error}`;
-  }
-  return `${time} ${entry.type}: ${entry.cmd || ""}`;
-}
-async function listCommand(args, globalOptions) {
-  const listOptions = parseListArgs(args);
-  if (listOptions.help) {
-    console.log(HELP);
-    return;
-  }
-  if (listOptions.logPath || listOptions.logTail !== void 0 || listOptions.info) {
-    let session;
-    if (globalOptions.session) {
-      session = await loadSession(globalOptions.session);
-    } else {
-      session = await getDefaultSession();
-    }
-    if (!session) {
-      throw new Error('No session found. Run "bp connect" first or specify with -s.');
-    }
-    const logger = getSessionLogger(session.id);
-    if (listOptions.logPath) {
-      console.log(logger.getLogPath());
-      return;
-    }
-    if (listOptions.logTail !== void 0) {
-      const entries = logger.tailLog(listOptions.logTail);
-      if (globalOptions.format === "json") {
-        output(entries, "json");
-        return;
-      }
-      if (entries.length === 0) {
-        console.log("No log entries.");
-        return;
-      }
-      console.log(`Last ${entries.length} log entries for session ${session.id}:
-`);
-      for (const entry of entries) {
-        console.log(`  ${formatLogEntry(entry)}`);
-      }
-      return;
-    }
-    if (listOptions.info) {
-      const stats = logger.getLogStats();
-      if (globalOptions.format === "json") {
-        output({ session, logStats: stats }, "json");
-        return;
-      }
-      console.log(`Session: ${session.id}
-`);
-      console.log(`  Provider: ${session.provider}`);
-      console.log(`  Created: ${new Date(session.createdAt).toLocaleString()}`);
-      console.log(`  Last activity: ${new Date(session.lastActivity).toLocaleString()}`);
-      console.log(`  URL: ${session.currentUrl}`);
-      if (session.exportLog) {
-        console.log(`  Export log: ${session.exportLog}`);
-      }
-      console.log("");
-      console.log("Log Stats:");
-      console.log(`  Path: ${logger.getLogPath()}`);
-      console.log(`  Entries: ${stats.entries}`);
-      console.log(`  Size: ${formatBytes3(stats.size)}`);
-      if (stats.first) {
-        console.log(`  First: ${new Date(stats.first).toLocaleString()}`);
-      }
-      if (stats.last) {
-        console.log(`  Last: ${new Date(stats.last).toLocaleString()}`);
-      }
-      return;
-    }
-  }
-  const sessions = await listSessions();
-  const TWO_DAYS_MS = 2 * 24 * 60 * 60 * 1e3;
-  const now = Date.now();
-  const stale = sessions.filter((s) => now - new Date(s.lastActivity).getTime() > TWO_DAYS_MS);
-  const fresh = sessions.filter((s) => now - new Date(s.lastActivity).getTime() <= TWO_DAYS_MS);
-  if (stale.length > 0) {
-    for (const s of stale) {
-      await deleteSessionFull(s.id);
-    }
-  }
-  if (globalOptions.format === "json") {
-    output(fresh, "json");
-    return;
-  }
-  if (stale.length > 0) {
-    console.log(`Cleaned ${stale.length} stale session(s) (>2 days old).
-`);
-  }
-  if (fresh.length === 0) {
-    console.log("No active sessions.");
-    console.log('Run "bp connect" to create a new session.');
-    return;
-  }
-  console.log("Active Sessions:\n");
-  console.log("  Tip: bp list -s <name> --log-tail     View action log");
-  console.log("       bp list -s <name> --log-path     Get log file path\n");
-  const displaySessions = fresh.slice(0, 20);
-  for (const session of displaySessions) {
-    const age = getAge(new Date(session.lastActivity));
-    const daemonStatus = session.daemon ? isDaemonAlive(session.daemon.pid) ? "running" : "dead" : "none";
-    console.log(`  ${session.id}`);
-    console.log(`    Provider: ${session.provider}`);
-    console.log(`    URL: ${session.currentUrl}`);
-    console.log(`    Last activity: ${age}`);
-    console.log(`    Daemon: ${daemonStatus}`);
-    console.log("");
-  }
-  if (fresh.length > 20) {
-    console.log(`  (showing 20 of ${fresh.length} sessions)
-`);
-  }
-}
-function formatBytes3(bytes) {
-  if (bytes < 1024) return `${bytes} B`;
-  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
-  return `${(bytes / 1024 / 1024).toFixed(1)} MB`;
-}
-function getAge(date) {
-  const now = Date.now();
-  const diff = now - date.getTime();
-  const seconds = Math.floor(diff / 1e3);
-  if (seconds < 60) return "just now";
-  const minutes = Math.floor(seconds / 60);
-  if (minutes < 60) return `${minutes}m ago`;
-  const hours = Math.floor(minutes / 60);
-  if (hours < 24) return `${hours}h ago`;
-  const days = Math.floor(hours / 24);
-  return `${days}d ago`;
-}
-
-// src/cli/commands/listen.ts
-var LISTEN_HELP = `
-bp listen - Monitor network traffic (WebSocket/HTTP)
-
-Attach to a browser session and stream network events as JSONL.
-Status messages go to stderr; stdout is clean JSONL (pipeable to jq).
-
-Usage:
-  bp listen <mode> [options]
-
-Modes:
-  ws      WebSocket traffic only
-  http    HTTP requests/responses only
-  all     Both WebSocket and HTTP
-
-Options:
-  -s, --session [id]     Session to use (omit: auto-connect, -s: latest, -s <id>: specific)
-  -m, --match <glob>     Filter by URL glob pattern (e.g. "*realtime*")
-  -o, --output <file>    Write JSONL to file instead of stdout
-  --max-payload <n>      Max text payload preview length (default: 256)
-  --timeout <ms>         Auto-stop after N milliseconds
-  -q, --quiet            Suppress stderr status messages
-  -h, --help             Show this help
-
-Output Format (JSONL):
-  {"ts":"...","type":"ws:created","requestId":"1.2","url":"wss://..."}
-  {"ts":"...","type":"ws:frame:sent","requestId":"1.2","opcode":1,"length":142,"payload":"..."}
-  {"ts":"...","type":"ws:frame:recv","requestId":"1.2","opcode":2,"length":24000,"payload":"[binary: 18000 bytes]"}
-  {"ts":"...","type":"ws:closed","requestId":"1.2"}
-  {"ts":"...","type":"http:request","requestId":"3.1","method":"POST","url":"https://..."}
-  {"ts":"...","type":"http:response","requestId":"3.1","status":200,"mimeType":"application/json"}
-
-Examples:
-  # Debug a voice agent's WebSocket protocol
-  bp listen ws -m "*voice*" -o voice-traffic.jsonl
-
-  # Watch all API calls during a session
-  bp listen http -m "*/api/*" --max-payload 1024
-
-  # Capture everything for 60 seconds
-  bp listen all -o full-trace.jsonl --timeout 60000
-
-  # Pipe to jq for live filtering
-  bp listen ws | jq 'select(.type == "ws:frame:recv")'
-`;
-function parseListenArgs(args) {
-  const options = {};
-  for (let i = 0; i < args.length; i++) {
-    const arg = args[i];
-    if (arg === "-m" || arg === "--match") {
-      options.match = args[++i];
-    } else if (arg === "-o" || arg === "--output") {
-      options.output = args[++i];
-    } else if (arg === "--max-payload") {
-      options.maxPayload = Number.parseInt(args[++i] ?? "", 10);
-    } else if (arg === "--timeout") {
-      options.timeout = Number.parseInt(args[++i] ?? "", 10);
-    } else if (arg === "-q" || arg === "--quiet") {
-      options.quiet = true;
-    } else if (arg === "-h" || arg === "--help") {
-      options.help = true;
-    } else if (arg === "-s" || arg === "--session") {
-      const nextArg = args[i + 1];
-      if (!nextArg || nextArg.startsWith("-")) {
-        options.useLatestSession = true;
-      }
-    } else if (!arg.startsWith("-") && !options.mode) {
-      if (arg === "ws" || arg === "http" || arg === "all") {
-        options.mode = arg;
-      }
-    }
-  }
-  return options;
-}
-function globToRegex(pattern) {
-  const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&");
-  const withWildcards = escaped.replace(/\*/g, ".*");
-  return new RegExp(`^${withWildcards}$`);
-}
-var TrafficMonitor = class {
-  cdp;
-  opts;
-  matchRegex;
-  wsUrls = /* @__PURE__ */ new Map();
-  httpUrls = /* @__PURE__ */ new Map();
-  handlers = [];
-  lineCount = 0;
-  constructor(cdp, opts) {
-    this.cdp = cdp;
-    this.opts = opts;
-    this.matchRegex = opts.match ? globToRegex(opts.match) : null;
-  }
-  emit(record) {
-    this.opts.write(JSON.stringify(record));
-    this.lineCount++;
-  }
-  matchesUrl(url) {
-    if (!this.matchRegex) return true;
-    return this.matchRegex.test(url);
-  }
-  formatPayload(payloadData, opcode) {
-    const data = payloadData ?? "";
-    if (opcode === 2) {
-      const byteLength = Math.floor(data.length * 3 / 4);
-      return { payload: `[binary: ${byteLength} bytes]`, length: data.length };
-    }
-    const length = data.length;
-    if (length > this.opts.maxPayload) {
-      return {
-        payload: `${data.slice(0, this.opts.maxPayload)}... [truncated, ${length} total]`,
-        length
-      };
-    }
-    return { payload: data, length };
-  }
-  subscribe(event, handler) {
-    this.cdp.on(event, handler);
-    this.handlers.push({ event, handler });
-  }
-  start() {
-    const mode = this.opts.mode;
-    if (mode === "ws" || mode === "all") {
-      this.subscribe("Network.webSocketCreated", (params) => {
-        const url = params["url"];
-        const requestId = params["requestId"];
-        if (!this.matchesUrl(url)) return;
-        this.wsUrls.set(requestId, url);
-        this.emit({
-          ts: (/* @__PURE__ */ new Date()).toISOString(),
-          type: "ws:created",
-          requestId,
-          url
-        });
-      });
-      this.subscribe("Network.webSocketFrameSent", (params) => {
-        const requestId = params["requestId"];
-        if (!this.wsUrls.has(requestId)) return;
-        const response = params["response"];
-        const opcode = response?.opcode ?? 1;
-        const { payload, length } = this.formatPayload(response?.payloadData, opcode);
-        this.emit({
-          ts: (/* @__PURE__ */ new Date()).toISOString(),
-          type: "ws:frame:sent",
-          requestId,
-          opcode,
-          length,
-          payload
-        });
-      });
-      this.subscribe("Network.webSocketFrameReceived", (params) => {
-        const requestId = params["requestId"];
-        if (!this.wsUrls.has(requestId)) return;
-        const response = params["response"];
-        const opcode = response?.opcode ?? 1;
-        const { payload, length } = this.formatPayload(response?.payloadData, opcode);
-        this.emit({
-          ts: (/* @__PURE__ */ new Date()).toISOString(),
-          type: "ws:frame:recv",
-          requestId,
-          opcode,
-          length,
-          payload
-        });
-      });
-      this.subscribe("Network.webSocketClosed", (params) => {
-        const requestId = params["requestId"];
-        if (!this.wsUrls.has(requestId)) return;
-        this.wsUrls.delete(requestId);
-        this.emit({
-          ts: (/* @__PURE__ */ new Date()).toISOString(),
-          type: "ws:closed",
-          requestId
-        });
-      });
-    }
-    if (mode === "http" || mode === "all") {
-      this.subscribe("Network.requestWillBeSent", (params) => {
-        const request = params["request"];
-        const url = request?.url ?? "";
-        const requestId = params["requestId"];
-        if (!this.matchesUrl(url)) return;
-        this.httpUrls.set(requestId, url);
-        this.emit({
-          ts: params["wallTime"] ? new Date(params["wallTime"] * 1e3).toISOString() : (/* @__PURE__ */ new Date()).toISOString(),
-          type: "http:request",
-          requestId,
-          method: request?.method ?? "GET",
-          url
-        });
-      });
-      this.subscribe("Network.responseReceived", (params) => {
-        const requestId = params["requestId"];
-        if (!this.httpUrls.has(requestId)) return;
-        const response = params["response"];
-        this.emit({
-          ts: (/* @__PURE__ */ new Date()).toISOString(),
-          type: "http:response",
-          requestId,
-          status: response?.status ?? 0,
-          mimeType: response?.mimeType ?? ""
-        });
-      });
-      this.subscribe("Network.loadingFailed", (params) => {
-        const requestId = params["requestId"];
-        if (!this.httpUrls.has(requestId)) return;
-        this.emit({
-          ts: (/* @__PURE__ */ new Date()).toISOString(),
-          type: "http:failed",
-          requestId,
-          errorText: params["errorText"] ?? ""
-        });
-      });
-    }
-  }
-  stop() {
-    for (const { event, handler } of this.handlers) {
-      this.cdp.off(event, handler);
-    }
-    this.handlers = [];
-  }
-};
-async function resolveConnection2(sessionId, useLatestSession, trace) {
-  if (sessionId) {
-    const session2 = await loadSession(sessionId);
-    const browser2 = await connect({
-      provider: session2.provider,
-      wsUrl: session2.wsUrl,
-      debug: trace
-    });
-    return { browser: browser2, session: session2 };
-  }
-  if (useLatestSession) {
-    const session2 = await getDefaultSession();
-    if (!session2) {
-      throw new Error('No sessions found. Run "bp connect" first or omit -s to auto-connect.');
-    }
-    const browser2 = await connect({
-      provider: session2.provider,
-      wsUrl: session2.wsUrl,
-      debug: trace
-    });
-    return { browser: browser2, session: session2 };
+}
+function formatLogEntry(entry) {
+  const time = new Date(entry.ts).toLocaleTimeString();
+  const status = entry.status === "failed" ? "\u2717" : entry.status === "success" ? "\u2713" : "\u25CB";
+  if (entry.type === "command") {
+    const dur = entry.durationMs ? `(${entry.durationMs}ms)` : "";
+    return `${time} ${status} ${entry.cmd} ${dur}`;
   }
-  let wsUrl;
-  try {
-    wsUrl = await getBrowserWebSocketUrl("localhost:9222");
-  } catch {
-    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 listen -s <session-id>\n  3. Use latest session: bp listen -s"
-    );
+  if (entry.type === "error") {
+    return `${time} \u2717 ERROR: ${entry.error}`;
   }
-  const browser = await connect({ provider: "generic", wsUrl, debug: trace });
-  const page = await browser.page();
-  const currentUrl = await page.url();
-  const newSessionId = generateSessionId();
-  const session = {
-    id: newSessionId,
-    provider: "generic",
-    wsUrl: browser.wsUrl,
-    createdAt: (/* @__PURE__ */ new Date()).toISOString(),
-    lastActivity: (/* @__PURE__ */ new Date()).toISOString(),
-    currentUrl
-  };
-  await saveSession(session);
-  return { browser, session };
+  return `${time} ${entry.type}: ${entry.cmd || ""}`;
 }
-async function listenCommand(args, globalOptions) {
-  const options = parseListenArgs(args);
-  if (options.help || globalOptions.help || !options.mode) {
-    console.log(LISTEN_HELP);
+async function listCommand(args, globalOptions) {
+  const listOptions = parseListArgs(args);
+  if (listOptions.help) {
+    console.log(HELP);
     return;
   }
-  const log = options.quiet ? () => {
-  } : (msg) => process.stderr.write(`${msg}
+  if (listOptions.logPath || listOptions.logTail !== void 0 || listOptions.info) {
+    let session;
+    if (globalOptions.session) {
+      session = await loadSession(globalOptions.session);
+    } else {
+      session = await getDefaultSession();
+    }
+    if (!session) {
+      throw new Error('No session found. Run "bp connect" first or specify with -s.');
+    }
+    const logger = getSessionLogger(session.id);
+    if (listOptions.logPath) {
+      console.log(logger.getLogPath());
+      return;
+    }
+    if (listOptions.logTail !== void 0) {
+      const entries = logger.tailLog(listOptions.logTail);
+      if (globalOptions.format === "json") {
+        output(entries, "json");
+        return;
+      }
+      if (entries.length === 0) {
+        console.log("No log entries.");
+        return;
+      }
+      console.log(`Last ${entries.length} log entries for session ${session.id}:
 `);
-  const { browser, session } = await resolveConnection2(
-    globalOptions.session,
-    options.useLatestSession ?? false,
-    globalOptions.trace ?? false
-  );
-  let outputStream;
-  if (options.output) {
-    const fs7 = await import("fs");
-    const fileStream = fs7.createWriteStream(options.output, { flags: "w" });
-    outputStream = {
-      write: (line) => fileStream.write(`${line}
-`),
-      close: () => fileStream.end()
-    };
-    log(`Writing to ${options.output}`);
-  } else {
-    outputStream = {
-      write: (line) => {
-        try {
-          process.stdout.write(`${line}
+      for (const entry of entries) {
+        console.log(`  ${formatLogEntry(entry)}`);
+      }
+      return;
+    }
+    if (listOptions.info) {
+      const stats = logger.getLogStats();
+      if (globalOptions.format === "json") {
+        output({ session, logStats: stats }, "json");
+        return;
+      }
+      console.log(`Session: ${session.id}
 `);
-        } catch {
-          process.exit(0);
-        }
+      console.log(`  Provider: ${session.provider}`);
+      console.log(`  Created: ${new Date(session.createdAt).toLocaleString()}`);
+      console.log(`  Last activity: ${new Date(session.lastActivity).toLocaleString()}`);
+      console.log(`  URL: ${session.currentUrl}`);
+      if (session.exportLog) {
+        console.log(`  Export log: ${session.exportLog}`);
       }
-    };
-    process.stdout.on("error", (err) => {
-      if (err.code === "EPIPE") {
-        process.exit(0);
+      console.log("");
+      console.log("Log Stats:");
+      console.log(`  Path: ${logger.getLogPath()}`);
+      console.log(`  Entries: ${stats.entries}`);
+      console.log(`  Size: ${formatBytes3(stats.size)}`);
+      if (stats.first) {
+        console.log(`  First: ${new Date(stats.first).toLocaleString()}`);
       }
-    });
+      if (stats.last) {
+        console.log(`  Last: ${new Date(stats.last).toLocaleString()}`);
+      }
+      return;
+    }
   }
-  try {
-    const page = await browser.page(void 0, { targetId: session.targetId });
-    const cdp = page.cdpClient;
-    await cdp.send("Network.enable");
-    const monitor = new TrafficMonitor(cdp, {
-      mode: options.mode,
-      match: options.match,
-      maxPayload: options.maxPayload ?? 256,
-      write: (line) => outputStream.write(line)
-    });
-    monitor.start();
-    const matchLabel = options.match ? ` matching "${options.match}"` : "";
-    log(`Listening for ${options.mode} traffic${matchLabel} (session: ${session.id})`);
-    log("Press Ctrl+C to stop.");
-    let cleaned = false;
-    const cleanup = () => {
-      if (cleaned) return;
-      cleaned = true;
-      monitor.stop();
-      log(`
-Stopped. ${monitor.lineCount} events captured.`);
-      outputStream.close?.();
-      browser.disconnect().catch(() => {
-      });
-      process.exit(0);
-    };
-    process.on("SIGINT", cleanup);
-    process.on("SIGTERM", cleanup);
-    if (options.timeout && options.timeout > 0) {
-      setTimeout(() => {
-        log(`
-Timeout reached (${options.timeout}ms).`);
-        cleanup();
-      }, options.timeout);
+  const sessions = await listSessions();
+  const TWO_DAYS_MS = 2 * 24 * 60 * 60 * 1e3;
+  const now = Date.now();
+  const stale = sessions.filter((s) => now - new Date(s.lastActivity).getTime() > TWO_DAYS_MS);
+  const fresh = sessions.filter((s) => now - new Date(s.lastActivity).getTime() <= TWO_DAYS_MS);
+  if (stale.length > 0) {
+    for (const s of stale) {
+      await deleteSessionFull(s.id);
     }
-    await new Promise(() => {
-    });
-  } catch (error) {
-    outputStream.close?.();
-    await browser.disconnect();
-    throw error;
   }
+  if (globalOptions.format === "json") {
+    output(fresh, "json");
+    return;
+  }
+  if (stale.length > 0) {
+    console.log(`Cleaned ${stale.length} stale session(s) (>2 days old).
+`);
+  }
+  if (fresh.length === 0) {
+    console.log("No active sessions.");
+    console.log('Run "bp connect" to create a new session.');
+    return;
+  }
+  console.log("Active Sessions:\n");
+  console.log("  Tip: bp list -s <name> --log-tail     View action log");
+  console.log("       bp list -s <name> --log-path     Get log file path\n");
+  const displaySessions = fresh.slice(0, 20);
+  for (const session of displaySessions) {
+    const age = getAge(new Date(session.lastActivity));
+    const daemonStatus = session.daemon ? isDaemonAlive(session.daemon.pid) ? "running" : "dead" : "none";
+    console.log(`  ${session.id}`);
+    console.log(`    Provider: ${session.provider}`);
+    console.log(`    URL: ${session.currentUrl}`);
+    console.log(`    Last activity: ${age}`);
+    console.log(`    Daemon: ${daemonStatus}`);
+    console.log("");
+  }
+  if (fresh.length > 20) {
+    console.log(`  (showing 20 of ${fresh.length} sessions)
+`);
+  }
+}
+function formatBytes3(bytes) {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+  return `${(bytes / 1024 / 1024).toFixed(1)} MB`;
+}
+function getAge(date) {
+  const now = Date.now();
+  const diff = now - date.getTime();
+  const seconds = Math.floor(diff / 1e3);
+  if (seconds < 60) return "just now";
+  const minutes = Math.floor(seconds / 60);
+  if (minutes < 60) return `${minutes}m ago`;
+  const hours = Math.floor(minutes / 60);
+  if (hours < 24) return `${hours}h ago`;
+  const days = Math.floor(hours / 24);
+  return `${days}d ago`;
 }
 
 // src/cli/commands/page.ts
 var PAGE_HELP = `
 bp page - Show a compact overview of the current page
 
+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\`.
+
+Likely next commands:
+  bp snapshot -i
+  bp forms
+  bp exec '[{"action":"click","selector":"ref:e4"}]'
+
 Usage:
   bp page [options]
 
@@ -3938,8 +4775,9 @@ async function quickstartCommand() {
 
 // src/cli/commands/record.ts
 import * as nodeFs2 from "fs";
-import { homedir as homedir5 } from "os";
-import { join as join8 } from "path";
+import { existsSync as existsSync6 } from "fs";
+import { homedir as homedir6 } from "os";
+import { dirname as dirname7, join as join9, resolve as resolve5 } from "path";
 
 // src/recording/aggregator.ts
 var INPUT_DEBOUNCE_MS = 300;
@@ -4686,6 +5524,15 @@ var RECORDER_SCRIPT = `(function() {
 })();`;
 
 // src/recording/recorder.ts
+function readString(value) {
+  return typeof value === "string" ? value : void 0;
+}
+function readStringOr(value, fallback = "") {
+  return readString(value) ?? fallback;
+}
+function formatConsoleArg(entry) {
+  return readString(entry["value"]) ?? readString(entry["description"]) ?? "";
+}
 var Recorder = class {
   cdp;
   options;
@@ -4705,6 +5552,8 @@ var Recorder = class {
   pendingBodies = [];
   wsUrls = /* @__PURE__ */ new Map();
   httpUrls = /* @__PURE__ */ new Map();
+  traceEvents = [];
+  traceHandlers = [];
   constructor(cdp, options) {
     this.cdp = cdp;
     this.options = options ?? {};
@@ -4726,6 +5575,7 @@ var Recorder = class {
       throw new Error("Recording already in progress");
     }
     this.events = [];
+    this.traceEvents = [];
     this.startTime = Date.now();
     this.recording = true;
     await this.cdp.send("Runtime.enable");
@@ -4740,23 +5590,75 @@ var Recorder = class {
       this.startUrl = "";
     }
     await this.cdp.send("Runtime.addBinding", { name: RECORDER_BINDING_NAME });
+    await this.cdp.send("Runtime.addBinding", { name: TRACE_BINDING_NAME });
     await this.cdp.send("Page.addScriptToEvaluateOnNewDocument", {
       source: RECORDER_SCRIPT
     });
+    await this.cdp.send("Page.addScriptToEvaluateOnNewDocument", {
+      source: TRACE_SCRIPT
+    });
     await this.cdp.send("Runtime.evaluate", {
       expression: RECORDER_SCRIPT,
       awaitPromise: false
     });
+    await this.cdp.send("Runtime.evaluate", {
+      expression: TRACE_SCRIPT,
+      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(payload);
       }
     };
     this.cdp.on("Runtime.bindingCalled", this.bindingHandler);
+    this.subscribeTrace("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(" ");
+      this.traceEvents.push(
+        normalizeTraceEvent({
+          traceId: createTraceId("console"),
+          sessionId: "",
+          ts: (/* @__PURE__ */ new Date()).toISOString(),
+          elapsedMs: this.elapsed(),
+          channel: "console",
+          event: `console.${type}`,
+          severity: type === "error" ? "error" : type === "warn" ? "warn" : "info",
+          summary: text || `console.${type}`,
+          data: { args },
+          url: this.startUrl
+        })
+      );
+    });
+    this.subscribeTrace("Runtime.exceptionThrown", (params) => {
+      const details = params["exceptionDetails"] ?? {};
+      this.traceEvents.push(
+        normalizeTraceEvent({
+          traceId: createTraceId("runtime"),
+          ts: (/* @__PURE__ */ new Date()).toISOString(),
+          elapsedMs: this.elapsed(),
+          channel: "runtime",
+          event: "runtime.exception",
+          severity: "error",
+          summary: readString(details["text"]) ?? "Runtime exception",
+          data: details,
+          url: this.startUrl
+        })
+      );
+    });
     if (this.options.listen) {
       const listenOpts = typeof this.options.listen === "boolean" ? { mode: "all" } : this.options.listen;
       this.listenOpts = listenOpts;
-      this.matchRegex = listenOpts.match ? globToRegex2(listenOpts.match) : null;
+      this.matchRegex = listenOpts.match ? globToRegex(listenOpts.match) : null;
       await this.cdp.send("Network.enable");
       this.setupNetworkListeners(listenOpts);
     }
@@ -4780,6 +5682,10 @@ var Recorder = class {
       this.cdp.off(event, handler);
     }
     this.networkHandlers = [];
+    for (const { event, handler } of this.traceHandlers) {
+      this.cdp.off(event, handler);
+    }
+    this.traceHandlers = [];
     if (this.listenOpts) {
       await this.cdp.send("Network.disable");
     }
@@ -4790,7 +5696,8 @@ var Recorder = class {
       recordedAt: new Date(this.startTime).toISOString(),
       startUrl: this.startUrl,
       duration,
-      steps
+      steps,
+      traceEvents: this.traceEvents
     };
     if (this.listenOpts) {
       const mode = this.listenOpts.mode ?? "all";
@@ -4831,11 +5738,35 @@ var Recorder = class {
     } catch {
     }
   }
+  handleTraceBindingCall(payload) {
+    if (!this.recording) return;
+    try {
+      const data = JSON.parse(payload);
+      this.traceEvents.push(
+        normalizeTraceEvent({
+          traceId: createTraceId("trace"),
+          ts: data.ts ? new Date(data.ts).toISOString() : (/* @__PURE__ */ new Date()).toISOString(),
+          elapsedMs: this.elapsed(),
+          channel: this.channelForTraceEvent(data.event),
+          event: data.event,
+          severity: data.severity,
+          summary: data.summary ?? data.event,
+          data: data.data ?? {},
+          url: typeof data.data?.["url"] === "string" ? data.data["url"] : this.startUrl
+        })
+      );
+    } catch {
+    }
+  }
   /** Subscribe to a CDP event, tracking for cleanup. */
   subscribeNetwork(event, handler) {
     this.cdp.on(event, handler);
     this.networkHandlers.push({ event, handler });
   }
+  subscribeTrace(event, handler) {
+    this.cdp.on(event, handler);
+    this.traceHandlers.push({ event, handler });
+  }
   /** Check if a URL matches the configured filter. */
   matchesUrl(url) {
     if (!this.matchRegex) return true;
@@ -4879,6 +5810,20 @@ var Recorder = class {
           type: "created",
           url
         });
+        this.traceEvents.push(
+          normalizeTraceEvent({
+            traceId: createTraceId("ws"),
+            ts: new Date(now).toISOString(),
+            elapsedMs: this.elapsed(),
+            channel: "ws",
+            event: "ws.connection.created",
+            summary: `WebSocket opened ${url}`,
+            data: { url },
+            connectionId: requestId,
+            requestId,
+            url
+          })
+        );
       });
       this.subscribeNetwork("Network.webSocketFrameSent", (params) => {
         const requestId = params["requestId"];
@@ -4896,6 +5841,20 @@ var Recorder = class {
           payload,
           length
         });
+        this.traceEvents.push(
+          normalizeTraceEvent({
+            traceId: createTraceId("ws"),
+            ts: new Date(now).toISOString(),
+            elapsedMs: this.elapsed(),
+            channel: "ws",
+            event: "ws.frame.sent",
+            summary: `WebSocket frame sent ${requestId}`,
+            data: { opcode, payload, length },
+            connectionId: requestId,
+            requestId,
+            url: this.wsUrls.get(requestId)
+          })
+        );
       });
       this.subscribeNetwork("Network.webSocketFrameReceived", (params) => {
         const requestId = params["requestId"];
@@ -4913,10 +5872,25 @@ var Recorder = class {
           payload,
           length
         });
+        this.traceEvents.push(
+          normalizeTraceEvent({
+            traceId: createTraceId("ws"),
+            ts: new Date(now).toISOString(),
+            elapsedMs: this.elapsed(),
+            channel: "ws",
+            event: "ws.frame.received",
+            summary: `WebSocket frame received ${requestId}`,
+            data: { opcode, payload, length },
+            connectionId: requestId,
+            requestId,
+            url: this.wsUrls.get(requestId)
+          })
+        );
       });
       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({
@@ -4925,6 +5899,21 @@ var Recorder = class {
           elapsedMs: this.elapsed(),
           type: "closed"
         });
+        this.traceEvents.push(
+          normalizeTraceEvent({
+            traceId: createTraceId("ws"),
+            ts: new Date(now).toISOString(),
+            elapsedMs: this.elapsed(),
+            channel: "ws",
+            event: "ws.connection.closed",
+            severity: "warn",
+            summary: `WebSocket closed ${requestId}`,
+            data: { url: url ?? null },
+            connectionId: requestId,
+            requestId,
+            url
+          })
+        );
       });
     }
     if (mode === "http" || mode === "all") {
@@ -4944,6 +5933,23 @@ var Recorder = class {
           headers: request?.headers,
           body: request?.postData
         });
+        this.traceEvents.push(
+          normalizeTraceEvent({
+            traceId: createTraceId("http"),
+            ts: new Date(now).toISOString(),
+            elapsedMs: this.elapsed(),
+            channel: "http",
+            event: "http.request.sent",
+            summary: `${request?.method ?? "GET"} ${url}`,
+            data: {
+              method: request?.method ?? "GET",
+              headers: request?.headers ?? {},
+              body: request?.postData ?? null
+            },
+            requestId,
+            url
+          })
+        );
       });
       this.subscribeNetwork("Network.responseReceived", (params) => {
         const requestId = params["requestId"];
@@ -4958,6 +5964,23 @@ var Recorder = class {
           headers: response?.headers,
           mimeType: response?.mimeType
         });
+        this.traceEvents.push(
+          normalizeTraceEvent({
+            traceId: createTraceId("http"),
+            ts: new Date(now).toISOString(),
+            elapsedMs: this.elapsed(),
+            channel: "http",
+            event: "http.response.received",
+            summary: `${response?.status ?? 0} ${this.httpUrls.get(requestId) ?? ""}`,
+            data: {
+              status: response?.status ?? 0,
+              headers: response?.headers ?? {},
+              mimeType: response?.mimeType ?? null
+            },
+            requestId,
+            url: this.httpUrls.get(requestId)
+          })
+        );
         if (this.listenOpts?.captureResponseBodies) {
           const bodyPromise = this.cdp.send("Network.getResponseBody", {
             requestId
@@ -4972,8 +5995,37 @@ var Recorder = class {
           this.pendingBodies.push(bodyPromise);
         }
       });
+      this.subscribeNetwork("Network.loadingFailed", (params) => {
+        const requestId = params["requestId"];
+        this.traceEvents.push(
+          normalizeTraceEvent({
+            traceId: createTraceId("http"),
+            ts: (/* @__PURE__ */ new Date()).toISOString(),
+            elapsedMs: this.elapsed(),
+            channel: "http",
+            event: "http.response.failed",
+            severity: "error",
+            summary: `HTTP request failed ${requestId}`,
+            data: {
+              errorText: params["errorText"] ?? null,
+              blockedReason: params["blockedReason"] ?? null,
+              canceled: params["canceled"] ?? false
+            },
+            requestId,
+            url: this.httpUrls.get(requestId)
+          })
+        );
+      });
     }
   }
+  channelForTraceEvent(eventName) {
+    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";
+  }
   /** Build a merged timeline from action events and network events. */
   buildTimeline() {
     const entries = [];
@@ -5021,7 +6073,7 @@ var Recorder = class {
     return entries;
   }
 };
-function globToRegex2(pattern) {
+function globToRegex(pattern) {
   const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&");
   const withWildcards = escaped.replace(/\*/g, ".*");
   return new RegExp(`^${withWildcards}$`);
@@ -5029,48 +6081,57 @@ function globToRegex2(pattern) {
 
 // src/cli/commands/record.ts
 var RECORD_HELP = `
-bp record - Record browser actions to JSON
+bp record - Capture a human demo into one canonical artifact
+
+When to use:
+  A human is demonstrating the workflow and you want replayable automation later.
+
+When not to use:
+  You already have steps and just want to run or validate them. Use \`bp exec\` or \`bp run\`.
+
+Default flow:
+  capture -> summary -> inspect or trace -> derive -> run
+
+Common mistake:
+  Opening \`recording.json\` first. Start with \`bp record summary\`.
 
 Usage:
   bp record [options]
-
-Options:
-  -s, --session [id]  Session to use:
-                        - omit -s: auto-connect to local browser
-                        - -s alone: use most recent session
-                        - -s <id>: use specific session
-  -f, --file <path>   Output file (default: recording.json)
-  --timeout <ms>      Auto-stop after timeout (optional)
-  --listen [mode]     Capture network traffic: ws, http, or all (default: all)
-  --bodies            Capture HTTP response bodies (requires --listen)
-  -m, --match <glob>  Filter network URLs by glob pattern (requires --listen)
-  --max-payload <n>   Max WebSocket payload preview length (default: 256)
-  -h, --help          Show this help
+  bp record <inspect|summary|derive|export> [artifact] [options]
+
+Capture options:
+  -s, --session [id]   Session to use (omit: auto-connect, -s: latest, -s <id>: specific)
+  -f, --file <path>    Artifact output path (default: recording.json)
+  --timeout <ms>       Auto-stop after timeout
+  --profile <name>     automation | realtime | voice | auth (default: automation)
+  --listen [mode]      ws | http | all (default: all)
+  --bodies             Capture HTTP response bodies
+  -m, --match <glob>   Filter HTTP/WS URLs
+  --max-payload <n>    Max WebSocket payload preview length (default: 256)
+
+Artifact subcommands:
+  inspect [artifact]   Show artifact metadata and next commands
+  summary [artifact]   Show workflow summary plus trace views
+  derive <artifact> -o <output>   Write replayable steps for bp run
+  export <artifact> -o <output>   Write canonical triage bundle
 
 Examples:
-  bp record                              # Auto-connect to local Chrome
-  bp record -s                           # Use most recent session
-  bp record -s mysession                 # Use specific session
-  bp record -f login.json                # Save to specific file
-  bp record --timeout 60000              # Auto-stop after 60s
-  bp record --listen                     # Record actions + all network traffic
-  bp record --listen ws -m "*voice*"     # Record actions + matching WS traffic
-  bp record --listen http --bodies       # Record actions + HTTP with bodies
-
-Recording captures: clicks, inputs, form submissions, navigation.
-Screenshots are captured automatically after each interaction and saved
-to the session directory (~/.browser-pilot/sessions/<id>/screenshots/).
-When --listen is enabled, network traffic is captured alongside actions
-and merged into a unified timeline in the output file.
-Sensitive fields are automatically redacted as [REDACTED] based on the
-field settings (password, hidden, one-time-code, card autofill hints).
-Recording also enables session-level auto-recording for subsequent
-bp exec calls (equivalent to bp connect --record).
-
-Press Ctrl+C to stop recording and save.
-`;
+  bp record -s demo --profile automation
+  bp record --profile voice --bodies
+  bp record summary recording.json
+  bp record inspect recording.json
+  bp record derive recording.json -o workflow.json
+  bp record export recording.json -o bundle.json
+
+Likely next commands:
+  bp record summary recording.json
+  bp trace summary recording.json --view ws
+  bp record derive recording.json -o workflow.json
+`.trim();
+var DEFAULT_ARTIFACT = "recording.json";
 function parseRecordArgs(args) {
   const options = {};
+  let nextIsArtifact = false;
   for (let i = 0; i < args.length; i++) {
     const arg = args[i];
     if (arg === "-f" || arg === "--file") {
@@ -5086,7 +6147,7 @@ function parseRecordArgs(args) {
       }
     } else if (arg === "--listen") {
       const nextArg = args[i + 1];
-      if (nextArg && (nextArg === "ws" || nextArg === "http" || nextArg === "all")) {
+      if (nextArg === "ws" || nextArg === "http" || nextArg === "all") {
         options.listen = nextArg;
         i++;
       } else {
@@ -5098,176 +6159,265 @@ function parseRecordArgs(args) {
       options.match = args[++i];
     } else if (arg === "--max-payload") {
       options.maxPayload = Number.parseInt(args[++i] ?? "", 10);
+    } else if (arg === "--profile") {
+      const profile = args[++i];
+      if (profile === "automation" || profile === "realtime" || profile === "voice" || profile === "auth") {
+        options.profile = profile;
+      }
+    } else if (arg === "-o" || arg === "--output") {
+      options.output = args[++i];
+    } else if (!arg.startsWith("-") && !options.subcommand && !nextIsArtifact) {
+      if (isSubcommand(arg)) {
+        options.subcommand = arg;
+        nextIsArtifact = arg !== "capture";
+      } else if (!options.artifactPath) {
+        options.artifactPath = arg;
+      }
+    } else if (!arg.startsWith("-") && nextIsArtifact && !options.artifactPath) {
+      options.artifactPath = arg;
+      nextIsArtifact = false;
     }
   }
   return options;
 }
-async function resolveConnection3(sessionId, useLatestSession, trace) {
+function isSubcommand(value) {
+  return value === "capture" || value === "inspect" || value === "summary" || value === "derive" || value === "export";
+}
+async function resolveConnection3(sessionId, useLatestSession, debug) {
   if (sessionId) {
     const session2 = await loadSession(sessionId);
     const browser2 = await connect({
       provider: session2.provider,
       wsUrl: session2.wsUrl,
-      debug: trace
+      debug
     });
     return { browser: browser2, session: session2, isNewSession: false };
   }
   if (useLatestSession) {
     const session2 = await getDefaultSession();
     if (!session2) {
-      throw new Error(
-        'No sessions found. Run "bp connect" first or use "bp record" to auto-connect.'
-      );
+      throw new Error('No sessions found. Run "bp connect" first or omit -s to auto-connect.');
     }
     const browser2 = await connect({
       provider: session2.provider,
       wsUrl: session2.wsUrl,
-      debug: trace
+      debug
     });
     return { browser: browser2, session: session2, isNewSession: false };
   }
   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 record -s <session-id>\n  3. Use latest session: bp record -s"
+      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({
     provider: "generic",
     wsUrl,
-    debug: trace
+    debug
   });
   const page = await browser.page();
   const currentUrl = await page.url();
-  const newSessionId = generateSessionId();
   const session = {
-    id: newSessionId,
+    id: generateSessionId(),
     provider: "generic",
     wsUrl: browser.wsUrl,
     createdAt: (/* @__PURE__ */ new Date()).toISOString(),
     lastActivity: (/* @__PURE__ */ new Date()).toISOString(),
     currentUrl
   };
-  await saveSession(session);
-  return { browser, session, isNewSession: true };
+  await saveSession(session);
+  return { browser, session, isNewSession: true };
+}
+function artifactSessionDir(sessionId) {
+  return join9(homedir6(), ".browser-pilot", "sessions", sessionId);
+}
+function resolveArtifactPath(explicit, session) {
+  if (explicit) {
+    return resolve5(explicit);
+  }
+  if (session) {
+    return join9(artifactSessionDir(session.id), DEFAULT_ARTIFACT);
+  }
+  return resolve5(DEFAULT_ARTIFACT);
+}
+function normalizeProfile(profile) {
+  return profile ?? "automation";
+}
+function tipsForArtifact(path) {
+  return {
+    tip: {
+      reason: "summary_first",
+      command: `bp record summary ${path}`
+    },
+    alternateTips: [
+      {
+        reason: "derive_replayable_steps",
+        command: `bp record derive ${path} -o workflow.json`
+      },
+      {
+        reason: "inspect_trace_views",
+        command: `bp trace summary ${path} --view ws`
+      }
+    ]
+  };
 }
-async function recordCommand(args, globalOptions) {
-  const options = parseRecordArgs(args);
-  if (options.help || globalOptions.help) {
-    console.log(RECORD_HELP);
-    return;
+function buildSummary(artifact, source) {
+  return {
+    source,
+    version: artifact.version,
+    session: artifact.session,
+    counts: {
+      steps: artifact.recipe.steps.length,
+      actions: artifact.actions.length,
+      screenshots: artifact.screenshots.length,
+      traceEvents: artifact.trace.events.length,
+      assertions: artifact.assertions.length
+    },
+    trace: artifact.trace.summaries,
+    tips: tipsForArtifact(source)
+  };
+}
+function deriveAssertions(artifact) {
+  const assertions = [];
+  if (artifact.session.endUrl) {
+    assertions.push({ action: "assertUrl", expect: artifact.session.endUrl });
+  }
+  for (const action of artifact.actions) {
+    if (action.action === "fill" && action.selector && typeof action.value === "string") {
+      assertions.push({
+        action: "assertValue",
+        selector: action.selector,
+        expect: action.value
+      });
+    }
+  }
+  return assertions;
+}
+async function loadArtifact(pathOrFallback) {
+  if (!existsSync6(pathOrFallback)) {
+    throw new Error(`Artifact not found: ${pathOrFallback}`);
   }
-  const outputFile = options.file ?? "recording.json";
+  const raw = JSON.parse(nodeFs2.readFileSync(pathOrFallback, "utf-8"));
+  return { path: pathOrFallback, artifact: canonicalizeRecordingArtifact(raw) };
+}
+function artifactToFrames(artifact) {
+  const screenshotsByAction = new Map(artifact.screenshots.map((shot) => [shot.actionId, shot]));
+  return artifact.actions.map((action, index) => {
+    const screenshot = screenshotsByAction.get(action.id);
+    return {
+      seq: index + 1,
+      timestamp: Date.parse(action.ts),
+      action: action.action,
+      selector: action.selector,
+      selectorUsed: action.selectorUsed,
+      value: action.value,
+      url: action.url,
+      coordinates: action.coordinates,
+      boundingBox: action.boundingBox,
+      success: action.success,
+      durationMs: action.durationMs,
+      error: action.error,
+      screenshot: screenshot?.file ?? "",
+      pageUrl: action.pageUrl,
+      pageTitle: action.pageTitle,
+      stepIndex: action.stepIndex,
+      actionId: action.id
+    };
+  });
+}
+async function runRecordCapture(args, globalOptions) {
+  const profile = normalizeProfile(args.profile);
   const { browser, session, isNewSession } = await resolveConnection3(
     globalOptions.session,
-    options.useLatestSession ?? false,
+    args.useLatestSession ?? false,
     globalOptions.trace ?? false
   );
   if (isNewSession) {
     console.log(`Created new session: ${session.id}`);
   }
   if (!session.metadata?.record) {
-    const recordSettings = {};
-    await updateSession(session.id, { metadata: { record: recordSettings } });
+    const recordSettings2 = {};
+    await updateSession(session.id, { metadata: { record: recordSettings2 } });
   }
-  const page = await browser.page();
+  const page = await browser.page(void 0, { targetId: session.targetId });
   const cdp = page.cdpClient;
-  let listenConfig;
-  if (options.listen) {
-    const listenOpts = {
-      mode: typeof options.listen === "string" ? options.listen : "all",
-      match: options.match,
-      captureResponseBodies: options.bodies,
-      maxPayload: options.maxPayload
-    };
-    listenConfig = listenOpts;
-  }
-  const sessionDir = join8(homedir5(), ".browser-pilot", "sessions", session.id);
-  const screenshotDir = join8(sessionDir, "screenshots");
-  const manifestPath = join8(sessionDir, "recording.json");
+  const sessionDir = artifactSessionDir(session.id);
+  const screenshotDir = join9(sessionDir, "screenshots");
+  const canonicalPath = join9(sessionDir, DEFAULT_ARTIFACT);
+  const outputPath = resolve5(args.file ?? DEFAULT_ARTIFACT);
   nodeFs2.mkdirSync(screenshotDir, { recursive: true });
-  const recordingFrames = [];
-  let manifestRecordedAt = (/* @__PURE__ */ new Date()).toISOString();
-  let manifestStartUrl = "";
-  try {
-    const existing = JSON.parse(nodeFs2.readFileSync(manifestPath, "utf-8"));
-    if (existing.frames && Array.isArray(existing.frames)) {
-      recordingFrames.push(...existing.frames);
-    }
-    if (existing.recordedAt) manifestRecordedAt = existing.recordedAt;
-    if (existing.startUrl) manifestStartUrl = existing.startUrl;
-  } catch {
+  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",
+    match: args.match,
+    captureResponseBodies: Boolean(args.bodies),
+    maxPayload: args.maxPayload
+  };
+  if (args.listen === false) {
+    listenConfig = void 0;
+  }
+  if (!args.listen && profile === "voice") {
+    listenConfig = {
+      mode: "all",
+      match: args.match,
+      captureResponseBodies: Boolean(args.bodies),
+      maxPayload: args.maxPayload
+    };
   }
-  const recordFormat = session.metadata?.record?.format ?? "webp";
-  const recordQuality = session.metadata?.record?.quality ?? 40;
+  const recordSettings = session.metadata?.record;
+  const recordFormat = recordSettings?.format ?? "webp";
+  const recordQuality = recordSettings?.quality ?? 40;
   let screenshotCount = 0;
-  function eventKindLabel(kind) {
-    switch (kind) {
-      case "click":
-      case "dblclick":
-        return "click";
-      case "input":
-      case "change":
-        return "fill";
-      case "submit":
-        return "submit";
-      case "keydown":
-        return "press";
-      case "navigation":
-        return "goto";
-      default:
-        return kind;
-    }
-  }
   async function captureScreenshotForEvent(event) {
     try {
       const ts = Date.now();
       const seq = String(recordingFrames.length + 1).padStart(4, "0");
       const label = eventKindLabel(event.kind);
       const filename = `${seq}-${ts}-${label}.${recordFormat}`;
-      const filepath = join8(screenshotDir, filename);
+      const filepath = join9(screenshotDir, filename);
       const result = await cdp.send("Page.captureScreenshot", {
         format: recordFormat === "png" ? "png" : recordFormat === "jpeg" ? "jpeg" : "webp",
         quality: recordFormat === "png" ? void 0 : recordQuality
       });
-      const buffer = Buffer.from(result.data, "base64");
-      nodeFs2.writeFileSync(filepath, buffer);
+      nodeFs2.writeFileSync(filepath, Buffer.from(result.data, "base64"));
       let pageUrl;
       let pageTitle;
       try {
-        const urlResult = await cdp.send("Runtime.evaluate", {
-          expression: "location.href",
-          returnByValue: true
-        });
-        pageUrl = urlResult.result.value;
-        const titleResult = await cdp.send("Runtime.evaluate", {
-          expression: "document.title",
-          returnByValue: true
-        });
-        pageTitle = titleResult.result.value;
+        pageUrl = await page.url();
+        pageTitle = await page.title();
       } catch {
       }
       const targetMetadata = event.element ? {
-        tagName: event.element.tag,
-        inputType: event.element.type ?? void 0
+        tagName: event.element["tag"],
+        inputType: event.element["type"] ?? void 0
       } : void 0;
-      const frame = {
+      recordingFrames.push({
         seq: recordingFrames.length + 1,
         timestamp: ts,
         action: label,
         selector: event.selectors?.[0]?.selector,
+        selectorUsed: event.selectors?.[0]?.selector,
         value: redactValueForRecording(event.value, targetMetadata),
         coordinates: event.client,
         success: true,
         durationMs: 0,
         screenshot: `screenshots/${filename}`,
         pageUrl,
-        pageTitle
-      };
-      recordingFrames.push(frame);
-      screenshotCount++;
+        pageTitle,
+        stepIndex: recordingFrames.length,
+        actionId: `action-${recordingFrames.length + 1}`
+      });
+      screenshotCount += 1;
     } catch {
     }
   }
@@ -5277,108 +6427,194 @@ async function recordCommand(args, globalOptions) {
   };
   const recorder = new Recorder(cdp, recorderOptions);
   let stopping = false;
-  async function stopAndSave() {
-    if (stopping) return;
+  const stopAndSave = async () => {
+    if (stopping) {
+      return;
+    }
     stopping = true;
     try {
       const recording = await recorder.stop();
-      const fs7 = await import("fs/promises");
-      await fs7.writeFile(outputFile, JSON.stringify(recording, null, 2));
-      let currentUrl = "";
-      let viewport = { width: 1280, height: 720 };
-      try {
-        const urlResult = await cdp.send("Runtime.evaluate", {
-          expression: "location.href",
-          returnByValue: true
-        });
-        currentUrl = urlResult.result.value;
-      } catch {
-      }
-      try {
-        const metrics = await cdp.send("Page.getLayoutMetrics");
-        viewport = {
-          width: metrics.cssVisualViewport.clientWidth,
-          height: metrics.cssVisualViewport.clientHeight
-        };
-      } catch {
-      }
-      const manifest = {
-        version: 1,
-        recordedAt: manifestRecordedAt,
+      const currentUrl = await page.url().catch(() => recording.startUrl);
+      const manifest = createRecordingManifest({
+        recordedAt: existingArtifact?.recordedAt ?? recording.recordedAt,
         sessionId: session.id,
-        startUrl: manifestStartUrl || recording.startUrl,
+        startUrl: existingArtifact?.session.startUrl ?? recording.startUrl,
         endUrl: currentUrl,
-        viewport,
-        format: recordFormat,
-        quality: recordQuality,
-        totalDurationMs: recording.duration,
-        success: true,
-        frames: recordingFrames
-      };
-      nodeFs2.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2));
-      await updateSession(session.id, { currentUrl: currentUrl || recording.startUrl });
-      await browser.disconnect();
-      const networkInfo = recording.network ? `, ${recording.network.requests.length} HTTP requests` : "";
-      const wsInfo = recording.websockets ? `, ${recording.websockets.frames.length} WS frames` : "";
-      const timelineInfo = recording.timeline ? ` (${recording.timeline.length} timeline entries)` : "";
-      const screenshotInfo = screenshotCount > 0 ? `, ${screenshotCount} screenshots` : "";
-      console.log(
-        `
-Saved ${recording.steps.length} steps${screenshotInfo}${networkInfo}${wsInfo}${timelineInfo} to ${outputFile}`
-      );
-      if (screenshotCount > 0) {
-        console.log(`Screenshots: ${sessionDir}`);
+        targetId: page.targetId,
+        profile,
+        steps: recording.steps,
+        frames: recordingFrames,
+        traceEvents: recording.traceEvents ?? [],
+        assertions: deriveAssertions(
+          createRecordingManifest({
+            recordedAt: recording.recordedAt,
+            sessionId: session.id,
+            startUrl: recording.startUrl,
+            endUrl: currentUrl,
+            targetId: page.targetId,
+            profile,
+            steps: recording.steps,
+            frames: recordingFrames,
+            traceEvents: recording.traceEvents ?? []
+          })
+        ),
+        notes: profile === "voice" ? ["Voice profile capture"] : [],
+        recordingManifest: DEFAULT_ARTIFACT,
+        screenshotDir: "screenshots/"
+      });
+      nodeFs2.writeFileSync(canonicalPath, JSON.stringify(manifest, null, 2));
+      if (outputPath !== canonicalPath) {
+        nodeFs2.mkdirSync(dirname7(outputPath), { recursive: true });
+        nodeFs2.writeFileSync(outputPath, JSON.stringify(manifest, null, 2));
       }
+      await updateSession(session.id, { currentUrl });
+      await browser.disconnect();
+      const summary = buildSummary(manifest, outputPath);
       if (globalOptions.format === "json") {
-        output(
-          {
-            success: true,
-            file: outputFile,
-            steps: recording.steps.length,
-            screenshots: screenshotCount,
-            duration: recording.duration,
-            networkRequests: recording.network?.requests.length ?? 0,
-            wsFrames: recording.websockets?.frames.length ?? 0,
-            timelineEntries: recording.timeline?.length ?? 0
-          },
-          "json"
+        output({ success: true, ...summary }, "json");
+      } else {
+        console.log(
+          `Saved ${manifest.recipe.steps.length} steps, ${screenshotCount} screenshots, ${manifest.trace.events.length} trace events to ${outputPath}`
         );
+        console.log(`Use: bp record summary ${outputPath}`);
       }
-      process.exit(0);
     } catch (error) {
-      console.error("Error saving recording:", error);
+      console.error(
+        `Error saving recording: ${error instanceof Error ? error.message : String(error)}`
+      );
       process.exit(1);
     }
-  }
+  };
   const handleSignal = () => {
-    stopAndSave().catch((err) => {
-      console.error("Error during shutdown:", err);
-      process.exit(1);
-    });
+    void stopAndSave();
   };
   process.on("SIGINT", handleSignal);
   process.on("SIGTERM", handleSignal);
-  if (options.timeout && options.timeout > 0) {
-    setTimeout(() => {
-      void stopAndSave();
-    }, options.timeout);
+  if (args.timeout && args.timeout > 0) {
+    setTimeout(() => void stopAndSave(), args.timeout);
   }
   await recorder.start();
-  console.log(`Recording... Press Ctrl+C to stop and save to ${outputFile}`);
-  if (options.listen) {
-    const listenMode = typeof options.listen === "string" ? options.listen : "all";
-    const matchLabel = options.match ? ` matching "${options.match}"` : "";
-    console.log(`Network capture: ${listenMode} traffic${matchLabel}`);
-  }
+  console.log(`Recording... Press Ctrl+C to stop. Artifact: ${outputPath}`);
   console.log(`Session: ${session.id}`);
+  console.log(`Profile: ${profile}`);
   console.log(`URL: ${await page.url()}`);
 }
+async function runRecordInspect(pathHint, globalOptions) {
+  const session = globalOptions.session ? await loadSession(globalOptions.session) : await getDefaultSession();
+  const artifactPath = resolveArtifactPath(pathHint, session ?? void 0);
+  const { path, artifact } = await loadArtifact(artifactPath);
+  output(buildSummary(artifact, path), globalOptions.format ?? "pretty");
+}
+async function runRecordSummary(pathHint, globalOptions) {
+  const session = globalOptions.session ? await loadSession(globalOptions.session) : await getDefaultSession();
+  const artifactPath = resolveArtifactPath(pathHint, session ?? void 0);
+  const { path, artifact } = await loadArtifact(artifactPath);
+  const summary = buildSummary(artifact, path);
+  summary.trace = buildTraceSummaries(artifact.trace.events);
+  output(summary, globalOptions.format ?? "pretty");
+}
+async function runRecordDerive(pathHint, outputPath, globalOptions) {
+  if (!outputPath) {
+    throw new Error("record derive requires -o <workflow.json>");
+  }
+  const session = globalOptions.session ? await loadSession(globalOptions.session) : await getDefaultSession();
+  const artifactPath = resolveArtifactPath(pathHint, session ?? void 0);
+  const { artifact } = await loadArtifact(artifactPath);
+  const steps = artifact.recipe.steps;
+  nodeFs2.mkdirSync(dirname7(resolve5(outputPath)), { recursive: true });
+  nodeFs2.writeFileSync(outputPath, JSON.stringify(steps, null, 2));
+  output(
+    {
+      success: true,
+      output: outputPath,
+      steps: steps.length,
+      suggestedAssertions: deriveAssertions(artifact)
+    },
+    globalOptions.format ?? "pretty"
+  );
+}
+async function runRecordExport(pathHint, outputPath, globalOptions) {
+  if (!outputPath) {
+    throw new Error("record export requires -o <bundle.json>");
+  }
+  const session = globalOptions.session ? await loadSession(globalOptions.session) : await getDefaultSession();
+  const artifactPath = resolveArtifactPath(pathHint, session ?? void 0);
+  const { artifact, path } = await loadArtifact(artifactPath);
+  const bundle = {
+    source: path,
+    exportedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    artifact,
+    summary: buildSummary(artifact, path)
+  };
+  nodeFs2.mkdirSync(dirname7(resolve5(outputPath)), { recursive: true });
+  nodeFs2.writeFileSync(outputPath, JSON.stringify(bundle, null, 2));
+  output({ success: true, output: outputPath }, globalOptions.format ?? "pretty");
+}
+function eventKindLabel(kind) {
+  switch (kind) {
+    case "click":
+    case "dblclick":
+      return "click";
+    case "input":
+    case "change":
+      return "fill";
+    case "submit":
+      return "submit";
+    case "keydown":
+      return "press";
+    case "navigation":
+      return "goto";
+    default:
+      return kind;
+  }
+}
+async function recordCommand(args, globalOptions) {
+  const options = parseRecordArgs(args);
+  const command = options.subcommand ?? "capture";
+  if (options.help || globalOptions.help) {
+    console.log(RECORD_HELP);
+    return;
+  }
+  if (command === "capture") {
+    await runRecordCapture(options, globalOptions);
+    return;
+  }
+  const pathHint = options.artifactPath ?? DEFAULT_ARTIFACT;
+  switch (command) {
+    case "inspect":
+      await runRecordInspect(pathHint, globalOptions);
+      break;
+    case "summary":
+      await runRecordSummary(pathHint, globalOptions);
+      break;
+    case "derive":
+      await runRecordDerive(pathHint, options.output, globalOptions);
+      break;
+    case "export":
+      await runRecordExport(pathHint, options.output, globalOptions);
+      break;
+    default:
+      throw new Error(`Unknown record subcommand: ${command}`);
+  }
+}
 
 // src/cli/commands/run.ts
 import { readFile } from "fs/promises";
-import { resolve as resolve4 } from "path";
+import { resolve as resolve6 } from "path";
 var RUN_HELP = `
-bp run - Execute a workflow file (JSON steps)
+bp run - Execute a saved workflow file
+
+When to use:
+  You already have reusable steps from \`bp record derive\` or a hand-authored workflow.
+
+When not to use:
+  You are exploring a page inline or debugging one interaction. Use \`bp exec\`.
+
+Default flow:
+  derive or author workflow -> run -> inspect failures -> harden with assertions
+
+Common mistake:
+  Treating \`run\` as discovery. It is for repeatable execution, not first-pass exploration.
 
 Usage:
   bp run <workflow.json> [options]
@@ -5392,7 +6628,7 @@ Options:
   --timeout <ms>       Default timeout for all steps (ms)
   -s, --session <id>   Session to use (default: most recent)
   --json               Output results as JSON
-  --trace              Enable debug tracing
+  --debug              Enable CDP transport debugging (global option)
   -h, --help           Show this help
 
 Examples:
@@ -5400,7 +6636,9 @@ Examples:
   bp run checkout.json --on-fail continue --json
   bp run smoke-test.json --timeout 10000
 
-Run 'bp actions' for complete action reference.
+Likely next commands:
+  bp trace summary -s <session> --view console
+  bp exec --record -f workflow.json
 `.trimEnd();
 function parseRunArgs(args) {
   const options = {};
@@ -5438,7 +6676,7 @@ async function runCommand(args, globalOptions) {
       "No workflow file provided. Usage: bp run <workflow.json>\n\nRun 'bp run --help' for details."
     );
   }
-  const absPath = resolve4(workflowPath);
+  const absPath = resolve6(workflowPath);
   let raw;
   try {
     raw = await readFile(absPath, "utf-8");
@@ -5590,7 +6828,7 @@ async function screenshotCommand(args, globalOptions) {
 }
 
 // src/cli/commands/snapshot.ts
-import * as fs6 from "fs";
+import * as fs7 from "fs";
 
 // src/browser/overlay.ts
 var OVERLAY_SCRIPT = `(function() {
@@ -5841,7 +7079,19 @@ function formatDiffPretty(diff) {
 
 // src/cli/commands/snapshot.ts
 var SNAPSHOT_HELP = `
-bp snapshot - Get page accessibility snapshot with element refs
+bp snapshot - Inspect the page and collect refs
+
+When to use:
+  You need to understand the current page or choose reliable targets for \`bp exec\`.
+
+When not to use:
+  You need long-running behavior, network, or voice causality. Use \`bp trace\`.
+
+Default flow:
+  snapshot -i -> use ref:eN selectors in exec -> take a fresh snapshot after navigation
+
+Common mistake:
+  Reusing refs after the page navigated or materially changed.
 
 Usage:
   bp snapshot [options]
@@ -5857,16 +7107,21 @@ Options:
   -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
+  --debug                Enable CDP transport debugging (global option)
   -h, --help             Show this help
 
 Examples:
   bp snapshot                       # Full accessibility tree as readable text
-  bp snapshot -i                    # Interactive elements only (best for AI agents)
+  bp snapshot -i                    # Interactive elements only; best default for automation
   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
   bp snapshot --inspect             # Visual ref labels on the page
+
+Likely next commands:
+  bp exec '[{"action":"click","selector":"ref:e4"}]'
+  bp page
+  bp diagnose "ref:e4"
 `.trimEnd();
 function parseSnapshotArgs(args) {
   const options = {
@@ -5902,7 +7157,7 @@ function writeInfo(message, asStderr = false) {
 `);
 }
 function sleep2(ms) {
-  return new Promise((resolve5) => setTimeout(resolve5, ms));
+  return new Promise((resolve8) => setTimeout(resolve8, ms));
 }
 async function snapshotCommand(args, globalOptions) {
   const options = parseSnapshotArgs(args);
@@ -5939,10 +7194,10 @@ async function snapshotCommand(args, globalOptions) {
       }
     });
     if (options.diffFile) {
-      if (!fs6.existsSync(options.diffFile)) {
+      if (!fs7.existsSync(options.diffFile)) {
         throw new Error(`Diff file not found: ${options.diffFile}`);
       }
-      const beforeContent = fs6.readFileSync(options.diffFile, "utf-8");
+      const beforeContent = fs7.readFileSync(options.diffFile, "utf-8");
       const parsedBefore = JSON.parse(beforeContent);
       if (!isRecord(parsedBefore) || !Array.isArray(parsedBefore["accessibilityTree"])) {
         throw new Error("Diff file is not a valid PageSnapshot JSON payload");
@@ -5950,7 +7205,7 @@ async function snapshotCommand(args, globalOptions) {
       const beforeSnapshot = parsedBefore;
       const diff = diffSnapshots(beforeSnapshot, snapshot);
       if (options.outputFile) {
-        fs6.writeFileSync(options.outputFile, renderOutput(diff, globalOptions.format));
+        fs7.writeFileSync(options.outputFile, renderOutput(diff, globalOptions.format));
         writeInfo(`Wrote output to ${options.outputFile}`, true);
       } else if (globalOptions.format === "json") {
         output(diff, "json");
@@ -5990,7 +7245,7 @@ async function snapshotCommand(args, globalOptions) {
       }
     }
     if (options.outputFile) {
-      fs6.writeFileSync(options.outputFile, renderOutput(payload, globalOptions.format));
+      fs7.writeFileSync(options.outputFile, renderOutput(payload, globalOptions.format));
       writeInfo(`Wrote output to ${options.outputFile}`, true);
     } else {
       output(payload, globalOptions.format);
@@ -6064,6 +7319,15 @@ async function targetsCommand(_args, globalOptions) {
 var TEXT_HELP = `
 bp text - Extract text content from the current page
 
+When to use:
+  You need readable content for summarization, comparison, or assertions outside the action batch.
+
+When not to use:
+  You are choosing clickable or fillable targets. Use \`bp snapshot -i\` or \`bp page\`.
+
+Common mistake:
+  Expecting \`bp text\` to tell you what to click next. It is content-focused, not action-focused.
+
 Usage:
   bp text [options]
 
@@ -6072,13 +7336,17 @@ Options:
   -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
+  --debug              Enable CDP transport debugging (global option)
   -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
+
+Likely next commands:
+  bp snapshot -i
+  bp exec '[{"action":"assertText","expect":"..."}]'
 `.trimEnd();
 function parseTextArgs(args) {
   const options = {};
@@ -6127,56 +7395,404 @@ async function textCommand(args, globalOptions) {
   }
 }
 
+// src/cli/commands/trace.ts
+import * as fs8 from "fs";
+import { dirname as dirname8, resolve as resolve7 } from "path";
+var TRACE_HELP = `
+bp trace - Inspect, summarize, and watch behavior over time
+
+When to use:
+  The question spans time, causality, network, console, permissions, media, or voice state.
+
+When not to use:
+  You already know the target element and just need to click, fill, or assert DOM state once. Use \`bp exec\`.
+
+Default flow:
+  start or tail live capture -> summary by view -> watch if you need a durable assertion -> export evidence
+
+Common mistake:
+  Using \`trace\` as the primary action surface. It analyzes behavior; it does not replace \`exec\` or \`run\`.
+
+Usage:
+  bp trace <start|tail|summary|watch|export|merge> [artifact|trace.jsonl] [options]
+
+Commands:
+  start                 Capture live trace events into the session trace store
+  tail                  Stream live canonical events (listen compatibility surface)
+  summary               Summarize a session trace or saved artifact
+  watch                 Run a durable trace assertion over a live capture window
+  export                Export events + summary to JSON
+  merge                 Merge multiple artifacts or trace files
+
+Options:
+  -s, --session [id]    Session to use (omit: default session, -s: latest, -s <id>: specific)
+  --view <name>         ws | voice | console | permissions | media | ui | session
+  -m, --match <glob>    Filter HTTP/WS URLs for live capture
+  -o, --output <path>   Output file for start/export/merge
+  --timeout <ms>        Stop live capture or watch after timeout
+  --max-payload <n>     Max WebSocket payload preview length (default: 256)
+  --assert <name>       Watch assertion (profile:reconnect, no-console-errors)
+  -q, --quiet           Suppress status lines for live capture
+  -h, --help            Show help
+
+Examples:
+  bp trace start -s dev --timeout 30000
+  bp trace tail ws -m "*realtime*"
+  bp trace summary -s dev --view session
+  bp trace summary recording.json --view ws
+  bp trace watch -s dev --view ws --assert profile:reconnect --timeout 15000
+  bp trace watch -s dev --view console --assert no-console-errors --timeout 5000
+  bp trace export -s dev -o trace-bundle.json
+  bp trace merge trace-a.jsonl trace-b.jsonl -o merged-trace.json
+
+Likely next commands:
+  bp trace summary -s dev --view ws
+  bp trace summary -s dev --view voice
+  bp trace export -s dev -o trace-bundle.json
+`.trim();
+function parseTraceArgs(args) {
+  const options = { sources: [], view: "session" };
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (!options.subcommand && (arg === "start" || arg === "tail" || arg === "summary" || arg === "watch" || arg === "export" || arg === "merge")) {
+      options.subcommand = arg;
+      continue;
+    }
+    if (!options.subcommand && (arg === "ws" || arg === "http" || arg === "all")) {
+      options.subcommand = "tail";
+      options.mode = arg;
+      continue;
+    }
+    if (arg === "-o" || arg === "--output") {
+      options.output = args[++i];
+    } else if (arg === "--timeout") {
+      options.timeout = Number.parseInt(args[++i] ?? "", 10);
+    } else if (arg === "--view") {
+      const view = args[++i];
+      if (view === "ws" || view === "voice" || view === "console" || view === "permissions" || view === "media" || view === "ui" || view === "session") {
+        options.view = view;
+      }
+    } else if (arg === "--assert") {
+      options.assert = args[++i];
+    } else if (arg === "-m" || arg === "--match") {
+      options.match = args[++i];
+    } else if (arg === "--max-payload") {
+      options.maxPayload = Number.parseInt(args[++i] ?? "", 10);
+    } else if (arg === "-q" || arg === "--quiet") {
+      options.quiet = true;
+    } else if (arg === "-h" || arg === "--help") {
+      options.help = true;
+    } else if (arg === "-s" || arg === "--session") {
+      const nextArg = args[i + 1];
+      if (!nextArg || nextArg.startsWith("-")) {
+        options.useLatestSession = true;
+      }
+    } else if (arg === "ws" || arg === "http" || arg === "all") {
+      options.mode = arg;
+    } else if (!arg.startsWith("-")) {
+      if (!options.source) {
+        options.source = arg;
+      }
+      options.sources.push(arg);
+    }
+  }
+  options.subcommand ??= "summary";
+  return options;
+}
+async function resolveTraceSource(sourceHint, sessionId) {
+  if (sourceHint && fs8.existsSync(sourceHint)) {
+    if (sourceHint.endsWith(".jsonl")) {
+      return { path: resolve7(sourceHint), events: readTraceEvents(sourceHint) };
+    }
+    const raw = JSON.parse(fs8.readFileSync(sourceHint, "utf-8"));
+    const artifact = canonicalizeRecordingArtifact(raw);
+    return { path: resolve7(sourceHint), events: artifact.trace.events };
+  }
+  let session = null;
+  if (sessionId) {
+    session = await loadSession(sessionId);
+  } else {
+    session = await getDefaultSession();
+  }
+  if (!session) {
+    throw new Error('No session found. Run "bp connect" first or pass an artifact path.');
+  }
+  const tracePath = getSessionTracePath(session.id);
+  if (fs8.existsSync(tracePath)) {
+    return { path: tracePath, events: readTraceEvents(tracePath) };
+  }
+  const artifactPath = resolve7(getSessionTracePath(session.id), "..", "recording.json");
+  if (fs8.existsSync(artifactPath)) {
+    const raw = JSON.parse(fs8.readFileSync(artifactPath, "utf-8"));
+    const artifact = canonicalizeRecordingArtifact(raw);
+    return { path: artifactPath, events: artifact.trace.events };
+  }
+  return { path: tracePath, events: [] };
+}
+async function runLiveTrace(sessionId, options, debug, mode) {
+  const session = await resolveSession(sessionId);
+  const { browser, page } = await attachSession(session, { trace: debug });
+  const tracePath = getSessionTracePath(session.id);
+  fs8.mkdirSync(dirname8(tracePath), { recursive: true });
+  const sinkPath = options.output ? resolve7(options.output) : tracePath;
+  fs8.mkdirSync(dirname8(sinkPath), { recursive: true });
+  const liveEvents = [];
+  const collector = new LiveTraceCollector(page.cdpClient, {
+    sessionId: session.id,
+    targetId: page.targetId,
+    mode: options.mode ?? "all",
+    match: options.match,
+    maxPayload: options.maxPayload ?? 256,
+    onEvent: (event) => {
+      liveEvents.push(event);
+      if (mode !== "tail") {
+        fs8.appendFileSync(tracePath, `${JSON.stringify(event)}
+`, "utf-8");
+      }
+      if (options.output) {
+        fs8.appendFileSync(sinkPath, `${JSON.stringify(event)}
+`, "utf-8");
+      }
+      if (mode === "tail") {
+        process.stdout.write(`${JSON.stringify(event)}
+`);
+      }
+    }
+  });
+  const stopPromise = new Promise((resolveStop) => {
+    const stop = () => resolveStop();
+    process.once("SIGINT", stop);
+    process.once("SIGTERM", stop);
+    if (options.timeout && options.timeout > 0) {
+      setTimeout(stop, options.timeout);
+    }
+  });
+  if (!options.quiet && mode !== "tail") {
+    process.stderr.write(
+      `Tracing session ${session.id} -> ${mode === "start" ? tracePath : "stdout"}
+`
+    );
+  }
+  try {
+    await collector.start();
+    await stopPromise;
+    return await collector.stop();
+  } finally {
+    await browser.disconnect();
+  }
+}
+function evaluateWatchAssertion(events, assertion, view) {
+  if (assertion === "no-console-errors") {
+    const summary = buildTraceSummary(events, "console");
+    return {
+      ok: summary.errors === 0,
+      reason: summary.errors === 0 ? "No console errors detected" : `${summary.errors} console/runtime errors detected`
+    };
+  }
+  if (assertion === "profile:reconnect" && view === "ws") {
+    const wsEvents = events.filter((event) => event.event.startsWith("ws."));
+    const created = wsEvents.filter((event) => event.event === "ws.connection.created");
+    const closed = wsEvents.filter((event) => event.event === "ws.connection.closed");
+    const reopened = created.length > 1 || closed.length === 0;
+    return {
+      ok: created.length > 0 && reopened,
+      reason: created.length === 0 ? "No WebSocket connections were observed" : reopened ? "WebSocket stayed up or reconnected" : "WebSocket closed without a reconnect"
+    };
+  }
+  return {
+    ok: false,
+    reason: `Unsupported assertion: ${assertion}`
+  };
+}
+async function traceStart(options, globalOptions) {
+  const events = await runLiveTrace(
+    globalOptions.session,
+    options,
+    globalOptions.trace ?? false,
+    "start"
+  );
+  output(
+    {
+      success: true,
+      events: events.length,
+      output: getSessionTracePath((await resolveSession(globalOptions.session)).id)
+    },
+    "pretty"
+  );
+}
+async function traceTail(options, globalOptions) {
+  await runLiveTrace(globalOptions.session, options, globalOptions.trace ?? false, "tail");
+}
+async function traceSummary(options, globalOptions) {
+  const source = await resolveTraceSource(options.source, globalOptions.session);
+  const filtered = options.mode === "ws" ? source.events.filter((event) => event.channel === "ws") : options.mode === "http" ? source.events.filter((event) => event.channel === "http") : source.events;
+  const summary = buildTraceSummary(filtered, options.view ?? "session");
+  output(
+    {
+      source: source.path,
+      view: options.view ?? "session",
+      summary
+    },
+    globalOptions.format ?? "pretty"
+  );
+}
+async function traceWatch(options, globalOptions) {
+  const view = options.view ?? "session";
+  const events = options.source ? (await resolveTraceSource(options.source, globalOptions.session)).events : await runLiveTrace(globalOptions.session, options, globalOptions.trace ?? false, "watch");
+  const assertion = options.assert ?? (view === "ws" ? "profile:reconnect" : "no-console-errors");
+  const result = evaluateWatchAssertion(events, assertion, view);
+  if (!result.ok) {
+    throw new Error(result.reason);
+  }
+  output(
+    {
+      success: true,
+      assertion,
+      reason: result.reason,
+      summary: buildTraceSummary(events, view)
+    },
+    globalOptions.format ?? "pretty"
+  );
+}
+async function traceExport(options, globalOptions) {
+  if (!options.output) {
+    throw new Error("trace export requires -o <output.json>");
+  }
+  const source = await resolveTraceSource(options.source, globalOptions.session);
+  const payload = {
+    source: source.path,
+    exportedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    summary: buildTraceSummary(source.events, options.view ?? "session"),
+    views: buildTraceSummaries(source.events),
+    events: source.events
+  };
+  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) }, globalOptions.format ?? "pretty");
+}
+async function traceMerge(options, globalOptions) {
+  if (options.sources.length === 0) {
+    throw new Error("trace merge requires at least one artifact or trace file");
+  }
+  if (!options.output) {
+    throw new Error("trace merge requires -o <output.json>");
+  }
+  const merged = [];
+  for (const sourcePath of options.sources) {
+    const source = await resolveTraceSource(sourcePath, globalOptions.session);
+    merged.push(...source.events);
+  }
+  merged.sort((a, b) => new Date(a.ts).getTime() - new Date(b.ts).getTime());
+  const payload = {
+    mergedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    summary: buildTraceSummary(merged, options.view ?? "session"),
+    views: buildTraceSummaries(merged),
+    events: merged
+  };
+  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"
+  );
+}
+async function traceCommand(args, globalOptions) {
+  const options = parseTraceArgs(args);
+  if (options.help || globalOptions.help) {
+    console.log(TRACE_HELP);
+    return;
+  }
+  switch (options.subcommand) {
+    case "start":
+      await traceStart(options, globalOptions);
+      break;
+    case "tail":
+      await traceTail(options, globalOptions);
+      break;
+    case "summary":
+      await traceSummary(options, globalOptions);
+      break;
+    case "watch":
+      await traceWatch(options, globalOptions);
+      break;
+    case "export":
+      await traceExport(options, globalOptions);
+      break;
+    case "merge":
+      await traceMerge(options, globalOptions);
+      break;
+    default:
+      console.log(TRACE_HELP);
+  }
+}
+
 // src/cli/index.ts
 var HELP2 = `
-bp - Browser automation CLI for AI agents
+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
 
 Usage:
   bp <command> [options]
 
 Commands:
-  quickstart  Getting started guide (start here!)
-  connect     Create browser session
-  exec        Execute actions
-  eval        Evaluate JavaScript expression
-  page        Show a compact page overview
-  forms       List form controls on the page
+  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
-  run         Run a workflow file (JSON steps)
-  record      Record browser actions to JSON
-  audio       Audio I/O for voice agent testing
-  listen      Monitor network traffic (WebSocket/HTTP)
-  snapshot    Get page with element refs
-  diagnose    Debug element selection issues
-  text        Extract text content
-  screenshot  Take screenshot
-  daemon      Manage daemon processes (status, stop, logs)
+  daemon      Manage session daemon
+  list        List sessions
   close       Close session
-  list        List sessions (--log-path, --log-tail, --info)
-  clean       Clean up old sessions
+  clean       Clean old sessions and artifacts
   actions     Complete action reference
 
+Golden paths:
+  1. Automate a page
+     bp connect --provider generic --name dev
+     bp snapshot -i -s dev
+     bp exec -s dev '[{"action":"click","selector":"ref:e4"}]'
+
+  2. 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
+     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
-  --trace               Enable debug tracing
+  --debug               Enable debug logs for CDP transport
+  --trace               Legacy alias for --debug
   --dialog <mode>       Handle dialogs: accept | dismiss
   -h, --help            Show help
 
-Examples:
-  bp connect --provider generic --name dev
-  bp exec '{"action":"goto","url":"https://example.com"}'
-  bp exec --record '[{"action":"click","selector":"#checkout"}]'
-  bp snapshot -i
-  bp exec '{"action":"click","selector":"ref:e3"}'
-  bp clean --max-size 500MB
-  bp eval 'document.title'
-  bp audio roundtrip -i prompt.wav --transcribe --silence-timeout 5000
-
-Run 'bp quickstart' for CLI workflow guide.
-Run 'bp actions' for complete action reference.
-Run 'bp audio --help' for voice agent testing guide.
+Notes:
+  Start with "record summary" or "trace summary" before opening raw artifacts.
 `;
 function parseGlobalOptions(args) {
   const options = {
@@ -6198,7 +7814,8 @@ function parseGlobalOptions(args) {
       options.format = "json";
     } else if (arg === "--pretty") {
       options.format = "pretty";
-    } else if (arg === "--trace") {
+    } else if (arg === "--debug" || arg === "--trace") {
+      options.debug = true;
       options.trace = true;
     } else if (arg === "-h" || arg === "--help") {
       options.help = true;
@@ -6297,9 +7914,6 @@ async function main() {
       case "screenshot":
         await screenshotCommand(remaining, options);
         break;
-      case "daemon":
-        await daemonCommand(remaining, options);
-        break;
       case "close":
         await closeCommand(remaining, options);
         break;
@@ -6318,11 +7932,20 @@ async function main() {
       case "record":
         await recordCommand(remaining, options);
         break;
+      case "trace":
+        await traceCommand(remaining, options);
+        break;
       case "audio":
         await audioCommand(remaining, options);
         break;
+      case "env":
+        await envCommand(remaining, options);
+        break;
       case "listen":
-        await listenCommand(remaining, options);
+        await traceCommand(["tail", ...remaining], options);
+        break;
+      case "daemon":
+        await daemonCommand(remaining, options);
         break;
       case "help":
       case "--help":