agent-device 0.20.9 → 0.21.0

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

@@ -0,0 +1,98 @@
+import XCTest
+
+enum SnapshotBackendEnvironment {
+  case simulator
+  case physicalDevice
+}
+
+enum SnapshotRegularDepthCapability: String {
+  /// The backend can stop acquisition at the requested regular presented-depth frontier.
+  case presentedFrontier = "presented-frontier"
+  /// The backend is flat; it can answer the root and one presented level, but has no hierarchy
+  /// from which to prove deeper regular depth.
+  case flat
+  /// The backend can return raw traversal depth, but cannot prove regular presented depth.
+  case rawOnly = "raw-only"
+}
+
+enum SnapshotBackendKind: String, CaseIterable {
+  case recursiveTree = "tree"
+  case querySweep = "queries"
+  case privateAX = "private-ax"
+
+  var isForceable: Bool {
+    switch self {
+    case .recursiveTree, .privateAX:
+      return true
+    case .querySweep:
+      return false
+    }
+  }
+
+  var hittableSemantics: String {
+    "geometric-actionability"
+  }
+
+  var usesXCTestAccessibilityChannel: Bool {
+    switch self {
+    case .recursiveTree, .querySweep:
+      return true
+    case .privateAX:
+      return false
+    }
+  }
+
+  /// The raw projection is the acquired tree, so only a backend that enumerates a hierarchy can
+  /// serve it. The query sweep answers an interactive element query: it has no hierarchy to
+  /// return, and planning it for `--raw` is exactly how a raw request gets answered with regular
+  /// membership.
+  var supportsRawProjection: Bool {
+    switch self {
+    case .recursiveTree, .privateAX:
+      return true
+    case .querySweep:
+      return false
+    }
+  }
+
+  var regularDepthCapability: SnapshotRegularDepthCapability {
+    switch self {
+    case .recursiveTree:
+      return .presentedFrontier
+    case .querySweep:
+      return .flat
+    case .privateAX:
+      return .rawOnly
+    }
+  }
+
+  func canServeRegularPresentedDepth(_ requestedDepth: Int?) -> Bool {
+    guard let requestedDepth else { return true }
+    switch regularDepthCapability {
+    case .presentedFrontier:
+      return true
+    case .flat:
+      return requestedDepth <= 1
+    case .rawOnly:
+      return false
+    }
+  }
+
+  var isAvailableOnCurrentPlatform: Bool {
+    #if os(iOS) && targetEnvironment(simulator)
+      return isAvailable(on: .simulator)
+    #else
+      return isAvailable(on: .physicalDevice)
+    #endif
+  }
+
+  func isAvailable(on environment: SnapshotBackendEnvironment) -> Bool {
+    switch self {
+    case .recursiveTree, .querySweep:
+      return true
+    case .privateAX:
+      return environment == .simulator
+    }
+  }
+}
+

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

@@ -1,4 +1,5 @@
 import XCTest
+import AgentDeviceSnapshotPresentation
 
 // MARK: - Snapshot capture plans (ADR 0004)
 //
@@ -14,9 +15,11 @@ struct SnapshotQuality: Codable {
   let state: String
   /// Backend that produced the returned payload: tree | queries | private-ax.
   let backend: String
-  /// Why recovery ran (first failure) or why the payload is degraded.
+  /// Why recovery ran (first failure), why the payload is degraded, or why an internal backend
+  /// selection was honored.
   let reason: String?
-  /// Machine-readable reason: ax-rejected | sparse-tree | budget | no-nodes.
+  /// Machine-readable reason: ax-rejected | sparse-tree | budget | no-nodes | capture-failed |
+  /// presentation-failed | deferred | requested-backend.
   let reasonCode: String?
   /// Private AX ladder cap when the accepted tree is shallower than requested.
   let effectiveDepth: Int?
@@ -24,49 +27,8 @@ struct SnapshotQuality: Codable {
   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 {
-  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
-    }
-  }
+  /// Response-level timing for the accepted backend attempt, never repeated per node.
+  var timing: SnapshotCaptureTiming? = nil
 }
 
 enum SnapshotXCTestChannelPlanState: Equatable {
@@ -79,6 +41,9 @@ struct EffectiveSnapshotCapturePlan {
   let plan: [SnapshotBackendKind]
   let xCTestChannelState: SnapshotXCTestChannelPlanState
   let treeCaptureSliceBudgetOverride: TimeInterval?
+  /// Non-nil only when the plan was narrowed by an explicit internal backend preference. This
+  /// keeps the quality marker tied to the plan decision rather than to an untrusted request field.
+  let preferredBackend: SnapshotBackendKind?
 }
 
 /// What the plan runner does when every backend failed or stayed sparse.
@@ -93,13 +58,26 @@ enum SnapshotCaptureTerminalPolicy {
 
 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
+  var qualityPayload: DataPayload? = nil
+  var timing: SnapshotCaptureTiming? = nil
 }
 
 extension RunnerTests {
+  static func makeSnapshotBackendCapture(
+    from result: AgentDeviceSnapshotPresentation.SnapshotPresentationResult
+  ) -> SnapshotBackendCapture {
+    SnapshotBackendCapture(
+      payload: DataPayload(nodes: result.nodes, truncated: result.truncated),
+      effectiveDepth: result.effectiveDepth,
+      customActions: result.customActions,
+      qualityPayload: result.qualityNodes.map {
+        DataPayload(nodes: $0, truncated: result.truncated)
+      }
+    )
+  }
+
   static let sparseRecoveryTruncatedNodeThreshold = 8
   /// Umbrella wall-clock budget for one capture plan. Individual backends bound themselves,
   /// but chained recovery tiers must never stack past the 30s main-thread watchdog: when the
@@ -115,7 +93,10 @@ extension RunnerTests {
   // MARK: Plan definitions
 
   static let regularVisiblePlan: [SnapshotBackendKind] = [.recursiveTree, .querySweep, .privateAX]
-  static let rawDiagnosticPlan: [SnapshotBackendKind] = [.recursiveTree, .privateAX]
+  /// Derived from the backend trait rather than hand-listed: a backend that cannot serve the raw
+  /// projection drops out of the raw plan by construction, and a new one joins it by declaring the
+  /// trait instead of by someone remembering this line.
+  static let rawDiagnosticPlan: [SnapshotBackendKind] = regularVisiblePlan.filter(\.supportsRawProjection)
 
   // MARK: XCTest accessibility channel penalty (cross-attempt memory, #1105/#1156)
   //
@@ -175,8 +156,15 @@ extension RunnerTests {
   /// cause that does not exist.
   static func xcTestChannelStateFirstFailure(
     _ state: SnapshotXCTestChannelPlanState,
-    requestPinnedBackend: Bool = false
+    requestPinnedBackend: Bool = false,
+    preferredBackend: String? = nil
   ) -> (reason: String, code: String)? {
+    if state == .normal && preferredBackend == SnapshotBackendKind.recursiveTree.rawValue {
+      return (
+        "the recursive XCTest tree backend was explicitly selected for this capture",
+        "requested-backend"
+      )
+    }
     switch state {
     case .normal:
       return nil
@@ -210,19 +198,36 @@ extension RunnerTests {
     penalized || preferredBackend == SnapshotBackendKind.privateAX.rawValue
   }
 
-  /// 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.
+  /// Pure plan-reorder rule: an internal preferred backend pins the regular plan to that backend;
+  /// this is the only force seam used by same-backend evidence and conformance captures. 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)
+    availableBackends: Set<SnapshotBackendKind> = Set(SnapshotBackendKind.allCases),
+    preferredBackend: String? = nil
   ) -> EffectiveSnapshotCapturePlan {
+    if
+      plan == Self.regularVisiblePlan,
+      let preferred = preferredBackend.flatMap(SnapshotBackendKind.init(rawValue:)),
+      preferred.isForceable,
+      availableBackends.contains(preferred)
+    {
+      return EffectiveSnapshotCapturePlan(
+        plan: [preferred],
+        xCTestChannelState: preferred == .privateAX ? .deferredToIndependentBackend : .normal,
+        treeCaptureSliceBudgetOverride: nil,
+        preferredBackend: preferred
+      )
+    }
     guard xCTestChannelPenalized, plan == Self.regularVisiblePlan else {
       return EffectiveSnapshotCapturePlan(
         plan: plan,
         xCTestChannelState: .normal,
-        treeCaptureSliceBudgetOverride: nil
+        treeCaptureSliceBudgetOverride: nil,
+        preferredBackend: nil
       )
     }
     let availablePlan = plan.filter { availableBackends.contains($0) }
@@ -231,13 +236,15 @@ extension RunnerTests {
       return EffectiveSnapshotCapturePlan(
         plan: recoveryPlan,
         xCTestChannelState: .deferredToIndependentBackend,
-        treeCaptureSliceBudgetOverride: nil
+        treeCaptureSliceBudgetOverride: nil,
+        preferredBackend: nil
       )
     }
     return EffectiveSnapshotCapturePlan(
       plan: availablePlan.filter(\.usesXCTestAccessibilityChannel),
       xCTestChannelState: .boundedXCTestProbe,
-      treeCaptureSliceBudgetOverride: Self.penalizedXCTestProbeTreeSliceBudget
+      treeCaptureSliceBudgetOverride: Self.penalizedXCTestProbeTreeSliceBudget,
+      preferredBackend: nil
     )
   }
 
@@ -250,7 +257,7 @@ extension RunnerTests {
   func runSnapshotCapturePlan(
     _ plan: [SnapshotBackendKind],
     app: XCUIApplication,
-    options: SnapshotOptions,
+    options: PresentationOptions,
     terminal: SnapshotCaptureTerminalPolicy,
     deadline: Date? = nil
   ) throws -> DataPayload {
@@ -279,14 +286,16 @@ extension RunnerTests {
     let effective = Self.effectiveSnapshotCapturePlan(
       plan,
       xCTestChannelPenalized: xCTestChannelPenalized,
-      availableBackends: Set(SnapshotBackendKind.allCases.filter(\.isAvailableOnCurrentPlatform))
+      availableBackends: Set(SnapshotBackendKind.allCases.filter(\.isAvailableOnCurrentPlatform)),
+      preferredBackend: options.preferredBackend
     )
     let effectivePlan = effective.plan
     // 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
+      requestPinnedBackend: options.customActions && !xCTestChannelPenalizedByBreaker,
+      preferredBackend: effective.preferredBackend?.rawValue
     )
     switch effective.xCTestChannelState {
     case .normal:
@@ -317,45 +326,22 @@ extension RunnerTests {
         }
         continue
       }
-      let capture: SnapshotBackendCapture
-      let backendStartedAt = Date()
-      do {
-        guard
-          let result = try captureWithBackend(
-            kind,
-            app: app,
-            options: options,
-            deadline: deadline,
-            treeCaptureSliceBudgetOverride: effective.treeCaptureSliceBudgetOverride
-          )
-        else {
-          recordSlowXCTestSnapshotBackendIfNeeded(
-            kind,
-            startedAt: backendStartedAt,
-            penaltySuppressed: suppressXCTestPenalty
-          )
-          continue
-        }
-        capture = result
-        recordSlowXCTestSnapshotBackendIfNeeded(
-          kind,
-          startedAt: backendStartedAt,
-          penaltySuppressed: suppressXCTestPenalty
-        )
-      } catch let failure as SnapshotCaptureFailure {
-        recordXCTestSnapshotBackendFailureIfNeeded(
-          kind,
-          failure: failure,
-          penaltySuppressed: suppressXCTestPenalty
-        )
-        recordSlowXCTestSnapshotBackendIfNeeded(
-          kind,
-          startedAt: backendStartedAt,
-          penaltySuppressed: suppressXCTestPenalty
-        )
+      let attempt = try captureWithBackend(
+        kind,
+        app: app,
+        options: options,
+        deadline: deadline,
+        treeCaptureSliceBudgetOverride: effective.treeCaptureSliceBudgetOverride
+      )
+      recordXCTestSnapshotBackendAttemptIfNeeded(
+        kind,
+        attempt: attempt,
+        penaltySuppressed: suppressXCTestPenalty
+      )
+      if case let .failed(failure, phase: _) = attempt.outcome {
         if Self.isAxSnapshotFailure(failure) { axFailure = failure }
         if firstFailure == nil {
-          firstFailure = (failure.message, Self.isAxSnapshotFailure(failure) ? "ax-rejected" : "capture-failed")
+          firstFailure = (failure.message, Self.snapshotQualityReasonCode(for: failure))
         }
         NSLog(
           "AGENT_DEVICE_RUNNER_SNAPSHOT_BACKEND_FAILED backend=%@ error=%@",
@@ -364,8 +350,9 @@ extension RunnerTests {
         )
         continue
       }
+      guard case let .captured(capture) = attempt.outcome else { continue }
 
-      if let sparseReason = Self.sparsePayloadReason(capture.payload) {
+      if let sparseReason = Self.sparsePayloadReason(capture.qualityPayload ?? capture.payload) {
         if firstFailure == nil { firstFailure = sparseReason }
         if Self.payloadNodeCount(capture.payload) > Self.payloadNodeCount(best?.capture.payload) {
           best = (kind, capture)
@@ -385,7 +372,7 @@ extension RunnerTests {
         capture,
         backend: kind,
         state: recovered ? "recovered" : "healthy",
-        reason: recovered ? firstFailure : nil
+        reason: recovered || firstFailure?.code == "requested-backend" ? firstFailure : nil
       )
     }
 
@@ -419,77 +406,136 @@ extension RunnerTests {
     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,
-    penaltySuppressed: Bool
-  ) {
-    guard !penaltySuppressed else { return }
-    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,
-    penaltySuppressed: Bool
-  ) {
-    guard !penaltySuppressed else { return }
-    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: PresentationOptions,
     deadline: Date,
     treeCaptureSliceBudgetOverride: TimeInterval?
-  ) throws -> SnapshotBackendCapture? {
-    switch kind {
-    case .recursiveTree:
-      guard
-        let context = try makeSnapshotTraversalContext(
-          app: app,
-          options: options,
-          captureDeadline: deadline,
-          treeCaptureSliceBudgetOverride: treeCaptureSliceBudgetOverride
-        )
-      else {
-        return nil
-      }
-      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)
+  ) throws -> SnapshotBackendAttempt {
+    let hint = SnapshotPresentation.captureHint(for: options)
+    var timer = SnapshotPhaseTimer()
+    // Scoped depth is relative to a presentation-selected root, so its hint stays broad and the
+    // backend capability gate applies only to an unscoped regular frontier.
+    let requestedRegularDepth = options.raw || SnapshotScopePolicy.isActive(options.scope)
+      ? nil
+      : options.depth
+    guard kind.canServeRegularPresentedDepth(requestedRegularDepth) else {
+      NSLog(
+        "AGENT_DEVICE_RUNNER_SNAPSHOT_BACKEND_DEPTH_UNSUPPORTED backend=%@ depth=%ld",
+        kind.rawValue,
+        requestedRegularDepth ?? -1
+      )
+      return SnapshotBackendAttempt(
+        outcome: .noCapture,
+        timing: timer.timing
+      )
+    }
+    let acquisition: SnapshotAcquisition?
+    do {
+      acquisition = try timer.measure(.acquisition) {
+        switch kind {
+        case .recursiveTree:
+          guard
+            let context = try self.makeSnapshotTraversalContext(
+              app: app,
+              hint: hint,
+              captureDeadline: deadline,
+              treeCaptureSliceBudgetOverride: treeCaptureSliceBudgetOverride
+            )
+          else {
+            return nil
+          }
+          return try self.runMainThreadWork(
+            timeout: min(self.treeCaptureSliceBudget, max(0.5, deadline.timeIntervalSinceNow)),
+            timeoutError: self.snapshotMainThreadTimeoutError("processing tree snapshot")
+          ) {
+            hint.isRaw
+              ? try self.rawTreeSnapshotAcquisition(context: context, hint: hint)
+              : self.recursiveTreeSnapshotAcquisition(context: context, hint: hint)
+          }
+        case .querySweep:
+          return try self.runMainThreadWork(
+            timeout: min(Self.flatInteractiveFallbackBudget, max(0.1, deadline.timeIntervalSinceNow)),
+            timeoutError: self.snapshotMainThreadTimeoutError("running query-sweep snapshot")
+          ) {
+            self.querySweepSnapshotAcquisition(
+              app: app,
+              hint: hint,
+              planDeadline: deadline
+            )
+          }
+        case .privateAX:
+          return self.privateAXSnapshotAcquisition(
+            app: app,
+            hint: hint,
+            deadline: deadline
+          )
+        }
       }
-      return SnapshotBackendCapture(payload: payload, effectiveDepth: nil)
-    case .querySweep:
-      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)
+    } catch let failure as SnapshotCaptureFailure {
+      return SnapshotBackendAttempt(
+        outcome: .failed(failure, phase: .acquisition),
+        timing: timer.timing
+      )
+    }
+    guard let acquisition else {
+      return SnapshotBackendAttempt(
+        outcome: .noCapture,
+        timing: timer.timing
+      )
+    }
+
+    let presented: SnapshotBackendCapture
+    do {
+      presented = try timer.measure(.presentation) {
+        guard let result = try SnapshotPresentation.present(acquisition, options: options) else {
+          NSLog(
+            "AGENT_DEVICE_RUNNER_SNAPSHOT_PROJECTION_MISMATCH requested=%@ acquired=%@",
+            hint.projection.rawValue,
+            acquisition.hint.projection.rawValue
+          )
+          throw Self.snapshotProjectionMismatchFailure(
+            kind,
+            requested: hint.projection,
+            acquired: acquisition.hint.projection
+          )
+        }
+        return Self.makeSnapshotBackendCapture(from: result)
       }
-      return SnapshotBackendCapture(payload: payload, effectiveDepth: nil)
-    case .privateAX:
-      return privateAXSnapshotCapture(app: app, options: options, deadline: deadline)
+    } catch let failure as SnapshotPresentationFailure {
+      return SnapshotBackendAttempt(
+        outcome: .failed(Self.snapshotCaptureFailure(for: failure), phase: .presentation),
+        timing: timer.timing
+      )
+    } catch let failure as SnapshotCaptureFailure {
+      return SnapshotBackendAttempt(
+        outcome: .failed(failure, phase: .presentation),
+        timing: timer.timing
+      )
     }
+
+    var capture = presented
+    capture.timing = timer.timing
+    return SnapshotBackendAttempt(
+      outcome: .captured(capture),
+      timing: timer.timing
+    )
+  }
+
+  /// A backend that answers a request with the other projection loses its tier and says why, so
+  /// the miss lands in the quality verdict instead of shipping as a correct-looking capture.
+  static func snapshotProjectionMismatchFailure(
+    _ kind: SnapshotBackendKind,
+    requested: CaptureHint.Projection,
+    acquired: CaptureHint.Projection
+  ) -> SnapshotCaptureFailure {
+    SnapshotCaptureFailure(
+      code: "IOS_SNAPSHOT_PROJECTION_MISMATCH",
+      message:
+        "the \(kind.rawValue) backend returned a \(acquired.rawValue) capture for a \(requested.rawValue) snapshot request",
+      hint: "This is a runner bug: report it with the failing command and the app under test."
+    )
   }
 
   // MARK: Quality classifier (the single source of "is this snapshot degraded")
@@ -529,7 +575,7 @@ extension RunnerTests {
     }
   }
 
-  static func isSparseApplicationWindowTree(_ nodes: [SnapshotNode]) -> Bool {
+  static func isSparseApplicationWindowTree(_ nodes: [PresentedNode]) -> Bool {
     guard !nodes.isEmpty else { return false }
     let rootRects = nodes.compactMap { node in
       node.type == "Application" || node.type == "Window" ? node.rect : nil
@@ -564,7 +610,7 @@ extension RunnerTests {
   /// 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.
-  static func collapsedLeafIndexes(_ nodes: [SnapshotNode]) -> [Int]? {
+  static func collapsedLeafIndexes(_ nodes: [PresentedNode]) -> [Int]? {
     let parents = Set(nodes.compactMap { $0.parentIndex })
     let collapsed = nodes.filter { node in
       guard !parents.contains(node.index) else { return false }
@@ -592,13 +638,22 @@ extension RunnerTests {
       reasonCode: reason?.code,
       effectiveDepth: capture.effectiveDepth,
       collapsedLeafIndexes: Self.collapsedLeafIndexes(payload.nodes ?? []),
-      customActions: capture.customActions
+      customActions: capture.customActions,
+      timing: capture.timing
     )
     return DataPayload(
       // Legacy human text for older daemons that read message instead of snapshotQuality.
       message: Self.legacyQualityMessage(quality) ?? payload.message,
       nodes: payload.nodes,
-      truncated: payload.truncated == true || state != "healthy" || capture.effectiveDepth != nil,
+      // Completeness, never provenance: a whole tree that a later backend produced (state
+      // "recovered") stays untruncated, so strict absence reads can trust it. Only a real cap
+      // (payload truncation, a depth-limited private AX capture) or a sparse terminal payload
+      // is truncated.
+      truncated: payload.truncated == true || state == "sparse" || capture.effectiveDepth != nil,
+      qualityPayload: capture.qualityPayload.flatMap { quality in
+        guard let nodes = quality.nodes else { return nil }
+        return SnapshotQualityPayload(nodes: nodes, truncated: quality.truncated == true)
+      },
       snapshotQuality: quality,
       runnerFatal: payload.runnerFatal,
       runnerFatalReason: payload.runnerFatalReason
@@ -640,9 +695,15 @@ extension RunnerTests {
     else { return nil }
     var parts: [String] = []
     if quality.state == "recovered" {
-      let meaning = quality.reasonCode == "budget" || quality.reasonCode == "deferred"
-        ? " 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."
+      let meaning: String
+      switch quality.reasonCode {
+      case "budget", "deferred":
+        meaning = " The primary capture ran out of its time budget (busy app or simulator); the recovered tree is authoritative for this screen."
+      case "presentation-failed":
+        meaning = " The runner rejected a regular presentation because its cumulative clip invariant failed; report this as a runner bug and treat screenshot as visual truth."
+      default:
+        meaning = " 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(
         "Detected an overly complex or slow accessibility tree. Fell back to the \(quality.backend) snapshot backend"
           + (quality.reason.map { " after: \($0)." } ?? ".")

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

@@ -0,0 +1,19 @@
+import AgentDeviceSnapshotPresentation
+
+extension RunnerTests {
+  static func snapshotCaptureFailure(
+    for failure: SnapshotPresentationFailure
+  ) -> SnapshotCaptureFailure {
+    SnapshotCaptureFailure(
+      code: failure.code,
+      message: failure.message,
+      hint: failure.hint,
+      qualityReasonCode: failure.qualityReasonCode
+    )
+  }
+
+  static func snapshotQualityReasonCode(for failure: SnapshotCaptureFailure) -> String {
+    failure.qualityReasonCode
+      ?? (Self.isAxSnapshotFailure(failure) ? "ax-rejected" : "capture-failed")
+  }
+}