chore(release): 0.27.0-fork.21 — multi-client relay (concurrent agents)

The nm-host fanned extension→client messages over a broadcast channel and
forwarded commands under the client's own id, so two sessions connected to one
relay collided: command replies went to every client and ids overlapped → the
2nd session's connect hung (EAGAIN after 30s×5) and responses cross-talked.

Now the relay demultiplexes:
- each forwarded command is re-keyed to a relay-global id mapped to (client,
  original_id); the extension's reply routes back to ONLY that client with its
  original id restored (relay.rs: pending map + ClientId)
- CDP events fan out to all clients (they ignore unknown sessions)
- nm-host keeps a client_id -> sender registry instead of a broadcast; clients
  are unregistered + their pending dropped on disconnect

Unblocks concurrent multi-agent on one shared Chrome (each --session its own tab
group from fork.20). relay.rs: 9 unit tests incl. cross-client id isolation.

.github/workflows/release-binaries.yml

@@ -36,7 +36,7 @@ jobs:
           - { name: macOS ARM64,      os: macos-latest,  target: aarch64-apple-darwin,        asset: agent-browser-darwin-arm64,     use_zigbuild: false, ext: '' }
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
         with:
           ref: ${{ github.event.inputs.tag || github.ref }}
 
@@ -102,7 +102,7 @@ jobs:
           )
 
       - name: Upload artifact
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v7
         with:
           name: ${{ matrix.asset }}
           path: dist/${{ matrix.asset }}.tar.gz*
@@ -117,7 +117,7 @@ jobs:
       contents: write
     steps:
       - name: Download all artifacts
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@v8
         with:
           path: dist
           merge-multiple: true
@@ -126,7 +126,7 @@ jobs:
         run: ls -la dist
 
       - name: Attach to release
-        uses: softprops/action-gh-release@v2
+        uses: softprops/action-gh-release@v3
         with:
           tag_name: ${{ github.event.inputs.tag || github.ref_name }}
           files: |

.gitignore

@@ -67,3 +67,7 @@ docs/package-lock.json
 # next
 .next/
 out/
+
+# extension signing key (never commit) + local-only id record
+.secrets/
+*.pem

README.md

@@ -115,9 +115,10 @@ In CI environments, standalone mode is used automatically.
 
 ## Anti-detection
 
-When connected to your real Chrome, we inject **zero** JavaScript patches. Your browser's fingerprint is completely genuine.
+When connected to your real Chrome, we inject **zero** JavaScript patches. Your browser's fingerprint is completely genuine. The guiding rule is **native CDP/Chrome overrides over JS lies** — a re-defined getter is itself detectable; a native override isn't.
 
-The only thing we do is call `Emulation.setAutomationOverride` via CDP to set `navigator.webdriver = false` at the native Chrome level — undetectable by lie-detection systems like CreepJS.
+- `navigator.webdriver = false` via `Emulation.setAutomationOverride` (native, undetectable by CreepJS-style lie tests).
+- **`Runtime.enable` is left OFF by default.** A live `Runtime` domain is a detectable CDP signal (the patchright/rebrowser "runtime leak") — even when attached to your real Chrome. We only enable it when you opt into console/error capture (see below). `click`, `fill`, `eval`, etc. work without it.
 
 **Test results (connected to real Chrome):**
 
@@ -129,6 +130,17 @@ The only thing we do is call `Emulation.setAutomationOverride` via CDP to set `n
 
 When using `--launch` mode (standalone browser), a full suite of 32 stealth patches is applied for headless Chrome.
 
+### Tuning knobs (environment variables)
+
+| Variable | Default | Effect |
+|---|---|---|
+| `AGENT_BROWSER_CAPTURE_CONSOLE` | off | Enable `Runtime` domain so `console` / `errors` capture page output. Off keeps the stealthiest profile. |
+| `AGENT_BROWSER_TIMEZONE` | unset | `--launch` only. An IANA id (e.g. `Asia/Tokyo`) sets the timezone natively (Intl + Date follow, no JS lie) to match a proxy; `auto` derives one from the locale. |
+| `AGENT_BROWSER_BLOCK_WEBRTC` | auto | `--launch` only. Auto-forces WebRTC through the proxy when one is set (no real-IP leak). `1` hides the local IP without a proxy; `0` opts out. |
+| `AGENT_BROWSER_HIDE_CANVAS` | off | `--launch` only. Adds session-stable canvas/audio fingerprint noise. Off by default (noise is itself a "lie"). |
+| `AGENT_BROWSER_ADAPTIVE_REF` | on | When a saved `@ref` moves and the role/name re-query fails, relocate it by fingerprint similarity (high score + clear margin required, else it fails loudly). `0` disables. |
+| `AGENT_BROWSER_CLICK_MODE` | _(auto)_ | Click strategy. Default scrolls the target into view, dispatches a coordinate click, and falls back to a DOM `.click()` if a floating layer occludes the point. `dom` always uses `.click()` (best for autocomplete/menu items that close on blur); `coord` is strict coordinate-only (hard-fail on occlusion). |
+
 ## Differences from upstream
 
 Based on [agent-browser v0.27.0](https://github.com/vercel-labs/agent-browser). Changes:

cli/Cargo.lock

@@ -45,7 +45,7 @@ dependencies = [
 
 [[package]]
 name = "agent-browser-stealth"
-version = "0.27.0-fork.13"
+version = "0.27.0-fork.21"
 dependencies = [
  "aes-gcm",
  "async-trait",

cli/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "agent-browser-stealth"
-version = "0.27.0-fork.13"
+version = "0.27.0-fork.21"
 edition = "2021"
 description = "Fast browser automation CLI for AI agents"
 license = "Apache-2.0"
@@ -22,7 +22,7 @@ dirs = "5.0"
 include_dir = "0.7"
 base64 = "0.22"
 getrandom = "0.2"
-tokio = { version = "1", features = ["rt-multi-thread", "macros", "net", "io-util", "time", "sync", "signal", "process"] }
+tokio = { version = "1", features = ["rt-multi-thread", "macros", "net", "io-util", "io-std", "time", "sync", "signal", "process"] }
 tokio-tungstenite = { version = "0.24", features = ["rustls-tls-webpki-roots"] }
 futures-util = "0.3"
 url = "2"

cli/src/connect.rs

@@ -0,0 +1,602 @@
+//! `agent-browser connect` — zero-confirmation control of the user's real,
+//! logged-in Chrome via the `ab-connect` MV3 extension over Chrome **native
+//! messaging** (no localhost port, no token; Chrome authenticates the extension
+//! to this host by id).
+//!
+//! Two pieces live here:
+//! - `run_connect` — `--install` writes the native-messaging host manifest (and
+//!   a tiny launcher) so Chrome will spawn us; with no flag it reports status.
+//! - `run_nm_host` — the hidden `__nm-host` mode Chrome launches: it speaks the
+//!   native-messaging stdio framing (4-byte little-endian length + JSON).
+//!
+//! This step wires the transport end-to-end (Chrome ⇄ host). Bridging the host
+//! to the daemon's relay + CdpClient is layered on next.
+
+use std::io::Write;
+use std::path::PathBuf;
+
+/// Native-messaging host name; must match `HOST_NAME` in the extension and the
+/// manifest filename.
+pub const HOST_NAME: &str = "com.agent_browser.connect";
+
+/// Stable id of the `ab-connect` extension, pinned by the `key` in its
+/// manifest.json (and the signing key of the published `.crx`). Chrome only lets
+/// that extension talk to this host, and the force-install policy references it.
+pub const EXTENSION_ID: &str = "ciiljdlhdpfckdcfkphgmfalanpdejep";
+
+/// Update URL the force-install policy points at. MUST be the Chrome Web Store
+/// endpoint: Chrome 149 tags any **off-Web-Store** force-installed extension
+/// `[BLOCKED]` on an unmanaged browser (verified on macOS — chrome://policy shows
+/// `[BLOCKED]…` / "Error, Warning"). Self-hosting a `.crx` therefore does NOT
+/// work on consumer Chrome; the extension must be published to the Web Store, and
+/// then this policy force-installs it silently (Web Store extensions are allowed).
+pub const UPDATE_URL: &str = "https://clients2.google.com/service/update2/crx";
+
+/// Public Web Store listing — the guaranteed one-click "Add to Chrome" path,
+/// and the fallback when the force-install profile can't be approved headlessly.
+pub const STORE_URL: &str = "https://chromewebstore.google.com/detail/ciiljdlhdpfckdcfkphgmfalanpdejep";
+
+/// Stable identifiers for the generated Chrome configuration profile, so a
+/// re-install replaces (rather than duplicates) it in System Settings.
+const PROFILE_ID: &str = "work.pwtk.agent-browser.ab-connect";
+const PROFILE_UUID: &str = "A1B2C3D4-AB00-4CCE-9E10-AAAABBBBCCCC";
+const PROFILE_PAYLOAD_UUID: &str = "A1B2C3D4-AB01-4CCE-9E10-DDDDEEEEFFFF";
+
+/// `agent-browser extension <install|uninstall|status>` (local; no daemon).
+/// `args` is the cleaned argv including the leading "extension".
+pub fn run_connect(args: &[String], json: bool) {
+    let install = args.iter().any(|a| a == "--install" || a == "install");
+    let uninstall = args.iter().any(|a| a == "--uninstall" || a == "uninstall");
+
+    if uninstall {
+        let removed = remove_host_manifests();
+        let profile_removed = remove_force_install_profile();
+        if json {
+            report(json, true, &format!("removed {removed} native-host manifest(s)"));
+        } else {
+            println!("✓ removed {removed} native-host manifest(s).");
+            if profile_removed {
+                println!("✓ removed ~/.agent-browser/ab-connect.mobileconfig");
+            }
+            if cfg!(target_os = "macos") {
+                println!(
+                    "  To fully remove the extension, delete the \"agent-browser connect\" profile\n\
+                     in System Settings → Profiles (or run: profiles remove -identifier {PROFILE_ID})."
+                );
+            }
+        }
+        return;
+    }
+    if install {
+        let no_open = args.iter().any(|a| a == "--no-open");
+        match install_native_host() {
+            Ok(paths) => {
+                let profile = install_force_install_profile(no_open);
+                if json {
+                    println!(
+                        "{}",
+                        serde_json::to_string(&serde_json::json!({
+                            "success": true,
+                            "data": {
+                                "installed": paths,
+                                "extensionId": EXTENSION_ID,
+                                "profile": profile.as_ref().ok().map(|p| p.display().to_string()),
+                                "profileError": profile.as_ref().err(),
+                                "updateUrl": UPDATE_URL,
+                            }
+                        }))
+                        .unwrap_or_default()
+                    );
+                } else {
+                    println!("✓ native-messaging host installed:");
+                    for p in &paths {
+                        println!("  {p}");
+                    }
+                    match profile {
+                        Ok(path) => {
+                            println!("\n✓ Chrome force-install profile written:\n  {}", path.display());
+                            if cfg!(target_os = "macos") {
+                                println!(
+                                    "\nGet the extension into Chrome (one-time). Either:\n\
+                                     A) One click: open {STORE_URL}\n   and press \"Add to Chrome\".\n\
+                                     B) Silent: approve the profile, then restart Chrome —\n   \
+                                     System Settings → General → Device Management → double-click\n   \
+                                     \"agent-browser connect\" → Install. Chrome then force-installs +\n   \
+                                     auto-updates it (no token, no per-use confirmation).\n\
+                                     Both need the extension published to the Web Store; until then use\n   \
+                                     chrome://extensions → Developer mode → Load unpacked → extensions/ab-connect."
+                                );
+                            }
+                        }
+                        Err(e) => {
+                            println!("\n! could not write the force-install profile: {e}");
+                            println!(
+                                "  Fallback: load extensions/ab-connect via chrome://extensions →\n\
+                                 Developer mode → Load unpacked."
+                            );
+                        }
+                    }
+                }
+            }
+            Err(e) => report(json, false, &format!("install failed: {e}")),
+        }
+        return;
+    }
+
+    // Status.
+    let manifest = host_manifest_path_for_chrome();
+    let installed = manifest.as_ref().map(|p| p.exists()).unwrap_or(false);
+    if json {
+        println!(
+            "{}",
+            serde_json::to_string(&serde_json::json!({
+                "success": true,
+                "data": {
+                    "installed": installed,
+                    "manifest": manifest.as_ref().map(|p| p.display().to_string()),
+                    "extensionId": EXTENSION_ID,
+                }
+            }))
+            .unwrap_or_default()
+        );
+    } else if installed {
+        println!("✓ native-messaging host installed ({HOST_NAME}).");
+        println!("  Load the ab-connect extension and it connects automatically.");
+    } else {
+        println!("✗ not installed. Run: agent-browser connect --install");
+    }
+}
+
+/// Write the launcher script + native-messaging host manifest(s).
+fn install_native_host() -> Result<Vec<String>, String> {
+    let home = dirs::home_dir().ok_or("no home dir")?;
+    let ab_dir = home.join(".agent-browser");
+    std::fs::create_dir_all(&ab_dir).map_err(|e| e.to_string())?;
+
+    // Chrome execs the manifest `path` directly with the calling extension's
+    // origin as argv[1]; a launcher lets us run the binary in __nm-host mode
+    // regardless of how/where agent-browser is installed.
+    let exe = std::env::current_exe().map_err(|e| e.to_string())?;
+    let launcher = ab_dir.join("nm-host.sh");
+    let script = format!(
+        "#!/bin/sh\n# agent-browser native-messaging host launcher (auto-generated)\nexec \"{}\" __nm-host \"$@\"\n",
+        exe.display()
+    );
+    std::fs::write(&launcher, script).map_err(|e| e.to_string())?;
+    #[cfg(unix)]
+    {
+        use std::os::unix::fs::PermissionsExt;
+        let _ = std::fs::set_permissions(&launcher, std::fs::Permissions::from_mode(0o755));
+    }
+
+    let manifest = serde_json::json!({
+        "name": HOST_NAME,
+        "description": "agent-browser connect — native messaging host",
+        "path": launcher.display().to_string(),
+        "type": "stdio",
+        "allowed_origins": [format!("chrome-extension://{EXTENSION_ID}/")],
+    });
+    let body = serde_json::to_string_pretty(&manifest).map_err(|e| e.to_string())?;
+
+    let mut written = Vec::new();
+    for dir in native_messaging_dirs() {
+        if let Some(parent) = dir.parent() {
+            if !parent.exists() {
+                continue; // that browser isn't installed
+            }
+        }
+        std::fs::create_dir_all(&dir).map_err(|e| e.to_string())?;
+        let path = dir.join(format!("{HOST_NAME}.json"));
+        std::fs::write(&path, &body).map_err(|e| e.to_string())?;
+        written.push(path.display().to_string());
+    }
+    if written.is_empty() {
+        return Err("no Chrome/Chromium NativeMessagingHosts directory found".into());
+    }
+    Ok(written)
+}
+
+/// Write a Chrome configuration profile that force-installs `ab-connect` from
+/// [`UPDATE_URL`], and (unless `no_open`) `open` it so the user approves it once
+/// in System Settings. Returns the profile path. macOS only — elsewhere it
+/// returns an error and the caller prints the manual fallback.
+fn install_force_install_profile(no_open: bool) -> Result<PathBuf, String> {
+    if !cfg!(target_os = "macos") {
+        return Err("force-install profile is macOS-only; on Linux set Chrome's \
+                    ExtensionInstallForcelist policy JSON, or Load unpacked from chrome://extensions"
+            .into());
+    }
+    let home = dirs::home_dir().ok_or("no home dir")?;
+    let ab_dir = home.join(".agent-browser");
+    std::fs::create_dir_all(&ab_dir).map_err(|e| e.to_string())?;
+    let path = ab_dir.join("ab-connect.mobileconfig");
+    std::fs::write(&path, force_install_mobileconfig()).map_err(|e| e.to_string())?;
+    if !no_open {
+        // `open` queues the profile in System Settings for one-time approval.
+        let _ = std::process::Command::new("open").arg(&path).status();
+    }
+    Ok(path)
+}
+
+/// The `.mobileconfig` payload: a user-scope Chrome policy that force-installs
+/// the extension by id from our hosted update manifest. User scope installs
+/// without admin — just a one-time approval click.
+fn force_install_mobileconfig() -> String {
+    let forcelist = format!("{EXTENSION_ID};{UPDATE_URL}");
+    format!(
+        r#"<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>PayloadContent</key>
+  <array>
+    <dict>
+      <key>PayloadType</key><string>com.google.Chrome</string>
+      <key>PayloadVersion</key><integer>1</integer>
+      <key>PayloadIdentifier</key><string>{PROFILE_ID}.chrome</string>
+      <key>PayloadUUID</key><string>{PROFILE_PAYLOAD_UUID}</string>
+      <key>PayloadEnabled</key><true/>
+      <key>PayloadDisplayName</key><string>agent-browser connect (Chrome)</string>
+      <key>ExtensionInstallForcelist</key>
+      <array>
+        <string>{forcelist}</string>
+      </array>
+    </dict>
+  </array>
+  <key>PayloadType</key><string>Configuration</string>
+  <key>PayloadVersion</key><integer>1</integer>
+  <key>PayloadIdentifier</key><string>{PROFILE_ID}</string>
+  <key>PayloadUUID</key><string>{PROFILE_UUID}</string>
+  <key>PayloadDisplayName</key><string>agent-browser connect</string>
+  <key>PayloadDescription</key><string>Force-installs the agent-browser connect extension so agent-browser can drive your logged-in Chrome. No token, no per-use confirmation.</string>
+  <key>PayloadOrganization</key><string>agent-browser-stealth</string>
+  <key>PayloadScope</key><string>User</string>
+  <key>PayloadRemovalDisallowed</key><false/>
+</dict>
+</plist>
+"#
+    )
+}
+
+/// Remove the generated `.mobileconfig` file (the profile itself is removed by
+/// the user from System Settings, or via `profiles remove`).
+fn remove_force_install_profile() -> bool {
+    dirs::home_dir()
+        .map(|h| h.join(".agent-browser").join("ab-connect.mobileconfig"))
+        .filter(|p| p.exists())
+        .map(|p| std::fs::remove_file(&p).is_ok())
+        .unwrap_or(false)
+}
+
+fn remove_host_manifests() -> usize {
+    let mut n = 0;
+    for dir in native_messaging_dirs() {
+        let path = dir.join(format!("{HOST_NAME}.json"));
+        if path.exists() && std::fs::remove_file(&path).is_ok() {
+            n += 1;
+        }
+    }
+    n
+}
+
+/// Per-OS NativeMessagingHosts directories for Chrome + Chromium-family browsers.
+fn native_messaging_dirs() -> Vec<PathBuf> {
+    let mut dirs_out = Vec::new();
+    #[cfg(target_os = "macos")]
+    {
+        if let Some(app_support) = dirs::config_dir() {
+            for sub in [
+                "Google/Chrome",
+                "Google/Chrome Beta",
+                "Google/Chrome Canary",
+                "Chromium",
+                "Microsoft Edge",
+                "BraveSoftware/Brave-Browser",
+            ] {
+                dirs_out.push(app_support.join(sub).join("NativeMessagingHosts"));
+            }
+        }
+    }
+    #[cfg(all(unix, not(target_os = "macos")))]
+    {
+        if let Some(config) = dirs::config_dir() {
+            for sub in ["google-chrome", "chromium", "microsoft-edge", "BraveSoftware/Brave-Browser"] {
+                dirs_out.push(config.join(sub).join("NativeMessagingHosts"));
+            }
+        }
+    }
+    dirs_out
+}
+
+fn host_manifest_path_for_chrome() -> Option<PathBuf> {
+    native_messaging_dirs()
+        .into_iter()
+        .map(|d| d.join(format!("{HOST_NAME}.json")))
+        .find(|p| p.exists())
+        .or_else(|| {
+            native_messaging_dirs()
+                .into_iter()
+                .next()
+                .map(|d| d.join(format!("{HOST_NAME}.json")))
+        })
+}
+
+fn report(json: bool, ok: bool, msg: &str) {
+    if json {
+        println!(
+            "{}",
+            serde_json::to_string(&serde_json::json!({ "success": ok, "error": if ok { serde_json::Value::Null } else { serde_json::json!(msg) }, "message": msg }))
+                .unwrap_or_default()
+        );
+    } else if ok {
+        println!("✓ {msg}");
+    } else {
+        eprintln!("✗ {msg}");
+    }
+    if !ok {
+        std::process::exit(1);
+    }
+}
+
+// ---- native messaging host (`__nm-host`) ----------------------------------
+
+fn nm_log(line: &str) {
+    let path = dirs::home_dir()
+        .map(|h| h.join(".agent-browser").join("nm-host.log"))
+        .unwrap_or_else(|| PathBuf::from("/tmp/ab-nm-host.log"));
+    if let Some(p) = path.parent() {
+        let _ = std::fs::create_dir_all(p);
+    }
+    if let Ok(mut f) = std::fs::OpenOptions::new().create(true).append(true).open(&path) {
+        let _ = writeln!(f, "{line}");
+    }
+}
+
+fn random_guid() -> String {
+    let mut b = [0u8; 16];
+    let _ = getrandom::getrandom(&mut b);
+    b.iter().map(|x| format!("{x:02x}")).collect()
+}
+
+/// Where the daemon/CLI reads the relay's CDP WebSocket URL (perms 600).
+fn relay_url_path() -> PathBuf {
+    dirs::home_dir()
+        .map(|h| h.join(".agent-browser").join("relay-cdp-url"))
+        .unwrap_or_else(|| PathBuf::from("/tmp/ab-relay-cdp-url"))
+}
+
+/// The live relay CDP WebSocket URL, if the native-messaging host is running
+/// (it writes the file on connect and removes it on exit). Used by
+/// `agent-browser extension connect` to attach without the user copying a URL.
+pub fn relay_url() -> Option<String> {
+    let s = std::fs::read_to_string(relay_url_path()).ok()?;
+    let s = s.trim().to_string();
+    if s.starts_with("ws://") {
+        Some(s)
+    } else {
+        None
+    }
+}
+
+/// Hidden `__nm-host` mode: launched by Chrome for the ab-connect extension.
+///
+/// Bridges the extension (native-messaging stdio, envelope protocol) to a local
+/// **CDP WebSocket endpoint** that agent-browser connects to like any Chrome.
+/// `relay::RelayState` translates envelope ⇄ raw CDP and emulates browser-level
+/// Target discovery. The ws URL carries an unguessable guid (written to a 600
+/// file) so only this user's agent-browser — not arbitrary local processes —
+/// can drive the browser. No token, no user interaction.
+pub fn run_nm_host() {
+    let rt = match tokio::runtime::Builder::new_multi_thread().enable_all().build() {
+        Ok(rt) => rt,
+        Err(e) => {
+            nm_log(&format!("[nm-host] runtime build failed: {e}"));
+            return;
+        }
+    };
+    rt.block_on(nm_host_main());
+}
+
+async fn nm_host_main() {
+    use crate::native::relay::{RelayOut, RelayState};
+    use std::collections::HashMap;
+    use std::sync::atomic::{AtomicU64, Ordering};
+    use std::sync::Arc;
+    use tokio::io::{AsyncReadExt, AsyncWriteExt};
+    use tokio::sync::{mpsc, Mutex};
+
+    /// client_id -> unbounded sender feeding that client's ws writer.
+    type ClientMap = Arc<Mutex<HashMap<u64, mpsc::UnboundedSender<String>>>>;
+
+    nm_log(&format!(
+        "[nm-host] start argv={:?}",
+        std::env::args().skip(1).collect::<Vec<_>>()
+    ));
+
+    let listener = match tokio::net::TcpListener::bind("127.0.0.1:0").await {
+        Ok(l) => l,
+        Err(e) => {
+            nm_log(&format!("[nm-host] bind failed: {e}"));
+            return;
+        }
+    };
+    let port = listener.local_addr().map(|a| a.port()).unwrap_or(0);
+    let guid = random_guid();
+    let url = format!("ws://127.0.0.1:{port}/{guid}");
+    let url_path = relay_url_path();
+    if let Some(p) = url_path.parent() {
+        let _ = std::fs::create_dir_all(p);
+    }
+    if std::fs::write(&url_path, &url).is_ok() {
+        #[cfg(unix)]
+        {
+            use std::os::unix::fs::PermissionsExt;
+            let _ = std::fs::set_permissions(&url_path, std::fs::Permissions::from_mode(0o600));
+        }
+    }
+    nm_log(&format!("[nm-host] cdp endpoint {url}"));
+
+    let state = Arc::new(Mutex::new(RelayState::new()));
+    let clients: ClientMap = Arc::new(Mutex::new(HashMap::new()));
+    let next_client_id = Arc::new(AtomicU64::new(1));
+    let (to_ext, mut to_ext_rx) = mpsc::channel::<Vec<u8>>(4096);
+
+    // Single writer to Chrome (extension) over stdout, native-messaging framed.
+    tokio::spawn(async move {
+        let mut out = tokio::io::stdout();
+        while let Some(frame) = to_ext_rx.recv().await {
+            let len = (frame.len() as u32).to_ne_bytes();
+            if out.write_all(&len).await.is_err() || out.write_all(&frame).await.is_err() {
+                break;
+            }
+            let _ = out.flush().await;
+        }
+    });
+
+    // Accept agent-browser CDP clients on the guid-scoped ws endpoint.
+    {
+        let state = state.clone();
+        let clients = clients.clone();
+        let next_client_id = next_client_id.clone();
+        let to_ext = to_ext.clone();
+        let guid = guid.clone();
+        tokio::spawn(async move {
+            loop {
+                let (stream, _) = match listener.accept().await {
+                    Ok(x) => x,
+                    Err(_) => break,
+                };
+                let st = state.clone();
+                let client_id = next_client_id.fetch_add(1, Ordering::Relaxed);
+                let (ctx, crx) = mpsc::unbounded_channel::<String>();
+                clients.lock().await.insert(client_id, ctx);
+                let tx = to_ext.clone();
+                let g = guid.clone();
+                let cls = clients.clone();
+                tokio::spawn(async move {
+                    handle_cdp_client(stream, g, st, client_id, crx, tx, cls).await;
+                });
+            }
+        });
+    }
+
+    // Extension → host frames.
+    let mut stdin = tokio::io::stdin();
+    loop {
+        let mut len_buf = [0u8; 4];
+        if stdin.read_exact(&mut len_buf).await.is_err() {
+            break;
+        }
+        let len = u32::from_ne_bytes(len_buf) as usize;
+        let mut buf = vec![0u8; len];
+        if stdin.read_exact(&mut buf).await.is_err() {
+            break;
+        }
+        let v: serde_json::Value = match serde_json::from_slice(&buf) {
+            Ok(v) => v,
+            Err(_) => continue,
+        };
+        let outs = {
+            let mut s = state.lock().await;
+            s.handle_ext_message(&v, "")
+        };
+        for o in outs {
+            match o {
+                RelayOut::ToClient { to, msg } => {
+                    let text = msg.to_string();
+                    let cls = clients.lock().await;
+                    match to {
+                        // Command reply → only the client that issued it.
+                        Some(cid) => {
+                            if let Some(tx) = cls.get(&cid) {
+                                let _ = tx.send(text);
+                            }
+                        }
+                        // CDP event → fan out to every connected client.
+                        None => {
+                            for tx in cls.values() {
+                                let _ = tx.send(text.clone());
+                            }
+                        }
+                    }
+                }
+                RelayOut::ToExt(m) => {
+                    let _ = to_ext.send(m.to_string().into_bytes()).await;
+                }
+            }
+        }
+    }
+    nm_log("[nm-host] stdin EOF — Chrome closed the port");
+    let _ = std::fs::remove_file(relay_url_path());
+}
+
+#[allow(clippy::too_many_arguments)]
+async fn handle_cdp_client(
+    stream: tokio::net::TcpStream,
+    guid: String,
+    state: std::sync::Arc<tokio::sync::Mutex<crate::native::relay::RelayState>>,
+    client_id: u64,
+    mut from_relay: tokio::sync::mpsc::UnboundedReceiver<String>,
+    to_ext: tokio::sync::mpsc::Sender<Vec<u8>>,
+    clients: std::sync::Arc<
+        tokio::sync::Mutex<std::collections::HashMap<u64, tokio::sync::mpsc::UnboundedSender<String>>>,
+    >,
+) {
+    use crate::native::relay::ClientRoute;
+    use futures_util::{SinkExt, StreamExt};
+    use tokio_tungstenite::tungstenite::Message;
+
+    let want_path = format!("/{guid}");
+    let cb = |req: &tokio_tungstenite::tungstenite::handshake::server::Request,
+              resp: tokio_tungstenite::tungstenite::handshake::server::Response| {
+        if req.uri().path() == want_path {
+            Ok(resp)
+        } else {
+            let mut reject = tokio_tungstenite::tungstenite::handshake::server::ErrorResponse::new(
+                Some("forbidden".to_string()),
+            );
+            *reject.status_mut() = tokio_tungstenite::tungstenite::http::StatusCode::FORBIDDEN;
+            Err(reject)
+        }
+    };
+    let ws = match tokio_tungstenite::accept_hdr_async(stream, cb).await {
+        Ok(ws) => ws,
+        Err(_) => return,
+    };
+    nm_log("[nm-host] cdp client connected");
+    // Ask the extension to (re)attach + announce every tab so this client
+    // discovers the user's existing tabs instead of racing an empty list.
+    let _ = to_ext.send(br#"{"method":"attachAll"}"#.to_vec()).await;
+    let (mut tx, mut rx) = ws.split();
+    loop {
+        tokio::select! {
+            relayed = from_relay.recv() => match relayed {
+                Some(text) => { if tx.send(Message::Text(text)).await.is_err() { break } }
+                None => break,
+            },
+            incoming = rx.next() => match incoming {
+                Some(Ok(Message::Text(text))) => {
+                    let v: serde_json::Value = match serde_json::from_str(&text) {
+                        Ok(v) => v,
+                        Err(_) => continue,
+                    };
+                    let route = { state.lock().await.route_client_command(client_id, &v) };
+                    match route {
+                        ClientRoute::Local(reply) => {
+                            if tx.send(Message::Text(reply.to_string())).await.is_err() { break }
+                        }
+                        ClientRoute::Forward(env) => {
+                            let _ = to_ext.send(env.to_string().into_bytes()).await;
+                        }
+                    }
+                }
+                Some(Ok(Message::Close(_))) | None => break,
+                _ => {}
+            },
+        }
+    }
+    // Unregister and forget this client's in-flight commands.
+    clients.lock().await.remove(&client_id);
+    state.lock().await.drop_client(client_id);
+    nm_log("[nm-host] cdp client disconnected");
+}

cli/src/findurl.rs

@@ -0,0 +1,244 @@
+//! `find-url` — search the user's local Chrome/Edge **bookmarks** for pages they
+//! saved, by keyword. Borrowed from web-access's `find-url.mjs`; lets an agent
+//! locate an internal system or a previously-saved page that public search
+//! can't reach, without opening a browser.
+//!
+//! v1 covers bookmarks only (a zero-dependency JSON read). Visited-history lives
+//! in a locked SQLite DB and would need a SQLite dependency — not included yet.
+
+use std::path::PathBuf;
+
+use serde_json::Value;
+
+use crate::color;
+
+struct Hit {
+    name: String,
+    url: String,
+    folder: String,
+    date_added: i64,
+}
+
+/// Entry point for the `find-url` subcommand. `args` is the full cleaned argv
+/// (including the leading "find-url").
+pub fn run_find_url(args: &[String], json: bool) {
+    // Parse flags out of args[1..]; everything else is a keyword.
+    let mut browser = "chrome".to_string();
+    let mut profile = "Default".to_string();
+    let mut limit: usize = 20;
+    let mut keywords: Vec<String> = Vec::new();
+
+    let mut i = 1;
+    while i < args.len() {
+        match args[i].as_str() {
+            "--browser" => {
+                if let Some(v) = args.get(i + 1) {
+                    browser = v.to_lowercase();
+                    i += 1;
+                }
+            }
+            "--profile" => {
+                if let Some(v) = args.get(i + 1) {
+                    profile = v.clone();
+                    i += 1;
+                }
+            }
+            "--limit" => {
+                if let Some(v) = args.get(i + 1).and_then(|s| s.parse::<usize>().ok()) {
+                    limit = v;
+                    i += 1;
+                }
+            }
+            "--json" => {}
+            other if other.starts_with("--") => {}
+            other => keywords.push(other.to_lowercase()),
+        }
+        i += 1;
+    }
+
+    let path = match bookmarks_path(&browser, &profile) {
+        Some(p) => p,
+        None => {
+            emit_error(
+                json,
+                &format!("Could not locate {browser} bookmarks for profile '{profile}'"),
+            );
+            return;
+        }
+    };
+
+    let raw = match std::fs::read_to_string(&path) {
+        Ok(r) => r,
+        Err(e) => {
+            emit_error(json, &format!("Failed to read {}: {e}", path.display()));
+            return;
+        }
+    };
+    let root: Value = match serde_json::from_str(&raw) {
+        Ok(v) => v,
+        Err(e) => {
+            emit_error(json, &format!("Failed to parse bookmarks JSON: {e}"));
+            return;
+        }
+    };
+
+    let mut hits: Vec<Hit> = Vec::new();
+    if let Some(roots) = root.get("roots").and_then(|r| r.as_object()) {
+        for node in roots.values() {
+            walk(node, "", &keywords, &mut hits);
+        }
+    }
+
+    // Most-recently-added first (date_added is microseconds since 1601).
+    hits.sort_by(|a, b| b.date_added.cmp(&a.date_added));
+    hits.truncate(limit);
+
+    if json {
+        let arr: Vec<Value> = hits
+            .iter()
+            .map(|h| {
+                serde_json::json!({
+                    "name": h.name,
+                    "url": h.url,
+                    "folder": h.folder,
+                })
+            })
+            .collect();
+        println!(
+            "{}",
+            serde_json::to_string(&serde_json::json!({
+                "success": true,
+                "data": { "results": arr, "count": hits.len() },
+            }))
+            .unwrap_or_default()
+        );
+        return;
+    }
+
+    if hits.is_empty() {
+        let kw = if keywords.is_empty() {
+            String::new()
+        } else {
+            format!(" matching {:?}", keywords.join(" "))
+        };
+        println!("No {browser} bookmarks found{kw}.");
+        return;
+    }
+    for h in &hits {
+        if h.folder.is_empty() {
+            println!("{}\n  {}", h.name, h.url);
+        } else {
+            println!("{}  ({})\n  {}", h.name, h.folder, h.url);
+        }
+    }
+}
+
+/// Recursively walk a bookmark node, collecting URL entries that match every
+/// keyword (in name or url). Empty keyword list matches everything.
+fn walk(node: &Value, folder: &str, keywords: &[String], out: &mut Vec<Hit>) {
+    match node.get("type").and_then(|t| t.as_str()) {
+        Some("url") => {
+            let name = node.get("name").and_then(|v| v.as_str()).unwrap_or("");
+            let url = node.get("url").and_then(|v| v.as_str()).unwrap_or("");
+            // Skip non-navigable bookmarks: javascript: bookmarklets and data:
+            // URIs aren't pages you can visit, and their bodies can be huge.
+            if url.is_empty()
+                || url.starts_with("javascript:")
+                || url.starts_with("data:")
+            {
+                return;
+            }
+            let hay = format!("{} {}", name.to_lowercase(), url.to_lowercase());
+            if keywords.iter().all(|k| hay.contains(k.as_str())) {
+                let date_added = node
+                    .get("date_added")
+                    .and_then(|v| v.as_str())
+                    .and_then(|s| s.parse::<i64>().ok())
+                    .unwrap_or(0);
+                out.push(Hit {
+                    name: name.to_string(),
+                    url: url.to_string(),
+                    folder: folder.to_string(),
+                    date_added,
+                });
+            }
+        }
+        Some("folder") => {
+            let fname = node.get("name").and_then(|v| v.as_str()).unwrap_or("");
+            let child_folder = if folder.is_empty() {
+                fname.to_string()
+            } else {
+                format!("{folder}/{fname}")
+            };
+            if let Some(children) = node.get("children").and_then(|c| c.as_array()) {
+                for child in children {
+                    walk(child, &child_folder, keywords, out);
+                }
+            }
+        }
+        _ => {}
+    }
+}
+
+/// Resolve the Bookmarks file path for a browser + profile across platforms.
+fn bookmarks_path(browser: &str, profile: &str) -> Option<PathBuf> {
+    let base = browser_user_data_dir(browser)?;
+    let path = base.join(profile).join("Bookmarks");
+    if path.exists() {
+        Some(path)
+    } else {
+        None
+    }
+}
+
+/// The "User Data" directory that holds per-profile folders, per OS/browser.
+fn browser_user_data_dir(browser: &str) -> Option<PathBuf> {
+    let is_edge = browser == "edge" || browser == "msedge";
+
+    #[cfg(target_os = "macos")]
+    {
+        let app_support = dirs::config_dir()?; // ~/Library/Application Support
+        let sub = if is_edge {
+            "Microsoft Edge"
+        } else {
+            "Google/Chrome"
+        };
+        Some(app_support.join(sub))
+    }
+    #[cfg(target_os = "windows")]
+    {
+        let local = dirs::data_local_dir()?; // %LOCALAPPDATA%
+        let sub = if is_edge {
+            "Microsoft/Edge/User Data"
+        } else {
+            "Google/Chrome/User Data"
+        };
+        Some(local.join(sub))
+    }
+    #[cfg(all(unix, not(target_os = "macos")))]
+    {
+        let config = dirs::config_dir()?; // ~/.config
+        let sub = if is_edge {
+            "microsoft-edge"
+        } else {
+            "google-chrome"
+        };
+        Some(config.join(sub))
+    }
+}
+
+fn emit_error(json: bool, msg: &str) {
+    if json {
+        println!(
+            "{}",
+            serde_json::to_string(&serde_json::json!({
+                "success": false,
+                "error": msg,
+            }))
+            .unwrap_or_default()
+        );
+    } else {
+        eprintln!("{} {msg}", color::error_indicator());
+    }
+    std::process::exit(1);
+}

cli/src/main.rs

@@ -2,7 +2,9 @@ mod chat;
 mod color;
 mod commands;
 mod connection;
+mod connect;
 mod doctor;
+mod findurl;
 mod flags;
 mod install;
 mod native;
@@ -502,6 +504,14 @@ fn main() {
         env::set_var("MSYS2_ARG_CONV_EXCL", "*");
     }
 
+    // Native-messaging host mode: Chrome launches `agent-browser __nm-host
+    // <extension-origin> [...]` for the ab-connect extension. Must run before
+    // ANY stdout write — stdout is the Chrome native-messaging channel.
+    if env::args().nth(1).as_deref() == Some("__nm-host") {
+        connect::run_nm_host();
+        return;
+    }
+
     // Native daemon mode: when AGENT_BROWSER_DAEMON is set, run as the daemon process
     if env::var("AGENT_BROWSER_DAEMON").is_ok() {
         // Ignore SIGPIPE so the daemon isn't killed when the parent drops
@@ -529,7 +539,7 @@ fn main() {
 
     let args: Vec<String> = env::args().skip(1).collect();
     let mut flags = parse_flags(&args);
-    let clean = clean_args(&args);
+    let mut clean = clean_args(&args);
 
     // Loudly warn when launching a fresh browser with no profile: it gets a
     // temporary EMPTY profile (no cookies / no login). For logged-in sites the
@@ -631,6 +641,40 @@ fn main() {
         return;
     }
 
+    // Handle find-url (doesn't need daemon): search local bookmarks
+    if matches!(
+        clean.first().map(|s| s.as_str()),
+        Some("find-url") | Some("findurl")
+    ) {
+        findurl::run_find_url(&clean, flags.json);
+        return;
+    }
+
+    // Handle extension: native-messaging host install/status, and
+    // `extension connect` which attaches to the live relay (auto-discovers the
+    // CDP url the host wrote) by rewriting into the normal `connect <url>` flow.
+    // (`connect <port>` stays the plain CDP-attach command.)
+    if clean.first().map(|s| s.as_str()) == Some("extension") {
+        if clean.get(1).map(|s| s.as_str()) == Some("connect") {
+            match connect::relay_url() {
+                Some(url) => {
+                    clean = vec!["connect".to_string(), url];
+                    // fall through to the normal connect handling below
+                }
+                None => {
+                    eprintln!(
+                        "{} extension not connected. Run `agent-browser extension install`, load the\n  ab-connect extension in Chrome (chrome://extensions → Developer mode →\n  Load unpacked → extensions/ab-connect), then retry.",
+                        color::error_indicator()
+                    );
+                    exit(1);
+                }
+            }
+        } else {
+            connect::run_connect(&clean, flags.json);
+            return;
+        }
+    }
+
     // Handle session separately (doesn't need daemon)
     if clean.first().map(|s| s.as_str()) == Some("session") {
         run_session(&clean, &flags.session, flags.json);

cli/src/native/actions.rs

@@ -3690,13 +3690,38 @@ async fn handle_console(cmd: &Value, state: &mut DaemonState) -> Result<Value, S
         state.event_tracker.clear_console();
         Ok(json!({ "cleared": true }))
     } else {
-        let result = state.event_tracker.get_console_json();
+        let mut result = state.event_tracker.get_console_json();
+        if !console_capture_active(state) {
+            if let Some(obj) = result.as_object_mut() {
+                obj.insert("hint".to_string(), json!(CONSOLE_DISABLED_HINT));
+            }
+        }
         Ok(result)
     }
 }
 
+/// Whether the active browser session has the CDP `Runtime` domain enabled
+/// (required to receive console/error events). OFF by default for stealth.
+fn console_capture_active(state: &DaemonState) -> bool {
+    state
+        .browser
+        .as_ref()
+        .map(|b| b.capture_console)
+        .unwrap_or(false)
+}
+
+const CONSOLE_DISABLED_HINT: &str =
+    "console/error capture is disabled for stealth (Runtime.enable is a detectable CDP \
+     signal). Restart the session with AGENT_BROWSER_CAPTURE_CONSOLE=1 to capture page output.";
+
 async fn handle_errors(state: &DaemonState) -> Result<Value, String> {
-    Ok(state.event_tracker.get_errors_json())
+    let mut result = state.event_tracker.get_errors_json();
+    if !console_capture_active(state) {
+        if let Some(obj) = result.as_object_mut() {
+            obj.insert("hint".to_string(), json!(CONSOLE_DISABLED_HINT));
+        }
+    }
+    Ok(result)
 }
 
 async fn handle_state_save(cmd: &Value, state: &DaemonState) -> Result<Value, String> {

cli/src/native/adaptive.rs

@@ -0,0 +1,364 @@
+//! Adaptive @ref relocation.
+//!
+//! When a saved `@ref`'s DOM node is gone (stale `backendNodeId`) and the
+//! role/name/nth re-query also fails, we score the current page's candidate
+//! elements against the ref's stored [`ElementFingerprint`] and relocate to the
+//! best match — but ONLY when confident: the best candidate must clear a high
+//! absolute threshold AND beat the runner-up by a clear margin. This matches the
+//! project's "fail loudly rather than mis-click" posture (see the identity and
+//! occlusion guards in `element.rs`).
+//!
+//! Everything in this module is pure and browser-free so the scoring can be
+//! unit-tested directly.
+
+use std::collections::BTreeMap;
+
+/// Minimum absolute similarity (0..1) for a relocation candidate to be accepted.
+pub const ADAPTIVE_THRESHOLD: f64 = 0.70;
+/// Minimum gap between the best and second-best candidate to avoid ambiguity.
+pub const ADAPTIVE_MARGIN: f64 = 0.15;
+
+/// A structural/semantic fingerprint of an element, captured at snapshot time so
+/// a moved element can be re-identified after the page mutates.
+///
+/// Populated purely from the accessibility tree we already walk (`TreeNode`), so
+/// capturing it costs no extra CDP round-trips — `TreeNode` has no DOM tag or
+/// attributes (those would need an N×`DOM.describeNode` storm per snapshot), so
+/// `tag` holds the AX **role** and `attrs` holds discriminating AX properties
+/// (value/url/level/checked), not DOM `id`/`class`.
+#[derive(Debug, Clone, Default, PartialEq)]
+pub struct ElementFingerprint {
+    /// AX role, e.g. "button" (used where a DOM tag would otherwise go).
+    pub tag: String,
+    /// Accessible name / visible text — the dominant identity signal.
+    pub text: String,
+    /// Discriminating AX properties: value, url, level, checked. Keyed by name.
+    pub attrs: BTreeMap<String, String>,
+    /// Ancestor role signatures from nearest to farthest, e.g. "form" / "list".
+    pub ancestors: Vec<String>,
+    /// Parent role.
+    pub parent_tag: String,
+    /// Parent accessible name / text.
+    pub parent_text: String,
+    /// Index among same-role siblings.
+    pub sibling_index: u32,
+    /// Count of same-role siblings.
+    pub sibling_count: u32,
+}
+
+/// Component weights. They sum to 1.0 so the total score lands in 0..1.
+/// Tuned for AX-derived fingerprints: the accessible name dominates, with role
+/// and tree structure carrying disambiguation when the name has changed (which
+/// is exactly when the exact role+name+nth fallback failed and we got here).
+const W_TAG: f64 = 0.20;
+const W_TEXT: f64 = 0.40;
+const W_ATTRS: f64 = 0.10;
+const W_ANCESTORS: f64 = 0.20;
+const W_PARENT_SIBLING: f64 = 0.10;
+
+/// Per-attribute importance for the attribute-overlap score. Strong identity
+/// signals (a link's url) outweigh weak ones (heading level).
+fn attr_weight(name: &str) -> f64 {
+    match name {
+        "url" | "value" => 3.0,
+        "checked" => 2.0,
+        _ => 1.0,
+    }
+}
+
+/// Levenshtein-based string similarity in 0..1 (1.0 = identical). Two empty
+/// strings are treated as a perfect match (consistent absence of text).
+pub fn string_similarity(a: &str, b: &str) -> f64 {
+    if a == b {
+        return 1.0;
+    }
+    let a: Vec<char> = a.chars().collect();
+    let b: Vec<char> = b.chars().collect();
+    let max_len = a.len().max(b.len());
+    if max_len == 0 {
+        return 1.0;
+    }
+    let dist = levenshtein(&a, &b);
+    1.0 - (dist as f64 / max_len as f64)
+}
+
+fn levenshtein(a: &[char], b: &[char]) -> usize {
+    if a.is_empty() {
+        return b.len();
+    }
+    if b.is_empty() {
+        return a.len();
+    }
+    let mut prev: Vec<usize> = (0..=b.len()).collect();
+    let mut cur = vec![0usize; b.len() + 1];
+    for (i, &ca) in a.iter().enumerate() {
+        cur[0] = i + 1;
+        for (j, &cb) in b.iter().enumerate() {
+            let cost = if ca == cb { 0 } else { 1 };
+            cur[j + 1] = (prev[j + 1] + 1).min(cur[j] + 1).min(prev[j] + cost);
+        }
+        std::mem::swap(&mut prev, &mut cur);
+    }
+    prev[b.len()]
+}
+
+/// Jaccard similarity over whitespace-separated tokens (used for `class`).
+fn token_jaccard(a: &str, b: &str) -> f64 {
+    let sa: std::collections::BTreeSet<&str> = a.split_whitespace().collect();
+    let sb: std::collections::BTreeSet<&str> = b.split_whitespace().collect();
+    if sa.is_empty() && sb.is_empty() {
+        return 1.0;
+    }
+    let inter = sa.intersection(&sb).count() as f64;
+    let union = sa.union(&sb).count() as f64;
+    if union == 0.0 {
+        1.0
+    } else {
+        inter / union
+    }
+}
+
+/// Length-ratio of the longest common subsequence over two ancestor sequences.
+fn lcs_ratio(a: &[String], b: &[String]) -> f64 {
+    if a.is_empty() && b.is_empty() {
+        return 1.0;
+    }
+    if a.is_empty() || b.is_empty() {
+        return 0.0;
+    }
+    let mut dp = vec![vec![0usize; b.len() + 1]; a.len() + 1];
+    for i in 0..a.len() {
+        for j in 0..b.len() {
+            dp[i + 1][j + 1] = if a[i] == b[j] {
+                dp[i][j] + 1
+            } else {
+                dp[i][j + 1].max(dp[i + 1][j])
+            };
+        }
+    }
+    let lcs = dp[a.len()][b.len()] as f64;
+    (2.0 * lcs) / (a.len() + b.len()) as f64
+}
+
+fn attr_score(base: &BTreeMap<String, String>, cand: &BTreeMap<String, String>) -> f64 {
+    let mut names: std::collections::BTreeSet<&str> = std::collections::BTreeSet::new();
+    names.extend(base.keys().map(|s| s.as_str()));
+    names.extend(cand.keys().map(|s| s.as_str()));
+    if names.is_empty() {
+        return 1.0; // no attributes on either side — neutral
+    }
+    let mut total = 0.0;
+    let mut got = 0.0;
+    for name in names {
+        let w = attr_weight(name);
+        total += w;
+        // present on only one side → no credit
+        if let (Some(a), Some(b)) = (base.get(name), cand.get(name)) {
+            if name == "class" {
+                got += w * token_jaccard(a, b);
+            } else if a == b {
+                got += w;
+            }
+        }
+    }
+    if total == 0.0 {
+        1.0
+    } else {
+        got / total
+    }
+}
+
+fn parent_sibling_score(base: &ElementFingerprint, cand: &ElementFingerprint) -> f64 {
+    // Split the 0.10 budget: parent tag 0.4, parent text 0.3, sibling pos 0.3.
+    let parent_tag = if base.parent_tag == cand.parent_tag {
+        1.0
+    } else {
+        0.0
+    };
+    let parent_text = string_similarity(&base.parent_text, &cand.parent_text);
+    let span = base.sibling_count.max(1) as f64;
+    let delta = (base.sibling_index as i64 - cand.sibling_index as i64).unsigned_abs() as f64;
+    let sibling = 1.0 - (delta / span).min(1.0);
+    0.4 * parent_tag + 0.3 * parent_text + 0.3 * sibling
+}
+
+/// Similarity score in 0..1 between a stored baseline and a candidate element.
+pub fn score(base: &ElementFingerprint, cand: &ElementFingerprint) -> f64 {
+    let tag = if base.tag == cand.tag { 1.0 } else { 0.0 };
+    let text = string_similarity(&base.text, &cand.text);
+    let attrs = attr_score(&base.attrs, &cand.attrs);
+    let ancestors = lcs_ratio(&base.ancestors, &cand.ancestors);
+    let parent_sibling = parent_sibling_score(base, cand);
+
+    W_TAG * tag
+        + W_TEXT * text
+        + W_ATTRS * attrs
+        + W_ANCESTORS * ancestors
+        + W_PARENT_SIBLING * parent_sibling
+}
+
+/// Why a relocation was rejected.
+#[derive(Debug, Clone, PartialEq)]
+pub enum RejectReason {
+    /// No candidates to score.
+    NoCandidates,
+    /// Best score below [`ADAPTIVE_THRESHOLD`].
+    LowScore { best: f64 },
+    /// Best score too close to the runner-up (below [`ADAPTIVE_MARGIN`]).
+    Ambiguous { best: f64, second: f64 },
+}
+
+/// A successful relocation decision.
+#[derive(Debug, Clone, PartialEq)]
+pub struct Relocation {
+    /// Chosen candidate's backend node id.
+    pub backend_node_id: i64,
+    /// Winning score.
+    pub score: f64,
+    /// Runner-up score (0.0 when there was only one candidate).
+    pub second_score: f64,
+}
+
+/// Pick the best candidate, accepting only when confident. `candidates` is a
+/// list of `(backend_node_id, fingerprint)` for the current page.
+pub fn pick_best(
+    base: &ElementFingerprint,
+    candidates: &[(i64, ElementFingerprint)],
+    threshold: f64,
+    margin: f64,
+) -> Result<Relocation, RejectReason> {
+    if candidates.is_empty() {
+        return Err(RejectReason::NoCandidates);
+    }
+    let mut scored: Vec<(i64, f64)> = candidates
+        .iter()
+        .map(|(id, fp)| (*id, score(base, fp)))
+        .collect();
+    // Highest score first; stable enough for deterministic ties.
+    scored.sort_by(|a, b| b.1.partial_cmp(&a.1).unwrap_or(std::cmp::Ordering::Equal));
+
+    let (best_id, best) = scored[0];
+    let second = scored.get(1).map(|(_, s)| *s).unwrap_or(0.0);
+
+    if best < threshold {
+        return Err(RejectReason::LowScore { best });
+    }
+    if best - second < margin {
+        return Err(RejectReason::Ambiguous { best, second });
+    }
+    Ok(Relocation {
+        backend_node_id: best_id,
+        score: best,
+        second_score: second,
+    })
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn fp(tag: &str, text: &str, attrs: &[(&str, &str)]) -> ElementFingerprint {
+        ElementFingerprint {
+            tag: tag.to_string(),
+            text: text.to_string(),
+            attrs: attrs
+                .iter()
+                .map(|(k, v)| (k.to_string(), v.to_string()))
+                .collect(),
+            ..Default::default()
+        }
+    }
+
+    #[test]
+    fn identical_fingerprints_score_one() {
+        let a = fp("button", "Submit", &[("id", "go"), ("class", "btn primary")]);
+        assert!((score(&a, &a) - 1.0).abs() < 1e-9);
+    }
+
+    #[test]
+    fn different_tag_caps_score_below_threshold() {
+        let a = fp("button", "Submit", &[("id", "go")]);
+        let b = fp("a", "Submit", &[("id", "go")]);
+        // Same text + same attrs but different role: must lose the role weight
+        // (W_TAG = 0.20), landing around 0.80 and below a perfect match.
+        let s = score(&a, &b);
+        assert!(s < 0.85 && s > 0.75, "got {s}");
+    }
+
+    #[test]
+    fn string_similarity_basics() {
+        assert_eq!(string_similarity("abc", "abc"), 1.0);
+        assert_eq!(string_similarity("", ""), 1.0);
+        assert!(string_similarity("Submit", "Submit now") > 0.5);
+        assert!(string_similarity("Add post", "Post all") < 0.6);
+    }
+
+    #[test]
+    fn class_uses_token_overlap() {
+        let a = fp("div", "", &[("class", "card primary big")]);
+        let b = fp("div", "", &[("class", "card primary")]);
+        // partial class overlap should still score high (tag+text match, attrs partial)
+        let s = score(&a, &b);
+        assert!(s > 0.85, "got {s}");
+    }
+
+    #[test]
+    fn ancestors_lcs() {
+        let mut a = fp("button", "OK", &[]);
+        let mut b = fp("button", "OK", &[]);
+        a.ancestors = vec!["form#f".into(), "div.col".into(), "body".into()];
+        // b wrapped in an extra div — DOM path changed but mostly preserved
+        b.ancestors = vec!["form#f".into(), "div.wrap".into(), "div.col".into(), "body".into()];
+        let s = score(&a, &b);
+        assert!(s > 0.85, "got {s}");
+    }
+
+    #[test]
+    fn pick_best_accepts_clear_winner() {
+        let base = fp("button", "Submit", &[("id", "go")]);
+        let winner = fp("button", "Submit", &[("id", "go")]);
+        let other = fp("a", "Home", &[("href", "/")]);
+        let out = pick_best(
+            &base,
+            &[(10, other), (20, winner)],
+            ADAPTIVE_THRESHOLD,
+            ADAPTIVE_MARGIN,
+        )
+        .expect("should accept");
+        assert_eq!(out.backend_node_id, 20);
+        assert!(out.score > out.second_score);
+    }
+
+    #[test]
+    fn pick_best_rejects_ambiguous_twins() {
+        let base = fp("button", "Delete", &[("class", "btn danger")]);
+        // Two near-identical delete buttons — must refuse to guess.
+        let twin_a = fp("button", "Delete", &[("class", "btn danger")]);
+        let twin_b = fp("button", "Delete", &[("class", "btn danger")]);
+        let err = pick_best(
+            &base,
+            &[(1, twin_a), (2, twin_b)],
+            ADAPTIVE_THRESHOLD,
+            ADAPTIVE_MARGIN,
+        )
+        .unwrap_err();
+        assert!(matches!(err, RejectReason::Ambiguous { .. }), "got {err:?}");
+    }
+
+    #[test]
+    fn pick_best_rejects_low_score() {
+        let base = fp("button", "Submit order", &[("id", "checkout")]);
+        let junk = fp("span", "unrelated footer text", &[("class", "muted")]);
+        let err = pick_best(&base, &[(1, junk)], ADAPTIVE_THRESHOLD, ADAPTIVE_MARGIN).unwrap_err();
+        assert!(matches!(err, RejectReason::LowScore { .. }), "got {err:?}");
+    }
+
+    #[test]
+    fn pick_best_no_candidates() {
+        let base = fp("button", "x", &[]);
+        assert_eq!(
+            pick_best(&base, &[], ADAPTIVE_THRESHOLD, ADAPTIVE_MARGIN).unwrap_err(),
+            RejectReason::NoCandidates
+        );
+    }
+}

cli/src/native/browser.rs

@@ -12,6 +12,11 @@ use super::cdp::lightpanda::{launch_lightpanda, LightpandaLaunchOptions, Lightpa
 use super::cdp::types::*;
 use super::element::{resolve_element_object_id, RefMap};
 
+/// The daemon's session name, set once at daemon start. Names the Chrome tab
+/// group that abs-created tabs land in when driving the user's real Chrome via
+/// the `ab-connect` extension, so each agent/session gets its own group.
+pub static DAEMON_SESSION: std::sync::OnceLock<String> = std::sync::OnceLock::new();
+
 // ---------------------------------------------------------------------------
 // Launch validation
 // ---------------------------------------------------------------------------
@@ -305,6 +310,22 @@ pub struct BrowserManager {
     /// Origins visited during this session, used by save_state to collect cross-origin localStorage.
     visited_origins: HashSet<String>,
     next_tab_id: u32,
+    /// Whether to enable the CDP `Runtime` domain (console / error / exception capture).
+    /// OFF by default for stealth: a live `Runtime.enable` is a detectable CDP signal
+    /// (the patchright / rebrowser "runtime leak") — even when attached to the user's
+    /// real Chrome. Opt in via `AGENT_BROWSER_CAPTURE_CONSOLE=1` when you need the
+    /// `console` / `errors` commands to return page output.
+    pub capture_console: bool,
+}
+
+/// Whether console/error capture (and thus `Runtime.enable`) is opted into for this
+/// daemon. Defaults to `false` so the common automation path leaves no Runtime-domain
+/// fingerprint. Set `AGENT_BROWSER_CAPTURE_CONSOLE=1` (or `true`) to turn it on.
+pub fn console_capture_enabled() -> bool {
+    std::env::var("AGENT_BROWSER_CAPTURE_CONSOLE")
+        .ok()
+        .map(|v| v == "1" || v.eq_ignore_ascii_case("true"))
+        .unwrap_or(false)
 }
 
 const LIGHTPANDA_CDP_CONNECT_TIMEOUT: Duration = Duration::from_secs(5);
@@ -413,6 +434,7 @@ impl BrowserManager {
                 ignore_https_errors,
                 visited_origins: HashSet::new(),
                 next_tab_id: 1,
+                capture_console: console_capture_enabled(),
             };
             manager.discover_and_attach_targets().await?;
             manager
@@ -502,6 +524,7 @@ impl BrowserManager {
             ignore_https_errors: false,
             visited_origins: HashSet::new(),
             next_tab_id: 1,
+            capture_console: console_capture_enabled(),
         };
 
         if direct_page {
@@ -550,12 +573,14 @@ impl BrowserManager {
 
         if page_targets.is_empty() {
             // Create a new tab
+            let agent_group = self.agent_group();
             let result: CreateTargetResult = self
                 .client
                 .send_command_typed(
                     "Target.createTarget",
                     &CreateTargetParams {
                         url: "about:blank".to_string(),
+                        agent_group,
                     },
                     None,
                 )
@@ -629,9 +654,14 @@ impl BrowserManager {
         self.client
             .send_command_no_params("Page.enable", Some(session_id))
             .await?;
-        self.client
-            .send_command_no_params("Runtime.enable", Some(session_id))
-            .await?;
+        // `Runtime.enable` leaves a detectable CDP signal (the patchright/rebrowser
+        // "runtime leak"), so only enable it when console/error capture is opted in.
+        // `Runtime.evaluate` / `Runtime.callFunctionOn` work fine without it.
+        if self.capture_console {
+            self.client
+                .send_command_no_params("Runtime.enable", Some(session_id))
+                .await?;
+        }
         // Resume the target if it is paused waiting for the debugger.
         // This is needed for real browser sessions (Chrome 144+) where targets
         // are paused after attach until explicitly resumed. No-op otherwise.
@@ -665,9 +695,12 @@ impl BrowserManager {
         self.client
             .send_command_no_params("Page.enable", None)
             .await?;
-        self.client
-            .send_command_no_params("Runtime.enable", None)
-            .await?;
+        // See `enable_domains`: `Runtime.enable` is a CDP fingerprint, gated on opt-in.
+        if self.capture_console {
+            self.client
+                .send_command_no_params("Runtime.enable", None)
+                .await?;
+        }
         let _ = self
             .client
             .send_command_no_params("Runtime.runIfWaitingForDebugger", None)
@@ -932,12 +965,14 @@ impl BrowserManager {
             return Ok(());
         }
 
+        let agent_group = self.agent_group();
         let result: CreateTargetResult = self
             .client
             .send_command_typed(
                 "Target.createTarget",
                 &CreateTargetParams {
                     url: "about:blank".to_string(),
+                    agent_group,
                 },
                 None,
             )
@@ -1046,6 +1081,27 @@ impl BrowserManager {
         self.pages.iter().any(|p| p.label.as_deref() == Some(label))
     }
 
+    /// Chrome tab-group name for tabs this manager creates, or `None` when not
+    /// driving the user's real Chrome via the `ab-connect` extension relay.
+    ///
+    /// Grouping only makes sense on the shared real browser (one Chrome, many
+    /// agents): each session's tabs go into its own group. On a launched / direct
+    /// CDP browser the endpoint is strict, so we must NOT send the custom param —
+    /// hence `None` there. We detect the relay by matching our `ws_url` against
+    /// the live relay URL the native-messaging host published.
+    fn agent_group(&self) -> Option<String> {
+        let via_relay = crate::connect::relay_url().as_deref() == Some(self.ws_url.as_str());
+        if !via_relay {
+            return None;
+        }
+        let name = DAEMON_SESSION.get().map(String::as_str).unwrap_or("default");
+        if name.is_empty() {
+            None
+        } else {
+            Some(name.to_string())
+        }
+    }
+
     pub async fn tab_new(
         &mut self,
         url: Option<&str>,
@@ -1070,12 +1126,14 @@ impl BrowserManager {
 
         let target_url = url.unwrap_or("about:blank");
 
+        let agent_group = self.agent_group();
         let result: CreateTargetResult = self
             .client
             .send_command_typed(
                 "Target.createTarget",
                 &CreateTargetParams {
                     url: target_url.to_string(),
+                    agent_group,
                 },
                 None,
             )
@@ -1659,6 +1717,7 @@ async fn initialize_lightpanda_manager(
             ignore_https_errors: false,
             visited_origins: HashSet::new(),
             next_tab_id: 1,
+            capture_console: console_capture_enabled(),
         };
 
         match discover_and_attach_lightpanda_targets(&mut manager, deadline).await {

cli/src/native/cdp/chrome.rs

@@ -146,6 +146,30 @@ struct ChromeArgs {
     temp_user_data_dir: Option<PathBuf>,
 }
 
+/// Decide the `--force-webrtc-ip-handling-policy` value, if any, for a launched
+/// Chrome. Returns `None` to leave WebRTC at Chrome's default behavior.
+fn webrtc_ip_handling_policy(has_proxy: bool) -> Option<&'static str> {
+    let opt_in = std::env::var("AGENT_BROWSER_BLOCK_WEBRTC").ok();
+    let explicitly_off = opt_in
+        .as_deref()
+        .is_some_and(|v| v == "0" || v.eq_ignore_ascii_case("false"));
+    if explicitly_off {
+        return None;
+    }
+    let explicitly_on = opt_in
+        .as_deref()
+        .is_some_and(|v| v == "1" || v.eq_ignore_ascii_case("true"));
+    if has_proxy {
+        // Force all WebRTC UDP through the proxy so the real IP can't leak.
+        Some("disable_non_proxied_udp")
+    } else if explicitly_on {
+        // No proxy, but the user asked to hide the local network IP.
+        Some("default_public_interface_only")
+    } else {
+        None
+    }
+}
+
 fn build_chrome_args(options: &LaunchOptions) -> Result<ChromeArgs, String> {
     let mut args = vec![
         "--remote-debugging-port=0".to_string(),
@@ -204,6 +228,20 @@ fn build_chrome_args(options: &LaunchOptions) -> Result<ChromeArgs, String> {
         args.push(format!("--proxy-bypass-list={}", bypass));
     }
 
+    // WebRTC IP-leak handling. WebRTC enumerates ICE candidates that can expose
+    // the machine's real local/public IP even when HTTP traffic goes through a
+    // proxy — defeating the proxy. `--force-webrtc-ip-handling-policy` is a real
+    // Chrome privacy switch (no detectable JS lie), applied here for launched
+    // Chrome only (an attached real Chrome keeps the user's own flags).
+    //   - proxy set            -> `disable_non_proxied_udp`: force WebRTC through
+    //                             the proxy so the real IP can't leak.
+    //   - AGENT_BROWSER_BLOCK_WEBRTC=1 (no proxy) -> `default_public_interface_only`:
+    //                             hide the local network IP (Brave/uBlock default).
+    // Opt out entirely with AGENT_BROWSER_BLOCK_WEBRTC=0.
+    if let Some(policy) = webrtc_ip_handling_policy(options.proxy.is_some()) {
+        args.push(format!("--force-webrtc-ip-handling-policy={}", policy));
+    }
+
     let (user_data_dir, temp_user_data_dir) = if let Some(ref profile) = options.profile {
         let expanded = expand_tilde(profile);
         let dir = PathBuf::from(&expanded);
@@ -1343,6 +1381,37 @@ mod tests {
     use super::*;
     use crate::test_utils::EnvGuard;
 
+    #[test]
+    fn webrtc_policy_forces_proxy_when_proxy_set() {
+        let g = EnvGuard::new(&["AGENT_BROWSER_BLOCK_WEBRTC"]);
+        g.remove("AGENT_BROWSER_BLOCK_WEBRTC");
+        // Proxy set, no env: always force WebRTC through the proxy.
+        assert_eq!(
+            webrtc_ip_handling_policy(true),
+            Some("disable_non_proxied_udp")
+        );
+        // No proxy, no env: leave WebRTC at Chrome's default.
+        assert_eq!(webrtc_ip_handling_policy(false), None);
+    }
+
+    #[test]
+    fn webrtc_policy_opt_in_and_opt_out() {
+        let g = EnvGuard::new(&["AGENT_BROWSER_BLOCK_WEBRTC"]);
+
+        g.set("AGENT_BROWSER_BLOCK_WEBRTC", "1");
+        assert_eq!(
+            webrtc_ip_handling_policy(false),
+            Some("default_public_interface_only")
+        );
+
+        // Explicit opt-out wins even when a proxy is set.
+        g.set("AGENT_BROWSER_BLOCK_WEBRTC", "0");
+        assert_eq!(webrtc_ip_handling_policy(true), None);
+        assert_eq!(webrtc_ip_handling_policy(false), None);
+
+        g.remove("AGENT_BROWSER_BLOCK_WEBRTC");
+    }
+
     #[cfg(unix)]
     fn spawn_noop_child() -> Child {
         Command::new("/bin/sh")

cli/src/native/cdp/types.rs

@@ -141,6 +141,12 @@ pub struct SetDiscoverTargetsParams {
 #[serde(rename_all = "camelCase")]
 pub struct CreateTargetParams {
     pub url: String,
+    /// Non-CDP hint consumed only by the `ab-connect` extension: the Chrome
+    /// tab-group name to drop the new tab into (per-session grouping on the
+    /// shared real Chrome). `None` on the normal CDP path so a strict real-Chrome
+    /// endpoint never receives an unknown parameter.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub agent_group: Option<String>,
 }
 
 #[derive(Debug, Deserialize)]

cli/src/native/daemon.rs

@@ -17,6 +17,10 @@ use super::state;
 use super::stream::StreamServer;
 
 pub async fn run_daemon(session: &str) {
+    // Record this daemon's session so tabs it opens on the shared real Chrome
+    // (via the ab-connect extension) land in a per-session Chrome tab group.
+    let _ = super::browser::DAEMON_SESSION.set(session.to_string());
+
     let socket_dir = get_daemon_socket_dir();
     if !socket_dir.exists() {
         let _ = fs::create_dir_all(&socket_dir);

cli/src/native/element.rs

@@ -2,6 +2,7 @@ use std::collections::HashMap;
 
 use serde_json::Value;
 
+use super::adaptive::{self, ElementFingerprint};
 use super::cdp::client::CdpClient;
 use super::cdp::types::*;
 
@@ -13,6 +14,9 @@ pub struct RefEntry {
     pub nth: Option<usize>,
     pub selector: Option<String>,
     pub frame_id: Option<String>,
+    /// AX fingerprint captured at snapshot time, used by adaptive relocation when
+    /// the node is gone and the role/name/nth re-query also fails.
+    pub fingerprint: Option<ElementFingerprint>,
 }
 
 pub struct RefMap {
@@ -57,10 +61,19 @@ impl RefMap {
                 nth,
                 selector: None,
                 frame_id: frame_id.map(|s| s.to_string()),
+                fingerprint: None,
             },
         );
     }
 
+    /// Attach an AX fingerprint to an existing ref (set during snapshot, used by
+    /// adaptive relocation). No-op if the ref is unknown.
+    pub fn set_fingerprint(&mut self, ref_id: &str, fingerprint: ElementFingerprint) {
+        if let Some(entry) = self.map.get_mut(ref_id) {
+            entry.fingerprint = Some(fingerprint);
+        }
+    }
+
     pub fn add_selector(
         &mut self,
         ref_id: String,
@@ -78,6 +91,7 @@ impl RefMap {
                 nth,
                 selector: Some(selector),
                 frame_id: None,
+                fingerprint: None,
             },
         );
     }
@@ -146,6 +160,46 @@ pub fn parse_ref(input: &str) -> Option<String> {
     None
 }
 
+/// When a saved `@ref`'s node is gone and the role/name/nth re-query also failed,
+/// try to relocate the element by AX fingerprint similarity. Returns the chosen
+/// backend node id only when confident (high score + clear margin over the
+/// runner-up). Opt out with `AGENT_BROWSER_ADAPTIVE_REF=0`.
+async fn relocate_stale_ref(
+    client: &CdpClient,
+    ref_id: &str,
+    entry: &RefEntry,
+    session_id: &str,
+    iframe_sessions: &HashMap<String, String>,
+) -> Option<i64> {
+    if std::env::var("AGENT_BROWSER_ADAPTIVE_REF").as_deref() == Ok("0") {
+        return None;
+    }
+    let baseline = entry.fingerprint.as_ref()?;
+    let candidates = super::snapshot::collect_current_fingerprints(
+        client,
+        session_id,
+        entry.frame_id.as_deref(),
+        iframe_sessions,
+    )
+    .await
+    .ok()?;
+    match adaptive::pick_best(
+        baseline,
+        &candidates,
+        adaptive::ADAPTIVE_THRESHOLD,
+        adaptive::ADAPTIVE_MARGIN,
+    ) {
+        Ok(reloc) => {
+            eprintln!(
+                "[adaptive] relocated {ref_id} ({} \"{}\") score={:.2} second={:.2} -> backendNodeId {}",
+                entry.role, entry.name, reloc.score, reloc.second_score, reloc.backend_node_id
+            );
+            Some(reloc.backend_node_id)
+        }
+        Err(_) => None,
+    }
+}
+
 pub async fn resolve_element_center(
     client: &CdpClient,
     session_id: &str,
@@ -163,15 +217,19 @@ pub async fn resolve_element_center(
 
         // Try cached backend_node_id first (fast path)
         if let Some(backend_node_id) = entry.backend_node_id {
+            let mut active_id = backend_node_id;
             // Identity check: React often re-uses the same DOM node when
             // re-rendering — backendNodeId stays the same but accessibleName
             // / role changes. Without this verification, `click @e20` (saved
             // when the button said "Add post") happily clicks the *same*
             // node that now says "Post all", silently submitting the thread.
             //
-            // Set AGENT_BROWSER_VERIFY_REF=0 to skip (saves one CDP
-            // roundtrip per ref-based interaction; only safe if you know
-            // the page is static between snapshot and click).
+            // On mismatch, try adaptive fingerprint relocation before failing:
+            // a confident high-score/high-margin match is a stronger identity
+            // signal than role+name, and lets a moved+renamed element still
+            // resolve. If relocation isn't confident, surface the original
+            // identity error. Set AGENT_BROWSER_VERIFY_REF=0 to skip the check
+            // (and thus relocation) entirely.
             if std::env::var("AGENT_BROWSER_VERIFY_REF").as_deref() != Ok("0") {
                 if let Err(e) = verify_ref_identity(
                     client,
@@ -183,7 +241,12 @@ pub async fn resolve_element_center(
                 )
                 .await
                 {
-                    return Err(e);
+                    match relocate_stale_ref(client, &ref_id, entry, session_id, iframe_sessions)
+                        .await
+                    {
+                        Some(id) => active_id = id,
+                        None => return Err(e),
+                    }
                 }
             }
 
@@ -191,7 +254,7 @@ pub async fn resolve_element_center(
                 .send_command_typed(
                     "DOM.getBoxModel",
                     &DomGetBoxModelParams {
-                        backend_node_id: Some(backend_node_id),
+                        backend_node_id: Some(active_id),
                         node_id: None,
                         object_id: None,
                     },
@@ -213,15 +276,9 @@ pub async fn resolve_element_center(
                 //
                 // Set AGENT_BROWSER_VERIFY_CLICK_TARGET=0 to skip.
                 if std::env::var("AGENT_BROWSER_VERIFY_CLICK_TARGET").as_deref() != Ok("0") {
-                    if let Err(e) = verify_click_target(
-                        client,
-                        effective_session_id,
-                        backend_node_id,
-                        &ref_id,
-                        x,
-                        y,
-                    )
-                    .await
+                    if let Err(e) =
+                        verify_click_target(client, effective_session_id, active_id, &ref_id, x, y)
+                            .await
                     {
                         return Err(e);
                     }
@@ -231,8 +288,9 @@ pub async fn resolve_element_center(
             // backend_node_id is stale; re-query the accessibility tree below
         }
 
-        // Fallback: re-query the accessibility tree to find a fresh node by role/name
-        let fresh_id = find_node_id_by_role_name(
+        // Fallback: re-query the accessibility tree to find a fresh node by role/name.
+        // If that fails, try adaptive fingerprint relocation before giving up.
+        let fresh_id = match find_node_id_by_role_name(
             client,
             session_id,
             &entry.role,
@@ -241,7 +299,16 @@ pub async fn resolve_element_center(
             entry.frame_id.as_deref(),
             iframe_sessions,
         )
-        .await?;
+        .await
+        {
+            Ok(id) => id,
+            Err(e) => match relocate_stale_ref(client, &ref_id, entry, session_id, iframe_sessions)
+                .await
+            {
+                Some(id) => id,
+                None => return Err(e),
+            },
+        };
         let result: DomGetBoxModelResult = client
             .send_command_typed(
                 "DOM.getBoxModel",
@@ -279,9 +346,11 @@ pub async fn resolve_element_object_id(
 
         // Try cached backend_node_id first (fast path)
         if let Some(backend_node_id) = entry.backend_node_id {
+            let mut active_id = backend_node_id;
             // Same identity guard as resolve_element_center — see that
             // function for why React DOM-node-reuse breaks ref-based
-            // interactions if we skip this.
+            // interactions if we skip this, and why a confident adaptive
+            // relocation is allowed to override an identity mismatch.
             if std::env::var("AGENT_BROWSER_VERIFY_REF").as_deref() != Ok("0") {
                 if let Err(e) = verify_ref_identity(
                     client,
@@ -293,7 +362,12 @@ pub async fn resolve_element_object_id(
                 )
                 .await
                 {
-                    return Err(e);
+                    match relocate_stale_ref(client, &ref_id, entry, session_id, iframe_sessions)
+                        .await
+                    {
+                        Some(id) => active_id = id,
+                        None => return Err(e),
+                    }
                 }
             }
 
@@ -301,7 +375,7 @@ pub async fn resolve_element_object_id(
                 .send_command_typed(
                     "DOM.resolveNode",
                     &DomResolveNodeParams {
-                        backend_node_id: Some(backend_node_id),
+                        backend_node_id: Some(active_id),
                         node_id: None,
                         object_group: Some("agent-browser".to_string()),
                     },
@@ -317,8 +391,9 @@ pub async fn resolve_element_object_id(
             // backend_node_id is stale; re-query the accessibility tree below
         }
 
-        // Fallback: re-query the accessibility tree to find a fresh node by role/name
-        let fresh_id = find_node_id_by_role_name(
+        // Fallback: re-query the accessibility tree to find a fresh node by role/name.
+        // If that fails, try adaptive fingerprint relocation before giving up.
+        let fresh_id = match find_node_id_by_role_name(
             client,
             session_id,
             &entry.role,
@@ -327,7 +402,16 @@ pub async fn resolve_element_object_id(
             entry.frame_id.as_deref(),
             iframe_sessions,
         )
-        .await?;
+        .await
+        {
+            Ok(id) => id,
+            Err(e) => match relocate_stale_ref(client, &ref_id, entry, session_id, iframe_sessions)
+                .await
+            {
+                Some(id) => id,
+                None => return Err(e),
+            },
+        };
         let result: DomResolveNodeResult = client
             .send_command_typed(
                 "DOM.resolveNode",

cli/src/native/interaction.rs

@@ -15,7 +15,111 @@ pub async fn click(
     click_count: i32,
     iframe_sessions: &HashMap<String, String>,
 ) -> Result<(), String> {
-    let (x, y, effective_session_id) = resolve_element_center(
+    // AGENT_BROWSER_CLICK_MODE: "" (default) = coordinate click with a DOM
+    // fallback; "coord" = strict coordinate only (no fallback); "dom" = always
+    // dispatch through the DOM.
+    let mode = std::env::var("AGENT_BROWSER_CLICK_MODE").unwrap_or_default();
+
+    // (A) Scroll the target into view first so the computed coordinates land
+    // inside the viewport. Without this, an element below the fold (or revealed
+    // after scroll/popup) yields off-viewport coordinates and the click lands on
+    // whatever currently occupies that point. Best-effort: ignore failures.
+    scroll_into_view_if_needed(client, session_id, ref_map, selector_or_ref, iframe_sessions).await;
+
+    if mode == "dom" {
+        return dom_click(client, session_id, ref_map, selector_or_ref, iframe_sessions).await;
+    }
+
+    let resolved = resolve_element_center(
+        client,
+        session_id,
+        ref_map,
+        selector_or_ref,
+        iframe_sessions,
+    )
+    .await;
+
+    match resolved {
+        Ok((x, y, effective_session_id)) => {
+            dispatch_click(client, &effective_session_id, x, y, button, click_count).await
+        }
+        Err(e) => {
+            // (B) The coordinate path failed — typically a persistent overlay
+            // failing the occlusion guard, or coordinates that won't resolve.
+            // Fall back to a DOM-dispatched `.click()` on the intended element,
+            // which targets the element directly instead of a screen point.
+            // Skipped for strict "coord" mode and for non-left / multi-clicks
+            // (a DOM `.click()` can't express right/middle/double semantics).
+            if mode == "coord" || button != "left" || click_count != 1 {
+                return Err(e);
+            }
+            eprintln!(
+                "[click] coordinate click failed ({e}); falling back to DOM dispatch \
+                 (set AGENT_BROWSER_CLICK_MODE=coord to disable)"
+            );
+            dom_click(client, session_id, ref_map, selector_or_ref, iframe_sessions)
+                .await
+                .map_err(|dom_err| format!("{e}\n(DOM-dispatch fallback also failed: {dom_err})"))
+        }
+    }
+}
+
+/// Best-effort scroll-into-view before a coordinate click. Uses Chrome's
+/// `scrollIntoViewIfNeeded` (only scrolls when not already fully visible),
+/// falling back to centered `scrollIntoView`. Resolution failures are ignored —
+/// the subsequent resolve will surface a real "not found" error.
+async fn scroll_into_view_if_needed(
+    client: &CdpClient,
+    session_id: &str,
+    ref_map: &RefMap,
+    selector_or_ref: &str,
+    iframe_sessions: &HashMap<String, String>,
+) {
+    let Ok((object_id, effective_session_id)) = resolve_element_object_id(
+        client,
+        session_id,
+        ref_map,
+        selector_or_ref,
+        iframe_sessions,
+    )
+    .await
+    else {
+        return;
+    };
+    let js = "function() { try { \
+        if (typeof this.scrollIntoViewIfNeeded === 'function') { this.scrollIntoViewIfNeeded(true); } \
+        else { this.scrollIntoView({ block: 'center', inline: 'center' }); } \
+    } catch (e) {} }";
+    let _ = client
+        .send_command_typed::<_, Value>(
+            "Runtime.callFunctionOn",
+            &CallFunctionOnParams {
+                function_declaration: js.to_string(),
+                object_id: Some(object_id),
+                arguments: None,
+                return_by_value: Some(true),
+                await_promise: Some(false),
+            },
+            Some(&effective_session_id),
+        )
+        .await;
+    // Let the scroll settle so the following getBoxModel sees final coordinates.
+    wait_for_paint_settled(client, &effective_session_id).await;
+}
+
+/// Dispatch a click through the DOM (`element.click()`) instead of via screen
+/// coordinates. Targets the intended element directly, so it works when a
+/// floating layer occludes the click point or the element sits in a portal that
+/// confuses `elementFromPoint`. Used as the fallback for `click` and when
+/// `AGENT_BROWSER_CLICK_MODE=dom`.
+async fn dom_click(
+    client: &CdpClient,
+    session_id: &str,
+    ref_map: &RefMap,
+    selector_or_ref: &str,
+    iframe_sessions: &HashMap<String, String>,
+) -> Result<(), String> {
+    let (object_id, effective_session_id) = resolve_element_object_id(
         client,
         session_id,
         ref_map,
@@ -23,7 +127,21 @@ pub async fn click(
         iframe_sessions,
     )
     .await?;
-    dispatch_click(client, &effective_session_id, x, y, button, click_count).await
+    client
+        .send_command_typed::<_, Value>(
+            "Runtime.callFunctionOn",
+            &CallFunctionOnParams {
+                function_declaration: "function() { this.click(); }".to_string(),
+                object_id: Some(object_id),
+                arguments: None,
+                return_by_value: Some(true),
+                await_promise: Some(false),
+            },
+            Some(&effective_session_id),
+        )
+        .await?;
+    wait_for_paint_settled(client, &effective_session_id).await;
+    Ok(())
 }
 
 pub async fn dblclick(

cli/src/native/mod.rs

@@ -1,6 +1,8 @@
 #[allow(dead_code)]
 pub mod actions;
 #[allow(dead_code)]
+pub mod adaptive;
+#[allow(dead_code)]
 pub mod auth;
 #[allow(dead_code)]
 pub mod browser;
@@ -25,6 +27,8 @@ pub mod policy;
 #[allow(dead_code)]
 pub mod providers;
 #[allow(dead_code)]
+pub mod relay;
+#[allow(dead_code)]
 pub mod react;
 #[allow(dead_code)]
 pub mod recording;

cli/src/native/relay.rs

@@ -0,0 +1,461 @@
+//! Relay between the `ab-connect` browser extension and the daemon's `CdpClient`.
+//!
+//! The extension speaks a small CDP-over-WebSocket "envelope" protocol (adapted
+//! from openclaw-browser-relay) and drives the user's real tabs via per-tab
+//! `chrome.debugger`. The daemon's `CdpClient`, however, expects a **browser-
+//! level** CDP endpoint (`Target.getTargets` / `Target.attachToTarget` → a
+//! `sessionId`, then per-session commands). This relay bridges the two: it
+//! tracks the targets the extension reports, answers the browser-level
+//! `Target.*` discovery commands LOCALLY, and forwards everything else to the
+//! extension as `forwardCDPCommand`. That keeps `CdpClient` and `browser.rs`
+//! unchanged.
+//!
+//! ## Multiple clients (concurrent agents on one shared browser)
+//!
+//! Several agent-browser daemons (one per `--session`) can connect to the same
+//! relay/Chrome at once. The extension is a single peer, so the relay must
+//! demultiplex: every forwarded command is re-keyed to a relay-global id mapped
+//! back to the originating client, and the extension's reply is routed to **only
+//! that client** (with its original id restored). Command ids from different
+//! clients therefore never collide, and one client never sees another's command
+//! replies. CDP *events* (no id) fan out to all clients, which ignore events for
+//! sessions they didn't attach.
+//!
+//! This module is the pure translation core (no I/O) so the protocol can be
+//! unit-tested; the tokio WebSocket server that drives it lives alongside.
+
+use std::collections::HashMap;
+
+use serde_json::{json, Value};
+
+/// Protocol version advertised in the connect handshake (matches the extension).
+pub const RELAY_PROTOCOL: i64 = 3;
+
+/// Identifies one connected CDP client (agent-browser daemon) for routing.
+pub type ClientId = u64;
+
+/// One target (tab) the extension has attached, as the relay tracks it.
+#[derive(Clone)]
+struct TargetEntry {
+    session_id: String,
+    target_info: Value,
+}
+
+/// Relay translation state: the targets the extension exposes, plus the
+/// in-flight command map used to route extension replies back to the right
+/// client.
+#[derive(Default)]
+pub struct RelayState {
+    /// targetId -> entry
+    targets: HashMap<String, TargetEntry>,
+    /// relay-global command id -> (client that sent it, its original id)
+    pending: HashMap<i64, (ClientId, Value)>,
+    /// monotonic source of relay-global command ids
+    next_global_id: i64,
+}
+
+/// What to do with a raw CDP command received from a `CdpClient`.
+#[derive(Debug, PartialEq)]
+pub enum ClientRoute {
+    /// Answer locally; the value is a raw CDP response `{id, result}` to send
+    /// back to the originating client only.
+    Local(Value),
+    /// Forward to the extension; the value is a `forwardCDPCommand` envelope
+    /// already re-keyed to a relay-global id.
+    Forward(Value),
+}
+
+/// An output the relay emits while handling an extension message.
+#[derive(Debug, PartialEq)]
+pub enum RelayOut {
+    /// Send this raw CDP message to clients. `to = Some(id)` targets one client
+    /// (a command reply); `to = None` broadcasts (a CDP event).
+    ToClient { to: Option<ClientId>, msg: Value },
+    /// Send this envelope message back to the extension.
+    ToExt(Value),
+}
+
+impl RelayState {
+    pub fn new() -> Self {
+        Self::default()
+    }
+
+    /// The challenge the relay sends to the extension as soon as it connects,
+    /// kicking off the connect handshake.
+    pub fn connect_challenge(nonce: &str) -> Value {
+        json!({ "type": "event", "event": "connect.challenge", "payload": { "nonce": nonce } })
+    }
+
+    /// A keepalive ping for the extension.
+    pub fn ping() -> Value {
+        json!({ "method": "ping" })
+    }
+
+    /// Forget a disconnected client's in-flight commands so its orphaned
+    /// `pending` entries don't leak.
+    pub fn drop_client(&mut self, client_id: ClientId) {
+        self.pending.retain(|_, (cid, _)| *cid != client_id);
+    }
+
+    /// Route a raw CDP command `{id, method, params?, sessionId?}` from a
+    /// `CdpClient`: answer browser-level `Target.*` discovery locally, forward
+    /// the rest to the extension under a relay-global id keyed to `client_id`.
+    pub fn route_client_command(&mut self, client_id: ClientId, raw: &Value) -> ClientRoute {
+        let id = raw.get("id").cloned().unwrap_or(Value::Null);
+        let method = raw.get("method").and_then(|m| m.as_str()).unwrap_or("");
+        let params = raw.get("params").cloned().unwrap_or_else(|| json!({}));
+        let session_id = raw.get("sessionId").and_then(|s| s.as_str());
+
+        match method {
+            // Discovery is best-effort and event-driven in real CDP; abs only
+            // reads the getTargets result, so an empty ack is enough here.
+            "Target.setDiscoverTargets" | "Target.setAutoAttach" => {
+                ClientRoute::Local(json!({ "id": id, "result": {} }))
+            }
+            "Target.getTargets" => {
+                let infos: Vec<Value> =
+                    self.targets.values().map(|t| t.target_info.clone()).collect();
+                ClientRoute::Local(json!({ "id": id, "result": { "targetInfos": infos } }))
+            }
+            "Target.attachToTarget" => {
+                let target_id = params.get("targetId").and_then(|t| t.as_str()).unwrap_or("");
+                match self.targets.get(target_id) {
+                    Some(entry) => ClientRoute::Local(
+                        json!({ "id": id, "result": { "sessionId": entry.session_id } }),
+                    ),
+                    None => ClientRoute::Local(json!({
+                        "id": id,
+                        "error": { "code": -32602, "message": format!("No such target {target_id}") }
+                    })),
+                }
+            }
+            // Everything else goes to the extension's chrome.debugger. Re-key the
+            // id so this client's reply can be routed back unambiguously.
+            _ => {
+                self.next_global_id += 1;
+                let gid = self.next_global_id;
+                self.pending.insert(gid, (client_id, id));
+                ClientRoute::Forward(json!({
+                    "id": gid,
+                    "method": "forwardCDPCommand",
+                    "params": { "method": method, "params": params, "sessionId": session_id },
+                }))
+            }
+        }
+    }
+
+    /// Handle one decoded message from the extension. Updates target state and
+    /// returns the messages to emit (routed to a client and/or back to the
+    /// extension). `expected_token` is matched against the connect handshake.
+    pub fn handle_ext_message(&mut self, msg: &Value, expected_token: &str) -> Vec<RelayOut> {
+        // Connect handshake request from the extension.
+        if msg.get("type").and_then(|t| t.as_str()) == Some("req")
+            && msg.get("method").and_then(|m| m.as_str()) == Some("connect")
+        {
+            let id = msg.get("id").cloned().unwrap_or(Value::Null);
+            let token = msg
+                .get("params")
+                .and_then(|p| p.get("auth"))
+                .and_then(|a| a.get("token"))
+                .and_then(|t| t.as_str())
+                .unwrap_or("");
+            let ok = !expected_token.is_empty() && token == expected_token;
+            let mut res = json!({ "type": "res", "id": id, "ok": ok });
+            if !ok {
+                res["error"] = json!({ "message": "invalid relay token" });
+            }
+            return vec![RelayOut::ToExt(res)];
+        }
+
+        // Keepalive.
+        if msg.get("method").and_then(|m| m.as_str()) == Some("pong") {
+            return vec![];
+        }
+
+        // Response to a forwardCDPCommand we sent → route the raw CDP response
+        // back to the client that issued it, with its original id restored.
+        if msg.get("id").is_some()
+            && (msg.get("result").is_some() || msg.get("error").is_some())
+            && msg.get("method").is_none()
+        {
+            let gid = msg.get("id").and_then(|i| i.as_i64());
+            let (to, orig_id) = match gid.and_then(|g| self.pending.remove(&g)) {
+                Some((client_id, orig)) => (Some(client_id), orig),
+                // No mapping (stale/unknown id) — fall back to broadcasting with
+                // whatever id the extension echoed.
+                None => (None, msg.get("id").cloned().unwrap_or(Value::Null)),
+            };
+            let mut out = json!({ "id": orig_id });
+            if let Some(r) = msg.get("result") {
+                out["result"] = r.clone();
+            }
+            if let Some(e) = msg.get("error") {
+                // CdpClient expects an error object; wrap a bare string.
+                out["error"] = match e {
+                    Value::String(s) => json!({ "code": -32000, "message": s }),
+                    other => other.clone(),
+                };
+            }
+            return vec![RelayOut::ToClient { to, msg: out }];
+        }
+
+        // CDP event forwarded from a tab.
+        if msg.get("method").and_then(|m| m.as_str()) == Some("forwardCDPEvent") {
+            let p = msg.get("params").cloned().unwrap_or_else(|| json!({}));
+            let inner_method = p.get("method").and_then(|m| m.as_str()).unwrap_or("");
+            let inner_params = p.get("params").cloned().unwrap_or_else(|| json!({}));
+            let session_id = p.get("sessionId").and_then(|s| s.as_str());
+
+            // Learn/forget targets from the extension's synthesized Target events.
+            // We consume these to maintain state and do NOT forward them: abs
+            // discovers targets by pulling getTargets, and forwarding a second
+            // attachedToTarget would duplicate the one attachToTarget emits.
+            match inner_method {
+                "Target.attachedToTarget" => {
+                    if let Some(info) = inner_params.get("targetInfo") {
+                        if let Some(tid) = info.get("targetId").and_then(|t| t.as_str()) {
+                            let sid = inner_params
+                                .get("sessionId")
+                                .and_then(|s| s.as_str())
+                                .unwrap_or("")
+                                .to_string();
+                            self.targets.insert(
+                                tid.to_string(),
+                                TargetEntry { session_id: sid, target_info: info.clone() },
+                            );
+                        }
+                    }
+                    return vec![];
+                }
+                "Target.detachedFromTarget" => {
+                    let gone = inner_params.get("sessionId").and_then(|s| s.as_str());
+                    if let Some(gone) = gone {
+                        self.targets.retain(|_, e| e.session_id != gone);
+                    }
+                    return vec![];
+                }
+                _ => {}
+            }
+
+            // Regular CDP event → fan out to all clients (each filters by the
+            // sessions it attached to).
+            let mut ev = json!({ "method": inner_method, "params": inner_params });
+            if let Some(sid) = session_id {
+                ev["sessionId"] = json!(sid);
+            }
+            return vec![RelayOut::ToClient { to: None, msg: ev }];
+        }
+
+        vec![]
+    }
+
+    #[cfg(test)]
+    fn seed_target(&mut self, target_id: &str, session_id: &str) {
+        self.targets.insert(
+            target_id.to_string(),
+            TargetEntry {
+                session_id: session_id.to_string(),
+                target_info: json!({
+                    "targetId": target_id,
+                    "type": "page",
+                    "title": "",
+                    "url": "about:blank",
+                    "attached": true,
+                }),
+            },
+        );
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn attached_event(target_id: &str, session_id: &str) -> Value {
+        json!({
+            "method": "forwardCDPEvent",
+            "params": {
+                "sessionId": session_id,
+                "method": "Target.attachedToTarget",
+                "params": {
+                    "sessionId": session_id,
+                    "targetInfo": { "targetId": target_id, "type": "page", "url": "https://x", "title": "X" }
+                }
+            }
+        })
+    }
+
+    #[test]
+    fn learns_target_from_attached_event_and_does_not_forward_it() {
+        let mut s = RelayState::new();
+        let out = s.handle_ext_message(&attached_event("T1", "cb-tab-1"), "tok");
+        assert!(out.is_empty(), "attachedToTarget should be consumed, not forwarded");
+        // Now getTargets must report it.
+        let route = s.route_client_command(1, &json!({ "id": 1, "method": "Target.getTargets" }));
+        match route {
+            ClientRoute::Local(v) => {
+                let infos = v["result"]["targetInfos"].as_array().unwrap();
+                assert_eq!(infos.len(), 1);
+                assert_eq!(infos[0]["targetId"], "T1");
+            }
+            _ => panic!("getTargets must be local"),
+        }
+    }
+
+    #[test]
+    fn attach_to_target_returns_known_session() {
+        let mut s = RelayState::new();
+        s.seed_target("T1", "cb-tab-1");
+        let route = s.route_client_command(
+            7,
+            &json!({ "id": 5, "method": "Target.attachToTarget", "params": { "targetId": "T1", "flatten": true } }),
+        );
+        assert_eq!(
+            route,
+            ClientRoute::Local(json!({ "id": 5, "result": { "sessionId": "cb-tab-1" } }))
+        );
+    }
+
+    #[test]
+    fn attach_to_unknown_target_errors_locally() {
+        let mut s = RelayState::new();
+        let route = s.route_client_command(
+            1,
+            &json!({ "id": 6, "method": "Target.attachToTarget", "params": { "targetId": "nope" } }),
+        );
+        match route {
+            ClientRoute::Local(v) => assert!(v.get("error").is_some()),
+            _ => panic!("should answer locally"),
+        }
+    }
+
+    #[test]
+    fn other_commands_forward_under_global_id() {
+        let mut s = RelayState::new();
+        let route = s.route_client_command(
+            42,
+            &json!({ "id": 9, "method": "Page.navigate", "params": { "url": "https://x" }, "sessionId": "cb-tab-1" }),
+        );
+        match route {
+            ClientRoute::Forward(v) => {
+                assert_eq!(v["method"], "forwardCDPCommand");
+                // id is re-keyed to a relay-global id (not the client's 9).
+                assert_eq!(v["id"], 1);
+                assert_eq!(v["params"]["method"], "Page.navigate");
+                assert_eq!(v["params"]["sessionId"], "cb-tab-1");
+                assert_eq!(v["params"]["params"]["url"], "https://x");
+            }
+            _ => panic!("Page.navigate must forward"),
+        }
+    }
+
+    #[test]
+    fn reply_routes_back_to_the_issuing_client_with_original_id() {
+        let mut s = RelayState::new();
+        // Two clients each send a command that happens to share original id 1.
+        let r1 = s.route_client_command(100, &json!({ "id": 1, "method": "Page.navigate", "params": {} }));
+        let r2 = s.route_client_command(200, &json!({ "id": 1, "method": "Page.reload", "params": {} }));
+        let g1 = match r1 {
+            ClientRoute::Forward(v) => v["id"].as_i64().unwrap(),
+            _ => panic!(),
+        };
+        let g2 = match r2 {
+            ClientRoute::Forward(v) => v["id"].as_i64().unwrap(),
+            _ => panic!(),
+        };
+        assert_ne!(g1, g2, "global ids must be distinct across clients");
+
+        // Extension replies for g2 → must go to client 200 with original id 1.
+        let out = s.handle_ext_message(&json!({ "id": g2, "result": { "ok": true } }), "tok");
+        assert_eq!(
+            out,
+            vec![RelayOut::ToClient {
+                to: Some(200),
+                msg: json!({ "id": 1, "result": { "ok": true } })
+            }]
+        );
+        // And g1 → client 100.
+        let out = s.handle_ext_message(&json!({ "id": g1, "result": { "ok": false } }), "tok");
+        assert_eq!(
+            out,
+            vec![RelayOut::ToClient {
+                to: Some(100),
+                msg: json!({ "id": 1, "result": { "ok": false } })
+            }]
+        );
+    }
+
+    #[test]
+    fn forward_command_error_is_wrapped_and_routed() {
+        let mut s = RelayState::new();
+        let r = s.route_client_command(5, &json!({ "id": 3, "method": "Page.navigate", "params": {} }));
+        let gid = match r {
+            ClientRoute::Forward(v) => v["id"].as_i64().unwrap(),
+            _ => panic!(),
+        };
+        let out = s.handle_ext_message(&json!({ "id": gid, "error": "boom" }), "tok");
+        match &out[0] {
+            RelayOut::ToClient { to, msg } => {
+                assert_eq!(*to, Some(5));
+                assert_eq!(msg["id"], 3);
+                assert_eq!(msg["error"]["message"], "boom");
+            }
+            _ => panic!("expected ToClient"),
+        }
+    }
+
+    #[test]
+    fn regular_event_broadcasts_with_session() {
+        let mut s = RelayState::new();
+        let ev = json!({
+            "method": "forwardCDPEvent",
+            "params": { "sessionId": "cb-tab-1", "method": "Page.loadEventFired", "params": { "timestamp": 1.0 } }
+        });
+        let out = s.handle_ext_message(&ev, "tok");
+        assert_eq!(
+            out,
+            vec![RelayOut::ToClient {
+                to: None,
+                msg: json!({
+                    "method": "Page.loadEventFired",
+                    "params": { "timestamp": 1.0 },
+                    "sessionId": "cb-tab-1"
+                })
+            }]
+        );
+    }
+
+    #[test]
+    fn drop_client_clears_its_pending() {
+        let mut s = RelayState::new();
+        let r = s.route_client_command(9, &json!({ "id": 1, "method": "Page.navigate", "params": {} }));
+        let gid = match r {
+            ClientRoute::Forward(v) => v["id"].as_i64().unwrap(),
+            _ => panic!(),
+        };
+        s.drop_client(9);
+        // Reply now has no mapping → broadcast fallback (to: None), echoed id.
+        let out = s.handle_ext_message(&json!({ "id": gid, "result": {} }), "tok");
+        match &out[0] {
+            RelayOut::ToClient { to, .. } => assert_eq!(*to, None),
+            _ => panic!(),
+        }
+    }
+
+    #[test]
+    fn connect_handshake_validates_token() {
+        let mut s = RelayState::new();
+        let req = json!({ "type": "req", "id": "c1", "method": "connect", "params": { "auth": { "token": "good" } } });
+        let ok = s.handle_ext_message(&req, "good");
+        assert_eq!(ok, vec![RelayOut::ToExt(json!({ "type": "res", "id": "c1", "ok": true }))]);
+
+        let bad = s.handle_ext_message(&req, "different");
+        match &bad[0] {
+            RelayOut::ToExt(v) => {
+                assert_eq!(v["ok"], false);
+                assert!(v.get("error").is_some());
+            }
+            _ => panic!("expected ToExt"),
+        }
+    }
+}

cli/src/native/snapshot.rs

@@ -6,6 +6,7 @@ use super::cdp::client::CdpClient;
 use super::cdp::types::{
     AXNode, AXProperty, AXValue, EvaluateParams, EvaluateResult, GetFullAXTreeResult,
 };
+use super::adaptive::ElementFingerprint;
 use super::element::{resolve_ax_session, RefMap};
 
 const INTERACTIVE_ROLES: &[&str] = &[
@@ -148,6 +149,122 @@ impl TreeNode {
     }
 }
 
+/// Build an AX fingerprint for a tree node, used by adaptive @ref relocation.
+/// Pulls only data already in the AX tree (no extra CDP calls): role as `tag`,
+/// accessible name as `text`, a few discriminating AX properties as `attrs`, and
+/// the ancestor/parent/sibling structure from the tree links.
+fn build_ax_fingerprint(tree_nodes: &[TreeNode], idx: usize) -> ElementFingerprint {
+    let node = &tree_nodes[idx];
+
+    let mut attrs = std::collections::BTreeMap::new();
+    if let Some(v) = &node.value_text {
+        if !v.is_empty() {
+            attrs.insert("value".to_string(), v.clone());
+        }
+    }
+    if let Some(u) = &node.url {
+        if !u.is_empty() {
+            attrs.insert("url".to_string(), u.clone());
+        }
+    }
+    if let Some(l) = node.level {
+        attrs.insert("level".to_string(), l.to_string());
+    }
+    if let Some(c) = &node.checked {
+        attrs.insert("checked".to_string(), c.clone());
+    }
+
+    // Ancestor roles, nearest first, capped to keep the signature stable.
+    let mut ancestors = Vec::new();
+    let mut cur = node.parent_idx;
+    while let Some(pidx) = cur {
+        if ancestors.len() >= 6 {
+            break;
+        }
+        let role = tree_nodes[pidx].role.clone();
+        if !role.is_empty() {
+            ancestors.push(role);
+        }
+        cur = tree_nodes[pidx].parent_idx;
+    }
+
+    let (parent_tag, parent_text) = node
+        .parent_idx
+        .map(|pidx| (tree_nodes[pidx].role.clone(), tree_nodes[pidx].name.clone()))
+        .unwrap_or_default();
+
+    // Position among same-role siblings under the same parent.
+    let (sibling_index, sibling_count) = match node.parent_idx {
+        Some(pidx) => {
+            let mut count = 0u32;
+            let mut index = 0u32;
+            for &child in &tree_nodes[pidx].children {
+                if tree_nodes[child].role == node.role {
+                    if child == idx {
+                        index = count;
+                    }
+                    count += 1;
+                }
+            }
+            (index, count)
+        }
+        None => (0, 0),
+    };
+
+    ElementFingerprint {
+        tag: node.role.clone(),
+        text: node.name.clone(),
+        attrs,
+        ancestors,
+        parent_tag,
+        parent_text,
+        sibling_index,
+        sibling_count,
+    }
+}
+
+/// Collect AX fingerprints for every node that has a backend node id, used as the
+/// candidate set when relocating a stale @ref. Reuses the same extraction as the
+/// baseline so the two are scored in the same space.
+fn collect_fingerprints(tree_nodes: &[TreeNode]) -> Vec<(i64, ElementFingerprint)> {
+    tree_nodes
+        .iter()
+        .enumerate()
+        .filter_map(|(idx, n)| {
+            n.backend_node_id
+                .map(|bid| (bid, build_ax_fingerprint(tree_nodes, idx)))
+        })
+        .collect()
+}
+
+/// Fetch a fresh AX tree for the given frame and return `(backend_node_id,
+/// fingerprint)` for every node — the candidate set for adaptive @ref
+/// relocation. One `getFullAXTree` call, no per-element work.
+pub(super) async fn collect_current_fingerprints(
+    client: &CdpClient,
+    session_id: &str,
+    frame_id: Option<&str>,
+    iframe_sessions: &HashMap<String, String>,
+) -> Result<Vec<(i64, ElementFingerprint)>, String> {
+    let (ax_params, effective_session_id) =
+        resolve_ax_session(frame_id, session_id, iframe_sessions);
+    let _ = client
+        .send_command_no_params("DOM.enable", Some(effective_session_id))
+        .await;
+    let _ = client
+        .send_command_no_params("Accessibility.enable", Some(effective_session_id))
+        .await;
+    let ax_tree: GetFullAXTreeResult = client
+        .send_command_typed(
+            "Accessibility.getFullAXTree",
+            &ax_params,
+            Some(effective_session_id),
+        )
+        .await?;
+    let (tree_nodes, _roots) = build_tree(&ax_tree.nodes);
+    Ok(collect_fingerprints(&tree_nodes))
+}
+
 /// The type of a hidden form input found inside a cursor-interactive element.
 #[derive(Clone, Copy)]
 enum HiddenInputKind {
@@ -397,6 +514,7 @@ pub async fn take_snapshot(
             actual_nth,
             frame_id,
         );
+        ref_map.set_fingerprint(&ref_id, build_ax_fingerprint(&tree_nodes, *idx));
 
         tree_nodes[*idx].has_ref = true;
         tree_nodes[*idx].ref_id = Some(ref_id);

cli/src/native/state.rs

@@ -119,6 +119,8 @@ async fn collect_storage_via_temp_target(
             "Target.createTarget",
             &CreateTargetParams {
                 url: "about:blank".to_string(),
+                // Transient internal target (storage collection) — never grouped.
+                agent_group: None,
             },
             None,
         )

cli/src/native/stealth.rs

@@ -51,13 +51,18 @@ pub fn build_stealth_script(mode: StealthMode, locale: Option<&str>) -> String {
         vec![locale, base_lang]
     };
     let config_line = format!(
-        r#"const __abStealth = {{ locale: "{}", languages: {}, allowWebGLContextFallback: false }};"#,
+        r#"const __abStealth = {{ locale: "{}", languages: {}, allowWebGLContextFallback: false, hideCanvas: {}, canvasSeed: {} }};"#,
         locale,
         serde_json::to_string(&languages).unwrap_or_else(|_| r#"["en-US","en"]"#.to_string()),
+        hide_canvas_enabled(),
+        canvas_noise_seed(),
     );
 
+    // NB: this prefix MUST match the first line of stealth_scripts.js verbatim,
+    // otherwise the fallback below prepends a SECOND `const __abStealth`
+    // declaration and the whole script dies with a redeclaration SyntaxError.
     if let Some(rest) = STEALTH_SCRIPTS_RAW.strip_prefix(
-        r#"const __abStealth = { locale: "en-US", languages: ["en-US", "en"], allowWebGLContextFallback: false };"#,
+        r#"const __abStealth = { locale: "en-US", languages: ["en-US", "en"], allowWebGLContextFallback: false, hideCanvas: false, canvasSeed: 0 };"#,
     ) {
         format!("{}{}", config_line, rest)
     } else {
@@ -65,6 +70,35 @@ pub fn build_stealth_script(mode: StealthMode, locale: Option<&str>) -> String {
     }
 }
 
+/// Whether canvas/audio fingerprint noise is opted into (FullLaunch only).
+/// OFF by default: injecting noise is a deliberate "lie" that can itself be a
+/// tell, so it's reserved for users who explicitly want it via
+/// `AGENT_BROWSER_HIDE_CANVAS=1`.
+fn hide_canvas_enabled() -> bool {
+    std::env::var("AGENT_BROWSER_HIDE_CANVAS")
+        .ok()
+        .map(|v| v == "1" || v.eq_ignore_ascii_case("true"))
+        .unwrap_or(false)
+}
+
+/// A per-process seed so canvas/audio noise is STABLE within a session (a real
+/// device returns the same hash on repeated reads) but differs from the
+/// headless-stable default. 0 is avoided so the JS can treat it as "unset".
+fn canvas_noise_seed() -> u32 {
+    use std::sync::OnceLock;
+    static SEED: OnceLock<u32> = OnceLock::new();
+    *SEED.get_or_init(|| {
+        use std::time::{SystemTime, UNIX_EPOCH};
+        let nanos = SystemTime::now()
+            .duration_since(UNIX_EPOCH)
+            .map(|d| d.subsec_nanos())
+            .unwrap_or(0x9e3779b9);
+        // mix the bits a little, then force non-zero
+        let mixed = nanos ^ nanos.rotate_left(13).wrapping_mul(2654435761);
+        mixed | 1
+    })
+}
+
 /// Apply stealth patches to a browser session.
 ///
 /// In `CdpAttach` mode (user's real Chrome): only removes `navigator.webdriver`.
@@ -118,11 +152,74 @@ pub async fn apply_stealth(
                     .await?;
             }
         }
+
+        // Align the timezone for fresh launches when explicitly requested.
+        // Headless/launched Chrome often reports UTC (or the host's zone), which
+        // can contradict a proxy's geolocation or a spoofed locale.
+        // `Emulation.setTimezoneOverride` is a NATIVE override — Intl.DateTimeFormat
+        // and Date both follow it with no detectable JS lie. Opt-in only:
+        //   AGENT_BROWSER_TIMEZONE=<IANA id>  -> use that zone (e.g. align to proxy)
+        //   AGENT_BROWSER_TIMEZONE=auto       -> derive a default from the locale
+        //   (unset)                           -> leave the real timezone untouched
+        if let Some(tz) = resolve_timezone(locale) {
+            let _ = client
+                .send_command(
+                    "Emulation.setTimezoneOverride",
+                    Some(json!({ "timezoneId": tz })),
+                    Some(session_id),
+                )
+                .await;
+        }
     }
 
     Ok(())
 }
 
+/// Resolve the timezone to emulate for a fresh-launch session, if any.
+/// Controlled by `AGENT_BROWSER_TIMEZONE`: an explicit IANA id, or `auto` to
+/// derive a sensible default from the locale. Returns `None` (leave the real
+/// timezone) when unset, empty, or when `auto` can't map the locale.
+fn resolve_timezone(locale: Option<&str>) -> Option<String> {
+    let raw = std::env::var("AGENT_BROWSER_TIMEZONE").ok()?;
+    let raw = raw.trim();
+    if raw.is_empty() {
+        return None;
+    }
+    if raw.eq_ignore_ascii_case("auto") {
+        return locale
+            .and_then(locale_default_timezone)
+            .map(str::to_string);
+    }
+    Some(raw.to_string())
+}
+
+/// Best-effort IANA timezone for a locale. Used only for
+/// `AGENT_BROWSER_TIMEZONE=auto`; unknown locales return `None` so the real
+/// timezone is left untouched rather than guessing a wrong one.
+fn locale_default_timezone(locale: &str) -> Option<&'static str> {
+    let tz = match locale.to_ascii_lowercase().as_str() {
+        "en-us" => "America/New_York",
+        "en-ca" => "America/Toronto",
+        "en-gb" => "Europe/London",
+        "en-au" => "Australia/Sydney",
+        "ja" | "ja-jp" => "Asia/Tokyo",
+        "ko" | "ko-kr" => "Asia/Seoul",
+        "zh-cn" | "zh-hans" | "zh-hans-cn" => "Asia/Shanghai",
+        "zh-tw" | "zh-hant" | "zh-hant-tw" => "Asia/Taipei",
+        "zh-hk" => "Asia/Hong_Kong",
+        "de" | "de-de" => "Europe/Berlin",
+        "fr" | "fr-fr" => "Europe/Paris",
+        "es" | "es-es" => "Europe/Madrid",
+        "it" | "it-it" => "Europe/Rome",
+        "nl" | "nl-nl" => "Europe/Amsterdam",
+        "pt-br" => "America/Sao_Paulo",
+        "pt" | "pt-pt" => "Europe/Lisbon",
+        "ru" | "ru-ru" => "Europe/Moscow",
+        _ => return None,
+    };
+    Some(tz)
+}
+
 /// Get the browser's User-Agent string via CDP.
 async fn get_browser_user_agent(client: &CdpClient, session_id: &str) -> Option<String> {
     let result = client
@@ -235,3 +332,43 @@ fn build_ua_metadata(ua: &str, locale: Option<&str>) -> serde_json::Value {
         "wow64": false,
     })
 }
+
+#[cfg(test)]
+mod timezone_tests {
+    use super::{locale_default_timezone, resolve_timezone};
+
+    #[test]
+    fn maps_common_locales_case_insensitively() {
+        assert_eq!(locale_default_timezone("en-US"), Some("America/New_York"));
+        assert_eq!(locale_default_timezone("ja-JP"), Some("Asia/Tokyo"));
+        assert_eq!(locale_default_timezone("zh-CN"), Some("Asia/Shanghai"));
+        assert_eq!(locale_default_timezone("ZH-TW"), Some("Asia/Taipei"));
+        assert_eq!(locale_default_timezone("ja"), Some("Asia/Tokyo"));
+    }
+
+    #[test]
+    fn unknown_locale_returns_none() {
+        assert_eq!(locale_default_timezone("xx-YY"), None);
+        assert_eq!(locale_default_timezone(""), None);
+    }
+
+    #[test]
+    fn resolve_timezone_honors_env() {
+        // Serialized via a single test to avoid cross-test env races on this key.
+        std::env::remove_var("AGENT_BROWSER_TIMEZONE");
+        assert_eq!(resolve_timezone(Some("en-US")), None);
+
+        std::env::set_var("AGENT_BROWSER_TIMEZONE", "Europe/Berlin");
+        assert_eq!(resolve_timezone(None), Some("Europe/Berlin".to_string()));
+
+        std::env::set_var("AGENT_BROWSER_TIMEZONE", "  ");
+        assert_eq!(resolve_timezone(Some("en-US")), None);
+
+        std::env::set_var("AGENT_BROWSER_TIMEZONE", "auto");
+        assert_eq!(resolve_timezone(Some("ja-JP")), Some("Asia/Tokyo".to_string()));
+        assert_eq!(resolve_timezone(Some("xx-YY")), None);
+        assert_eq!(resolve_timezone(None), None);
+
+        std::env::remove_var("AGENT_BROWSER_TIMEZONE");
+    }
+}

cli/src/native/stealth_scripts.js

@@ -1,4 +1,4 @@
-const __abStealth = { locale: "en-US", languages: ["en-US", "en"], allowWebGLContextFallback: false };
+const __abStealth = { locale: "en-US", languages: ["en-US", "en"], allowWebGLContextFallback: false, hideCanvas: false, canvasSeed: 0 };
 (function(){
   // Prefer the CDP-level automation override (Emulation.setAutomationOverride),
   // which makes navigator.webdriver report `false` NATIVELY — undetectable by
@@ -1275,3 +1275,126 @@ const __abStealth = { locale: "en-US", languages: ["en-US", "en"], allowWebGLCon
     }
   }
 })();
+// Canvas + audio fingerprint noise (OPT-IN, full-launch only).
+// Headless Chrome produces a stable canvas/audio hash that trackers use as a
+// device id. When __abStealth.hideCanvas is on we perturb readback APIs with a
+// SESSION-STABLE, sub-perceptual amount of noise: repeated reads on this page
+// return the same noised result (a real device is consistent too), but the
+// hash differs from the headless default. Off by default — noise is itself a
+// "lie", so it's reserved for users who explicitly enable it.
+(function(){
+  if (!__abStealth || __abStealth.hideCanvas !== true) return;
+
+  // Deterministic PRNG keyed by the per-session seed plus a position, so the
+  // same pixel/sample is perturbed identically every read within the session.
+  const baseSeed = (__abStealth.canvasSeed >>> 0) || 0x9e3779b9;
+  const noiseAt = (n) => {
+    let t = (baseSeed ^ Math.imul(n | 0, 0x6d2b79f5)) >>> 0;
+    t = Math.imul(t ^ (t >>> 15), t | 1) >>> 0;
+    t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+
+  // Make a wrapped function masquerade as the native one (toString + name).
+  const mask = (wrapped, native) => {
+    try {
+      Object.defineProperty(wrapped, 'name', {
+        value: native.name,
+        configurable: true,
+      });
+      Object.defineProperty(wrapped, 'toString', {
+        value: () => native.toString(),
+        configurable: true,
+        writable: true,
+      });
+    } catch {}
+    return wrapped;
+  };
+
+  // ---- Canvas 2D readback ---------------------------------------------------
+  const perturbImageData = (imageData) => {
+    const data = imageData && imageData.data;
+    if (!data || !data.length) return imageData;
+    for (let i = 0; i < data.length; i += 4) {
+      // Touch ~5% of pixels by +/-1 on each RGB channel; leave alpha alone.
+      if (noiseAt(i) < 0.05) {
+        const delta = noiseAt(i + 1) < 0.5 ? -1 : 1;
+        data[i] = Math.max(0, Math.min(255, data[i] + delta));
+        data[i + 1] = Math.max(0, Math.min(255, data[i + 1] + delta));
+        data[i + 2] = Math.max(0, Math.min(255, data[i + 2] + delta));
+      }
+    }
+    return imageData;
+  };
+
+  try {
+    const ctxProto = (typeof CanvasRenderingContext2D !== 'undefined')
+      ? CanvasRenderingContext2D.prototype : null;
+    if (ctxProto && typeof ctxProto.getImageData === 'function') {
+      const nativeGetImageData = ctxProto.getImageData;
+      ctxProto.getImageData = mask(function(...args) {
+        return perturbImageData(nativeGetImageData.apply(this, args));
+      }, nativeGetImageData);
+    }
+  } catch {}
+
+  // For toDataURL/toBlob, draw the (already-rendered) canvas onto a scratch
+  // canvas, perturb its pixels, then encode that — so the export hash shifts
+  // without disturbing what the page sees on screen.
+  const exportNoised = (canvas) => {
+    try {
+      const w = canvas.width, h = canvas.height;
+      if (!w || !h) return null;
+      const scratch = document.createElement('canvas');
+      scratch.width = w; scratch.height = h;
+      const sctx = scratch.getContext('2d');
+      if (!sctx) return null;
+      sctx.drawImage(canvas, 0, 0);
+      const img = sctx.getImageData(0, 0, w, h);
+      perturbImageData(img);
+      sctx.putImageData(img, 0, 0);
+      return scratch;
+    } catch { return null; }
+  };
+
+  try {
+    const canvasProto = (typeof HTMLCanvasElement !== 'undefined')
+      ? HTMLCanvasElement.prototype : null;
+    if (canvasProto && typeof canvasProto.toDataURL === 'function') {
+      const nativeToDataURL = canvasProto.toDataURL;
+      canvasProto.toDataURL = mask(function(...args) {
+        const scratch = exportNoised(this);
+        return nativeToDataURL.apply(scratch || this, args);
+      }, nativeToDataURL);
+    }
+    if (canvasProto && typeof canvasProto.toBlob === 'function') {
+      const nativeToBlob = canvasProto.toBlob;
+      canvasProto.toBlob = mask(function(cb, ...rest) {
+        const scratch = exportNoised(this);
+        return nativeToBlob.call(scratch || this, cb, ...rest);
+      }, nativeToBlob);
+    }
+  } catch {}
+
+  // ---- AudioBuffer readback -------------------------------------------------
+  // Perturb time-domain samples by a tiny, seed-stable amount so the audio
+  // fingerprint (sum/hash of channel data) shifts without audible effect.
+  try {
+    const audioProto = (typeof AudioBuffer !== 'undefined') ? AudioBuffer.prototype : null;
+    if (audioProto && typeof audioProto.getChannelData === 'function') {
+      const nativeGetChannelData = audioProto.getChannelData;
+      const seen = new WeakSet();
+      audioProto.getChannelData = mask(function(...args) {
+        const channel = nativeGetChannelData.apply(this, args);
+        // Only perturb once per buffer to keep reads consistent.
+        if (channel && !seen.has(channel)) {
+          seen.add(channel);
+          for (let i = 0; i < channel.length; i += 100) {
+            channel[i] = channel[i] + (noiseAt(i) - 0.5) * 1e-7;
+          }
+        }
+        return channel;
+      }, nativeGetChannelData);
+    }
+  } catch {}
+})();

cli/src/upgrade.rs

@@ -1,284 +1,70 @@
 use crate::color;
-use std::path::Path;
-use std::process::{exit, Command, Stdio};
+use std::process::{exit, Command};
 
 const CURRENT_VERSION: &str = env!("CARGO_PKG_VERSION");
-const NPM_REGISTRY_URL: &str = "https://registry.npmjs.org/agent-browser/latest";
 
-enum InstallMethod {
-    Npm,
-    Pnpm,
-    Yarn,
-    Bun,
-    Homebrew,
-    Cargo,
-    Unknown,
-}
-
-async fn fetch_latest_version() -> Result<String, String> {
-    let resp = reqwest::get(NPM_REGISTRY_URL)
-        .await
-        .map_err(|e| format!("Failed to fetch version info: {}", e))?;
-
-    let body: serde_json::Value = resp
-        .json()
-        .await
-        .map_err(|e| format!("Failed to parse version info: {}", e))?;
-
-    body.get("version")
-        .and_then(|v| v.as_str())
-        .map(|s| s.to_string())
-        .ok_or_else(|| "No version field in registry response".to_string())
-}
-
-/// Parse the `.install-method` marker written by postinstall.js.
-fn read_install_method_marker(exe_dir: &Path) -> Option<InstallMethod> {
-    let contents = std::fs::read_to_string(exe_dir.join(".install-method")).ok()?;
-    match contents.trim() {
-        "npm" => Some(InstallMethod::Npm),
-        "pnpm" => Some(InstallMethod::Pnpm),
-        "yarn" => Some(InstallMethod::Yarn),
-        "bun" => Some(InstallMethod::Bun),
-        _ => None,
-    }
-}
-
-fn detect_install_method() -> InstallMethod {
-    if let Ok(exe) = std::env::current_exe() {
-        // Resolve symlinks to find the real binary location
-        let real_path = exe.canonicalize().unwrap_or(exe);
-
-        // Preferred: read the marker file written at install time
-        if let Some(dir) = real_path.parent() {
-            if let Some(method) = read_install_method_marker(dir) {
-                return method;
-            }
-        }
-
-        // Fallback: infer from executable path
-        let path_str = real_path.to_string_lossy();
-
-        if path_str.contains("/.cargo/bin/") || path_str.contains("\\.cargo\\bin\\") {
-            return InstallMethod::Cargo;
-        }
-
-        if path_str.contains("/Cellar/agent-browser/")
-            || path_str.contains("/homebrew/")
-            || path_str.contains("/linuxbrew/")
-        {
-            return InstallMethod::Homebrew;
-        }
-
-        if path_str.contains("/pnpm/") || path_str.contains("/pnpm-global/") {
-            return InstallMethod::Pnpm;
-        }
-
-        if path_str.contains("/.yarn/") || path_str.contains("/yarn/global/") {
-            return InstallMethod::Yarn;
-        }
-
-        if path_str.contains("/.bun/") {
-            return InstallMethod::Bun;
-        }
-
-        if path_str.contains("node_modules/agent-browser")
-            || path_str.contains("node_modules\\agent-browser")
-        {
-            return InstallMethod::Npm;
-        }
-    }
-
-    // Last resort: probe package managers via subprocess
-
-    #[cfg(any(target_os = "macos", target_os = "linux"))]
-    {
-        if command_succeeds("brew", &["list", "agent-browser"]) {
-            return InstallMethod::Homebrew;
-        }
-    }
-
-    if command_output_contains(
-        "pnpm",
-        &["list", "-g", "agent-browser", "--depth=0"],
-        "agent-browser",
-    ) {
-        return InstallMethod::Pnpm;
-    }
-
-    if command_output_contains("yarn", &["global", "list", "--depth=0"], "agent-browser") {
-        return InstallMethod::Yarn;
-    }
-
-    if command_output_contains("bun", &["pm", "ls", "-g"], "agent-browser") {
-        return InstallMethod::Bun;
-    }
-
-    if command_succeeds("npm", &["list", "-g", "agent-browser", "--depth=0"]) {
-        return InstallMethod::Npm;
-    }
-
-    InstallMethod::Unknown
-}
-
-fn command_succeeds(cmd: &str, args: &[&str]) -> bool {
-    Command::new(cmd)
-        .args(args)
-        .stdout(Stdio::null())
-        .stderr(Stdio::null())
-        .status()
-        .map(|s| s.success())
-        .unwrap_or(false)
-}
-
-fn command_output_contains(cmd: &str, args: &[&str], needle: &str) -> bool {
-    Command::new(cmd)
-        .args(args)
-        .stderr(Stdio::null())
-        .output()
-        .map(|o| o.status.success() && String::from_utf8_lossy(&o.stdout).contains(needle))
-        .unwrap_or(false)
-}
-
-fn run_upgrade_command(method: &InstallMethod) -> bool {
-    let (cmd, args, display): (&str, &[&str], &str) = match method {
-        InstallMethod::Npm => (
-            "npm",
-            &["install", "-g", "agent-browser@latest"],
-            "npm install -g agent-browser@latest",
-        ),
-        InstallMethod::Pnpm => (
-            "pnpm",
-            &["add", "-g", "agent-browser@latest"],
-            "pnpm add -g agent-browser@latest",
-        ),
-        // NOTE: `yarn global` is Yarn Classic (v1) only; Yarn Berry (v2+) removed it.
-        // Users on Yarn v2+ won't reach this path — detection falls through to Unknown.
-        InstallMethod::Yarn => (
-            "yarn",
-            &["global", "add", "agent-browser@latest"],
-            "yarn global add agent-browser@latest",
-        ),
-        InstallMethod::Bun => (
-            "bun",
-            &["install", "-g", "agent-browser@latest"],
-            "bun install -g agent-browser@latest",
-        ),
-        InstallMethod::Homebrew => (
-            "brew",
-            &["upgrade", "agent-browser"],
-            "brew upgrade agent-browser",
-        ),
-        InstallMethod::Cargo => (
-            "cargo",
-            &["install", "agent-browser", "--force"],
-            "cargo install agent-browser --force",
-        ),
-        InstallMethod::Unknown => return false,
-    };
-
-    println!("Running: {}", display);
-    Command::new(cmd)
-        .args(args)
-        .status()
-        .map(|s| s.success())
-        .unwrap_or(false)
-}
+/// Canonical installer for the stealth fork. `upgrade` just re-runs it, so the
+/// upgrade path and the install path are identical (GitHub Release, no npm).
+const INSTALL_URL: &str =
+    "https://raw.githubusercontent.com/leeguooooo/agent-browser-stealth/main/install.sh";
 
+/// Upgrade to the latest GitHub Release.
+///
+/// The stealth fork ships as a prebuilt binary attached to a GitHub Release —
+/// NOT via the npm registry. Earlier this command (inherited from upstream)
+/// ran `npm/pnpm install -g agent-browser@latest`, which installed the
+/// UNRELATED upstream `agent-browser` package and clobbered the user's setup.
+/// Now `upgrade` simply re-runs install.sh into the same directory as the
+/// current binary, so it always tracks the freshest GitHub Release.
 pub fn run_upgrade() {
-    let current = CURRENT_VERSION;
+    println!(
+        "{}",
+        color::cyan(&format!(
+            "Upgrading agent-browser-stealth (currently v{}) from the latest GitHub Release...",
+            CURRENT_VERSION
+        ))
+    );
 
-    let rt = tokio::runtime::Builder::new_current_thread()
-        .enable_all()
-        .build()
-        .unwrap_or_else(|e| {
-            eprintln!(
-                "{} Failed to create runtime: {}",
-                color::error_indicator(),
-                e
-            );
-            exit(1);
-        });
-
-    let latest = match rt.block_on(fetch_latest_version()) {
-        Ok(v) => v,
-        Err(e) => {
-            eprintln!(
-                "{} Could not check latest version: {}",
-                color::warning_indicator(),
-                e
-            );
-            String::new()
-        }
-    };
-
-    if !latest.is_empty() && current == latest.as_str() {
-        println!(
-            "{} agent-browser is already at the latest version (v{})",
-            color::success_indicator(),
-            current
-        );
-        return;
-    }
-
-    let method = detect_install_method();
-
-    let method_name = match &method {
-        InstallMethod::Npm => "npm",
-        InstallMethod::Pnpm => "pnpm",
-        InstallMethod::Yarn => "yarn",
-        InstallMethod::Bun => "bun",
-        InstallMethod::Homebrew => "Homebrew",
-        InstallMethod::Cargo => "Cargo",
-        InstallMethod::Unknown => "",
-    };
-
-    if matches!(method, InstallMethod::Unknown) {
+    #[cfg(windows)]
+    {
         eprintln!(
-            "{} Could not detect installation method.",
-            color::error_indicator()
+            "{} Automatic upgrade isn't supported on Windows.",
+            color::warning_indicator()
         );
-        eprintln!("  To update manually, run one of:");
-        eprintln!("    npm install -g agent-browser@latest       # npm");
-        eprintln!("    pnpm add -g agent-browser@latest          # pnpm");
-        eprintln!("    yarn global add agent-browser@latest       # yarn");
-        eprintln!("    bun install -g agent-browser@latest        # bun");
-        eprintln!("    brew upgrade agent-browser                 # Homebrew");
-        eprintln!("    cargo install agent-browser --force        # Cargo");
+        eprintln!("  Download the latest agent-browser-win32-x64.tar.gz from:");
+        eprintln!("    https://github.com/leeguooooo/agent-browser-stealth/releases/latest");
+        eprintln!("  and replace agent-browser.exe on your PATH.");
         exit(1);
     }
 
-    println!("Detected installation via {}.", method_name);
+    #[cfg(not(windows))]
+    {
+        // Install into the SAME directory as the running binary (in-place
+        // upgrade), so we don't create a second copy elsewhere on PATH.
+        let bin_dir = std::env::current_exe()
+            .ok()
+            .and_then(|p| p.canonicalize().ok())
+            .and_then(|p| p.parent().map(|d| d.to_path_buf()));
 
-    if !latest.is_empty() {
-        println!(
-            "{}",
-            color::cyan(&format!(
-                "Upgrading agent-browser... v{} → v{}",
-                current, latest
-            ))
-        );
-    } else {
-        println!(
-            "{}",
-            color::cyan(&format!("Upgrading agent-browser (v{})...", current))
-        );
-    }
+        let install_cmd = format!("curl -fsSL {} | sh", INSTALL_URL);
+        println!("Running: {}", install_cmd);
 
-    let success = run_upgrade_command(&method);
+        let mut cmd = Command::new("sh");
+        cmd.arg("-c").arg(&install_cmd);
+        if let Some(ref dir) = bin_dir {
+            cmd.env("AGENT_BROWSER_BIN_DIR", dir);
+        }
 
-    if success {
-        if !latest.is_empty() {
+        let ok = cmd.status().map(|s| s.success()).unwrap_or(false);
+        if ok {
             println!(
-                "{} Done! v{} → v{}",
-                color::success_indicator(),
-                current,
-                latest
+                "{} Upgrade complete — run `agent-browser-stealth --version` to confirm.",
+                color::success_indicator()
             );
         } else {
-            println!("{} Done!", color::success_indicator());
+            eprintln!("{} Upgrade failed. Install manually:", color::error_indicator());
+            eprintln!("  curl -fsSL {} | sh", INSTALL_URL);
+            exit(1);
         }
-    } else {
-        eprintln!("{} Upgrade failed.", color::error_indicator());
-        exit(1);
     }
 }

extensions/ab-connect/NOTICE.md

@@ -0,0 +1,11 @@
+# Attribution
+
+The chrome.debugger attach + CDP Target handling in `background.js` is adapted
+from **openclaw-browser-relay** by chengyixu
+(https://github.com/chengyixu/openclaw-browser-relay, MIT per its README).
+
+Changes for agent-browser-stealth: rebranded to "agent-browser connect"; the
+transport is rewritten from a localhost WebSocket + shared token to Chrome
+**native messaging** (host `com.agent_browser.connect`) — no port, no token,
+Chrome authenticates the extension to the host by id. WebSocket/token/options
+code removed.

extensions/ab-connect/background.js

@@ -0,0 +1,365 @@
+// agent-browser connect — MV3 service worker.
+//
+// Bridges the user's real Chrome tabs to the local agent-browser daemon over a
+// Chrome **native messaging** channel (no localhost port, no token: Chrome
+// authenticates this extension to the host by id). It attaches chrome.debugger
+// to eligible tabs and relays CDP both ways via a tiny envelope:
+//   host → ext : {id, method:"forwardCDPCommand", params:{method,params,sessionId}}
+//   ext → host : {id, result|error}                      (command reply)
+//   ext → host : {method:"forwardCDPEvent", params:{sessionId,method,params}}
+//
+// Target/discovery semantics (getTargets/attachToTarget) are emulated on the
+// daemon side; here we just attach tabs and announce them as
+// Target.attachedToTarget so the daemon's CDP client sees them appear.
+//
+// Adapted from openclaw-browser-relay (MIT, chengyixu) — the chrome.debugger
+// attach + Target handling; the transport is rewritten from WebSocket+token to
+// native messaging.
+
+const HOST_NAME = 'com.agent_browser.connect'
+const SKIP_URL = /^(chrome|chrome-extension|devtools|chrome-untrusted|edge|about):/i
+
+/** @type {chrome.runtime.Port|null} */
+let port = null
+let nextSession = 1
+/** tabId -> { sessionId, targetId } */
+const tabs = new Map()
+/** sessionId -> tabId (main session per tab) */
+const sessionToTab = new Map()
+/** child (OOPIF/worker) sessionId -> tabId */
+const childSessionToTab = new Map()
+/** tab-group name -> chrome tabGroups id (best-effort cache) */
+const groupIdByName = new Map()
+
+// Deterministic color per group name so a given session keeps the same color.
+const GROUP_COLORS = ['blue', 'cyan', 'green', 'yellow', 'orange', 'red', 'pink', 'purple', 'grey']
+function colorForName(name) {
+  let h = 0
+  for (let i = 0; i < name.length; i++) h = (h * 31 + name.charCodeAt(i)) >>> 0
+  return GROUP_COLORS[h % GROUP_COLORS.length]
+}
+
+// Put a freshly-created tab into the agent/session's own Chrome tab group, so
+// each agent's tabs are visually separated (from each other and from the user's
+// own tabs) on the shared real browser. Best-effort: grouping failures never
+// break tab creation.
+async function groupTabInto(tabId, name) {
+  if (!name || !chrome.tabGroups || !chrome.tabs.group) return
+  const tab = await chrome.tabs.get(tabId).catch(() => null)
+  if (!tab) return
+  let gid = groupIdByName.get(name)
+  if (gid != null) {
+    const ok = await chrome.tabGroups.get(gid).then(() => true).catch(() => false)
+    if (!ok) {
+      gid = null
+      groupIdByName.delete(name)
+    }
+  }
+  if (gid == null) {
+    // Reuse a same-titled group already in this window (survives SW restarts).
+    const found = await chrome.tabGroups.query({ windowId: tab.windowId, title: name }).catch(() => [])
+    if (found && found[0]) gid = found[0].id
+  }
+  if (gid == null) {
+    gid = await chrome.tabs.group({ tabIds: tabId })
+    await chrome.tabGroups.update(gid, { title: name, color: colorForName(name) }).catch(() => {})
+  } else {
+    await chrome.tabs.group({ groupId: gid, tabIds: tabId }).catch(() => {})
+  }
+  groupIdByName.set(name, gid)
+}
+
+function postToHost(msg) {
+  try {
+    if (port) port.postMessage(msg)
+  } catch (e) {
+    // port died; onDisconnect will reconnect.
+  }
+}
+
+function setBadge(tabId, kind) {
+  const map = { on: '', connecting: '…', error: '!' }
+  const colors = { on: '#16a34a', connecting: '#d97706', error: '#b91c1c' }
+  try {
+    chrome.action.setBadgeText({ tabId, text: map[kind] ?? '' })
+    if (colors[kind]) chrome.action.setBadgeBackgroundColor({ tabId, color: colors[kind] })
+  } catch {}
+}
+
+// ---- native messaging transport ------------------------------------------
+
+function connectHost() {
+  if (port) return
+  try {
+    port = chrome.runtime.connectNative(HOST_NAME)
+  } catch (e) {
+    port = null
+    return
+  }
+  port.onMessage.addListener((msg) => void whenReady(() => onHostMessage(msg)))
+  port.onDisconnect.addListener(() => {
+    port = null
+    // Sessions are stale once the host is gone; the daemon re-discovers on
+    // reconnect. Keep chrome.debugger attached so reconnect is cheap.
+    for (const tabId of tabs.keys()) setBadge(tabId, 'connecting')
+  })
+  // Tell the daemon about everything we already have attached, then attach
+  // anything new.
+  reannounceAttachedTabs()
+  void attachAllTabs()
+}
+
+async function onHostMessage(msg) {
+  if (!msg || typeof msg !== 'object') return
+  // Optional keepalive.
+  if (msg.method === 'ping') {
+    postToHost({ method: 'pong' })
+    return
+  }
+  // Daemon (re)connected — (re)attach and announce every tab so it discovers
+  // the user's existing tabs rather than racing an empty target list.
+  if (msg.method === 'attachAll') {
+    reannounceAttachedTabs()
+    await attachAllTabs()
+    return
+  }
+  if (typeof msg.id !== 'undefined' && msg.method === 'forwardCDPCommand') {
+    try {
+      const result = await handleForwardCdpCommand(msg)
+      postToHost({ id: msg.id, result })
+    } catch (err) {
+      postToHost({ id: msg.id, error: err instanceof Error ? err.message : String(err) })
+    }
+  }
+}
+
+// ---- CDP command dispatch -------------------------------------------------
+
+function tabForSession(sessionId) {
+  return sessionToTab.get(sessionId) ?? childSessionToTab.get(sessionId) ?? null
+}
+
+function tabForTarget(targetId) {
+  for (const [tabId, t] of tabs.entries()) if (t.targetId === targetId) return tabId
+  return null
+}
+
+function anyConnectedTab() {
+  const it = tabs.keys().next()
+  return it.done ? null : it.value
+}
+
+async function handleForwardCdpCommand(msg) {
+  const method = String(msg?.params?.method || '')
+  const params = msg?.params?.params || undefined
+  const sessionId = typeof msg?.params?.sessionId === 'string' ? msg.params.sessionId : undefined
+
+  // Browser-level Target methods that map onto chrome.tabs.
+  if (method === 'Target.createTarget') {
+    const url = typeof params?.url === 'string' && params.url ? params.url : 'about:blank'
+    const tab = await chrome.tabs.create({ url, active: false })
+    if (!tab.id) throw new Error('createTarget: no tab id')
+    await new Promise((r) => setTimeout(r, 100))
+    const t = await attachTab(tab.id)
+    // Per-session tab grouping (non-CDP hint from the daemon). Best-effort.
+    const group = typeof params?.agentGroup === 'string' ? params.agentGroup.trim() : ''
+    if (group) {
+      try {
+        await groupTabInto(tab.id, group)
+      } catch {}
+    }
+    return { targetId: t.targetId }
+  }
+  if (method === 'Target.closeTarget') {
+    const tid = typeof params?.targetId === 'string' ? params.targetId : ''
+    const tabId = tid ? tabForTarget(tid) : null
+    if (!tabId) return { success: false }
+    try {
+      await chrome.tabs.remove(tabId)
+    } catch {
+      return { success: false }
+    }
+    return { success: true }
+  }
+  if (method === 'Target.activateTarget') {
+    const tid = typeof params?.targetId === 'string' ? params.targetId : ''
+    const tabId = tid ? tabForTarget(tid) : null
+    if (tabId) {
+      const tab = await chrome.tabs.get(tabId).catch(() => null)
+      if (tab?.windowId) await chrome.windows.update(tab.windowId, { focused: true }).catch(() => {})
+      await chrome.tabs.update(tabId, { active: true }).catch(() => {})
+    }
+    return {}
+  }
+
+  // Everything else → chrome.debugger on the resolved tab.
+  const tabId =
+    (sessionId ? tabForSession(sessionId) : null) ??
+    (typeof params?.targetId === 'string' ? tabForTarget(params.targetId) : null) ??
+    anyConnectedTab()
+  if (!tabId) throw new Error(`no attached tab for ${method}`)
+  const dbg = { tabId }
+
+  // Re-enabling Runtime can leave a stale state; bounce it (matches upstream).
+  if (method === 'Runtime.enable') {
+    try {
+      await chrome.debugger.sendCommand(dbg, 'Runtime.disable')
+      await new Promise((r) => setTimeout(r, 30))
+    } catch {}
+    return await chrome.debugger.sendCommand(dbg, 'Runtime.enable', params)
+  }
+  return await chrome.debugger.sendCommand(dbg, method, params)
+}
+
+// ---- attach / detach ------------------------------------------------------
+
+async function attachTab(tabId) {
+  const existing = tabs.get(tabId)
+  if (existing) return existing
+  const dbg = { tabId }
+  try {
+    await chrome.debugger.attach(dbg, '1.3')
+  } catch (e) {
+    // After a service-worker restart, chrome.debugger may still be bound to
+    // this tab from the previous instance — "Another debugger is already
+    // attached". The tab is still controllable via {tabId}, so don't skip it
+    // (skipping is why existing tabs went un-announced and the daemon opened a
+    // blank tab instead). Re-announce it. Any other error (restricted page) is
+    // surfaced and the caller skips this tab.
+    const msg = String((e && e.message) || e)
+    if (!/already attached|already being debugged/i.test(msg)) throw e
+  }
+  await chrome.debugger.sendCommand(dbg, 'Page.enable').catch(() => {})
+  const info = /** @type {any} */ (await chrome.debugger.sendCommand(dbg, 'Target.getTargetInfo'))
+  const targetInfo = info?.targetInfo
+  const targetId = String(targetInfo?.targetId || '')
+  if (!targetId) throw new Error('attachTab: no targetId')
+  const sessionId = `cb-tab-${nextSession++}`
+  const entry = { sessionId, targetId }
+  tabs.set(tabId, entry)
+  sessionToTab.set(sessionId, tabId)
+  setBadge(tabId, port ? 'on' : 'connecting')
+  postToHost({
+    method: 'forwardCDPEvent',
+    params: {
+      sessionId,
+      method: 'Target.attachedToTarget',
+      params: { sessionId, targetInfo: { ...targetInfo, attached: true } },
+    },
+  })
+  return entry
+}
+
+function detachTab(tabId, notify) {
+  const entry = tabs.get(tabId)
+  if (!entry) return
+  tabs.delete(tabId)
+  sessionToTab.delete(entry.sessionId)
+  for (const [sid, tid] of childSessionToTab.entries()) if (tid === tabId) childSessionToTab.delete(sid)
+  if (notify) {
+    postToHost({
+      method: 'forwardCDPEvent',
+      params: { sessionId: entry.sessionId, method: 'Target.detachedFromTarget', params: { sessionId: entry.sessionId } },
+    })
+  }
+}
+
+function eligible(tab) {
+  return !!tab && !!tab.id && typeof tab.url === 'string' && !SKIP_URL.test(tab.url)
+}
+
+async function attachAllTabs() {
+  let all = []
+  try {
+    all = await chrome.tabs.query({})
+  } catch {
+    return
+  }
+  for (const tab of all) {
+    if (eligible(tab) && !tabs.has(tab.id)) {
+      try {
+        await attachTab(tab.id)
+      } catch {
+        // Tab may be a restricted page or already attached elsewhere.
+      }
+    }
+  }
+}
+
+function reannounceAttachedTabs() {
+  for (const [, entry] of tabs.entries()) {
+    postToHost({
+      method: 'forwardCDPEvent',
+      params: {
+        sessionId: entry.sessionId,
+        method: 'Target.attachedToTarget',
+        params: { sessionId: entry.sessionId, targetInfo: { targetId: entry.targetId, type: 'page', attached: true } },
+      },
+    })
+  }
+}
+
+// ---- chrome.debugger events ----------------------------------------------
+
+chrome.debugger.onEvent.addListener((source, method, params) =>
+  void whenReady(() => {
+    const tabId = source.tabId
+    if (!tabId) return
+    const entry = tabs.get(tabId)
+    if (!entry) return
+    if (method === 'Target.attachedToTarget' && params?.sessionId) {
+      childSessionToTab.set(String(params.sessionId), tabId)
+    }
+    if (method === 'Target.detachedFromTarget' && params?.sessionId) {
+      childSessionToTab.delete(String(params.sessionId))
+    }
+    postToHost({
+      method: 'forwardCDPEvent',
+      params: { sessionId: source.sessionId || entry.sessionId, method, params },
+    })
+  }),
+)
+
+chrome.debugger.onDetach.addListener((source) =>
+  void whenReady(() => {
+    if (source.tabId) detachTab(source.tabId, true)
+  }),
+)
+
+// ---- tab lifecycle --------------------------------------------------------
+
+chrome.tabs.onUpdated.addListener((tabId, changeInfo, tab) =>
+  void whenReady(async () => {
+    if (changeInfo.status === 'complete' && eligible(tab) && !tabs.has(tabId) && port) {
+      try {
+        await attachTab(tabId)
+      } catch {}
+    }
+  }),
+)
+chrome.tabs.onRemoved.addListener((tabId) => void whenReady(() => detachTab(tabId, true)))
+
+// ---- bootstrap + keepalive ------------------------------------------------
+
+chrome.runtime.onInstalled.addListener(() => void whenReady(connectHost))
+chrome.runtime.onStartup.addListener(() => void whenReady(connectHost))
+chrome.action.onClicked.addListener(() => void whenReady(connectHost))
+
+// MV3 service workers get suspended; an alarm wakes us to keep the host link
+// and badges fresh.
+chrome.alarms.create('keepalive', { periodInMinutes: 0.4 })
+chrome.alarms.onAlarm.addListener((a) => {
+  if (a.name !== 'keepalive') return
+  void whenReady(() => {
+    if (!port) connectHost()
+    else void attachAllTabs()
+  })
+})
+
+// Gate placeholder so future async state-rehydration can hook in.
+async function whenReady(fn) {
+  return fn()
+}
+
+// Kick a connection attempt as soon as the worker starts.
+connectHost()

extensions/ab-connect/manifest.json

@@ -0,0 +1,29 @@
+{
+  "manifest_version": 3,
+  "name": "agent-browser connect",
+  "version": "0.4.0",
+  "description": "Let agent-browser drive your logged-in Chrome — install once, no token, no per-use confirmation.",
+  "key": "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA6vQIyscGIPYPZdSpPwPL0+0gxUROyRgCpmvCSDoc8XUm4qm97VbKnD9Ijc1lV22lNWZtE78gaRjt6BeSfuMgnBymnhLKjN1gU6AI5QUU0mrJyeHdWKvrKQR5FmsM2A7Xr1ykE2SiiS8zNUS3Y/6O5l+Nva7wrVy6E4a2dkBVQkOsu+DV+nEZvhIyuDY5D5SPXqNwUTWTaglwj5mjvHz36xSwCWlPmrtJ+ED0AUyrb2z4GIOmvk4kqtBVrh/UD058klLo4CkYOnIybB5aV6WYuwarfPY4bF/dLggPem+ewLNTUNBuwrxj/A4nUv0LJTuRO8rR7f8WR9qnRCY0Ic5saQIDAQAB",
+  "icons": {
+    "16": "icons/icon16.png",
+    "32": "icons/icon32.png",
+    "48": "icons/icon48.png",
+    "128": "icons/icon128.png"
+  },
+  "permissions": [
+    "debugger",
+    "tabs",
+    "tabGroups",
+    "nativeMessaging",
+    "storage",
+    "alarms",
+    "webNavigation"
+  ],
+  "background": {
+    "service_worker": "background.js",
+    "type": "module"
+  },
+  "action": {
+    "default_title": "agent-browser connect"
+  }
+}

extensions/store/SUBMISSION.html

@@ -0,0 +1,131 @@
+<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>Chrome Web Store 提交指南 — agent-browser connect</title>
+<style>
+  :root{--fg:#1a1a1a;--muted:#5c5c5c;--accent:#2563eb;--warn:#b45309;--ok:#15803d;--border:#e2e2e2;--bg:#fff;--code:#f5f5f7}
+  *{box-sizing:border-box}
+  body{font-family:-apple-system,BlinkMacSystemFont,"PingFang SC","Microsoft YaHei",sans-serif;color:var(--fg);background:var(--bg);max-width:880px;margin:0 auto;padding:48px 24px;line-height:1.65}
+  header{border-bottom:2px solid var(--fg);padding-bottom:16px;margin-bottom:24px}
+  h1{font-size:1.7rem;margin:0 0 4px}
+  .sub{color:var(--muted)}
+  h2{font-size:1.2rem;margin:34px 0 10px;border-left:3px solid var(--accent);padding-left:10px}
+  h3{font-size:1rem;margin:20px 0 6px}
+  code{background:var(--code);padding:1px 5px;border-radius:4px;font-size:.88em}
+  pre{background:var(--code);border:1px solid var(--border);border-radius:8px;padding:12px 14px;overflow:auto;font-size:.86rem;white-space:pre-wrap}
+  table{border-collapse:collapse;width:100%;margin:12px 0;font-size:.92rem}
+  th,td{border:1px solid var(--border);padding:8px 10px;text-align:left;vertical-align:top}
+  th{background:var(--code)}
+  ol li,ul li{margin:6px 0}
+  .warn{background:#fffbeb;border:1px solid #fde68a;border-left:4px solid var(--warn);padding:12px 14px;border-radius:6px;margin:16px 0}
+  .ok{background:#f0fdf4;border:1px solid #bbf7d0;border-left:4px solid var(--ok);padding:12px 14px;border-radius:6px;margin:16px 0}
+  .field{font-weight:600;color:var(--accent)}
+  footer{margin-top:40px;padding-top:16px;border-top:1px solid var(--border);color:var(--muted);font-size:.85rem}
+</style>
+</head>
+<body>
+<header>
+  <h1>Chrome Web Store 提交指南</h1>
+  <div class="sub">agent-browser connect · 上传包 <code>extensions/ab-connect.zip</code> · id 锁定为 <code>ciiljdlhdpfckdcfkphgmfalanpdejep</code></div>
+</header>
+
+<p>为什么必须走商店:实测 Chrome 149 在<strong>非企业托管</strong>的 Mac 上,会把"非 Web Store"的 force-install 扩展直接标成 <code>[BLOCKED]</code>。商店扩展不受此限。这也是 codex / claude 扩展都发商店的原因。</p>
+
+<div class="warn">
+  <strong>评审风险(务必知道):</strong> 本扩展用了 <code>debugger</code> 权限,这是 Chrome Web Store 审核最严的权限之一。理由必须写清楚"只在用户本机、用户主动发指令时驱动用户自己的标签页,无远程服务器"。类似工具(如 claude-in-chrome)能过审,但可能被多问一轮、审核时间偏长(几天到一两周)。
+</div>
+
+<h2>一、前置(你来做,一次性)</h2>
+<ol>
+  <li>用一个 Google 账号登录 <code>https://chrome.google.com/webstore/devconsole</code></li>
+  <li>首次需付 <strong>$5</strong> 一次性开发者注册费</li>
+  <li>(隐私政策需要一个公开 URL,见第四节 —— 我可以帮你开 GitHub Pages 托管 <code>privacy.html</code>)</li>
+</ol>
+
+<h2>二、上传</h2>
+<ol>
+  <li>devconsole → <span class="field">New item</span> → 上传 <code>extensions/ab-connect.zip</code></li>
+  <li>上传后确认分配到的 Item ID = <code>ciiljdlhdpfckdcfkphgmfalanpdejep</code>(因为 manifest 里保留了 <code>key</code>,id 会被锁成这个,native messaging 的 allowed_origins 才对得上)。<strong>若 id 不是这个,告诉我,我重签。</strong></li>
+</ol>
+
+<h2>三、商店信息(直接复制以下文案)</h2>
+
+<h3>名称 / Name</h3>
+<pre>agent-browser connect</pre>
+
+<h3>简介 / Summary（≤132 字符）</h3>
+<pre>Let your own agent-browser CLI drive your logged-in Chrome — a local automation bridge. No remote server, no token.</pre>
+
+<h3>详细描述 / Description</h3>
+<pre>agent-browser connect is the in-browser half of the open-source agent-browser CLI. It lets the
+command-line tool you installed on this same computer automate the Chrome you're already logged
+into — opening pages, clicking, filling forms, reading the DOM — driven entirely by you.
+
+How it works
+- The extension talks ONLY to the local agent-browser CLI over Chrome native messaging (a local
+  inter-process channel — no network socket, no token, no remote server).
+- When you run an automation command, the extension relays Chrome DevTools Protocol operations to
+  the tab you target, then returns the result to the CLI.
+
+Privacy
+- No analytics, no trackers, no data collection.
+- Nothing is sent to any remote server. The only message peer is the local CLI.
+- Source is open (Apache-2.0): https://github.com/leeguooooo/agent-browser-stealth
+
+You need the agent-browser CLI installed and paired (run: agent-browser extension install) for this
+extension to do anything.</pre>
+
+<h3>类别 / Category</h3>
+<pre>Developer Tools</pre>
+
+<h3>语言 / Language</h3>
+<pre>English</pre>
+
+<h2>四、隐私实践（Privacy practices 标签页 —— 必填）</h2>
+
+<h3>Single purpose（单一用途）</h3>
+<pre>Bridge the user's locally-installed agent-browser CLI to their own logged-in Chrome so the CLI can
+automate pages the user is working with, entirely on the user's machine and at the user's command.</pre>
+
+<h3>各权限理由 / Permission justifications</h3>
+<table>
+  <tr><th>权限</th><th>理由（复制到对应输入框）</th></tr>
+  <tr><td class="field">debugger</td><td>Attaches the Chrome DevTools Protocol to the user's own active tab so the paired local agent-browser CLI can automate it (navigate, click, read DOM) only while the user is running a command. Commands arrive solely from the local CLI via native messaging; there is no remote endpoint.</td></tr>
+  <tr><td class="field">tabs</td><td>Enumerate and target the correct open tab to attach automation to.</td></tr>
+  <tr><td class="field">nativeMessaging</td><td>The sole communication channel: a local native-messaging connection to the agent-browser CLI installed on the same machine. No network is used.</td></tr>
+  <tr><td class="field">storage</td><td>Persist small local pairing/configuration state for the extension.</td></tr>
+  <tr><td class="field">alarms</td><td>Keep the MV3 service worker alive during longer automation sessions.</td></tr>
+  <tr><td class="field">webNavigation</td><td>Detect page loads/navigations so automation can wait for the right moment before acting.</td></tr>
+  <tr><td class="field">host permissions（若被问）</td><td>The extension declares none; tab access is mediated through the debugger attach the user initiates.</td></tr>
+</table>
+
+<h3>数据用途勾选 / Data usage</h3>
+<ul>
+  <li>不勾选任何"collects user data"类别。</li>
+  <li>三个合规声明全部勾选可以为真:不卖数据 / 不挪作无关用途 / 不用于判断信用资质。</li>
+  <li><span class="field">Privacy policy URL</span>:填 <code>privacy.html</code> 的公开地址(见下)。</li>
+</ul>
+
+<h2>五、隐私政策 URL</h2>
+<p>商店要求一个公开可访问的隐私政策地址。GitHub Pages <strong>已开启</strong>,直接填这个(渲染好看):</p>
+<pre>https://leeguooooo.github.io/agent-browser-stealth/extensions/store/privacy.html</pre>
+<p>(部署需 1–2 分钟生效。raw 备用直链:<code>https://raw.githubusercontent.com/leeguooooo/agent-browser-stealth/main/extensions/store/privacy.html</code>。)</p>
+
+<h2>六、截图 / Screenshots（至少 1 张，1280×800 或 640×400）</h2>
+<p>可以截一张 CLI + Chrome 并排的演示图。<em>需要的话我用 cua-driver 截一张合规尺寸的图给你。</em></p>
+
+<h2>七、提交后</h2>
+<ol>
+  <li>提交审核 → 等几天。审核通过且状态变 <em>Published</em> 后告诉我。</li>
+  <li>我会把 <code>extension install</code> 的 force-install <code>update_url</code> 切到商店地址并发布新 fork;之后用户 <code>extension install</code> → 批准一次描述文件 → 静默装好(商店扩展不再 <code>[BLOCKED]</code>);或者用户在商店页一键 <span class="field">Add to Chrome</span>。</li>
+</ol>
+
+<div class="ok">
+  <strong>今天的临时可用方案:</strong> 在你这台 Mac 上 <code>chrome://extensions</code> → 打开开发者模式 → Load unpacked → 选 <code>extensions/ab-connect</code>,30 秒手动装一次,native messaging + <code>extension connect</code> 立即可用。等商店过审再切静默路径。
+</div>
+
+<footer>agent-browser-stealth · 提交包与文案随扩展版本更新;改扩展后重跑 <code>scripts/pack-extension.sh</code> 并重打 <code>ab-connect.zip</code>。</footer>
+</body>
+</html>

extensions/store/privacy.html

@@ -0,0 +1,77 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>Privacy Policy — agent-browser connect</title>
+<style>
+  :root{
+    --fg:#1a1a1a; --muted:#5c5c5c; --accent:#2563eb; --border:#e2e2e2; --bg:#fff; --code:#f5f5f5;
+  }
+  *{box-sizing:border-box}
+  body{font-family:-apple-system,BlinkMacSystemFont,"PingFang SC","Microsoft YaHei",sans-serif;
+    color:var(--fg);background:var(--bg);max-width:820px;margin:0 auto;padding:48px 24px;line-height:1.65}
+  header{border-bottom:2px solid var(--fg);padding-bottom:16px;margin-bottom:28px}
+  h1{font-size:1.7rem;margin:0 0 4px}
+  .sub{color:var(--muted);font-size:.95rem}
+  h2{font-size:1.15rem;margin:32px 0 8px;border-left:3px solid var(--accent);padding-left:10px}
+  code{background:var(--code);padding:1px 5px;border-radius:4px;font-size:.88em}
+  table{border-collapse:collapse;width:100%;margin:12px 0;font-size:.92rem}
+  th,td{border:1px solid var(--border);padding:8px 10px;text-align:left;vertical-align:top}
+  th{background:var(--code)}
+  .key{font-weight:600;color:var(--accent)}
+  footer{margin-top:40px;padding-top:16px;border-top:1px solid var(--border);color:var(--muted);font-size:.85rem}
+  strong{color:var(--fg)}
+</style>
+</head>
+<body>
+<header>
+  <h1>Privacy Policy — agent-browser connect</h1>
+  <div class="sub">Chrome extension (id <code>ciiljdlhdpfckdcfkphgmfalanpdejep</code>) · Last updated 2026-06-09</div>
+</header>
+
+<p><strong>Summary: this extension collects no personal data, contains no analytics or
+trackers, and sends nothing to any remote server.</strong> It is a local bridge that lets the
+user's own <code>agent-browser</code> command-line tool, running on the same computer, drive the
+user's logged-in Chrome.</p>
+
+<h2>What the extension does</h2>
+<p>agent-browser connect pairs Chrome with the locally-installed <code>agent-browser</code> CLI over
+Chrome <em>native messaging</em> (a local inter-process channel; no network socket, no token). When
+the user issues an automation command in the CLI, the extension relays Chrome DevTools Protocol
+operations to the tab the user targets. Everything happens on the user's machine, initiated by the
+user.</p>
+
+<h2>Data collection &amp; use</h2>
+<table>
+  <tr><th>Category</th><th>Collected?</th><th>Detail</th></tr>
+  <tr><td class="key">Personally identifiable information</td><td>No</td><td>Never read, stored, or transmitted.</td></tr>
+  <tr><td class="key">Browsing history</td><td>No</td><td>Not collected. Page content is acted on transiently only while the user is running an automation command, and is never stored or sent off-device.</td></tr>
+  <tr><td class="key">Authentication / cookies / credentials</td><td>No</td><td>Not read or exported by the extension.</td></tr>
+  <tr><td class="key">Analytics / telemetry</td><td>No</td><td>The extension contains no analytics, tracking, or crash-reporting code.</td></tr>
+  <tr><td class="key">Remote transmission</td><td>No</td><td>The extension's only message peer is the local <code>agent-browser</code> CLI via native messaging. It makes no outbound network requests of its own.</td></tr>
+</table>
+
+<h2>Permissions &amp; why they are needed</h2>
+<table>
+  <tr><th>Permission</th><th>Purpose</th></tr>
+  <tr><td class="key">debugger</td><td>Attach the Chrome DevTools Protocol to the user's own tab so the local CLI can automate it, only while the user is actively running a command.</td></tr>
+  <tr><td class="key">tabs</td><td>Enumerate and target the correct open tab to automate.</td></tr>
+  <tr><td class="key">nativeMessaging</td><td>The local transport to the paired <code>agent-browser</code> CLI — the extension's sole communication channel.</td></tr>
+  <tr><td class="key">storage</td><td>Persist small local pairing/state values.</td></tr>
+  <tr><td class="key">alarms</td><td>Keep the MV3 service worker alive during longer automation sessions.</td></tr>
+  <tr><td class="key">webNavigation</td><td>Detect page loads so automation can wait for the right moment.</td></tr>
+</table>
+
+<h2>Data sharing</h2>
+<p>None. No data is sold, shared, or transferred to third parties. There are no third parties — the
+extension talks only to a program the user installed on the same computer.</p>
+
+<h2>Contact</h2>
+<p>Source code, issues, and contact: <code>https://github.com/leeguooooo/agent-browser-stealth</code></p>
+
+<footer>
+  agent-browser connect is open source (Apache-2.0). This policy applies to the extension only.
+</footer>
+</body>
+</html>

extensions/store/shot.html

@@ -0,0 +1,45 @@
+<!DOCTYPE html>
+<html lang="en"><head><meta charset="UTF-8">
+<style>
+  html,body{margin:0;width:1280px;height:800px;overflow:hidden;
+    font-family:-apple-system,BlinkMacSystemFont,"SF Pro Text",sans-serif;
+    background:linear-gradient(135deg,#0f172a 0%,#1e293b 100%);color:#e2e8f0}
+  .wrap{display:flex;flex-direction:column;height:100%;padding:56px 64px;box-sizing:border-box}
+  h1{font-size:46px;margin:0 0 6px;font-weight:700;letter-spacing:-.5px;color:#fff}
+  .tag{font-size:21px;color:#94a3b8;margin:0 0 32px;font-weight:400}
+  .accent{color:#38bdf8}
+  .term{background:#0b1220;border:1px solid #334155;border-radius:14px;
+    box-shadow:0 24px 60px rgba(0,0,0,.45);overflow:hidden;flex:1;display:flex;flex-direction:column}
+  .bar{background:#1e293b;padding:13px 18px;display:flex;gap:9px;align-items:center;border-bottom:1px solid #334155}
+  .dot{width:13px;height:13px;border-radius:50%}
+  .r{background:#ff5f56}.y{background:#ffbd2e}.g{background:#27c93f}
+  .bartitle{color:#64748b;font-size:14px;margin-left:12px;font-family:ui-monospace,monospace}
+  pre{margin:0;padding:26px 30px;font-family:ui-monospace,"SF Mono",Menlo,monospace;
+    font-size:19.5px;line-height:1.72;flex:1}
+  .p{color:#38bdf8}.c{color:#f1f5f9;font-weight:600}.o{color:#94a3b8}.ok{color:#4ade80}.dim{color:#475569}
+  .foot{display:flex;gap:40px;margin-top:30px;font-size:18px;color:#cbd5e1}
+  .foot b{color:#fff}
+  .pill{display:inline-block;background:#0c4a6e;color:#7dd3fc;font-size:15px;padding:4px 13px;
+    border-radius:999px;margin-left:14px;vertical-align:middle;font-weight:600}
+</style></head>
+<body><div class="wrap">
+  <h1>agent-browser&nbsp;connect <span class="pill">local · no token · no remote</span></h1>
+  <p class="tag">Let your own <span class="accent">agent-browser</span> CLI drive the Chrome you're already logged into.</p>
+  <div class="term">
+    <div class="bar"><span class="dot r"></span><span class="dot y"></span><span class="dot g"></span><span class="bartitle">zsh — agent-browser</span></div>
+<pre><span class="p">$</span> <span class="c">agent-browser extension install</span>
+<span class="ok">✓</span> <span class="o">native-messaging host installed (com.agent_browser.connect)</span>
+<span class="ok">✓</span> <span class="o">extension ready — add it from the Chrome Web Store</span>
+
+<span class="p">$</span> <span class="c">agent-browser open</span> <span class="o">"https://mail.google.com"</span>   <span class="dim"># your logged-in tab</span>
+<span class="p">$</span> <span class="c">agent-browser snapshot -i</span>                    <span class="dim"># read the page</span>
+<span class="p">$</span> <span class="c">agent-browser click</span> <span class="o">@e42</span>                      <span class="dim"># act on it</span>
+<span class="ok">✓</span> <span class="o">driving your real session — no re-login, no confirmation</span>
+</pre>
+  </div>
+  <div class="foot">
+    <span>🔌 <b>Native messaging</b> — local only</span>
+    <span>🧩 <b>chrome.debugger</b> — on your command</span>
+    <span>🔓 <b>Open source</b> · Apache-2.0</span>
+  </div>
+</div></body></html>

install.sh

@@ -95,10 +95,14 @@ fi
 mkdir -p "$bindir"
 
 mv "$tmp/${BIN_NAME}" "$bindir/${BIN_NAME}"
-# convenience aliases: `abs` (short) -> agent-browser
-ln -sf "$bindir/${BIN_NAME}" "$bindir/abs" 2>/dev/null || true
+# Aliases pointing at the same binary: `abs` (short) and `agent-browser-stealth`
+# (the fork's package name). All three names work, and an upgrade refreshes
+# whichever name you actually run.
+for alias_name in abs agent-browser-stealth; do
+  ln -sf "$bindir/${BIN_NAME}" "$bindir/${alias_name}" 2>/dev/null || true
+done
 
-info "installed ${BIN_NAME} -> ${bindir}/${BIN_NAME}"
+info "installed -> ${bindir}/ (agent-browser, agent-browser-stealth, abs)"
 "$bindir/${BIN_NAME}" --version 2>/dev/null || true
 
 case ":$PATH:" in

package.json

@@ -1,7 +1,7 @@
 {
   "name": "agent-browser-stealth",
-  "version": "0.27.0-fork.13",
-  "description": "Browser automation CLI for AI agents — stealth fork with anti-detection",
+  "version": "0.27.0-fork.21",
+  "description": "Browser automation CLI for AI agents \u2014 stealth fork with anti-detection",
   "type": "module",
   "packageManager": "pnpm@11.1.3",
   "files": [

scripts/pack-extension.sh

@@ -0,0 +1,39 @@
+#!/bin/sh
+# Build the Chrome Web Store upload package extensions/ab-connect.zip (and a signed
+# extensions/ab-connect.crx for reference) from extensions/ab-connect, keeping the
+# extension id constant via the stable signing key + manifest "key".
+#
+# The id MUST stay ciiljdlhdpfckdcfkphgmfalanpdejep so the native-messaging
+# allowed_origins and the force-install policy keep matching. The id is pinned by
+# the "key" field in manifest.json (kept in the uploaded zip on purpose).
+#
+# The private key lives at .secrets/ab-connect.pem and is git-ignored.
+#
+# After changing the extension:
+#   1. bump "version" in extensions/ab-connect/manifest.json
+#   2. run this script
+#   3. commit extensions/ab-connect.zip (+ .crx) + manifest.json
+#   4. upload ab-connect.zip to the Web Store (see extensions/store/SUBMISSION.html)
+set -e
+cd "$(dirname "$0")/.."
+KEY=.secrets/ab-connect.pem
+EXT=extensions/ab-connect
+CHROME="${CHROME_BIN:-/Applications/Google Chrome.app/Contents/MacOS/Google Chrome}"
+
+# Web Store upload package (zip of the unpacked extension, dotfiles excluded).
+rm -f extensions/ab-connect.zip
+( cd "$EXT" && zip -rq ../ab-connect.zip . -x '.*' )
+[ -f extensions/ab-connect.zip ] || { echo "error: zip failed" >&2; exit 1; }
+
+# Signed crx (reference / non-store force-install for managed setups).
+if [ -f "$KEY" ]; then
+  rm -f extensions/ab-connect.crx
+  "$CHROME" --pack-extension="$PWD/$EXT" --pack-extension-key="$PWD/$KEY" >/dev/null 2>&1 || true
+  ID=$(openssl rsa -in "$KEY" -pubout -outform DER 2>/dev/null \
+       | openssl dgst -sha256 -binary | xxd -p -c256 | head -c32 | tr '0-9a-f' 'a-p')
+  echo "extension id: $ID"
+else
+  echo "note: $KEY missing — built zip only (no crx)."
+fi
+echo "packed extensions/ab-connect.zip"
+echo "manifest version: $(grep -o '"version"[^,]*' "$EXT/manifest.json" | head -1)"

skill-data/core/SKILL.md

@@ -29,6 +29,57 @@ Refs (`@e1`, `@e2`, ...) are assigned fresh on every snapshot. They become
 submits, dynamic re-renders, dialog opens. Always re-snapshot before your
 next ref interaction.
 
+## Before you automate: pick the cheapest tool
+
+Driving a browser is the heavy option. agent-browser earns its keep when you
+need a **real, logged-in browser** — not for reading text off a public page.
+
+| You need | Use |
+|---|---|
+| Discover what exists / find sources | `WebSearch` |
+| Specific facts from a static or public page | `WebFetch` or `curl` (no browser) |
+| Login state, interaction, JS-rendered or anti-bot pages | **agent-browser** (this skill) |
+| A page the user saved before / an internal system | `agent-browser find-url <keywords>` (their bookmarks), then open it |
+| The user's **own already-open, logged-in** Chrome window | the **extension connect** flow (below) |
+
+Don't hand-build deep URLs with query params — links discovered by *interacting*
+with the site carry the right hidden context and dodge anti-bot checks; a
+hand-constructed URL often doesn't.
+
+### Driving the user's real, already-open Chrome (extension)
+
+When the task needs the user's *live* logged-in window (their real session, the
+window they're looking at — not a fresh browser), use the extension connect flow:
+`agent-browser extension install` once, load `extensions/ab-connect` in
+`chrome://extensions` once (a GUI step you can perform with a **computer-use /
+GUI-automation tool** like the `cua-driver` skill — see
+`references/commands.md` → "Drive your real, logged-in Chrome"), then
+`agent-browser extension connect`. After that it's zero-confirmation, zero-token
+CLI. Use `--launch` instead when a fresh, isolated browser is fine.
+
+## Two ways to drive a page — and when to drop to `eval`
+
+You have a **real Chrome with the user's DOM**. Two layers, mix them freely:
+
+1. **Structured** (`snapshot` + `@ref`, `find`, typed actions) — convenient and
+   readable; best for straightforward forms and navigation. But the a11y view is
+   *lossy and fragile*: refs go stale on any change, hidden inputs never show up,
+   overlays can block coordinate clicks.
+2. **eval-first** (`agent-browser eval "<js>"`) — your eyes and hands on the real
+   DOM: read hidden inputs, reach into Shadow DOM / iframes, inspect
+   `form.elements` and `.validity`, extract the exact shape you want, or call
+   `el.click()` directly. **The moment the structured path fights you, drop to
+   `eval` instead of retrying it** — it's the fast way to find *why* something
+   failed (e.g. a hidden `point_choice=none` the UI never exposes).
+
+```bash
+# "what's actually in this form / why won't it submit?"
+agent-browser eval "[...document.forms[0].elements].map(e=>[e.name,e.type,e.value,e.checked])"
+agent-browser eval "document.querySelector('[name=point_choice]')?.value"
+agent-browser eval "[...document.forms[0].elements].filter(e=>!e.validity.valid).map(e=>e.name+': '+e.validationMessage)"
+agent-browser eval "document.querySelector('#stubborn').click()"   # direct DOM click, bypasses overlays
+```
+
 ## Quickstart
 
 ```bash
@@ -137,9 +188,17 @@ agent-browser fill "input[name=email]" "user@test.com"
 agent-browser click "button.primary"
 ```
 
-Rule of thumb: snapshot + `@eN` refs are fastest and most reliable for
-AI agents. `find role/text/label` is next best and doesn't require a prior
-snapshot. Raw CSS is a fallback when the others fail.
+Escalation ladder: snapshot + `@eN` refs are quickest for straightforward
+pages → `find role/text/label` when you'd rather skip the snapshot → raw CSS
+→ **`eval` the moment any of those fight you** (stale refs, hidden state,
+occluded clicks). Don't retry a flaky structured locator three times; drop to
+`eval` and act on the DOM directly.
+
+`click` auto-scrolls into view and, if the coordinate click is occluded, falls
+back to a DOM `.click()`. If a click *reports success but nothing happened* —
+classic for an autocomplete/menu `<li>` that closes on the input's blur — retry
+that one with `AGENT_BROWSER_CLICK_MODE=dom agent-browser click ...`, or just
+`agent-browser eval "<select the item via JS>"`.
 
 ## Waiting (read this)
 
@@ -209,6 +268,44 @@ AGENT_BROWSER_SESSION_NAME=my-app agent-browser open https://app.example.com
 # State is auto-saved and restored on subsequent runs with the same name.
 ```
 
+### Remember a site's quirks (site notes)
+
+A site behaves the same every time you visit it. When you work out something
+durable — a working selector, a URL pattern, a hidden field a form needs, an
+anti-bot trap, what requires login — **write it down so the next run doesn't
+re-discover it.** Keep one markdown file per domain (these are your own notes,
+not shipped with the skill):
+
+```
+~/.agent-browser/site-patterns/<domain>.md
+```
+
+**Before** working on a domain, read its file if it exists (use your normal file
+tools — this is plain markdown you own). Treat it as *hints, not guarantees* —
+sites change; verify before relying. **After** a successful session that taught
+you something durable, create or update it. Suggested shape:
+
+```markdown
+---
+domain: app.example.com
+updated: 2026-06-05
+---
+## Platform traits
+SPA; form renders ~1s after load (wait --text). Cloudflare on /login.
+
+## Working patterns
+- Address pick: the `<li>` closes on blur — select with CLICK_MODE=dom.
+- Submit needs hidden `point_choice` set (eval), the UI never exposes it.
+- Stable selector for "Continue": button[data-testid=submit]
+
+## Known traps (date them)
+- 2026-06-05: @ref to the basket button goes stale after the mini-cart opens;
+  re-snapshot or use `find role button --name "Checkout"`.
+```
+
+This is how repeat visits get fast and reliable instead of re-solving the same
+page every time.
+
 ### Extract data
 
 ```bash

skill-data/core/references/commands.md

@@ -318,15 +318,58 @@ agent-browser --version               # Show version (-V)
 agent-browser <command> --help        # Show detailed help for a command
 ```
 
+## Drive your real, logged-in Chrome (extension — zero confirmation)
+
+Chrome 136 blocked `--remote-debugging-port` on the default profile, so to drive
+the user's *existing* logged-in window, agent-browser uses a Chrome **extension**
+over native messaging — no port, no token, no per-use confirmation (the
+codex/claude approach).
+
+One-time setup:
+```bash
+agent-browser extension install        # writes the native-messaging host manifest
+```
+Then load the extension **once** — this is a GUI step (Chrome's `chrome://extensions`
+is privileged; the CLI can't load an unpacked extension):
+
+> chrome://extensions → enable **Developer mode** (top-right) → **Load unpacked** →
+> select `<repo>/extensions/ab-connect`
+
+**You can do this load step yourself with a computer-use / GUI-automation tool**
+(e.g. the `cua-driver` skill) — drive `chrome://extensions`, toggle Developer
+mode, click *Load unpacked*, pick the folder in the Open dialog. If the extension
+is already loaded, clicking its **Reload** (↻) button after a code change is
+enough. Notes from doing this live: tools that send *synthetic keystrokes* (e.g.
+peekaboo) often don't reach Chrome — **`cua-driver` works** because it reads
+Chrome's accessibility tree and clicks real elements. The native "Open" file
+dialog is the fiddly part; if keystroke entry there fails, ask the user to pick
+the folder (one click). After it loads, Chrome assigns the extension a fixed id
+(pinned in its manifest) and auto-connects the host.
+
+Then, any time (pure CLI, zero confirmation):
+```bash
+agent-browser extension connect        # auto-attaches to the live, logged-in tabs
+agent-browser tab                      # list the real tabs it now controls
+agent-browser tab t3                   # switch the session to one of them
+agent-browser snapshot -i / eval / click ...   # drive it like any session
+agent-browser extension status         # is the host installed?
+agent-browser extension uninstall      # remove the host manifest
+```
+
+Security: the extension↔host link is authenticated by Chrome (extension id); the
+host↔agent-browser CDP link uses an unguessable URL in a 0600 file. Use this when
+you need the user's real cookies/login on their actual machine. (`--extension
+<path>` is unrelated — that loads an extension into a *launched* browser.)
+
 ## Debugging
 
 ```bash
 agent-browser --headed open example.com   # Show browser window
 agent-browser --cdp 9222 snapshot         # Connect via CDP port
 agent-browser connect 9222                # Alternative: connect command
-agent-browser console                     # View console messages
+agent-browser console                     # View console messages (needs AGENT_BROWSER_CAPTURE_CONSOLE=1)
 agent-browser console --clear             # Clear console
-agent-browser errors                      # View page errors
+agent-browser errors                      # View page errors (needs AGENT_BROWSER_CAPTURE_CONSOLE=1)
 agent-browser errors --clear              # Clear errors
 agent-browser highlight @e1               # Highlight element
 agent-browser inspect                     # Open Chrome DevTools for this session
@@ -336,6 +379,41 @@ agent-browser profiler start              # Start Chrome DevTools profiling
 agent-browser profiler stop trace.json    # Stop and save profile
 ```
 
+### Finding a page the user saved (`find-url`)
+
+Search the user's local Chrome/Edge **bookmarks** by keyword — for internal
+systems or previously-saved pages that public search can't reach. Local read, no
+browser/daemon needed.
+
+```bash
+agent-browser find-url jira board          # all keywords must match (name or url)
+agent-browser find-url --limit 10 invoices
+agent-browser find-url --browser edge --profile "Profile 1" wiki
+agent-browser find-url grafana --json      # {results:[{name,url,folder}], count}
+```
+
+Results are most-recently-added first. `javascript:`/`data:` bookmarklets are
+skipped. (Visited-history search isn't included yet — bookmarks only.)
+
+### Debugging forms / hidden state with `eval`
+
+The a11y `snapshot` shows visible, interactive elements — it does **not** show
+hidden inputs or a control's actual submitted value. When a form "looks filled"
+but submit-validation rejects it, go straight to the DOM with `eval` instead of
+guessing from the snapshot. This is usually the fastest way to find the real
+problem (e.g. a hidden `point_choice=none` that the visible UI never exposes):
+
+```bash
+# Dump every field's name → value, including hidden inputs and unchecked radios
+agent-browser eval "JSON.stringify([...document.forms[0].elements].map(e=>({name:e.name,type:e.type,value:e.value,checked:e.checked})).filter(e=>e.name))"
+
+# Inspect one hidden field directly
+agent-browser eval "document.querySelector('[name=point_choice]')?.value"
+
+# Why won't it submit? Ask the browser's own validity API
+agent-browser eval "[...document.forms[0].elements].filter(e=>!e.validity?.valid).map(e=>e.name+': '+e.validationMessage)"
+```
+
 ## React / Web Vitals
 
 Requires `--enable react-devtools` at launch for the `react ...` commands.
@@ -391,4 +469,38 @@ AGENT_BROWSER_HIDE_SCROLLBARS="false"        # Keep native scrollbars visible in
 AGENT_BROWSER_PROVIDER="browserbase"         # Cloud browser provider
 AGENT_BROWSER_STREAM_PORT="9223"             # Override WebSocket streaming port (default: OS-assigned)
 AGENT_BROWSER_HOME="/path/to/agent-browser"  # Custom install location
+AGENT_BROWSER_CLICK_MODE="dom"               # Click strategy: "" (default: scroll-in + coordinate
+                                             #   click, DOM-dispatch fallback), "coord" (strict
+                                             #   coordinate only), "dom" (always element.click())
 ```
+
+### Click reliability
+
+`click` auto-scrolls the target into view first, then dispatches a coordinate
+click. If that fails (a floating layer fails the occlusion guard, or the point
+won't resolve) it falls back to a DOM-dispatched `.click()` on the intended
+element. If a click *reports success but the page didn't react* — common for
+autocomplete/menu `<li>` items that close on the input's blur — retry that one
+with `AGENT_BROWSER_CLICK_MODE=dom` (a DOM dispatch doesn't move focus the way a
+real pointer press does, so the item still selects). `=coord` disables the
+fallback when you specifically want a hard failure on occlusion.
+
+### Stealth / anti-detection knobs (fork)
+
+```bash
+AGENT_BROWSER_CAPTURE_CONSOLE="1"     # Enable `console`/`errors` capture. OFF by default:
+                                      #   a live CDP Runtime domain is a detectable bot signal,
+                                      #   so console/errors return empty (with a hint) until set.
+AGENT_BROWSER_TIMEZONE="Asia/Tokyo"   # --launch only. Native timezone override (IANA id, or
+                                      #   "auto" to derive from locale). Aligns Intl+Date to a proxy.
+AGENT_BROWSER_BLOCK_WEBRTC="1"        # --launch only. Hide local IP via WebRTC. Auto-forces WebRTC
+                                      #   through the proxy when one is set; "0" opts out.
+AGENT_BROWSER_HIDE_CANVAS="1"         # --launch only. Session-stable canvas/audio fingerprint noise.
+AGENT_BROWSER_ADAPTIVE_REF="0"        # Disable adaptive @ref relocation (on by default; relocates a
+                                      #   moved element by fingerprint when role/name re-query fails).
+```
+
+> **Heads-up for `console` / `errors`:** capture is **off by default** in this stealth
+> fork. Both commands return `{"messages":[]}` / `{"errors":[]}` plus a `hint` until you
+> launch the session with `AGENT_BROWSER_CAPTURE_CONSOLE=1`. This keeps the CDP `Runtime`
+> domain disabled (a known bot signal) for the common automation path.

skill-data/dogfood/SKILL.md

@@ -96,7 +96,7 @@ Read [references/issue-taxonomy.md](references/issue-taxonomy.md) for the full l
 - Within each section, test interactive elements: click buttons, fill forms, open dropdowns/modals.
 - Check edge cases: empty states, error handling, boundary inputs.
 - Try realistic end-to-end workflows (create, edit, delete flows).
-- Check the browser console for errors periodically.
+- Check the browser console for errors periodically. **Console/error capture is off by default in this stealth fork** — start the dogfood session with `AGENT_BROWSER_CAPTURE_CONSOLE=1` (e.g. `AGENT_BROWSER_CAPTURE_CONSOLE=1 agent-browser --session {SESSION} open <url>`) or `console`/`errors` will return empty.
 
 **At each page:**
 

skill-data/slack/SKILL.md

@@ -230,6 +230,9 @@ agent-browser snapshot -i | grep -c "treeitem"
 
 ### Check console for errors
 
+Console/error capture is off by default in this stealth fork — launch the session with
+`AGENT_BROWSER_CAPTURE_CONSOLE=1` first, or these return empty.
+
 ```bash
 agent-browser console
 agent-browser errors