chore(release): bump to 0.27.0-fork.5 — attach-mode UX + zombie-CDP probe + wait @ref

Two changes that pair with each other:

1. connect_auto_with_fresh_tab now does a Runtime.evaluate "1"
   round-trip after creating the fresh tab. This catches the zombie
   CDP socket case (process alive, websocket dead) where every step
   up to that point reports success but the next user command would
   silently no-op against a dead session. Failing here lets the
   caller surface a proper "CDP session unresponsive" error instead
   of returning Ok and letting `agent-browser open URL` exit 0 with
   a still-blank tab.

2. handle_wait now recognizes @ref selectors (e.g. `wait @e8 --gone`).
   It polls resolve_element_object_id, which already runs the
   verify_ref_identity check from 007fd1b — so:
     - `wait @e8`             succeeds while the original element is
                              still mounted with its snapshot role+name
     - `wait @e8 --gone`      succeeds when the ref's identity changes
                              (modal closed, button re-textified, etc.)
   This gives users the "assert modal still open" primitive that
   prior versions could only approximate with screenshots.

cli/Cargo.lock

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

cli/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "agent-browser-stealth"
-version = "0.27.0-fork.3"
+version = "0.27.0-fork.5"
 edition = "2021"
 description = "Fast browser automation CLI for AI agents"
 license = "Apache-2.0"

cli/src/main.rs

@@ -822,11 +822,24 @@ fn main() {
         .collect();
 
         if !ignored_flags.is_empty() && !flags.json {
-            eprintln!(
-                "{} {} ignored: daemon already running. Use 'agent-browser close' first to restart with new options.",
-                color::warning_indicator(),
-                ignored_flags.join(", ")
-            );
+            // Special case: --headed is irrelevant in CDP-attach mode
+            // (your existing Chrome is always already visible). The
+            // "agent-browser close + reopen" advice doesn't help because
+            // the new daemon will attach right back to the same Chrome.
+            // Don't suggest a useless workaround.
+            if ignored_flags == ["--headed"] {
+                eprintln!(
+                    "{} --headed has no effect when attached to your running Chrome (it's already visible). \
+                     Pass --launch to spawn a separate browser if you need to control headedness.",
+                    color::warning_indicator(),
+                );
+            } else {
+                eprintln!(
+                    "{} {} ignored: daemon already running. Use 'agent-browser close' first to restart with new options.",
+                    color::warning_indicator(),
+                    ignored_flags.join(", ")
+                );
+            }
         }
     }
 

cli/src/native/actions.rs

@@ -1510,6 +1510,28 @@ async fn connect_auto_with_fresh_tab() -> Result<BrowserManager, String> {
         .client
         .send_command("Page.bringToFront", None, Some(&session_id))
         .await;
+
+    // Liveness probe: confirm the CDP session can actually round-trip
+    // before returning success. Without this, a zombie CDP socket (process
+    // alive, websocket dead) would let `connect_auto` and `tab_new` succeed,
+    // we'd return Ok, the next user command would silently no-op, and
+    // `agent-browser open URL` would exit 0 with the browser still on
+    // about:blank. Failing here lets the caller surface the real error.
+    if let Err(e) = mgr
+        .client
+        .send_command("Runtime.evaluate", Some(serde_json::json!({
+            "expression": "1",
+            "returnByValue": true,
+        })), Some(&session_id))
+        .await
+    {
+        return Err(format!(
+            "CDP session is unresponsive after attaching ({}). \
+             The browser may have lost its DevTools connection. \
+             Try: agent-browser close, then re-run.",
+            e
+        ));
+    }
     Ok(mgr)
 }
 
@@ -3105,6 +3127,15 @@ async fn handle_wait(cmd: &Value, state: &mut DaemonState) -> Result<Value, Stri
             .get("state")
             .and_then(|v| v.as_str())
             .unwrap_or("visible");
+        // @-ref support: if the selector is `@e12` style, poll the ref map +
+        // accessibility tree instead of `document.querySelector`. This makes
+        // `wait @e8 --gone` a usable "assert modal still mounted" primitive
+        // for SPA flows where the only stable identity is the AX role+name
+        // captured at snapshot time.
+        if selector.starts_with('@') {
+            wait_for_ref(state, selector, state_str, timeout_ms).await?;
+            return Ok(json!({ "waited": "ref", "ref": selector, "state": state_str }));
+        }
         wait_for_selector(&mgr.client, &session_id, selector, state_str, timeout_ms).await?;
         return Ok(json!({ "waited": "selector", "selector": selector }));
     }
@@ -3316,6 +3347,49 @@ async fn handle_reload(state: &mut DaemonState) -> Result<Value, String> {
 // Wait helpers
 // ---------------------------------------------------------------------------
 
+/// Poll-based wait for a ref-identified element. Resolves the @-ref by
+/// re-running the ref-identity verification each iteration. The supported
+/// states mirror selector-based waits:
+///
+///   - "visible" / "attached" — succeed when the ref resolves to a node
+///     whose AX role + name still match the snapshot entry
+///   - "detached" / "hidden" — succeed when the ref no longer matches
+///     (node removed OR re-textified to something else)
+///
+/// Times out with a "ref X did not become {state}" error.
+async fn wait_for_ref(
+    state: &mut DaemonState,
+    ref_selector: &str,
+    desired_state: &str,
+    timeout_ms: u64,
+) -> Result<(), String> {
+    let want_present = !matches!(desired_state, "detached" | "hidden");
+    let deadline = std::time::Instant::now() + std::time::Duration::from_millis(timeout_ms);
+    loop {
+        let mgr = state.browser.as_ref().ok_or("Browser not launched")?;
+        let session_id = mgr.active_session_id()?.to_string();
+        let resolved = super::element::resolve_element_object_id(
+            &mgr.client,
+            &session_id,
+            &state.ref_map,
+            ref_selector,
+            &state.iframe_sessions,
+        )
+        .await;
+        let present = resolved.is_ok();
+        if present == want_present {
+            return Ok(());
+        }
+        if std::time::Instant::now() >= deadline {
+            return Err(format!(
+                "Timeout: ref {} did not become {} within {}ms",
+                ref_selector, desired_state, timeout_ms
+            ));
+        }
+        tokio::time::sleep(tokio::time::Duration::from_millis(100)).await;
+    }
+}
+
 async fn wait_for_selector(
     client: &super::cdp::client::CdpClient,
     session_id: &str,

cli/src/native/element.rs

@@ -163,6 +163,30 @@ pub async fn resolve_element_center(
 
         // Try cached backend_node_id first (fast path)
         if let Some(backend_node_id) = entry.backend_node_id {
+            // Identity check: React often re-uses the same DOM node when
+            // re-rendering — backendNodeId stays the same but accessibleName
+            // / role changes. Without this verification, `click @e20` (saved
+            // when the button said "Add post") happily clicks the *same*
+            // node that now says "Post all", silently submitting the thread.
+            //
+            // Set AGENT_BROWSER_VERIFY_REF=0 to skip (saves one CDP
+            // roundtrip per ref-based interaction; only safe if you know
+            // the page is static between snapshot and click).
+            if std::env::var("AGENT_BROWSER_VERIFY_REF").as_deref() != Ok("0") {
+                if let Err(e) = verify_ref_identity(
+                    client,
+                    effective_session_id,
+                    backend_node_id,
+                    &ref_id,
+                    &entry.role,
+                    &entry.name,
+                )
+                .await
+                {
+                    return Err(e);
+                }
+            }
+
             let result: Result<DomGetBoxModelResult, String> = client
                 .send_command_typed(
                     "DOM.getBoxModel",
@@ -230,6 +254,24 @@ pub async fn resolve_element_object_id(
 
         // Try cached backend_node_id first (fast path)
         if let Some(backend_node_id) = entry.backend_node_id {
+            // Same identity guard as resolve_element_center — see that
+            // function for why React DOM-node-reuse breaks ref-based
+            // interactions if we skip this.
+            if std::env::var("AGENT_BROWSER_VERIFY_REF").as_deref() != Ok("0") {
+                if let Err(e) = verify_ref_identity(
+                    client,
+                    effective_session_id,
+                    backend_node_id,
+                    &ref_id,
+                    &entry.role,
+                    &entry.name,
+                )
+                .await
+                {
+                    return Err(e);
+                }
+            }
+
             let result: Result<DomResolveNodeResult, String> = client
                 .send_command_typed(
                     "DOM.resolveNode",
@@ -333,6 +375,57 @@ fn resolve_frame_session<'a>(
         .unwrap_or(session_id)
 }
 
+/// Verify that the cached backendNodeId still has the same accessible role
+/// and name it had when the snapshot ran. Catches the case where React (or
+/// any reconciler) reused the DOM node for a different component instance
+/// — same physical node, different semantics.
+///
+/// On mismatch, returns an actionable error naming both the snapshot label
+/// and the current label so the agent can re-snapshot intelligently.
+/// On any CDP failure (e.g. node deleted), returns Ok(()) so the caller's
+/// existing fallback (`find_node_id_by_role_name`) takes over.
+async fn verify_ref_identity(
+    client: &CdpClient,
+    session_id: &str,
+    backend_node_id: i64,
+    ref_id: &str,
+    expected_role: &str,
+    expected_name: &str,
+) -> Result<(), String> {
+    let params = serde_json::json!({
+        "backendNodeId": backend_node_id,
+        "fetchRelatives": false,
+    });
+    let resp: Result<GetFullAXTreeResult, String> = client
+        .send_command_typed("Accessibility.getPartialAXTree", &params, Some(session_id))
+        .await;
+    let Ok(tree) = resp else {
+        // Node likely gone; let the box-model call fail and trigger fallback.
+        return Ok(());
+    };
+    // Find the AXNode for our backendNodeId. fetchRelatives=false still
+    // returns ancestors; the target node has the matching backendNodeId.
+    let Some(node) = tree
+        .nodes
+        .iter()
+        .find(|n| n.backend_d_o_m_node_id == Some(backend_node_id))
+    else {
+        return Ok(());
+    };
+    let actual_role = extract_ax_string(&node.role);
+    let actual_name = extract_ax_string(&node.name);
+    if actual_role == expected_role && actual_name == expected_name {
+        return Ok(());
+    }
+    Err(format!(
+        "Ref {} no longer matches its snapshot. Was [{} \"{}\"], now [{} \"{}\"].\n\
+         The DOM mutated between snapshot and interaction (typical with React/Vue \
+         reusing nodes during re-render). Take a fresh snapshot, then re-target.\n\
+         To bypass this guard set AGENT_BROWSER_VERIFY_REF=0.",
+        ref_id, expected_role, expected_name, actual_role, actual_name,
+    ))
+}
+
 /// Re-query the accessibility tree to find a node matching role+name+nth,
 /// returning its fresh backendDOMNodeId. This uses the same data source
 /// (Accessibility.getFullAXTree) that built the ref map during snapshot,

package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-browser-stealth",
-  "version": "0.27.0-fork.3",
+  "version": "0.27.0-fork.5",
   "description": "Browser automation CLI for AI agents — stealth fork with anti-detection",
   "type": "module",
   "files": [