fix(cua-driver): classify an AX reply before the selection fallback

A reply the application answered the action with reached the collection-row
selection fallback before it was classified. That fallback writes AXSelected
and reads it back, so a -25200/-25205/-25206 press on a row-like element
mutated the selection a second time and returned selection_verified, which
the caller publishes as effect: confirmed with no reply code — the opposite of
the uncertain dispatch this branch exists to report.

The reply now decides what may happen next: an answered dispatch reports
itself and touches nothing further, while a genuine refusal (Finder's -25204
on a row whose selectable object is an ancestor) keeps the fallback. The
published half of the result moves into ax_click_structured so the effect,
delivery mode and evidence a caller sees are testable without a live window
server.

Author: will-bogusz

libs/cua-driver/rust/crates/platform-macos/src/tools/click.rs

@@ -101,6 +101,42 @@ fn ax_reply_is_outcome_unverifiable(code: crate::ax::bindings::AXError) -> bool
     )
 }
 
+/// What a reply to `AXUIElementPerformAction` licenses the driver to do next.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+enum AxReplyDisposition {
+    Performed,
+    /// The application answered the action without saying whether it acted, so
+    /// nothing further may touch the UI: a selection write could act a second
+    /// time, and its read-back would then report a confirmed effect the reply
+    /// does not support.
+    Dispatched(crate::ax::bindings::AXError),
+    /// A refusal to a plain press. Finder answers `kAXErrorCannotComplete` for
+    /// a press on a collection row whose selectable object is an ancestor, so
+    /// the bounded `AXSelected` fallback is still worth trying.
+    TrySelection(crate::ax::bindings::AXError),
+    Failed(crate::ax::bindings::AXError),
+}
+
+fn ax_reply_disposition(
+    code: crate::ax::bindings::AXError,
+    ax_action: &str,
+    modifiers: &[String],
+) -> AxReplyDisposition {
+    if code == crate::ax::bindings::kAXErrorSuccess {
+        AxReplyDisposition::Performed
+    } else if ax_reply_is_outcome_unverifiable(code) {
+        AxReplyDisposition::Dispatched(code)
+    } else if ax_action == "AXPress" && modifiers.is_empty() {
+        AxReplyDisposition::TrySelection(code)
+    } else {
+        AxReplyDisposition::Failed(code)
+    }
+}
+
+fn ax_reply_failure(ax_action: &str, code: crate::ax::bindings::AXError) -> anyhow::Error {
+    anyhow::anyhow!("AXUIElementPerformAction({ax_action}) returned {code}")
+}
+
 fn ax_reply_code_name(code: crate::ax::bindings::AXError) -> &'static str {
     match code {
         crate::ax::bindings::kAXErrorFailure => "kAXErrorFailure",
@@ -728,69 +764,15 @@ impl Tool for ClickTool {
             let changes = super::finish_window_observation(snapshot, &args).await;
 
             match result {
-                Ok(Ok((
-                    AxClickOutcome {
-                        summary: mut msg,
-                        needs_webkit_delay,
-                        suspected_noop,
-                        selection_verified,
-                        selection_via_pixel,
-                        unverified,
-                    },
-                    fronted,
-                ))) => {
+                Ok(Ok((mut outcome, fronted))) => {
                     // For text inputs, wait 800ms for WebKit DOM focus to settle
                     // before returning — matches the Swift reference behaviour.
-                    if needs_webkit_delay {
+                    if outcome.needs_webkit_delay {
                         tokio::time::sleep(std::time::Duration::from_millis(800)).await;
                     }
+                    let structured = ax_click_structured(&outcome, fronted);
+                    let mut msg = std::mem::take(&mut outcome.summary);
                     msg.push_str(&changes.result_suffix());
-                    // AX dispatch went through, but AXPerformAction returning
-                    // success does not confirm the on-screen effect (many elements
-                    // no-op silently). A click is never driver-verifiable (no
-                    // read-back) → verified:false stays for back-compat. The
-                    // tri-state `effect` is the richer signal:
-                    //   * suspected_noop — the element didn't advertise the action,
-                    //     so the press likely did nothing → cross to vision/pixel.
-                    //   * unverifiable — dispatched fine, driver just can't confirm;
-                    //     the caller verifies via screenshot.
-                    let mut structured = serde_json::json!({
-                        "path": if selection_via_pixel {
-                            if fronted { "cgevent_fg" } else { "cgevent" }
-                        } else if fronted {
-                            "ax_fg"
-                        } else {
-                            "ax"
-                        },
-                        "verified": selection_verified,
-                        "effect": if selection_verified {
-                            "confirmed"
-                        } else if suspected_noop {
-                            "suspected_noop"
-                        } else {
-                            "unverifiable"
-                        },
-                    });
-                    if selection_verified {
-                        structured["evidence"] = serde_json::json!([
-                            { "kind": "accessibility_readback" }
-                        ]);
-                    }
-                    // The application answered the dispatch with a code that
-                    // establishes neither delivery nor a no-op, so the mode
-                    // the action was delivered in is not known either.
-                    if unverified.is_some() {
-                        structured["delivery_mode"] = serde_json::json!("unknown");
-                    }
-                    if suspected_noop {
-                        structured["escalation"] = serde_json::json!({
-                            "recommended": "px",
-                            "reason": "element does not advertise this action — the \
-                                       AX press likely no-op'd. Do an element px \
-                                       action: click by pixel (x,y) off the \
-                                       screenshot from get_window_state."
-                        });
-                    }
                     ToolResult::text(msg).with_structured(structured)
                 }
                 Ok(Err(e)) => ToolResult::error(format!("AX action failed: {e}")),
@@ -1251,6 +1233,49 @@ struct AxClickOutcome {
     unverified: Option<crate::ax::bindings::AXError>,
 }
 
+/// The machine-readable half of an AX click result. A generic click has no
+/// independent read-back, so `verified` stays false unless a selection write
+/// was confirmed, and the tri-state `effect` carries the richer verdict:
+/// `suspected_noop` for an action the element never advertised (cross to the
+/// vision/pixel path), `unverifiable` for a dispatch the driver cannot settle
+/// (the caller's own observation does). A reply that establishes neither
+/// delivery nor a no-op leaves the delivery mode unknown as well.
+fn ax_click_structured(outcome: &AxClickOutcome, fronted: bool) -> serde_json::Value {
+    let mut structured = serde_json::json!({
+        "path": if outcome.selection_via_pixel {
+            if fronted { "cgevent_fg" } else { "cgevent" }
+        } else if fronted {
+            "ax_fg"
+        } else {
+            "ax"
+        },
+        "verified": outcome.selection_verified,
+        "effect": if outcome.selection_verified {
+            "confirmed"
+        } else if outcome.suspected_noop {
+            "suspected_noop"
+        } else {
+            "unverifiable"
+        },
+    });
+    if outcome.selection_verified {
+        structured["evidence"] = serde_json::json!([{ "kind": "accessibility_readback" }]);
+    }
+    if outcome.unverified.is_some() {
+        structured["delivery_mode"] = serde_json::json!("unknown");
+    }
+    if outcome.suspected_noop {
+        structured["escalation"] = serde_json::json!({
+            "recommended": "px",
+            "reason": "element does not advertise this action — the \
+                       AX press likely no-op'd. Do an element px \
+                       action: click by pixel (x,y) off the \
+                       screenshot from get_window_state."
+        });
+    }
+    structured
+}
+
 fn perform_ax_click(
     element_ptr: usize,
     idx: usize,
@@ -1393,30 +1418,25 @@ fn perform_ax_click(
     }
 
     let err = unsafe { crate::ax::bindings::perform_action(element, ax_action) };
-    let unverified = if err == crate::ax::bindings::kAXErrorSuccess {
-        None
-    } else {
-        // Some collection rows claim a click-like action but Finder returns
-        // kAXErrorCannotComplete. Use the same verified selection fallback
-        // before surfacing the dispatch error.
-        if ax_action == "AXPress" && modifiers.is_empty() {
+    let unverified = match ax_reply_disposition(err, ax_action, modifiers) {
+        AxReplyDisposition::Performed => None,
+        AxReplyDisposition::Dispatched(code) => Some(code),
+        AxReplyDisposition::TrySelection(code) => {
             if let Some(selected_role) =
                 crate::input::ax_actions::select_nearest_container(element_ptr)
             {
                 return Ok(AxClickOutcome {
                     summary: format!(
                         "✅ Selected nearest {selected_role} for [{idx}] {role} \"{title}\" \
-                         after AXPress returned {err}; confirmed AXSelected=true."
+                         after AXPress returned {code}; confirmed AXSelected=true."
                     ),
                     selection_verified: true,
                     ..AxClickOutcome::default()
                 });
             }
+            return Err(ax_reply_failure(ax_action, code));
         }
-        if !ax_reply_is_outcome_unverifiable(err) {
-            anyhow::bail!("AXUIElementPerformAction({ax_action}) returned {err}");
-        }
-        Some(err)
+        AxReplyDisposition::Failed(code) => return Err(ax_reply_failure(ax_action, code)),
     };
 
     let mut summary = ax_reply_summary(unverified, ax_action, idx, &role, &title);
@@ -1728,4 +1748,73 @@ mod tests {
             "strict-suppression paths retain their existing ownership"
         );
     }
+
+    /// The reply decides what may happen next, before anything else touches
+    /// the UI. An application that answered the action may have performed it,
+    /// so the collection-row selection fallback — an `AXSelected` write whose
+    /// read-back would publish a confirmed effect — must not run for those
+    /// replies. `-25204` (kAXErrorCannotComplete) is the refusal that fallback
+    /// exists for and keeps it.
+    #[test]
+    fn an_unverifiable_reply_is_classified_before_the_selection_fallback() {
+        for code in [
+            crate::ax::bindings::kAXErrorFailure,
+            crate::ax::bindings::kAXErrorAttributeUnsupported,
+            crate::ax::bindings::kAXErrorActionUnsupported,
+        ] {
+            assert_eq!(
+                ax_reply_disposition(code, "AXPress", &[]),
+                AxReplyDisposition::Dispatched(code),
+                "{code}"
+            );
+        }
+        assert_eq!(
+            ax_reply_disposition(-25204, "AXPress", &[]),
+            AxReplyDisposition::TrySelection(-25204)
+        );
+        assert_eq!(
+            ax_reply_disposition(-25204, "AXPress", &["cmd".to_string()]),
+            AxReplyDisposition::Failed(-25204),
+            "a modified click never improvises a selection"
+        );
+        assert_eq!(
+            ax_reply_disposition(-25204, "AXShowMenu", &[]),
+            AxReplyDisposition::Failed(-25204),
+            "only a plain press has a selection equivalent"
+        );
+        assert_eq!(
+            ax_reply_disposition(crate::ax::bindings::kAXErrorSuccess, "AXPress", &[]),
+            AxReplyDisposition::Performed
+        );
+    }
+
+    /// The published result of a dispatch the application answered: uncertain,
+    /// with the delivery mode unknown and no read-back evidence. Only a
+    /// confirmed selection write earns `confirmed`.
+    #[test]
+    fn an_answered_dispatch_is_not_published_as_a_confirmed_effect() {
+        let dispatched = ax_click_structured(
+            &AxClickOutcome {
+                unverified: Some(crate::ax::bindings::kAXErrorFailure),
+                ..AxClickOutcome::default()
+            },
+            false,
+        );
+        assert_eq!(dispatched["effect"], "unverifiable");
+        assert_eq!(dispatched["verified"], false);
+        assert_eq!(dispatched["delivery_mode"], "unknown");
+        assert!(dispatched.get("evidence").is_none(), "{dispatched}");
+
+        let selected = ax_click_structured(
+            &AxClickOutcome {
+                selection_verified: true,
+                ..AxClickOutcome::default()
+            },
+            false,
+        );
+        assert_eq!(selected["effect"], "confirmed");
+        assert_eq!(selected["verified"], true);
+        assert_eq!(selected["evidence"][0]["kind"], "accessibility_readback");
+        assert!(selected.get("delivery_mode").is_none(), "{selected}");
+    }
 }