fix(ios): scope the raw-match rejection to mutating dispatches

`RunnerTests+Interaction.findElement` applied the new fail-closed
classification to `querySelector` as well as press/type, because the read
call site takes the default `allowNonHittableFallback: false`. With one
visible/hittable match and one non-hittable same-selector duplicate the
query started returning AMBIGUOUS_MATCH where it previously selected the
hittable element, and `queryDirectIosSelectorOrFallback` preserves that
error for read callers — so `get`, `is`, and `wait` surfaced an error
instead of their prior answer.

`classifyDirectSelectorCandidates` now takes a `rawMatchPolicy`. Mutations
keep `.rejectDistinctMatches` (the default, so no mutation call site
changes); `queryElement` passes `.preferHittableMatch`, restoring the
prior read rule: prefer the single hittable match, ambiguous only when
hittable matches compete, and never adopt the Maestro coordinate fallback.
The Maestro expected-point path is untouched.

Covers the one-hittable + one-non-hittable read, competing hittable reads,
and the non-hittable-only read. ADR 0011's amendment now states the scope.

Author: claude

apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerSelectorMatchPolicy.swift

@@ -20,19 +20,37 @@ enum DirectSelectorCandidateDecision: Equatable {
   case ambiguous
 }
 
+/// How many raw exact matches a dispatch may discard before hittability is
+/// allowed to pick a winner. The two rows differ because the cost of guessing
+/// wrong differs, not because the matching differs.
+enum DirectSelectorRawMatchPolicy: Equatable {
+  /// Mutations fail closed: every raw exact match counts, so a hittable
+  /// element can never silently win over a same-selector duplicate the caller
+  /// never saw and act on the wrong one.
+  case rejectDistinctMatches
+  /// Reads prefer the single hittable match and ignore non-hittable
+  /// same-selector duplicates. A read has no side effect to guard, and
+  /// `querySelector` backs `get`/`is`/`wait` — failing those closed turns a
+  /// decorative duplicate into an error where the reader previously got its
+  /// answer.
+  case preferHittableMatch
+}
+
 /// Normal direct selector mutations count every raw exact match before
-/// hittability can choose a winner. Maestro's explicitly requested coordinate
-/// fallback keeps its point-filtered compatibility behavior.
+/// hittability can choose a winner. Reads keep the hittable-preference rule,
+/// and Maestro's explicitly requested coordinate fallback keeps its
+/// point-filtered compatibility behavior.
 func classifyDirectSelectorCandidates(
   _ candidates: [SelectorCandidateFacts],
   allowNonHittableFallback: Bool,
-  filtersByExpectedPoint: Bool = false
+  filtersByExpectedPoint: Bool = false,
+  rawMatchPolicy: DirectSelectorRawMatchPolicy = .rejectDistinctMatches
 ) -> DirectSelectorCandidateDecision {
   let eligible = candidates.indices.filter { index in
     !filtersByExpectedPoint || candidates[index].containsExpectedPoint
   }
 
-  if !allowNonHittableFallback {
+  if !allowNonHittableFallback && rawMatchPolicy == .rejectDistinctMatches {
     guard eligible.count <= 1 else { return .ambiguous }
     guard let index = eligible.first, candidates[index].isHittable else { return .noMatch }
     return .selected(index: index, usedNonHittableFallback: false)
@@ -45,7 +63,7 @@ func classifyDirectSelectorCandidates(
     if candidate.isHittable {
       guard hittableIndex == nil else { return .ambiguous }
       hittableIndex = index
-    } else if candidate.hasTappableFrame {
+    } else if allowNonHittableFallback && candidate.hasTappableFrame {
       guard fallbackIndex == nil else { return .ambiguous }
       fallbackIndex = index
     }

apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Interaction.swift

@@ -129,7 +129,8 @@ extension RunnerTests {
     selectorKey: String,
     selectorValue: String,
     allowNonHittableFallback: Bool = false,
-    expectedPoint: CGPoint? = nil
+    expectedPoint: CGPoint? = nil,
+    rawMatchPolicy: DirectSelectorRawMatchPolicy = .rejectDistinctMatches
   ) -> SelectorElementMatch {
     let value = selectorValue.trimmingCharacters(in: .whitespacesAndNewlines)
     guard !value.isEmpty else {
@@ -161,7 +162,8 @@ extension RunnerTests {
     switch classifyDirectSelectorCandidates(
       facts,
       allowNonHittableFallback: allowNonHittableFallback,
-      filtersByExpectedPoint: expectedPoint != nil
+      filtersByExpectedPoint: expectedPoint != nil,
+      rawMatchPolicy: rawMatchPolicy
     ) {
     case .noMatch:
       return SelectorElementMatch(element: nil, isAmbiguous: false, usedNonHittableFallback: false)
@@ -205,7 +207,17 @@ extension RunnerTests {
   }
 
   func queryElement(app: XCUIApplication, selectorKey: String, selectorValue: String) -> Response {
-    let match = findElement(app: app, selectorKey: selectorKey, selectorValue: selectorValue)
+    // querySelector is a read — it backs get/is/wait and the offscreen-refusal
+    // double-check, none of which mutate. The fail-closed raw-match rule exists
+    // to stop a mutation acting on an unseen duplicate; applying it here would
+    // instead turn a decorative non-hittable duplicate into an AMBIGUOUS_MATCH
+    // for readers that previously resolved the hittable element.
+    let match = findElement(
+      app: app,
+      selectorKey: selectorKey,
+      selectorValue: selectorValue,
+      rawMatchPolicy: .preferHittableMatch
+    )
     if match.isAmbiguous {
       return Response(ok: false, error: ErrorPayload(code: "AMBIGUOUS_MATCH", message: "selector matched multiple elements"))
     }

apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+SelectorMatchPolicyTests.swift

@@ -24,6 +24,50 @@ extension RunnerTests {
     )
   }
 
+  // The read rows below are the regression guard for scoping the fail-closed
+  // rule to mutations: querySelector backs get/is/wait, so the exact shape
+  // that must stay resolvable is one hittable match beside a non-hittable
+  // same-selector duplicate.
+  func testReadSelectorPrefersTheHittableMatchOverANonHittableDuplicate() {
+    let decision = classifyDirectSelectorCandidates(
+      [
+        SelectorCandidateFacts(isHittable: true, hasTappableFrame: true),
+        SelectorCandidateFacts(isHittable: false, hasTappableFrame: true),
+      ],
+      allowNonHittableFallback: false,
+      rawMatchPolicy: .preferHittableMatch
+    )
+
+    XCTAssertEqual(decision, .selected(index: 0, usedNonHittableFallback: false))
+  }
+
+  func testReadSelectorStillRejectsTwoHittableMatches() {
+    XCTAssertEqual(
+      classifyDirectSelectorCandidates(
+        [
+          SelectorCandidateFacts(isHittable: true, hasTappableFrame: true),
+          SelectorCandidateFacts(isHittable: true, hasTappableFrame: true),
+        ],
+        allowNonHittableFallback: false,
+        rawMatchPolicy: .preferHittableMatch
+      ),
+      .ambiguous
+    )
+  }
+
+  // A read never coordinate-taps, so a non-hittable-only match stays a miss
+  // rather than borrowing the Maestro fallback.
+  func testReadSelectorDoesNotAdoptTheNonHittableCoordinateFallback() {
+    XCTAssertEqual(
+      classifyDirectSelectorCandidates(
+        [SelectorCandidateFacts(isHittable: false, hasTappableFrame: true)],
+        allowNonHittableFallback: false,
+        rawMatchPolicy: .preferHittableMatch
+      ),
+      .noMatch
+    )
+  }
+
   func testMaestroSelectorKeepsExpectedPointAndNonHittableFallbackSemantics() {
     XCTAssertEqual(
       classifyDirectSelectorCandidates(

docs/adr/0011-interaction-guarantee-contract.md

@@ -251,9 +251,13 @@ The replacement contract is structural. Multiple matches collapse only when
 all matches form one ancestor–descendant chain and every member resolves to the
 same actionable node. Otherwise the mutation fails with `AMBIGUOUS_MATCH`, a
 bounded list of snapshot candidate lines, and a partial ref frame generation so
-the caller can retry one listed candidate immediately. The direct XCTest path
-counts all raw exact matches before hittability can select a winner and delegates
-multiple matches to the runtime classifier; Maestro's explicit expected-point /
+the caller can retry one listed candidate immediately. On the direct XCTest path
+this applies to mutating dispatches only: they count all raw exact matches before
+hittability can select a winner and delegate multiple matches to the runtime
+classifier. Reads (`querySelector`, and so `get`/`is`/`wait`) keep the prior rule
+— prefer the single hittable match, ambiguous only when hittable matches compete
+— because a read has no side effect to guard and failing it closed would turn a
+decorative duplicate into an error. Maestro's explicit expected-point /
 non-hittable compatibility path remains intentionally separate.
 
 ### Synthesized iOS gesture policy