agent-device 0.18.2 → 0.19.0

package/android-multitouch-helper/dist/agent-device-android-multitouch-helper-0.19.0.apk.sha256

@@ -0,0 +1 @@
+fbcaeff3de2f16c64ffe2fef8a4736b4392a08f11e3c957d826b40009195cf2e  agent-device-android-multitouch-helper-0.19.0.apk

package/android-multitouch-helper/dist/{agent-device-android-multitouch-helper-0.18.2.manifest.json → agent-device-android-multitouch-helper-0.19.0.manifest.json}

@@ -1,10 +1,10 @@
 {
   "name": "android-multitouch-helper",
-  "version": "0.18.2",
-  "assetName": "agent-device-android-multitouch-helper-0.18.2.apk",
-  "sha256": "1c8e6f04f5453ecea2e26281896faf7d940237c0011ba8d50b436c0b7ba82c4e",
+  "version": "0.19.0",
+  "assetName": "agent-device-android-multitouch-helper-0.19.0.apk",
+  "sha256": "fbcaeff3de2f16c64ffe2fef8a4736b4392a08f11e3c957d826b40009195cf2e",
   "packageName": "com.callstack.agentdevice.multitouchhelper",
-  "versionCode": 18002,
+  "versionCode": 19000,
   "instrumentationRunner": "com.callstack.agentdevice.multitouchhelper/.MultiTouchInstrumentation",
   "statusProtocol": "android-multitouch-helper-v1"
 }

package/android-snapshot-helper/dist/agent-device-android-snapshot-helper-0.19.0.apk.sha256

@@ -0,0 +1 @@
+56bb052ba4868491bdace904dc41f905cdde3a589e4f4f314d2a7d57c6f8d76c  agent-device-android-snapshot-helper-0.19.0.apk

package/android-snapshot-helper/dist/{agent-device-android-snapshot-helper-0.18.2.manifest.json → agent-device-android-snapshot-helper-0.19.0.manifest.json}

@@ -1,13 +1,13 @@
 {
   "name": "android-snapshot-helper",
-  "version": "0.18.2",
-  "releaseTag": "v0.18.2",
-  "assetName": "agent-device-android-snapshot-helper-0.18.2.apk",
+  "version": "0.19.0",
+  "releaseTag": "v0.19.0",
+  "assetName": "agent-device-android-snapshot-helper-0.19.0.apk",
   "apkUrl": null,
-  "sha256": "a91e0b0b4d8b5b1dc6d1e25abe1491efefa8b8d89cc5c406f1fd84a302e56ebf",
-  "checksumName": "agent-device-android-snapshot-helper-0.18.2.apk.sha256",
+  "sha256": "56bb052ba4868491bdace904dc41f905cdde3a589e4f4f314d2a7d57c6f8d76c",
+  "checksumName": "agent-device-android-snapshot-helper-0.19.0.apk.sha256",
   "packageName": "com.callstack.agentdevice.snapshothelper",
-  "versionCode": 18002,
+  "versionCode": 19000,
   "instrumentationRunner": "com.callstack.agentdevice.snapshothelper/.SnapshotInstrumentation",
   "minSdk": 23,
   "targetSdk": 36,

package/dist/apple-runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTapPointPolicy.swift

@@ -0,0 +1,28 @@
+import XCTest
+
+// The tap-point rule the runner shares with the TS runtime (ADR 0011 Layer 2).
+//
+// RULE: the tap point is the element frame's CENTER; a tap is allowed iff that
+// center lies inside the window frame, edges inclusive. An empty or invalid
+// window frame fails open (allowed): resolving the best available frame is the
+// impure caller's job (onScreenWindowFrame / app.frame), and the policy must
+// not turn a missing frame into a refusal.
+//
+// This is pure geometry on purpose — no XCUIElement — so the exact decision
+// can be proven against the golden fixture table shared with the TS twin:
+//   table:   contracts/fixtures/tap-point-policy.json
+//   TS twin: src/snapshot/mobile-snapshot-semantics.ts#isTapPointInsideViewport
+//   TS test: src/snapshot/__tests__/tap-point-policy-parity.test.ts
+// Drift on either side turns CI red without needing a simulator.
+enum TapPointPolicy {
+  static func isAllowed(elementFrame: CGRect, windowFrame: CGRect) -> Bool {
+    if windowFrame.isNull || windowFrame.isEmpty || windowFrame.isInfinite {
+      return true
+    }
+    let centerX = elementFrame.midX
+    let centerY = elementFrame.midY
+    return centerX >= windowFrame.minX && centerX <= windowFrame.maxX
+      && centerY >= windowFrame.minY && centerY <= windowFrame.maxY
+  }
+}
+

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

@@ -12,7 +12,8 @@ extension RunnerTests {
 
   func privateAXSnapshotCapture(
     app: XCUIApplication,
-    options: SnapshotOptions
+    options: SnapshotOptions,
+    deadline: Date = .distantFuture
   ) -> SnapshotBackendCapture? {
     #if os(iOS) && targetEnvironment(simulator)
       let requestedDepth = options.depth ?? 64
@@ -24,6 +25,13 @@ extension RunnerTests {
       var effectiveDepth = requestedDepth
       var lastError = "unknown private AX snapshot failure"
       for depth in attemptDepths {
+        // The first rung always runs (the plan gated entry on its own budget); later rungs
+        // stop when the capture-plan deadline is spent so ladder retries can never stack
+        // past the runner's main-thread watchdog (#1105).
+        if depth != attemptDepths.first, Date() >= deadline {
+          NSLog("AGENT_DEVICE_RUNNER_PRIVATE_AX_SNAPSHOT_BUDGET_EXHAUSTED depth=%ld", depth)
+          break
+        }
         response = RunnerAXSnapshotBridge.snapshotTree(
           for: app,
           maxDepth: depth,
@@ -208,122 +216,3 @@ extension RunnerTests {
   }
 }
 
-#if AGENT_DEVICE_RUNNER_UNIT_TESTS
-// MARK: - In-bundle unit tests
-
-extension RunnerTests {
-  func testPrivateAXScopeSelectsSubtreeNotMatchingLabels() {
-    let tree: [String: Any] = [
-      "type": 1, "label": "App",
-      "children": [
-        [
-          "type": 9, "identifier": "homeScreen",
-          "children": [
-            ["type": 48, "label": "Post body without the scope text", "children": []]
-          ],
-        ],
-        ["type": 9, "label": "unrelated sibling", "children": []],
-      ],
-    ]
-    var nodes: [SnapshotNode] = []
-    appendPrivateAXNode(
-      tree,
-      to: &nodes,
-      options: SnapshotOptions(interactiveOnly: false, depth: nil, scope: "homeScreen", raw: false),
-      viewport: .infinite,
-      depth: 0,
-      parentIndex: nil,
-      insideMatchedScope: false
-    )
-
-    let labels = nodes.compactMap { $0.label ?? $0.identifier }
-    XCTAssertTrue(labels.contains("homeScreen"))
-    // Descendants of the matched scope are included even when they do not contain the text.
-    XCTAssertTrue(labels.contains("Post body without the scope text"))
-    XCTAssertFalse(labels.contains("unrelated sibling"))
-  }
-
-  func testPrivateAXInteractiveFiltersLoginLikeHiddenDrawer() {
-    let tree: [String: Any] = [
-      "type": Int(XCUIElement.ElementType.application.rawValue),
-      "label": "Blue Sky",
-      "frame": ["x": 0, "y": 0, "width": 390, "height": 844],
-      "children": [
-        [
-          "type": Int(XCUIElement.ElementType.scrollView.rawValue),
-          "frame": ["x": 0, "y": 0, "width": 390, "height": 844],
-          "children": [
-            [
-              "type": Int(XCUIElement.ElementType.image.rawValue),
-              "label": "Callstack",
-              "frame": ["x": 145, "y": 104, "width": 100, "height": 100],
-              "children": [],
-            ],
-            [
-              "type": Int(XCUIElement.ElementType.staticText.rawValue),
-              "label": "Welcome back",
-              "frame": ["x": 32, "y": 260, "width": 326, "height": 32],
-              "children": [],
-            ],
-            [
-              "type": Int(XCUIElement.ElementType.textField.rawValue),
-              "label": "Email",
-              "identifier": "login.email",
-              "frame": ["x": 32, "y": 348, "width": 326, "height": 48],
-              "children": [],
-            ],
-            [
-              "type": Int(XCUIElement.ElementType.secureTextField.rawValue),
-              "label": "Password",
-              "identifier": "login.password",
-              "frame": ["x": 32, "y": 412, "width": 326, "height": 48],
-              "children": [],
-            ],
-            [
-              "type": Int(XCUIElement.ElementType.button.rawValue),
-              "label": "Sign in",
-              "identifier": "login.submit",
-              "frame": ["x": 32, "y": 492, "width": 326, "height": 52],
-              "children": [],
-            ],
-            [
-              "type": Int(XCUIElement.ElementType.link.rawValue),
-              "label": "Forgot password?",
-              "frame": ["x": 128, "y": 568, "width": 134, "height": 32],
-              "children": [],
-            ],
-            [
-              "type": Int(XCUIElement.ElementType.button.rawValue),
-              "label": "Admin settings",
-              "frame": ["x": -260, "y": 184, "width": 220, "height": 44],
-              "children": [],
-            ],
-            [
-              "type": Int(XCUIElement.ElementType.other.rawValue),
-              "frame": ["x": 16, "y": 184, "width": 220, "height": 44],
-              "children": [],
-            ],
-          ],
-        ]
-      ],
-    ]
-    var nodes: [SnapshotNode] = []
-    appendPrivateAXNode(
-      tree,
-      to: &nodes,
-      options: SnapshotOptions(interactiveOnly: true, depth: nil, scope: nil, raw: false),
-      viewport: CGRect(x: 0, y: 0, width: 390, height: 844),
-      depth: 0,
-      parentIndex: nil,
-      insideMatchedScope: false
-    )
-
-    let labels = nodes.compactMap { $0.label }
-    XCTAssertEqual(
-      labels,
-      ["Blue Sky", "Callstack", "Welcome back", "Email", "Password", "Sign in", "Forgot password?"]
-    )
-    XCTAssertFalse(labels.contains("Admin settings"))
-  }
-}
-#endif

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

@@ -130,58 +130,6 @@ extension RunnerTests {
     return Response(ok: true, data: data)
   }
 
-#if AGENT_DEVICE_RUNNER_UNIT_TESTS
-  func testGestureResponseIncludesSynthesizedTapFallbackDiagnostics() {
-    let response = gestureResponse(
-      message: "tapped",
-      timing: (gestureStartUptimeMs: 1, gestureEndUptimeMs: 2),
-      fallback: GestureFallback(
-        strategy: "xctest-coordinate-tap",
-        message: "Runner synthesized coordinate tap is unavailable",
-        hint: "Using XCTest coordinate tap fallback."
-      )
-    )
-
-    XCTAssertEqual(response.ok, true)
-    XCTAssertEqual(response.data?.gestureFallback, "xctest-coordinate-tap")
-    XCTAssertEqual(
-      response.data?.gestureFallbackMessage,
-      "Runner synthesized coordinate tap is unavailable"
-    )
-    XCTAssertEqual(response.data?.gestureFallbackHint, "Using XCTest coordinate tap fallback.")
-  }
-
-  func testXCTestRecordedFailureResponseFailsMutatingSuccesses() throws {
-    let command = try runnerCommandFixture(#"{"command":"tap","commandId":"tap-1"}"#)
-    let response = Response(ok: true, data: DataPayload(message: "tapped"))
-
-    let failureResponse = xctestRecordedFailureResponse(command: command, response: response)
-
-    XCTAssertEqual(failureResponse?.ok, false)
-    XCTAssertEqual(failureResponse?.error?.code, "XCTEST_RECORDED_FAILURE")
-    XCTAssertEqual(
-      failureResponse?.error?.message,
-      "XCTest recorded a failure while executing tap; the action may not have been performed."
-    )
-  }
-
-  func testXCTestRecordedFailureResponseDoesNotWrapReadOnlyOrRunnerFatalResponses() throws {
-    let snapshotCommand = try runnerCommandFixture(#"{"command":"snapshot","commandId":"snapshot-1"}"#)
-    let tapCommand = try runnerCommandFixture(#"{"command":"tap","commandId":"tap-1"}"#)
-    let runnerFatalResponse = Response(
-      ok: true,
-      data: DataPayload(runnerFatal: true, runnerFatalReason: "ax_snapshot_unavailable")
-    )
-
-    XCTAssertNil(
-      xctestRecordedFailureResponse(
-        command: snapshotCommand,
-        response: Response(ok: true, data: DataPayload(nodes: [], truncated: false))
-      )
-    )
-    XCTAssertNil(xctestRecordedFailureResponse(command: tapCommand, response: runnerFatalResponse))
-  }
-#endif
 
   func execute(command: Command) throws -> Response {
     if command.command == .status {
@@ -233,23 +181,126 @@ extension RunnerTests {
     )
   }
 
+  /// Tracks one main-queue dispatch so the watchdog and the dispatched block can agree —
+  /// under `mainThreadWorkLock` — on exactly one of: finished in time, or abandoned.
+  private final class MainThreadWorkState {
+    var finished = false
+    var abandoned = false
+  }
+
+  enum MainThreadBusyState {
+    case idle
+    case busy(abandonedForSeconds: TimeInterval)
+    case wedged(abandonedForSeconds: TimeInterval)
+  }
+
+  func currentMainThreadBusyState() -> MainThreadBusyState {
+    mainThreadWorkLock.lock()
+    defer { mainThreadWorkLock.unlock() }
+    guard abandonedMainThreadWorkCount > 0 else { return .idle }
+    let abandonedFor = abandonedMainThreadWorkSince.map { Date().timeIntervalSince($0) } ?? 0
+    if abandonedFor > mainThreadWedgeThreshold {
+      return .wedged(abandonedForSeconds: abandonedFor)
+    }
+    return .busy(abandonedForSeconds: abandonedFor)
+  }
+
+  private func runnerBusyResponse(command: Command, abandonedForSeconds: TimeInterval) -> Response {
+    NSLog(
+      "AGENT_DEVICE_RUNNER_BUSY command=%@ commandId=%@ abandonedForSeconds=%.1f",
+      command.command.rawValue,
+      command.commandId ?? "",
+      abandonedForSeconds
+    )
+    return Response(
+      ok: false,
+      error: ErrorPayload(
+        code: "RUNNER_BUSY",
+        message:
+          "The iOS runner is still finishing a previous command that exceeded its execution watchdog (usually an accessibility capture on a heavy or animating screen).",
+        hint:
+          "Wait a few seconds and retry. If snapshots keep failing on this screen, use screenshot as visual truth and interact by coordinates, or navigate to another screen."
+      )
+    )
+  }
+
+  private func runnerWedgedResponse(command: Command, abandonedForSeconds: TimeInterval) -> Response {
+    NSLog(
+      "AGENT_DEVICE_RUNNER_WEDGED command=%@ commandId=%@ abandonedForSeconds=%.1f",
+      command.command.rawValue,
+      command.commandId ?? "",
+      abandonedForSeconds
+    )
+    return Response(
+      ok: false,
+      error: ErrorPayload(
+        code: "RUNNER_WEDGED",
+        message:
+          "The iOS runner main thread has been stuck in abandoned work for \(Int(abandonedForSeconds)) seconds and cannot recover on its own.",
+        hint:
+          "The runner session will be restarted. Retry the command after the restart; if this screen keeps wedging captures, use screenshot as visual truth and interact by coordinates."
+      )
+    )
+  }
+
   private func executeDispatched(command: Command) throws -> Response {
+    // XCTest work cannot be cancelled mid-flight: once the watchdog abandons a main-queue
+    // block, queueing more main-thread commands behind it only buries the runner deeper.
+    // Refuse fast instead so the daemon backs off while the abandoned work drains; past the
+    // wedge threshold, escalate so the daemon recycles this runner (#1105).
+    switch currentMainThreadBusyState() {
+    case .idle:
+      break
+    case .busy(let abandonedForSeconds):
+      return runnerBusyResponse(command: command, abandonedForSeconds: abandonedForSeconds)
+    case .wedged(let abandonedForSeconds):
+      return runnerWedgedResponse(command: command, abandonedForSeconds: abandonedForSeconds)
+    }
     if Thread.isMainThread {
       return try executeOnMainSafely(command: command)
     }
     var result: Result<Response, Error>?
     let semaphore = DispatchSemaphore(value: 0)
+    let workState = MainThreadWorkState()
     DispatchQueue.main.async {
       do {
         result = .success(try self.executeOnMainSafely(command: command))
       } catch {
         result = .failure(error)
       }
+      self.mainThreadWorkLock.lock()
+      if workState.abandoned {
+        self.abandonedMainThreadWorkCount -= 1
+        if self.abandonedMainThreadWorkCount == 0 {
+          self.abandonedMainThreadWorkSince = nil
+          NSLog("AGENT_DEVICE_RUNNER_ABANDONED_WORK_DRAINED")
+        }
+      } else {
+        workState.finished = true
+      }
+      self.mainThreadWorkLock.unlock()
       semaphore.signal()
     }
     let waitResult = semaphore.wait(timeout: .now() + mainThreadExecutionTimeout)
     if waitResult == .timedOut {
       // The main queue work may still be running; we stop waiting and report timeout.
+      mainThreadWorkLock.lock()
+      let stillRunning = !workState.finished
+      if stillRunning {
+        workState.abandoned = true
+        abandonedMainThreadWorkCount += 1
+        if abandonedMainThreadWorkSince == nil {
+          abandonedMainThreadWorkSince = Date()
+        }
+      }
+      mainThreadWorkLock.unlock()
+      if stillRunning && command.command == .snapshot {
+        // The next capture on this screen must not re-grind the tree backend.
+        penalizeSnapshotTreeBackend(
+          bundleId: command.appBundleId,
+          reason: "main_thread_watchdog"
+        )
+      }
       throw NSError(
         domain: RunnerErrorDomain.general,
         code: RunnerErrorCode.mainThreadExecutionTimedOut,
@@ -477,6 +528,24 @@ extension RunnerTests {
         }
         if let element = match.element {
           let frame = element.frame
+          // XCTest reports closed-drawer/off-viewport items as hittable, then
+          // "taps" coordinates outside the visible window as a silent no-op.
+          // Refuse instead; the daemon falls back to tree-based resolution,
+          // which can prefer an on-screen candidate or explain the off-screen
+          // state. The check uses the main window frame, not app.frame: on RN
+          // apps app.frame unions transformed subtrees (a closed drawer at
+          // negative x), so it happily "contains" unreachable coordinates.
+          // The DECISION lives in TapPointPolicy (golden parity table with the
+          // TS twin); onScreenWindowFrame only supplies the frame.
+          if !match.usedNonHittableFallback
+            && !TapPointPolicy.isAllowed(
+              elementFrame: frame,
+              windowFrame: onScreenWindowFrame(app: activeApp)
+            ) {
+            return Response(ok: false, error: ErrorPayload(
+              code: "ELEMENT_OFFSCREEN",
+              message: "element resolved off-screen at (\(Int(frame.midX)), \(Int(frame.midY)))"))
+          }
           let isTextEntry = isTextEntryElement(element)
           let touchFrame = frame.isEmpty
             ? nil
@@ -504,18 +573,6 @@ extension RunnerTests {
         }
         return Response(ok: false, error: ErrorPayload(code: "ELEMENT_NOT_FOUND", message: "element not found"))
       }
-      if let text = command.text {
-        if let element = findElement(app: activeApp, text: text) {
-          let (timing, outcome) = performGesture(activeApp) {
-            activateElement(app: activeApp, element: element, action: "tap by text")
-          }
-          if let response = unsupportedResponse(for: outcome) {
-            return response
-          }
-          return gestureResponse(message: "tapped", timing: timing)
-        }
-        return Response(ok: false, error: ErrorPayload(message: "element not found"))
-      }
       if let x = command.x, let y = command.y {
         var fallback: GestureFallback?
         if command.synthesized == true {
@@ -539,7 +596,7 @@ extension RunnerTests {
           fallback: fallback
         )
       }
-      return Response(ok: false, error: ErrorPayload(message: "tap requires text or x/y"))
+      return Response(ok: false, error: ErrorPayload(message: "tap requires a selector or x/y"))
     case .mouseClick:
       guard let x = command.x, let y = command.y else {
         return Response(ok: false, error: ErrorPayload(message: "mouseClick requires x and y"))
@@ -1128,6 +1185,7 @@ extension RunnerTests {
     let delaySeconds = Double(max(command.delayMs ?? 0, 0)) / 1000.0
     let textEntryMode = resolveTextEntryMode(command)
     let target: TextEntryTarget
+    let focusStartedAt = Date()
     if let selectorKey = command.selectorKey, let selectorValue = command.selectorValue {
       let match = findElement(
         app: activeApp,
@@ -1148,6 +1206,13 @@ extension RunnerTests {
     } else {
       target = focusTextInputForTextEntry(app: activeApp, x: command.x, y: command.y)
     }
+    NSLog(
+      "AGENT_DEVICE_RUNNER_TEXT_ENTRY_PHASE commandId=%@ phase=focus durationMs=%.1f chars=%d mode=%@",
+      command.commandId ?? "",
+      Date().timeIntervalSince(focusStartedAt) * 1000.0,
+      text.count,
+      textEntryModeName(textEntryMode)
+    )
     if textEntryMode == .replacement {
       guard target.element != nil else {
         let message =
@@ -1162,7 +1227,8 @@ extension RunnerTests {
       target: target,
       text: text,
       delaySeconds: delaySeconds,
-      repairMode: textEntryMode
+      repairMode: textEntryMode,
+      commandId: command.commandId
     )
     if textResult.verified == false {
       let expected = textResult.expectedText ?? ""

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

@@ -0,0 +1,155 @@
+import Foundation
+import XCTest
+
+enum RunnerCommandLifecycleState: String {
+  case notAccepted
+  case accepted
+  case started
+  case completed
+  case failed
+}
+
+struct RunnerCommandJournalEntry {
+  let commandId: String
+  let command: String
+  var state: RunnerCommandLifecycleState
+  var responseOk: Bool?
+  var responseJson: String?
+  var error: ErrorPayload?
+}
+
+final class RunnerCommandJournal {
+  private let lock = NSLock()
+  private let maxEntries = 64
+  private let maxResponseJsonBytes = 16 * 1024
+  private var entries: [String: RunnerCommandJournalEntry] = [:]
+  private var order: [String] = []
+
+  func accept(command: Command) {
+    guard let commandId = normalizedCommandId(command.commandId) else { return }
+    lock.lock()
+    defer { lock.unlock() }
+    entries[commandId] = RunnerCommandJournalEntry(
+      commandId: commandId,
+      command: command.command.rawValue,
+      state: .accepted,
+      responseOk: nil,
+      responseJson: nil,
+      error: nil
+    )
+    order.removeAll { $0 == commandId }
+    order.append(commandId)
+    pruneIfNeeded()
+  }
+
+  func start(command: Command) {
+    update(command: command, state: .started, responseOk: nil, responseJson: nil, error: nil)
+  }
+
+  func finish(command: Command, response: Response) {
+    update(
+      command: command,
+      state: response.ok ? .completed : .failed,
+      responseOk: response.ok,
+      responseJson: encodeResponseJson(command: command, response: response),
+      error: response.error
+    )
+  }
+
+  func fail(command: Command, error: Error) {
+    update(
+      command: command,
+      state: .failed,
+      responseOk: nil,
+      responseJson: nil,
+      error: ErrorPayload(message: error.localizedDescription)
+    )
+  }
+
+  func status(commandId: String) -> DataPayload {
+    guard let normalized = normalizedCommandId(commandId) else {
+      return DataPayload(lifecycleState: RunnerCommandLifecycleState.notAccepted.rawValue)
+    }
+    lock.lock()
+    let entry = entries[normalized]
+    lock.unlock()
+    guard let entry else {
+      return DataPayload(
+        commandId: normalized,
+        lifecycleState: RunnerCommandLifecycleState.notAccepted.rawValue
+      )
+    }
+    return DataPayload(
+      commandId: entry.commandId,
+      lifecycleState: entry.state.rawValue,
+      lifecycleCommand: entry.command,
+      lifecycleResponseOk: entry.responseOk,
+      lifecycleResponseJson: entry.responseJson,
+      lifecycleErrorCode: entry.error?.code,
+      lifecycleErrorMessage: entry.error?.message,
+      lifecycleErrorHint: entry.error?.hint
+    )
+  }
+
+  private func update(
+    command: Command,
+    state: RunnerCommandLifecycleState,
+    responseOk: Bool?,
+    responseJson: String?,
+    error: ErrorPayload?
+  ) {
+    guard let commandId = normalizedCommandId(command.commandId) else { return }
+    lock.lock()
+    defer { lock.unlock() }
+    var entry = entries[commandId] ?? RunnerCommandJournalEntry(
+      commandId: commandId,
+      command: command.command.rawValue,
+      state: .accepted,
+      responseOk: nil,
+      responseJson: nil,
+      error: nil
+    )
+    entry.state = state
+    entry.responseOk = responseOk
+    entry.responseJson = responseJson
+    entry.error = error
+    entries[commandId] = entry
+    order.removeAll { $0 == commandId }
+    order.append(commandId)
+    pruneIfNeeded()
+  }
+
+  private func pruneIfNeeded() {
+    while order.count > maxEntries {
+      let removed = order.removeFirst()
+      entries.removeValue(forKey: removed)
+    }
+  }
+
+  private func normalizedCommandId(_ value: String?) -> String? {
+    guard let value else { return nil }
+    let trimmed = value.trimmingCharacters(in: .whitespacesAndNewlines)
+    return trimmed.isEmpty ? nil : trimmed
+  }
+
+  private func encodeResponseJson(command: Command, response: Response) -> String? {
+    guard shouldRetainResponseJson(command: command) else { return nil }
+    guard let data = try? JSONEncoder().encode(response) else { return nil }
+    guard data.count <= maxResponseJsonBytes else { return nil }
+    return String(data: data, encoding: .utf8)
+  }
+
+  private func shouldRetainResponseJson(command: Command) -> Bool {
+    switch command.command {
+    case .snapshot, .screenshot:
+      return false
+    case .tap, .mouseClick, .longPress, .drag,
+         .remotePress, .type, .swipe, .scroll, .desktopScroll, .findText, .querySelector, .readText, .back,
+         .backInApp, .backSystem, .home, .rotate, .appSwitcher, .keyboardDismiss, .keyboardReturn,
+         .alert, .pinch, .sequence, .rotateGesture, .transformGesture, .recordStart, .recordStop,
+         .status, .uptime, .shutdown:
+      return true
+    }
+  }
+}
+