agent-device 0.18.3 → 0.19.0

package/{apple-runner → dist/apple-runner}/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+TextEntry.swift

@@ -45,6 +45,11 @@ extension RunnerTests {
     }
   }
 
+  struct TextEntryStabilization {
+    let element: XCUIElement?
+    let focusConfirmed: Bool
+  }
+
   func clearTextInput(_ element: XCUIElement) {
     // Skip the clear (delete burst + moveCaretToEnd edge-tap) ONLY when we can confirm the
     // field is empty. Why skip: the edge-tap computes a point from the element frame, which can
@@ -90,30 +95,45 @@ extension RunnerTests {
 #endif
   }
 
-  func stabilizeTextInputBeforeTyping(app: XCUIApplication, target: XCUIElement?) -> XCUIElement? {
+  func stabilizeTextInputBeforeTyping(
+    app: XCUIApplication,
+    target: XCUIElement?,
+    keyboardVisibleBeforeTap: Bool? = nil
+  ) -> TextEntryStabilization {
 #if os(tvOS)
-    return target
+    return TextEntryStabilization(element: target, focusConfirmed: true)
 #else
     let latest = target
-    let keyboardVisibleAtEntry = isKeyboardVisible(app: app)
+    let keyboardVisibleAtEntry = keyboardVisibleBeforeTap ?? isKeyboardVisible(app: app)
     let deadline = Date().addingTimeInterval(TextEntryTiming.focusTimeout)
     while Date() < deadline {
       if let focused = focusedTextInput(app: app) {
-        return focused
+        return TextEntryStabilization(element: focused, focusConfirmed: true)
       }
       // focusedTextInput is intentionally nil on iOS; treat the keyboard transitioning to
       // visible after our tap as the focus-moved signal. Don't fast-path when it was already up.
       if keyboardBecameVisible(app: app, wasVisibleAtEntry: keyboardVisibleAtEntry) {
-        return latest
+        return TextEntryStabilization(element: latest, focusConfirmed: true)
       }
       sleepFor(TextEntryTiming.pollInterval)
     }
-    return latest
+    return TextEntryStabilization(element: latest, focusConfirmed: false)
 #endif
   }
 
   func focusTextInputForTextEntry(app: XCUIApplication, x: Double?, y: Double?) -> TextEntryTarget {
     guard let x, let y else {
+      // Bare `type` targets the current first responder. On iOS we intentionally do not trust
+      // `hasKeyboardFocus`, but an already-visible software keyboard is sufficient evidence that
+      // app.typeText has a receiver; waiting the full readiness timeout cannot prove a stronger
+      // target because there is no selector/coordinate focus move to validate.
+      if isKeyboardVisible(app: app) {
+        return TextEntryTarget(
+          element: focusedTextInput(app: app),
+          refreshPoint: nil,
+          prefersFocusedElement: true
+        )
+      }
       let focused = waitForTextEntryReadiness(
         app: app,
         target: TextEntryTarget(
@@ -125,6 +145,7 @@ extension RunnerTests {
       return TextEntryTarget(element: focused, refreshPoint: nil, prefersFocusedElement: true)
     }
 
+    let keyboardVisibleBeforeTap = isKeyboardVisible(app: app)
     let target = textInputAt(app: app, x: x, y: y)
     let requestedPoint = CGPoint(x: x, y: y)
     if let target {
@@ -137,15 +158,30 @@ extension RunnerTests {
     } else {
       _ = tapAt(app: app, x: x, y: y)
     }
-    let stabilized = stabilizeTextInputBeforeTyping(app: app, target: target)
-    let element = waitForTextEntryReadiness(
-      app: app,
-      target: TextEntryTarget(
-        element: stabilized ?? target,
-        refreshPoint: requestedPoint,
+    // A visible keyboard is not enough evidence for app.typeText, because focus may still
+    // belong to a previous field. With a concrete target we type through XCUIElement.typeText,
+    // so after tapping it the iOS readiness timeout cannot prove anything stronger.
+    if keyboardVisibleBeforeTap, let target {
+      return TextEntryTarget(
+        element: target,
+        refreshPoint: textEntryRefreshPoint(for: target) ?? requestedPoint,
         prefersFocusedElement: false
       )
-    ) ?? stabilized ?? target
+    }
+    let stabilized = stabilizeTextInputBeforeTyping(
+      app: app,
+      target: target,
+      keyboardVisibleBeforeTap: keyboardVisibleBeforeTap
+    )
+    let readyTarget = TextEntryTarget(
+      element: stabilized.element ?? target,
+      refreshPoint: requestedPoint,
+      prefersFocusedElement: false
+    )
+    let concreteTargetReady = keyboardVisibleBeforeTap && readyTarget.element != nil
+    let element = stabilized.focusConfirmed || concreteTargetReady
+      ? (stabilized.element ?? target)
+      : (waitForTextEntryReadiness(app: app, target: readyTarget) ?? stabilized.element ?? target)
     return TextEntryTarget(
       element: element,
       refreshPoint: textEntryRefreshPoint(for: element) ?? requestedPoint,
@@ -155,18 +191,32 @@ extension RunnerTests {
 
   func focusTextInputForTextEntry(app: XCUIApplication, element: XCUIElement) -> TextEntryTarget {
     let point = textEntryRefreshPoint(for: element)
+    let keyboardVisibleBeforeTap = isKeyboardVisible(app: app)
     if let point {
       _ = tapAt(app: app, x: point.x, y: point.y)
     }
-    let stabilized = stabilizeTextInputBeforeTyping(app: app, target: element)
-    let resolved = waitForTextEntryReadiness(
-      app: app,
-      target: TextEntryTarget(
-        element: stabilized ?? element,
-        refreshPoint: point,
+    // See the coordinate-target path above: direct element typing keeps this scoped to the
+    // tapped target, while the first-character warmup and final verify still catch dropped input.
+    if keyboardVisibleBeforeTap {
+      return TextEntryTarget(
+        element: element,
+        refreshPoint: textEntryRefreshPoint(for: element) ?? point,
         prefersFocusedElement: false
       )
-    ) ?? stabilized ?? element
+    }
+    let stabilized = stabilizeTextInputBeforeTyping(
+      app: app,
+      target: element,
+      keyboardVisibleBeforeTap: keyboardVisibleBeforeTap
+    )
+    let readyTarget = TextEntryTarget(
+      element: stabilized.element ?? element,
+      refreshPoint: point,
+      prefersFocusedElement: false
+    )
+    let resolved = stabilized.focusConfirmed
+      ? (stabilized.element ?? element)
+      : (waitForTextEntryReadiness(app: app, target: readyTarget) ?? stabilized.element ?? element)
     return TextEntryTarget(
       element: resolved,
       refreshPoint: textEntryRefreshPoint(for: resolved) ?? point,
@@ -199,31 +249,51 @@ extension RunnerTests {
     target: TextEntryTarget,
     text: String,
     delaySeconds: Double,
-    repairMode: TextTypingRepairMode = .none
+    repairMode: TextTypingRepairMode = .none,
+    commandId: String? = nil
   ) -> TextEntryResult {
+    let totalStartedAt = Date()
     guard !text.isEmpty else {
+      logTextEntryPhase(commandId: commandId, phase: "total", startedAt: totalStartedAt, chars: 0, mode: repairMode)
       return TextEntryResult(verified: true, repaired: false, expectedText: "", observedText: "")
     }
     var activeTarget = target
+    let initialResolveStartedAt = Date()
     let initialTarget = resolveTextEntryElement(app: app, target: activeTarget)
     activeTarget = activeTarget.withElement(initialTarget)
     let currentText = editableTextValue(for: initialTarget, treatingPlaceholderAsEmpty: true)
     let initialText = repairMode == .append ? currentText : nil
     let expectedText = expectedTextEntryValue(typedText: text, mode: repairMode, initialText: initialText)
+    logTextEntryPhase(
+      commandId: commandId,
+      phase: "initial-resolve",
+      startedAt: initialResolveStartedAt,
+      chars: text.count,
+      mode: repairMode
+    )
 
     if repairMode == .replacement {
       guard let replacementTarget = initialTarget else {
+        logTextEntryPhase(commandId: commandId, phase: "total", startedAt: totalStartedAt, chars: text.count, mode: repairMode)
         return TextEntryResult(verified: nil, repaired: false, expectedText: expectedText, observedText: nil)
       }
       if currentText == nil || currentText?.isEmpty == false {
+        let clearStartedAt = Date()
         clearTextInput(replacementTarget)
         activeTarget = activeTarget.withElement(replacementTarget)
+        logTextEntryPhase(
+          commandId: commandId,
+          phase: "clear",
+          startedAt: clearStartedAt,
+          chars: text.count,
+          mode: repairMode
+        )
       }
     }
 
     func typeIntoCurrentTarget(_ value: String) -> XCUIElement? {
       if let currentTarget = resolveTextEntryElement(app: app, target: activeTarget) {
-        app.typeText(value)
+        currentTarget.typeText(value)
         return currentTarget
       } else {
         app.typeText(value)
@@ -248,76 +318,158 @@ extension RunnerTests {
     let characters = Array(text)
     if delaySeconds > 0 && characters.count > 1 {
       var typedTarget: XCUIElement?
+      let delayedTypeStartedAt = Date()
       for (index, character) in characters.enumerated() {
         typedTarget = typeIntoCurrentTarget(String(character)) ?? typedTarget
         if index + 1 < characters.count {
           sleepFor(delaySeconds)
         }
       }
+      logTextEntryPhase(
+        commandId: commandId,
+        phase: "type-delayed",
+        startedAt: delayedTypeStartedAt,
+        chars: characters.count,
+        mode: repairMode
+      )
       if repairMode == .none {
+        logTextEntryPhase(commandId: commandId, phase: "total", startedAt: totalStartedAt, chars: text.count, mode: repairMode)
         return TextEntryResult(verified: nil, repaired: false, expectedText: nil, observedText: nil)
       }
-      let repairResult = repairTextEntryIfNeeded(
+      let verifyStartedAt = Date()
+      let result = verifyTextEntryWithRepairIfNeeded(
         app: app,
         target: activeTarget.withElement(typedTarget),
         expectedText: expectedText,
         repairMode: repairMode
       )
-      return verifyTextEntry(
-        app: app,
-        target: activeTarget.withElement(typedTarget),
-        expectedText: expectedText,
-        repaired: repairResult.repaired
+      logTextEntryPhase(
+        commandId: commandId,
+        phase: "verify",
+        startedAt: verifyStartedAt,
+        chars: characters.count,
+        mode: repairMode
       )
+      logTextEntryPhase(commandId: commandId, phase: "total", startedAt: totalStartedAt, chars: text.count, mode: repairMode)
+      return result
     }
 
     let typedTarget: XCUIElement?
     if repairMode != .none && characters.count > 1 {
       let firstCharacter = String(characters[0])
+      let firstStartedAt = Date()
       var firstTypedTarget = typeIntoCurrentTarget(firstCharacter)
+      logTextEntryPhase(
+        commandId: commandId,
+        phase: "type-first",
+        startedAt: firstStartedAt,
+        chars: 1,
+        mode: repairMode
+      )
       activeTarget = activeTarget.withElement(firstTypedTarget)
       let warmupExpectedText = expectedTextEntryValue(
         typedText: firstCharacter,
         mode: repairMode,
         initialText: initialText
       )
+      let warmupStartedAt = Date()
       waitForWarmupValue(warmupExpectedText, target: activeTarget)
+      logTextEntryPhase(
+        commandId: commandId,
+        phase: "warmup",
+        startedAt: warmupStartedAt,
+        chars: 1,
+        mode: repairMode
+      )
       let remainingText = String(characters.dropFirst())
+      let remainingStartedAt = Date()
       firstTypedTarget = typeIntoCurrentTarget(remainingText) ?? firstTypedTarget
+      logTextEntryPhase(
+        commandId: commandId,
+        phase: "type-remaining",
+        startedAt: remainingStartedAt,
+        chars: characters.count - 1,
+        mode: repairMode
+      )
       typedTarget = firstTypedTarget
     } else {
+      let typeStartedAt = Date()
       typedTarget = typeIntoCurrentTarget(text)
+      logTextEntryPhase(
+        commandId: commandId,
+        phase: "type-all",
+        startedAt: typeStartedAt,
+        chars: characters.count,
+        mode: repairMode
+      )
     }
     if repairMode == .none {
+      logTextEntryPhase(commandId: commandId, phase: "total", startedAt: totalStartedAt, chars: text.count, mode: repairMode)
       return TextEntryResult(verified: nil, repaired: false, expectedText: nil, observedText: nil)
     }
-    let repairResult = repairTextEntryIfNeeded(
+    let verifyStartedAt = Date()
+    let result = verifyTextEntryWithRepairIfNeeded(
       app: app,
       target: activeTarget.withElement(typedTarget),
       expectedText: expectedText,
       repairMode: repairMode
     )
-    return verifyTextEntry(
-      app: app,
-      target: activeTarget.withElement(typedTarget),
-      expectedText: expectedText,
-      repaired: repairResult.repaired
+    logTextEntryPhase(
+      commandId: commandId,
+      phase: "verify",
+      startedAt: verifyStartedAt,
+      chars: characters.count,
+      mode: repairMode
     )
+    logTextEntryPhase(commandId: commandId, phase: "total", startedAt: totalStartedAt, chars: text.count, mode: repairMode)
+    return result
+  }
+
+  private func logTextEntryPhase(
+    commandId: String?,
+    phase: String,
+    startedAt: Date,
+    chars: Int,
+    mode: TextTypingRepairMode
+  ) {
+    NSLog(
+      "AGENT_DEVICE_RUNNER_TEXT_ENTRY_PHASE commandId=%@ phase=%@ durationMs=%.1f chars=%d mode=%@",
+      commandId ?? "",
+      phase,
+      Date().timeIntervalSince(startedAt) * 1000.0,
+      chars,
+      textEntryModeName(mode)
+    )
+  }
+
+  func textEntryModeName(_ mode: TextTypingRepairMode) -> String {
+    switch mode {
+    case .none:
+      return "none"
+    case .append:
+      return "append"
+    case .replacement:
+      return "replacement"
+    }
   }
 
-  private func repairTextEntryIfNeeded(
+  private func verifyTextEntryWithRepairIfNeeded(
     app: XCUIApplication,
     target: TextEntryTarget,
     expectedText: String?,
     repairMode: TextTypingRepairMode
   ) -> TextEntryResult {
+    let initialResult = verifyTextEntry(
+      app: app,
+      target: target,
+      expectedText: expectedText,
+      repaired: false
+    )
 #if os(iOS)
-    guard let targetElement = resolveTextEntryElement(app: app, target: target) else {
-      return TextEntryResult(verified: nil, repaired: false, expectedText: expectedText, observedText: nil)
-    }
-    guard let expectedText else {
-      let observedText = editableTextValue(for: targetElement)
-      return TextEntryResult(verified: nil, repaired: false, expectedText: nil, observedText: observedText)
+    guard initialResult.verified == false,
+          let expectedText = initialResult.expectedText
+    else {
+      return initialResult
     }
     guard shouldRepairTextEntry(
       app: app,
@@ -325,11 +477,16 @@ extension RunnerTests {
       expectedText: expectedText,
       repairMode: repairMode
     ) else {
-      return verifyTextEntry(app: app, target: target, expectedText: expectedText, repaired: false)
+      return verifyTextEntry(
+        app: app,
+        target: target,
+        expectedText: expectedText,
+        repaired: false
+      )
     }
 
     guard let repairTarget = resolveTextEntryElement(app: app, target: target) else {
-      return TextEntryResult(verified: nil, repaired: false, expectedText: expectedText, observedText: nil)
+      return initialResult
     }
     let observedText = editableTextValue(for: repairTarget) ?? ""
     NSLog(
@@ -338,10 +495,15 @@ extension RunnerTests {
       observedText.count
     )
     clearTextInput(repairTarget)
-    app.typeText(expectedText)
-    return verifyTextEntry(app: app, target: target, expectedText: expectedText, repaired: true)
+    repairTarget.typeText(expectedText)
+    return verifyTextEntry(
+      app: app,
+      target: target.withElement(repairTarget),
+      expectedText: expectedText,
+      repaired: true
+    )
 #else
-    return TextEntryResult(verified: nil, repaired: false, expectedText: expectedText, observedText: nil)
+    return initialResult
 #endif
   }
 

package/{apple-runner → dist/apple-runner}/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Transport.swift

@@ -116,6 +116,12 @@ extension RunnerTests {
         completion((jsonResponse(status: 200, response: executeUptime()), false))
         return
       }
+      // Re-sends of a still-executing commandId (the daemon's transport retry loop) attach to
+      // the in-flight execution and receive its response instead of piling a second execution
+      // onto the main queue behind it (#1105 capture pileup).
+      if attachToInFlightCommandIfNeeded(command: command, completion: completion) {
+        return
+      }
       NSLog(
         "AGENT_DEVICE_RUNNER_COMMAND_ACCEPTED command=%@ commandId=%@",
         command.command.rawValue,
@@ -131,7 +137,11 @@ extension RunnerTests {
             command.commandId ?? "",
             response.ok ? 1 : 0
           )
-          completion((self.jsonResponse(status: 200, response: response), command.command == .shutdown))
+          self.deliverCommandResult(
+            command: command,
+            result: (self.jsonResponse(status: 200, response: response), command.command == .shutdown),
+            completion: completion
+          )
         } catch {
           NSLog(
             "AGENT_DEVICE_RUNNER_COMMAND_FAILED command=%@ commandId=%@ error=%@",
@@ -139,17 +149,21 @@ extension RunnerTests {
             command.commandId ?? "",
             String(describing: error)
           )
-          completion((
-            self.jsonResponse(
-              status: 500,
-              response: self.errorResponse(
-                code: "COMMAND_FAILED",
-                message: error.localizedDescription,
-                hint: "Check the runner log for XCTest details, then retry after the app is foregrounded if this was a timeout or activation failure."
-              )
+          self.deliverCommandResult(
+            command: command,
+            result: (
+              self.jsonResponse(
+                status: 500,
+                response: self.errorResponse(
+                  code: "COMMAND_FAILED",
+                  message: error.localizedDescription,
+                  hint: "Check the runner log for XCTest details, then retry after the app is foregrounded if this was a timeout or activation failure."
+                )
+              ),
+              false
             ),
-            false
-          ))
+            completion: completion
+          )
         }
       }
     } catch {
@@ -167,6 +181,60 @@ extension RunnerTests {
     }
   }
 
+  // MARK: - In-Flight Command Coalescing
+
+  /// Returns true when this send duplicated a still-executing commandId and was attached as a
+  /// waiter of the in-flight execution. Otherwise marks the commandId in flight and returns
+  /// false so the caller enqueues the (single) execution.
+  private func attachToInFlightCommandIfNeeded(
+    command: Command,
+    completion: @escaping ((data: Data, shouldFinish: Bool)) -> Void
+  ) -> Bool {
+    guard let commandId = normalizedInFlightCommandId(command.commandId) else { return false }
+    inFlightCommandLock.lock()
+    if inFlightCommandIds.contains(commandId) {
+      inFlightCommandWaiters[commandId, default: []].append(completion)
+      inFlightCommandLock.unlock()
+      NSLog(
+        "AGENT_DEVICE_RUNNER_COMMAND_COALESCED command=%@ commandId=%@",
+        command.command.rawValue,
+        commandId
+      )
+      return true
+    }
+    inFlightCommandIds.insert(commandId)
+    inFlightCommandLock.unlock()
+    return false
+  }
+
+  private func deliverCommandResult(
+    command: Command,
+    result: (data: Data, shouldFinish: Bool),
+    completion: ((data: Data, shouldFinish: Bool)) -> Void
+  ) {
+    var waiters: [((data: Data, shouldFinish: Bool)) -> Void] = []
+    if let commandId = normalizedInFlightCommandId(command.commandId) {
+      inFlightCommandLock.lock()
+      inFlightCommandIds.remove(commandId)
+      waiters = inFlightCommandWaiters.removeValue(forKey: commandId) ?? []
+      inFlightCommandLock.unlock()
+    }
+    completion(result)
+    for waiter in waiters {
+      waiter(result)
+    }
+  }
+
+  private func normalizedInFlightCommandId(_ commandId: String?) -> String? {
+    guard let trimmed = commandId?.trimmingCharacters(in: .whitespacesAndNewlines),
+      !trimmed.isEmpty
+    else {
+      return nil
+    }
+    return trimmed
+  }
+
+
   // MARK: - Response Encoding
 
   private func jsonResponse(status: Int, response: Response) -> Data {
@@ -203,6 +271,9 @@ extension RunnerTests {
   private func finish() {
     listener?.cancel()
     listener = nil
+    // Guard against double-fulfill: coalesced shutdown sends deliver one result to
+    // multiple waiters, each of which may ask to finish.
     doneExpectation?.fulfill()
+    doneExpectation = nil
   }
 }

package/{apple-runner → dist/apple-runner}/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests.swift

@@ -54,6 +54,41 @@ final class RunnerTests: XCTestCase {
   var needsFirstInteractionDelay = false
   var activeRecording: ScreenRecorder?
   let commandJournal = RunnerCommandJournal()
+  // Coalesces duplicate transport sends of the same commandId onto the single in-flight
+  // execution instead of enqueueing them again behind it (#1105 capture pileup).
+  let inFlightCommandLock = NSLock()
+  var inFlightCommandIds: Set<String> = []
+  var inFlightCommandWaiters: [String: [((data: Data, shouldFinish: Bool)) -> Void]] = [:]
+  // Tracks main-queue work abandoned by the execution watchdog so new main-thread commands
+  // fail fast as busy instead of queueing behind work that cannot be cancelled (#1105).
+  let mainThreadWorkLock = NSLock()
+  var abandonedMainThreadWorkCount = 0
+  var abandonedMainThreadWorkSince: Date?
+  // Past this age the runner stops claiming "busy, retry soon" and reports itself wedged so
+  // the daemon recycles it — the only cure once the main thread is stuck for good.
+  let mainThreadWedgeThreshold: TimeInterval = 120
+  // Sticky per-bundle hint: after the XCTest tree backend ground past its slice (or a snapshot
+  // was abandoned by the watchdog), later capture plans lead with the private AX backend
+  // instead of re-grinding the tree on the same screen class (#1105).
+  let snapshotTreePenaltyLock = NSLock()
+  var snapshotTreePenaltyBundleId: String?
+  var snapshotTreePenaltyUntil = Date.distantPast
+  let snapshotTreePenaltyDuration: TimeInterval = 120
+  // Bluesky-class screens grind ~4-8s before the tree backend fails; anything past this
+  // threshold marks the screen hostile so the next capture leads with private AX.
+  let snapshotTreeSlowCaptureThreshold: TimeInterval = 3
+  // The blocking XCTest tree snapshot XPC runs on a worker thread with this slice so a
+  // content-dependent grind (#1105: seconds to minutes on live Bluesky screens) cannot pin
+  // the capture plan. On timeout the XPC keeps grinding on its worker; while any abandoned
+  // tree capture is outstanding, plans skip the XCTest-backed tiers (tree, query sweep) and
+  // use the private AX backend, which does not go through testmanagerd.
+  let treeCaptureLock = NSLock()
+  var abandonedTreeCaptureCount = 0
+  let treeCaptureSliceBudget: TimeInterval = 8
+  // Observability for the record(_:) suppression below: how many AX-broken-screen snapshot
+  // issues this session muted, so wedge investigations see the volume without grepping logs.
+  let suppressedIssueLock = NSLock()
+  var suppressedAxSnapshotIssueCount = 0
   let interactiveTypes: Set<XCUIElement.ElementType> = [
     .button,
     .cell,
@@ -88,6 +123,43 @@ final class RunnerTests: XCTestCase {
     continueAfterFailure = true
   }
 
+  /// True for the one recorded-issue class the runner deliberately mutes: an AX-server error
+  /// (`kAXError*`) inside a "Failed to get matching snapshot" fetch. The kAXError token
+  /// intentionally covers kAXErrorIllegalArgument and its sibling AX server codes (e.g.
+  /// kAXErrorCannotComplete): any AX-server rejection inside a matching-snapshot fetch is the
+  /// same capture-plan noise the plan already classifies and recovers from. The timeout
+  /// variant ("Failed to get matching snapshot: Timed out while evaluating UI query.") carries
+  /// no kAXError token and MUST keep recording — it signals a genuinely hung query, exactly
+  /// the pathology XCTEST_RECORDED_FAILURE must stay able to see.
+  static func isSuppressedAxSnapshotIssueDescription(_ description: String) -> Bool {
+    description.contains("Failed to get matching snapshot") && description.contains("kAXError")
+  }
+
+  /// On AX-broken screens (deep RN trees, #758/#1105) XCUIApplication queries record
+  /// "Failed to get matching snapshot: ... kAXError..." issues; XCTest tears the whole test
+  /// case down once a few accumulate, killing the long-lived runner right after the command
+  /// completes and forcing a ~25s restart per capture. This override is deliberately
+  /// suite-global (all commands, not just snapshot capture): tap-triggered element queries on
+  /// the same screens record the same noise and would still tear the runner down, and command
+  /// outcomes stay honest through their own error paths — only this issue side-channel is
+  /// muted. Everything else still records (and still drives XCTEST_RECORDED_FAILURE).
+  override func record(_ issue: XCTIssue) {
+    let description = issue.compactDescription
+    if Self.isSuppressedAxSnapshotIssueDescription(description) {
+      suppressedIssueLock.lock()
+      suppressedAxSnapshotIssueCount += 1
+      let count = suppressedAxSnapshotIssueCount
+      suppressedIssueLock.unlock()
+      NSLog(
+        "AGENT_DEVICE_RUNNER_AX_SNAPSHOT_ISSUE_SUPPRESSED count=%ld description=%@",
+        count,
+        description
+      )
+      return
+    }
+    super.record(issue)
+  }
+
   @MainActor
   func testCommand() throws {
     if RunnerEnv.isTruthy("AGENT_DEVICE_RUNNER_NOOP_STARTUP") {

package/dist/src/agent-browser-tool.js

@@ -0,0 +1 @@
+import{t as e}from"./rolldown-runtime.js";import{F as t,I as n}from"./sdk-contracts.js";import{T as r,j as i,v as a}from"./sdk-android-adb.js";import{t as o}from"./timeouts.js";import{c as s,i as c,n as l,o as u,t as d}from"./host-process.js";import f from"node:crypto";import p from"node:fs";import m from"node:os";import h from"node:path";async function g(e){let{lockDirPath:n,owner:r}=e,i=h.join(n,`owner.json`),a=Date.now()+(e.timeoutMs??3e4),s=e.pollMs??100,c=e.ownerGraceMs??5e3,l=e.description??`process lock`;for(p.mkdirSync(h.dirname(n),{recursive:!0});Date.now()<a;)try{p.mkdirSync(n),_(i,r);let e=!1;return async()=>{e||(e=!0,p.rmSync(n,{recursive:!0,force:!0}))}}catch(e){let t=e;if(t.code!==`EEXIST`)throw t;if(ee(n,i,c))continue;await o(s)}throw new t(`COMMAND_FAILED`,`Timed out waiting for ${l}`,{lockDirPath:n,...y(n,i)})}function _(e,t){let n=`${e}.${process.pid}.${Date.now()}.tmp`;p.writeFileSync(n,JSON.stringify(t),`utf8`),p.renameSync(n,e)}function ee(e,t,n){let r=null;try{r=p.statSync(e)}catch{return!0}let i=v(t);return i?b(i)?!1:(p.rmSync(e,{recursive:!0,force:!0}),!0):Date.now()-r.mtimeMs<n?!1:(p.rmSync(e,{recursive:!0,force:!0}),!0)}function v(e){try{return JSON.parse(p.readFileSync(e,`utf8`))}catch{return null}}function y(e,t){let n=Date.now(),r=v(t),i;try{i=Math.max(0,Math.round(n-p.statSync(e).mtimeMs))}catch{}return{...i===void 0?{}:{lockAgeMs:i},...r?{ownerPid:r.pid,ownerStartTime:r.startTime,ownerAgeMs:Math.max(0,Math.round(n-r.acquiredAtMs))}:{}}}function b(e){return!Number.isInteger(e.pid)||e.pid<=0||!l(e.pid)?!1:e.startTime?u(e.pid)===e.startTime:!0}const x=new Map;function S(e){let t=f.createHash(`sha256`);return t.update(h.resolve(e.stateDir)),t.update(`\0`),t.update(h.resolve(e.installDir)),`--agent-device-managed-web=${t.digest(`hex`).slice(0,16)}`}function C(e,t){let n=S(t),r=e?.trim();return r?k(r).includes(n)?r:`${r},${n}`:n}function w(e){return A(e.AGENT_BROWSER_IDLE_TIMEOUT_MS)??A(e.AGENT_DEVICE_WEB_IDLE_TIMEOUT_MS)??3e5}function te(e,t){if(e.pid!==process.pid&&j(e.command)){if(e.command.includes(S(t)))return{process:e,reason:`launch-marker`};if(M(t).some(t=>re(e,t)))return{process:e,reason:`managed-browser-home`}}}function T(e,t){let n=e.flatMap(e=>{let n=te(e,t);return n?[n]:[]});return{count:n.length,pids:n.map(e=>e.process.pid),processes:n}}async function E(e){return T(await O(),e)}async function D(e,t,n={}){let r=N([...n.openWebSessionNames??[]]);if(r.length>0)return P(`open-web-session`,{openWebSessionNames:r});let a=w(process.env),o=I(e);if(o!==void 0&&Date.now()-o<a)return P(`recent-browser-activity`,{idleTimeoutMs:a,latestActivityMs:o});let c=await O(),l=T(c,e),u=d(l.processes.map(e=>e.process.pid),c).map(e=>e.pid),f={...l,signalPids:u};return l.count===0?f:(i({level:`warn`,phase:`web_agent_browser_orphan_cleanup`,data:{reason:t,count:l.count,pids:l.pids,signalPids:u,stateDir:e.stateDir,installDir:e.installDir,matchReasons:l.processes.map(e=>e.reason)}}),await s({pids:u,termTimeoutMs:1500,killTimeoutMs:1e3}),f)}async function ne(e,t={}){let n=Date.now(),r=h.resolve(e.stateDir),i=x.get(r);if(!(i!==void 0&&n-i<3e4))return x.set(r,n),await D(e,`provider-startup`,t)}async function O(){return await r(async()=>await c({timeoutMs:1500}))}function k(e){return e.split(/[,\n]/).map(e=>e.trim()).filter(Boolean)}function A(e){if(e===void 0||e.trim()===``)return;let t=Number.parseInt(e,10);return Number.isInteger(t)&&t>0?t:void 0}function j(e){return/\b(?:Google Chrome for Testing|Chrome for Testing|Chromium|chrome|chrome\.exe|chromium|chromium-browser|headless_shell)\b/i.test(e)}function M(e){return N([h.join(e.homeDir,`.agent-browser`,`browsers`),h.join(e.runtimeHomeDir,`.agent-browser`,`browsers`)])}function N(e){return[...new Set(e.filter(e=>e.length>0))]}function P(e,t){return{count:0,pids:[],processes:[],signalPids:[],skipped:{reason:e,...t}}}function re(e,t){let n=F(e.command),r=`${F(h.resolve(t)).replace(/\/+$/,``)}/`;return n.includes(r)}function F(e){return e.replace(/\\/g,`/`)}function I(e){let t=L(e.socketDir).map(e=>R(e)).filter(e=>e!==void 0);return t.length>0?Math.max(...t):void 0}function L(e){try{return p.readdirSync(e).map(t=>h.join(e,t))}catch{return[]}}function R(e){try{return p.statSync(e).mtimeMs}catch{return}}var z=e({doctorManagedAgentBrowser:()=>K,getManagedAgentBrowserStatus:()=>q,mapManagedAgentBrowserError:()=>$,resolveAgentBrowserTool:()=>W,setupManagedAgentBrowser:()=>G});const B=`0.27.1`,V=`agent-browser`,H=5*6e4,U=6e4;async function W(e){let t=q(e);if(t.installed)return J(t);throw Q(t)}async function G(e){let t=q(e);ce(t.nodeMajor);let n=await g({lockDirPath:h.join(t.installDir,`..`,`.agent-browser-install.lock`),owner:{pid:process.pid,startTime:u(process.pid),acquiredAtMs:Date.now()},timeoutMs:H,description:`managed agent-browser setup`});try{let t=q(e);return t.installed?t:(p.mkdirSync(t.installDir,{recursive:!0}),await Y(t),await X(t,[`install`],{timeoutMs:H}),await X(t,[`doctor`,`--offline`,`--quick`],{timeoutMs:U}),ae(t),q(e))}finally{await n()}}async function K(e){let t=q(e);if(!t.installed)throw Q(t);return{status:t,...await X(t,[`doctor`,`--offline`,`--quick`],{timeoutMs:U,allowFailure:!0})}}function q(e){let t=e.stateDir??process.env.AGENT_DEVICE_STATE_DIR??pe(),n=h.join(t,`tools`,`agent-browser`,B),r=se(n),i=h.join(n,`home`),a=le(n),o=ue(n),s=fe(r)&&oe(n),c=Number.parseInt(process.versions.node.split(`.`)[0]??`0`,10);return{version:B,stateDir:t,installDir:n,binaryPath:r,homeDir:i,runtimeHomeDir:a,socketDir:o,installed:s,nodeMajor:c,nodeSupported:c>=24}}function J(e){if(!e.installed)throw Q(e);return{command:e.binaryPath,env:Z(e,process.env)}}async function Y(e){let t=h.join(e.installDir,`package`);p.mkdirSync(t,{recursive:!0}),await a(`npm`,[`install`,`--prefix`,t,`--no-audit`,`--no-fund`,`--no-save`,`${V}@${B}`],{env:process.env,timeoutMs:H})}async function X(e,t,n){return await a(e.binaryPath,t,{allowFailure:n.allowFailure,env:Z(e,process.env),timeoutMs:n.timeoutMs})}function Z(e,t){return p.mkdirSync(e.homeDir,{recursive:!0}),ie(e),p.mkdirSync(e.socketDir,{recursive:!0}),{...t,HOME:e.runtimeHomeDir,AGENT_BROWSER_SOCKET_DIR:e.socketDir,AGENT_BROWSER_IDLE_TIMEOUT_MS:String(w(t)),AGENT_BROWSER_ARGS:C(t.AGENT_BROWSER_ARGS,e)}}function ie(e){if(e.runtimeHomeDir!==e.homeDir){p.mkdirSync(h.dirname(e.runtimeHomeDir),{recursive:!0});try{let t=p.lstatSync(e.runtimeHomeDir);if(t.isSymbolicLink()&&p.readlinkSync(e.runtimeHomeDir)===e.homeDir||t.isDirectory())return;t.isSymbolicLink()&&p.unlinkSync(e.runtimeHomeDir)}catch(e){if(!de(e))throw e}try{p.symlinkSync(e.homeDir,e.runtimeHomeDir,`dir`)}catch{p.mkdirSync(e.runtimeHomeDir,{recursive:!0})}}}function ae(e){p.writeFileSync(h.join(e.installDir,`manifest.json`),JSON.stringify({package:V,version:B,node:process.version,installedAt:new Date().toISOString()},null,2),`utf8`)}function oe(e){return p.existsSync(h.join(e,`manifest.json`))}function se(e){let t=h.join(e,`package`);return h.join(t,`node_modules`,`.bin`,process.platform===`win32`?`agent-browser.cmd`:`agent-browser`)}function Q(e){return new t(`TOOL_MISSING`,`Managed web browser backend is not installed.`,{version:B,installDir:e.installDir,hint:e.nodeSupported===!1?`Web automation requires Node 24+; current Node is ${process.version}.`:"Run `agent-device web setup` to install the managed web backend."})}function ce(e){if(!(e>=24))throw new t(`UNSUPPORTED_OPERATION`,`Web automation requires Node 24 or newer.`,{currentNode:process.version,requiredNodeMajor:24,hint:`Run agent-device with Node 24+ for web setup and web automation.`})}function le(e){if(process.platform===`win32`)return h.join(e,`home`);let t=f.createHash(`sha1`).update(e).digest(`hex`).slice(0,12);return h.join(m.tmpdir(),`agent-device-web`,t)}function ue(e){let t=f.createHash(`sha1`).update(e).digest(`hex`).slice(0,12);return h.join(m.tmpdir(),`adw`,t)}function de(e){return typeof e==`object`&&!!e&&`code`in e&&e.code===`ENOENT`}function fe(e){try{return p.accessSync(e,p.constants.X_OK),!0}catch{return!1}}function pe(){return h.join(process.env.HOME??process.cwd(),`.agent-device`)}function $(e){let r=n(e);return r.code===`TOOL_MISSING`?new t(r.code,r.message,{...r.details??{},hint:typeof r.details?.hint==`string`?r.details.hint:"Run `agent-device web setup` to install the managed web backend."}):r}export{D as a,g as c,W as i,q as n,ne as o,$ as r,E as s,z as t};