agent-device 0.19.0 → 0.19.1

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

@@ -99,7 +99,7 @@ extension RunnerTests {
     .table
   ]
 
-  private static let flatInteractiveFallbackBudget: TimeInterval = 1.0
+  static let flatInteractiveFallbackBudget: TimeInterval = 1.0
 
   func snapshotFast(app: XCUIApplication, options: SnapshotOptions) throws -> DataPayload {
     if let blocking = blockingSystemAlertSnapshot() {
@@ -387,6 +387,7 @@ extension RunnerTests {
 
   func snapshotAccessibilityUnavailable(failure: SnapshotCaptureFailure) -> DataPayload {
     NSLog("AGENT_DEVICE_RUNNER_SNAPSHOT_AX_UNAVAILABLE=%@", failure.message)
+    runnerAccessibilityHealth = .unavailable
     invalidateCachedTarget(reason: Self.axSnapshotUnavailableReason)
     // This is a planned terminal result, so it carries the structured verdict like every other
     // planned snapshot — downstream sparse handling keys off the verdict, not node shapes.
@@ -526,12 +527,22 @@ extension RunnerTests {
   func makeSnapshotTraversalContext(
     app: XCUIApplication,
     options: SnapshotOptions,
-    captureDeadline: Date = .distantFuture
+    captureDeadline: Date = .distantFuture,
+    treeCaptureSliceBudgetOverride: TimeInterval? = nil
   ) throws -> SnapshotTraversalContext? {
-    let viewport = safeSnapshotViewport(app: app)
-    let queryRoot = options.scope.flatMap { findScopeElement(app: app, scope: $0) } ?? app
+    let (viewport, queryRoot) = try runMainThreadWork(
+      command: nil,
+      timeout: min(1.0, max(0.1, captureDeadline.timeIntervalSinceNow)),
+      timeoutError: snapshotMainThreadTimeoutError("preparing tree snapshot")
+    ) {
+      (
+        self.safeSnapshotViewport(app: app),
+        options.scope.flatMap { self.findScopeElement(app: app, scope: $0) } ?? app
+      )
+    }
 
-    let slice = min(treeCaptureSliceBudget, max(0.5, captureDeadline.timeIntervalSinceNow))
+    let treeSliceBudget = treeCaptureSliceBudgetOverride ?? treeCaptureSliceBudget
+    let slice = min(treeSliceBudget, max(0.5, captureDeadline.timeIntervalSinceNow))
     guard let rootSnapshot = try captureSnapshotRootBounded(queryRoot, sliceSeconds: slice) else {
       return nil
     }
@@ -547,7 +558,7 @@ extension RunnerTests {
     )
   }
 
-  static let treeCaptureTimeoutCode = "IOS_TREE_CAPTURE_TIMEOUT"
+  static let xCTestSnapshotTimeoutCode = "IOS_TREE_CAPTURE_TIMEOUT"
 
   func hasAbandonedTreeCapture() -> Bool {
     treeCaptureLock.lock()
@@ -555,63 +566,60 @@ extension RunnerTests {
     return abandonedTreeCaptureCount > 0
   }
 
-  /// Runs the blocking tree-snapshot XPC on a worker thread bounded by `sliceSeconds`. On
-  /// timeout the XPC keeps running on its worker (it cannot be cancelled); the capture is
-  /// marked abandoned so plans avoid XCTest-backed tiers until it drains, the tree backend is
-  /// penalized for this bundle, and the plan moves on to the private AX backend (#1105).
+  /// Runs the blocking tree-snapshot XPC on the main thread bounded by `sliceSeconds`. On
+  /// timeout the XPC keeps running on main (it cannot be cancelled); the capture is marked
+  /// abandoned so plans avoid XCTest-backed tiers until it drains, the tree backend is penalized
+  /// for this bundle, and the plan moves to the platform's independent recovery tier when one
+  /// exists (#1105/#1122).
   private func captureSnapshotRootBounded(
     _ element: XCUIElement,
     sliceSeconds: TimeInterval
   ) throws -> XCUIElementSnapshot? {
-    final class TreeCaptureBox {
-      var abandoned = false
-      var outcome: Result<XCUIElementSnapshot?, Error>?
+    if Thread.isMainThread {
+      return try captureSnapshotRoot(element)
     }
-    let box = TreeCaptureBox()
-    let semaphore = DispatchSemaphore(value: 0)
-    DispatchQueue.global(qos: .userInitiated).async {
-      var result: Result<XCUIElementSnapshot?, Error>
-      do {
-        result = .success(try self.captureSnapshotRoot(element))
-      } catch {
-        result = .failure(error)
-      }
-      self.treeCaptureLock.lock()
-      if box.abandoned {
+    return try runMainThreadWork(
+      command: nil,
+      timeout: sliceSeconds,
+      timeoutError: treeCaptureTimeoutError(sliceSeconds: sliceSeconds),
+      onAbandoned: {
+        self.treeCaptureLock.lock()
+        self.abandonedTreeCaptureCount += 1
+        self.treeCaptureLock.unlock()
+        NSLog("AGENT_DEVICE_RUNNER_TREE_CAPTURE_SLICE_TIMEOUT slice=%.1f", sliceSeconds)
+        self.penalizeSnapshotXCTestChannel(
+          bundleId: self.currentBundleId,
+          reason: "tree_capture_slice_timeout"
+        )
+      },
+      onDrained: {
+        self.treeCaptureLock.lock()
         self.abandonedTreeCaptureCount -= 1
         self.treeCaptureLock.unlock()
         NSLog("AGENT_DEVICE_RUNNER_TREE_CAPTURE_DRAINED")
-      } else {
-        box.outcome = result
-        self.treeCaptureLock.unlock()
       }
-      semaphore.signal()
+    ) {
+      try self.captureSnapshotRoot(element)
     }
-    if semaphore.wait(timeout: .now() + sliceSeconds) == .timedOut {
-      treeCaptureLock.lock()
-      let timedOut = box.outcome == nil
-      if timedOut {
-        box.abandoned = true
-        abandonedTreeCaptureCount += 1
-      }
-      treeCaptureLock.unlock()
-      if timedOut {
-        NSLog("AGENT_DEVICE_RUNNER_TREE_CAPTURE_SLICE_TIMEOUT slice=%.1f", sliceSeconds)
-        penalizeSnapshotTreeBackend(bundleId: currentBundleId, reason: "tree_capture_slice_timeout")
-        throw SnapshotCaptureFailure(
-          code: Self.treeCaptureTimeoutCode,
-          message: "the XCTest tree capture exceeded its \(Int(sliceSeconds))s time slice",
-          hint: "The capture plan recovers through the private AX backend on this screen."
-        )
-      }
+  }
+
+  private func treeCaptureTimeoutError(sliceSeconds: TimeInterval) -> () -> Error {
+    {
+      SnapshotCaptureFailure(
+        code: Self.xCTestSnapshotTimeoutCode,
+        message: "the XCTest tree capture exceeded its \(Int(sliceSeconds))s time slice",
+        hint: "The capture plan will avoid or tightly bound XCTest-backed snapshot tiers on this screen."
+      )
     }
-    switch box.outcome {
-    case .success(let snapshot):
-      return snapshot
-    case .failure(let error):
-      throw error
-    case .none:
-      return nil
+  }
+
+  func snapshotMainThreadTimeoutError(_ operation: String) -> () -> Error {
+    {
+      SnapshotCaptureFailure(
+        code: Self.xCTestSnapshotTimeoutCode,
+        message: "timed out while \(operation) on the XCTest main thread",
+        hint: "The capture plan will skip XCTest-backed snapshot tiers while the previous main-thread work drains."
+      )
     }
   }
 

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

@@ -28,6 +28,40 @@ enum SnapshotBackendKind: String, CaseIterable {
   case recursiveTree = "tree"
   case querySweep = "queries"
   case privateAX = "private-ax"
+
+  var usesXCTestAccessibilityChannel: Bool {
+    switch self {
+    case .recursiveTree, .querySweep:
+      return true
+    case .privateAX:
+      return false
+    }
+  }
+
+  var isAvailableOnCurrentPlatform: Bool {
+    switch self {
+    case .recursiveTree, .querySweep:
+      return true
+    case .privateAX:
+      #if os(iOS) && targetEnvironment(simulator)
+        return true
+      #else
+        return false
+      #endif
+    }
+  }
+}
+
+enum SnapshotXCTestChannelPlanState: Equatable {
+  case normal
+  case deferredToIndependentBackend
+  case boundedXCTestProbe
+}
+
+struct EffectiveSnapshotCapturePlan {
+  let plan: [SnapshotBackendKind]
+  let xCTestChannelState: SnapshotXCTestChannelPlanState
+  let treeCaptureSliceBudgetOverride: TimeInterval?
 }
 
 /// What the plan runner does when every backend failed or stayed sparse.
@@ -52,6 +86,7 @@ extension RunnerTests {
   /// but chained recovery tiers must never stack past the 30s main-thread watchdog: when the
   /// budget is spent, remaining tiers are skipped and the best payload so far is returned.
   static let snapshotPlanBudget: TimeInterval = 20
+  static let penalizedXCTestProbeTreeSliceBudget: TimeInterval = 1
   static let collapsedLeafMinimumSegments = 10
 
   static func payloadNodeCount(_ payload: DataPayload?) -> Int {
@@ -63,44 +98,68 @@ extension RunnerTests {
   static let regularVisiblePlan: [SnapshotBackendKind] = [.recursiveTree, .querySweep, .privateAX]
   static let rawDiagnosticPlan: [SnapshotBackendKind] = [.recursiveTree, .privateAX]
 
-  // MARK: Tree-backend penalty (cross-attempt memory, #1105)
+  // MARK: XCTest accessibility channel penalty (cross-attempt memory, #1105/#1156)
   //
   // On some deep/dynamic screens the XCTest bulk snapshot no longer fails fast with
   // kAXErrorIllegalArgument (the #758 signature) — it grinds for many seconds first. One slow
   // grind is tolerable; re-grinding on every subsequent capture of the same screen buries the
-  // main thread past the execution watchdog. After a slow or abandoned tree capture, later
-  // plans for the same bundle lead with the private AX backend until the penalty expires.
-
-  func penalizeSnapshotTreeBackend(bundleId: String?, reason: String) {
-    snapshotTreePenaltyLock.lock()
-    snapshotTreePenaltyBundleId = bundleId
-    snapshotTreePenaltyUntil = Date().addingTimeInterval(snapshotTreePenaltyDuration)
-    snapshotTreePenaltyLock.unlock()
+  // main thread past the execution watchdog. After a slow, timed-out, or abandoned XCTest-backed
+  // capture, later plans for the same bundle use non-XCTest recovery tiers until the penalty expires.
+
+  func penalizeSnapshotXCTestChannel(bundleId: String?, reason: String) {
+    snapshotXCTestChannelPenaltyLock.lock()
+    snapshotXCTestChannelPenaltyBundleId = bundleId
+    snapshotXCTestChannelPenaltyUntil = Date().addingTimeInterval(snapshotXCTestChannelPenaltyDuration)
+    snapshotXCTestChannelPenaltyLock.unlock()
     NSLog(
-      "AGENT_DEVICE_RUNNER_SNAPSHOT_TREE_PENALIZED bundle=%@ reason=%@",
+      "AGENT_DEVICE_RUNNER_SNAPSHOT_XCTEST_CHANNEL_PENALIZED bundle=%@ reason=%@",
       bundleId ?? "",
       reason
     )
   }
 
-  func isSnapshotTreeBackendPenalized(bundleId: String?) -> Bool {
-    snapshotTreePenaltyLock.lock()
-    defer { snapshotTreePenaltyLock.unlock() }
-    guard Date() < snapshotTreePenaltyUntil else { return false }
+  func isSnapshotXCTestChannelPenalized(bundleId: String?) -> Bool {
+    snapshotXCTestChannelPenaltyLock.lock()
+    defer { snapshotXCTestChannelPenaltyLock.unlock() }
+    guard Date() < snapshotXCTestChannelPenaltyUntil else { return false }
     // A penalty recorded without a bundle id applies to whatever target is current.
-    guard let penalized = snapshotTreePenaltyBundleId else { return true }
+    guard let penalized = snapshotXCTestChannelPenaltyBundleId else { return true }
     return penalized == bundleId
   }
 
-  /// Pure plan-reorder rule: a penalized tree backend defers to the private AX backend on the
-  /// regular plan only. The raw diagnostic plan keeps tree-first errors, and unknown plans are
-  /// left untouched.
+  /// Pure plan-reorder rule: a penalized XCTest accessibility channel uses independent backends
+  /// when the platform has one, otherwise it keeps XCTest work on a short probe. The raw
+  /// diagnostic plan keeps tree-first errors, and unknown plans are left untouched.
   static func effectiveSnapshotCapturePlan(
     _ plan: [SnapshotBackendKind],
-    treePenalized: Bool
-  ) -> (plan: [SnapshotBackendKind], treeDeferred: Bool) {
-    guard treePenalized, plan == Self.regularVisiblePlan else { return (plan, false) }
-    return ([.privateAX, .querySweep, .recursiveTree], true)
+    xCTestChannelPenalized: Bool,
+    availableBackends: Set<SnapshotBackendKind> = Set(SnapshotBackendKind.allCases)
+  ) -> EffectiveSnapshotCapturePlan {
+    guard xCTestChannelPenalized, plan == Self.regularVisiblePlan else {
+      return EffectiveSnapshotCapturePlan(
+        plan: plan,
+        xCTestChannelState: .normal,
+        treeCaptureSliceBudgetOverride: nil
+      )
+    }
+    let availablePlan = plan.filter { availableBackends.contains($0) }
+    let recoveryPlan = availablePlan.filter { !$0.usesXCTestAccessibilityChannel }
+    if !recoveryPlan.isEmpty {
+      return EffectiveSnapshotCapturePlan(
+        plan: recoveryPlan,
+        xCTestChannelState: .deferredToIndependentBackend,
+        treeCaptureSliceBudgetOverride: nil
+      )
+    }
+    return EffectiveSnapshotCapturePlan(
+      plan: availablePlan.filter(\.usesXCTestAccessibilityChannel),
+      xCTestChannelState: .boundedXCTestProbe,
+      treeCaptureSliceBudgetOverride: Self.penalizedXCTestProbeTreeSliceBudget
+    )
+  }
+
+  func shouldSkipSnapshotBackendForAbandonedTreeCapture(_ kind: SnapshotBackendKind) -> Bool {
+    kind.usesXCTestAccessibilityChannel && hasAbandonedTreeCapture()
   }
 
   // MARK: Plan runner
@@ -116,22 +175,34 @@ extension RunnerTests {
     var axFailure: SnapshotCaptureFailure?
     let deadline = Date().addingTimeInterval(Self.snapshotPlanBudget)
 
-    // Reorder is gated to iOS simulators — the only place the private AX backend exists, so
-    // the deferred plan cannot degrade platforms where the tree backend is the strongest tier.
-    var treePenalized = false
-#if os(iOS) && targetEnvironment(simulator)
-    treePenalized = isSnapshotTreeBackendPenalized(bundleId: currentBundleId)
+    // Reorder is iOS-only because hostile screens can make XCTest tree/query work grind while
+    // the app remains visually responsive. Simulators can avoid that channel through private AX;
+    // physical devices have no independent semantic backend yet, so they use a bounded probe.
+    var xCTestChannelPenalized = false
+#if os(iOS)
+    xCTestChannelPenalized = isSnapshotXCTestChannelPenalized(bundleId: currentBundleId)
 #endif
-    let (effectivePlan, treeDeferred) = Self.effectiveSnapshotCapturePlan(
+    let effective = Self.effectiveSnapshotCapturePlan(
       plan,
-      treePenalized: treePenalized
+      xCTestChannelPenalized: xCTestChannelPenalized,
+      availableBackends: Set(SnapshotBackendKind.allCases.filter(\.isAvailableOnCurrentPlatform))
     )
-    if treeDeferred {
+    let effectivePlan = effective.plan
+    switch effective.xCTestChannelState {
+    case .normal:
+      break
+    case .deferredToIndependentBackend:
+      firstFailure = (
+        "XCTest-backed snapshot tiers were deferred after recent slow accessibility work on this screen",
+        "budget"
+      )
+      NSLog("AGENT_DEVICE_RUNNER_SNAPSHOT_XCTEST_CHANNEL_DEFERRED bundle=%@", currentBundleId ?? "")
+    case .boundedXCTestProbe:
       firstFailure = (
-        "the XCTest tree backend was deferred after a recent slow capture on this screen",
+        "XCTest-backed snapshot tiers are running with a short recovery probe after recent slow accessibility work on this screen",
         "budget"
       )
-      NSLog("AGENT_DEVICE_RUNNER_SNAPSHOT_TREE_DEFERRED bundle=%@", currentBundleId ?? "")
+      NSLog("AGENT_DEVICE_RUNNER_SNAPSHOT_XCTEST_CHANNEL_PROBE_BOUNDED bundle=%@", currentBundleId ?? "")
     }
 
     for kind in effectivePlan {
@@ -143,8 +214,8 @@ extension RunnerTests {
         break
       }
       // While an abandoned tree capture is still grinding inside testmanagerd, XCTest-backed
-      // tiers would block behind it; only the private AX backend stays responsive (#1105).
-      if kind != .privateAX, hasAbandonedTreeCapture() {
+      // tiers would block behind it; only independent backends stay responsive (#1105).
+      if shouldSkipSnapshotBackendForAbandonedTreeCapture(kind) {
         NSLog("AGENT_DEVICE_RUNNER_SNAPSHOT_TIER_SKIPPED_XCTEST_OCCUPIED tier=%@", kind.rawValue)
         if firstFailure == nil {
           firstFailure = (
@@ -157,15 +228,23 @@ extension RunnerTests {
       let capture: SnapshotBackendCapture
       let backendStartedAt = Date()
       do {
-        guard let result = try captureWithBackend(kind, app: app, options: options, deadline: deadline)
+        guard
+          let result = try captureWithBackend(
+            kind,
+            app: app,
+            options: options,
+            deadline: deadline,
+            treeCaptureSliceBudgetOverride: effective.treeCaptureSliceBudgetOverride
+          )
         else {
-          recordSlowTreeBackendIfNeeded(kind, startedAt: backendStartedAt)
+          recordSlowXCTestSnapshotBackendIfNeeded(kind, startedAt: backendStartedAt)
           continue
         }
         capture = result
-        recordSlowTreeBackendIfNeeded(kind, startedAt: backendStartedAt)
+        recordSlowXCTestSnapshotBackendIfNeeded(kind, startedAt: backendStartedAt)
       } catch let failure as SnapshotCaptureFailure {
-        recordSlowTreeBackendIfNeeded(kind, startedAt: backendStartedAt)
+        recordXCTestSnapshotBackendFailureIfNeeded(kind, failure: failure)
+        recordSlowXCTestSnapshotBackendIfNeeded(kind, startedAt: backendStartedAt)
         if Self.isAxSnapshotFailure(failure) { axFailure = failure }
         if firstFailure == nil {
           firstFailure = (failure.message, Self.isAxSnapshotFailure(failure) ? "ax-rejected" : "capture-failed")
@@ -186,7 +265,7 @@ extension RunnerTests {
         continue
       }
 
-      let recovered = kind != effectivePlan.first || treeDeferred
+      let recovered = kind != effectivePlan.first || effective.xCTestChannelState != .normal
       if recovered {
         NSLog(
           "AGENT_DEVICE_RUNNER_SNAPSHOT_RECOVERED backend=%@ reason=%@",
@@ -225,22 +304,33 @@ extension RunnerTests {
       best.map { stampedSnapshotPayload($0.capture, backend: $0.kind, state: "sparse", reason: firstFailure) }
       ?? stampedSnapshotPayload(
         SnapshotBackendCapture(payload: sparseTruncatedSnapshotPayload(), effectiveDepth: nil),
-        backend: plan.last ?? .recursiveTree,
+        backend: effectivePlan.last ?? plan.last ?? .recursiveTree,
         state: "sparse",
         reason: firstFailure
       )
     return fallbackPayload
   }
 
-  /// Marks the tree backend as penalized when a capture attempt ground past the slow-capture
+  /// Marks XCTest-backed snapshot tiers as penalized when one attempt ground past the slow-capture
   /// threshold — even a successful one: the next capture of this screen must not re-grind.
-  private func recordSlowTreeBackendIfNeeded(_ kind: SnapshotBackendKind, startedAt: Date) {
-    guard kind == .recursiveTree else { return }
+  private func recordSlowXCTestSnapshotBackendIfNeeded(_ kind: SnapshotBackendKind, startedAt: Date) {
+    guard kind.usesXCTestAccessibilityChannel else { return }
     let elapsed = Date().timeIntervalSince(startedAt)
-    guard elapsed > snapshotTreeSlowCaptureThreshold else { return }
-    penalizeSnapshotTreeBackend(
+    guard elapsed > snapshotXCTestSlowCaptureThreshold else { return }
+    penalizeSnapshotXCTestChannel(
       bundleId: currentBundleId,
-      reason: "slow_tree_capture_\(Int(elapsed * 1000))ms"
+      reason: "slow_\(kind.rawValue)_capture_\(Int(elapsed * 1000))ms"
+    )
+  }
+
+  private func recordXCTestSnapshotBackendFailureIfNeeded(
+    _ kind: SnapshotBackendKind,
+    failure: SnapshotCaptureFailure
+  ) {
+    guard kind.usesXCTestAccessibilityChannel, failure.code == Self.xCTestSnapshotTimeoutCode else { return }
+    penalizeSnapshotXCTestChannel(
+      bundleId: currentBundleId,
+      reason: "\(kind.rawValue)_backend_timeout"
     )
   }
 
@@ -248,7 +338,8 @@ extension RunnerTests {
     _ kind: SnapshotBackendKind,
     app: XCUIApplication,
     options: SnapshotOptions,
-    deadline: Date
+    deadline: Date,
+    treeCaptureSliceBudgetOverride: TimeInterval?
   ) throws -> SnapshotBackendCapture? {
     switch kind {
     case .recursiveTree:
@@ -256,20 +347,31 @@ extension RunnerTests {
         let context = try makeSnapshotTraversalContext(
           app: app,
           options: options,
-          captureDeadline: deadline
+          captureDeadline: deadline,
+          treeCaptureSliceBudgetOverride: treeCaptureSliceBudgetOverride
         )
       else {
         return nil
       }
-      let payload = options.raw
-        ? try rawTreeSnapshotPayload(context: context, options: options)
-        : recursiveTreeSnapshotPayload(context: context, options: options)
+      let payload = try runMainThreadWork(
+        command: nil,
+        timeout: min(treeCaptureSliceBudget, max(0.5, deadline.timeIntervalSinceNow)),
+        timeoutError: snapshotMainThreadTimeoutError("processing tree snapshot")
+      ) {
+        options.raw
+          ? try self.rawTreeSnapshotPayload(context: context, options: options)
+          : self.recursiveTreeSnapshotPayload(context: context, options: options)
+      }
       return SnapshotBackendCapture(payload: payload, effectiveDepth: nil)
     case .querySweep:
-      return SnapshotBackendCapture(
-        payload: snapshotFlatInteractive(app: app, options: options, planDeadline: deadline),
-        effectiveDepth: nil
-      )
+      let payload = try runMainThreadWork(
+        command: nil,
+        timeout: min(Self.flatInteractiveFallbackBudget, max(0.1, deadline.timeIntervalSinceNow)),
+        timeoutError: snapshotMainThreadTimeoutError("running query-sweep snapshot")
+      ) {
+        self.snapshotFlatInteractive(app: app, options: options, planDeadline: deadline)
+      }
+      return SnapshotBackendCapture(payload: payload, effectiveDepth: nil)
     case .privateAX:
       return privateAXSnapshotCapture(app: app, options: options, deadline: deadline)
     }
@@ -349,6 +451,7 @@ extension RunnerTests {
     state: String,
     reason: (reason: String, code: String)?
   ) -> DataPayload {
+    runnerAccessibilityHealth = reason?.code == "ax-rejected" ? .unavailable : .healthy
     let payload = capture.payload
     let quality = SnapshotQuality(
       state: state,
@@ -377,7 +480,7 @@ extension RunnerTests {
         ? " The primary capture ran out of its time budget (busy app or simulator); the recovered tree is authoritative for this screen."
         : " This usually means the app publishes an unhealthy accessibility tree — fixing the app's accessibility is the real cure. Treat screenshot as visual truth when this warning appears."
       parts.append(
-        "Recovered this snapshot with the \(quality.backend) accessibility backend"
+        "Detected an overly complex or slow accessibility tree. Fell back to the \(quality.backend) snapshot backend"
           + (quality.reason.map { " after: \($0)." } ?? ".")
           + meaning
       )

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

@@ -0,0 +1,142 @@
+import XCTest
+
+// Runner-local policy for AX-free/private synthesized iOS gestures.
+//
+// This policy is intentionally separate from the TS interaction guarantee matrix:
+// ADR 0011 models element-targeting guarantees, while this module models command
+// paths that must keep scroll/drag/sequence usable when XCTest AX is unhealthy.
+
+enum RunnerAccessibilityHealth: String, Equatable {
+  case unknown
+  case healthy
+  case unavailable
+}
+
+enum SynthesizedKeyboardPolicy: String, Equatable, Hashable {
+  case never
+  case whenAccessibilityHealthy
+  case requiredWhenAvailable
+
+  func allowsProbe(accessibilityHealth: RunnerAccessibilityHealth) -> Bool {
+    switch self {
+    case .never:
+      return false
+    case .whenAccessibilityHealthy:
+      return accessibilityHealth == .healthy
+    case .requiredWhenAvailable:
+      return accessibilityHealth != .unavailable
+    }
+  }
+}
+
+enum SynthesizedFallbackPolicy: String, Equatable, Hashable {
+  case privateSynthesisRequired
+  case xctestCoordinateWhenAccessibilityAvailable
+  case xctestCoordinateAllowed
+
+  func allowsXCTestCoordinateFallback(accessibilityHealth: RunnerAccessibilityHealth) -> Bool {
+    switch self {
+    case .privateSynthesisRequired:
+      return false
+    case .xctestCoordinateWhenAccessibilityAvailable:
+      return accessibilityHealth != .unavailable
+    case .xctestCoordinateAllowed:
+      return true
+    }
+  }
+}
+
+enum SynthesizedGesturePolicyKind: String, Equatable, Hashable {
+  case coordinateTap
+  case scroll
+  case synthesizedDrag
+}
+
+struct SynthesizedGesturePolicy: Equatable, Hashable {
+  let keyboardPolicy: SynthesizedKeyboardPolicy
+  let fallbackPolicy: SynthesizedFallbackPolicy
+}
+
+struct SynthesizedCoordinateContext {
+  let referenceFrame: CGRect
+  let keyboardPolicy: SynthesizedKeyboardPolicy
+  let fallbackPolicy: SynthesizedFallbackPolicy
+  let accessibilityHealth: RunnerAccessibilityHealth
+
+  func withReferenceFrame(_ frame: CGRect) -> SynthesizedCoordinateContext {
+    SynthesizedCoordinateContext(
+      referenceFrame: frame,
+      keyboardPolicy: keyboardPolicy,
+      fallbackPolicy: fallbackPolicy,
+      accessibilityHealth: accessibilityHealth
+    )
+  }
+
+  var allowsXCTestCoordinateFallback: Bool {
+    fallbackPolicy.allowsXCTestCoordinateFallback(accessibilityHealth: accessibilityHealth)
+  }
+
+  var allowsKeyboardProbe: Bool {
+    keyboardPolicy.allowsProbe(accessibilityHealth: accessibilityHealth)
+  }
+}
+
+func synthesizedGesturePolicy(_ kind: SynthesizedGesturePolicyKind) -> SynthesizedGesturePolicy {
+  switch kind {
+  case .coordinateTap:
+    return SynthesizedGesturePolicy(
+      keyboardPolicy: .never,
+      fallbackPolicy: .xctestCoordinateAllowed
+    )
+  case .scroll:
+    return SynthesizedGesturePolicy(
+      keyboardPolicy: .whenAccessibilityHealthy,
+      fallbackPolicy: .privateSynthesisRequired
+    )
+  case .synthesizedDrag:
+    return SynthesizedGesturePolicy(
+      keyboardPolicy: .requiredWhenAvailable,
+      fallbackPolicy: .xctestCoordinateWhenAccessibilityAvailable
+    )
+  }
+}
+
+func sequenceHasSynthesizedCoordinateStep(_ steps: [SequenceStep]) -> Bool {
+  steps.contains { step in
+    step.synthesized == true && (step.kind == "tap" || step.kind == "drag")
+  }
+}
+
+extension RunnerTests {
+  func synthesizedSequenceCoordinateContext(steps: [SequenceStep]) -> SynthesizedCoordinateContext? {
+    guard sequenceHasSynthesizedCoordinateStep(steps) else { return nil }
+    return synthesizedCoordinateContext(policy: synthesizedGesturePolicy(.synthesizedDrag))
+  }
+
+  func logSynthesizedGesturePolicyDecision(
+    kind: SynthesizedGesturePolicyKind,
+    context: SynthesizedCoordinateContext?,
+    fallbackAttempted: Bool
+  ) {
+#if os(iOS)
+    guard let context else {
+      NSLog(
+        "AGENT_DEVICE_RUNNER_SYNTHESIZED_GESTURE_POLICY kind=%@ context=unavailable fallbackAttempted=%@",
+        kind.rawValue,
+        fallbackAttempted.description
+      )
+      return
+    }
+    NSLog(
+      "AGENT_DEVICE_RUNNER_SYNTHESIZED_GESTURE_POLICY kind=%@ axHealth=%@ frameSource=screenshot keyboardPolicy=%@ fallbackPolicy=%@ fallbackAllowed=%@ fallbackAttempted=%@",
+      kind.rawValue,
+      context.accessibilityHealth.rawValue,
+      context.keyboardPolicy.rawValue,
+      context.fallbackPolicy.rawValue,
+      context.allowsXCTestCoordinateFallback.description,
+      fallbackAttempted.description
+    )
+#endif
+  }
+}
+