agent-device 0.18.3 → 0.19.1

package/{apple-runner → 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() {
@@ -302,7 +302,11 @@ extension RunnerTests {
     return DataPayload(nodes: nodes, truncated: false)
   }
 
-  func snapshotFlatInteractive(app: XCUIApplication, options: SnapshotOptions) -> DataPayload {
+  func snapshotFlatInteractive(
+    app: XCUIApplication,
+    options: SnapshotOptions,
+    planDeadline: Date = .distantFuture
+  ) -> DataPayload {
     var nodes: [SnapshotNode] = [
       interactiveRootNode(rect: .zero)
     ]
@@ -310,9 +314,12 @@ extension RunnerTests {
       return DataPayload(nodes: nodes, truncated: false)
     }
 
-    let deadline = options.interactiveOnly
+    // Bounded by both its own sweep budget and the umbrella capture-plan deadline, so a
+    // chained recovery tier can never push the plan past the main-thread watchdog (#1105).
+    let sweepDeadline = options.interactiveOnly
       ? Date().addingTimeInterval(Self.flatInteractiveFallbackBudget)
       : Date.distantFuture
+    let deadline = min(sweepDeadline, planDeadline)
     let viewport = safeSnapshotViewport(app: app)
     var seen = Set<String>()
     var candidates: [SnapshotNode] = []
@@ -380,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.
@@ -426,50 +434,6 @@ extension RunnerTests {
     )
   }
 
-#if AGENT_DEVICE_RUNNER_UNIT_TESTS
-  func testSnapshotAccessibilityUnavailableMarksSparseSnapshotRunnerFatal() {
-    currentApp = app
-    currentBundleId = "com.example.app"
-
-    let payload = snapshotAccessibilityUnavailable(
-      failure: SnapshotCaptureFailure(
-        code: Self.axSnapshotErrorCode,
-        message: Self.axSnapshotFailureMessage,
-        hint: Self.axSnapshotHint
-      )
-    )
-
-    XCTAssertEqual(payload.message, "\(Self.axSnapshotFailureMessage) Hint: \(Self.axSnapshotHint)")
-    XCTAssertEqual(payload.nodes?.count, 1)
-    XCTAssertEqual(payload.nodes?.first?.type, "Application")
-    XCTAssertEqual(payload.truncated, true)
-    XCTAssertEqual(payload.runnerFatal, true)
-    XCTAssertEqual(payload.runnerFatalReason, Self.axSnapshotUnavailableReason)
-    XCTAssertNil(currentApp)
-    XCTAssertNil(currentBundleId)
-  }
-
-  func testRecoveredSnapshotMessagePreservesHint() {
-    let message = recoveredSnapshotMessage(
-      SnapshotCaptureFailure(
-        code: Self.axSnapshotErrorCode,
-        message: Self.axSnapshotFailureMessage,
-        hint: Self.axSnapshotHint
-      )
-    )
-
-    XCTAssertTrue(message.contains(Self.axSnapshotFailureMessage))
-    XCTAssertTrue(message.contains(Self.axSnapshotHint))
-  }
-
-  func testRawSnapshotTooLargeFailureIsStructured() {
-    let failure = rawSnapshotTooLargeFailure(nodeCount: Self.rawSnapshotMaxNodes + 1)
-
-    XCTAssertEqual(failure.code, Self.rawSnapshotTooLargeCode)
-    XCTAssertTrue(failure.message.contains("\(Self.rawSnapshotMaxNodes) nodes"))
-    XCTAssertEqual(failure.hint, Self.rawSnapshotTooLargeHint)
-  }
-#endif
 
   private func interactiveRootNode(rect: CGRect) -> SnapshotNode {
     SnapshotNode(
@@ -562,12 +526,24 @@ extension RunnerTests {
 
   func makeSnapshotTraversalContext(
     app: XCUIApplication,
-    options: SnapshotOptions
+    options: SnapshotOptions,
+    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
+      )
+    }
 
-    guard let rootSnapshot = try captureSnapshotRoot(queryRoot) else {
+    let treeSliceBudget = treeCaptureSliceBudgetOverride ?? treeCaptureSliceBudget
+    let slice = min(treeSliceBudget, max(0.5, captureDeadline.timeIntervalSinceNow))
+    guard let rootSnapshot = try captureSnapshotRootBounded(queryRoot, sliceSeconds: slice) else {
       return nil
     }
 
@@ -582,6 +558,71 @@ extension RunnerTests {
     )
   }
 
+  static let xCTestSnapshotTimeoutCode = "IOS_TREE_CAPTURE_TIMEOUT"
+
+  func hasAbandonedTreeCapture() -> Bool {
+    treeCaptureLock.lock()
+    defer { treeCaptureLock.unlock() }
+    return abandonedTreeCaptureCount > 0
+  }
+
+  /// 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? {
+    if Thread.isMainThread {
+      return try captureSnapshotRoot(element)
+    }
+    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")
+      }
+    ) {
+      try self.captureSnapshotRoot(element)
+    }
+  }
+
+  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."
+      )
+    }
+  }
+
+  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."
+      )
+    }
+  }
+
   private func captureSnapshotRoot(_ element: XCUIElement) throws -> XCUIElementSnapshot? {
     var rootSnapshot: XCUIElementSnapshot?
     var swiftErrorMessage: String?

package/{apple-runner → 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,6 +98,70 @@ extension RunnerTests {
   static let regularVisiblePlan: [SnapshotBackendKind] = [.recursiveTree, .querySweep, .privateAX]
   static let rawDiagnosticPlan: [SnapshotBackendKind] = [.recursiveTree, .privateAX]
 
+  // 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, 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_XCTEST_CHANNEL_PENALIZED bundle=%@ reason=%@",
+      bundleId ?? "",
+      reason
+    )
+  }
+
+  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 = snapshotXCTestChannelPenaltyBundleId else { return true }
+    return penalized == bundleId
+  }
+
+  /// 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],
+    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
 
   func runSnapshotCapturePlan(
@@ -76,21 +175,76 @@ extension RunnerTests {
     var axFailure: SnapshotCaptureFailure?
     let deadline = Date().addingTimeInterval(Self.snapshotPlanBudget)
 
-    for kind in plan {
-      if kind != plan.first && Date() >= deadline {
+    // 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 effective = Self.effectiveSnapshotCapturePlan(
+      plan,
+      xCTestChannelPenalized: xCTestChannelPenalized,
+      availableBackends: Set(SnapshotBackendKind.allCases.filter(\.isAvailableOnCurrentPlatform))
+    )
+    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 = (
+        "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_XCTEST_CHANNEL_PROBE_BOUNDED bundle=%@", currentBundleId ?? "")
+    }
+
+    for kind in effectivePlan {
+      if kind != effectivePlan.first && Date() >= deadline {
         NSLog("AGENT_DEVICE_RUNNER_SNAPSHOT_PLAN_BUDGET_EXHAUSTED skipped=%@", kind.rawValue)
         if firstFailure == nil {
           firstFailure = ("the capture plan ran out of its time budget", "budget")
         }
         break
       }
+      // While an abandoned tree capture is still grinding inside testmanagerd, XCTest-backed
+      // 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 = (
+            "the XCTest capture channel is occupied by an abandoned tree capture",
+            "budget"
+          )
+        }
+        continue
+      }
       let capture: SnapshotBackendCapture
+      let backendStartedAt = Date()
       do {
-        guard let result = try captureWithBackend(kind, app: app, options: options) else {
+        guard
+          let result = try captureWithBackend(
+            kind,
+            app: app,
+            options: options,
+            deadline: deadline,
+            treeCaptureSliceBudgetOverride: effective.treeCaptureSliceBudgetOverride
+          )
+        else {
+          recordSlowXCTestSnapshotBackendIfNeeded(kind, startedAt: backendStartedAt)
           continue
         }
         capture = result
+        recordSlowXCTestSnapshotBackendIfNeeded(kind, startedAt: backendStartedAt)
       } catch let failure as SnapshotCaptureFailure {
+        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")
@@ -111,7 +265,7 @@ extension RunnerTests {
         continue
       }
 
-      let recovered = kind != plan.first
+      let recovered = kind != effectivePlan.first || effective.xCTestChannelState != .normal
       if recovered {
         NSLog(
           "AGENT_DEVICE_RUNNER_SNAPSHOT_RECOVERED backend=%@ reason=%@",
@@ -150,34 +304,76 @@ 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 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 recordSlowXCTestSnapshotBackendIfNeeded(_ kind: SnapshotBackendKind, startedAt: Date) {
+    guard kind.usesXCTestAccessibilityChannel else { return }
+    let elapsed = Date().timeIntervalSince(startedAt)
+    guard elapsed > snapshotXCTestSlowCaptureThreshold else { return }
+    penalizeSnapshotXCTestChannel(
+      bundleId: currentBundleId,
+      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"
+    )
+  }
+
   private func captureWithBackend(
     _ kind: SnapshotBackendKind,
     app: XCUIApplication,
-    options: SnapshotOptions
+    options: SnapshotOptions,
+    deadline: Date,
+    treeCaptureSliceBudgetOverride: TimeInterval?
   ) throws -> SnapshotBackendCapture? {
     switch kind {
     case .recursiveTree:
-      guard let context = try makeSnapshotTraversalContext(app: app, options: options) else {
+      guard
+        let context = try makeSnapshotTraversalContext(
+          app: app,
+          options: options,
+          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),
-        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)
+      return privateAXSnapshotCapture(app: app, options: options, deadline: deadline)
     }
   }
 
@@ -255,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,
@@ -283,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
       )
@@ -304,124 +501,3 @@ extension RunnerTests {
   }
 }
 
-#if AGENT_DEVICE_RUNNER_UNIT_TESTS
-// MARK: - In-bundle unit tests
-
-extension RunnerTests {
-  private func planTestNode(
-    index: Int,
-    type: String,
-    label: String? = nil,
-    identifier: String? = nil,
-    hittable: Bool = false,
-    parentIndex: Int? = nil
-  ) -> SnapshotNode {
-    SnapshotNode(
-      index: index,
-      type: type,
-      label: label,
-      identifier: identifier,
-      value: nil,
-      rect: snapshotRect(from: .zero),
-      enabled: true,
-      focused: nil,
-      selected: nil,
-      hittable: hittable,
-      depth: parentIndex == nil ? 0 : 1,
-      parentIndex: parentIndex,
-      hiddenContentAbove: nil,
-      hiddenContentBelow: nil
-    )
-  }
-
-  func testSparsePayloadReasonMatrix() {
-    let root = planTestNode(index: 0, type: "Application", label: "Example App", hittable: true)
-    let window = planTestNode(index: 1, type: "Window", parentIndex: 0)
-    let button = planTestNode(index: 1, type: "Button", label: "Ok", hittable: true, parentIndex: 0)
-
-    // Labeled, hittable root over a bare window is still sparse.
-    XCTAssertNotNil(Self.sparsePayloadReason(DataPayload(nodes: [root, window], truncated: false)))
-    // Deadline-truncated near-empty sweep needs recovery even with one real control.
-    XCTAssertNotNil(Self.sparsePayloadReason(DataPayload(nodes: [root, button], truncated: true)))
-    // The same tiny tree from a completed sweep is a legitimately minimal screen.
-    XCTAssertNil(Self.sparsePayloadReason(DataPayload(nodes: [root, button], truncated: false)))
-    // Empty payloads are degraded.
-    XCTAssertNotNil(Self.sparsePayloadReason(DataPayload(nodes: [], truncated: false)))
-  }
-
-  func testCollapsedLeafIndexesFlagsMergedContainersOnly() {
-    let root = planTestNode(index: 0, type: "Application", label: "App")
-    let merged = planTestNode(
-      index: 1,
-      type: "Other",
-      label: (0...30).map { "Row \($0), Tap" }.joined(separator: ", "),
-      parentIndex: 0
-    )
-    let prose = planTestNode(
-      index: 2,
-      type: "StaticText",
-      label: (0...30).map { "clause \($0)" }.joined(separator: ", "),
-      parentIndex: 0
-    )
-    XCTAssertEqual(Self.collapsedLeafIndexes([root, merged, prose]), [1])
-    XCTAssertNil(Self.collapsedLeafIndexes([root, prose]))
-  }
-
-  func testLegacyQualityMessageStatesFallbackMeaning() {
-    let recovered = SnapshotQuality(
-      state: "recovered",
-      backend: "queries",
-      reason: "snapshot returned only structural application/window nodes",
-      reasonCode: "sparse-tree",
-      effectiveDepth: nil,
-      collapsedLeafIndexes: nil
-    )
-    let message = Self.legacyQualityMessage(recovered)
-    XCTAssertTrue(message?.contains("queries accessibility backend") == true)
-    XCTAssertTrue(message?.contains("fixing the app's accessibility") == true)
-    XCTAssertTrue(message?.contains("screenshot as visual truth") == true)
-    XCTAssertNil(
-      Self.legacyQualityMessage(
-        SnapshotQuality(
-          state: "healthy", backend: "tree", reason: nil, reasonCode: nil, effectiveDepth: nil,
-          collapsedLeafIndexes: nil)
-      )
-    )
-  }
-  func testTerminalFailsClosedOnInteractiveAxFailureRegardlessOfSparseBest() {
-    // Interactive AX failure must invalidate + fail closed; a later tier's sparse synthetic-root
-    // "best" must never downgrade this to a returned-sparse payload (regression: best == nil guard).
-    XCTAssertEqual(
-      Self.resolveSnapshotPlanTerminal(terminal: .sparseWithFatalOnAXFailure, interactiveOnly: true),
-      .failClosed
-    )
-    XCTAssertEqual(
-      Self.resolveSnapshotPlanTerminal(terminal: .sparseWithFatalOnAXFailure, interactiveOnly: false),
-      .sparseBest
-    )
-    XCTAssertEqual(
-      Self.resolveSnapshotPlanTerminal(terminal: .throwOnAXFailure, interactiveOnly: true),
-      .throwAxFailure
-    )
-  }
-
-  func testSnapshotAccessibilityUnavailableCarriesSparseVerdict() {
-    currentApp = app
-    currentBundleId = "com.example.app"
-    defer {
-      currentApp = nil
-      currentBundleId = nil
-    }
-    let payload = snapshotAccessibilityUnavailable(
-      failure: SnapshotCaptureFailure(
-        code: "IOS_AX_SNAPSHOT_FAILED",
-        message: "kAXErrorIllegalArgument",
-        hint: "use screenshot"
-      )
-    )
-    XCTAssertEqual(payload.runnerFatal, true)
-    XCTAssertEqual(payload.snapshotQuality?.state, "sparse")
-    XCTAssertEqual(payload.snapshotQuality?.reasonCode, "ax-rejected")
-  }
-}
-#endif