@divebell/agent-browser 0.33.2-divebell.5 → 0.33.2-divebell.7

package/README.md

@@ -1,6 +1,6 @@
 # agent-browser
 
-Browser automation CLI for AI agents. This Divebell build adds memory diagnostics and code coverage support.
+Browser automation CLI for AI agents. This Divebell build adds compiled JavaScript debugging, safe logpoints, memory diagnostics, and code coverage support.
 
 [![skills.sh](https://skills.sh/b/vercel-labs/agent-browser)](https://skills.sh/vercel-labs/agent-browser)
 
@@ -111,7 +111,7 @@ agent-browser find role button click --name "Submit"
 
 ```bash
 agent-browser open                    # Launch browser (no navigation); stays on about:blank
-agent-browser open <url>              # Launch + navigate to URL (aliases: goto, navigate)
+agent-browser open <url> [--timeout <ms>] # Launch + navigate to URL (aliases: goto, navigate)
 agent-browser read [url]              # Fetch agent-readable text, or read rendered active-tab DOM
 agent-browser click <sel>             # Click element (--new-tab to open in new tab)
 agent-browser dblclick <sel>          # Double-click element
@@ -345,7 +345,7 @@ agent-browser click @e3              # click uses docs's refs
 agent-browser tab close docs         # close by label
 ```
 
-Switching to a tab discarded by Chrome's Memory Saver reactivates it, since a discarded tab has no renderer to drive. Reactivation reloads the discarded page and resets its unsaved state, and the switch result reports `"revived": true`. A tab whose page is paused by a JavaScript dialog is alive rather than discarded, so the switch leaves it untouched and reports `"dialogBlocked": true`; resolve the dialog with `dialog accept` or `dialog dismiss` before interacting. Closing the active tab onto a discarded successor revives it the same way and reports `"activeTabRevived": true`.
+Switching to a tab discarded by Chrome's Memory Saver reactivates it, since a discarded tab has no renderer to drive. Reactivation reloads the discarded page and resets its unsaved state, and the switch result reports `"revived": true`. A tab whose page is paused by a JavaScript dialog or debugger is alive rather than discarded, so the switch leaves it untouched and reports `"dialogBlocked": true` or `"debuggerPaused": true`. Resolve the dialog or resume the debugger before interacting. Closing the active tab onto a discarded successor revives it the same way and reports `"activeTabRevived": true`.
 
 ### Frames
 
@@ -394,6 +394,14 @@ agent-browser memory sampling stop     # Save allocation profile and top call si
 agent-browser memory snapshot          # Stream a heap snapshot to a local file
 agent-browser memory status            # Show the active capture
 agent-browser memory cancel            # Cancel the active capture
+agent-browser debug enable              # Enable compiled JavaScript debugging
+agent-browser debug scripts             # List loaded script instances
+agent-browser debug source search <text> # Search compiled sources
+agent-browser debug breakpoint set <script-id> <line> # Set a breakpoint
+agent-browser debug logpoint set <script-id> <line> --expression <js> # Add a logpoint
+agent-browser debug stack               # Inspect the current pause
+agent-browser debug resume              # Resume the current pause
+agent-browser debug events              # Read debugger and logpoint events
 agent-browser console                 # View console messages (log, error, warn, info)
 agent-browser console --json          # JSON output with raw CDP args for programmatic access
 agent-browser console --clear         # Clear console
@@ -411,6 +419,75 @@ agent-browser state clear --all       # Clear all saved states
 agent-browser state clean --older-than <days>  # Delete old states
 ```
 
+### Compiled JavaScript debugger
+
+The Chrome debugger works with the JavaScript that the browser actually loaded. It does not require project source files or source maps. This makes it suitable for production bundles, Rstack output, and Module Federation containers where only compiled assets are available.
+
+Start by enabling debugging, then locate a script and a compiled line:
+
+```bash
+agent-browser open https://app.example.com
+agent-browser debug enable
+agent-browser debug scripts --filter assets --json
+agent-browser debug source search "checkout" --filter assets --json
+```
+
+`debug scripts` returns a `scriptInstanceKey` scoped by connection generation, CDP session, document generation, and script ID. It also returns a separate `sourceLineageKey` and `runtimeOwner` evidence. Parent or initiator information is evidence only and is never used as identity. The generic substrate reports runtime ownership as `unknown` until a caller supplies reliable Host or Module Federation evidence. Persistent probes do not automatically rebind when ownership is unknown or ambiguous.
+
+Set a breakpoint using the returned script ID and one-based compiled line:
+
+```bash
+agent-browser debug breakpoint set 42 108 --strict --json
+agent-browser eval "startCheckout()"
+```
+
+When the page pauses, use another shell, agent tool call, or MCP call:
+
+```bash
+agent-browser debug status --json
+agent-browser debug stack --json
+agent-browser debug eval "order.id" --frame 0 --json
+agent-browser debug step-over
+agent-browser debug resume
+```
+
+Debugger inspection and control use a lock-independent daemon path. If the first CLI is waiting inside `eval`, `click`, or another renderer command that hit a breakpoint, a second CLI can still read the pause and resume it. When multiple tabs are paused, pass `--tab <tN>`, `--session <cdp-session-id>`, or `--pause-id <id>` to `stack`, `eval`, `resume`, and step commands.
+
+Locations use one-based lines and one-based UTF-16 columns. With only a line, `--strict` selects a breakable point on that line; an explicit `--column` must match exactly. The default `--after` mode resolves forward, while `--before` and `--nearest` use backward candidates only after Chrome proves that they reach an anchor in the requested function. `--nearest` prefers a forward point when distances tie. Resolution is bounded to three lines and 512 UTF-16 code units by default; tighten or explicitly expand those bounds with `--max-lines <n>` and `--max-utf16-distance <n>`. `--nearest-forward` remains a compatibility alias for `--after`. Breakpoint conditions and logpoint expressions are syntax checked with `Runtime.compileScript`. A valid expression can still fail when the selected runtime scope does not contain a referenced variable; the logpoint records that failure without creating an unrelated pause.
+
+Logpoints use a private Runtime binding rather than the page console:
+
+```bash
+agent-browser debug logpoint set 42 108 \
+  --when "order.ready" \
+  --expression "order" \
+  --expression "cart.total" \
+  --tag phase=checkout \
+  --json
+
+agent-browser debug events --since 0 --wait 5000 --json
+```
+
+Logpoints use a random per-connection Runtime binding name and nonce. Serialization is bounded by depth, property count, array length, string length, and a 64 KiB payload cap. It handles cycles, `BigInt`, non-finite numbers, functions, symbols, accessors, throwing getters, and proxies without pausing the page. A false `--when` condition emits nothing; a thrown condition is reported as `whenError`, while individual expression failures are reported as `evaluationError`. Incoming binding messages must match the active connection nonce, CDP session, execution context, logical probe, and physical binding. Script identity, location, tags, and owner metadata always come from the daemon registry rather than the page payload.
+
+Manage probes and lifecycle explicitly:
+
+```bash
+agent-browser debug breakpoint list --json
+agent-browser debug breakpoint remove <probe-id>
+agent-browser debug logpoint list --json
+agent-browser debug logpoint remove <probe-id>
+agent-browser debug disable --resume
+```
+
+Use `--persist` to request same-document rebinding after a new compiled script instance appears. Automatic rebinding requires a resolved runtime owner and an exact lineage match for session, document generation, execution context, compiled URL, and owner ID. Navigation, target detach, browser reconnect, and connection reset invalidate stale physical bindings. Rebinding never crosses a connection or document generation.
+
+`debug events` stores up to 10,000 events and 8 MiB per daemon session. Responses include `oldestSequence`, `latestSequence`, `gap`, `bufferGap`, `transportGap`, `droppedThroughSequence`, and `lastTransportGapSequence`. A `transport-gap` event reports CDP broadcast lag. Use `--since` as a cursor, `--wait` for bounded long polling, and `--clear` after consuming evidence.
+
+Debugger inspection uses the `debug.inspect` action-policy category, while probe changes and execution control use `debug.control`. Frame evaluation, logpoints, and conditional breakpoints also require `evaluate` because they run expressions in page context. When multiple policy categories apply, denial takes precedence over confirmation.
+
+The debugger is supported on Chrome and Chromium only. Reading one compiled source response is capped at 32 MiB; source search returns at most 100 matches by default with bounded context and accepts up to 1,000. The debugger is intentionally a generic CDP substrate. Rstack HMR cycle grouping and Module Federation shared-module consumer or runtime-instance attribution belong in the Divebell extension, which should consume script, probe, pause, and lifecycle events without changing core script identity.
+
 ### Memory diagnostics
 
 Memory diagnostics reuse the current agent-browser Chrome session. No separate CDP port or address is required. They are disabled on Lightpanda, Safari, and other engines that do not provide the required Chrome memory capabilities.
@@ -436,6 +513,7 @@ Heap snapshots and allocation profiles can contain page text, application data,
 ### Navigation
 
 ```bash
+agent-browser open <url> --timeout 40000 # Wait up to 40s for the page load lifecycle event
 agent-browser back                    # Go back
 agent-browser forward                 # Go forward
 agent-browser reload                  # Reload page
@@ -560,7 +638,7 @@ Profiles:
 - `core` — Default. Navigation, snapshots, interaction, waits, reads, screenshots, JavaScript eval, close, tab basics, and profile discovery
 - `network` — Network routes, request inspection, HAR, headers, credentials, offline
 - `state` — Cookies, storage, auth, saved state, sessions, profiles, skills
-- `debug` — Console/errors, tracing, profiling, recording, a11y audit, clipboard, plugins, doctor, dashboard, install, upgrade, chat, diff, batch, confirm/deny
+- `debug` — Compiled JavaScript breakpoints, logpoints, pause recovery, console/errors, tracing, profiling, recording, a11y audit, clipboard, plugins, doctor, dashboard, install, upgrade, chat, diff, batch, confirm/deny
 - `tabs` — Back/forward/reload, tabs, windows, frames, dialogs
 - `react` — React tree/inspect/renders/suspense, vitals, pushstate
 - `mobile` — Viewport/device/geolocation/media, touch, swipe, mouse, keyboard
@@ -1123,7 +1201,9 @@ Auto-discovered config files that are missing are silently ignored. If `--config
 
 ## Default Timeout
 
-The default timeout for standard operations (clicks, waits, fills, etc.) is 25 seconds. This is intentionally below the CLI's 30-second IPC read timeout so that the daemon returns a proper error instead of the CLI timing out with EAGAIN.
+The default timeout for standard operations (clicks, waits, fills, etc.) is 25 seconds. This is intentionally below the CLI's 30-second IPC read timeout so that the daemon returns a proper error instead of the CLI timing out with EAGAIN. Navigation commands (`open`, `goto`, and `navigate`) wait up to 60 seconds by default and receive a matching command transport budget.
+
+Pass `--timeout <ms>` to `open`, `goto`, or `navigate` to override the navigation lifecycle timeout for one command. `AGENT_BROWSER_DEFAULT_TIMEOUT` also overrides the navigation default. The effective navigation timeout is forwarded to the command transport with an additional response margin.
 
 Override the default timeout via environment variable:
 
@@ -1132,7 +1212,7 @@ Override the default timeout via environment variable:
 export AGENT_BROWSER_DEFAULT_TIMEOUT=45000
 ```
 
-> **Note:** Setting this above 30000 (30s) may cause EAGAIN errors on slow operations because the CLI's read timeout will expire before the daemon responds. The CLI retries transient errors automatically, but response times will increase.
+> **Note:** Navigation commands receive a transport budget that matches their effective timeout. For other slow operations, setting the environment variable above 30000 (30s) may still cause EAGAIN because their CLI read timeout can expire before the daemon responds.
 
 | Variable                        | Description                              |
 | ------------------------------- | ---------------------------------------- |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@divebell/agent-browser",
-  "version": "0.33.2-divebell.5",
+  "version": "0.33.2-divebell.7",
   "description": "Browser automation CLI for AI agents with Divebell memory diagnostics",
   "type": "module",
   "engines": {

package/skill-data/core/SKILL.md

@@ -384,6 +384,29 @@ agent-browser memory snapshot ./after.heapsnapshot
 
 Only one capture can be active per session. Sampling remains bound to the page where it started even if another tab becomes active. Use `memory status` to inspect the current capture and `memory cancel` to stop it safely. Keep `.heapprofile` and `.heapsnapshot` files local because they can contain page text, application data, credentials, and tokens. See [references/commands.md](references/commands.md#memory-diagnostics) for every option and output field.
 
+## Debugging compiled JavaScript
+
+Use the Chrome-only `debug` commands when a loaded bundle must be inspected without source files or source maps. Enable the debugger, search the compiled source, set a probe, then use a separate command to inspect or resume if execution pauses.
+
+```bash
+agent-browser debug enable
+agent-browser debug scripts --filter assets --json
+agent-browser debug source search "checkout" --filter assets --json
+agent-browser debug breakpoint set <script-id> <line> --strict --json
+agent-browser debug stack --json
+agent-browser debug eval "order.id" --frame 0 --json
+agent-browser debug resume
+```
+
+Debugger control bypasses the daemon's ordinary renderer-command lock, so it remains available when an earlier `eval`, click, or page action is stopped at a breakpoint. If more than one page is paused, select it with exactly one of `--tab`, `--session`, or `--pause-id`. Use logpoints when evidence is needed without pausing:
+
+```bash
+agent-browser debug logpoint set <script-id> <line> --when "order.ready" --expression "order" --json
+agent-browser debug events --since 0 --wait 5000 --json
+```
+
+Do not infer source identity from script parents. Use the returned script instance and lineage fields. Persistent rebinding is allowed only for a resolved runtime owner within the same connection, session, document generation, execution context, and compiled URL. See [references/debugging-compiled-js.md](references/debugging-compiled-js.md) for commands, lifecycle rules, safe log serialization, and HMR or Module Federation extension guidance.
+
 ## Diagnosing install issues
 
 If a command fails unexpectedly (`Unknown command`, `Failed to connect`, stale daemons, version mismatches after `upgrade`, missing Chrome, etc.) run `doctor` before anything else:
@@ -518,6 +541,7 @@ That pulls in:
 - `references/trust-boundaries.md` — safety rules for driving a real browser
 - `references/session-management.md` — persistence, multi-session workflows
 - `references/profiling.md` — Chrome DevTools tracing and profiling
+- `references/debugging-compiled-js.md` — compiled JavaScript breakpoints, logpoints, pause recovery, and lifecycle semantics
 - `references/video-recording.md` — video capture options
 - `references/streaming.md` covers live viewport streaming, remote input, per-client frame rate, and the encoding vars that set bandwidth cost
 - `references/proxy-support.md` — proxy configuration

package/skill-data/core/references/commands.md

@@ -8,7 +8,10 @@ Complete reference for all agent-browser commands. For quick start and common pa
 agent-browser open            # Launch browser (no navigation); stays on about:blank.
                               # Pair with `network route`, `cookies set --curl`, or
                               # `addinitscript` to stage state before the first navigation.
-agent-browser open <url>      # Launch + navigate (aliases: goto, navigate)
+agent-browser open <url> [--timeout <ms>]
+                              # Launch + navigate (aliases: goto, navigate)
+                              # Waits for the page load lifecycle event for 60s by default;
+                              # --timeout overrides that navigation wait for one command
                               # Supports: https://, http://, file://, about:, data://
                               # Auto-prepends https:// if no protocol given
 agent-browser read [url]      # Fetch agent-readable text, or read rendered active-tab DOM
@@ -229,7 +232,7 @@ agent-browser tab close docs             # close by label
 
 Labels are never auto-generated, never rewritten on navigation, and must be unique within a session. To interact with another tab, switch to it first: the daemon maintains a single active tab, so refs (`@eN`) belong to the tab that was active when the snapshot ran.
 
-Switching to a tab that the browser discarded to save memory reactivates it, since a discarded tab has no renderer to drive. Reactivation reloads the page and resets its unsaved state, and the switch result adds `"revived": true` so the reload is not silent. A tab whose page is paused by a JavaScript dialog is alive rather than discarded: the switch leaves it untouched and adds `"dialogBlocked": true`. Resolve the dialog with `dialog accept`/`dialog dismiss` and its state is preserved. Closing the active tab onto a discarded successor revives it the same way and reports `"activeTabRevived": true`.
+Switching to a tab that the browser discarded to save memory reactivates it, since a discarded tab has no renderer to drive. Reactivation reloads the page and resets its unsaved state, and the switch result adds `"revived": true` so the reload is not silent. A tab whose page is paused by a JavaScript dialog or debugger is alive rather than discarded: the switch leaves it untouched and adds `"dialogBlocked": true` or `"debuggerPaused": true`. Resolve the dialog or resume the debugger and its state is preserved. Closing the active tab onto a discarded successor revives it the same way and reports `"activeTabRevived": true`.
 
 ## Frames
 
@@ -356,7 +359,7 @@ Profiles:
 - `core` - Default. Navigation, snapshots, interaction, waits, reads, screenshots, JavaScript eval, close, tab basics, and profile discovery
 - `network` - Network routes, request inspection, HAR, headers, credentials, offline
 - `state` - Cookies, storage, auth, saved state, sessions, profiles, skills
-- `debug` - Console/errors, tracing, profiling, recording, a11y audit, clipboard, plugins, doctor, dashboard, install, upgrade, chat, diff, batch, confirm/deny
+- `debug` - Compiled JavaScript breakpoints, logpoints, pause recovery, console/errors, tracing, profiling, recording, a11y audit, clipboard, plugins, doctor, dashboard, install, upgrade, chat, diff, batch, confirm/deny
 - `tabs` - Back/forward/reload, tabs, windows, frames, dialogs
 - `react` - React tree/inspect/renders/suspense, vitals, pushstate
 - `mobile` - Viewport/device/geolocation/media, touch, swipe, mouse, keyboard
@@ -418,6 +421,39 @@ agent-browser profiler start              # Start Chrome DevTools profiling
 agent-browser profiler stop trace.json    # Stop and save profile
 ```
 
+### Compiled JavaScript debugger
+
+```bash
+agent-browser debug enable [--tab <tN> | --session <id>] [--all-tabs]
+agent-browser debug disable [selectors] [--all-tabs] [--resume]
+agent-browser debug status [--tab <tN> | --session <id> | --pause-id <id>]
+agent-browser debug scripts [--filter <url>] [--tab <tN> | --session <id>]
+agent-browser debug source <script-id> [selectors]
+agent-browser debug source search <text> [--filter <url>] [--max-results <count>]
+agent-browser debug breakpoint set <script-id> <line> [--column <n>] [--condition <js>] [--strict | --before | --after | --nearest] [--max-lines <n>] [--max-utf16-distance <n>] [--persist] [--tag <key=value>]
+agent-browser debug breakpoint list
+agent-browser debug breakpoint remove <probe-id>
+agent-browser debug logpoint set <script-id> <line> --expression <js>... [--when <js>] [--column <n>] [--strict | --before | --after | --nearest] [--max-lines <n>] [--max-utf16-distance <n>] [--persist] [--tag <key=value>]
+agent-browser debug logpoint list
+agent-browser debug logpoint remove <probe-id>
+agent-browser debug pause [selectors]
+agent-browser debug resume [pause selectors]
+agent-browser debug step-over|step-into|step-out [pause selectors]
+agent-browser debug stack [pause selectors]
+agent-browser debug eval <expression> [--frame <index> | --call-frame-id <id>] [pause selectors]
+agent-browser debug events [--since <sequence>] [--wait <ms>] [--clear]
+```
+
+All locations are one-based. Columns count UTF-16 code units. `--strict` requires the requested line and, when explicitly supplied, the exact column. `--after` is the default. `--before`, `--after`, and `--nearest` use `Debugger.getPossibleBreakpoints` with verified function boundaries, a default three-line bound, and a default 512 UTF-16 code unit distance. `--nearest-forward` remains a compatibility alias for `--after`.
+
+Debugger pause inspection and control are lock-independent. A second CLI or MCP request can use `status`, `stack`, frame `eval`, step, or `resume` while an ordinary command is blocked at a breakpoint. With multiple paused sessions, pause selectors are mandatory.
+
+Logpoints never use the page console as their authoritative channel. They call a random per-connection private Runtime binding with a connection nonce and physical binding ID. Values are serialized with depth, collection, string, and 64 KiB total payload limits. Cycles, accessors, getters, proxies, functions, symbols, `BigInt`, and non-finite numbers are represented safely. `--when` failures and individual expression failures are reported separately. Registry metadata is not trusted from the page payload.
+
+`debug events` is a persistent per-daemon ring capped at 10,000 events and 8 MiB. Use `latestSequence` as the next `--since` cursor. `bufferGap` and `droppedThroughSequence` report ring eviction. `transportGap`, `lastTransportGapSequence`, and the `transport-gap` event report CDP listener lag. The aggregate `gap` field is true for either condition.
+
+See [debugging-compiled-js.md](debugging-compiled-js.md) for the identity model, lifecycle invalidation, HMR rebinding constraints, Module Federation ownership boundaries, and MCP tool mapping.
+
 ## Memory diagnostics
 
 Memory commands require Chrome or Chromium. They reuse the current browser session and return `memory_unsupported_engine` on Lightpanda, Safari, or other unsupported engines.

package/skill-data/core/references/debugging-compiled-js.md

@@ -0,0 +1,185 @@
+# Compiled JavaScript debugging
+
+Use this workflow to debug JavaScript exactly as Chrome loaded it. Project sources and source maps are optional and are not consulted by these commands.
+
+## Start and discover scripts
+
+```bash
+agent-browser open https://app.example.com
+agent-browser debug enable
+agent-browser debug scripts --filter assets --json
+agent-browser debug source search "checkout" --filter assets --json
+agent-browser debug source <script-id>
+```
+
+`debug enable` enables `Runtime`, `Debugger`, and `Page` for the active tab. Pass `--all-tabs` to enable every current top-level page, or select one with `--tab <tN>` or `--session <cdp-session-id>`.
+
+`debug source <script-id>` returns at most 32 MiB in one response. `debug source search` returns one-based UTF-16 start and end coordinates, byte offsets, and at most 160 UTF-16 code units of context on each side. Search returns 100 matches by default and accepts an explicit maximum up to 1,000.
+
+`debug scripts` records each `Debugger.scriptParsed` event. Script records include URL, hash, execution context, compiled extent, runtime owner evidence, and two different identities:
+
+- `scriptInstanceKey` is `connectionGeneration + sessionId + documentGeneration + scriptId`. Use it for exact CDP operations.
+- `sourceLineageKey` is `sessionId + documentGeneration + executionContextId + URL or sourceURL + resolvedRuntimeOwnerId`. Use it only when deciding whether a logical probe may rebind to a new script instance.
+
+The initiating or parent script is evidence, never an identity component. Runtime ownership is reported with `status`, `kind`, `ownerId`, `confidence`, `evidence`, and `candidates`. A default page execution context can contain both Host and Module Federation remote code, so the generic substrate reports it as `unknown`. Reliable owner resolution belongs in the Divebell extension. `unknown` and `ambiguous` owners never auto-rebind.
+
+## Locations
+
+CLI locations are one-based. Columns count UTF-16 code units so non-ASCII compiled text maps to Chrome correctly.
+
+Before setting a probe, agent-browser calls `Debugger.getPossibleBreakpoints` with `restrictToFunction: true`.
+
+- `--strict` accepts a breakable location on the requested line. When `--column` is supplied, the column must also match.
+- `--before` selects the closest earlier location only after Chrome proves that it reaches an anchor in the requested function.
+- `--after` selects the closest location at or after the request in the same function. This is the default.
+- `--nearest` compares verified backward candidates with forward candidates and prefers forward when distances tie.
+- `--nearest-forward` is a compatibility alias for `--after`.
+- `--max-lines <n>` changes the default three-line bound, up to 500.
+- `--max-utf16-distance <n>` changes the default 512 UTF-16 code unit bound, up to 1,000,000.
+
+If no bounded location is found, the command fails without installing a breakpoint.
+
+## Breakpoints
+
+```bash
+agent-browser debug breakpoint set <script-id> <line> --strict --json
+agent-browser debug breakpoint set <script-id> <line> --condition "order.total > 100" --json
+agent-browser debug breakpoint list --json
+agent-browser debug breakpoint remove <probe-id>
+```
+
+Conditions are syntax checked with `Runtime.compileScript` in the script's execution context before the physical breakpoint is installed. Syntax success does not prove that runtime scope variables exist. Scope failures are returned as evaluation evidence and must not be converted into an unrelated debugger pause.
+
+A logical probe has a stable `probeId`. Each compiled script installation creates a separate physical record containing `physicalId`, CDP breakpoint ID, session, document generation, script ID, execution context, requested location, and actual location.
+
+## Pause recovery
+
+A normal daemon command holds ordinary browser state while it waits for a renderer response. A renderer stopped at a breakpoint cannot finish that command. Debugger inspection and control therefore use an independent controller, event receiver, state lock, and direct CDP command path.
+
+One shell can trigger a pause:
+
+```bash
+agent-browser eval "startCheckout()"
+```
+
+A second shell or MCP request can recover it:
+
+```bash
+agent-browser debug status --json
+agent-browser debug stack --json
+agent-browser debug eval "order.id" --frame 0 --json
+agent-browser debug step-over
+agent-browser debug resume
+```
+
+Each pause receives a generation-scoped `pauseId`. If exactly one session is paused, the selector can be omitted. If more than one session is paused, use exactly one of:
+
+```bash
+--tab <tN>
+--session <cdp-session-id>
+--pause-id <pause-id>
+```
+
+`debug eval` accepts either `--frame <zero-based-index>` or `--call-frame-id <id>`. An explicit call frame ID must belong to the selected pause.
+
+Ordinary renderer commands fail early when the active tab is already paused. Tab management remains available. A tab switch reports `debuggerPaused: true` rather than treating the paused renderer as a discarded tab and attempting recovery that could alter state.
+
+## Logpoints
+
+Logpoints collect evidence without pausing:
+
+```bash
+agent-browser debug logpoint set <script-id> <line> \
+  --when "order.ready" \
+  --expression "order" \
+  --expression "cart.total" \
+  --tag phase=checkout \
+  --json
+
+agent-browser debug events --since 0 --wait 5000 --json
+```
+
+The physical breakpoint condition always returns false. When `--when` is false it emits nothing. Otherwise it serializes each expression independently, then calls a random per-connection private Runtime binding. The browser console is not an authoritative delivery channel.
+
+Serialization has fixed limits for depth, properties, array items, strings, and a 64 KiB total payload. It does not invoke accessors through ordinary property reads. Cycles, `BigInt`, non-finite numbers, functions, symbols, accessors, throwing getters, proxy traps, and expression failures receive explicit representations rather than escaping the condition or pausing the page. A thrown `--when` expression is reported as `whenError`; a thrown value expression is reported as `evaluationError`.
+
+Every binding message is validated against:
+
+- connection nonce
+- CDP session
+- execution context when known
+- logical probe ID
+- active physical binding ID
+- enabled logpoint registry state
+
+The payload supplies only serialized expression values and the validation IDs. Script identity, compiled location, runtime owner, and tags come from the daemon registry. Rejected payloads create a `logpoint-rejected` event.
+
+Removing the final logpoint for a session calls `Runtime.removeBinding`. Disabling the debugger removes the binding and all Debugger-domain state.
+
+## Events and gaps
+
+```bash
+agent-browser debug events --since <sequence> --wait <milliseconds> --json
+agent-browser debug events --clear --json
+```
+
+The debugger keeps events independently of individual CLI connections. The ring is capped at 10,000 events and 8 MiB. Every response includes:
+
+- `oldestSequence`
+- `latestSequence`
+- `gap`
+- `bufferGap`
+- `transportGap`
+- `droppedThroughSequence`
+- `lastTransportGapSequence`
+
+`bufferGap: true` means the requested cursor is older than retained history. `transportGap: true` and a `transport-gap` event mean the controller's CDP broadcast receiver lagged after that cursor and browser events may have been lost. `gap` is true for either condition. Treat a gap as incomplete evidence and refresh debugger status, scripts, and probes before making automated conclusions.
+
+Relevant event types include `target-attached`, `target-detached`, `script-parsed`, `probe-bound`, `probe-unbound`, `probe-rebind-failed`, `probe-removed`, `debugger-paused`, `debugger-resumed`, `logpoint-hit`, `logpoint-rejected`, `document-invalidated`, `document-committed`, `execution-context-created`, `execution-context-destroyed`, `execution-contexts-cleared`, `session-detached`, `connection-reset`, `binding-residue`, and `transport-gap`.
+
+## Lifecycle and rebinding
+
+Navigation, target detach, browser close, and connection replacement invalidate physical bindings and pauses. Connection generation and document generation prevent stale IDs from being reused.
+
+`--persist` allows same-document rebinding when HMR creates a new script instance. Rebinding requires all of the following:
+
+- same browser connection generation
+- same CDP session
+- same document generation
+- same execution context
+- same compiled URL or sourceURL
+- same resolved runtime owner ID
+
+Unknown or ambiguous ownership changes the probe status to `awaiting-owner-evidence` and performs no automatic action. Navigation never inherits a probe into the next document generation. Browser reconnect never inherits a probe into the next connection generation.
+
+## Rstack HMR and Module Federation
+
+Core agent-browser deliberately provides generic CDP facts rather than framework conclusions. The Divebell extension should consume the event stream and add framework-specific grouping.
+
+For Rstack HMR, the extension should create a runtime-scoped cycle with a stable cycle ID, start and completion evidence, affected script instances, probe rebind attempts, and one of these outcomes: applied, failed, aborted, timed out, or incomplete because of an event gap. State preservation must be reported as `verified-preserved`, `verified-reset`, or `not-verified`; a successful HMR transport message is not proof that application state survived.
+
+For Module Federation shared modules, aggregate by consumer, runtime instance, and share scope. Do not aggregate only by package name or resolved URL. A host and multiple remotes can load the same compiled URL under different ownership and sharing decisions. If owner resolution has multiple candidates, preserve all candidates and report `ambiguous`; do not silently select a parent or initiator.
+
+## MCP mapping
+
+Start the server with the debug profile:
+
+```bash
+agent-browser mcp --tools debug
+```
+
+The profile includes dedicated typed tools for debugger enable, disable, status, scripts, source read and search, breakpoint set/list/remove, logpoint set/list/remove, pause, resume, step over/into/out, stack, frame evaluation, and events. Tool implementations delegate through the canonical CLI parser. Advanced global CLI fields, including session isolation and confirmation policy, remain available through the common MCP arguments.
+
+## Security
+
+Debugger commands use the same action policy and confirmation sources as ordinary commands. Inspection maps to `debug.inspect`, frame evaluation maps to `evaluate`, and mutation or execution control maps to `debug.control`. Logpoints and conditional breakpoints require both `debug.control` and `evaluate` because their expressions run in page context. Policy denial takes precedence over confirmation when multiple categories apply. Confirmation for debugger recovery is itself lock-independent, so a required approval does not make a paused page impossible to resume.
+
+Frame evaluation and logpoint expressions execute in page context and can have side effects. Treat them as code execution. Logpoint events can contain application data or credentials even with size limits. Keep event output within trusted agent and storage boundaries.
+
+## Limitations
+
+- Chrome and Chromium only
+- Compiled locations only; no source map remapping
+- Top-level page sessions are managed directly; framework worker attribution requires extension evidence
+- Persistent rebinding is conservative by design
+- HMR cycle semantics and Module Federation ownership are extension responsibilities