agent-device 0.20.10 → 0.21.1

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

@@ -1,72 +1,34 @@
 import XCTest
+import AgentDeviceSnapshotPresentation
+
+
+
+
+
+
+
 
-// MARK: - Snapshot capture plans (ADR 0004)
-//
-// Each snapshot strategy declares an ordered chain of capture backends. One runner walks the
-// chain: capture, classify, accept the first payload the quality classifier calls usable, and
-// stamp the outcome with a structured quality verdict so the daemon renders state instead of
-// re-deriving it from node shapes. Recovery ordering is data here, never a per-call-site branch.
 
-/// Structured quality verdict shipped with every iOS snapshot payload.
 struct SnapshotQuality: Codable {
-  /// healthy: first backend produced a usable tree. recovered: a later backend did.
-  /// sparse: no backend produced a usable tree; the best attempt is returned as-is.
+
+
   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.
+
+
   let reason: String?
-  /// Machine-readable reason: ax-rejected | sparse-tree | budget | no-nodes.
+
+
   let reasonCode: String?
-  /// Private AX ladder cap when the accepted tree is shallower than requested.
+
   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
-}
+  let collapsedLeafIndexes: [Int]?
 
-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
-    }
-  }
+  let customActions: SnapshotCustomActionCoverage?
 
-  var isAvailableOnCurrentPlatform: Bool {
-    switch self {
-    case .recursiveTree, .querySweep:
-      return true
-    case .privateAX:
-      #if os(iOS) && targetEnvironment(simulator)
-        return true
-      #else
-        return false
-      #endif
-    }
-  }
+  var timing: SnapshotCaptureTiming? = nil
 }
 
 enum SnapshotXCTestChannelPlanState: Equatable {
@@ -79,31 +41,47 @@ struct EffectiveSnapshotCapturePlan {
   let plan: [SnapshotBackendKind]
   let xCTestChannelState: SnapshotXCTestChannelPlanState
   let treeCaptureSliceBudgetOverride: TimeInterval?
+
+
+  let preferredBackend: SnapshotBackendKind?
 }
 
-/// What the plan runner does when every backend failed or stayed sparse.
+
 enum SnapshotCaptureTerminalPolicy {
-  /// Return the best sparse payload; if the tree backend hit a real AX serialization failure
-  /// on an interactive request, fail closed: invalidate the cached target and mark runnerFatal
-  /// (AX-unavailable target invalidation, CONTEXT.md).
+
+
+
   case sparseWithFatalOnAXFailure
-  /// Re-throw the tree backend's AX failure (raw diagnostics preserve errors, ADR 0004).
+
   case throwOnAXFailure
 }
 
 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
-  /// 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
@@ -112,18 +90,21 @@ extension RunnerTests {
     payload?.nodes?.count ?? 0
   }
 
-  // MARK: Plan definitions
+
 
   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.
+
+
+  static let rawDiagnosticPlan: [SnapshotBackendKind] = regularVisiblePlan.filter(\.supportsRawProjection)
+
+
+
+
+
+
+
+
 
   func penalizeSnapshotXCTestChannel(bundleId: String?, reason: String) {
     snapshotXCTestChannelPenaltyLock.lock()
@@ -152,7 +133,7 @@ extension RunnerTests {
     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
   }
@@ -163,20 +144,27 @@ extension RunnerTests {
     return pending
   }
 
-  /// The pre-seeded first-failure a penalized plan stamps into its verdict. The deferred case
-  /// uses the dedicated 'deferred' code: the breaker pre-selected the backend, nothing new
-  /// 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,
-    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
@@ -199,10 +187,10 @@ extension RunnerTests {
     }
   }
 
-  /// Pure gate: a capture is planned as penalized when the channel penalty is
-  /// active OR the daemon pinned the private-AX backend (same-backend evidence
-  /// probe) — both mean "do not enter XCTest tree work first, and stamp the
-  /// pre-selection as 'deferred' rather than a degradation".
+
+
+
+
   static func snapshotXCTestChannelTreatedAsPenalized(
     penalized: Bool,
     preferredBackend: String?
@@ -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.
+
+
+
+
+
   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
     )
   }
 
@@ -245,7 +252,7 @@ extension RunnerTests {
     kind.usesXCTestAccessibilityChannel && hasAbandonedTreeCapture()
   }
 
-  // MARK: Plan runner
+
 
   func runSnapshotCapturePlan(
     _ plan: [SnapshotBackendKind],
@@ -257,16 +264,16 @@ extension RunnerTests {
     var best: (kind: SnapshotBackendKind, capture: SnapshotBackendCapture)?
     var firstFailure: (reason: String, code: String)?
     var axFailure: SnapshotCaptureFailure?
-    // A caller may share the pre-plan system-modal probe's deadline; otherwise own the full budget (#1244).
+
     let deadline = deadline ?? Date().addingTimeInterval(Self.snapshotPlanBudget)
     let suppressXCTestPenalty = consumeSnapshotXCTestPenaltyWarmupExemption()
 
-    // 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.
-    // A daemon-preferred private-AX capture (same-backend evidence probe) takes the exact
-    // 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)
@@ -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:
@@ -305,8 +314,8 @@ extension RunnerTests {
         }
         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 {
@@ -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
       )
     }
 
@@ -397,11 +384,11 @@ extension RunnerTests {
       case .throwAxFailure:
         throw axFailure
       case .failClosed:
-        // Fail closed on any interactive AX serialization failure that no backend recovered:
-        // invalidate the cached target so the next command reacquires it (AX-unavailable target
-        // invalidation, CONTEXT.md). A sparse `best` from a later tier (e.g. the query sweep's
-        // synthetic root) must NOT suppress this — reaching the terminal already means no backend
-        // produced a usable tree.
+
+
+
+
+
         return snapshotAccessibilityUnavailable(failure: axFailure)
       case .sparseBest:
         break
@@ -419,83 +406,125 @@ 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: PresentationOptions,
     deadline: Date,
     treeCaptureSliceBudgetOverride: TimeInterval?
-  ) throws -> SnapshotBackendCapture? {
+  ) throws -> SnapshotBackendAttempt {
+    let hint = SnapshotPresentation.captureHint(for: options)
+    var timer = SnapshotPhaseTimer()
     let acquisition: SnapshotAcquisition?
-    switch kind {
-    case .recursiveTree:
-      guard
-        let context = try makeSnapshotTraversalContext(
-          app: app,
-          options: options,
-          captureDeadline: deadline,
-          treeCaptureSliceBudgetOverride: treeCaptureSliceBudgetOverride
-        )
-      else {
-        return nil
-      }
-      acquisition = try runMainThreadWork(
-        command: nil,
-        timeout: min(treeCaptureSliceBudget, max(0.5, deadline.timeIntervalSinceNow)),
-        timeoutError: snapshotMainThreadTimeoutError("processing tree snapshot")
-      ) {
-        options.raw
-          ? try self.rawTreeSnapshotAcquisition(context: context, options: options)
-          : self.recursiveTreeSnapshotAcquisition(context: context, options: options)
+    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
+          )
+        }
       }
-    case .querySweep:
-      acquisition = try runMainThreadWork(
-        command: nil,
-        timeout: min(Self.flatInteractiveFallbackBudget, max(0.1, deadline.timeIntervalSinceNow)),
-        timeoutError: snapshotMainThreadTimeoutError("running query-sweep snapshot")
-      ) {
-        self.querySweepSnapshotAcquisition(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)
       }
-    case .privateAX:
-      acquisition = privateAXSnapshotAcquisition(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
+      )
     }
-    guard let acquisition else { return nil }
-    return SnapshotPresentation.present(acquisition, options: options)
+
+    var capture = presented
+    capture.timing = timer.timing
+    return SnapshotBackendAttempt(
+      outcome: .captured(capture),
+      timing: timer.timing
+    )
+  }
+
+
+
+  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")
 
-  /// Returns a degradation reason + machine code when the payload is too degraded to accept.
+
+
   static func sparsePayloadReason(_ payload: DataPayload) -> (reason: String, code: String)? {
     guard let nodes = payload.nodes, !nodes.isEmpty else {
       return ("snapshot returned no nodes", "no-nodes")
@@ -509,9 +538,9 @@ extension RunnerTests {
     return nil
   }
 
-  /// Terminal action when a capture plan exhausted every backend with an AX serialization
-  /// failure still pending. Pure so the fail-closed-vs-sparse policy is unit-testable without
-  /// a live app (the ordering gap the architecture review flagged).
+
+
+
   enum SnapshotPlanTerminalAction: Equatable {
     case throwAxFailure
     case failClosed
@@ -536,8 +565,8 @@ extension RunnerTests {
       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"
       guard Self.structuralOnlyNodeTypes.contains(node.type) else { return false }
       guard !isRootContainer else { return true }
@@ -553,18 +582,18 @@ extension RunnerTests {
     }
   }
 
-  /// 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.
+
+
+
   static func collapsedLeafIndexes(_ nodes: [PresentedNode]) -> [Int]? {
     let parents = Set(nodes.compactMap { $0.parentIndex })
     let collapsed = nodes.filter { node in
@@ -576,7 +605,7 @@ extension RunnerTests {
     return collapsed.isEmpty ? nil : collapsed.map(\.index)
   }
 
-  // MARK: Outcome stamping
+
 
   private func stampedSnapshotPayload(
     _ capture: SnapshotBackendCapture,
@@ -593,27 +622,36 @@ 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,
+
+
+
+
+      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
     )
   }
 
-  /// 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 "
@@ -641,9 +679,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)." } ?? ".")
@@ -659,9 +703,9 @@ extension RunnerTests {
     }
     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
-      // this capture did. A plain re-run retries with a fresh extension budget.
+
+
+
       parts.append(
         "The accessibility server rejected deeper requests; content below depth \(depth) may be missing — re-run snapshot to retry deeper content."
       )
@@ -670,3 +714,514 @@ extension RunnerTests {
   }
 }
 
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+