chore(release): 1.5.10 — warn on debug-port launch while relay is up (#32)

The connect-mode diagnostic (1.5.5) proved the 'Allow remote debugging?' modal
is NOT Chrome 149 UX (my earlier hypothesis) — it's chrome-use launching a fresh
debug-port Chrome on session=default while the ab-connect relay is up (32 logged
CONSENT-MODAL-RISK launches), almost always from a stray --launch/--no-auto-connect.
A launch now warns loudly when the relay is available, naming the modal and how
to avoid it (drop --launch/--new, don't pass --no-auto-connect), so the modal is
self-explained and the offending caller is fixable.

.github/workflows/release-binaries.yml

@@ -116,6 +116,16 @@ jobs:
     permissions:
       contents: write
     steps:
+      # The release job is separate from the build matrix and has no repo by
+      # default — check it out (full history + tags) so the changelog step has a
+      # git repo to diff. Without this, `git` failed with "not a git repository"
+      # and the changelog came out empty.
+      - name: Checkout
+        uses: actions/checkout@v6
+        with:
+          ref: ${{ github.event.inputs.tag || github.ref }}
+          fetch-depth: 0
+
       - name: Download all artifacts
         uses: actions/download-artifact@v8
         with:
@@ -125,6 +135,47 @@ jobs:
       - name: List assets
         run: ls -la dist
 
+      # Build the changelog from conventional-commit subjects since the previous
+      # tag. GitHub's built-in generate_release_notes only lists merged PRs,
+      # which is near-empty for this commit-to-main workflow — so we render the
+      # commit log ourselves and every release shows what actually changed.
+      - name: Generate changelog
+        id: changelog
+        run: |
+          # fetch-depth:0 gets history, but the tag refs the changelog needs
+          # aren't always present in a detached-HEAD tag checkout — pull them in.
+          git fetch --tags --force --quiet origin 2>/dev/null || true
+          TAG="${{ github.event.inputs.tag || github.ref_name }}"
+          PREV="$(git describe --tags --abbrev=0 "${TAG}^" 2>/dev/null || true)"
+          RANGE="${TAG}"
+          [ -n "$PREV" ] && RANGE="${PREV}..${TAG}"
+          # Group commit subjects by conventional-commit type so the notes are
+          # scannable ("what's new / what's fixed") instead of a flat dev log.
+          LOG="$(git log "$RANGE" --no-merges --pretty='%s' | grep -v '^chore(release)' || true)"
+          # NOTE: the job runs under `bash -e`. grep returning 1 (no match) and
+          # the `[ -n "$body" ]` test returning 1 (empty section) must NOT abort
+          # the script — otherwise a release whose commit range lacks a whole
+          # category (e.g. only `feat`, no `fix`) dies before writing the closing
+          # heredoc delimiter and the whole release step fails. `|| true` +
+          # `return 0` keep section() always-succeeding.
+          section() { # $1=header  $2=grep-pattern
+            local body; body="$(printf '%s\n' "$LOG" | grep -E "$2" | sed 's/^/- /' || true)"
+            [ -n "$body" ] && printf '\n### %s\n%s\n' "$1" "$body"
+            return 0
+          }
+          {
+            echo "notes<<__NOTES_EOF__"
+            echo "## What changed"
+            section "✨ Features" '^feat'
+            section "🐛 Fixes" '^fix'
+            section "🔧 Other" '^(perf|refactor|docs|build|ci|test|style|revert)'
+            if [ -n "$PREV" ]; then
+              echo ""
+              echo "**Full changelog**: https://github.com/${{ github.repository }}/compare/${PREV}...${TAG}"
+            fi
+            echo "__NOTES_EOF__"
+          } >> "$GITHUB_OUTPUT"
+
       - name: Attach to release
         uses: softprops/action-gh-release@v3
         with:
@@ -133,5 +184,8 @@ jobs:
             dist/*.tar.gz
             dist/*.tar.gz.sha256
           fail_on_unmatched_files: true
-          # keep existing release notes if the release was created beforehand
+          # The commit-based changelog so every release shows what changed. The
+          # first matrix job to run creates the release with these notes;
+          # append_body:false keeps later platform jobs from duplicating them.
+          body: ${{ steps.changelog.outputs.notes }}
           append_body: false

.gitignore

@@ -75,3 +75,4 @@ out/
 # extension signing key (never commit) + local-only id record
 .secrets/
 *.pem
+/cu-test-artifacts

README.md

@@ -205,6 +205,47 @@ chrome-use --launch --profile auto open https://x.com/home
 
 In CI environments, standalone mode is used automatically.
 
+## Automated testing (`chrome-use test`)
+
+Turn the repetitive "open it, click around, check it's right" work into a
+**re-runnable suite** — unit tests for the frontend. Write cases in YAML; steps
+reuse chrome-use's own commands and assertions compile to a single check:
+
+```yaml
+# smoke.yaml
+suite: chatgpt smoke
+setup:
+  - account: chatgpt/huayue          # inject a cookie-use login (optional)
+cases:
+  - name: home loads logged in
+    steps:
+      - open: https://chatgpt.com/
+      - wait: { load: networkidle }
+    assert:
+      - url: { contains: chatgpt.com }
+      - visible: "#prompt-textarea"
+```
+
+```bash
+chrome-use test smoke.yaml                     # launches an isolated browser, runs cases
+chrome-use test smoke.yaml --session default   # …or against your connected Chrome
+```
+
+```
+suite: chatgpt smoke  (session cu-test)
+  ✓ home loads logged in   1.2s
+  ✗ composer takes text    0.8s
+      assert text "#prompt-textarea" contains "hi" → got ""
+      ↳ cu-test-artifacts/composer-takes-text.png
+2 cases · 1 passed · 1 failed
+```
+
+Exit code is non-zero if any case fails (drop it into CI), and failed cases save
+a screenshot. Assertions: `url` · `visible` · `hidden` · `text` · `count` ·
+`eval`. Steps: `open` · `click` · `fill` · `type` · `press` · `wait` · `scroll`
+· `eval`. Full guide: `chrome-use skills get test`. Found a regression? Add a
+case — the suite gets more valuable the more you use it.
+
 ## Anti-detection
 
 <img src="assets/shield.png" alt="stealth shield" width="320" align="right" />

cli/Cargo.lock

@@ -290,7 +290,7 @@ checksum = "613afe47fcd5fac7ccf1db93babcb082c5994d996f20b8b159f2ad1658eb5724"
 
 [[package]]
 name = "chrome-use"
-version = "1.1.0"
+version = "1.5.10"
 dependencies = [
  "aes",
  "aes-gcm",
@@ -312,6 +312,7 @@ dependencies = [
  "rust-embed",
  "serde",
  "serde_json",
+ "serde_yaml",
  "sha1",
  "sha2",
  "similar",
@@ -1982,6 +1983,19 @@ dependencies = [
  "serde",
 ]
 
+[[package]]
+name = "serde_yaml"
+version = "0.9.34+deprecated"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6a8b1a1a2ebf674015cc02edccce75287f1a0130d394307b36743c2f5d504b47"
+dependencies = [
+ "indexmap",
+ "itoa",
+ "ryu",
+ "serde",
+ "unsafe-libyaml",
+]
+
 [[package]]
 name = "sha1"
 version = "0.10.6"
@@ -2419,6 +2433,12 @@ dependencies = [
  "subtle",
 ]
 
+[[package]]
+name = "unsafe-libyaml"
+version = "0.2.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "673aac59facbab8a9007c7f6108d11f63b603f7cabff99fabf650fea5c32b861"
+
 [[package]]
 name = "untrusted"
 version = "0.9.0"

cli/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "chrome-use"
-version = "1.1.0"
+version = "1.5.10"
 edition = "2021"
 description = "Fast browser automation CLI for AI agents"
 license = "Apache-2.0"
@@ -45,6 +45,7 @@ sha1 = "0.10"
 chrono = "0.4"
 urlencoding = "2"
 rust-embed = "8"
+serde_yaml = "0.9"
 
 [target.'cfg(unix)'.dependencies]
 libc = "0.2"

cli/build.rs

@@ -3,6 +3,23 @@ use std::env;
 use std::fs;
 use std::path::Path;
 
+/// Embed the version of the `ab-connect` extension this CLI ships alongside, so
+/// `doctor` can tell a connected extension "you're older than what this CLI
+/// expects, update it." Read from the extension manifest at build time so it
+/// stays in sync with whatever extension version is in the same checkout/release
+/// (the ext is on its own 0.4.x line, separate from the CLI version). Falls back
+/// to "unknown" if the manifest can't be read.
+fn embed_extension_version() {
+    let manifest = Path::new("../extensions/ab-connect/manifest.json");
+    println!("cargo:rerun-if-changed=../extensions/ab-connect/manifest.json");
+    let version = fs::read_to_string(manifest)
+        .ok()
+        .and_then(|s| serde_json::from_str::<serde_json::Value>(&s).ok())
+        .and_then(|v| v.get("version").and_then(|x| x.as_str()).map(String::from))
+        .unwrap_or_else(|| "unknown".to_string());
+    println!("cargo:rustc-env=AB_CONNECT_VERSION={}", version);
+}
+
 /// Ensure `packages/dashboard/out/` exists so `rust-embed` doesn't fail during
 /// Rust-only dev builds where the dashboard hasn't been built. The placeholder
 /// `index.html` is only written when the directory is completely absent.
@@ -20,6 +37,7 @@ fn ensure_dashboard_dir() {
 
 fn main() {
     ensure_dashboard_dir();
+    embed_extension_version();
 
     let protocol_dir = Path::new("cdp-protocol");
     let out_dir = env::var("OUT_DIR").unwrap();

cli/src/commands.rs

@@ -30,12 +30,65 @@ pub enum ParseError {
     InvalidSessionName { name: String },
 }
 
+/// Top-level commands an agent is likely to mistype, used for "did you mean"
+/// suggestions on an unknown command (issue #29). Not exhaustive — just the
+/// common verbs plus a few known wrong-guesses mapped to the real command.
+const KNOWN_COMMANDS: &[&str] = &[
+    "open", "navigate", "click", "fill", "type", "press", "snapshot", "screenshot", "eval", "get",
+    "text", "html", "frames", "find", "wait", "scroll", "hover", "select", "check", "uncheck",
+    "tab", "tabs", "close", "back", "forward", "reload", "sessions", "status", "daemon", "doctor",
+    "upgrade", "connect", "cookies", "mouse", "keyboard", "stream", "frame", "profiles", "title",
+    "url", "is", "drag", "dialog", "upload",
+];
+
+/// Levenshtein distance, capped — small inputs only (command names).
+fn edit_distance(a: &str, b: &str) -> usize {
+    let a: Vec<char> = a.chars().collect();
+    let b: Vec<char> = b.chars().collect();
+    let mut prev: Vec<usize> = (0..=b.len()).collect();
+    let mut curr = vec![0usize; b.len() + 1];
+    for (i, &ca) in a.iter().enumerate() {
+        curr[0] = i + 1;
+        for (j, &cb) in b.iter().enumerate() {
+            let cost = if ca == cb { 0 } else { 1 };
+            curr[j + 1] = (prev[j + 1] + 1).min(curr[j] + 1).min(prev[j] + cost);
+        }
+        std::mem::swap(&mut prev, &mut curr);
+    }
+    prev[b.len()]
+}
+
+/// Closest known command within a small edit distance, or a prefix/substring
+/// match — `None` if nothing is close enough to suggest confidently.
+fn nearest_command(input: &str) -> Option<String> {
+    let lower = input.to_lowercase();
+    // Exact prefix/substring hits first (e.g. "session" -> "sessions").
+    if let Some(c) = KNOWN_COMMANDS
+        .iter()
+        .find(|c| c.starts_with(&lower) || lower.starts_with(**c))
+    {
+        return Some(c.to_string());
+    }
+    // Tolerance scales with length: short words get distance 1, longer get 2.
+    let max_dist = if lower.len() <= 4 { 1 } else { 2 };
+    KNOWN_COMMANDS
+        .iter()
+        .map(|c| (*c, edit_distance(&lower, c)))
+        .filter(|(_, d)| *d <= max_dist)
+        .min_by_key(|(_, d)| *d)
+        .map(|(c, _)| c.to_string())
+}
+
 impl ParseError {
     pub fn format(&self) -> String {
         match self {
-            ParseError::UnknownCommand { command } => {
-                format!("Unknown command: {}", command)
-            }
+            ParseError::UnknownCommand { command } => match nearest_command(command) {
+                Some(suggestion) => format!(
+                    "Unknown command: {}\nDid you mean: chrome-use {}?",
+                    command, suggestion
+                ),
+                None => format!("Unknown command: {}", command),
+            },
             ParseError::UnknownSubcommand {
                 subcommand,
                 valid_options,
@@ -370,6 +423,12 @@ fn parse_command_inner(args: &[String], flags: &Flags) -> Result<Value, ParseErr
             if flags.provider.is_some() {
                 nav_cmd["waitUntil"] = json!("none");
             }
+            // `--reuse-tab`: adopt an existing tab already on this URL instead of
+            // navigating/spawning a new one (issue #21 — avoids duplicate tabs on
+            // rebind, preserves in-page state).
+            if rest.iter().any(|a| *a == "--reuse-tab" || *a == "--reuse") {
+                nav_cmd["reuseTab"] = json!(true);
+            }
             // Explicit readiness override (issue #10): SPAs whose `load` event
             // never fires (a long-lived XHR/websocket holds it open) hang out the
             // load-event wait. `--wait-until domcontentloaded` returns as soon as
@@ -408,10 +467,19 @@ fn parse_command_inner(args: &[String], flags: &Flags) -> Result<Value, ParseErr
         "back" => Ok(json!({ "id": id, "action": "back" })),
         "forward" => Ok(json!({ "id": id, "action": "forward" })),
         "reload" => Ok(json!({ "id": id, "action": "reload" })),
+        // Explicit opt-in to raise the active tab to the foreground (the core
+        // skill references it; the daemon handler existed but the CLI didn't map
+        // it — issue #19). Accept the documented camelCase + kebab/lowercase.
+        "bringToFront" | "bring-to-front" | "bringtofront" => {
+            Ok(json!({ "id": id, "action": "bringtofront" }))
+        }
 
         // === Core Actions ===
         "click" => {
             let new_tab = rest.contains(&"--new-tab");
+            // `--follow`: if the click opens a new tab, switch the active tab to
+            // it (default reports the opened tab but stays put) (issue #24-A).
+            let follow = rest.contains(&"--follow");
             // Coordinate click as a first-class form (issue #8.4): when the only
             // handle is a pixel position, no element/selector is needed.
             //   click <x> <y>          e.g. click 449 320
@@ -420,23 +488,27 @@ fn parse_command_inner(args: &[String], flags: &Flags) -> Result<Value, ParseErr
             let coord_args: Vec<&str> = rest
                 .iter()
                 .copied()
-                .filter(|a| *a != "--new-tab" && *a != "--coords")
+                .filter(|a| !a.starts_with("--"))
                 .collect();
             if let Some((x, y)) = parse_coords(&coord_args) {
                 return Ok(json!({ "id": id, "action": "click", "x": x, "y": y }));
             }
             let sel = rest
                 .iter()
-                .find(|arg| **arg != "--new-tab")
+                .find(|arg| !arg.starts_with("--"))
                 .ok_or_else(|| ParseError::MissingArguments {
                     context: "click".to_string(),
-                    usage: "click <selector> | click <x> <y> | click --coords <x>,<y> [--new-tab]",
+                    usage:
+                        "click <selector> | click <x> <y> | click --coords <x>,<y> [--new-tab] [--follow]",
                 })?;
+            let mut cmd = json!({ "id": id, "action": "click", "selector": sel });
             if new_tab {
-                Ok(json!({ "id": id, "action": "click", "selector": sel, "newTab": true }))
-            } else {
-                Ok(json!({ "id": id, "action": "click", "selector": sel }))
+                cmd["newTab"] = json!(true);
             }
+            if follow {
+                cmd["follow"] = json!(true);
+            }
+            Ok(cmd)
         }
         "dblclick" => {
             let sel = rest.first().ok_or_else(|| ParseError::MissingArguments {
@@ -571,11 +643,27 @@ fn parse_command_inner(args: &[String], flags: &Flags) -> Result<Value, ParseErr
 
         // === Keyboard ===
         "press" | "key" => {
-            let key = rest.first().ok_or_else(|| ParseError::MissingArguments {
-                context: "press".to_string(),
-                usage: "press <key>",
+            let key = rest.iter().find(|a| !a.starts_with("--")).ok_or_else(|| {
+                ParseError::MissingArguments {
+                    context: "press".to_string(),
+                    usage: "press <key> [--hold <ms>]",
+                }
             })?;
-            Ok(json!({ "id": id, "action": "press", "key": key }))
+            let mut c = json!({ "id": id, "action": "press", "key": key });
+            // `--hold <ms>`: hold the key down for <ms> then release, timed inside
+            // the daemon (one round-trip, no shell-sleep jitter) — for games and
+            // hold-to-charge where keydown+sleep+keyup over 3 round-trips is too
+            // imprecise.
+            if let Some(i) = rest.iter().position(|a| *a == "--hold") {
+                let ms = rest.get(i + 1).and_then(|s| s.parse::<u64>().ok()).ok_or(
+                    ParseError::MissingArguments {
+                        context: "press --hold".to_string(),
+                        usage: "press <key> --hold <ms>",
+                    },
+                )?;
+                c["hold"] = json!(ms);
+            }
+            Ok(c)
         }
         "keydown" => {
             let key = rest.first().ok_or_else(|| ParseError::MissingArguments {
@@ -819,17 +907,37 @@ fn parse_command_inner(args: &[String], flags: &Flags) -> Result<Value, ParseErr
             // selector: @ref or CSS selector
             // path: file path (contains / or . or ends with known extension)
             let mut full_page = false;
-            let positional: Vec<&str> = rest
-                .iter()
-                .filter(|arg| match **arg {
-                    "--full" | "-f" => {
-                        full_page = true;
-                        false
+            let mut clip: Option<Value> = None;
+            let mut positional: Vec<&str> = Vec::new();
+            let mut i = 0;
+            while i < rest.len() {
+                match rest[i] {
+                    "--full" | "-f" => full_page = true,
+                    // `--clip x,y,w,h` captures a pixel region (issue #34).
+                    "--clip" => {
+                        let raw = rest.get(i + 1).ok_or_else(|| ParseError::MissingArguments {
+                            context: "screenshot --clip".to_string(),
+                            usage: "screenshot --clip <x,y,w,h> [path]",
+                        })?;
+                        let nums: Vec<f64> = raw
+                            .split(',')
+                            .filter_map(|n| n.trim().parse::<f64>().ok())
+                            .collect();
+                        if nums.len() != 4 {
+                            return Err(ParseError::InvalidValue {
+                                message: format!("--clip expects 'x,y,w,h' (4 numbers), got '{raw}'"),
+                                usage: "screenshot --clip <x,y,w,h> [path]",
+                            });
+                        }
+                        clip = Some(json!({
+                            "x": nums[0], "y": nums[1], "width": nums[2], "height": nums[3]
+                        }));
+                        i += 1;
                     }
-                    _ => true,
-                })
-                .copied()
-                .collect();
+                    other => positional.push(other),
+                }
+                i += 1;
+            }
             let (selector, path) = match (positional.first(), positional.get(1)) {
                 (Some(first), Some(second)) => {
                     // Two args: first is selector, second is path
@@ -860,6 +968,9 @@ fn parse_command_inner(args: &[String], flags: &Flags) -> Result<Value, ParseErr
                 "path": path, "selector": selector,
                 "fullPage": full_page, "annotate": flags.annotate
             });
+            if let Some(c) = clip {
+                cmd["clip"] = c;
+            }
             if let Some(ref fmt) = flags.screenshot_format {
                 cmd["format"] = json!(fmt);
             }
@@ -990,8 +1101,31 @@ fn parse_command_inner(args: &[String], flags: &Flags) -> Result<Value, ParseErr
             Ok(json!({ "id": id, "action": "stealth_status" }))
         }
 
+        // `cf-status` — Cloudflare challenge/clearance preflight: is the page
+        // currently a CF challenge, and is there a still-valid cf_clearance (the
+        // HttpOnly persistence cookie)? Lets an agent SKIP re-solving when already
+        // cleared, and know when it must solve. Persistence optimization.
+        "cf-status" | "cf" | "cloudflare-status" | "clearance" => {
+            Ok(json!({ "id": id, "action": "cf_status" }))
+        }
+
         // === Close ===
-        "close" | "quit" | "exit" => Ok(json!({ "id": id, "action": "close" })),
+        "close" | "quit" | "exit" => {
+            // `close <tab>` closes only that tab (and the output says "Tab
+            // closed"); bare `close` closes the browser/session. `close --all` is
+            // intercepted earlier in the dispatcher. Previously `close t12` still
+            // ran a browser close and alarmingly printed "Browser closed" (#26).
+            if let Some(tab_ref) = rest.iter().find(|a| !a.starts_with("--")) {
+                Ok(json!({ "id": id, "action": "tab_close", "tabId": tab_ref }))
+            } else {
+                Ok(json!({ "id": id, "action": "close" }))
+            }
+        }
+
+        // The active tab's stable handle — `targetId` survives cross-process
+        // navigation and is reusable across sessions, so an agent can hold it
+        // instead of re-deriving "which tab is live" from `tabs` each step (#26).
+        "current" => Ok(json!({ "id": id, "action": "current" })),
 
         // === Inspect ===
         "inspect" => Ok(json!({ "id": id, "action": "inspect" })),
@@ -1246,6 +1380,11 @@ fn parse_command_inner(args: &[String], flags: &Flags) -> Result<Value, ParseErr
         // === Get ===
         "get" => parse_get(&rest, &id),
 
+        // List every frame the session can reach (top + same-process child
+        // frames + out-of-process iframes), with a text-length per frame so you
+        // can see where a listing's description actually lives (issue #27).
+        "frames" => Ok(json!({ "id": id, "action": "frames" })),
+
         // Top-level shortcuts for `get <x>` status reads — users naturally type
         // `chrome-use url` / `cdp-url` / `title` without the `get` prefix
         // (and expect `cdp-url`/`cdp_url` to work interchangeably).
@@ -1328,11 +1467,11 @@ fn parse_command_inner(args: &[String], flags: &Flags) -> Result<Value, ParseErr
                             usage: "cookies transfer --from <profile> [--domain <domain>]",
                         });
                     }
-                    return Ok(json!({
+                    Ok(json!({
                         "id": id,
                         "action": "cookies_set",
                         "cookies": cookies,
-                    }));
+                    }))
                 }
                 "set" => {
                     // --curl <file> mode: import cookies from a JSON array,
@@ -1496,7 +1635,12 @@ fn parse_command_inner(args: &[String], flags: &Flags) -> Result<Value, ParseErr
         // `tabs` (plural) is a natural guess for the `tab` subcommand tree —
         // alias it so `tabs` / `tabs list` / `tabs new` all work (issue #8.4).
         "tab" | "tabs" => {
-            match rest.first().copied() {
+            // `--full` makes `tab list` emit untruncated URLs (needed to re-open
+            // a long SSO/redirect URL after a stale session — issue #19). Pick
+            // the subcommand as the first non-flag arg so the flag can appear
+            // anywhere (`tab --full`, `tab list --full`).
+            let full = rest.contains(&"--full");
+            match rest.iter().find(|a| !a.starts_with("--")).copied() {
                 Some("new") => {
                     // Accepted forms:
                     //   tab new [url]
@@ -1528,7 +1672,13 @@ fn parse_command_inner(args: &[String], flags: &Flags) -> Result<Value, ParseErr
                     }
                     Ok(cmd)
                 }
-                Some("list") => Ok(json!({ "id": id, "action": "tab_list" })),
+                Some("list") => {
+                    let mut cmd = json!({ "id": id, "action": "tab_list" });
+                    if full {
+                        cmd["full"] = json!(true);
+                    }
+                    Ok(cmd)
+                }
                 Some("close") => {
                     let mut cmd = json!({ "id": id, "action": "tab_close" });
                     if let Some(tab_ref) = rest.get(1) {
@@ -1536,12 +1686,23 @@ fn parse_command_inner(args: &[String], flags: &Flags) -> Result<Value, ParseErr
                     }
                     Ok(cmd)
                 }
-                Some(tab_ref) => Ok(json!({
-                    "id": id,
-                    "action": "tab_switch",
-                    "tabId": tab_ref,
-                })),
-                None => Ok(json!({ "id": id, "action": "tab_list" })),
+                Some(tab_ref) => {
+                    // `tab <ref> --activate` (alias `--front`) switches to the tab
+                    // AND raises it to the foreground — for handing a specific tab
+                    // to the human (SMS code, captcha) (issue #24-C).
+                    let mut cmd = json!({ "id": id, "action": "tab_switch", "tabId": tab_ref });
+                    if rest.iter().any(|a| *a == "--activate" || *a == "--front") {
+                        cmd["activate"] = json!(true);
+                    }
+                    Ok(cmd)
+                }
+                None => {
+                    let mut cmd = json!({ "id": id, "action": "tab_list" });
+                    if full {
+                        cmd["full"] = json!(true);
+                    }
+                    Ok(cmd)
+                }
             }
         }
 
@@ -2316,11 +2477,42 @@ fn parse_get(rest: &[&str], id: &str) -> Result<Value, ParseError> {
 
     match rest.first().copied() {
         Some("text") => {
-            let sel = rest.get(1).ok_or_else(|| ParseError::MissingArguments {
-                context: "get text".to_string(),
-                usage: "get text <selector>",
-            })?;
-            Ok(json!({ "id": id, "action": "gettext", "selector": sel }))
+            // `get text --all-frames` aggregates visible text across every
+            // frame, including out-of-process iframes invisible to the top
+            // document (issue #27). The selector is ignored in this mode.
+            let all_frames = rest[1..]
+                .iter()
+                .any(|a| matches!(*a, "--all-frames" | "--frames" | "-a"));
+            if all_frames {
+                return Ok(json!({ "id": id, "action": "gettext", "allFrames": true }));
+            }
+            // `get text --pierce` reads through CLOSED shadow DOM / child docs
+            // via the CDP DOM tree — content eval/innerText can't reach, e.g. an
+            // extension's injected panel in a closed shadow root (issue #30).
+            let pierce = rest[1..]
+                .iter()
+                .any(|a| matches!(*a, "--pierce" | "--shadow" | "--deep"));
+            if pierce {
+                return Ok(json!({ "id": id, "action": "gettext", "pierce": true }));
+            }
+            // `get text --main` returns the main-content region (readability),
+            // skipping header/nav/footer/sidebar boilerplate (issue #27).
+            let main = rest[1..]
+                .iter()
+                .any(|a| matches!(*a, "--main" | "--readable" | "-m"));
+            if main {
+                return Ok(json!({ "id": id, "action": "gettext", "main": true }));
+            }
+            // `get text` with no selector reads the WHOLE PAGE and now defaults
+            // to cross-frame aggregation, so an agent gets a page's iframed
+            // content (listing descriptions etc.) without having to know about
+            // `--all-frames` (#27). On a single-frame page this is identical to
+            // the old body read; multi-frame pages get the child frames too —
+            // a strict superset. An explicit selector stays element-scoped.
+            match rest.iter().skip(1).find(|a| !a.starts_with("--")).copied() {
+                Some(sel) => Ok(json!({ "id": id, "action": "gettext", "selector": sel })),
+                None => Ok(json!({ "id": id, "action": "gettext", "allFrames": true })),
+            }
         }
         Some("html") => {
             let sel = rest.get(1).ok_or_else(|| ParseError::MissingArguments {
@@ -3552,6 +3744,40 @@ mod tests {
         assert_eq!(cmd["url"], "https://example.com");
     }
 
+    #[test]
+    fn test_press_plain_and_hold() {
+        let cmd = parse_command(&args("press d"), &default_flags()).unwrap();
+        assert_eq!(cmd["action"], "press");
+        assert_eq!(cmd["key"], "d");
+        assert!(cmd.get("hold").is_none());
+
+        let held = parse_command(&args("press d --hold 800"), &default_flags()).unwrap();
+        assert_eq!(held["key"], "d");
+        assert_eq!(held["hold"], 800);
+
+        // Missing/invalid duration is an error, not a silent no-hold.
+        assert!(parse_command(&args("press d --hold"), &default_flags()).is_err());
+        assert!(parse_command(&args("press d --hold abc"), &default_flags()).is_err());
+    }
+
+    #[test]
+    fn test_navigate_reuse_tab_flag() {
+        let cmd = parse_command(
+            &args("open https://example.com --reuse-tab"),
+            &default_flags(),
+        )
+        .unwrap();
+        assert_eq!(cmd["action"], "navigate");
+        assert_eq!(cmd["reuseTab"], true);
+        // Alias.
+        let cmd2 =
+            parse_command(&args("open https://example.com --reuse"), &default_flags()).unwrap();
+        assert_eq!(cmd2["reuseTab"], true);
+        // Absent by default.
+        let cmd3 = parse_command(&args("open https://example.com"), &default_flags()).unwrap();
+        assert!(cmd3.get("reuseTab").is_none());
+    }
+
     #[test]
     fn test_navigate_with_headers() {
         let mut flags = default_flags();
@@ -3700,6 +3926,21 @@ mod tests {
         assert!(cmd.get("x").is_none());
     }
 
+    #[test]
+    fn test_click_follow_flag() {
+        // `--follow` sets the flag; the selector is still found even with the flag
+        // before it (issue #24-A).
+        let cmd = parse_command(&args("click @e5 --follow"), &default_flags()).unwrap();
+        assert_eq!(cmd["selector"], "@e5");
+        assert_eq!(cmd["follow"], true);
+        let cmd2 = parse_command(&args("click --follow @e5"), &default_flags()).unwrap();
+        assert_eq!(cmd2["selector"], "@e5");
+        assert_eq!(cmd2["follow"], true);
+        // Absent by default.
+        let plain = parse_command(&args("click @e5"), &default_flags()).unwrap();
+        assert!(plain.get("follow").is_none());
+    }
+
     #[test]
     fn test_tabs_alias_lists() {
         assert_eq!(
@@ -3716,6 +3957,30 @@ mod tests {
         );
     }
 
+    #[test]
+    fn test_tab_list_full_flag() {
+        // issue #19: `--full` → untruncated URLs; works as `tab list --full`,
+        // `tab --full`, and `tabs --full`. Plain list has no `full`.
+        for inv in ["tab list --full", "tab --full", "tabs --full"] {
+            let cmd = parse_command(&args(inv), &default_flags()).unwrap();
+            assert_eq!(cmd["action"], "tab_list", "{inv}");
+            assert_eq!(cmd["full"], true, "{inv}");
+        }
+        let plain = parse_command(&args("tab list"), &default_flags()).unwrap();
+        assert_eq!(plain["action"], "tab_list");
+        assert!(plain.get("full").is_none());
+    }
+
+    #[test]
+    fn test_bring_to_front_aliases() {
+        // issue #19: the documented `bringToFront` (+ kebab/lowercase) maps to
+        // the existing daemon action.
+        for inv in ["bringToFront", "bring-to-front", "bringtofront"] {
+            let cmd = parse_command(&args(inv), &default_flags()).unwrap();
+            assert_eq!(cmd["action"], "bringtofront", "{inv}");
+        }
+    }
+
     #[test]
     fn test_get_text_hyphen_and_underscore_aliases() {
         for verb in ["get-text", "get_text"] {
@@ -3884,6 +4149,28 @@ mod tests {
         assert_eq!(cmd["tabId"], "docs");
     }
 
+    #[test]
+    fn test_close_tab_vs_browser() {
+        // `close <tab>` closes that tab (says "Tab closed"); bare `close` closes
+        // the browser (#26).
+        let tab = parse_command(&args("close t12"), &default_flags()).unwrap();
+        assert_eq!(tab["action"], "tab_close");
+        assert_eq!(tab["tabId"], "t12");
+        let browser = parse_command(&args("close"), &default_flags()).unwrap();
+        assert_eq!(browser["action"], "close");
+        // `quit`/`exit` aliases still browser-close.
+        assert_eq!(
+            parse_command(&args("quit"), &default_flags()).unwrap()["action"],
+            "close"
+        );
+    }
+
+    #[test]
+    fn test_current_command() {
+        let cmd = parse_command(&args("current"), &default_flags()).unwrap();
+        assert_eq!(cmd["action"], "current");
+    }
+
     #[test]
     fn test_tab_sends_string_tab_id() {
         let cmd = parse_command(&args("tab t2"), &default_flags()).unwrap();
@@ -4063,6 +4350,21 @@ mod tests {
         assert_eq!(cmd["fullPage"], true);
     }
 
+    #[test]
+    fn test_screenshot_clip() {
+        // `--clip x,y,w,h` captures a pixel region (issue #34); the path still parses.
+        let cmd = parse_command(&args("screenshot --clip 10,20,200,40 out.png"), &default_flags())
+            .unwrap();
+        assert_eq!(cmd["action"], "screenshot");
+        assert_eq!(cmd["clip"]["x"], 10.0);
+        assert_eq!(cmd["clip"]["y"], 20.0);
+        assert_eq!(cmd["clip"]["width"], 200.0);
+        assert_eq!(cmd["clip"]["height"], 40.0);
+        assert_eq!(cmd["path"], "out.png");
+        // Bad clip is a clear error, not silent.
+        assert!(parse_command(&args("screenshot --clip 1,2,3"), &default_flags()).is_err());
+    }
+
     #[test]
     fn test_screenshot_with_ref() {
         let cmd = parse_command(&args("screenshot @e1"), &default_flags()).unwrap();
@@ -4583,12 +4885,96 @@ mod tests {
     }
 
     #[test]
-    fn test_get_text_missing_selector() {
-        let result = parse_command(&args("get text"), &default_flags());
-        assert!(result.is_err());
-        let err = result.unwrap_err();
-        assert!(matches!(err, ParseError::MissingArguments { .. }));
-        assert!(err.format().contains("get text"));
+    fn test_get_text_defaults_to_all_frames() {
+        // `get text` with no selector now reads the whole page across ALL frames
+        // by default (#27), so iframed content isn't silently missed. (Was: a
+        // top-frame `body` read, #24-D.)
+        let cmd = parse_command(&args("get text"), &default_flags()).unwrap();
+        assert_eq!(cmd["action"], "gettext");
+        assert_eq!(cmd["allFrames"], true);
+        assert!(cmd.get("selector").is_none());
+        // An explicit selector still wins and stays element-scoped.
+        let cmd2 = parse_command(&args("get text h1"), &default_flags()).unwrap();
+        assert_eq!(cmd2["selector"], "h1");
+        assert!(cmd2.get("allFrames").is_none());
+        // `text` top-level shortcut behaves the same.
+        let cmd3 = parse_command(&args("text"), &default_flags()).unwrap();
+        assert_eq!(cmd3["allFrames"], true);
+    }
+
+    #[test]
+    fn test_get_text_all_frames() {
+        // `--all-frames` switches to whole-page, cross-frame aggregation and
+        // drops the selector (issue #27).
+        for variant in ["get text --all-frames", "get text --frames", "text -a"] {
+            let cmd = parse_command(&args(variant), &default_flags()).unwrap();
+            assert_eq!(cmd["action"], "gettext", "{variant}");
+            assert_eq!(cmd["allFrames"], true, "{variant}");
+            assert!(cmd.get("selector").is_none(), "{variant}");
+        }
+        // A flag mixed with a selector still triggers all-frames.
+        let cmd = parse_command(&args("get text body --all-frames"), &default_flags()).unwrap();
+        assert_eq!(cmd["allFrames"], true);
+        // Without the flag, a leading flag-like token is skipped for the selector.
+        let cmd = parse_command(&args("get text main"), &default_flags()).unwrap();
+        assert_eq!(cmd["selector"], "main");
+        assert!(cmd.get("allFrames").is_none());
+    }
+
+    #[test]
+    fn test_frames_command() {
+        let cmd = parse_command(&args("frames"), &default_flags()).unwrap();
+        assert_eq!(cmd["action"], "frames");
+    }
+
+    #[test]
+    fn test_nearest_command_suggestions() {
+        assert_eq!(nearest_command("sesions").as_deref(), Some("sessions"));
+        assert_eq!(nearest_command("session").as_deref(), Some("sessions"));
+        assert_eq!(nearest_command("clik").as_deref(), Some("click"));
+        assert_eq!(nearest_command("screenshits").as_deref(), Some("screenshot"));
+        // Nonsense with no close match stays silent.
+        assert_eq!(nearest_command("xyzzy"), None);
+        // The unknown-command error embeds the suggestion.
+        let err = ParseError::UnknownCommand {
+            command: "sesions".to_string(),
+        };
+        assert!(err.format().contains("Did you mean: chrome-use sessions?"));
+    }
+
+    #[test]
+    fn test_get_text_main() {
+        for variant in ["get text --main", "get text --readable", "text -m"] {
+            let cmd = parse_command(&args(variant), &default_flags()).unwrap();
+            assert_eq!(cmd["action"], "gettext", "{variant}");
+            assert_eq!(cmd["main"], true, "{variant}");
+            assert!(cmd.get("selector").is_none(), "{variant}");
+        }
+    }
+
+    #[test]
+    fn test_get_text_pierce() {
+        for variant in ["get text --pierce", "get text --shadow", "text --deep"] {
+            let cmd = parse_command(&args(variant), &default_flags()).unwrap();
+            assert_eq!(cmd["action"], "gettext", "{variant}");
+            assert_eq!(cmd["pierce"], true, "{variant}");
+            assert!(cmd.get("selector").is_none(), "{variant}");
+        }
+    }
+
+    #[test]
+    fn test_tab_activate_flag() {
+        let plain = parse_command(&args("tab t3"), &default_flags()).unwrap();
+        assert_eq!(plain["action"], "tab_switch");
+        assert!(plain.get("activate").is_none());
+
+        let act = parse_command(&args("tab t3 --activate"), &default_flags()).unwrap();
+        assert_eq!(act["action"], "tab_switch");
+        assert_eq!(act["tabId"], "t3");
+        assert_eq!(act["activate"], true);
+        // `--front` alias.
+        let front = parse_command(&args("tab t3 --front"), &default_flags()).unwrap();
+        assert_eq!(front["activate"], true);
     }
 
     // === Protocol alignment tests ===

cli/src/connect.rs

@@ -16,8 +16,18 @@ 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.leeguoo.chrome_use";
+/// manifest filename. `com.agent_browser.connect` is the original name, used by
+/// every shipped extension up to ab-connect 0.4.2.
+pub const HOST_NAME: &str = "com.agent_browser.connect";
+
+/// Alternate host name for the chrome-use rebrand era (ab-connect 0.5.0+). We
+/// install AND recognize both names so the relay works regardless of which
+/// extension version a user has — old (0.4.2) or new — with no forced
+/// re-install. See [`install_native_host`] / [`host_installed`].
+pub const HOST_NAME_ALT: &str = "com.leeguoo.chrome_use";
+
+/// Every native-messaging host name this CLI installs and accepts.
+pub const HOST_NAMES: &[&str] = &[HOST_NAME, HOST_NAME_ALT];
 
 /// 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
@@ -182,18 +192,9 @@ fn install_native_host() -> Result<Vec<String>, String> {
         let _ = std::fs::set_permissions(&launcher, std::fs::Permissions::from_mode(0o755));
     }
 
-    let manifest = serde_json::json!({
-        "name": HOST_NAME,
-        "description": "chrome-use connect — native messaging host",
-        "path": launcher.display().to_string(),
-        "type": "stdio",
-        "allowed_origins": [
-            format!("chrome-extension://{EXTENSION_ID}/"),
-            format!("chrome-extension://{STORE_EXTENSION_ID}/"),
-        ],
-    });
-    let body = serde_json::to_string_pretty(&manifest).map_err(|e| e.to_string())?;
-
+    // Write a manifest under EVERY accepted host name (both point to the same
+    // launcher + allowed extensions), so any extension version's
+    // `connectNative(<its host name>)` finds a matching host json.
     let mut written = Vec::new();
     for dir in native_messaging_dirs() {
         if let Some(parent) = dir.parent() {
@@ -202,9 +203,22 @@ fn install_native_host() -> Result<Vec<String>, String> {
             }
         }
         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());
+        for host in HOST_NAMES {
+            let manifest = serde_json::json!({
+                "name": host,
+                "description": "chrome-use connect — native messaging host",
+                "path": launcher.display().to_string(),
+                "type": "stdio",
+                "allowed_origins": [
+                    format!("chrome-extension://{EXTENSION_ID}/"),
+                    format!("chrome-extension://{STORE_EXTENSION_ID}/"),
+                ],
+            });
+            let body = serde_json::to_string_pretty(&manifest).map_err(|e| e.to_string())?;
+            let path = dir.join(format!("{host}.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());
@@ -289,9 +303,11 @@ fn remove_force_install_profile() -> bool {
 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;
+        for host in HOST_NAMES {
+            let path = dir.join(format!("{host}.json"));
+            if path.exists() && std::fs::remove_file(&path).is_ok() {
+                n += 1;
+            }
         }
     }
     n
@@ -334,7 +350,7 @@ fn native_messaging_dirs() -> Vec<PathBuf> {
 fn host_manifest_path_for_chrome() -> Option<PathBuf> {
     native_messaging_dirs()
         .into_iter()
-        .map(|d| d.join(format!("{HOST_NAME}.json")))
+        .flat_map(|d| HOST_NAMES.iter().map(move |h| d.join(format!("{h}.json"))))
         .find(|p| p.exists())
         .or_else(|| {
             native_messaging_dirs()
@@ -352,9 +368,11 @@ fn host_manifest_path_for_chrome() -> Option<PathBuf> {
 /// service worker; this manifest is the durable signal that the extension is
 /// the chosen path.
 pub fn host_installed() -> bool {
-    native_messaging_dirs()
-        .into_iter()
-        .any(|d| d.join(format!("{HOST_NAME}.json")).exists())
+    native_messaging_dirs().into_iter().any(|d| {
+        HOST_NAMES
+            .iter()
+            .any(|h| d.join(format!("{h}.json")).exists())
+    })
 }
 
 fn report(json: bool, ok: bool, msg: &str) {
@@ -399,10 +417,23 @@ fn random_guid() -> String {
 }
 
 /// Where the daemon/CLI reads the relay's CDP WebSocket URL (perms 600).
+///
+/// Cross-binary handoff: the native-messaging *host* writes it and the CLI reads
+/// it, but the two may be different binaries under different brand dirs after
+/// the agent-browser → chrome-use rename. Read from whichever brand dir actually
+/// has the file (an old `agent-browser` host writes `~/.agent-browser`; a
+/// `chrome-use` host writes `~/.chrome-use`); default to [`config_home`].
 fn relay_url_path() -> PathBuf {
-    dirs::home_dir()
-        .map(|h| h.join(".chrome-use").join("relay-cdp-url"))
-        .unwrap_or_else(|| PathBuf::from("/tmp/ab-relay-cdp-url"))
+    if let Some(home) = dirs::home_dir() {
+        for base in [".chrome-use", ".agent-browser"] {
+            let p = home.join(base).join("relay-cdp-url");
+            if p.exists() {
+                return p;
+            }
+        }
+        return crate::connection::config_home().join("relay-cdp-url");
+    }
+    PathBuf::from("/tmp/ab-relay-cdp-url")
 }
 
 /// The live relay CDP WebSocket URL, if the native-messaging host is running
@@ -418,6 +449,69 @@ pub fn relay_url() -> Option<String> {
     }
 }
 
+/// Append a one-line record of how a CDP connection was established, to
+/// `~/.chrome-use/connect-mode.log`. This is the smoking-gun detector for the
+/// "Allow remote debugging?" consent modal: that modal ONLY appears on a raw
+/// remote-debugging attach / a browser we launched with a debug port — NEVER on
+/// the extension relay. When the modal reappears, this log says which session
+/// took which path and when, so we can tell a code regression (`raw-port` /
+/// `launched` while the relay was up) from Chrome's own extension-debugger
+/// consent UX. Low volume (one line per connection); best-effort, never fails a
+/// connection.
+pub fn log_connect_mode(ws_url: &str, launched: bool, session: &str) {
+    let relay = relay_url();
+    let relay_up = relay.is_some();
+    let mode = if launched {
+        "launched(debug-port)"
+    } else if relay.as_deref() == Some(ws_url) {
+        "relay"
+    } else if ws_url.contains("127.0.0.1") || ws_url.contains("localhost") {
+        "raw-port-attach"
+    } else {
+        "remote-ws"
+    };
+    // A raw-port attach or a self-launch while the relay was available is the
+    // exact thing that pops the consent modal — flag it loudly in the line.
+    let suspect = (mode == "raw-port-attach" || launched) && relay_up;
+    let line = format!(
+        "session={session} mode={mode} relay_up={relay_up}{} ws={ws_url}\n",
+        if suspect { " CONSENT-MODAL-RISK" } else { "" }
+    );
+    if let Some(home) = dirs::home_dir() {
+        let path = home.join(".chrome-use").join("connect-mode.log");
+        use std::io::Write;
+        if let Ok(mut f) = std::fs::OpenOptions::new()
+            .create(true)
+            .append(true)
+            .open(&path)
+        {
+            let _ = f.write_all(line.as_bytes());
+        }
+    }
+}
+
+/// Sidecar recording the connected extension's version, written by the host when
+/// it receives the extension's `hello` (sibling of `relay-cdp-url`). Lets
+/// `doctor` surface which extension build is live without a CDP round-trip.
+fn relay_ext_version_path() -> PathBuf {
+    relay_url_path().with_file_name("relay-ext-version")
+}
+
+/// Version of the connected `ab-connect` extension, if the host learned it from
+/// the extension's `hello`. `None` when no extension has connected since the
+/// host started, or the extension predates version reporting.
+pub fn relay_ext_version() -> Option<String> {
+    let s = std::fs::read_to_string(relay_ext_version_path())
+        .ok()?
+        .trim()
+        .to_string();
+    if s.is_empty() {
+        None
+    } else {
+        Some(s)
+    }
+}
+
 /// Hidden `__nm-host` mode: launched by Chrome for the ab-connect extension.
 ///
 /// Bridges the extension (native-messaging stdio, envelope protocol) to a local
@@ -539,6 +633,15 @@ async fn nm_host_main() {
             Ok(v) => v,
             Err(_) => continue,
         };
+        // Extension version handshake: record it next to the relay URL so
+        // `doctor` can report which extension build is live (and whether it's
+        // behind). Best-effort; the message carries no CDP payload.
+        if v.get("method").and_then(|m| m.as_str()) == Some("hello") {
+            if let Some(ver) = v.get("version").and_then(|x| x.as_str()) {
+                let _ = std::fs::write(relay_ext_version_path(), ver);
+            }
+            continue;
+        }
         let outs = {
             let mut s = state.lock().await;
             s.handle_ext_message(&v, "")
@@ -571,6 +674,7 @@ async fn nm_host_main() {
     }
     nm_log("[nm-host] stdin EOF — Chrome closed the port");
     let _ = std::fs::remove_file(relay_url_path());
+    let _ = std::fs::remove_file(relay_ext_version_path());
 }
 
 #[allow(clippy::too_many_arguments)]

cli/src/connection.rs

@@ -88,8 +88,39 @@ impl Connection {
     }
 }
 
+/// Brand-compat config directory basename. The project renamed
+/// `agent-browser` → `chrome-use`, but this dotfile dir is invisible internal
+/// plumbing: it's shared with the native-messaging host (the `relay-cdp-url`
+/// handoff) and holds saved auth/daemon state. Renaming it would break existing
+/// installs and re-pop the "Allow remote debugging?" dialog when the relay
+/// can't be located. So decide ONCE per run: prefer the new `.chrome-use`, but
+/// keep using an existing `.agent-browser` install if that's the only one
+/// present; fresh installs get `.chrome-use`. `dotted` picks the home-dir form
+/// (`.chrome-use`) vs the XDG/tmp subdir form (`chrome-use`); both agree.
+pub fn config_dir_basename(dotted: bool) -> &'static str {
+    let prefer_old = dirs::home_dir()
+        .map(|h| !h.join(".chrome-use").exists() && h.join(".agent-browser").exists())
+        .unwrap_or(false);
+    match (prefer_old, dotted) {
+        (true, true) => ".agent-browser",
+        (true, false) => "agent-browser",
+        (false, true) => ".chrome-use",
+        (false, false) => "chrome-use",
+    }
+}
+
+/// The home-based config dir (`~/.chrome-use`, or `~/.agent-browser` on an
+/// existing install — see [`config_dir_basename`]). Single source of truth so
+/// sockets, auth, and the relay handoff all agree within one run.
+pub fn config_home() -> PathBuf {
+    match dirs::home_dir() {
+        Some(home) => home.join(config_dir_basename(true)),
+        None => env::temp_dir().join(config_dir_basename(false)),
+    }
+}
+
 /// Get the base directory for socket/pid files.
-/// Priority: AGENT_BROWSER_SOCKET_DIR > XDG_RUNTIME_DIR > ~/.chrome-use > tmpdir
+/// Priority: AGENT_BROWSER_SOCKET_DIR > XDG_RUNTIME_DIR > config_home() > tmpdir
 pub fn get_socket_dir() -> PathBuf {
     // 1. Explicit override (ignore empty string)
     if let Ok(dir) = env::var("AGENT_BROWSER_SOCKET_DIR") {
@@ -101,17 +132,17 @@ pub fn get_socket_dir() -> PathBuf {
     // 2. XDG_RUNTIME_DIR (Linux standard, ignore empty string)
     if let Ok(runtime_dir) = env::var("XDG_RUNTIME_DIR") {
         if !runtime_dir.is_empty() {
-            return PathBuf::from(runtime_dir).join("chrome-use");
+            return PathBuf::from(runtime_dir).join(config_dir_basename(false));
         }
     }
 
     // 3. Home directory fallback (like Docker Desktop's ~/.docker/run/)
-    if let Some(home) = dirs::home_dir() {
-        return home.join(".chrome-use");
+    if dirs::home_dir().is_some() {
+        return config_home();
     }
 
     // 4. Last resort: temp dir
-    env::temp_dir().join("chrome-use")
+    env::temp_dir().join(config_dir_basename(false))
 }
 
 #[cfg(unix)]
@@ -611,6 +642,22 @@ fn kill_stale_daemon(session: &str) {
     cleanup_stale_files(session);
 }
 
+/// Kill every per-session daemon worker (SIGTERM→SIGKILL + sidecar cleanup),
+/// leaving the Chrome-launched `__nm-host` native-messaging bridge alone — it's
+/// not a tracked session daemon, so the extension relay stays up. Returns the
+/// session names that were stopped. Powers `chrome-use daemon restart`, which
+/// clears corrupted/cross-leaked daemon state (e.g. after a version-mismatch
+/// restart) without the user resorting to `pgrep`/`kill` (issue #20).
+pub fn restart_all_daemons() -> Vec<String> {
+    let inventory = walk_daemons();
+    let mut stopped = Vec::new();
+    for session in &inventory.sessions {
+        kill_stale_daemon(&session.name);
+        stopped.push(session.name.clone());
+    }
+    stopped
+}
+
 pub fn ensure_daemon(session: &str, opts: &DaemonOptions) -> Result<DaemonResult, String> {
     // Socket connectivity is the sole liveness check — no PID check — so
     // callers in a different PID namespace (e.g. unshare) can still reuse
@@ -1151,6 +1198,55 @@ mod tests {
         let _ = fs::remove_dir(&dir);
     }
 
+    #[test]
+    fn test_restart_all_daemons_empty_dir() {
+        let dir = std::env::temp_dir().join("ab-test-restart-empty");
+        let _ = fs::create_dir_all(&dir);
+        let _guard = EnvGuard::new(&["AGENT_BROWSER_SOCKET_DIR", "XDG_RUNTIME_DIR"]);
+        _guard.set("AGENT_BROWSER_SOCKET_DIR", dir.to_str().unwrap());
+
+        // No daemons registered → nothing to stop, and it must not blow up.
+        assert!(restart_all_daemons().is_empty());
+
+        let _ = fs::remove_dir(&dir);
+    }
+
+    #[cfg(unix)]
+    #[test]
+    fn test_restart_all_daemons_kills_live_session() {
+        let dir = std::env::temp_dir().join("ab-test-restart-live");
+        let _ = fs::create_dir_all(&dir);
+        let _guard = EnvGuard::new(&["AGENT_BROWSER_SOCKET_DIR", "XDG_RUNTIME_DIR"]);
+        _guard.set("AGENT_BROWSER_SOCKET_DIR", dir.to_str().unwrap());
+
+        // Spawn a real, killable child and register it as a session daemon.
+        let mut child = Command::new("sleep")
+            .arg("30")
+            .spawn()
+            .expect("spawn sleep");
+        let pid = child.id();
+        let _ = fs::write(dir.join("rktest.pid"), pid.to_string());
+        let _ = fs::write(get_socket_path("rktest"), b"");
+
+        let stopped = restart_all_daemons();
+        assert!(
+            stopped.contains(&"rktest".to_string()),
+            "stopped: {:?}",
+            stopped
+        );
+
+        // Reap the killed child first — until the parent waits, it lingers as a
+        // zombie that still answers `kill(pid, 0)`, so is_pid_alive would lie.
+        let _ = child.wait();
+        assert!(!is_pid_alive(pid));
+
+        // Sidecars are cleaned up.
+        assert!(!dir.join("rktest.pid").exists());
+        assert!(!get_socket_path("rktest").exists());
+
+        let _ = fs::remove_dir(&dir);
+    }
+
     #[test]
     fn test_cleanup_stale_files_removes_version() {
         let dir = std::env::temp_dir().join("ab-test-cleanup-version");

cli/src/doctor/mod.rs

@@ -18,6 +18,7 @@ mod launch;
 mod network;
 mod providers;
 mod security;
+mod versions;
 
 use serde_json::{json, Value};
 
@@ -97,6 +98,7 @@ pub fn run_doctor(opts: DoctorOptions) -> i32 {
     let mut fixed: Vec<String> = Vec::new();
 
     environment::check(&mut checks);
+    versions::check(&mut checks);
     chrome::check(&mut checks);
     daemon::check(&mut checks);
     config::check(&mut checks);

cli/src/doctor/versions.rs

@@ -0,0 +1,89 @@
+//! Version-coherence checks across all four moving parts: the CLI binary, the
+//! per-session daemons (covered by `daemon.rs`), the connected `ab-connect`
+//! extension, and the bundled skill. The extension was previously a black box —
+//! nothing reported which build was live — so a user could sit on an old
+//! extension with no signal. The extension now reports its version over the
+//! relay (`hello`), the host records it, and this surfaces it in one place.
+
+use super::{Check, Status};
+use crate::{connect, upgrade};
+
+pub(super) fn check(checks: &mut Vec<Check>) {
+    let category = "Versions";
+    let cli_version = env!("CARGO_PKG_VERSION");
+
+    // CLI — compare against the latest seen by the background update check.
+    match upgrade::cached_latest_version() {
+        Some(latest) if upgrade::version_is_newer(&latest, cli_version) => {
+            checks.push(
+                Check::new(
+                    "versions.cli",
+                    category,
+                    Status::Warn,
+                    format!("CLI {cli_version} (newer available: {latest})"),
+                )
+                .with_fix("chrome-use upgrade".to_string()),
+            );
+        }
+        _ => {
+            checks.push(Check::new(
+                "versions.cli",
+                category,
+                Status::Pass,
+                format!("CLI {cli_version}"),
+            ));
+        }
+    }
+
+    // Extension — the build this CLI shipped alongside (embedded at compile time
+    // from the extension manifest) is what we expect to be running.
+    let expected_ext = env!("AB_CONNECT_VERSION");
+    match connect::relay_ext_version() {
+        Some(ext) if upgrade::version_is_newer(expected_ext, &ext) => {
+            checks.push(
+                Check::new(
+                    "versions.extension",
+                    category,
+                    Status::Warn,
+                    format!("extension {ext} is behind the bundled {expected_ext}"),
+                )
+                .with_fix(
+                    "update ab-connect in Chrome: chrome://extensions \u{2192} reload \
+                     (or wait for the Web Store auto-update)"
+                        .to_string(),
+                ),
+            );
+        }
+        Some(ext) => {
+            checks.push(Check::new(
+                "versions.extension",
+                category,
+                Status::Pass,
+                format!("extension {ext}"),
+            ));
+        }
+        None => {
+            checks.push(Check::new(
+                "versions.extension",
+                category,
+                Status::Info,
+                format!(
+                    "extension not connected (or it predates version reporting — \
+                     expected {expected_ext})"
+                ),
+            ));
+        }
+    }
+
+    // Skill — ships inside the same release artifact as the binary, so it's
+    // version-locked here. Copies made elsewhere via `skills add` aren't.
+    checks.push(Check::new(
+        "versions.skill",
+        category,
+        Status::Info,
+        format!(
+            "skills bundled with this CLI ({cli_version}); copies made via `skills add` \
+             elsewhere may be stale — re-run to refresh"
+        ),
+    ));
+}

cli/src/main.rs

@@ -11,6 +11,7 @@ mod install;
 mod native;
 mod output;
 mod skills;
+mod test_runner;
 #[cfg(test)]
 mod test_utils;
 mod upgrade;
@@ -28,8 +29,8 @@ use windows_sys::Win32::System::Threading::OpenProcess;
 
 use commands::{gen_id, parse_command, ParseError};
 use connection::{
-    cleanup_stale_files, ensure_daemon, get_socket_dir, is_pid_alive, send_command, walk_daemons,
-    DaemonOptions,
+    cleanup_stale_files, ensure_daemon, get_socket_dir, is_pid_alive, restart_all_daemons,
+    send_command, walk_daemons, DaemonOptions,
 };
 use flags::{clean_args, parse_flags, Flags};
 use install::run_install;
@@ -269,13 +270,19 @@ fn run_session(args: &[String], session: &str, json_mode: bool) {
                 .into_iter()
                 .map(|s| s.name)
                 .collect();
+            // The extension relay drives the user's live Chrome but isn't always
+            // registered as a launched daemon session — without surfacing it,
+            // `session list` says "No active sessions" while open/tab work fine,
+            // and agents misjudge the connection as down (issue #15).
+            let relay_up = connect::relay_url().is_some();
 
             if json_mode {
                 println!(
-                    r#"{{"success":true,"data":{{"sessions":{}}}}}"#,
-                    serde_json::to_string(&sessions).unwrap_or_default()
+                    r#"{{"success":true,"data":{{"sessions":{},"relay":{}}}}}"#,
+                    serde_json::to_string(&sessions).unwrap_or_default(),
+                    relay_up
                 );
-            } else if sessions.is_empty() {
+            } else if sessions.is_empty() && !relay_up {
                 println!("No active sessions");
             } else {
                 println!("Active sessions:");
@@ -287,6 +294,14 @@ fn run_session(args: &[String], session: &str, json_mode: bool) {
                     };
                     println!("{} {}", marker, s);
                 }
+                if relay_up && !sessions.iter().any(|s| s == session) {
+                    println!(
+                        "{} {} {}",
+                        color::cyan("→"),
+                        session,
+                        color::dim("(relay/extension → live Chrome)")
+                    );
+                }
             }
         }
         None | Some(_) => {
@@ -305,6 +320,94 @@ fn run_session(args: &[String], session: &str, json_mode: bool) {
     }
 }
 
+/// `chrome-use daemon <restart|status>` — manage the per-session daemon workers
+/// without resorting to `pgrep`/`kill`. `restart` clears corrupted or
+/// cross-leaked daemon state (e.g. after a mid-session `chrome-use upgrade`
+/// where stale tab handles bleed across sessions, issue #20) by killing every
+/// session worker. The Chrome-launched `__nm-host` native-messaging bridge is
+/// NOT a tracked session daemon, so the extension relay survives a restart —
+/// the next command spins up a fresh, clean daemon against the same live Chrome.
+fn run_daemon(args: &[String], json_mode: bool) {
+    match args.get(1).map(|s| s.as_str()) {
+        Some("restart") => {
+            let stopped = restart_all_daemons();
+            let relay_up = connect::relay_url().is_some();
+            if json_mode {
+                print_json_value(json!({
+                    "success": true,
+                    "data": { "stopped": stopped, "count": stopped.len(), "relay": relay_up },
+                }));
+            } else if stopped.is_empty() {
+                println!("No session daemons running — nothing to restart.");
+                if relay_up {
+                    println!(
+                        "{}",
+                        color::dim("Extension relay still up; next command starts a fresh daemon.")
+                    );
+                }
+            } else {
+                for s in &stopped {
+                    println!("{} Stopped daemon: {}", color::green("✓"), s);
+                }
+                println!(
+                    "{}",
+                    color::dim(if relay_up {
+                        "Extension relay (__nm-host) left running; next command starts a fresh daemon."
+                    } else {
+                        "Next command starts a fresh daemon."
+                    })
+                );
+            }
+        }
+        Some("status") | Some("list") => {
+            let inventory = walk_daemons();
+            let relay_up = connect::relay_url().is_some();
+            if json_mode {
+                let sessions: Vec<_> = inventory
+                    .sessions
+                    .iter()
+                    .map(|s| json!({ "name": s.name, "pid": s.pid, "version": s.version }))
+                    .collect();
+                print_json_value(json!({
+                    "success": true,
+                    "data": { "sessions": sessions, "relay": relay_up },
+                }));
+            } else if inventory.sessions.is_empty() {
+                println!("No session daemons running.");
+                if relay_up {
+                    println!("{}", color::dim("Extension relay (__nm-host): up"));
+                }
+            } else {
+                println!("Session daemons:");
+                for s in &inventory.sessions {
+                    let ver = s
+                        .version
+                        .as_deref()
+                        .map(|v| format!(" {}", color::dim(&format!("(v{})", v))))
+                        .unwrap_or_default();
+                    println!("  {} pid {}{}", s.name, s.pid, ver);
+                }
+                if relay_up {
+                    println!("{}", color::dim("Extension relay (__nm-host): up"));
+                }
+            }
+        }
+        other => {
+            eprintln!(
+                "{} usage: chrome-use daemon <restart|status>",
+                color::error_indicator()
+            );
+            if let Some(unknown) = other {
+                eprintln!(
+                    "{}",
+                    color::dim(&format!("  unknown subcommand: {}", unknown))
+                );
+            }
+            exit(2);
+        }
+    }
+}
+
 fn get_dashboard_pid_path() -> std::path::PathBuf {
     get_socket_dir().join("dashboard.pid")
 }
@@ -571,6 +674,17 @@ fn main() {
         return;
     }
 
+    // Hidden update-check worker, spawned detached by maybe_notify_update() to
+    // refresh the cached latest version without blocking a real command.
+    if env::args().nth(1).as_deref() == Some("__update-check") {
+        upgrade::run_update_check();
+        return;
+    }
+
+    // Non-blocking "update available" hint (stderr only; self-skips meta
+    // commands, daemon mode, CI, and the opt-out env vars).
+    upgrade::maybe_notify_update();
+
     // 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
@@ -707,6 +821,19 @@ fn main() {
         return;
     }
 
+    // Handle `test <suite.yaml>`: run a browser test suite. It orchestrates by
+    // re-invoking this binary per step, so it lives outside the normal dispatch.
+    if clean.first().map(|s| s.as_str()) == Some("test") {
+        let Some(suite) = clean.get(1) else {
+            eprintln!(
+                "{} usage: chrome-use test <suite.yaml> [--launch | --session <name>]",
+                color::error_indicator()
+            );
+            exit(2);
+        };
+        exit(test_runner::run_test(suite, &flags));
+    }
+
     // Handle skills command (doesn't need daemon)
     if clean.first().map(|s| s.as_str()) == Some("skills") {
         skills::run_skills(&clean, flags.json);
@@ -760,6 +887,20 @@ fn main() {
         return;
     }
 
+    // Handle daemon management (doesn't talk to a daemon — it manages them).
+    if clean.first().map(|s| s.as_str()) == Some("daemon") {
+        run_daemon(&clean, flags.json);
+        return;
+    }
+
+    // `sessions` is a natural top-level guess for "list my sessions" (the skill
+    // advertises sessions as a feature) — route it to the daemon inventory the
+    // same way `daemon status` does (issue #29).
+    if clean.first().map(|s| s.as_str()) == Some("sessions") {
+        run_daemon(&["sessions".to_string(), "status".to_string()], flags.json);
+        return;
+    }
+
     // Handle close --all: close all active sessions
     if matches!(
         clean.first().map(|s| s.as_str()),
@@ -1228,6 +1369,20 @@ fn main() {
         && flags.provider.is_none()
         && (flags.force_launch || !flags.auto_connect)
     {
+        // Launching a debug-port Chrome pops Chrome's "Allow remote debugging?"
+        // consent modal (Chrome 136+). When the ab-connect relay is already up,
+        // this is almost always unintended — the relay drives the user's real
+        // Chrome with NO modal. Warn so the modal is self-explained and the
+        // caller (often a stray --launch / --no-auto-connect) is fixable (#32).
+        if !flags.json && connect::relay_url().is_some() {
+            eprintln!(
+                "{} launching a new Chrome with a debug port — this pops Chrome's \
+                 \"Allow remote debugging?\" modal.\n  The ab-connect relay is up; \
+                 drop --launch/--new (and don't pass --no-auto-connect) to drive your \
+                 real Chrome with no modal.",
+                color::warning_indicator()
+            );
+        }
         let mut launch_cmd = json!({
             "id": gen_id(),
             "action": "launch",

cli/src/native/actions.rs

@@ -1332,6 +1332,7 @@ pub async fn execute_command(cmd: &Value, state: &mut DaemonState) -> Value {
         "uncheck" => handle_uncheck(cmd, state).await,
         "wait" => handle_wait(cmd, state).await,
         "gettext" => handle_gettext(cmd, state).await,
+        "frames" => handle_frames(cmd, state).await,
         "getattribute" => handle_getattribute(cmd, state).await,
         "isvisible" => handle_isvisible(cmd, state).await,
         "isenabled" => handle_isenabled(cmd, state).await,
@@ -1340,6 +1341,7 @@ pub async fn execute_command(cmd: &Value, state: &mut DaemonState) -> Value {
         "forward" => handle_forward(state).await,
         "reload" => handle_reload(state).await,
         "cookies_get" => handle_cookies_get(cmd, state).await,
+        "cf_status" => handle_cf_status(cmd, state).await,
         "cookies_set" => handle_cookies_set(cmd, state).await,
         "cookies_clear" => handle_cookies_clear(state).await,
         "storage_get" => handle_storage_get(cmd, state).await,
@@ -1364,7 +1366,7 @@ pub async fn execute_command(cmd: &Value, state: &mut DaemonState) -> Value {
         "recording_stop" => handle_recording_stop(state).await,
         "recording_restart" => handle_recording_restart(cmd, state).await,
         "pdf" => handle_pdf(cmd, state).await,
-        "tab_list" => handle_tab_list(state).await,
+        "tab_list" => handle_tab_list(cmd, state).await,
         "tab_new" => handle_tab_new(cmd, state).await,
         "tab_switch" => handle_tab_switch(cmd, state).await,
         "tab_close" => handle_tab_close(cmd, state).await,
@@ -1395,6 +1397,7 @@ pub async fn execute_command(cmd: &Value, state: &mut DaemonState) -> Value {
         "count" => handle_count(cmd, state).await,
         "styles" => handle_styles(cmd, state).await,
         "bringtofront" => handle_bringtofront(state).await,
+        "current" => handle_current(state).await,
         "timezone" => handle_timezone(cmd, state).await,
         "locale" => handle_locale(cmd, state).await,
         "geolocation" => handle_geolocation(cmd, state).await,
@@ -2531,6 +2534,20 @@ async fn handle_navigate(cmd: &Value, state: &mut DaemonState) -> Result<Value,
     state.ref_map.clear();
     state.iframe_sessions.clear();
     state.active_frame_id = None;
+
+    // `--reuse-tab`: if a tab already shows this URL (same origin+path), switch
+    // to it instead of navigating — preserves any in-page state and stops
+    // re-`open` from piling up duplicate tabs on rebind (issue #21).
+    if cmd
+        .get("reuseTab")
+        .and_then(|v| v.as_bool())
+        .unwrap_or(false)
+    {
+        if let Ok(Some(switched)) = mgr.reuse_tab_for_url(url).await {
+            return Ok(switched);
+        }
+    }
+
     let result = mgr.navigate(url, wait_until).await?;
     // Adaptive humanize: sample the freshly loaded page for known behavioural
     // anti-bot vendors and escalate this session to Human if any are present.
@@ -2874,7 +2891,41 @@ async fn handle_snapshot(cmd: &Value, state: &mut DaemonState) -> Result<Value,
         })
         .collect();
 
-    Ok(json!({ "snapshot": tree, "origin": url, "refs": refs }))
+    let ref_count = refs.len();
+    let mut out = json!({ "snapshot": tree, "origin": url, "refs": refs });
+
+    // Canvas/WebGL apps (games, map/3D viewers, drawing tools) paint to a
+    // <canvas> and expose almost no accessibility tree, so `snapshot` comes back
+    // near-empty and agents get stuck looking for refs that will never exist
+    // (dogfood: the Dead Cell game). When the tree is sparse but a canvas
+    // dominates the viewport, tell them to switch to the screenshot-driven path.
+    if ref_count < 3 {
+        let canvas_js =
+            "(() => { const c = document.querySelector('canvas'); if (!c) return false; \
+                         const r = c.getBoundingClientRect(); \
+                         return r.width * r.height > innerWidth * innerHeight * 0.5; })()";
+        if let Ok(v) = mgr.evaluate(canvas_js, None).await {
+            if v.as_bool() == Some(true) {
+                out["note"] = json!(
+                    "This page renders to a <canvas> (game / WebGL / editor) and exposes almost no \
+                     accessibility tree — refs won't help. Use `screenshot` to see it, coordinate \
+                     `click <x> <y>` to interact, and `keydown`/`keyup`/`press` for keyboard \
+                     (hold-to-move: `keydown d` … `keyup d`)."
+                );
+            }
+        }
+    }
+
+    Ok(out)
+}
+
+/// Resolve a (possibly relative) saved-file path to an absolute one so the CLI
+/// echoes a path the agent can read regardless of the process cwd (issue #16).
+/// Falls back to the original string if the file can't be canonicalized.
+fn absolutize_saved_path(p: &str) -> String {
+    std::fs::canonicalize(p)
+        .map(|c| c.to_string_lossy().into_owned())
+        .unwrap_or_else(|_| p.to_string())
 }
 
 async fn handle_screenshot(cmd: &Value, state: &mut DaemonState) -> Result<Value, String> {
@@ -2902,7 +2953,7 @@ async fn handle_screenshot(cmd: &Value, state: &mut DaemonState) -> Result<Value
                 .map_err(|e| format!("Base64 decode error: {}", e))?;
                 std::fs::write(p, bytes)
                     .map_err(|e| format!("Failed to write screenshot: {}", e))?;
-                return Ok(json!({ "path": p }));
+                return Ok(json!({ "path": absolutize_saved_path(p) }));
             }
             let tmp = format!(
                 "/tmp/screenshot-{}.png",
@@ -2949,6 +3000,14 @@ async fn handle_screenshot(cmd: &Value, state: &mut DaemonState) -> Result<Value
             .get("screenshotDir")
             .and_then(|v| v.as_str())
             .map(String::from),
+        clip: cmd.get("clip").and_then(|c| {
+            Some((
+                c.get("x")?.as_f64()?,
+                c.get("y")?.as_f64()?,
+                c.get("width")?.as_f64()?,
+                c.get("height")?.as_f64()?,
+            ))
+        }),
     };
 
     if annotate {
@@ -2976,7 +3035,7 @@ async fn handle_screenshot(cmd: &Value, state: &mut DaemonState) -> Result<Value
     )
     .await?;
 
-    let mut response = json!({ "path": result.path });
+    let mut response = json!({ "path": absolutize_saved_path(&result.path) });
     if !result.annotations.is_empty() {
         response["annotations"] = serde_json::to_value(&result.annotations)
             .map_err(|e| format!("Failed to serialize annotations: {}", e))?;
@@ -3068,6 +3127,15 @@ async fn handle_click(cmd: &Value, state: &mut DaemonState) -> Result<Value, Str
 
     let button = cmd.get("button").and_then(|v| v.as_str()).unwrap_or("left");
     let click_count = cmd.get("clickCount").and_then(|v| v.as_i64()).unwrap_or(1) as i32;
+    let follow = cmd.get("follow").and_then(|v| v.as_bool()).unwrap_or(false);
+
+    // Snapshot tracked targets so we can tell if this click opened a NEW tab
+    // (target=_blank link / window.open). On the relay the new tab is discovered
+    // passively and doesn't steal focus (#7/#8.1), so without surfacing it the
+    // post-click snapshot shows the OLD page and looks like the click failed
+    // (issue #24-A).
+    let before: std::collections::HashSet<String> =
+        mgr.pages_list().into_iter().map(|p| p.target_id).collect();
 
     interaction::click(
         &mgr.client,
@@ -3080,7 +3148,26 @@ async fn handle_click(cmd: &Value, state: &mut DaemonState) -> Result<Value, Str
     )
     .await?;
 
-    Ok(json!({ "clicked": selector }))
+    // Give a just-opened tab a moment to register, then look for it.
+    let mgr = state.browser.as_mut().ok_or("Browser not launched")?;
+    tokio::time::sleep(std::time::Duration::from_millis(150)).await;
+    let opened = mgr.adopt_newly_opened(&before).await;
+
+    let mut out = json!({ "clicked": selector });
+    if let Some(page) = opened {
+        let tab_id = super::browser::format_tab_id(page.tab_id);
+        out["openedTab"] = json!({ "tabId": tab_id, "url": page.url, "title": page.title });
+        // `--follow`: switch the active tab to the newly-opened one (default is
+        // to report it but stay put, so multi-tab flows aren't hijacked).
+        if follow {
+            state.ref_map.clear();
+            state.iframe_sessions.clear();
+            state.active_frame_id = None;
+            let _ = mgr.tab_switch_by_id(page.tab_id).await;
+            out["followed"] = json!(true);
+        }
+    }
+    Ok(out)
 }
 
 async fn handle_dblclick(cmd: &Value, state: &mut DaemonState) -> Result<Value, String> {
@@ -3286,6 +3373,16 @@ async fn handle_press(cmd: &Value, state: &mut DaemonState) -> Result<Value, Str
     // Parse modifier+key chords like "Control+a", "Shift+Enter", "Control+Shift+a"
     let (actual_key, modifiers) = parse_key_chord(key);
 
+    // `--hold <ms>`: keyDown, wait, keyUp — all inside the daemon so the hold
+    // duration is precise (no shell-sleep / round-trip jitter). For games
+    // (hold-to-move/charge) and any press-and-hold interaction.
+    if let Some(ms) = cmd.get("hold").and_then(|v| v.as_u64()) {
+        interaction::dispatch_single_key(&mgr.client, &session_id, &actual_key, "keyDown").await?;
+        tokio::time::sleep(std::time::Duration::from_millis(ms)).await;
+        interaction::dispatch_single_key(&mgr.client, &session_id, &actual_key, "keyUp").await?;
+        return Ok(json!({ "pressed": key, "heldMs": ms }));
+    }
+
     interaction::press_key_with_modifiers(&mgr.client, &session_id, &actual_key, modifiers).await?;
     Ok(json!({ "pressed": key }))
 }
@@ -3507,6 +3604,56 @@ async fn handle_wait(cmd: &Value, state: &mut DaemonState) -> Result<Value, Stri
 async fn handle_gettext(cmd: &Value, state: &mut DaemonState) -> Result<Value, String> {
     let mgr = state.browser.as_ref().ok_or("Browser not launched")?;
     let session_id = mgr.active_session_id()?.to_string();
+
+    // `get text --all-frames` aggregates visible text across every frame the
+    // session can reach — including out-of-process iframes that never show up
+    // in the top document (#27: Yahoo/Rakuten/Mercari listing descriptions).
+    if cmd.get("allFrames").and_then(|v| v.as_bool()) == Some(true) {
+        let frames = super::element::collect_all_frames_text(
+            &mgr.client,
+            &session_id,
+            &state.iframe_sessions,
+        )
+        .await?;
+        let mut combined = String::new();
+        let mut frame_count = 0usize;
+        for f in &frames {
+            let t = f.text.trim();
+            if t.is_empty() {
+                continue;
+            }
+            frame_count += 1;
+            if f.kind != "top" {
+                combined.push_str(&format!("\n\n----- frame [{}] {} -----\n", f.kind, f.url));
+            }
+            combined.push_str(t);
+        }
+        let url = mgr.get_url().await.unwrap_or_default();
+        return Ok(json!({
+            "text": combined,
+            "origin": url,
+            "frames": frame_count,
+            "allFrames": true,
+        }));
+    }
+
+    // `get text --pierce` reads text through CLOSED shadow roots and child
+    // documents via the CDP DOM tree — content `innerText`/`eval` can't see,
+    // e.g. an extension's injected panel in a closed shadow DOM (#30).
+    if cmd.get("pierce").and_then(|v| v.as_bool()) == Some(true) {
+        let text = super::element::get_pierced_text(&mgr.client, &session_id).await?;
+        let url = mgr.get_url().await.unwrap_or_default();
+        return Ok(json!({ "text": text, "origin": url, "pierce": true }));
+    }
+
+    // `get text --main` returns the page's main-content region (readability-lite),
+    // skipping global header/nav/footer/sidebar boilerplate (#27).
+    if cmd.get("main").and_then(|v| v.as_bool()) == Some(true) {
+        let text = super::element::get_main_content_text(&mgr.client, &session_id).await?;
+        let url = mgr.get_url().await.unwrap_or_default();
+        return Ok(json!({ "text": text, "origin": url, "main": true }));
+    }
+
     let selector = cmd
         .get("selector")
         .and_then(|v| v.as_str())
@@ -3524,6 +3671,32 @@ async fn handle_gettext(cmd: &Value, state: &mut DaemonState) -> Result<Value, S
     Ok(json!({ "text": text, "origin": url }))
 }
 
+async fn handle_frames(_cmd: &Value, state: &mut DaemonState) -> Result<Value, String> {
+    let mgr = state.browser.as_ref().ok_or("Browser not launched")?;
+    let session_id = mgr.active_session_id()?.to_string();
+    let frames = super::element::collect_all_frames_text(
+        &mgr.client,
+        &session_id,
+        &state.iframe_sessions,
+    )
+    .await?;
+    let list: Vec<Value> = frames
+        .iter()
+        .enumerate()
+        .map(|(i, f)| {
+            json!({
+                "index": i,
+                "kind": f.kind,
+                "url": f.url,
+                "frameId": f.frame_id,
+                "textLen": f.text.trim().chars().count(),
+            })
+        })
+        .collect();
+    let url = mgr.get_url().await.unwrap_or_default();
+    Ok(json!({ "frames": list, "count": list.len(), "origin": url }))
+}
+
 async fn handle_getattribute(cmd: &Value, state: &mut DaemonState) -> Result<Value, String> {
     let mgr = state.browser.as_ref().ok_or("Browser not launched")?;
     let session_id = mgr.active_session_id()?.to_string();
@@ -3958,6 +4131,108 @@ async fn handle_cookies_clear(state: &DaemonState) -> Result<Value, String> {
     Ok(json!({ "cleared": true }))
 }
 
+// Detect whether the active page is *currently* a Cloudflare challenge
+// (the full-page "Just a moment…" / "正在进行安全验证" interstitial), so an agent
+// knows whether it must solve or can proceed. Runs in the top frame main world.
+const CF_CHALLENGE_JS: &str = r#"(function(){
+  var t = document.title || '';
+  var challenged =
+    /just a moment|attention required|checking (your|if)|verify you are human|正在进行安全验证|安全验证|请稍候|请完成|人机验证/i.test(t) ||
+    !!document.querySelector('#challenge-form, #challenge-running, #cf-challenge-running, [id^="cf-chl"], script[src*="/cdn-cgi/challenge-platform/"]');
+  var turnstile = !!document.querySelector('.cf-turnstile, [data-sitekey]');
+  return JSON.stringify({ title: t, challenged: challenged, turnstile: turnstile, readyState: document.readyState });
+})()"#;
+
+/// Recommendation for a Cloudflare-gated page, from the current challenge state
+/// and whether a still-valid `cf_clearance` exists. Pure so it's unit-testable.
+/// - not challenged            → "proceed" (the page is cleared/loaded)
+/// - challenged, valid cookie  → "reissue" (clearance present but page still
+///   blocks → it's stale or the IP/UA no longer matches what it was issued for)
+/// - challenged, no cookie     → "solve"
+fn cf_recommendation(challenged: bool, clearance_valid: bool) -> &'static str {
+    if !challenged {
+        "proceed"
+    } else if clearance_valid {
+        "reissue"
+    } else {
+        "solve"
+    }
+}
+
+/// `cf_clearance` validity for a cookie's expiry (epoch seconds; <=0 = session
+/// cookie, treated as non-expiring). Returns (present, expired). Pure.
+fn clearance_state(expires: Option<f64>, now: f64) -> (bool, bool) {
+    match expires {
+        None => (false, false),
+        Some(e) if e <= 0.0 => (true, false), // session cookie: no expiry
+        Some(e) => (true, e < now),
+    }
+}
+
+async fn handle_cf_status(_cmd: &Value, state: &mut DaemonState) -> Result<Value, String> {
+    let mgr = state.browser.as_ref().ok_or("Browser not launched")?;
+    let session_id = mgr.active_session_id()?.to_string();
+    let url = mgr.get_url().await.unwrap_or_default();
+
+    // 1. Is the page a Cloudflare challenge right now?
+    let probe_raw = mgr.evaluate(CF_CHALLENGE_JS, None).await.unwrap_or(Value::Null);
+    let probe = parse_json_string(probe_raw, "cf challenge probe").unwrap_or(Value::Null);
+    let challenged = probe
+        .get("challenged")
+        .and_then(|v| v.as_bool())
+        .unwrap_or(false);
+    let turnstile = probe
+        .get("turnstile")
+        .and_then(|v| v.as_bool())
+        .unwrap_or(false);
+    let title = probe
+        .get("title")
+        .and_then(|v| v.as_str())
+        .unwrap_or("")
+        .to_string();
+
+    // 2. Persistence artifacts: cf_clearance (HttpOnly → must read via CDP, not
+    //    document.cookie) + CF_VERIFIED_DEVICE. Scope to the current URL.
+    let urls = if url.is_empty() {
+        None
+    } else {
+        Some(vec![url.clone()])
+    };
+    let cookies = super::cookies::get_cookies(&mgr.client, &session_id, urls)
+        .await
+        .unwrap_or_default();
+    let clearance = cookies.iter().find(|c| c.name == "cf_clearance");
+    let now = std::time::SystemTime::now()
+        .duration_since(std::time::UNIX_EPOCH)
+        .map(|d| d.as_secs_f64())
+        .unwrap_or(0.0);
+    let (present, expired) = clearance_state(clearance.map(|c| c.expires), now);
+    let expires_in = clearance
+        .filter(|_| present && !expired)
+        .map(|c| (c.expires - now).max(0.0) as i64);
+    let device_verified = cookies
+        .iter()
+        .any(|c| c.name.starts_with("CF_VERIFIED_DEVICE"));
+
+    let clearance_valid = present && !expired;
+    let recommendation = cf_recommendation(challenged, clearance_valid);
+
+    Ok(json!({
+        "url": url,
+        "title": title,
+        "challenged": challenged,
+        "turnstile": turnstile,
+        "clearance": {
+            "present": present,
+            "expired": expired,
+            "expiresIn": expires_in,
+            "httpOnly": clearance.map(|c| c.http_only).unwrap_or(false),
+        },
+        "deviceVerified": device_verified,
+        "recommendation": recommendation,
+    }))
+}
+
 async fn handle_storage_get(cmd: &Value, state: &DaemonState) -> Result<Value, String> {
     let mgr = state.browser.as_ref().ok_or("Browser not launched")?;
     let session_id = mgr.active_session_id()?.to_string();
@@ -4346,10 +4621,19 @@ async fn handle_keyboard(cmd: &Value, state: &DaemonState) -> Result<Value, Stri
 // Phase 5 handlers
 // ---------------------------------------------------------------------------
 
-async fn handle_tab_list(state: &DaemonState) -> Result<Value, String> {
-    let mgr = state.browser.as_ref().ok_or("Browser not launched")?;
+async fn handle_tab_list(cmd: &Value, state: &mut DaemonState) -> Result<Value, String> {
+    let mgr = state.browser.as_mut().ok_or("Browser not launched")?;
+    // Re-sync with the live browser so the list reflects tabs opened by other
+    // sessions or re-attached after a cross-process nav, and drops gone ones
+    // (issue #21). Best-effort: a stale list still beats erroring the command.
+    mgr.resync_targets().await.ok();
     let tabs = mgr.tab_list();
-    Ok(json!({ "tabs": tabs }))
+    // Echo `full` so the formatter prints untruncated URLs (issue #19).
+    if cmd.get("full").and_then(|v| v.as_bool()).unwrap_or(false) {
+        Ok(json!({ "tabs": tabs, "full": true }))
+    } else {
+        Ok(json!({ "tabs": tabs }))
+    }
 }
 
 async fn handle_tab_new(cmd: &Value, state: &mut DaemonState) -> Result<Value, String> {
@@ -4380,13 +4664,50 @@ async fn handle_tab_switch(cmd: &Value, state: &mut DaemonState) -> Result<Value
     let tab_ref_str = cmd
         .get("tabId")
         .and_then(|v| v.as_str())
-        .ok_or("Missing 'tabId' parameter (expected `t<N>` or a label)")?;
-    let tab_ref = super::browser::TabRef::parse(tab_ref_str)?;
-    let tab_id = mgr.resolve_tab_ref(&tab_ref)?;
+        .ok_or("Missing 'tabId' parameter (expected `t<N>`, a label, or a targetId)")?;
+    // Re-sync first so a tab opened by another session, or one that re-attached
+    // after a cross-process nav, is adoptable from here (issue #21).
+    mgr.resync_targets().await.ok();
+    // A CDP `targetId` (shown in `tab list`) is stable across sessions, so accept
+    // it directly for adopting a specific pre-existing tab — falling back to the
+    // per-session `t<N>` / label form.
+    let tab_id = match mgr.tab_id_for_target(tab_ref_str) {
+        Some(id) => id,
+        None => {
+            let tab_ref = super::browser::TabRef::parse(tab_ref_str)?;
+            mgr.resolve_tab_ref(&tab_ref)?
+        }
+    };
     state.ref_map.clear();
     state.iframe_sessions.clear();
     state.active_frame_id = None;
-    let result = mgr.tab_switch_by_id(tab_id).await?;
+    let mut result = mgr.tab_switch_by_id(tab_id).await?;
+
+    // Liveness probe: confirm the new session actually answers before we report
+    // success, so `tab <id>` doesn't print a misleading ✓ for a session that's
+    // stale and will fail on the very next command (issue #29.3). On the churned
+    // -tabId case the ext-0.4.9 targetId recovery (#24) self-heals within ~6s, so
+    // we surface a warning rather than a hard error to avoid a false failure
+    // during that window.
+    if mgr.evaluate("1", None).await.is_err() {
+        if let Some(obj) = result.as_object_mut() {
+            obj.insert(
+                "warning".to_string(),
+                json!("switched tab is not responding yet (session re-attaching); retry the next command"),
+            );
+        }
+    }
+
+    // `--activate`: raise this tab to the foreground (the switch made it active;
+    // bring_to_front acts on the active tab) — for handing a specific tab to the
+    // human (issue #24-C). Best-effort; don't fail the switch if it can't.
+    if cmd
+        .get("activate")
+        .and_then(|v| v.as_bool())
+        .unwrap_or(false)
+    {
+        let _ = mgr.bring_to_front().await;
+    }
 
     if let Some(ref server) = state.stream_server {
         if let Ok(dims) = mgr
@@ -5216,6 +5537,18 @@ async fn handle_bringtofront(state: &DaemonState) -> Result<Value, String> {
     Ok(json!({ "broughtToFront": true }))
 }
 
+async fn handle_current(state: &mut DaemonState) -> Result<Value, String> {
+    let mgr = state.browser.as_mut().ok_or("Browser not launched")?;
+    // Refresh so `current` reflects the live URL/title even after a cross-process
+    // nav (the relay's cached target_info can lag) (#26).
+    mgr.resync_targets().await.ok();
+    let mut info = mgr.active_page_info().ok_or("No active tab")?;
+    if let Some(obj) = info.as_object_mut() {
+        obj.insert("current".to_string(), json!(true));
+    }
+    Ok(info)
+}
+
 async fn handle_timezone(cmd: &Value, state: &DaemonState) -> Result<Value, String> {
     let mgr = state.browser.as_ref().ok_or("Browser not launched")?;
     let timezone = cmd
@@ -7121,6 +7454,7 @@ async fn handle_diff_screenshot(cmd: &Value, state: &DaemonState) -> Result<Valu
         quality: None,
         annotate: false,
         output_dir: None,
+        clip: None,
     };
 
     let result = screenshot::take_screenshot(
@@ -8717,13 +9051,7 @@ async fn handle_keydown(cmd: &Value, state: &DaemonState) -> Result<Value, Strin
         .and_then(|v| v.as_str())
         .ok_or("Missing 'key' parameter")?;
 
-    mgr.client
-        .send_command(
-            "Input.dispatchKeyEvent",
-            Some(json!({ "type": "keyDown", "key": key })),
-            Some(&session_id),
-        )
-        .await?;
+    interaction::dispatch_single_key(&mgr.client, &session_id, key, "keyDown").await?;
     Ok(json!({ "keydown": key }))
 }
 
@@ -8735,13 +9063,7 @@ async fn handle_keyup(cmd: &Value, state: &DaemonState) -> Result<Value, String>
         .and_then(|v| v.as_str())
         .ok_or("Missing 'key' parameter")?;
 
-    mgr.client
-        .send_command(
-            "Input.dispatchKeyEvent",
-            Some(json!({ "type": "keyUp", "key": key })),
-            Some(&session_id),
-        )
-        .await?;
+    interaction::dispatch_single_key(&mgr.client, &session_id, key, "keyUp").await?;
     Ok(json!({ "keyup": key }))
 }
 
@@ -8859,6 +9181,26 @@ mod tests {
     use crate::test_utils::EnvGuard;
     use std::fs;
 
+    #[test]
+    fn test_cf_recommendation() {
+        assert_eq!(cf_recommendation(false, false), "proceed");
+        assert_eq!(cf_recommendation(false, true), "proceed");
+        assert_eq!(cf_recommendation(true, false), "solve");
+        assert_eq!(cf_recommendation(true, true), "reissue");
+    }
+
+    #[test]
+    fn test_clearance_state() {
+        // no cookie
+        assert_eq!(clearance_state(None, 1000.0), (false, false));
+        // session cookie (expires <= 0) → present, never expired
+        assert_eq!(clearance_state(Some(-1.0), 1000.0), (true, false));
+        // valid: expiry in the future
+        assert_eq!(clearance_state(Some(2000.0), 1000.0), (true, false));
+        // expired: expiry in the past
+        assert_eq!(clearance_state(Some(500.0), 1000.0), (true, true));
+    }
+
     #[test]
     fn test_url_glob_to_regex() {
         assert_eq!(url_glob_to_regex("**/dashboard"), "^.*/dashboard$");

cli/src/native/browser.rs

@@ -106,10 +106,22 @@ pub(crate) fn should_track_target(target: &TargetInfo) -> bool {
         && (target.url.is_empty() || !is_internal_chrome_target(&target.url))
 }
 
+/// Origin + path of a URL, dropping the query string and fragment, for
+/// `--reuse-tab` matching. SPA/SSO URLs carry volatile `?client_id=…&state=…`
+/// and `#/route` parts, so two opens of the "same" page rarely match
+/// byte-for-byte; comparing origin+path lands the reuse on the right tab.
+/// Returns the input unchanged if it doesn't parse as a URL.
+fn normalize_url_for_match(url: &str) -> String {
+    match url::Url::parse(url) {
+        Ok(u) => format!("{}{}", u.origin().ascii_serialization(), u.path()),
+        Err(_) => url.to_string(),
+    }
+}
+
 fn update_page_target_info_in_pages(pages: &mut [PageInfo], target: &TargetInfo) -> bool {
     if let Some(page) = pages.iter_mut().find(|p| p.target_id == target.target_id) {
         page.url = target.url.clone();
-        page.title = target.title.clone();
+        page.title = sanitize_title(&target.title);
         page.target_type = target.target_type.clone();
         return true;
     }
@@ -136,6 +148,112 @@ fn active_page_index_after_removal(
     active_page_index
 }
 
+/// Resolve the session's active page index: prefer the pinned `active_target_id`
+/// (stable across tab reorder / passive discovery / removal), falling back to the
+/// raw `active_page_index` only when nothing is pinned or the pin is gone. Keeping
+/// commands anchored to the pinned target is what stops `eval`/`get url`/`snapshot`
+/// from drifting onto a foreign tab between commands (issue #14).
+fn resolve_active_index(
+    pages: &[PageInfo],
+    active_target_id: Option<&str>,
+    active_page_index: usize,
+) -> usize {
+    if let Some(tid) = active_target_id {
+        if let Some(i) = pages.iter().position(|p| p.target_id == tid) {
+            return i;
+        }
+    }
+    active_page_index
+}
+
+/// Strip zero-width / invisible / bidi-format Unicode from a page title before
+/// we store it. Some sites prepend runs of ZWJ / word-joiner / invisible-times /
+/// BOM to `document.title` (badging, watermarking, anti-scrape); left in, they
+/// pollute `tab list`, break text matching, and wreck column alignment (#33).
+fn sanitize_title(s: &str) -> String {
+    s.chars()
+        .filter(|&c| {
+            !matches!(c as u32,
+                0x00AD            // soft hyphen
+                | 0x200B..=0x200F // ZWSP, ZWNJ, ZWJ, LRM, RLM
+                | 0x2028 | 0x2029 // line / paragraph separators
+                | 0x202A..=0x202E // bidi embedding/override
+                | 0x2060..=0x2064 // word joiner, invisible operators
+                | 0x2066..=0x2069 // bidi isolates
+                | 0x180E          // Mongolian vowel separator
+                | 0xFEFF          // BOM / ZW no-break space
+            )
+        })
+        .collect::<String>()
+        .trim()
+        .to_string()
+}
+
+/// Best-effort MIME type from a filename extension, for the relay file-upload
+/// fallback (the page-constructed `File` needs a sensible `type`). Covers the
+/// common upload kinds; anything unknown falls back to a generic binary type.
+fn mime_for_path(name: &str) -> &'static str {
+    let ext = name.rsplit('.').next().unwrap_or("").to_lowercase();
+    match ext.as_str() {
+        "png" => "image/png",
+        "jpg" | "jpeg" => "image/jpeg",
+        "gif" => "image/gif",
+        "webp" => "image/webp",
+        "svg" => "image/svg+xml",
+        "bmp" => "image/bmp",
+        "pdf" => "application/pdf",
+        "txt" => "text/plain",
+        "csv" => "text/csv",
+        "json" => "application/json",
+        "mp4" => "video/mp4",
+        "webm" => "video/webm",
+        "mov" => "video/quicktime",
+        "mp3" => "audio/mpeg",
+        "zip" => "application/zip",
+        _ => "application/octet-stream",
+    }
+}
+
+/// Target ids to prune after a `Target.getTargets` resync: tracked pages whose
+/// target is no longer in the live set — EXCEPT the explicitly-pinned active
+/// target, which is protected. The relay against a busy real Chrome occasionally
+/// returns a different window's tabs for a single `getTargets` call ("tab list
+/// hops windows", issue #31); pruning on that transient snapshot would drop the
+/// agent's adopted tab and drift subsequent eval/click onto a foreign tab. A
+/// genuine close still arrives as `Target.targetDestroyed` (handled in the event
+/// drain), which removes the pin properly — so protecting it here only guards
+/// against flaky snapshots, not real closures.
+fn prunable_target_ids(
+    pages: &[PageInfo],
+    live_ids: &HashSet<String>,
+    pinned: Option<&str>,
+) -> Vec<String> {
+    pages
+        .iter()
+        .map(|p| p.target_id.clone())
+        .filter(|tid| !live_ids.contains(tid) && pinned != Some(tid.as_str()))
+        .collect()
+}
+
+/// Whether the resolved active page is a tab the session created (its target_id
+/// is in `created_targets`). Pure core of [`BrowserManager::active_is_session_owned`]
+/// so the relay no-hijack rule is unit-testable without a live browser.
+fn active_index_is_owned(
+    pages: &[PageInfo],
+    active_target_id: Option<&str>,
+    active_page_index: usize,
+    created_targets: &HashSet<String>,
+) -> bool {
+    pages
+        .get(resolve_active_index(
+            pages,
+            active_target_id,
+            active_page_index,
+        ))
+        .map(|p| created_targets.contains(&p.target_id))
+        .unwrap_or(false)
+}
+
 /// Converts common error messages into AI-friendly, actionable descriptions.
 pub fn to_ai_friendly_error(error: &str) -> String {
     let lower = error.to_lowercase();
@@ -441,6 +559,13 @@ impl BrowserManager {
             }
         };
 
+        // A launched browser carries a debug port → it's the other path that can
+        // pop Chrome's consent modal; record it for #31 diagnosis.
+        crate::connect::log_connect_mode(
+            &ws_url,
+            true,
+            DAEMON_SESSION.get().map(String::as_str).unwrap_or("default"),
+        );
         let manager = if engine == "lightpanda" {
             initialize_lightpanda_manager(ws_url, process).await?
         } else {
@@ -536,6 +661,13 @@ impl BrowserManager {
         headers: Option<Vec<(String, String)>>,
     ) -> Result<Self, String> {
         let ws_url = resolve_cdp_url(url).await?;
+        // Record the transport so a reappearing "Allow remote debugging?" modal
+        // can be traced to a raw-port attach vs the consent-free relay (#31).
+        crate::connect::log_connect_mode(
+            &ws_url,
+            false,
+            DAEMON_SESSION.get().map(String::as_str).unwrap_or("default"),
+        );
         let client = Arc::new(CdpClient::connect_with_headers(&ws_url, headers).await?);
         let mut manager = Self {
             client,
@@ -664,7 +796,7 @@ impl BrowserManager {
                     target_id: target.target_id.clone(),
                     session_id: attach_result.session_id.clone(),
                     url: target.url.clone(),
-                    title: target.title.clone(),
+                    title: sanitize_title(&target.title),
                     target_type: target.target_type.clone(),
                 });
             }
@@ -762,12 +894,25 @@ impl BrowserManager {
     /// falling back to `active_page_index` when nothing is pinned or the pin is
     /// gone. This is what keeps commands on the tab the agent actually opened.
     fn resolved_active_index(&self) -> usize {
-        if let Some(tid) = &self.active_target_id {
-            if let Some(i) = self.pages.iter().position(|p| &p.target_id == tid) {
-                return i;
-            }
-        }
-        self.active_page_index
+        resolve_active_index(
+            &self.pages,
+            self.active_target_id.as_deref(),
+            self.active_page_index,
+        )
+    }
+
+    /// Whether the resolved active page is a tab THIS session created (via
+    /// `Target.createTarget` — `tab new`, `ensure_page`, or the first `open`).
+    /// On the shared real browser a fresh session also passively attaches to the
+    /// user's existing tabs; those are NOT owned, and navigating one would
+    /// clobber the user's page. Used to gate `navigate` on the relay.
+    fn active_is_session_owned(&self) -> bool {
+        active_index_is_owned(
+            &self.pages,
+            self.active_target_id.as_deref(),
+            self.active_page_index,
+            &self.created_targets,
+        )
     }
 
     /// Pin the current active page by target_id so later commands stick to it.
@@ -787,6 +932,18 @@ impl BrowserManager {
     }
 
     pub async fn navigate(&mut self, url: &str, wait_until: WaitUntil) -> Result<Value, String> {
+        // On the shared real browser (extension relay), a fresh session only
+        // passively attached to the user's existing tabs — it doesn't own any. The
+        // pre-fix code made one of those the active tab, so the first `open` then
+        // navigated (clobbered) the user's page: in dogfooding an `open` replaced a
+        // half-filled form with the target site. If the active tab isn't one we
+        // created, open our own tab in this session's group and navigate THAT, so
+        // the user's (and other sessions') tabs are never hijacked. Off the relay
+        // (a browser we launched) reusing the active tab is correct, so this is
+        // gated on `agent_group()`.
+        if self.agent_group().is_some() && !self.active_is_session_owned() {
+            self.tab_new(None, None).await?;
+        }
         let session_id = self.active_session_id()?.to_string();
         let mut lifecycle_rx = self.client.subscribe();
 
@@ -854,10 +1011,20 @@ impl BrowserManager {
             }
         }
 
+        // An explicit `open`/navigate IS the "explicit open" the pin invariant is
+        // built around (see `active_target_id`). On the relay path `open` reuses an
+        // existing tab via this method rather than `add_page`, so without pinning
+        // here `active_target_id` stayed `None` and the session rode the fragile
+        // `active_page_index` — a later passive tab close/reorder then drifted
+        // `eval`/`get url`/`snapshot` onto a foreign tab between commands (issue
+        // #14). Sync the index to the resolved active page, then pin it by stable
+        // target_id so subsequent commands stick to the tab we just navigated.
+        self.active_page_index = self.resolved_active_index();
         if let Some(page) = self.pages.get_mut(self.active_page_index) {
             page.url = page_url.clone();
-            page.title = title.clone();
+            page.title = sanitize_title(&title);
         }
+        self.pin_active_target();
 
         let mut out = json!({ "url": page_url, "title": title });
         if let Some(w) = nav_warning {
@@ -917,7 +1084,7 @@ impl BrowserManager {
 
     pub async fn get_title(&self) -> Result<String, String> {
         let result = self.evaluate_simple("document.title").await?;
-        Ok(result.as_str().unwrap_or("").to_string())
+        Ok(sanitize_title(result.as_str().unwrap_or("")))
     }
 
     pub async fn get_content(&self) -> Result<String, String> {
@@ -1124,6 +1291,9 @@ impl BrowserManager {
             target_type: "page".to_string(),
         });
         self.active_page_index = 0;
+        // Pin this freshly-created tab (matches `add_page`) so it's a stable
+        // anchor from the first command, not a bare index (issue #14).
+        self.pin_active_target();
         self.enable_domains(&attach_result.session_id).await?;
 
         Ok(())
@@ -1154,22 +1324,242 @@ impl BrowserManager {
     }
 
     pub fn tab_list(&self) -> Vec<Value> {
+        let active = self.resolved_active_index();
         self.pages
             .iter()
             .enumerate()
             .map(|(i, p)| {
                 json!({
                     "tabId": format_tab_id(p.tab_id),
+                    // Stable CDP target id. Unlike `t<N>` (per-session, reassigned
+                    // each connect) this is the same handle across every session
+                    // attached to the relayed Chrome, so it's how you adopt a
+                    // specific pre-existing tab from another session (issue #21).
+                    "targetId": p.target_id,
                     "label": p.label,
                     "title": p.title,
                     "url": p.url,
                     "type": p.target_type,
-                    "active": i == self.active_page_index,
+                    "active": i == active,
                 })
             })
             .collect()
     }
 
+    /// The active tab's stable handle + current location, for `chrome-use
+    /// current` (#26). `targetId` survives cross-process navigation, so it's the
+    /// handle an agent should hold across a multi-step flow.
+    pub fn active_page_info(&self) -> Option<Value> {
+        let i = self.resolved_active_index();
+        self.pages.get(i).map(|p| {
+            json!({
+                "tabId": format_tab_id(p.tab_id),
+                "targetId": p.target_id,
+                "label": p.label,
+                "url": p.url,
+                "title": p.title,
+            })
+        })
+    }
+
+    /// Stable `tab_id` for a page identified by its CDP `targetId`, if tracked.
+    /// Lets callers adopt a tab by the cross-session-stable target id.
+    pub fn tab_id_for_target(&self, target_id: &str) -> Option<u32> {
+        self.pages
+            .iter()
+            .find(|p| p.target_id == target_id)
+            .map(|p| p.tab_id)
+    }
+
+    /// Re-pull the live target set and reconcile `self.pages`: adopt tabs that
+    /// appeared since connect (another session's tab, or one that just
+    /// re-attached after a cross-process nav), refresh url/title on known tabs,
+    /// and drop tabs that are gone (clearing phantom rows). Never steals focus —
+    /// the active tab is preserved, and re-pinned if it was pruned. Powers a live
+    /// `tab list` and adopt-by-targetId so a fresh session can reach a stranded,
+    /// still-filled tab without reloading it (issue #21).
+    /// Detect targets that appeared since the `before` set (e.g. a click that
+    /// opened a new tab via a `target=_blank` link or `window.open`), attach +
+    /// track each in the background, and return the first newly-opened page.
+    ///
+    /// Lighter than [`resync_targets`] — one `getTargets` and work only on the
+    /// new targets, no whole-tab url/title refresh — so it's cheap enough to run
+    /// after every click. The new tab is added in the background (never steals
+    /// the active tab, per #7/#8.1); the caller surfaces it so the agent knows a
+    /// tab opened instead of seeing the old page (issue #24-A).
+    pub async fn adopt_newly_opened(&mut self, before: &HashSet<String>) -> Option<PageInfo> {
+        let result: GetTargetsResult = self
+            .client
+            .send_command_typed("Target.getTargets", &json!({}), None)
+            .await
+            .ok()?;
+        let live: Vec<TargetInfo> = result
+            .target_infos
+            .into_iter()
+            .filter(should_track_target)
+            .collect();
+        let mut opened: Option<PageInfo> = None;
+        for target in &live {
+            if before.contains(&target.target_id)
+                || self.pages.iter().any(|p| p.target_id == target.target_id)
+            {
+                continue;
+            }
+            let attach: AttachToTargetResult = match self
+                .client
+                .send_command_typed(
+                    "Target.attachToTarget",
+                    &AttachToTargetParams {
+                        target_id: target.target_id.clone(),
+                        flatten: true,
+                    },
+                    None,
+                )
+                .await
+            {
+                Ok(r) => r,
+                Err(_) => continue,
+            };
+            let tab_id = self.assign_tab_id();
+            let page = PageInfo {
+                tab_id,
+                label: None,
+                target_id: target.target_id.clone(),
+                session_id: attach.session_id.clone(),
+                url: target.url.clone(),
+                title: sanitize_title(&target.title),
+                target_type: target.target_type.clone(),
+            };
+            self.add_background_page(page.clone());
+            let _ = self.enable_domains(&attach.session_id).await;
+            if opened.is_none() {
+                opened = Some(page);
+            }
+        }
+        opened
+    }
+
+    pub async fn resync_targets(&mut self) -> Result<(), String> {
+        self.client
+            .send_command_typed::<_, Value>(
+                "Target.setDiscoverTargets",
+                &SetDiscoverTargetsParams { discover: true },
+                None,
+            )
+            .await?;
+        let result: GetTargetsResult = self
+            .client
+            .send_command_typed("Target.getTargets", &json!({}), None)
+            .await?;
+        let live: Vec<TargetInfo> = result
+            .target_infos
+            .into_iter()
+            .filter(should_track_target)
+            .collect();
+        let live_ids: HashSet<String> = live.iter().map(|t| t.target_id.clone()).collect();
+
+        for target in &live {
+            if self.update_page_target_info(target) {
+                continue;
+            }
+            // A target this session hasn't tracked yet — attach and add it in the
+            // background so it's listable/adoptable without stealing the active tab.
+            let attach_result: AttachToTargetResult = match self
+                .client
+                .send_command_typed(
+                    "Target.attachToTarget",
+                    &AttachToTargetParams {
+                        target_id: target.target_id.clone(),
+                        flatten: true,
+                    },
+                    None,
+                )
+                .await
+            {
+                Ok(r) => r,
+                // The tab may have closed between getTargets and attach, or be a
+                // restricted page — skip it rather than failing the whole resync.
+                Err(_) => continue,
+            };
+            let tab_id = self.assign_tab_id();
+            self.add_background_page(PageInfo {
+                tab_id,
+                label: None,
+                target_id: target.target_id.clone(),
+                session_id: attach_result.session_id.clone(),
+                url: target.url.clone(),
+                title: sanitize_title(&target.title),
+                target_type: target.target_type.clone(),
+            });
+            let _ = self.enable_domains(&attach_result.session_id).await;
+        }
+
+        // Drop tabs that no longer exist so `tab list` doesn't show phantom rows —
+        // but never prune the explicitly-pinned active target on a transient
+        // getTargets snapshot (issue #31; see `prunable_target_ids`).
+        let gone = prunable_target_ids(&self.pages, &live_ids, self.active_target_id.as_deref());
+        for tid in gone {
+            self.remove_page_by_target_id(&tid);
+        }
+
+        // Refresh url/title from each live tab. The relay only stamps target_info
+        // on attach, so after a navigation its cached url/title go stale (or stay
+        // blank for a tab attached at about:blank) — which made `tab list` show
+        // blank rows you couldn't tell apart, defeating the point of listing them
+        // to pick a tab to adopt (issue #21). `Target.getTargetInfo` is a plain
+        // CDP read (no Runtime fingerprint), one cheap call per tab.
+        let sessions: Vec<(usize, String)> = self
+            .pages
+            .iter()
+            .enumerate()
+            .map(|(i, p)| (i, p.session_id.clone()))
+            .collect();
+        for (i, sid) in sessions {
+            if sid.is_empty() {
+                continue;
+            }
+            if let Ok(resp) = self
+                .client
+                .send_command("Target.getTargetInfo", None, Some(&sid))
+                .await
+            {
+                if let Some(ti) = resp.get("targetInfo") {
+                    if let Some(page) = self.pages.get_mut(i) {
+                        if let Some(u) = ti.get("url").and_then(|v| v.as_str()) {
+                            if !u.is_empty() {
+                                page.url = u.to_string();
+                            }
+                        }
+                        if let Some(t) = ti.get("title").and_then(|v| v.as_str()) {
+                            page.title = sanitize_title(t);
+                        }
+                    }
+                }
+            }
+        }
+        Ok(())
+    }
+
+    /// If `--reuse-tab` and a tracked tab already shows `url`, switch to it
+    /// (without reloading, so any in-page state survives) and return its info.
+    /// Returns `None` when no tab matches and the caller should navigate/create.
+    /// Matches on exact URL or the same origin+path (ignoring query/fragment) so
+    /// a re-`open` of a stable entry URL lands on the existing tab instead of
+    /// piling up duplicates (issue #21).
+    pub async fn reuse_tab_for_url(&mut self, url: &str) -> Result<Option<Value>, String> {
+        self.resync_targets().await.ok();
+        let want = normalize_url_for_match(url);
+        let tab_id = self
+            .pages
+            .iter()
+            .find(|p| !want.is_empty() && (p.url == url || normalize_url_for_match(&p.url) == want))
+            .map(|p| p.tab_id);
+        match tab_id {
+            Some(id) => Ok(Some(self.tab_switch_by_id(id).await?)),
+            None => Ok(None),
+        }
+    }
+
     /// Resolve a user-supplied `TabRef` (either `t<N>` or a label) to the
     /// stable numeric `tab_id`. Returns a teaching error for unknown tabs.
     pub fn resolve_tab_ref(&self, tab_ref: &TabRef) -> Result<u32, String> {
@@ -1329,7 +1719,7 @@ impl BrowserManager {
 
         if let Some(page) = self.pages.get_mut(index) {
             page.url = url.clone();
-            page.title = title.clone();
+            page.title = sanitize_title(&title);
         }
 
         let page = &self.pages[index];
@@ -1584,7 +1974,8 @@ impl BrowserManager {
             .and_then(|v| v.as_i64())
             .ok_or("Could not get backendNodeId for file input")?;
 
-        self.client
+        let set_files = self
+            .client
             .send_command(
                 "DOM.setFileInputFiles",
                 Some(json!({
@@ -1593,8 +1984,153 @@ impl BrowserManager {
                 })),
                 Some(&effective_session_id),
             )
-            .await?;
+            .await;
 
+        if let Err(e) = set_files {
+            // Chrome's chrome.debugger API (the extension-relay transport) forbids
+            // DOM.setFileInputFiles for security, surfacing as an opaque
+            // `-32000 "Not allowed"`. Fall back to constructing the File entirely
+            // IN THE PAGE and assigning it to the input — the standard
+            // Playwright/Cypress trick, which needs no privileged CDP and so works
+            // over the relay (issue #13).
+            if e.contains("Not allowed") || e.contains("-32000") {
+                return self
+                    .upload_files_via_page(object_id, files, &effective_session_id)
+                    .await;
+            }
+            return Err(e);
+        }
+
+        Ok(())
+    }
+
+    /// Relay-safe file upload: read each file locally, hand its bytes to the page
+    /// as base64, and rebuild a `File` there — then either assign it to a file
+    /// `<input>` (Chrome allows `input.files = dataTransfer.files`) or, for a
+    /// dropzone/composer, dispatch synthetic `paste`/`drop` events carrying the
+    /// `DataTransfer`. No `DOM.setFileInputFiles`, so chrome.debugger permits it.
+    async fn upload_files_via_page(
+        &self,
+        object_id: String,
+        files: &[String],
+        session_id: &str,
+    ) -> Result<(), String> {
+        use base64::Engine;
+        // The relay tunnels every CDP message through Chrome native messaging,
+        // which caps a single message at ~1 MiB. A whole image's base64 blows
+        // past that ("CDP response channel closed"), so we STREAM the bytes into
+        // a page-side buffer in sub-limit chunks, then assemble the File from it.
+        const CHUNK: usize = 96 * 1024; // base64 chars per message; safe under 1 MiB
+
+        // Reset the staging buffer.
+        self.client
+            .send_command(
+                "Runtime.evaluate",
+                Some(json!({ "expression": "window.__cuUpload = [];", "returnByValue": true })),
+                Some(session_id),
+            )
+            .await
+            .map_err(|e| format!("relay upload (reset) failed: {}", e))?;
+
+        for path in files {
+            let bytes = std::fs::read(path).map_err(|e| format!("cannot read {}: {}", path, e))?;
+            let name = std::path::Path::new(path)
+                .file_name()
+                .and_then(|n| n.to_str())
+                .unwrap_or("upload.bin")
+                .to_string();
+            let mime = mime_for_path(&name);
+            let b64 = base64::engine::general_purpose::STANDARD.encode(&bytes);
+
+            // Push the file's metadata with an empty buffer.
+            let init = format!(
+                "window.__cuUpload.push({{ name: {}, type: {}, b64: '' }});",
+                serde_json::to_string(&name).unwrap_or_default(),
+                serde_json::to_string(mime).unwrap_or_default(),
+            );
+            self.client
+                .send_command(
+                    "Runtime.evaluate",
+                    Some(json!({ "expression": init, "returnByValue": true })),
+                    Some(session_id),
+                )
+                .await
+                .map_err(|e| format!("relay upload (init) failed: {}", e))?;
+
+            // Stream the base64 in chunks. base64's alphabet (A–Za–z0–9+/=) needs
+            // no escaping inside a single-quoted JS string, so concatenation is safe.
+            let idx = "window.__cuUpload[window.__cuUpload.length-1].b64";
+            let mut start = 0;
+            while start < b64.len() {
+                let end = (start + CHUNK).min(b64.len());
+                let chunk = &b64[start..end];
+                let expr = format!("{idx} += '{chunk}';");
+                self.client
+                    .send_command(
+                        "Runtime.evaluate",
+                        Some(json!({ "expression": expr, "returnByValue": true })),
+                        Some(session_id),
+                    )
+                    .await
+                    .map_err(|e| format!("relay upload (chunk) failed: {}", e))?;
+                start = end;
+            }
+        }
+
+        // Assemble the Files from the buffer and attach to the element, then clean up.
+        let func = r#"function() {
+            const filesData = window.__cuUpload || [];
+            const dt = new DataTransfer();
+            for (const f of filesData) {
+                const bin = atob(f.b64);
+                const arr = new Uint8Array(bin.length);
+                for (let i = 0; i < bin.length; i++) arr[i] = bin.charCodeAt(i);
+                dt.items.add(new File([arr], f.name, { type: f.type }));
+            }
+            try { delete window.__cuUpload; } catch (e) { window.__cuUpload = undefined; }
+            const el = this;
+            if (el.tagName === 'INPUT' && el.type === 'file') {
+                el.files = dt.files;
+                el.dispatchEvent(new Event('input', { bubbles: true }));
+                el.dispatchEvent(new Event('change', { bubbles: true }));
+                return 'input:' + dt.files.length;
+            }
+            // Dropzone / rich composer: replay paste then drop with the files.
+            try { el.dispatchEvent(new ClipboardEvent('paste', { bubbles: true, clipboardData: dt })); } catch (e) {}
+            try {
+                const ev = new DragEvent('drop', { bubbles: true, cancelable: true });
+                Object.defineProperty(ev, 'dataTransfer', { value: dt });
+                el.dispatchEvent(ev);
+            } catch (e) {}
+            return 'event:' + dt.files.length;
+        }"#;
+
+        let result: EvaluateResult = self
+            .client
+            .send_command_typed(
+                "Runtime.callFunctionOn",
+                &CallFunctionOnParams {
+                    function_declaration: func.to_string(),
+                    object_id: Some(object_id),
+                    arguments: None,
+                    return_by_value: Some(true),
+                    await_promise: Some(false),
+                },
+                Some(session_id),
+            )
+            .await
+            .map_err(|e| format!("relay file-injection failed: {}", e))?;
+
+        if let Some(ref details) = result.exception_details {
+            return Err(format!(
+                "relay file-injection threw: {}",
+                details
+                    .exception
+                    .as_ref()
+                    .and_then(|ex| ex.description.as_deref())
+                    .unwrap_or(&details.text)
+            ));
+        }
         Ok(())
     }
 
@@ -2157,6 +2693,154 @@ mod tests {
         assert_eq!(active_page_index_after_removal(0, 0, 0), 0);
     }
 
+    fn page(target_id: &str) -> PageInfo {
+        PageInfo {
+            tab_id: 1,
+            label: None,
+            target_id: target_id.to_string(),
+            session_id: format!("session-{target_id}"),
+            url: String::new(),
+            title: String::new(),
+            target_type: "page".to_string(),
+        }
+    }
+
+    // --- issue #21: --reuse-tab URL matching ignores query/fragment ---
+
+    #[test]
+    fn normalize_url_match_strips_query_and_fragment() {
+        // Two opens of the "same" SSO page differ only in volatile query/hash —
+        // they must normalize equal so --reuse-tab lands on the existing tab.
+        let a = normalize_url_for_match(
+            "https://login.account.rakuten.com/sso/authorize?client_id=x&state=abc#/sign_in",
+        );
+        let b = normalize_url_for_match(
+            "https://login.account.rakuten.com/sso/authorize?client_id=y&state=zzz#/forgot",
+        );
+        assert_eq!(a, b);
+        assert_eq!(a, "https://login.account.rakuten.com/sso/authorize");
+    }
+
+    #[test]
+    fn normalize_url_match_distinguishes_different_paths() {
+        let cart = normalize_url_for_match("https://cart.step.rakuten.co.jp/cart");
+        let order = normalize_url_for_match("https://cart.step.rakuten.co.jp/order");
+        assert_ne!(cart, order);
+    }
+
+    #[test]
+    fn normalize_url_match_passes_through_unparseable() {
+        assert_eq!(normalize_url_for_match("not a url"), "not a url");
+    }
+
+    // --- issue #14: a pinned target must keep commands on the right tab ---
+
+    #[test]
+    fn resolve_active_index_prefers_pin_over_stale_index() {
+        // The tab we opened ("A") is at index 0, but `active_page_index` is stale
+        // and points at a foreign tab ("B"). With the pin set, resolution sticks
+        // to A — the drift that bit issue #14 (eval landing on /notifications).
+        let pages = vec![page("A"), page("B")];
+        assert_eq!(resolve_active_index(&pages, Some("A"), 1), 0);
+    }
+
+    #[test]
+    fn resolve_active_index_unpinned_drifts_with_index() {
+        // Documents the pre-fix hazard: with no pin, resolution blindly trusts
+        // `active_page_index`, so a clamp/reorder from passive tab discovery lands
+        // commands on a foreign tab. This is exactly what pinning on `open` avoids.
+        let pages = vec![page("A"), page("B")];
+        assert_eq!(resolve_active_index(&pages, None, 1), 1);
+    }
+
+    #[test]
+    fn resolve_active_index_falls_back_when_pin_is_gone() {
+        // If the pinned tab was closed (target_id no longer present), fall back to
+        // the index rather than panicking or returning a bogus slot.
+        let pages = vec![page("A"), page("B")];
+        assert_eq!(resolve_active_index(&pages, Some("CLOSED"), 1), 1);
+    }
+
+    // --- issue: `open` must not hijack a user's tab on the relay (dogfood) ---
+
+    #[test]
+    fn active_not_owned_when_only_user_tabs_discovered() {
+        // A fresh relay session passively attached to the user's tabs but created
+        // none — so navigate must NOT reuse the active tab (it'd clobber the
+        // user's page); it has to open its own first.
+        let pages = vec![page("USER_A"), page("USER_B")];
+        let created = HashSet::new();
+        assert!(!active_index_is_owned(&pages, Some("USER_A"), 0, &created));
+    }
+
+    #[test]
+    fn active_owned_when_session_created_the_tab() {
+        let pages = vec![page("USER_A"), page("OURS")];
+        let mut created = HashSet::new();
+        created.insert("OURS".to_string());
+        // Active pinned to the tab we created → safe to navigate it.
+        assert!(active_index_is_owned(&pages, Some("OURS"), 1, &created));
+        // But pinned to the user's tab → not owned, even though we own another.
+        assert!(!active_index_is_owned(&pages, Some("USER_A"), 0, &created));
+    }
+
+    #[test]
+    fn active_not_owned_when_no_pages() {
+        let created = HashSet::new();
+        assert!(!active_index_is_owned(&[], None, 0, &created));
+    }
+
+    #[test]
+    fn test_sanitize_title() {
+        // The exact pollution from #33: ZWJ / word-joiner / invisible-times / BOM
+        // prepended to "GitHub".
+        let dirty = "\u{200d}\u{2061}\u{200d}\u{2063}\u{200b}\u{2062}\u{feff}GitHub";
+        assert_eq!(sanitize_title(dirty), "GitHub");
+        // Clean titles (incl. CJK + normal punctuation) pass through untouched.
+        assert_eq!(sanitize_title("購入手続きへ - メルカリ"), "購入手続きへ - メルカリ");
+        assert_eq!(sanitize_title("  Hello World  "), "Hello World");
+        // Emoji and real content survive; only the invisibles are dropped.
+        assert_eq!(sanitize_title("✓ Done\u{200b}"), "✓ Done");
+    }
+
+    #[test]
+    fn test_mime_for_path() {
+        assert_eq!(mime_for_path("a.png"), "image/png");
+        assert_eq!(mime_for_path("PHOTO.JPG"), "image/jpeg");
+        assert_eq!(mime_for_path("clip.webp"), "image/webp");
+        assert_eq!(mime_for_path("doc.pdf"), "application/pdf");
+        assert_eq!(mime_for_path("noext"), "application/octet-stream");
+        assert_eq!(mime_for_path("weird.xyz"), "application/octet-stream");
+    }
+
+    #[test]
+    fn prune_protects_pinned_target_on_transient_snapshot() {
+        // The relay returned a getTargets snapshot missing the pinned tab "A"
+        // (it hopped to another window). "B" is also absent. Without protection
+        // both would be pruned and the next command would drift; with the pin
+        // protected, only the genuinely-unpinned "B" is dropped (issue #31).
+        let pages = vec![page("A"), page("B")];
+        let live: HashSet<String> = HashSet::new(); // snapshot returned neither
+        let gone = prunable_target_ids(&pages, &live, Some("A"));
+        assert_eq!(gone, vec!["B".to_string()]);
+        // With no pin, both are prunable (unchanged behavior).
+        let gone_unpinned = prunable_target_ids(&pages, &live, None);
+        assert_eq!(gone_unpinned.len(), 2);
+        // A pinned target that IS in the live set is simply not prunable anyway.
+        let mut live2 = HashSet::new();
+        live2.insert("A".to_string());
+        assert_eq!(prunable_target_ids(&pages, &live2, Some("A")), vec!["B".to_string()]);
+    }
+
+    #[test]
+    fn resolve_active_index_pin_survives_passive_background_tab() {
+        // A foreign tab ("Z") gets appended by passive discovery after we pinned
+        // "A". The append doesn't shift A's position, and the pin keeps us on A
+        // regardless of what `active_page_index` happens to be.
+        let pages = vec![page("A"), page("B"), page("Z")];
+        assert_eq!(resolve_active_index(&pages, Some("A"), 2), 0);
+    }
+
     // issue #7: removing the pinned active target must re-anchor the pin to a
     // surviving page. Models `remove_page_by_target_id`'s index + re-pin steps
     // purely (BrowserManager needs a live CDP client, so the method itself can't

cli/src/native/cdp/chrome.rs

@@ -341,6 +341,46 @@ fn build_chrome_args(options: &LaunchOptions) -> Result<ChromeArgs, String> {
     })
 }
 
+/// Cross-process advisory lock that serializes concurrent launches of the SAME
+/// Chrome profile (issue #11). Held via `flock` on a per-profile lock file; the
+/// kernel releases it automatically when the holding process exits, so a crash
+/// can't wedge the queue. Best-effort: if the lock can't be acquired the launch
+/// proceeds unlocked rather than failing.
+struct ProfileLaunchLock {
+    #[cfg(unix)]
+    _file: std::fs::File,
+}
+
+impl ProfileLaunchLock {
+    fn acquire(profile: &str) -> Option<Self> {
+        let safe: String = profile
+            .chars()
+            .map(|c| if c.is_alphanumeric() { c } else { '_' })
+            .collect();
+        let path = std::env::temp_dir().join(format!("chrome-use-launch-{safe}.lock"));
+        let file = std::fs::OpenOptions::new()
+            .create(true)
+            .write(true)
+            .truncate(false)
+            .open(&path)
+            .ok()?;
+        #[cfg(unix)]
+        {
+            use std::os::unix::io::AsRawFd;
+            // Blocking exclusive lock: concurrent same-profile launches queue.
+            if unsafe { libc::flock(file.as_raw_fd(), libc::LOCK_EX) } != 0 {
+                return None;
+            }
+            Some(ProfileLaunchLock { _file: file })
+        }
+        #[cfg(not(unix))]
+        {
+            let _ = file;
+            Some(ProfileLaunchLock {})
+        }
+    }
+}
+
 pub fn launch_chrome(options: &LaunchOptions) -> Result<ChromeProcess, String> {
     let chrome_path = match &options.executable_path {
         Some(p) => PathBuf::from(p),
@@ -363,6 +403,13 @@ pub fn launch_chrome(options: &LaunchOptions) -> Result<ChromeProcess, String> {
     // rewrite options so the retry loop uses the copied profile.
     let mut resolved_options: Option<LaunchOptions> = None;
     let mut profile_temp_dir: Option<PathBuf> = None;
+    // Serialize concurrent launches of the SAME named profile across processes
+    // (issue #11). Without this, N parallel `open --profile <same>` collide on
+    // the profile-copy disk I/O / Chrome's profile lock, every candidate burns
+    // its full launch timeout, and all fail. The flock queues them instead and
+    // auto-releases on process exit, so a crash can't wedge the queue. Held
+    // until Chrome is up (function return).
+    let mut _launch_lock: Option<ProfileLaunchLock> = None;
 
     if let Some(ref profile) = options.profile {
         if is_chrome_profile_name(profile) {
@@ -372,6 +419,7 @@ pub fn launch_chrome(options: &LaunchOptions) -> Result<ChromeProcess, String> {
                     .to_string()
             })?;
             let resolved = resolve_chrome_profile(&user_data_dir, profile)?;
+            _launch_lock = ProfileLaunchLock::acquire(&resolved);
             let temp_path = copy_chrome_profile(&user_data_dir, &resolved)?;
 
             let mut opts = options.clone();
@@ -1886,6 +1934,17 @@ mod tests {
         assert!(is_chrome_profile_name(""));
     }
 
+    #[test]
+    fn test_profile_launch_lock_acquires_and_sanitizes() {
+        // Uncontended acquire succeeds and writes a sanitized per-profile lock
+        // file (issue #11: serialize concurrent same-profile launches).
+        let lock = ProfileLaunchLock::acquire("Profile 5/weird:name");
+        assert!(lock.is_some(), "uncontended lock should acquire");
+        let expected = std::env::temp_dir().join("chrome-use-launch-Profile_5_weird_name.lock");
+        assert!(expected.exists(), "lock file should exist at {expected:?}");
+        drop(lock);
+    }
+
     #[test]
     fn test_is_chrome_profile_name_paths() {
         assert!(!is_chrome_profile_name("/tmp/dir"));

cli/src/native/element.rs

@@ -796,16 +796,43 @@ pub(super) fn extract_ax_string(value: &Option<AXValue>) -> String {
 /// Build a JS expression that finds a DOM element by CSS selector or XPath.
 fn build_find_element_js(selector: &str) -> String {
     if let Some(xpath) = selector.strip_prefix("xpath=") {
-        format!(
+        return format!(
             "document.evaluate({}, document, null, XPathResult.FIRST_ORDERED_NODE_TYPE, null).singleNodeValue",
             serde_json::to_string(xpath).unwrap_or_default()
-        )
-    } else {
-        format!(
-            "document.querySelector({})",
-            serde_json::to_string(selector).unwrap_or_default()
-        )
+        );
     }
+    // Bare string (or explicit `text=`): try CSS first, then fall back to
+    // matching an interactive element by its VISIBLE TEXT. snapshot exposes
+    // buttons/links by their name, so `click "購入手続きへ"` should resolve by
+    // that label — previously it was fed straight to `querySelector` as CSS and
+    // failed as an invalid selector even though the button was right there
+    // (issue #24-B). CSS still wins when it matches, so existing selectors are
+    // unaffected; nested/non-ASCII labels now resolve too.
+    let text_only = selector.strip_prefix("text=");
+    let force_text = text_only.is_some();
+    let sel_json = serde_json::to_string(selector).unwrap_or_default();
+    let want_json = serde_json::to_string(text_only.unwrap_or(selector)).unwrap_or_default();
+    format!(
+        r#"(() => {{
+  const sel = {sel};
+  const css = {force_text} ? null : (() => {{ try {{ return document.querySelector(sel); }} catch (_e) {{ return null; }} }})();
+  if (css) return css;
+  const norm = s => (s == null ? '' : String(s)).replace(/\s+/g, ' ').trim();
+  const w = norm({want}); if (!w) return null;
+  const wl = w.toLowerCase();
+  const interactive = Array.from(document.querySelectorAll(
+    'button,a,[role=button],[role=link],[role=menuitem],[role=tab],[role=option],input[type=submit],input[type=button],input[type=reset],summary,label,[onclick]'));
+  const textOf = e => norm(e.innerText || e.textContent) || norm(e.value) ||
+    norm(e.getAttribute && e.getAttribute('aria-label')) || norm(e.getAttribute && e.getAttribute('title'));
+  let hit = interactive.find(e => textOf(e) === w) || interactive.find(e => textOf(e).toLowerCase().includes(wl));
+  if (hit) return hit;
+  const leaves = Array.from(document.querySelectorAll('*')).filter(e => !e.children.length);
+  return leaves.find(e => norm(e.textContent) === w) || leaves.find(e => norm(e.textContent).toLowerCase().includes(wl)) || null;
+}})()"#,
+        sel = sel_json,
+        want = want_json,
+        force_text = force_text
+    )
 }
 
 /// Build a JS expression that counts matching DOM elements by CSS selector or XPath.
@@ -948,6 +975,263 @@ pub async fn get_element_text(
         .unwrap_or_default())
 }
 
+/// Text content collected from a single frame of the page.
+#[derive(Debug, Clone)]
+pub struct FrameText {
+    pub frame_id: String,
+    pub url: String,
+    /// "top" | "inline" (same-process child frame) | "oopif" (out-of-process).
+    pub kind: &'static str,
+    pub text: String,
+}
+
+// The expression we run in every frame to read its visible text. innerText
+// honors CSS visibility (skips display:none), textContent is the fallback.
+const FRAME_INNERTEXT_JS: &str = "(function(){try{var b=document.body||document.documentElement;return b?(b.innerText||b.textContent||''):'';}catch(e){return '';}})()";
+
+async fn eval_text_default(client: &CdpClient, session_id: &str) -> String {
+    let res = client
+        .send_command(
+            "Runtime.evaluate",
+            Some(serde_json::json!({
+                "expression": FRAME_INNERTEXT_JS,
+                "returnByValue": true,
+            })),
+            Some(session_id),
+        )
+        .await;
+    res.ok()
+        .and_then(|v| v.get("result").and_then(|r| r.get("value")).cloned())
+        .and_then(|v| v.as_str().map(|s| s.to_string()))
+        .unwrap_or_default()
+}
+
+// Same-process child frames share the top renderer but live in their own
+// execution context. Page.createIsolatedWorld hands us a context id bound to
+// that frame so Runtime.evaluate reads the child document, not the parent.
+async fn eval_text_in_frame(client: &CdpClient, session_id: &str, frame_id: &str) -> String {
+    let ctx = client
+        .send_command(
+            "Page.createIsolatedWorld",
+            Some(serde_json::json!({ "frameId": frame_id, "worldName": "chrome_use_text" })),
+            Some(session_id),
+        )
+        .await
+        .ok()
+        .and_then(|v| v.get("executionContextId").and_then(|c| c.as_i64()));
+    let Some(ctx_id) = ctx else { return String::new() };
+    let res = client
+        .send_command(
+            "Runtime.evaluate",
+            Some(serde_json::json!({
+                "expression": FRAME_INNERTEXT_JS,
+                "returnByValue": true,
+                "contextId": ctx_id,
+            })),
+            Some(session_id),
+        )
+        .await;
+    res.ok()
+        .and_then(|v| v.get("result").and_then(|r| r.get("value")).cloned())
+        .and_then(|v| v.as_str().map(|s| s.to_string()))
+        .unwrap_or_default()
+}
+
+fn flatten_frame_tree(node: &Value, is_top: bool, out: &mut Vec<(String, String, bool)>) {
+    if let Some(frame) = node.get("frame") {
+        if let Some(id) = frame.get("id").and_then(|v| v.as_str()) {
+            let url = frame
+                .get("url")
+                .and_then(|v| v.as_str())
+                .unwrap_or("")
+                .to_string();
+            out.push((id.to_string(), url, is_top));
+        }
+    }
+    if let Some(children) = node.get("childFrames").and_then(|v| v.as_array()) {
+        for child in children {
+            flatten_frame_tree(child, false, out);
+        }
+    }
+}
+
+/// Collect visible text from every frame reachable in the active session,
+/// including out-of-process iframes (which never appear in the top frame's
+/// `Page.getFrameTree` and so are invisible to `document.body.innerText`).
+///
+/// Same-process child frames are read through `Page.createIsolatedWorld`;
+/// OOPIFs are read through their own auto-attached debugger session
+/// (`iframe_sessions`, keyed by frameId == targetId). This is the engine
+/// behind `get text --all-frames` and `chrome-use frames` — the fix for
+/// listing/marketplace pages whose description lives in a child frame (#27).
+pub async fn collect_all_frames_text(
+    client: &CdpClient,
+    top_session: &str,
+    iframe_sessions: &HashMap<String, String>,
+) -> Result<Vec<FrameText>, String> {
+    let mut out: Vec<FrameText> = Vec::new();
+    let mut seen: std::collections::HashSet<String> = std::collections::HashSet::new();
+
+    // 1. Top session: the top frame plus its same-process descendants. OOPIF
+    //    frames that happen to surface here are skipped — they're read via
+    //    their dedicated session in step 2 (cross-process isolated worlds fail).
+    let tree = client
+        .send_command_no_params("Page.getFrameTree", Some(top_session))
+        .await?;
+    let mut frames: Vec<(String, String, bool)> = Vec::new();
+    flatten_frame_tree(&tree["frameTree"], true, &mut frames);
+    for (fid, url, is_top) in frames {
+        if iframe_sessions.contains_key(&fid) {
+            continue;
+        }
+        if !seen.insert(fid.clone()) {
+            continue;
+        }
+        let (kind, text) = if is_top {
+            ("top", eval_text_default(client, top_session).await)
+        } else {
+            ("inline", eval_text_in_frame(client, top_session, &fid).await)
+        };
+        out.push(FrameText {
+            frame_id: fid,
+            url,
+            kind,
+            text,
+        });
+    }
+
+    // 2. Each out-of-process iframe, read through its own session.
+    for (fid, sid) in iframe_sessions {
+        if !seen.insert(fid.clone()) {
+            continue;
+        }
+        let url = client
+            .send_command_no_params("Page.getFrameTree", Some(sid))
+            .await
+            .ok()
+            .and_then(|t| {
+                t.get("frameTree")
+                    .and_then(|ft| ft.get("frame"))
+                    .and_then(|f| f.get("url"))
+                    .and_then(|v| v.as_str())
+                    .map(|s| s.to_string())
+            })
+            .unwrap_or_default();
+        let text = eval_text_default(client, sid).await;
+        out.push(FrameText {
+            frame_id: fid.clone(),
+            url,
+            kind: "oopif",
+            text,
+        });
+    }
+
+    Ok(out)
+}
+
+// Readability-lite: prefer the page's semantic main-content region over the
+// whole body so global header/nav/footer chrome (and, on many listing pages,
+// the "related items" sidebar) doesn't drown out the actual content. Runs on
+// the live, rendered tree (innerText needs layout — a detached clone returns
+// empty), so we pick the densest <main>/<article> region rather than cloning
+// and stripping. Falls back to <body> when no substantial main region exists.
+const MAIN_CONTENT_JS: &str = r#"(function(){
+  function txt(el){try{return (el.innerText||'').trim();}catch(e){return '';}}
+  var sels=['main','[role=main]','article','#main','#contents','#l-content'];
+  var best=null,bestLen=0;
+  for(var i=0;i<sels.length;i++){
+    var els=document.querySelectorAll(sels[i]);
+    for(var j=0;j<els.length;j++){var l=txt(els[j]).length;if(l>bestLen){bestLen=l;best=els[j];}}
+  }
+  if(best&&bestLen>200)return txt(best);
+  return txt(document.body);
+})()"#;
+
+/// Extract the page's main-content text (readability-lite), preferring a
+/// semantic `<main>`/`<article>` region over the full body. Used by
+/// `get text --main` to avoid header/nav/sidebar boilerplate (#27).
+pub async fn get_main_content_text(client: &CdpClient, session_id: &str) -> Result<String, String> {
+    let res = client
+        .send_command(
+            "Runtime.evaluate",
+            Some(serde_json::json!({
+                "expression": MAIN_CONTENT_JS,
+                "returnByValue": true,
+            })),
+            Some(session_id),
+        )
+        .await?;
+    Ok(res
+        .get("result")
+        .and_then(|r| r.get("value"))
+        .and_then(|v| v.as_str())
+        .unwrap_or_default()
+        .to_string())
+}
+
+// Text nodes whose parent is one of these carry no visible content.
+fn is_noise_tag(name: &str) -> bool {
+    matches!(name, "SCRIPT" | "STYLE" | "NOSCRIPT" | "TEMPLATE" | "HEAD")
+}
+
+// Walk a CDP DOM.Node tree, collecting text-node values. Unlike `innerText`
+// (JS, blocked by CLOSED shadow roots), the CDP DOM tree from
+// `DOM.getDocument(pierce:true)` includes closed shadow roots and child
+// documents — so this reaches text JS can't. `parent_noise` carries whether an
+// ancestor was <script>/<style>/etc so their text is skipped.
+fn collect_dom_text(node: &Value, parent_noise: bool, out: &mut String) {
+    let node_type = node.get("nodeType").and_then(|v| v.as_i64()).unwrap_or(0);
+    let node_name = node.get("nodeName").and_then(|v| v.as_str()).unwrap_or("");
+    if node_type == 3 {
+        if !parent_noise {
+            if let Some(t) = node.get("nodeValue").and_then(|v| v.as_str()) {
+                let t = t.trim();
+                if !t.is_empty() {
+                    if !out.is_empty() {
+                        out.push(' ');
+                    }
+                    out.push_str(t);
+                }
+            }
+        }
+        return;
+    }
+    let noise = parent_noise || is_noise_tag(node_name);
+    if let Some(children) = node.get("children").and_then(|v| v.as_array()) {
+        for child in children {
+            collect_dom_text(child, noise, out);
+        }
+    }
+    if let Some(shadow) = node.get("shadowRoots").and_then(|v| v.as_array()) {
+        for sr in shadow {
+            collect_dom_text(sr, noise, out);
+        }
+    }
+    if let Some(doc) = node.get("contentDocument") {
+        collect_dom_text(doc, noise, out);
+    }
+}
+
+/// Extract text from the page via the CDP DOM tree with `pierce:true`, which
+/// reaches into CLOSED shadow roots and child documents that `innerText`/`eval`
+/// cannot. Lets an agent read content rendered into a closed shadow DOM (e.g. an
+/// extension's injected debug panel) without any extra Chrome permission — it
+/// rides the per-tab debugger session that's already attached (#30).
+pub async fn get_pierced_text(client: &CdpClient, session_id: &str) -> Result<String, String> {
+    let doc = client
+        .send_command(
+            "DOM.getDocument",
+            Some(serde_json::json!({ "depth": -1, "pierce": true })),
+            Some(session_id),
+        )
+        .await?;
+    let mut out = String::new();
+    if let Some(root) = doc.get("root") {
+        collect_dom_text(root, false, &mut out);
+    }
+    Ok(out)
+}
+
 pub async fn get_element_attribute(
     client: &CdpClient,
     session_id: &str,
@@ -1421,6 +1705,31 @@ mod tests {
         assert_eq!(parse_ref("@e123"), Some("e123".to_string()));
     }
 
+    #[test]
+    fn test_collect_dom_text_pierces_closed_shadow_and_skips_noise() {
+        // A CDP DOM.Node tree: a host element whose CLOSED shadow root holds the
+        // text, plus a <script> whose text must be skipped.
+        let tree = serde_json::json!({
+            "nodeType": 1, "nodeName": "BODY",
+            "children": [
+                { "nodeType": 1, "nodeName": "SCRIPT",
+                  "children": [ { "nodeType": 3, "nodeName": "#text", "nodeValue": "var secret=1;" } ] },
+                { "nodeType": 1, "nodeName": "DIV",
+                  "shadowRoots": [
+                    { "nodeType": 11, "nodeName": "#document-fragment",
+                      "children": [
+                        { "nodeType": 1, "nodeName": "SPAN",
+                          "children": [ { "nodeType": 3, "nodeName": "#text", "nodeValue": "DECRYPTED 42" } ] }
+                      ] }
+                  ] }
+            ]
+        });
+        let mut out = String::new();
+        collect_dom_text(&tree, false, &mut out);
+        assert_eq!(out, "DECRYPTED 42");
+        assert!(!out.contains("secret"), "script text must be skipped");
+    }
+
     #[test]
     fn test_parse_ref_equals_prefix() {
         assert_eq!(parse_ref("ref=e1"), Some("e1".to_string()));
@@ -1452,10 +1761,30 @@ mod tests {
     #[test]
     fn test_build_selector_js_css() {
         let js = build_selector_js("#submit-btn");
-        assert!(js.contains("document.querySelector(\"#submit-btn\")"));
+        // CSS is now tried via a `sel` variable, with a visible-text fallback
+        // appended (issue #24-B). It must still use querySelector (not xpath).
+        assert!(js.contains("const sel = \"#submit-btn\""));
+        assert!(js.contains("document.querySelector(sel)"));
         assert!(!js.contains("document.evaluate"));
     }
 
+    #[test]
+    fn test_build_find_element_js_text_fallback() {
+        // A bare label gets a text-matching fallback so `click "購入手続きへ"`
+        // resolves by visible text, not just CSS (issue #24-B).
+        let js = build_find_element_js("購入手続きへ");
+        assert!(js.contains("購入手続きへ"));
+        assert!(js.contains("interactive")); // the text-match branch
+        assert!(js.contains("textOf"));
+        // `text=` forces the text path (skips CSS).
+        let forced = build_find_element_js("text=Buy now");
+        assert!(forced.contains("true ? null")); // force_text => css skipped
+                                                 // xpath is unchanged.
+        let xp = build_find_element_js("xpath=//button");
+        assert!(xp.contains("document.evaluate"));
+        assert!(!xp.contains("interactive"));
+    }
+
     #[test]
     fn test_build_selector_js_xpath() {
         let js = build_selector_js("xpath=//button[@id='ok']");

cli/src/native/interaction.rs

@@ -306,32 +306,50 @@ pub async fn fill(
     )
     .await?;
 
-    // Focus the element
-    client
-        .send_command_typed::<_, Value>(
-            "Runtime.callFunctionOn",
-            &CallFunctionOnParams {
-                function_declaration: "function() { this.focus(); }".to_string(),
-                object_id: Some(object_id.clone()),
-                arguments: None,
-                return_by_value: Some(true),
-                await_promise: Some(false),
-            },
-            Some(&effective_session_id),
-        )
-        .await?;
+    // Emulate a real edit so framework-controlled inputs (React/Vue) and
+    // site-side listeners actually see the change (issue #25): the old path set
+    // `this.value` directly and used Input.insertText, which left React's
+    // internal value-tracker out of sync and never fired change/blur — so
+    // dependent logic (e.g. Mercari's postal-code → 都道府県 autocomplete) never
+    // ran even though the value was visible. Set the value through the element's
+    // PROTOTYPE setter (which React's _valueTracker hooks), then dispatch
+    // input → change → blur/focusout. `type <sel> <text>` remains for sites that
+    // need per-keystroke events.
+    let fill_js = format!(
+        r#"function() {{
+            const el = this;
+            const v = {val};
+            try {{ el.focus(); }} catch (e) {{}}
+            const tag = el.tagName;
+            const fire = (type, ctor) => el.dispatchEvent(new (ctor || Event)(type, {{ bubbles: true }}));
+            if (tag === 'SELECT') {{
+                el.value = v; fire('input'); fire('change'); return true;
+            }}
+            if (el.isContentEditable) {{
+                el.textContent = v; fire('input', window.InputEvent || Event); fire('change');
+                try {{ el.blur(); }} catch (e) {{}} fire('focusout'); return true;
+            }}
+            const proto = tag === 'TEXTAREA' ? window.HTMLTextAreaElement.prototype
+                                             : window.HTMLInputElement.prototype;
+            const desc = Object.getOwnPropertyDescriptor(proto, 'value');
+            const set = desc && desc.set ? (x) => desc.set.call(el, x) : (x) => {{ el.value = x; }};
+            set('');                                   // reset the framework tracker
+            fire('input', window.InputEvent || Event);
+            set(v);                                    // native setter → React/Vue registers
+            fire('input', window.InputEvent || Event);
+            fire('change');
+            try {{ el.blur(); }} catch (e) {{}}
+            fire('focusout');                          // blur-triggered lookups/validation
+            return true;
+        }}"#,
+        val = serde_json::to_string(value).unwrap_or_default()
+    );
 
-    // Select all + delete to clear
     client
         .send_command_typed::<_, Value>(
             "Runtime.callFunctionOn",
             &CallFunctionOnParams {
-                function_declaration: r#"function() {
-                    this.select && this.select();
-                    this.value = '';
-                    this.dispatchEvent(new Event('input', { bubbles: true }));
-                }"#
-                .to_string(),
+                function_declaration: fill_js,
                 object_id: Some(object_id),
                 arguments: None,
                 return_by_value: Some(true),
@@ -341,17 +359,6 @@ pub async fn fill(
         )
         .await?;
 
-    // Insert text (keyboard input dispatched at page level, use parent session_id)
-    client
-        .send_command_typed::<_, Value>(
-            "Input.insertText",
-            &InsertTextParams {
-                text: value.to_string(),
-            },
-            Some(session_id),
-        )
-        .await?;
-
     Ok(())
 }
 
@@ -557,6 +564,48 @@ pub async fn press_key_with_modifiers(
     Ok(())
 }
 
+/// Dispatch a SINGLE key event (`keyDown` or `keyUp`) carrying the full key
+/// descriptor — `key`, `code`, `windowsVirtualKeyCode`/`nativeVirtualKeyCode`,
+/// and (on key-down) printable `text`. Powers the `keydown`/`keyup` commands.
+///
+/// The previous implementation sent only `{key}`, so games and shortcut handlers
+/// that read `event.code` (e.g. `"KeyD"`, `"ArrowRight"`) or `event.keyCode` saw
+/// nothing — a held key set no movement flag and did nothing (dogfood: holding a
+/// direction in a canvas platformer barely nudged the player). Sending the same
+/// descriptor `press` uses makes hold-to-move work regardless of which field the
+/// page keys off.
+pub async fn dispatch_single_key(
+    client: &CdpClient,
+    session_id: &str,
+    key: &str,
+    event_type: &str,
+) -> Result<(), String> {
+    let (key_name, code, key_code) = named_key_info(key);
+    // Printable text is only meaningful on key-down; key-up never inserts.
+    let text = if event_type == "keyDown" {
+        key_text(&key_name)
+    } else {
+        None
+    };
+    client
+        .send_command_typed::<_, Value>(
+            "Input.dispatchKeyEvent",
+            &DispatchKeyEventParams {
+                event_type: event_type.to_string(),
+                key: Some(key_name),
+                code: Some(code),
+                text: text.clone(),
+                unmodified_text: text,
+                windows_virtual_key_code: Some(key_code),
+                native_virtual_key_code: Some(key_code),
+                modifiers: None,
+            },
+            Some(session_id),
+        )
+        .await?;
+    Ok(())
+}
+
 pub async fn scroll(
     client: &CdpClient,
     session_id: &str,

cli/src/native/relay.rs

@@ -330,6 +330,45 @@ mod tests {
         }
     }
 
+    #[test]
+    fn reattach_with_same_session_restores_target() {
+        // Issue #17 recovery contract. A tab's chrome.debugger session is torn
+        // down (cross-process nav, SW restart, …) then re-attached. The fix has
+        // the extension reuse the SAME `cb-tab-<tabId>` id across that churn, so
+        // after detach+reattach the relay must expose the NEW target under the
+        // SAME session — which is exactly the session the daemon is still bound
+        // to, so its eval/snapshot auto-follow the new page instead of going stale.
+        let mut s = RelayState::new();
+        s.handle_ext_message(&attached_event("T_old", "cb-tab-42"), "tok");
+        s.handle_ext_message(
+            &json!({
+                "method": "forwardCDPEvent",
+                "params": { "method": "Target.detachedFromTarget", "params": { "sessionId": "cb-tab-42" } }
+            }),
+            "tok",
+        );
+        s.handle_ext_message(&attached_event("T_new", "cb-tab-42"), "tok");
+
+        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, "only the new target should remain");
+                assert_eq!(infos[0]["targetId"], "T_new");
+            }
+            _ => panic!("getTargets must be local"),
+        }
+        // The daemon's existing session id still resolves — to the new target.
+        let route = s.route_client_command(
+            1,
+            &json!({ "id": 2, "method": "Target.attachToTarget", "params": { "targetId": "T_new" } }),
+        );
+        assert_eq!(
+            route,
+            ClientRoute::Local(json!({ "id": 2, "result": { "sessionId": "cb-tab-42" } }))
+        );
+    }
+
     #[test]
     fn browser_get_version_is_answered_locally() {
         // Liveness probe must NOT be forwarded (the extension can't do

cli/src/native/screenshot.rs

@@ -60,6 +60,9 @@ pub struct ScreenshotOptions {
     pub quality: Option<i32>,
     pub annotate: bool,
     pub output_dir: Option<String>,
+    /// Explicit pixel region (x, y, width, height) — `--clip` (issue #34). Takes
+    /// precedence over selector/full_page.
+    pub clip: Option<(f64, f64, f64, f64)>,
 }
 
 impl Default for ScreenshotOptions {
@@ -72,6 +75,7 @@ impl Default for ScreenshotOptions {
             quality: None,
             annotate: false,
             output_dir: None,
+            clip: None,
         }
     }
 }
@@ -187,7 +191,16 @@ async fn capture_screenshot_base64(
         capture_beyond_viewport: if options.full_page { Some(true) } else { None },
     };
 
-    if options.full_page {
+    if let Some((x, y, width, height)) = options.clip {
+        // Explicit pixel region wins over selector/full_page (issue #34).
+        params.clip = Some(Viewport {
+            x,
+            y,
+            width,
+            height,
+            scale: 1.0,
+        });
+    } else if options.full_page {
         let metrics: Value = client
             .send_command_no_params("Page.getLayoutMetrics", Some(session_id))
             .await?;

cli/src/output.rs

@@ -186,6 +186,78 @@ pub fn print_response_with_opts(resp: &Response, action: Option<&str>, opts: &Ou
     }
 
     if let Some(data) = &resp.data {
+        // A click that opened a new tab: surface it so the agent doesn't read the
+        // unchanged old page as a failed click (issue #24-A).
+        if let Some(opened) = data.get("openedTab") {
+            let tid = opened.get("tabId").and_then(|v| v.as_str()).unwrap_or("?");
+            let url = opened.get("url").and_then(|v| v.as_str()).unwrap_or("");
+            let followed = data
+                .get("followed")
+                .and_then(|v| v.as_bool())
+                .unwrap_or(false);
+            let verb = if followed {
+                "switched to new tab"
+            } else {
+                "opened new tab"
+            };
+            eprintln!(
+                "{} {} [{}] {}",
+                color::cyan("→"),
+                verb,
+                tid,
+                color::dim(url)
+            );
+        }
+
+        // `current`: the active tab's stable handle (#26).
+        if data
+            .get("current")
+            .and_then(|v| v.as_bool())
+            .unwrap_or(false)
+        {
+            let tid = data.get("tabId").and_then(|v| v.as_str()).unwrap_or("?");
+            let title = data.get("title").and_then(|v| v.as_str()).unwrap_or("");
+            let url = data.get("url").and_then(|v| v.as_str()).unwrap_or("");
+            let target = data.get("targetId").and_then(|v| v.as_str()).unwrap_or("");
+            println!("{} [{}] {} - {}", color::cyan("→"), tid, title, url);
+            println!("      {}", color::dim(&format!("target: {}", target)));
+            return;
+        }
+
+        // Cloudflare challenge/clearance preflight (`cf-status`). Checked early
+        // because its response carries `url`/`title`, which later generic
+        // renderers would otherwise swallow.
+        if action == Some("cf_status") {
+            let challenged = data.get("challenged").and_then(|v| v.as_bool()).unwrap_or(false);
+            let rec = data.get("recommendation").and_then(|v| v.as_str()).unwrap_or("?");
+            let cl = data.get("clearance");
+            let present = cl.and_then(|c| c.get("present")).and_then(|v| v.as_bool()).unwrap_or(false);
+            let expired = cl.and_then(|c| c.get("expired")).and_then(|v| v.as_bool()).unwrap_or(false);
+            let expires_in = cl.and_then(|c| c.get("expiresIn")).and_then(|v| v.as_i64());
+            let device = data.get("deviceVerified").and_then(|v| v.as_bool()).unwrap_or(false);
+
+            let (icon, headline) = match rec {
+                "proceed" => (color::success_indicator().to_string(), "cleared — no challenge, proceed"),
+                "solve" => (color::warning_indicator().to_string(), "Cloudflare challenge active, no valid clearance — solve it"),
+                "reissue" => (color::warning_indicator().to_string(), "challenge active but a clearance cookie exists — stale (IP/UA changed?), re-solve"),
+                _ => (color::cyan("•").to_string(), "unknown"),
+            };
+            println!("{} {}", icon, headline);
+            println!("  challenged:     {}", if challenged { "yes" } else { "no" });
+            let cl_desc = if !present {
+                "absent".to_string()
+            } else if expired {
+                "present but EXPIRED".to_string()
+            } else if let Some(s) = expires_in {
+                format!("valid, expires in {}m {}s", s / 60, s % 60)
+            } else {
+                "present (session)".to_string()
+            };
+            println!("  cf_clearance:   {}", cl_desc);
+            println!("  device trusted: {}", if device { "yes (CF_VERIFIED_DEVICE)" } else { "no" });
+            return;
+        }
+
         // Dialog status response
         if action == Some("dialog") {
             if let Some(has_dialog) = data.get("hasDialog").and_then(|v| v.as_bool()) {
@@ -297,6 +369,39 @@ pub fn print_response_with_opts(resp: &Response, action: Option<&str>, opts: &Ou
         // Snapshot
         if let Some(snapshot) = data.get("snapshot").and_then(|v| v.as_str()) {
             print_with_boundaries(snapshot, origin, opts);
+            // Canvas-app hint: the tree was near-empty but the page paints to a
+            // <canvas>, so refs are a dead end — point at the screenshot path.
+            if let Some(note) = data.get("note").and_then(|v| v.as_str()) {
+                eprintln!("{}", color::dim(note));
+            }
+            return;
+        }
+        // Frame list (`chrome-use frames`)
+        if action == Some("frames") {
+            if let Some(list) = data.get("frames").and_then(|v| v.as_array()) {
+                let count = list.len();
+                println!(
+                    "{}",
+                    color::bold(&format!("{} frame{}", count, if count == 1 { "" } else { "s" }))
+                );
+                for f in list {
+                    let idx = f.get("index").and_then(|v| v.as_i64()).unwrap_or(0);
+                    let kind = f.get("kind").and_then(|v| v.as_str()).unwrap_or("?");
+                    let url = f.get("url").and_then(|v| v.as_str()).unwrap_or("");
+                    let len = f.get("textLen").and_then(|v| v.as_i64()).unwrap_or(0);
+                    println!(
+                        "  [{}] {:<6} {} chars  {}",
+                        idx,
+                        kind,
+                        len,
+                        color::dim(if url.is_empty() { "(about:blank)" } else { url })
+                    );
+                }
+                eprintln!(
+                    "{}",
+                    color::dim("read everything with: chrome-use get text --all-frames")
+                );
+            }
             return;
         }
         // Title
@@ -477,6 +582,9 @@ pub fn print_response_with_opts(resp: &Response, action: Option<&str>, opts: &Ou
         }
         // Tabs
         if let Some(tabs) = data.get("tabs").and_then(|v| v.as_array()) {
+            // `tab list --full` prints untruncated URLs so a long SSO/redirect
+            // URL can actually be re-opened after a stale session (issue #19).
+            let full = data.get("full").and_then(|v| v.as_bool()).unwrap_or(false);
             for tab in tabs {
                 let tab_id = tab.get("tabId").and_then(|v| v.as_str()).unwrap_or("?");
                 let tab_label = tab.get("label").and_then(|v| v.as_str());
@@ -491,8 +599,13 @@ pub fn print_response_with_opts(resp: &Response, action: Option<&str>, opts: &Ou
                 let title = title.as_str();
                 let url = tab.get("url").and_then(|v| v.as_str()).unwrap_or("");
                 // Truncate very long URLs (e.g. multi-KB JWT/OTP login links) so
-                // the list stays readable instead of flooding the terminal.
-                let url = truncate_middle(url, 120);
+                // the list stays readable instead of flooding the terminal —
+                // unless `--full` was asked for (to re-open the exact URL).
+                let url = if full {
+                    url.to_string()
+                } else {
+                    truncate_middle(url, 120)
+                };
                 let active = tab.get("active").and_then(|v| v.as_bool()).unwrap_or(false);
                 let marker = if active {
                     color::cyan("→")
@@ -504,25 +617,35 @@ pub fn print_response_with_opts(resp: &Response, action: Option<&str>, opts: &Ou
                 } else {
                     println!("{} [{}] {} - {}", marker, tab_id, title, url);
                 }
+                // `--full` also surfaces the stable cross-session CDP targetId so
+                // a stranded tab can be adopted from another session via
+                // `tab <targetId>` (issue #21).
+                if full {
+                    if let Some(target_id) = tab.get("targetId").and_then(|v| v.as_str()) {
+                        println!("      {}", color::dim(&format!("target: {}", target_id)));
+                    }
+                }
             }
             return;
         }
         // Tab switch
         if action == Some("tab_switch") {
             if let Some(tab_id) = data.get("tabId").and_then(|v| v.as_str()) {
-                if let Some(url) = data.get("url").and_then(|v| v.as_str()) {
-                    println!(
-                        "{} Switched to tab [{}] ({})",
-                        color::success_indicator(),
-                        tab_id,
-                        url
-                    );
+                let warning = data.get("warning").and_then(|v| v.as_str());
+                // A non-responding session isn't a real success — show a warning
+                // indicator instead of the green ✓ (issue #29.3).
+                let indicator = if warning.is_some() {
+                    color::warning_indicator()
                 } else {
-                    println!(
-                        "{} Switched to tab [{}]",
-                        color::success_indicator(),
-                        tab_id
-                    );
+                    color::success_indicator()
+                };
+                if let Some(url) = data.get("url").and_then(|v| v.as_str()) {
+                    println!("{} Switched to tab [{}] ({})", indicator, tab_id, url);
+                } else {
+                    println!("{} Switched to tab [{}]", indicator, tab_id);
+                }
+                if let Some(w) = warning {
+                    eprintln!("{}", color::dim(w));
                 }
                 return;
             }
@@ -1709,6 +1832,8 @@ Pass --hide-scrollbars false when launching to keep native scrollbars visible.
 
 Options:
   --full, -f           Capture full page (not just viewport)
+  [selector]           Capture just an element (CSS or @ref), e.g. `screenshot ".header" h.png`
+  --clip <x,y,w,h>     Capture a pixel region, e.g. `screenshot --clip 0,0,200,40 corner.png`
   --annotate           Overlay numbered labels on interactive elements.
                        Each label [N] corresponds to ref @eN from snapshot.
                        Prints a legend mapping labels to element roles/names.
@@ -1729,6 +1854,8 @@ Examples:
   chrome-use screenshot
   chrome-use screenshot ./screenshot.png
   chrome-use screenshot --full ./full-page.png
+  chrome-use screenshot ".header .indicator" corner.png  # just one element
+  chrome-use screenshot --clip 1600,0,200,40 corner.png  # a pixel region
   chrome-use screenshot --annotate              # Labeled screenshot + legend
   chrome-use screenshot --annotate ./page.png   # Save annotated screenshot
   chrome-use screenshot --annotate --json       # JSON output with annotations
@@ -1870,7 +1997,9 @@ Usage: chrome-use get <subcommand> [args]
 Retrieves various types of information from elements or the page.
 
 Subcommands:
-  text <selector>            Get text content of element
+  text [selector]            Element text; no selector = WHOLE PAGE, all frames
+  text --main                Main-content text only (skip nav/header/sidebar)
+  text --pierce              Read through CLOSED shadow DOM (injected panels)
   html <selector>            Get inner HTML of element
   value <selector>           Get value of input element
   attr <selector> <name>     Get attribute value
@@ -1886,7 +2015,10 @@ Global Options:
   --session <name>     Use specific session
 
 Examples:
-  chrome-use get text @e1
+  chrome-use get text                  # whole page across ALL frames (default)
+  chrome-use get text @e1              # one element
+  chrome-use get text --main           # main content, no nav/sidebar boilerplate
+  chrome-use frames                    # list frames + where the text lives
   chrome-use get html "#content"
   chrome-use get value "#email-input"
   chrome-use get attr "#link" href
@@ -2757,6 +2889,20 @@ Notes:
   - Streaming is always enabled. Set AGENT_BROWSER_STREAM_PORT to bind to a
     specific port instead of the default OS-assigned port.
 
+The WS is BIDIRECTIONAL — the high-throughput way to drive a live/real-time page
+(games, canvas apps) instead of one screenshot + one CLI call per action:
+  - Server -> client (JSON text frames):
+      {"type":"frame","data":"<base64 jpeg>"}   live screencast (~60fps)
+      plus status / tabs messages.
+  - Client -> server (send JSON text):
+      {"type":"input_keyboard","eventType":"keyDown|keyUp","key":" ","code":"Space",
+       "windowsVirtualKeyCode":32}
+      {"type":"input_mouse","eventType":"mousePressed|mouseReleased|mouseMoved",
+       "x":640,"y":360,"button":"left","clickCount":1}
+      {"type":"input_touch","eventType":"touchStart|touchEnd","touchPoints":[...]}
+  Connect once and run a tight local loop: read frames, send timed input — no
+  per-action process spawn, no round-trip. Works over the extension relay too.
+
 Global Options:
   --json               Output as JSON
   --session <name>     Use specific session
@@ -3049,7 +3195,12 @@ Core Commands:
   dblclick <sel>             Double-click element
   type <sel> <text>          Type into element
   fill <sel> <text>          Clear and fill
-  press <key>                Press key (Enter, Tab, Control+a)
+  press <key> [--hold <ms>]  Press key (Enter, Tab, Control+a). --hold keeps it
+                             down <ms> then releases — precise (in-daemon), for
+                             games/charge: `press d --hold 800`
+  keydown <key>              Hold a key down (no auto-release) — for games/shortcuts
+  keyup <key>                Release a held key. Pair with keydown to hold-to-move:
+                             `keydown d` … `keyup d`
   keyboard type <text>       Type text with real keystrokes (no selector)
   keyboard inserttext <text> Insert text without key events
   hover <sel>                Hover element
@@ -3077,10 +3228,15 @@ Navigation:
 
 Get Info:  chrome-use get <what> [selector]
   text, html, value, attr <name>, title, url, count, box, styles, cdp-url
+  text (no selector = whole page, all frames), text --main, frames (list)
 
 Check State:  chrome-use is <what> <selector>
   visible, enabled, checked
 
+Anti-bot:  chrome-use stealth | cf-status
+  stealth         stealth self-check (webdriver/UA/plugins + overrides)
+  cf-status       Cloudflare challenge + cf_clearance preflight (skip re-solving)
+
 Find Elements:  chrome-use find <locator> <value> <action> [text]
   role, text, label, placeholder, alt, title, testid, first, last, nth
 
@@ -3108,7 +3264,12 @@ Storage:
   storage <local|session>    Manage web storage
 
 Tabs:
-  tab [new|list|close|<n>]   Manage tabs
+  tab [new|list|close|<ref>] Manage tabs (<ref> = t<N>, a label, or a CDP targetId)
+  tab list --full            Full URLs + stable cross-session targetId per tab
+  tab <targetId>             Adopt a specific tab (incl. another session's) by its
+                             stable targetId, no reload — preserves in-page state
+  open <url> --reuse-tab     Reuse an existing tab on that URL instead of spawning
+                             a duplicate (matches origin+path; preserves state)
 
 Diff:
   diff snapshot              Compare current vs last snapshot
@@ -3170,6 +3331,10 @@ Confirmation:
 Sessions:
   session                    Show current session name
   session list               List active sessions
+  sessions                   List running session daemons (alias of daemon status)
+  daemon status              List running session daemons (+ relay state)
+  daemon restart             Kill all session daemons; keeps the extension relay
+                             up. Clears stale/cross-leaked state after an upgrade.
 
 Chat (AI):
   chat <message>             Send a natural language instruction (single-shot)

cli/src/test_runner.rs

@@ -0,0 +1,522 @@
+//! `chrome-use test <suite.yaml>` — a tiny, re-runnable browser test runner.
+//!
+//! Turns repetitive browser checks into unit-test-style suites for the frontend.
+//! A suite is a YAML file of cases; each case is a list of `steps` (which reuse
+//! chrome-use's own commands) followed by `assert`s (which compile to a single
+//! `eval` expression read back as a boolean). The runner drives the session by
+//! re-invoking the chrome-use binary per step, so it inherits every flag /
+//! launch / daemon / `@ref` semantic for free; the daemon stays up for the
+//! session, so each step is just a fast socket round-trip.
+//!
+//! ```yaml
+//! suite: chatgpt smoke
+//! setup:
+//!   - account: chatgpt/huayue        # cookie-use injects this login (optional)
+//! cases:
+//!   - name: home loads logged in
+//!     steps:
+//!       - open: https://chatgpt.com/
+//!       - wait: { load: networkidle }
+//!     assert:
+//!       - url: { contains: chatgpt.com }
+//!       - visible: "#prompt-textarea"
+//! ```
+
+use crate::flags::Flags;
+use serde_json::Value;
+use std::process::Command;
+use std::time::Instant;
+
+pub fn run_test(suite_path: &str, flags: &Flags) -> i32 {
+    let text = match std::fs::read_to_string(suite_path) {
+        Ok(t) => t,
+        Err(e) => {
+            eprintln!("{} cannot read suite '{}': {}", err(), suite_path, e);
+            return 2;
+        }
+    };
+    // YAML deserializes straight into serde_json::Value (maps→objects, etc.).
+    let suite: Value = match serde_yaml::from_str(&text) {
+        Ok(v) => v,
+        Err(e) => {
+            eprintln!("{} invalid YAML in '{}': {}", err(), suite_path, e);
+            return 2;
+        }
+    };
+
+    let cases = match suite.get("cases").and_then(|c| c.as_array()) {
+        Some(c) if !c.is_empty() => c.clone(),
+        _ => {
+            eprintln!("{} suite has no `cases`", err());
+            return 2;
+        }
+    };
+    let suite_name = suite
+        .get("suite")
+        .and_then(|s| s.as_str())
+        .unwrap_or("suite");
+
+    let exe = match std::env::current_exe() {
+        Ok(p) => p.to_string_lossy().into_owned(),
+        Err(e) => {
+            eprintln!("{} cannot find own binary: {}", err(), e);
+            return 2;
+        }
+    };
+
+    // A dedicated launched browser by default (deterministic, re-runnable). If
+    // the user named a --session, target that existing one instead.
+    let (session, do_launch) = if flags.session == "default" {
+        ("cu-test".to_string(), true)
+    } else {
+        (flags.session.clone(), flags.force_launch)
+    };
+    let owns_session = session == "cu-test";
+
+    let mut base: Vec<String> = vec!["--session".into(), session.clone()];
+    if do_launch {
+        base.push("--launch".into());
+    }
+    if let Some(p) = &flags.profile {
+        base.push("--profile".into());
+        base.push(p.clone());
+    }
+
+    let artifacts_dir = flags
+        .download_path
+        .clone()
+        .unwrap_or_else(|| "cu-test-artifacts".to_string());
+
+    let runner = Runner {
+        exe,
+        base,
+        artifacts_dir,
+    };
+
+    // --- setup (runs once) ---
+    if let Some(setup) = suite.get("setup").and_then(|s| s.as_array()) {
+        for item in setup {
+            if let Err(e) = runner.run_setup_item(item, &session) {
+                eprintln!("{} setup failed: {}", err(), e);
+                if owns_session {
+                    runner.close();
+                }
+                return 2;
+            }
+        }
+    }
+
+    // --- cases ---
+    println!("suite: {}  (session {})", suite_name, session);
+    let mut passed = 0usize;
+    let mut failed = 0usize;
+    for case in &cases {
+        let name = case
+            .get("name")
+            .and_then(|n| n.as_str())
+            .unwrap_or("(unnamed)");
+        let start = Instant::now();
+        let outcome = runner.run_case(case);
+        let secs = start.elapsed().as_secs_f64();
+        match outcome {
+            Ok(()) => {
+                passed += 1;
+                println!("  {} {}  {:.1}s", ok(), name, secs);
+            }
+            Err(failure) => {
+                failed += 1;
+                println!("  {} {}  {:.1}s", cross(), name, secs);
+                println!("      {}", failure.reason);
+                if let Some(shot) = runner.capture_artifact(name) {
+                    println!("      ↳ {}", shot);
+                }
+            }
+        }
+    }
+
+    if owns_session {
+        runner.close();
+    }
+
+    println!(
+        "{} cases · {} passed · {} failed",
+        cases.len(),
+        passed,
+        failed
+    );
+    i32::from(failed > 0)
+}
+
+struct Failure {
+    reason: String,
+}
+
+struct Runner {
+    exe: String,
+    base: Vec<String>,
+    artifacts_dir: String,
+}
+
+impl Runner {
+    /// Run one chrome-use sub-command. Returns the `data` object on success.
+    fn cli(&self, args: &[String]) -> Result<Option<Value>, String> {
+        let out = Command::new(&self.exe)
+            .args(&self.base)
+            .args(args)
+            .arg("--json")
+            .output()
+            .map_err(|e| format!("spawning chrome-use: {}", e))?;
+        let stdout = String::from_utf8_lossy(&out.stdout);
+        if let Ok(v) = serde_json::from_str::<Value>(stdout.trim()) {
+            let success = v
+                .get("success")
+                .and_then(|b| b.as_bool())
+                .unwrap_or(out.status.success());
+            if !success {
+                return Err(v
+                    .get("error")
+                    .and_then(|e| e.as_str())
+                    .unwrap_or("command failed")
+                    .to_string());
+            }
+            return Ok(v.get("data").cloned());
+        }
+        if out.status.success() {
+            Ok(None)
+        } else {
+            Err(String::from_utf8_lossy(&out.stderr).trim().to_string())
+        }
+    }
+
+    fn close(&self) {
+        let _ = self.cli(&["close".to_string()]);
+    }
+
+    fn run_setup_item(&self, item: &Value, session: &str) -> Result<(), String> {
+        // `account: <id>` injects a stored cookie-use login into this session.
+        if let Some(acct) = item.get("account").and_then(|a| a.as_str()) {
+            let target = format!("session:{}", session);
+            let out = Command::new("cookie-use")
+                .args(["use", acct, "--target", &target, "--no-open"])
+                .output();
+            return match out {
+                Ok(o) if o.status.success() => Ok(()),
+                Ok(o) => Err(format!(
+                    "cookie-use use {} failed: {}",
+                    acct,
+                    String::from_utf8_lossy(&o.stderr).trim()
+                )),
+                Err(e) => Err(format!(
+                    "cookie-use not available ({}); skip `account:` or install it",
+                    e
+                )),
+            };
+        }
+        // Otherwise it's a normal step.
+        let args = step_to_args(item)?;
+        self.cli(&args).map(|_| ())
+    }
+
+    fn run_case(&self, case: &Value) -> Result<(), Failure> {
+        if let Some(steps) = case.get("steps").and_then(|s| s.as_array()) {
+            for step in steps {
+                let args = step_to_args(step).map_err(|e| Failure {
+                    reason: format!("bad step: {}", e),
+                })?;
+                self.cli(&args).map_err(|e| Failure {
+                    reason: format!(
+                        "step `{}` failed: {}",
+                        args.first().cloned().unwrap_or_default(),
+                        e
+                    ),
+                })?;
+            }
+        }
+        if let Some(asserts) = case.get("assert").and_then(|a| a.as_array()) {
+            for a in asserts {
+                let (expr, describe) = assert_to_eval(a).map_err(|e| Failure {
+                    reason: format!("bad assert: {}", e),
+                })?;
+                let data = self.cli(&["eval".to_string(), expr]).map_err(|e| Failure {
+                    reason: format!("assert `{}` could not run: {}", describe, e),
+                })?;
+                let result = data.as_ref().and_then(|d| d.get("result"));
+                if !is_truthy(result) {
+                    let got = result
+                        .map(value_short)
+                        .unwrap_or_else(|| "undefined".into());
+                    return Err(Failure {
+                        reason: format!("assert {} → got {}", describe, got),
+                    });
+                }
+            }
+        }
+        Ok(())
+    }
+
+    /// Best-effort screenshot of the failing state. Returns the saved path.
+    fn capture_artifact(&self, case_name: &str) -> Option<String> {
+        let _ = std::fs::create_dir_all(&self.artifacts_dir);
+        let path = format!("{}/{}.png", self.artifacts_dir, slug(case_name));
+        match self.cli(&["screenshot".to_string(), path.clone()]) {
+            Ok(Some(d)) => d
+                .get("path")
+                .and_then(|p| p.as_str())
+                .map(String::from)
+                .or(Some(path)),
+            Ok(None) => Some(path),
+            Err(_) => None,
+        }
+    }
+}
+
+/// Map a YAML step (a one-key object) to chrome-use CLI args.
+fn step_to_args(step: &Value) -> Result<Vec<String>, String> {
+    let obj = step
+        .as_object()
+        .ok_or_else(|| "step must be a key: value mapping".to_string())?;
+    let (key, val) = obj.iter().next().ok_or_else(|| "empty step".to_string())?;
+    let s = |v: &Value| v.as_str().map(String::from);
+    match key.as_str() {
+        "open" | "goto" | "navigate" => {
+            let url = s(val).ok_or("open: expected a URL string")?;
+            Ok(vec!["open".into(), url])
+        }
+        "click" => Ok(vec![
+            "click".into(),
+            s(val).ok_or("click: expected a selector")?,
+        ]),
+        "press" => Ok(vec!["press".into(), s(val).ok_or("press: expected a key")?]),
+        "eval" => Ok(vec![
+            "eval".into(),
+            s(val).ok_or("eval: expected JS string")?,
+        ]),
+        "fill" | "type" => {
+            let sel = field(val, &["sel", "selector"]).ok_or("fill/type: need sel")?;
+            let text = field(val, &["text", "value"]).ok_or("fill/type: need text")?;
+            Ok(vec![key.clone(), sel, text])
+        }
+        "scroll" => {
+            if let Some(dir) = s(val) {
+                Ok(vec!["scroll".into(), dir])
+            } else {
+                let dir = field(val, &["dir", "direction"]).ok_or("scroll: need dir")?;
+                let mut a = vec!["scroll".into(), dir];
+                if let Some(px) = field(val, &["px", "pixels"]) {
+                    a.push(px);
+                }
+                Ok(a)
+            }
+        }
+        "wait" => {
+            if let Some(n) = val.as_i64() {
+                Ok(vec!["wait".into(), n.to_string()])
+            } else if let Some(load) = field(val, &["load"]) {
+                Ok(vec!["wait".into(), "--load".into(), load])
+            } else if let Some(sel) = s(val) {
+                Ok(vec!["wait".into(), sel])
+            } else {
+                Err("wait: expected ms, a selector, or { load: <state> }".into())
+            }
+        }
+        other => Err(format!("unknown step `{}`", other)),
+    }
+}
+
+/// Compile a YAML assert (one-key object) into (js-bool-expr, human-describe).
+fn assert_to_eval(a: &Value) -> Result<(String, String), String> {
+    let obj = a
+        .as_object()
+        .ok_or_else(|| "assert must be a key: value mapping".to_string())?;
+    let (key, val) = obj
+        .iter()
+        .next()
+        .ok_or_else(|| "empty assert".to_string())?;
+    match key.as_str() {
+        "url" => {
+            let (op, want) = str_op(val).ok_or("url: need contains/equals/matches")?;
+            Ok((
+                cmp_expr("location.href", &op, &want),
+                format!("url {} {:?}", op, want),
+            ))
+        }
+        "visible" => {
+            let sel = val.as_str().ok_or("visible: expected a selector")?;
+            Ok((visible_expr(sel), format!("visible {:?}", sel)))
+        }
+        "hidden" => {
+            let sel = val.as_str().ok_or("hidden: expected a selector")?;
+            Ok((
+                format!("!({})", visible_expr(sel)),
+                format!("hidden {:?}", sel),
+            ))
+        }
+        "text" => {
+            let sel = field(val, &["sel", "selector"]).ok_or("text: need sel")?;
+            let (op, want) = str_op(val).ok_or("text: need contains/equals/matches")?;
+            let base = format!(
+                "((document.querySelector({})||{{}}).textContent||\"\")",
+                js(&sel)
+            );
+            Ok((
+                cmp_expr(&base, &op, &want),
+                format!("text {:?} {} {:?}", sel, op, want),
+            ))
+        }
+        "count" => {
+            let sel = field(val, &["sel", "selector"]).ok_or("count: need sel")?;
+            let n = val
+                .get("eq")
+                .or_else(|| val.get("equals"))
+                .and_then(|v| v.as_i64())
+                .ok_or("count: need eq: <n>")?;
+            Ok((
+                format!("document.querySelectorAll({}).length==={}", js(&sel), n),
+                format!("count {:?} == {}", sel, n),
+            ))
+        }
+        "eval" => {
+            let expr = val.as_str().ok_or("eval: expected JS string")?;
+            Ok((format!("!!({})", expr), format!("eval {:?}", expr)))
+        }
+        other => Err(format!("unknown assert `{}`", other)),
+    }
+}
+
+fn visible_expr(sel: &str) -> String {
+    format!(
+        "(function(){{var e=document.querySelector({});return !!(e&&(e.offsetWidth||e.offsetHeight||e.getClientRects().length));}})()",
+        js(sel)
+    )
+}
+
+/// Extract (op, want) from `{contains|equals|matches: <str>}`.
+fn str_op(val: &Value) -> Option<(String, String)> {
+    for op in ["contains", "equals", "matches"] {
+        if let Some(s) = val.get(op).and_then(|v| v.as_str()) {
+            return Some((op.to_string(), s.to_string()));
+        }
+    }
+    None
+}
+
+fn cmp_expr(base: &str, op: &str, want: &str) -> String {
+    match op {
+        "equals" => format!("({})==={}", base, js(want)),
+        "matches" => format!("new RegExp({}).test({})", js(want), base),
+        _ => format!("({}).includes({})", base, js(want)), // contains
+    }
+}
+
+/// First present field among `keys`, as a string.
+fn field(val: &Value, keys: &[&str]) -> Option<String> {
+    for k in keys {
+        if let Some(v) = val.get(*k) {
+            return match v {
+                Value::String(s) => Some(s.clone()),
+                Value::Number(n) => Some(n.to_string()),
+                Value::Bool(b) => Some(b.to_string()),
+                _ => None,
+            };
+        }
+    }
+    None
+}
+
+/// JSON-encode a string so it embeds safely as a JS literal.
+fn js(s: &str) -> String {
+    serde_json::to_string(s).unwrap_or_else(|_| "\"\"".into())
+}
+
+fn is_truthy(v: Option<&Value>) -> bool {
+    match v {
+        Some(Value::Bool(b)) => *b,
+        Some(Value::Null) | None => false,
+        Some(Value::Number(n)) => n.as_f64().map(|f| f != 0.0).unwrap_or(false),
+        Some(Value::String(s)) => !s.is_empty(),
+        Some(_) => true,
+    }
+}
+
+fn value_short(v: &Value) -> String {
+    let s = v.to_string();
+    if s.len() > 60 {
+        format!("{}…", &s[..60])
+    } else {
+        s
+    }
+}
+
+fn slug(name: &str) -> String {
+    let s: String = name
+        .chars()
+        .map(|c| if c.is_alphanumeric() { c } else { '-' })
+        .collect();
+    s.trim_matches('-').to_lowercase()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use serde_json::json;
+
+    #[test]
+    fn step_mapping() {
+        assert_eq!(
+            step_to_args(&json!({"open": "https://x.com"})).unwrap(),
+            vec!["open", "https://x.com"]
+        );
+        assert_eq!(
+            step_to_args(&json!({"fill": {"sel": "#a", "text": "hi"}})).unwrap(),
+            vec!["fill", "#a", "hi"]
+        );
+        assert_eq!(
+            step_to_args(&json!({"wait": {"load": "networkidle"}})).unwrap(),
+            vec!["wait", "--load", "networkidle"]
+        );
+        assert_eq!(
+            step_to_args(&json!({"wait": 500})).unwrap(),
+            vec!["wait", "500"]
+        );
+        assert!(step_to_args(&json!({"bogus": 1})).is_err());
+    }
+
+    #[test]
+    fn assert_compilation() {
+        let (e, _) = assert_to_eval(&json!({"url": {"contains": "x.com"}})).unwrap();
+        assert!(e.contains("location.href") && e.contains(".includes("));
+        let (e, _) = assert_to_eval(&json!({"count": {"sel": ".a", "eq": 3}})).unwrap();
+        assert!(e.contains("querySelectorAll") && e.ends_with("===3"));
+        let (e, _) = assert_to_eval(&json!({"hidden": "#x"})).unwrap();
+        assert!(e.starts_with("!("));
+        let (e, _) = assert_to_eval(&json!({"eval": "window.ok"})).unwrap();
+        assert_eq!(e, "!!(window.ok)");
+        assert!(assert_to_eval(&json!({"bogus": 1})).is_err());
+    }
+
+    #[test]
+    fn truthiness() {
+        assert!(is_truthy(Some(&json!(true))));
+        assert!(!is_truthy(Some(&json!(false))));
+        assert!(!is_truthy(None));
+        assert!(!is_truthy(Some(&json!(""))));
+        assert!(is_truthy(Some(&json!("x"))));
+        assert!(!is_truthy(Some(&json!(0))));
+    }
+
+    #[test]
+    fn js_escaping() {
+        // Selectors with quotes must embed safely.
+        assert_eq!(js(r#"a"b"#), r#""a\"b""#);
+    }
+}
+
+fn ok() -> &'static str {
+    "\x1b[32m✓\x1b[0m"
+}
+fn cross() -> &'static str {
+    "\x1b[31m✗\x1b[0m"
+}
+fn err() -> &'static str {
+    "\x1b[31merror:\x1b[0m"
+}

cli/src/upgrade.rs

@@ -1,5 +1,7 @@
 use crate::color;
-use std::process::{exit, Command};
+use std::path::PathBuf;
+use std::process::{exit, Command, Stdio};
+use std::time::{SystemTime, UNIX_EPOCH};
 
 const CURRENT_VERSION: &str = env!("CARGO_PKG_VERSION");
 
@@ -7,6 +9,164 @@ const CURRENT_VERSION: &str = env!("CARGO_PKG_VERSION");
 /// upgrade path and the install path are identical (GitHub Release, no npm).
 const INSTALL_URL: &str = "https://raw.githubusercontent.com/leeguooooo/chrome-use/main/install.sh";
 
+/// GitHub API for the latest published release (used by the update check).
+const LATEST_RELEASE_API: &str =
+    "https://api.github.com/repos/leeguooooo/chrome-use/releases/latest";
+
+/// Re-check the latest version at most this often (seconds).
+const UPDATE_CHECK_INTERVAL_SECS: u64 = 86_400; // once a day
+
+fn now_secs() -> u64 {
+    SystemTime::now()
+        .duration_since(UNIX_EPOCH)
+        .map(|d| d.as_secs())
+        .unwrap_or(0)
+}
+
+fn update_cache_path() -> PathBuf {
+    crate::connection::config_home().join("update-check.json")
+}
+
+fn write_update_cache(checked_at: u64, latest: &str) {
+    let path = update_cache_path();
+    if let Some(parent) = path.parent() {
+        let _ = std::fs::create_dir_all(parent);
+    }
+    let body = serde_json::json!({ "checked_at": checked_at, "latest": latest }).to_string();
+    let _ = std::fs::write(&path, body);
+}
+
+/// Parse a dotted version (`1.2.1`, `v1.2.1`, `1.2.1-fork.3`) into a comparable
+/// `(major, minor, patch)`, ignoring any pre-release/build suffix.
+fn parse_version(v: &str) -> Option<(u64, u64, u64)> {
+    let core = v.trim().trim_start_matches('v');
+    let core = core.split(['-', '+']).next().unwrap_or(core);
+    let mut parts = core.split('.');
+    let major = parts.next()?.parse().ok()?;
+    let minor = parts.next().unwrap_or("0").parse().ok()?;
+    let patch = parts.next().unwrap_or("0").parse().ok()?;
+    Some((major, minor, patch))
+}
+
+fn is_newer(latest: &str, current: &str) -> bool {
+    matches!((parse_version(latest), parse_version(current)), (Some(l), Some(c)) if l > c)
+}
+
+/// Public semver-ish comparison (`latest` strictly newer than `current`), so
+/// `doctor` can flag a stale extension/CLI without re-implementing parsing.
+pub fn version_is_newer(latest: &str, current: &str) -> bool {
+    is_newer(latest, current)
+}
+
+/// The latest CLI version recorded by the background update check, if any.
+/// `doctor` uses it to show "a newer chrome-use is available" without a network
+/// call (the `__update-check` worker refreshes the cache out of band).
+pub fn cached_latest_version() -> Option<String> {
+    std::fs::read_to_string(update_cache_path())
+        .ok()
+        .and_then(|s| serde_json::from_str::<serde_json::Value>(&s).ok())
+        .and_then(|j| {
+            j.get("latest")
+                .and_then(|v| v.as_str())
+                .map(|s| s.to_string())
+        })
+        .filter(|s| !s.is_empty())
+}
+
+/// Hidden `__update-check` subcommand: fetch the latest release tag and cache it.
+/// Spawned detached by [`maybe_notify_update`] so the network call never blocks a
+/// real command. Uses `curl` (no extra deps, matches `upgrade`).
+pub fn run_update_check() {
+    let latest = Command::new("curl")
+        .args([
+            "-fsSL",
+            "--max-time",
+            "8",
+            "-H",
+            "User-Agent: chrome-use-update-check",
+            LATEST_RELEASE_API,
+        ])
+        .output()
+        .ok()
+        .filter(|o| o.status.success())
+        .and_then(|o| serde_json::from_slice::<serde_json::Value>(&o.stdout).ok())
+        .and_then(|j| {
+            j.get("tag_name")
+                .and_then(|v| v.as_str())
+                .map(|s| s.trim_start_matches('v').to_string())
+        });
+    if let Some(latest) = latest {
+        write_update_cache(now_secs(), &latest);
+    }
+}
+
+/// Non-blocking "update available" notice. Called once per command run:
+/// - prints a one-line hint to **stderr** (never stdout, so `--json` is clean)
+///   when a cached release is newer than the running binary;
+/// - refreshes the cached latest version at most once a day via a **detached**
+///   background process, so the current command never waits on the network.
+///
+/// Skipped for meta commands (upgrade/install/doctor/`__*`/--version/--help),
+/// in CI, in daemon mode, and when CHROME_USE_NO_UPDATE_CHECK /
+/// AGENT_BROWSER_NO_UPDATE_CHECK is set.
+pub fn maybe_notify_update() {
+    if std::env::var_os("CHROME_USE_NO_UPDATE_CHECK").is_some()
+        || std::env::var_os("AGENT_BROWSER_NO_UPDATE_CHECK").is_some()
+        || std::env::var_os("CI").is_some()
+        || std::env::var_os("AGENT_BROWSER_DAEMON").is_some()
+    {
+        return;
+    }
+    let first = std::env::args().nth(1).unwrap_or_default();
+    if first.starts_with("__")
+        || matches!(
+            first.as_str(),
+            "upgrade" | "install" | "doctor" | "dashboard" | "daemon"
+        )
+    {
+        return;
+    }
+    if std::env::args().any(|a| matches!(a.as_str(), "--version" | "-V" | "--help" | "-h")) {
+        return;
+    }
+
+    let (checked_at, latest) = std::fs::read_to_string(update_cache_path())
+        .ok()
+        .and_then(|s| serde_json::from_str::<serde_json::Value>(&s).ok())
+        .map(|j| {
+            (
+                j.get("checked_at").and_then(|v| v.as_u64()).unwrap_or(0),
+                j.get("latest")
+                    .and_then(|v| v.as_str())
+                    .unwrap_or_default()
+                    .to_string(),
+            )
+        })
+        .unwrap_or((0, String::new()));
+
+    if is_newer(&latest, CURRENT_VERSION) {
+        eprintln!(
+            "{} chrome-use {latest} is available (you have {CURRENT_VERSION}) — run `chrome-use upgrade`",
+            color::warning_indicator()
+        );
+    }
+
+    // Refresh in the background at most once a day. Bump the timestamp first
+    // (keeping the last-known latest) so concurrent runs don't all spawn a
+    // checker, then fire a detached child that does the network fetch.
+    if now_secs().saturating_sub(checked_at) >= UPDATE_CHECK_INTERVAL_SECS {
+        write_update_cache(now_secs(), &latest);
+        if let Ok(exe) = std::env::current_exe() {
+            let _ = Command::new(exe)
+                .arg("__update-check")
+                .stdin(Stdio::null())
+                .stdout(Stdio::null())
+                .stderr(Stdio::null())
+                .spawn();
+        }
+    }
+}
+
 /// Upgrade to the latest GitHub Release.
 ///
 /// The stealth fork ships as a prebuilt binary attached to a GitHub Release —

extensions/ab-connect/NOTICE.md

@@ -6,6 +6,6 @@ from **openclaw-browser-relay** by chengyixu
 
 Changes for chrome-use: rebranded to "chrome-use connect"; the
 transport is rewritten from a localhost WebSocket + shared token to Chrome
-**native messaging** (host `com.leeguoo.chrome_use`) — no port, no token,
+**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

@@ -16,7 +16,7 @@
 // attach + Target handling; the transport is rewritten from WebSocket+token to
 // native messaging.
 
-const HOST_NAME = 'com.leeguoo.chrome_use'
+const HOST_NAME = 'com.agent_browser.connect'
 const SKIP_URL = /^(chrome|chrome-extension|devtools|chrome-untrusted|edge|about):/i
 
 /** @type {chrome.runtime.Port|null} */
@@ -24,13 +24,22 @@ let port = null
 /** Whether the native-messaging host (the local chrome-use CLI) is linked.
  *  Read by the popup status page. */
 let hostConnected = false
-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()
+/** sessionId -> CDP targetId, kept ACROSS detach so a dead `cb-tab-<oldTabId>`
+ * session can be recovered by its stable targetId when the cross-process nav
+ * gave the tab a new Chrome tabId (issue #24). Capped to bound memory. */
+const sessionTargets = new Map()
+function rememberSessionTarget(sessionId, targetId) {
+  if (!sessionId || !targetId) return
+  sessionTargets.delete(sessionId)
+  sessionTargets.set(sessionId, targetId)
+  if (sessionTargets.size > 256) sessionTargets.delete(sessionTargets.keys().next().value)
+}
 /** tab-group name -> chrome tabGroups id (best-effort cache) */
 const groupIdByName = new Map()
 
@@ -109,6 +118,12 @@ function connectHost() {
     // reconnect. Keep chrome.debugger attached so reconnect is cheap.
     for (const tabId of tabs.keys()) setBadge(tabId, 'connecting')
   })
+  // Report our version so the host can tell the CLI/`doctor` which extension
+  // build is live (otherwise the extension version is a black box — the user
+  // can't tell they're on an old one). Best-effort; ignored by older hosts.
+  try {
+    postToHost({ method: 'hello', version: chrome.runtime.getManifest().version })
+  } catch {}
   // Tell the daemon about everything we already have attached, then attach
   // anything new.
   reannounceAttachedTabs()
@@ -150,6 +165,90 @@ function tabForTarget(targetId) {
   return null
 }
 
+// The STABLE Chrome tabId encoded in a `cb-tab-<tabId>` session id (#17), or
+// null for any other session shape (child/iframe sessions). The tabId is the
+// real source of truth: it survives the renderer-process swaps (cross-origin
+// OAuth/SSO navs) that tear down the page's CDP target — which is why binding to
+// it (like claude-in-chrome) rides through the hop that killed the old
+// target/sessionId binding (issue #23).
+function tabIdFromSession(sessionId) {
+  const m = /^cb-tab-(\d+)$/.exec(sessionId || '')
+  return m ? Number(m[1]) : null
+}
+
+// Ensure the debugger is attached to a `cb-tab-<tabId>` session's tab, re-attaching
+// across the transient window of a process swap (with a couple of short retries).
+// Returns the tabId on success, or null when the tab is genuinely gone
+// (closed / restricted). (issues #20.1, #23)
+async function recoverSessionTab(sessionId) {
+  const tabId = tabIdFromSession(sessionId)
+  // 1) Fast path: the encoded Chrome tabId still exists — re-attach it (covers
+  //    the common renderer-process swap where the tabId is preserved, #23).
+  if (tabId != null) {
+    for (let i = 0; i < 3; i++) {
+      const tab = await chrome.tabs.get(tabId).catch(() => null)
+      if (!eligible(tab)) break // tabId is gone — fall through to targetId recovery
+      try {
+        await attachTab(tabId)
+        if (tabs.has(tabId)) return tabId
+      } catch {
+        // mid-swap: tab exists but isn't attachable yet — back off and retry.
+      }
+      await new Promise((r) => setTimeout(r, 120 + i * 150))
+    }
+  }
+  // 2) The Chrome tabId is gone, but the CDP targetId is STABLE across the nav.
+  //    Some cross-process hops (Mercari's signin token exchange) give the tab a
+  //    NEW tabId while keeping the same target, so `cb-tab-<oldTabId>` can't be
+  //    recovered by tabId. Find the tab now hosting our remembered targetId via
+  //    chrome.debugger.getTargets(), attach it, and ALIAS the dead session to it
+  //    so the daemon's session id keeps resolving. Longer window: this hop can
+  //    take several seconds to settle (issue #24).
+  const targetId = sessionTargets.get(sessionId)
+  if (targetId) {
+    for (let i = 0; i < 6; i++) {
+      const targets = await chrome.debugger.getTargets().catch(() => null)
+      const t = targets && targets.find((x) => x.id === targetId && x.tabId != null)
+      if (t && t.tabId != null) {
+        const tab = await chrome.tabs.get(t.tabId).catch(() => null)
+        if (eligible(tab)) {
+          try {
+            await attachTab(t.tabId)
+            if (tabs.has(t.tabId)) {
+              sessionToTab.set(sessionId, t.tabId) // alias dead session -> live tab
+              return t.tabId
+            }
+          } catch {
+            // not attachable yet — keep waiting for the swap to settle.
+          }
+        }
+      }
+      await new Promise((r) => setTimeout(r, 300 + i * 300))
+    }
+  }
+  return null
+}
+
+// Send a CDP command to a tab, riding a debugger detach that can happen between
+// our attach check and the command itself (a renderer-process swap mid-flight).
+// On a detached-style failure, drop the stale handle, re-attach the stable tab,
+// and retry once — so a cross-process nav never surfaces as a hard error (#23).
+async function sendCdpToTab(tabId, method, params) {
+  const dbg = { tabId }
+  try {
+    return await chrome.debugger.sendCommand(dbg, method, params)
+  } catch (e) {
+    const msg = String((e && e.message) || e)
+    if (!/detached|not attached|target.*(closed|gone)|no target|cannot access|frame.*detached/i.test(msg)) {
+      throw e
+    }
+    detachTab(tabId, false)
+    const ok = await recoverSessionTab(`cb-tab-${tabId}`)
+    if (!ok) throw e
+    return await chrome.debugger.sendCommand(dbg, method, params)
+  }
+}
+
 function anyConnectedTab() {
   const it = tabs.keys().next()
   return it.done ? null : it.value
@@ -208,13 +307,26 @@ async function handleForwardCdpCommand(msg) {
   // Fail loudly instead so the agent sees an actionable error, not bad data.
   let tabId
   if (sessionId) {
-    tabId = tabForSession(sessionId)
-    if (!tabId) {
-      throw new Error(
-        `stale sessionId ${sessionId} for ${method}: its tab is gone (closed, ` +
-          `navigated across processes, or lost after an extension restart). ` +
-          `Re-attach by re-opening your target URL before retrying.`,
-      )
+    // The stable Chrome tabId encoded in `cb-tab-<tabId>` is the source of truth
+    // (it survives renderer-process swaps; the CDP target/sessionId does not).
+    // Resolve via it primarily — don't depend on a session→tab map entry that the
+    // detach handler may have cleared — and ensure the debugger is attached,
+    // re-attaching across a cross-process nav before failing (issues #20.1, #23).
+    // `tabForSession` still covers child/iframe sessions that aren't `cb-tab-*`.
+    tabId = tabIdFromSession(sessionId) ?? tabForSession(sessionId)
+    if (tabId == null) {
+      throw new Error(`unknown sessionId ${sessionId} for ${method}`)
+    }
+    if (!tabs.has(tabId)) {
+      const recovered = await recoverSessionTab(sessionId)
+      if (!recovered) {
+        throw new Error(
+          `stale sessionId ${sessionId} for ${method}: its tab is gone (closed, ` +
+            `navigated across processes, or lost after an extension restart). ` +
+            `Re-attach by re-opening your target URL before retrying.`,
+        )
+      }
+      tabId = recovered
     }
   } else if (typeof params?.targetId === 'string') {
     tabId = tabForTarget(params.targetId)
@@ -224,18 +336,17 @@ async function handleForwardCdpCommand(msg) {
     // applies to any attached tab.
     tabId = anyConnectedTab()
   }
-  if (!tabId) throw new Error(`no attached tab for ${method}`)
-  const dbg = { tabId }
+  if (tabId == null) throw new Error(`no attached tab for ${method}`)
 
   // 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 sendCdpToTab(tabId, 'Runtime.disable', undefined)
       await new Promise((r) => setTimeout(r, 30))
     } catch {}
-    return await chrome.debugger.sendCommand(dbg, 'Runtime.enable', params)
+    return await sendCdpToTab(tabId, 'Runtime.enable', params)
   }
-  return await chrome.debugger.sendCommand(dbg, method, params)
+  return await sendCdpToTab(tabId, method, params)
 }
 
 // ---- attach / detach ------------------------------------------------------
@@ -261,10 +372,20 @@ async function attachTab(tabId) {
   const targetInfo = info?.targetInfo
   const targetId = String(targetInfo?.targetId || '')
   if (!targetId) throw new Error('attachTab: no targetId')
-  const sessionId = `cb-tab-${nextSession++}`
+  // Derive the session id from the STABLE Chrome tabId, not a monotonic counter
+  // (issue #17). A tab's chrome.debugger session can be torn down and
+  // re-established — cross-process navigation, a service-worker restart wiping
+  // these in-memory maps, DevTools stealing the debugger — and each time the tab
+  // re-attaches. With a counter, re-attach minted a BRAND-NEW `cb-tab-N`, which
+  // orphaned the daemon's binding (it's still pinned to the old id and the relay
+  // never tells it to rebind) → permanent "stale sessionId / tab is gone". The
+  // tabId is stable across all of that, so `cb-tab-<tabId>` restores the SAME
+  // session the daemon already holds → eval/snapshot auto-follow the new page.
+  const sessionId = `cb-tab-${tabId}`
   const entry = { sessionId, targetId }
   tabs.set(tabId, entry)
   sessionToTab.set(sessionId, tabId)
+  rememberSessionTarget(sessionId, targetId)
   setBadge(tabId, port ? 'on' : 'connecting')
   postToHost({
     method: 'forwardCDPEvent',
@@ -347,9 +468,33 @@ chrome.debugger.onEvent.addListener((source, method, params) =>
   }),
 )
 
-chrome.debugger.onDetach.addListener((source) =>
-  void whenReady(() => {
-    if (source.tabId) detachTab(source.tabId, true)
+chrome.debugger.onDetach.addListener((source, reason) =>
+  void whenReady(async () => {
+    const tabId = source.tabId
+    if (!tabId) return
+    detachTab(tabId, true)
+    // A cross-process navigation (e.g. an SSO redirect like
+    // login.account.rakuten.com that swaps the render process / spawns OOPIFs)
+    // detaches the debugger, but the TAB survives. Without re-attaching, the
+    // session goes permanently stale and even open/navigate fails — exactly the
+    // #19 follow-up. So proactively re-attach (the stable `cb-tab-<tabId>`
+    // session id then restores the daemon's binding). Don't fight a detach the
+    // user or DevTools initiated.
+    if (reason === 'canceled_by_user' || reason === 'replaced_with_devtools') return
+    if (!port) return
+    // The swapped-in process needs a moment to settle; retry with backoff.
+    for (let i = 0; i < 6; i++) {
+      await new Promise((r) => setTimeout(r, 250 + i * 200))
+      if (tabs.has(tabId)) return // already re-attached (e.g. via onUpdated)
+      const tab = await chrome.tabs.get(tabId).catch(() => null)
+      if (!tab || !eligible(tab)) return // tab gone or now a restricted page
+      try {
+        await attachTab(tabId)
+        return
+      } catch (e) {
+        console.warn(`ab-connect: reattach attempt ${i + 1} for tab ${tabId} failed:`, e)
+      }
+    }
   }),
 )
 

extensions/ab-connect/manifest.json

@@ -1,7 +1,7 @@
 {
   "manifest_version": 3,
   "name": "chrome-use",
-  "version": "0.5.0",
+  "version": "0.4.9",
   "description": "Let chrome-use drive your logged-in Chrome \u2014 install once, no token, no per-use confirmation.",
   "key": "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA6vQIyscGIPYPZdSpPwPL0+0gxUROyRgCpmvCSDoc8XUm4qm97VbKnD9Ijc1lV22lNWZtE78gaRjt6BeSfuMgnBymnhLKjN1gU6AI5QUU0mrJyeHdWKvrKQR5FmsM2A7Xr1ykE2SiiS8zNUS3Y/6O5l+Nva7wrVy6E4a2dkBVQkOsu+DV+nEZvhIyuDY5D5SPXqNwUTWTaglwj5mjvHz36xSwCWlPmrtJ+ED0AUyrb2z4GIOmvk4kqtBVrh/UD058klLo4CkYOnIybB5aV6WYuwarfPY4bF/dLggPem+ewLNTUNBuwrxj/A4nUv0LJTuRO8rR7f8WR9qnRCY0Ic5saQIDAQAB",
   "icons": {

extensions/store/SUBMISSION.html

@@ -28,7 +28,7 @@
 <body>
 <header>
   <h1>Chrome Web Store 提交指南</h1>
-  <div class="sub">chrome-use · 上传包 <code>extensions/ab-connect.zip</code> · id 锁定为 <code>ciiljdlhdpfckdcfkphgmfalanpdejep</code></div>
+  <div class="sub">chrome-use · <strong>更新现有商店条目</strong> <code>knfcmbamhjmaonkfnjhldjedeobeafmk</code> · 上传 <strong>key 已删</strong> 的包(纯改名,保住老用户/评分)</div>
 </header>
 
 <p>为什么必须走商店:实测 Chrome 149 在<strong>非企业托管</strong>的 Mac 上,会把"非 Web Store"的 force-install 扩展直接标成 <code>[BLOCKED]</code>。商店扩展不受此限。这也是 codex / claude 扩展都发商店的原因。</p>
@@ -44,11 +44,15 @@
   <li>(隐私政策需要一个公开 URL,见第四节 —— 我可以帮你开 GitHub Pages 托管 <code>privacy.html</code>)</li>
 </ol>
 
-<h2>二、上传</h2>
+<h2>二、上传(更新现有条目,纯改名)</h2>
+<p>你已经有一个上架条目(原名 <em>agent-browser-stealth</em>,Item ID <code>knfcmbamhjmaonkfnjhldjedeobeafmk</code>)。这次只是把它<strong>改名成 chrome-use</strong>,所以走 <span class="field">更新版本</span>,<u>不要</u> New item —— 这样老用户自动更新、评分/安装量都保留。</p>
 <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>
+  <li>devconsole → 打开 <strong>现有的 agent-browser-stealth 条目</strong>(id <code>knfcmbamhjmaonkfnjhldjedeobeafmk</code>)→ <span class="field">Package → Upload new package</span>。</li>
+  <li>上传 <strong>key 已删</strong> 的包 <code>chrome-use-store-vX.Y.Z.zip</code>(<em>必须删掉 manifest 的 <code>key</code> 字段</em>,否则商店报"key 字段不符";仓库里 <code>ab-connect/manifest.json</code> 带 key 是给本地 Load-unpacked 用的,别直接传那个)。上传后 Item ID <strong>保持 <code>knfcmbam…</code> 不变</strong>;用户看到的扩展名变成 <strong>chrome-use</strong>。</li>
+  <li>native messaging 的 <code>allowed_origins</code> 同时放行 <code>knfcmbam…</code> 和 <code>ciiljdl…</code> 两个 id,所以改名后 relay 照常连得上,<strong>不会断现有用户</strong>。</li>
+  <li><strong>不要</strong>在这次发布里改 <code>background.js</code> 的 native host 名(保持 <code>com.agent_browser.connect</code>);<code>com.leeguoo.chrome_use</code> 是给将来真迁移用的。</li>
 </ol>
+<div class="warn"><strong>若你确实想另开一个全新的 "chrome-use" 条目(新 id、评分清零、用户需重装)</strong>:那才用保留 key 的包,id 会锁成 <code>ciiljdlhdpfckdcfkphgmfalanpdejep</code>。仅在你想彻底脱离旧 <em>stealth</em> 品牌时才这么做 —— 默认按上面"更新现有条目"走。</div>
 
 <h2>三、商店信息(直接复制以下文案)</h2>
 
@@ -114,8 +118,12 @@ automate pages the user is working with, entirely on the user's machine and at t
 <pre>https://leeguooooo.github.io/chrome-use/extensions/store/privacy.html</pre>
 <p>(部署需 1–2 分钟生效。raw 备用直链:<code>https://raw.githubusercontent.com/leeguooooo/chrome-use/main/extensions/store/privacy.html</code>。)</p>
 
-<h2>六、截图 / Screenshots（至少 1 张，1280×800 或 640×400）</h2>
-<p>可以截一张 CLI + Chrome 并排的演示图。<em>需要的话我用 cua-driver 截一张合规尺寸的图给你。</em></p>
+<h2>六、图标 + 截图 / Icon &amp; Screenshots</h2>
+<p><strong>已生成,涂鸦风(和 cookie-use README 同一套)。</strong>上传到对应字段即可:</p>
+<ul>
+  <li><span class="field">Store icon(128×128)</span>:<code>chrome-use-store-icon-128.png</code></li>
+  <li><span class="field">Screenshots(每张正好 1280×800)</span>:<code>chrome-use-store-shot1-1280x800.png</code>(CMD 牵线操控已登录浏览器)、<code>shot2</code>(机械臂抓浏览器方向盘)、<code>shot3</code>(浏览器插线连终端 CONNECTED)。</li>
+</ul>
 
 <h2>七、提交后</h2>
 <ol>
@@ -127,6 +135,6 @@ automate pages the user is working with, entirely on the user's machine and at t
   <strong>今天的临时可用方案:</strong> 在你这台 Mac 上 <code>chrome://extensions</code> → 打开开发者模式 → Load unpacked → 选 <code>extensions/ab-connect</code>,30 秒手动装一次,native messaging + <code>extension connect</code> 立即可用。等商店过审再切静默路径。
 </div>
 
-<footer>chrome-use · 提交包与文案随扩展版本更新;改扩展后重跑 <code>scripts/pack-extension.sh</code> 并重打 <code>ab-connect.zip</code>。</footer>
+<footer>chrome-use · 更新现有条目 <code>knfcmbam…</code>(纯改名);上传包必须删 key。改扩展后重打 key-stripped 的 <code>chrome-use-store-vX.Y.Z.zip</code> 再传。</footer>
 </body>
 </html>

package.json

@@ -1,6 +1,6 @@
 {
   "name": "chrome-use",
-  "version": "1.1.0",
+  "version": "1.5.10",
   "description": "chrome-use — drive your real, logged-in Chrome from any AI agent, stealth by default",
   "type": "module",
   "packageManager": "pnpm@11.1.3",

skill-data/core/SKILL.md

@@ -127,6 +127,19 @@ cadence, and scroll/drag ease. Default `off`; a per-navigation detector
 auto-escalates pages guarded by Akamai/PerimeterX/DataDome to `human`. Leave it
 on auto; force `human` only when you already know the target scores behaviour.
 
+**Cloudflare clearance — solve once, reuse.** Passing a Cloudflare challenge
+mints a `cf_clearance` cookie (HttpOnly — invisible to `eval`/`document.cookie`;
+read it via `chrome-use cookies`). It's bound to your **IP + User-Agent**: reuse
+the same exit IP and UA and you skip the challenge until it expires. Driving the
+user's real Chrome (relay) persists it natively; for isolated sessions,
+`--session-name <name>` save/restores it. Before spending effort solving, run
+`chrome-use cf-status` (aliases `cf`, `clearance`): it reports whether the page
+is *currently* a Cloudflare challenge and whether a still-valid `cf_clearance`
+exists, with a recommendation — `proceed` (already cleared, don't re-solve),
+`solve` (challenge up, no clearance), or `reissue` (clearance present but page
+still blocks → IP/UA drifted, re-solve). Use it as a preflight to avoid
+re-solving what you already cleared.
+
 ## 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:
@@ -207,7 +220,11 @@ assigned fresh on every snapshot.
 For unstructured reading (no refs needed):
 
 ```bash
-chrome-use get text @e1                # visible text of an element
+chrome-use get text                    # WHOLE PAGE — all frames by default (see below)
+chrome-use get text @e1                # visible text of one element (or a CSS selector)
+chrome-use get text --main             # main content only — skip nav/header/sidebar
+chrome-use get text --pierce           # read through CLOSED shadow DOM (injected panels)
+chrome-use frames                      # list every frame + where the text lives
 chrome-use get html @e1                # innerHTML
 chrome-use get attr @e1 href           # any attribute
 chrome-use get value @e1               # input value
@@ -216,6 +233,27 @@ chrome-use get url                     # current URL
 chrome-use get count ".item"           # count matching elements
 ```
 
+**Whole-page text is cross-frame by default.** `chrome-use get text` with no
+selector aggregates visible text across **every** frame — top document plus
+same-process child frames plus cross-origin iframes — so you never silently miss
+content that lives in an iframe (Yahoo Auctions / Rakuten / Mercari shop
+descriptions, embedded checkout/spec frames). Each child frame is delimited with
+a `----- frame [kind] url -----` marker. You do **not** need to remember a flag —
+the default already reads all frames. (`--all-frames` is still accepted as an
+explicit alias.)
+
+So: when text looks missing or wrong, you don't have to guess — just
+`chrome-use get text` reads everything. To **see** the structure (which frame
+holds what), run `chrome-use frames`. To **cut boilerplate** (global nav/header/
+footer, "related items" sidebars), use `chrome-use get text --main`. If content
+is lazy-loaded, `scroll` it into view first, then read.
+
+**Closed shadow DOM.** Some injected UI (browser-extension debug panels, web
+components) renders into a *closed* shadow root that `eval`/`innerText` cannot
+read. `chrome-use get text --pierce` reads through closed shadow roots and child
+documents via the CDP DOM tree — use it when content is clearly on screen (you
+see it in a screenshot) but `get text`/`eval` come back empty.
+
 ## Interacting
 
 ```bash
@@ -226,8 +264,11 @@ chrome-use hover @e1                   # hover
 chrome-use focus @e1                   # focus (useful before keyboard input)
 chrome-use fill @e2 "hello"            # clear then type
 chrome-use type @e2 " world"           # type without clearing
-chrome-use press Enter                 # press a key at current focus
+chrome-use press Enter                 # press a key at current focus (down+up)
 chrome-use press Control+a             # key combination
+chrome-use keydown d                   # HOLD a key down (no auto-release)
+chrome-use keyup d                     # release it — pair them to hold-to-move
+                                          # in a game: `keydown d; sleep; keyup d`
 chrome-use check @e3                   # check checkbox
 chrome-use uncheck @e3                 # uncheck
 chrome-use select @e4 "option-value"   # native <select> only
@@ -240,7 +281,11 @@ chrome-use pick @e4 --option "Europe"  # ANY combobox (react-select / ARIA /
                                           # (no silent no-op). Use this for custom
                                           # dropdowns where `select` returns ✓ but
                                           # changes nothing.
-chrome-use upload @e5 file1.pdf        # upload file(s)
+chrome-use upload @e5 file1.pdf        # upload file(s) — works over the extension relay too:
+                                          # chrome.debugger forbids setFileInputFiles, so the
+                                          # file's bytes are streamed into the page and rebuilt as
+                                          # a File there (chunked under native-messaging's 1 MiB cap).
+                                          # Works on file <input>s and drop/paste composers (e.g. X).
 chrome-use scroll down 500             # scroll page (up/down/left/right)
 chrome-use scrollintoview @e1          # scroll element into view
 chrome-use drag @e1 @e2                # drag and drop
@@ -292,6 +337,54 @@ chrome-use click --coords 449,320   # same, explicit flag
 
 A bare-number argument is always a coordinate, never a selector.
 
+### Canvas / WebGL apps (games, map & 3D viewers, drawing tools)
+
+These paint everything to a `<canvas>` and expose **almost no accessibility
+tree**, so `snapshot` comes back near-empty and refs are a dead end. `snapshot`
+detects this and prints a one-line hint. Drive them the screenshot way:
+
+```bash
+chrome-use screenshot /tmp/s.png       # SEE the state (your only read path —
+                                          # eval/get text return nothing useful)
+chrome-use click 640 360               # interact by viewport coordinate
+chrome-use press d --hold 800          # hold-to-move, precise (timed in-daemon —
+                                          # NOT keydown+shell-sleep+keyup, which
+                                          # adds ~250ms jitter per round-trip)
+chrome-use press Space                 # discrete actions (jump/attack/confirm)
+```
+
+**Don't drive frame-by-frame with one CLI call per action** — that's the slowest,
+lowest-fidelity way (each call is a process spawn + round-trip). Script a *timed
+sequence in a single round-trip* with `batch` (it sends each step to the running
+daemon; `press --hold` and `wait` block in-daemon, so timing is precise):
+
+```bash
+chrome-use batch "press d --hold 900" "press j" "press j" "wait 200" "press d --hold 500"
+```
+
+Also try reading real state instead of pixels: `eval` runs in the page's main
+world, so for a framework/engine game you can often reach its globals (e.g. a
+Phaser/PIXI/Three instance, a store, `window.__GAME__`) and read positions/score
+directly — far better than guessing from a screenshot.
+
+**For genuinely real-time driving, drop the CLI entirely and use the WebSocket.**
+`chrome-use stream enable` opens a bidirectional WS (`stream status` prints the
+`ws://127.0.0.1:<port>`). Connect once and you get a live ~60fps screencast AND
+can send input on the same socket — no per-action process spawn, no round-trip,
+works over the extension relay:
+
+```js
+// node (global WebSocket): live frames + locally-timed input
+const ws = new WebSocket("ws://127.0.0.1:PORT")
+ws.onmessage = e => { const m = JSON.parse(e.data); if (m.type==="frame") {/* base64 jpeg */} }
+const k = (eventType,key,code,vk) => ws.send(JSON.stringify({type:"input_keyboard",eventType,key,code,windowsVirtualKeyCode:vk}))
+k("keyDown"," ","Space",32); setTimeout(()=>k("keyUp"," ","Space",32), 80)   // a jump
+// also: {type:"input_mouse",eventType:"mousePressed",x,y,button:"left",clickCount:1}
+```
+
+This is the difference between watching a slideshow and playing the game. Reserve
+screenshots for one-off checks; use the WS for any sustained real-time control.
+
 ## Waiting (read this)
 
 Agents fail more often from bad waits than from bad selectors. Pick the
@@ -497,6 +590,43 @@ the same browser's existing targets, so a second session's first `open` can
 navigate a sibling's tab. For concurrent agents on one real Chrome, use the
 extension (each with a distinct `--session`), not raw `--cdp`.
 
+Each session owns its own tab group and assigns its own `t<N>` indices (the same
+physical tab is `t8` in one session, `t1` in another), so `t<N>` is **not** a
+stable cross-session handle. To reach a *specific* tab from another session — e.g.
+a tab that was filled in a session whose handle later died — use the **stable CDP
+`targetId`**:
+
+```bash
+chrome-use tab list --full --session B   # re-syncs live tabs; prints `target: <id>` per row
+chrome-use tab <targetId> --session B    # adopt that exact tab, NO reload (state preserved)
+```
+
+`tab list` re-discovers the live tab set on every call, so a fresh session sees
+tabs other sessions opened (and re-attached ones), not just its own. Adopting by
+`targetId` lands session B on the stranded tab without reloading it, so a
+half-filled form survives. Still, the simplest recovery for a session whose own
+tab died is to recover *that* session (reload / re-`open` / `daemon restart`).
+
+To avoid piling up duplicate tabs when you re-`open` the same entry URL on
+rebind, pass **`--reuse-tab`**: if a tab already shows that URL (matched by
+origin+path), it switches to it instead of spawning a new one.
+
+### Reset stuck daemon state
+
+Each session runs a background daemon worker that holds the page handles. If a
+session starts misbehaving — commands hit the wrong tab, refs/handles look stale,
+or you upgraded `chrome-use` mid-session and old workers linger — restart the
+daemons instead of hunting PIDs with `pgrep`/`kill`:
+
+```bash
+chrome-use daemon status     # list running session daemons (+ relay state)
+chrome-use daemon restart    # kill every session daemon worker
+```
+
+`daemon restart` leaves the extension's native-messaging bridge (`__nm-host`)
+alone, so the relay to your live Chrome stays up — the next command just spins up
+a fresh, clean daemon against the same browser. It does **not** close any tabs.
+
 ### Mock network requests
 
 ```bash
@@ -606,6 +736,13 @@ forbids debugging). The session no longer has a live tab — re-run
 replaces the old silent behaviour where the command ran on some *other*
 tab and returned wrong data.
 
+To recover, you need the tab's **exact** URL (query params and all — a long
+SSO/redirect link breaks if truncated). `tab list` shortens long URLs with
+`…`; use **`tab list --full`** to print them untruncated, then re-`open` the
+right one. For multi-redirect SSO flows, re-open the **stable entry URL**
+(not the mid-redirect one) and `wait` a few seconds for the SPA to settle
+before snapshotting.
+
 **Reads landing on the wrong page**
 `eval`, `screenshot`, and `network requests` print the page they ran
 against to stderr: `eval @ <url>`, `screenshot @ <url>`, `network @ <url>`.
@@ -668,6 +805,8 @@ and [references/authentication.md](references/authentication.md).
   `chrome-use skills get electron`
 - **Slack workspace automation**: `chrome-use skills get slack`
 - **Exploratory testing / QA / bug hunts**: `chrome-use skills get dogfood`
+- **Re-runnable test suites (frontend "unit tests")**: `chrome-use skills get test`
+  — turn repeated checks into a `chrome-use test <suite.yaml>` regression suite
 - **Vercel Sandbox microVMs**: `chrome-use skills get vercel-sandbox`
 - **AWS Bedrock AgentCore cloud browser**: `chrome-use skills get agentcore`
 

skill-data/test/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: test
+description: Write and run re-runnable, unit-test-style browser test suites with `chrome-use test <suite.yaml>`. Use when repetitive manual browser checks (does the page load logged in? is this element there? did the flow work?) should become a fixed, repeatable regression suite instead of being re-done by hand each time — frontend automated testing on top of chrome-use.
+---
+
+# chrome-use test — browser test suites
+
+Turn the repetitive "open it, click around, check it's right" work into a
+**re-runnable suite**, like unit tests for the frontend. Every time you find a
+regression, add a case — the suite gets more valuable the more you use it.
+
+```
+chrome-use test <suite.yaml> [--launch | --session <name>] [--json]
+```
+
+- Exit code **0** if all cases pass, **1** if any fail → drop it straight into CI.
+- Default: launches a fresh isolated browser (deterministic, repeatable) in a
+  `cu-test` session and closes it after. Pass `--session <name>` to run against an
+  already-connected session (e.g. the live Chrome via `chrome-use extension connect`).
+- Failed cases auto-save a screenshot to `cu-test-artifacts/<case>.png`.
+
+## Suite format (YAML)
+
+```yaml
+suite: chatgpt smoke               # label (optional)
+setup:                             # runs once before all cases (optional)
+  - account: chatgpt/huayue        # inject a cookie-use stored login (optional)
+  - open: https://chatgpt.com/     # …or any normal step
+cases:
+  - name: home loads logged in
+    steps:                         # steps reuse chrome-use's own commands
+      - open: https://chatgpt.com/
+      - wait: { load: networkidle }
+    assert:                        # all asserts must hold or the case fails
+      - url: { contains: chatgpt.com }
+      - visible: "#prompt-textarea"
+  - name: composer takes text
+    steps:
+      - fill: { sel: "#prompt-textarea", text: "hi" }
+    assert:
+      - text: { sel: "#prompt-textarea", contains: hi }
+      - eval: "!!window.__NEXT_DATA__"
+```
+
+## Steps (the verbs)
+
+Each step is a one-key mapping; the key is a chrome-use command:
+
+| Step | Meaning |
+|---|---|
+| `open: <url>` | navigate |
+| `click: <selector\|@ref>` | click |
+| `fill: { sel: <s>, text: <t> }` | clear + type |
+| `type: { sel: <s>, text: <t> }` | type (no clear) |
+| `press: <key>` | key press (e.g. `Enter`) |
+| `wait: <ms>` / `wait: { load: networkidle }` / `wait: <selector>` | wait |
+| `scroll: <up\|down\|...>` or `{ dir: down, px: 500 }` | scroll |
+| `eval: "<js>"` | run JS |
+
+## Assertions (the checks) — all compile to one truthy `eval`
+
+| Assert | Passes when |
+|---|---|
+| `url: { contains\|equals\|matches: <v> }` | the page URL matches |
+| `visible: <selector>` | element exists and is laid out |
+| `hidden: <selector>` | element is absent / not laid out |
+| `text: { sel: <s>, contains\|equals\|matches: <v> }` | element text matches |
+| `count: { sel: <s>, eq: <n> }` | exactly N elements match |
+| `eval: "<js>"` | the JS expression is truthy |
+
+## Auth
+
+`setup: - account: <id>` injects a [cookie-use](https://github.com/leeguooooo/cookie-use)
+stored login into the test session, so the suite runs authenticated. (Needs
+`cookie-use` installed; skip the line if you don't use it.)
+
+## Workflow
+
+1. Do the check once by hand with `open`/`snapshot`/`eval` to learn the selectors.
+2. Write it up as a case in a `*.yaml` suite.
+3. `chrome-use test suite.yaml` — green means it works; red shows the failing
+   assert + a screenshot.
+4. Found a regression later? Add a case. Run the whole suite in CI.
+
+## Limits (v1)
+
+Assertions are evaluated independently after the steps run. No per-case retries,
+no parallel cases, no snapshot/screenshot baseline diffing yet (use an `eval`
+assert against known content for now). Steps run sequentially; a failing step
+fails the case immediately.