agent-device 0.20.6 → 0.20.7

package/dist/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerSelectorMatchPolicy.swift

@@ -0,0 +1,78 @@
+struct SelectorCandidateFacts {
+  let isHittable: Bool
+  let hasTappableFrame: Bool
+  let containsExpectedPoint: Bool
+
+  init(
+    isHittable: Bool,
+    hasTappableFrame: Bool,
+    containsExpectedPoint: Bool = true
+  ) {
+    self.isHittable = isHittable
+    self.hasTappableFrame = hasTappableFrame
+    self.containsExpectedPoint = containsExpectedPoint
+  }
+}
+
+enum DirectSelectorCandidateDecision: Equatable {
+  case noMatch
+  case selected(index: Int, usedNonHittableFallback: Bool)
+  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. 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,
+  rawMatchPolicy: DirectSelectorRawMatchPolicy = .rejectDistinctMatches
+) -> DirectSelectorCandidateDecision {
+  let eligible = candidates.indices.filter { index in
+    !filtersByExpectedPoint || candidates[index].containsExpectedPoint
+  }
+
+  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)
+  }
+
+  var hittableIndex: Int?
+  var fallbackIndex: Int?
+  for index in eligible {
+    let candidate = candidates[index]
+    if candidate.isHittable {
+      guard hittableIndex == nil else { return .ambiguous }
+      hittableIndex = index
+    } else if allowNonHittableFallback && candidate.hasTappableFrame {
+      guard fallbackIndex == nil else { return .ambiguous }
+      fallbackIndex = index
+    }
+  }
+  if let hittableIndex {
+    return .selected(index: hittableIndex, usedNonHittableFallback: false)
+  }
+  if let fallbackIndex {
+    return .selected(index: fallbackIndex, usedNonHittableFallback: true)
+  }
+  return .noMatch
+}

package/dist/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+AXSnapshotFallback.swift

@@ -9,6 +9,12 @@ extension RunnerTests {
   /// the capture-plan deadline, which is also enforced per call.
   private static let privateAXDeepExtensionCallLimit = 8
 
+  /// Upper bound on per-element custom-action reads per capture. Each is its own
+  /// AX round trip (~100ms on an idle simulator), so this caps the opt-in cost
+  /// at roughly a second on top of the capture; the capture-plan deadline stops
+  /// it earlier under load. A screenful of merged cards is well under this.
+  private static let privateAXCustomActionLimit = 12
+
   /// A capture is depth-limited unless its frontier extension resolved every
   /// capped node: frontiers left pending (budget/deadline) or missed (element
   /// vanished, re-rooted request failed) mean subtrees are still absent, and
@@ -42,6 +48,24 @@ extension RunnerTests {
     return depths.filter { $0 <= remembered }
   }
 
+  /// The bridge omits the key entirely when the capture did not ask for custom
+  /// actions, which is the difference between "nothing to disclose" and "read
+  /// none of them" — so a missing key must stay nil, never (0, 0).
+  static func privateAXCustomActionCoverage(_ raw: Any?) -> SnapshotCustomActionCoverage? {
+    guard let coverage = raw as? [String: Any],
+      let read = (coverage[RunnerAXSnapshotCustomActionsReadKey] as? NSNumber)?.intValue,
+      let candidates = (coverage[RunnerAXSnapshotCustomActionsCandidatesKey] as? NSNumber)?.intValue
+    else { return nil }
+    // read/candidates are the ratio and must both be present; the truncation
+    // count is additive, so an older bridge that omits it reads as zero rather
+    // than voiding the whole coverage.
+    let truncated =
+      (coverage[RunnerAXSnapshotCustomActionsTruncatedKey] as? NSNumber)?.intValue ?? 0
+    let blocked = (coverage[RunnerAXSnapshotCustomActionsBlockedKey] as? NSNumber)?.boolValue ?? false
+    return SnapshotCustomActionCoverage(
+      read: read, candidates: candidates, truncated: truncated, blocked: blocked)
+  }
+
   func rememberPrivateAXAcceptedDepth(bundleId: String?, processIdentifier: Int?, depth: Int) {
     // No PID means no way to notice a relaunch later; record nothing rather than risk serving
     // a stale shallow rung to a fresh process.
@@ -116,6 +140,7 @@ extension RunnerTests {
           maxDepth: depth,
           maxNodes: Self.privateAXSnapshotMaxNodes,
           deepExtensionCallLimit: exactDepthRequested ? 0 : Self.privateAXDeepExtensionCallLimit,
+          customActionLimit: options.customActions ? Self.privateAXCustomActionLimit : 0,
           deadline: deadline
         )
         if response["ok"] as? Bool == true {
@@ -184,7 +209,10 @@ extension RunnerTests {
       )
       return SnapshotBackendCapture(
         payload: DataPayload(nodes: nodes, truncated: (response["truncated"] as? Bool) == true),
-        effectiveDepth: depthLimited ? effectiveDepth : nil
+        effectiveDepth: depthLimited ? effectiveDepth : nil,
+        customActions: Self.privateAXCustomActionCoverage(
+          response[RunnerAXSnapshotCustomActionsKey]
+        )
       )
     #else
       return nil
@@ -274,7 +302,8 @@ extension RunnerTests {
           depth: depth,
           parentIndex: parentIndex,
           hiddenContentAbove: nil,
-          hiddenContentBelow: nil
+          hiddenContentBelow: nil,
+          actions: rawNode["actions"] as? [String]
         )
       )
     } else {

package/dist/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CommandExecution.swift

@@ -586,12 +586,18 @@ extension RunnerTests {
   /// Pure command→options projection, extracted so the runner unit bundle can
   /// prove the decoded wire field actually reaches capture options (#1634 P2).
   static func snapshotOptions(from command: Command) -> SnapshotOptions {
-    SnapshotOptions(
+    let customActions = command.customActions ?? false
+    return SnapshotOptions(
       interactiveOnly: command.interactiveOnly ?? false,
       depth: command.depth,
       scope: command.scope,
       raw: command.raw ?? false,
+      // Custom actions are only readable through the private AX client, so
+      // asking for them pins that backend rather than silently returning a
+      // capture that structurally cannot carry them. An explicit pin wins.
       preferredBackend: command.preferredBackend
+        ?? (customActions ? SnapshotBackendKind.privateAX.rawValue : nil),
+      customActions: customActions
     )
   }
 
@@ -871,7 +877,7 @@ extension RunnerTests {
     return .context(ActiveCommandContext(app: activeApp))
   }
 
-  private func executeOnMainPrepared(
+  func executeOnMainPrepared(
     command: Command,
     activeApp: XCUIApplication,
     alertDeadline: Date? = nil
@@ -1016,7 +1022,23 @@ extension RunnerTests {
         return Response(ok: false, error: ErrorPayload(code: "ELEMENT_NOT_FOUND", message: "element not found"))
       }
       if let x = command.x, let y = command.y {
-        let textInput = textInputAt(app: activeApp, x: x, y: y)
+        let xCTestChannelPenalized = isSnapshotXCTestChannelPenalized(
+          bundleId: currentBundleId
+        )
+        let xCTestTextInputProbeSkipped = !shouldProbeCoordinateTapTextInput(
+          xCTestChannelPenalized: xCTestChannelPenalized
+        )
+        let textInput: XCUIElement?
+        if !xCTestTextInputProbeSkipped {
+          textInput = textInputAt(app: activeApp, x: x, y: y)
+        } else {
+          // A process-scoped tap cannot authorize later typing without concrete element identity.
+          textInput = nil
+          NSLog(
+            "AGENT_DEVICE_RUNNER_COORDINATE_TAP_TEXT_INPUT_PROBE_SKIPPED bundle=%@",
+            currentBundleId ?? ""
+          )
+        }
         var fallback: GestureFallback?
         if command.synthesized == true {
           let policyKind = SynthesizedGesturePolicyKind.coordinateTap
@@ -1710,11 +1732,11 @@ extension RunnerTests {
     return message == "scrolled" ? "scroll" : "drag"
   }
 
-  private func currentXCTestFailureCount() -> Int {
+  func currentXCTestFailureCount() -> Int {
     return testRun?.failureCount ?? 0
   }
 
-  private func didRecordXCTestFailure(since failureCountBefore: Int) -> Bool {
+  func didRecordXCTestFailure(since failureCountBefore: Int) -> Bool {
     return currentXCTestFailureCount() > failureCountBefore
   }
 
@@ -1736,7 +1758,7 @@ extension RunnerTests {
     )
   }
 
-  private func runnerCommandFixture(_ json: String) throws -> Command {
+  func runnerCommandFixture(_ json: String) throws -> Command {
     try JSONDecoder().decode(Command.self, from: Data(json.utf8))
   }
 
@@ -1815,7 +1837,7 @@ extension RunnerTests {
     return XCUIApplication(bundleIdentifier: bundleId)
   }
 
-  private func executeTypeCommand(activeApp: XCUIApplication, command: Command) -> Response {
+  func executeTypeCommand(activeApp: XCUIApplication, command: Command) -> Response {
     guard let text = command.text else {
       return Response(ok: false, error: ErrorPayload(message: "type requires text"))
     }

package/dist/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CoordinateTextEntryTests.swift

@@ -0,0 +1,4 @@
+import XCTest
+
+extension RunnerTests {
+}

package/dist/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 {
@@ -149,35 +150,32 @@ extension RunnerTests {
       return SelectorElementMatch(element: nil, isAmbiguous: false, usedNonHittableFallback: false)
     }
 
-    var matchedElement: XCUIElement?
-    var nonHittableElement: XCUIElement?
     let matches = app.descendants(matching: .any).matching(predicate).allElementsBoundByIndex
-    for element in matches where element.exists {
-      if let expectedPoint, !element.frame.contains(expectedPoint) {
-        continue
-      }
-      if !element.isHittable {
-        if allowNonHittableFallback && hasTappableFrame(app: app, element: element) {
-          guard nonHittableElement == nil else {
-            return SelectorElementMatch(element: nil, isAmbiguous: true, usedNonHittableFallback: false)
-          }
-          nonHittableElement = element
-        }
-        continue
-      }
-      guard matchedElement == nil else {
-        return SelectorElementMatch(element: nil, isAmbiguous: true, usedNonHittableFallback: false)
-      }
-      matchedElement = element
+      .filter(\.exists)
+    let facts = matches.map { element in
+      SelectorCandidateFacts(
+        isHittable: element.isHittable,
+        hasTappableFrame: hasTappableFrame(app: app, element: element),
+        containsExpectedPoint: expectedPoint.map(element.frame.contains) ?? true
+      )
     }
-    if let matchedElement {
-      return SelectorElementMatch(element: matchedElement, isAmbiguous: false, usedNonHittableFallback: false)
+    switch classifyDirectSelectorCandidates(
+      facts,
+      allowNonHittableFallback: allowNonHittableFallback,
+      filtersByExpectedPoint: expectedPoint != nil,
+      rawMatchPolicy: rawMatchPolicy
+    ) {
+    case .noMatch:
+      return SelectorElementMatch(element: nil, isAmbiguous: false, usedNonHittableFallback: false)
+    case .ambiguous:
+      return SelectorElementMatch(element: nil, isAmbiguous: true, usedNonHittableFallback: false)
+    case let .selected(index, usedNonHittableFallback):
+      return SelectorElementMatch(
+        element: matches[index],
+        isAmbiguous: false,
+        usedNonHittableFallback: usedNonHittableFallback
+      )
     }
-    return SelectorElementMatch(
-      element: nonHittableElement,
-      isAmbiguous: false,
-      usedNonHittableFallback: nonHittableElement != nil
-    )
   }
 
   // Maestro-compat gate for the non-hittable coordinate fallback: an element
@@ -209,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"))
     }

package/dist/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Models.swift

@@ -138,6 +138,7 @@ struct Command: Codable {
   let fps: Int?
   let interactiveOnly: Bool?
   let preferredBackend: String?
+  let customActions: Bool?
   let depth: Int?
   let scope: String?
   let raw: Bool?
@@ -389,6 +390,9 @@ struct SnapshotNode: Codable {
   let parentIndex: Int?
   let hiddenContentAbove: Bool?
   let hiddenContentBelow: Bool?
+  /// Names of the element's UIAccessibilityCustomActions, present only when the
+  /// capture asked for them and the element carries some.
+  var actions: [String]? = nil
 }
 
 struct SnapshotOptions {
@@ -400,4 +404,7 @@ struct SnapshotOptions {
   /// health ("private-ax"). Same-backend evidence probes (tap-outcome
   /// corroboration) must be captured the way their baseline was.
   var preferredBackend: String? = nil
+  /// Read UIAccessibilityCustomActions for merged leaves. Opt-in: each element
+  /// costs its own AX round trip (see RunnerAXSnapshotBridge).
+  var customActions: Bool = false
 }

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

@@ -0,0 +1,4 @@
+import XCTest
+
+extension RunnerTests {
+}

package/dist/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Snapshot.swift

@@ -493,7 +493,8 @@ extension RunnerTests {
         reason: failure.message,
         reasonCode: "ax-rejected",
         effectiveDepth: nil,
-        collapsedLeafIndexes: nil
+        collapsedLeafIndexes: nil,
+        customActions: nil
       ),
       runnerFatal: true,
       runnerFatalReason: Self.axSnapshotUnavailableReason

package/dist/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+SnapshotCapturePlan.swift

@@ -22,6 +22,23 @@ struct SnapshotQuality: Codable {
   let effectiveDepth: Int?
   /// Leaves that merge many labels — a container marked accessible hides its descendants.
   let collapsedLeafIndexes: [Int]?
+  /// Coverage of the bounded custom-action pass, when the capture asked for one.
+  let customActions: SnapshotCustomActionCoverage?
+}
+
+/// How much of the merged-element set the custom-action pass actually read. An
+/// unread element renders exactly like one with no actions, so a partial pass
+/// has to say so — otherwise absence reads as proof of absence.
+struct SnapshotCustomActionCoverage: Codable {
+  let read: Int
+  let candidates: Int
+  /// Elements whose action list was clipped by the per-element output caps. A
+  /// clipped list looks complete, so it is disclosed on the same principle as
+  /// an unread element.
+  let truncated: Int
+  /// The pass stopped early because an earlier read is still hung. Distinct from
+  /// a budget stop: the remedy is waiting, not scrolling.
+  let blocked: Bool
 }
 
 enum SnapshotBackendKind: String, CaseIterable {
@@ -78,6 +95,8 @@ struct SnapshotBackendCapture {
   let payload: DataPayload
   /// Set by the private AX backend when the ladder accepted a shallower depth than requested.
   let effectiveDepth: Int?
+  /// Set by the private AX backend when the capture asked for custom actions.
+  var customActions: SnapshotCustomActionCoverage? = nil
 }
 
 extension RunnerTests {
@@ -149,13 +168,25 @@ extension RunnerTests {
   /// degraded on this capture, and the daemon keys warning suppression and the settle budget
   /// reset off exactly that distinction. The bounded probe keeps 'budget': its short XCTest
   /// slice genuinely constrains what this capture could read.
+  ///
+  /// `requestPinnedBackend` separates the two ways the plan can arrive at the same
+  /// deferred shape. A capture that ASKED for a private-AX-only reading (custom
+  /// actions) degraded nothing, so reporting slow accessibility work would name a
+  /// cause that does not exist.
   static func xcTestChannelStateFirstFailure(
-    _ state: SnapshotXCTestChannelPlanState
+    _ state: SnapshotXCTestChannelPlanState,
+    requestPinnedBackend: Bool = false
   ) -> (reason: String, code: String)? {
     switch state {
     case .normal:
       return nil
     case .deferredToIndependentBackend:
+      if requestPinnedBackend {
+        return (
+          "the private AX backend was selected because this capture asked for accessibility custom actions",
+          "requested-backend"
+        )
+      }
       return (
         "XCTest-backed snapshot tiers were deferred after recent slow accessibility work on this screen",
         "deferred"
@@ -237,9 +268,11 @@ extension RunnerTests {
     // penalized route: privateAX-first plan, 'deferred' verdict — the backend was pre-selected
     // deliberately, so no degradation warning should render for it.
     var xCTestChannelPenalized = false
+    var xCTestChannelPenalizedByBreaker = false
 #if os(iOS)
+    xCTestChannelPenalizedByBreaker = isSnapshotXCTestChannelPenalized(bundleId: currentBundleId)
     xCTestChannelPenalized = Self.snapshotXCTestChannelTreatedAsPenalized(
-      penalized: isSnapshotXCTestChannelPenalized(bundleId: currentBundleId),
+      penalized: xCTestChannelPenalizedByBreaker,
       preferredBackend: options.preferredBackend
     )
 #endif
@@ -249,7 +282,12 @@ extension RunnerTests {
       availableBackends: Set(SnapshotBackendKind.allCases.filter(\.isAvailableOnCurrentPlatform))
     )
     let effectivePlan = effective.plan
-    firstFailure = Self.xcTestChannelStateFirstFailure(effective.xCTestChannelState)
+    // Only a customActions-implied pin is request-pinned; the daemon's
+    // same-backend evidence probe pins for its own reasons and keeps 'deferred'.
+    firstFailure = Self.xcTestChannelStateFirstFailure(
+      effective.xCTestChannelState,
+      requestPinnedBackend: options.customActions && !xCTestChannelPenalizedByBreaker
+    )
     switch effective.xCTestChannelState {
     case .normal:
       break
@@ -462,7 +500,7 @@ extension RunnerTests {
       return ("snapshot returned no nodes", "no-nodes")
     }
     if isSparseApplicationWindowTree(nodes) {
-      return ("snapshot returned only structural application/window nodes", "sparse-tree")
+      return ("snapshot returned no semantic controls or content", "sparse-tree")
     }
     if payload.truncated == true && nodes.count <= sparseRecoveryTruncatedNodeThreshold {
       return ("snapshot was cut off by its budget with almost nothing collected", "budget")
@@ -493,19 +531,36 @@ extension RunnerTests {
 
   static func isSparseApplicationWindowTree(_ nodes: [SnapshotNode]) -> Bool {
     guard !nodes.isEmpty else { return false }
+    let rootRects = nodes.compactMap { node in
+      node.type == "Application" || node.type == "Window" ? node.rect : nil
+    }
     return nodes.allSatisfy { node in
       // Application/Window labels are just the app/window name, and full-screen roots
       // compute as hittable; neither says anything about tree health.
       let isRootContainer = node.type == "Application" || node.type == "Window"
-      let hasContent = (!isRootContainer && node.label?.isEmpty == false)
-        || node.identifier?.isEmpty == false
-        || node.value?.isEmpty == false
-      return !hasContent
-        && (isRootContainer || !node.hittable)
-        && Self.structuralOnlyNodeTypes.contains(node.type)
+      guard Self.structuralOnlyNodeTypes.contains(node.type) else { return false }
+      guard !isRootContainer else { return true }
+
+      let isFullScreenContainer = !node.hittable && rootRects.contains { rootRect in
+        rootRect.x == node.rect.x && rootRect.y == node.rect.y
+          && rootRect.width == node.rect.width && rootRect.height == node.rect.height
+      }
+      let hasAddressableIdentifier = node.identifier?.isEmpty == false && !isFullScreenContainer
+      return !Self.isSemanticSnapshotText(node.label)
+        && !Self.isSemanticSnapshotText(node.value)
+        && !hasAddressableIdentifier
     }
   }
 
+  /// Private AX can stringify an unserializable accessibility label as the JavaScript object
+  /// placeholder. It is transport residue, not UI content, and must not make a shell-only tree
+  /// look healthy.
+  static func isSemanticSnapshotText(_ text: String?) -> Bool {
+    guard let text else { return false }
+    let normalized = text.trimmingCharacters(in: .whitespacesAndNewlines)
+    return !normalized.isEmpty && normalized.lowercased() != "[object object]"
+  }
+
   /// A leaf whose label joins many short segments is a container marked as an accessibility
   /// element: the platform folds every descendant into one merged node. Nothing below it can
   /// be addressed — by automation or by assistive tech. This is app-side; no backend recovers it.
@@ -536,7 +591,8 @@ extension RunnerTests {
       reason: reason?.reason,
       reasonCode: reason?.code,
       effectiveDepth: capture.effectiveDepth,
-      collapsedLeafIndexes: Self.collapsedLeafIndexes(payload.nodes ?? [])
+      collapsedLeafIndexes: Self.collapsedLeafIndexes(payload.nodes ?? []),
+      customActions: capture.customActions
     )
     return DataPayload(
       // Legacy human text for older daemons that read message instead of snapshotQuality.
@@ -549,8 +605,39 @@ extension RunnerTests {
     )
   }
 
+  /// Response level, one line per incompleteness. An unread merged element is
+  /// byte-identical to one with no actions, and a clipped list looks complete,
+  /// so both have to name themselves.
+  static func customActionCoverageWarnings(_ coverage: SnapshotCustomActionCoverage) -> [String] {
+    var lines: [String] = []
+    if coverage.blocked {
+      // Scrolling is the remedy for a budget stop, not for this one — saying it
+      // here would send the reader off doing something that cannot help.
+      lines.append(
+        "Custom actions were not read: an earlier accessibility read is still hung, so this "
+          + "capture skipped the read pass instead of queueing behind it. No element's actions "
+          + "list is authoritative here. Reads resume once that call returns.")
+    } else if coverage.read < coverage.candidates {
+      lines.append(
+        "Custom actions were read for \(coverage.read) of \(coverage.candidates) merged elements, "
+          + "on-screen ones first; the remaining \(coverage.candidates - coverage.read) were not read, "
+          + "so an absent actions list on those is not evidence that they have none. "
+          + "Scroll them into view and re-run to read them.")
+    }
+    if coverage.truncated > 0 {
+      lines.append(
+        "\(coverage.truncated) element(s) published more custom actions than are shown; those "
+          + "lists are clipped to the first 8 names, and long names are shortened.")
+    }
+    return lines
+  }
+
   static func legacyQualityMessage(_ quality: SnapshotQuality) -> String? {
-    guard quality.state != "healthy" || quality.collapsedLeafIndexes != nil else { return nil }
+    let customActionWarnings =
+      quality.customActions.map { Self.customActionCoverageWarnings($0) } ?? []
+    guard quality.state != "healthy" || quality.collapsedLeafIndexes != nil
+      || !customActionWarnings.isEmpty
+    else { return nil }
     var parts: [String] = []
     if quality.state == "recovered" {
       let meaning = quality.reasonCode == "budget" || quality.reasonCode == "deferred"
@@ -569,6 +656,7 @@ extension RunnerTests {
           + ". Use screenshot as visual truth and coordinate taps."
       )
     }
+    parts.append(contentsOf: customActionWarnings)
     if let depth = quality.effectiveDepth {
       // No --depth remedy here: an explicit --depth capture disables the
       // frontier extension, so following it would return strictly less than

package/dist/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+SynthesizedGesturePolicy.swift

@@ -101,6 +101,10 @@ func synthesizedGesturePolicy(_ kind: SynthesizedGesturePolicyKind) -> Synthesiz
   }
 }
 
+func shouldProbeCoordinateTapTextInput(xCTestChannelPenalized: Bool) -> Bool {
+  !xCTestChannelPenalized
+}
+
 func sequenceHasSynthesizedCoordinateStep(_ steps: [SequenceStep]) -> Bool {
   steps.contains { step in
     step.synthesized == true && step.kind == "tap"

package/dist/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+SynthesizedTextEntry.swift

@@ -159,6 +159,63 @@ extension RunnerTests {
     repairMode == .none && fromTapWitness && !softwareKeyboardVisible
   }
 
+  enum SynthesizedTextCommitProgress: Equatable {
+    case committed
+    case pending
+    case diverged
+  }
+
+  // The private synthesize call returns once the event record is posted, not once the target
+  // app has committed the characters, so intermediate reads walk prefix-by-prefix toward the
+  // expected value. Anything off that prefix path means the app transformed the input
+  // (formatter, mid-text caret, autocomplete) and the runner must not second-guess it. An
+  // unreadable value — secure field, or the element stopped resolving — ends the wait the
+  // same way.
+  static func synthesizedTextCommitProgress(
+    observedText: String?,
+    expectedText: String
+  ) -> SynthesizedTextCommitProgress {
+    guard let observedText else {
+      return .diverged
+    }
+    if observedText == expectedText {
+      return .committed
+    }
+    return expectedText.hasPrefix(observedText) ? .pending : .diverged
+  }
+
+  /// Blocks until the synthesized bare-type text is observable in the target field, so `type`
+  /// cannot report ok while trailing characters are still uncommitted on a slow simulator.
+  ///
+  /// Observation only. A stalled prefix cannot be told apart from a suffix still queued in the
+  /// event stream, so re-synthesizing the difference risks committing it twice after the command
+  /// already reported success. Text carrying a submit key is skipped outright: the app may clear
+  /// or rewrite the field on submit, so `textBefore + typedText` is not the value to wait for.
+  func awaitSynthesizedFirstResponderCommit(
+    app: XCUIApplication,
+    target: TextEntryTarget,
+    textBefore: String?,
+    typedText: String
+  ) {
+    guard let textBefore, !typedText.contains("\n"), !typedText.contains("\r") else {
+      return
+    }
+    let expectedText = textBefore + typedText
+    let deadline = Date().addingTimeInterval(TextEntryTiming.synthesizedCommitTimeout)
+    while Date() < deadline {
+      let observedText = editableTextValue(
+        for: resolveTextEntryElement(app: app, target: target),
+        treatingPlaceholderAsEmpty: true
+      )
+      switch Self.synthesizedTextCommitProgress(observedText: observedText, expectedText: expectedText) {
+      case .committed, .diverged:
+        return
+      case .pending:
+        sleepFor(TextEntryTiming.pollInterval)
+      }
+    }
+  }
+
   static func shouldUseResolvedCoordinateTextEntryRoute(
     repairMode: TextTypingRepairMode,
     hasX: Bool,

package/dist/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+TextEntry.swift

@@ -40,6 +40,7 @@ extension RunnerTests {
     static let pollInterval: TimeInterval = 0.02
     static let warmupValueTimeout: TimeInterval = 0.4
     static let verificationStabilityWindow: TimeInterval = 0.2
+    static let synthesizedCommitTimeout: TimeInterval = 3.0
   }
 
   struct TextEntryResult {